Merge pull request #10572 from nextcloud/backport/10437/stable27

[stable27] (s3 primary) Simplify language, note defaults, better examples

admin_manual/configuration_files/primary_storage.rst

@@ -116,39 +116,88 @@ V3 Authentication:
 Simple Storage Service (S3)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The simple storage service (S3) backend mounts a bucket on an Amazon S3 object
+The Simple Storage Service (S3) backend mounts a bucket on an Amazon S3 object
 storage or compatible implementation (e.g. Minio or Ceph Object Gateway) into the
 virtual filesystem.
 
 The class to be used is :code:`\\OC\\Files\\ObjectStore\\S3`
 
+Amazon-hosted S3:
+
 ::
 
 	'objectstore' => [
 		'class' => '\\OC\\Files\\ObjectStore\\S3',
 		'arguments' => [
-			'bucket' => 'nextcloud',
-			'autocreate' => true,
-			'key'    => 'EJ39ITYZEUH5BGWDRUFY',
+			'bucket' => 'my-nextcloud-store',
+			'region' => 'us-east-1',
+			'key' => 'EJ39ITYZEUH5BGWDRUFY',
+			'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj',
+		],
+	],
+
+Non-Amazon hosted S3:
+
+::
+
+	'objectstore' => [
+		'class' => '\\OC\\Files\\ObjectStore\\S3',
+		'arguments' => [
+			'bucket' => 'my-nextcloud-store',
+			'hostname' => 's3.example.com',
+			'key' => 'EJ39ITYZEUH5BGWDRUFY',
 			'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj',
-			'hostname' => 'example.com',
-			'port' => 1234,
-			'use_ssl' => true,
-			'region' => 'optional',
-			// required for some non Amazon S3 implementations
-			'use_path_style'=>true
+			'port' => 8443,
+			// required for some non-Amazon S3 implementations
+			'use_path_style' => true,
 		],
 	],
 
-.. note:: Not all configuration options are required for all S3 servers. Overriding
-          the hostname, port and region of your S3 server is only required for
-          non-Amazon implementations, which in turn usually don't require the region to be set.
+Minimum required parameters are:
 
-.. note:: :code:`use_path_style` is usually not required (and is, in fact, incompatible
-          with newer Amazon datacenters), but can be used with non-Amazon servers
-          where the DNS infrastructure cannot be controlled. Ordinarily, requests
-          will be made with http://bucket.hostname.domain/, but with path style enabled,
-          requests are made with http://hostname.domain/bucket instead.
+* :code:`bucket`
+* :code:`key`
+* :code:`secret`
+
+.. note:: You will *probably* need to specify additional parameters beyond these, unless the default 
+          values (see below) exactly match your situation. In particular, your :code:`region` (if Amazon 
+	  hosted) or :code:`hostname` (if non-Amazon hosted).
+
+Optional parameters most commonly needing adjustment (and their defaults values if left 
+unconfigured):
+
+* :code:`region` defaults to :code:`eu-west-1`
+* :code:`storageClass` defaults to :code:`STANDARD`
+* :code:`hostname` defaults to :code:`s3.REGION.amazonaws.com`
+* :code:`use_ssl` defaults to :code:`true`
+
+Optional parameters sometimes needing adjustment:
+
+* :code:`use_path_style` defaults to :code:`false`
+* :code:`port` defaults to :code:`443`
+* :code:`sse_c_key` has no default
+
+Optional parameters less commonly needing adjustment:
+
+* :code:`proxy` defaults to :code:`false`
+* :code:`timeout` defaults to :code:`15`
+* :code:`uploadPartSize` defaults to :code:`524288000`
+* :code:`putSizeLimit` defaults to :code:`104857600`
+* :code:`legacy_auth` has no default
+* :code:`version` defaults to :code:`latest`
+* :code:`verify_bucket_exists` defaults to :code:`true`
+
+**If you are using Amazon S3:** the :code:`region` parameter is required unless you're happy with 
+the default of :code:`eu-west-1`. There is no need to override the :code:`hostname` or :code:`port`. 
+And :code:`storageClass` only needs to be modified if you're using a different configuration at AWS. 
+Lastly, :code:`use_path_style` is rarely required with Amazon, but some legacy Amazon datacenters 
+may require it.
+
+**If you using a non-Amazon hosted S3 store:** you will need to set the :code:`hostname` 
+parameter (and can ignore the :code:`region` parameter). You may need to use :code:`use_path_style` 
+if your non-Amazon S3 store does *not* support requests like :code:`https://bucket.hostname.domain/`.
+Setting :code:`use_path_style` to true configures the S3 client to make requests like 
+:code:`https://hostname.domain/bucket` instead.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Microsoft Azure Blob Storage
@@ -205,9 +254,9 @@ You can find out more information about upscaling with object storage and Nextcl
 `Nextcloud customer portal <https://portal.nextcloud.com/article/object-store-as-primary-storage-16.html>`_.
 
 
-------------------------
-SSE-C encryption support
-------------------------
+---------------------------
+S3 SSE-C encryption support
+---------------------------
 
 Nextcloud supports server side encryption, also known as `SSE-C <http://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html>`_, with compatible S3 bucket provider. The encryption and decryption happens on the S3 bucket side with a key provided by the Nextcloud server.
 
@@ -239,4 +288,4 @@ The following example shows how to configure the S3 object store with SSE-C encr
 				'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=',
 			),
 		);
-	],
+	],