From 2281e388b0d4014e93ef85e723d2ed8cffbe2ccd Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Thu, 25 May 2023 11:12:41 -0400 Subject: [PATCH 1/2] (s3 primary) Simplify language, note defaults, better examples Fixes #9934 (for primary storage) * Clarifies parameters that may need to be changed when using with Amazon's S3 * Clarifies parameters that must be changed when using non-Amazon hosted S3 * Strips out no-op parameters (default values) from config example * Lists supported parameters by type and their defaults (if any) * Adds example config for non-Amazon hosted S3 Signed-off-by: Josh Richards --- .../configuration_files/primary_storage.rst | 92 ++++++++++++++----- 1 file changed, 70 insertions(+), 22 deletions(-) diff --git a/admin_manual/configuration_files/primary_storage.rst b/admin_manual/configuration_files/primary_storage.rst index 285b63f4ec3..e789b40a98a 100644 --- a/admin_manual/configuration_files/primary_storage.rst +++ b/admin_manual/configuration_files/primary_storage.rst @@ -116,39 +116,87 @@ 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. + +Optional parameters most commonly needing adjustment (and their defaults values if left +unconfigured): + +* :code:`region` defaults to :code:`eu-west-1` +* :code:`storageClass` defaults :code:`STANDARD` +* :code:`hostname` defaults :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 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 +253,9 @@ You can find out more information about upscaling with object storage and Nextcl `Nextcloud customer portal `_. ------------------------- -SSE-C encryption support ------------------------- +--------------------------- +S3 SSE-C encryption support +--------------------------- Nextcloud supports server side encryption, also known as `SSE-C `, 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 +287,4 @@ The following example shows how to configure the S3 object store with SSE-C encr 'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=', ), ); - ], \ No newline at end of file + ], From 640b7245fc95c275c984abd401f26784890606d0 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Thu, 25 May 2023 12:06:12 -0400 Subject: [PATCH 2/2] Add'l clarification in S3 note + couple typos fixed Signed-off-by: Josh Richards --- admin_manual/configuration_files/primary_storage.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/admin_manual/configuration_files/primary_storage.rst b/admin_manual/configuration_files/primary_storage.rst index e789b40a98a..df9df8b6a1b 100644 --- a/admin_manual/configuration_files/primary_storage.rst +++ b/admin_manual/configuration_files/primary_storage.rst @@ -160,14 +160,15 @@ Minimum required parameters are: * :code:`secret` .. note:: You will *probably* need to specify additional parameters beyond these, unless the default - values (see below) exactly match your situation. + 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 :code:`STANDARD` -* :code:`hostname` defaults :code:`s3.REGION.amazonaws.com` +* :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: @@ -189,7 +190,7 @@ Optional parameters less commonly needing adjustment: **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 is rarely required with Amazon, but some legacy Amazon datacenters +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`