rclone/backend/s3/README.md

# Adding a new s3 provider

It is quite easy to add a new S3 provider to rclone.

You'll then need to do add the following (optional tags are in [] and
do not get displayed in rclone config if empty):

The process is as follows: Create yaml -> add docs -> run tests ->
adjust yaml until tests pass.

All tags can be found in `backend/s3/providers.go` Provider Struct.
Looking through a few of the yaml files as examples should make things
clear. `AWS.yaml` as the most config. pasting.

## YAML

In `backend/s3/provider/YourProvider.yaml`

- name
- description
  - More like the full name often "YourProvider + Object Storage"
- [Region]
  - Any regions your provider supports or the defaults (use `region: {}` for this)
    - Example from AWS.yaml:

      ```yaml
      region:
        us-east-1: |-
          The default endpoint - a good choice if you are unsure.
          US Region, Northern Virginia, or Pacific Northwest.
          Leave location constraint empty.
      ```

    - The defaults (as seen in Rclone.yaml):

      ```yaml
      region:
        "": |-
          Use this if unsure.
          Will use v4 signatures and an empty region.
        other-v2-signature: |-
          Use this only if v4 signatures don't work.
          E.g. pre Jewel/v10 CEPH.
      ```

- [Endpoint]
  - Any endpoints your provider supports

    - Example from Mega.yaml

      ```yaml
        endpoint:
          s3.eu-central-1.s4.mega.io: Mega S4 eu-central-1 (Amsterdam)
      ```

- [Location Constraint]
  - The Location Constraint of your remote, often same as region.
    - Example from AWS.yaml

      ```yaml
      location_constraint:
        "": Empty for US Region, Northern Virginia, or Pacific Northwest
        us-east-2: US East (Ohio) Region
      ```

- [ACL]
  - Identical across *most* providers. Select the default with `acl: {}`
    - Example from AWS.yaml

      ```yaml
      acl:
        private: |-
          Owner gets FULL_CONTROL.
          No one else has access rights (default).
        public-read: |-
          Owner gets FULL_CONTROL.
          The AllUsers group gets READ access.
        public-read-write: |-
          Owner gets FULL_CONTROL.
          The AllUsers group gets READ and WRITE access.
          Granting this on a bucket is generally not recommended.
        authenticated-read: |-
          Owner gets FULL_CONTROL.
          The AuthenticatedUsers group gets READ access.
        bucket-owner-read: |-
          Object owner gets FULL_CONTROL.
          Bucket owner gets READ access.
          If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.
        bucket-owner-full-control: |-
          Both the object owner and the bucket owner get FULL_CONTROL over the object.
          If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.
      ```

- [Storage Class]
  - Identical across *most* providers.
    - Defaults from AWS.yaml

      ```yaml
      storage_class:
        "": Default
        STANDARD: Standard storage class
        REDUCED_REDUNDANCY: Reduced redundancy storage class
        STANDARD_IA: Standard Infrequent Access storage class
        ONEZONE_IA: One Zone Infrequent Access storage class
        GLACIER: Glacier Flexible Retrieval storage class
        DEEP_ARCHIVE: Glacier Deep Archive storage class
        INTELLIGENT_TIERING: Intelligent-Tiering storage class
        GLACIER_IR: Glacier Instant Retrieval storage class
      ```

- [Server Side Encryption]
  - Not common, identical across *most* providers.
    - Defaults from AWS.yaml

      ```yaml
        server_side_encryption:
          "": None
          AES256: AES256
          aws:kms: aws:kms
      ```

- [Advanced Options]
  - All advanced options are Boolean - if true the configurator asks about that
    value, if not it doesn't:

    ```go
    BucketACL             bool `yaml:"bucket_acl,omitempty"`
    DirectoryBucket       bool `yaml:"directory_bucket,omitempty"`
    LeavePartsOnError     bool `yaml:"leave_parts_on_error,omitempty"`
    RequesterPays         bool `yaml:"requester_pays,omitempty"`
    SSECustomerAlgorithm  bool `yaml:"sse_customer_algorithm,omitempty"`
    SSECustomerKey        bool `yaml:"sse_customer_key,omitempty"`
    SSECustomerKeyBase64  bool `yaml:"sse_customer_key_base64,omitempty"`
    SSECustomerKeyMd5     bool `yaml:"sse_customer_key_md5,omitempty"`
    SSEKmsKeyID           bool `yaml:"sse_kms_key_id,omitempty"`
    STSEndpoint           bool `yaml:"sts_endpoint,omitempty"`
    UseAccelerateEndpoint bool `yaml:"use_accelerate_endpoint,omitempty"`
    ```

    - Example from AWS.yaml:

      ```yaml
      bucket_acl: true
      directory_bucket: true
      leave_parts_on_error: true
      requester_pays: true
      sse_customer_algorithm: true
      sse_customer_key: true
      sse_customer_key_base64: true
      sse_customer_key_md5: true
      sse_kms_key_id: true
      sts_endpoint: true
      use_accelerate_endpoint: true
      ```

- Quirks
  - Quirks are discovered through documentation and running the tests as seen below.
    - Most quirks are *bool as to have 3 values, `true`, `false` and `dont care`.

      ```go
      type Quirks struct {
          ListVersion           *int   `yaml:"list_version,omitempty"`     // 1 or 2
          ForcePathStyle        *bool  `yaml:"force_path_style,omitempty"` // true = path-style
          ListURLEncode         *bool  `yaml:"list_url_encode,omitempty"`
          UseMultipartEtag      *bool  `yaml:"use_multipart_etag,omitempty"`
          UseAlreadyExists      *bool  `yaml:"use_already_exists,omitempty"`
          UseAcceptEncodingGzip *bool  `yaml:"use_accept_encoding_gzip,omitempty"`
          MightGzip             *bool  `yaml:"might_gzip,omitempty"`
          UseMultipartUploads   *bool  `yaml:"use_multipart_uploads,omitempty"`
          UseUnsignedPayload    *bool  `yaml:"use_unsigned_payload,omitempty"`
          UseXID                *bool  `yaml:"use_x_id,omitempty"`
          SignAcceptEncoding    *bool  `yaml:"sign_accept_encoding,omitempty"`
          CopyCutoff            *int64 `yaml:"copy_cutoff,omitempty"`
          MaxUploadParts        *int   `yaml:"max_upload_parts,omitempty"`
          MinChunkSize          *int64 `yaml:"min_chunk_size,omitempty"`
      }
        ```

      - Example from AWS.yaml

        ```yaml
        quirks:
          might_gzip: false # Never auto gzips objects
          use_unsigned_payload: false # AWS has trailer support
        ```

Note that if you omit a section, eg `region` then the user won't be
asked that question, and if you add an empty section e.g. `region: {}`
then the defaults from the `Other.yaml` will be used.

## DOCS

- `docs/content/s3.md`
  - Add the provider at the top of the page.
  - Add a section about the provider linked from there.
    - Make sure this is in alphabetical order in the `Providers` section.
  - Add a transcript of a trial `rclone config` session
    - Edit the transcript to remove things which might change in subsequent versions
  - **Do not** alter or add to the autogenerated parts of `s3.md`
    - Rule of thumb: don't edit anything not mentioned above.
  - **Do not** run `make backenddocs` or `bin/make_backend_docs.py s3`
    - This will make autogenerated changes!
- `README.md` - this is the home page in github
  - Add the provider and a link to the section you wrote in `docs/contents/s3.md`
- `docs/content/_index.md` - this is the home page of rclone.org
  - Add the provider and a link to the section you wrote in `docs/contents/s3.md`
- Once you've written the docs, run `make serve` and check they look OK
  in the web browser and the links (internal and external) all work.

## TESTS

Once you've written the code, test `rclone config` works to your
satisfaction and looks correct, and check the integration tests work
`go test -v -remote NewS3Provider:`. You may need to adjust the quirks
to get them to pass. Some providers just can't pass the tests with
control characters in the names so if these fail and the provider
doesn't support `urlEncodeListings` in the quirks then ignore them.