Google Cloud Storage

At a glance

Capability	Support
rclone support tier	Tier 1: Core
Checksums	MD5
Modification times	Kept, to 1 ns
Case-insensitive names	No
Duplicate names allowed	No
Server-side copy	Yes
Server-side move and rename	No
Folder move and rename	No: each file is moved in turn
Free space reporting	No
Empty folders	Yes
Change notifications	No
Uploads of unknown size	Yes
Public links	No

command.) You may put subdirectories in too, e.g. remote:bucket/path/to/dir.

Setup notes

In CloudMount you add this drive from the Add drive screen, and the wizard asks for the options listed under Options. The notes below come from rclone’s setup guide.

Service Account support

You can set up rclone with Google Cloud Storage in an unattended mode, i.e. not tied to a specific end-user Google account. This is useful when you want to synchronise files onto machines that don’t have actively logged-in users, for example build machines.

To get credentials for Google Cloud Platform IAM Service Accounts, please head to the Service Account section of the Google Developer Console. Service Accounts behave just like normal User permissions in Google Cloud Storage ACLs, so you can limit their access (e.g. make them read only). After creating an account, a JSON file containing the Service Account’s credentials will be downloaded onto your machines. These credentials are what rclone will use for authentication.

To use a Service Account instead of OAuth2 token flow, enter the path to your Service Account credentials at the service_account_file prompt and rclone won’t use the browser based authentication flow. If you’d rather stuff the contents of the credentials file into the rclone config file, you can set service_account_credentials with the actual contents of the file instead, or set the equivalent environment variable.

Service Account Authentication with Access Tokens

Another option for service account authentication is to use access tokens via gcloud impersonate-service-account. Access tokens protect security by avoiding the use of the JSON key file, which can be breached. They also bypass oauth login flow, which is simpler on remote VMs that lack a web browser.

If you already have a working service account, skip to step 3.

1. Create a service account using

gcloud iam service-accounts create gcs-read-only

You can re-use an existing service account as well (like the one created above)

2. Attach a Viewer (read-only) or User (read-write) role to the service account

$ PROJECT_ID=my-project
$ gcloud --verbose iam service-accounts add-iam-policy-binding \
   gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com  \
   --member=serviceAccount:gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com \
   --role=roles/storage.objectViewer

Use the Google Cloud console to identify a limited role. Some relevant pre-defined roles:

roles/storage.objectUser – read-write access but no admin privileges
roles/storage.objectViewer – read-only access to objects
roles/storage.admin – create buckets & administrative roles

3. Get a temporary access key for the service account

$ gcloud auth application-default print-access-token  \
   --impersonate-service-account \
      gcs-read-only@${PROJECT_ID}.iam.gserviceaccount.com

ya29.c.c0ASRK0GbAFEewXD [truncated]

4. Update `access_token` setting

hit CTRL-C when you see waiting for code. This will save the config without doing oauth flow

rclone config update ${REMOTE_NAME} access_token ya29.c.c0Axxxx

5. Run rclone as usual

rclone ls dev-gcs:${MY_BUCKET}/

More Info on Service Accounts

Anonymous Access

For downloads of objects that permit public access you can configure rclone to use anonymous access by setting anonymous to true. With unauthorized access you can’t write or create files but only read or list those buckets and objects that have public read access.

Application Default Credentials

If no other source of credentials is provided, rclone will fall back to Application Default Credentials this is useful both when you already have configured authentication for your developer account, or in production when running on a google compute host. Note that if running in docker, you may need to run additional commands on your google compute machine - see this page.

Note that in the case application default credentials are used, there is no need to explicitly configure a project number.

`--fast-list`

This remote supports --fast-list which allows you to use fewer transactions in exchange for more memory. See the rclone docs for more details.

Custom upload headers

You can set custom upload headers with the --header-upload flag. Google Cloud Storage supports the headers as described in the working with metadata documentation

Cache-Control
Content-Disposition
Content-Encoding
Content-Language
Content-Type
X-Goog-Storage-Class
X-Goog-Meta-

Eg --header-upload "Content-Type text/potato"

Note that the last of these is for setting custom metadata in the form --header-upload "x-goog-meta-key: value"

Modification times

Google Cloud Storage stores md5sum natively. Google’s gsutil tool stores modification time with one-second precision as goog-reserved-file-mtime in file metadata.

To ensure compatibility with gsutil, rclone stores modification time in 2 separate metadata entries. mtime uses RFC3339 format with one-nanosecond precision. goog-reserved-file-mtime uses Unix timestamp format with one-second precision. To get modification time from object metadata, rclone reads the metadata in the following order: mtime, goog-reserved-file-mtime, object updated time.

Note that rclone’s default modify window is 1ns. Files uploaded by gsutil only contain timestamps with one-second precision. If you use rclone to sync files previously uploaded by gsutil, rclone will attempt to update modification time for all these files. To avoid these possibly unnecessary updates, use --modify-window 1s.

Restricted filename characters

Character	Value	Replacement
NUL	0x00	␀
LF	0x0A	␊
CR	0x0D	␍
/	0x2F	／

Invalid UTF-8 bytes will also be replaced, as they can’t be used in JSON strings.

Options

Standard options

The wizard asks for these when you add the drive.

client_id

OAuth Client Id.

Leave blank normally.

Type: string

client_secret

OAuth Client Secret.

Leave blank normally.

Type: string

project_number

Project number.

Optional - needed only for list/create/delete buckets - see your developer console.

Type: string

user_project

User project.

Optional - needed only for requester pays.

Type: string

service_account_file

Service Account Credentials JSON file path.

Leave blank normally. Needed only if you want use SA instead of interactive login.

Leading ~ will be expanded in the file name as will environment variables such as ${RCLONE_CONFIG_DIR}.

Type: string

anonymous

Access public buckets and objects without credentials.

Set to ‘true’ if you just want to download files and don’t configure credentials.

Type: bool · Default: false

object_acl

Access Control List for new objects.

Type: string

Choices:

authenticatedRead: Object owner gets OWNER access. All Authenticated Users get READER access.
bucketOwnerFullControl: Object owner gets OWNER access. Project team owners get OWNER access.
bucketOwnerRead: Object owner gets OWNER access. Project team owners get READER access.
private: Object owner gets OWNER access. Default if left blank.
projectPrivate: Object owner gets OWNER access. Project team members get access according to their roles.
publicRead: Object owner gets OWNER access. All Users get READER access.

bucket_acl

Access Control List for new buckets.

Type: string

Choices:

authenticatedRead: Project team owners get OWNER access. All Authenticated Users get READER access.
private: Project team owners get OWNER access. Default if left blank.
projectPrivate: Project team members get access according to their roles.
publicRead: Project team owners get OWNER access. All Users get READER access.
publicReadWrite: Project team owners get OWNER access. All Users get WRITER access.

bucket_policy_only

Access checks should use bucket-level IAM policies.

If you want to upload objects to a bucket with Bucket Policy Only set then you will need to set this.

When it is set, rclone:

ignores ACLs set on buckets
ignores ACLs set on objects
creates buckets with Bucket Policy Only set

Docs: https://cloud.google.com/storage/docs/bucket-policy-only

Type: bool · Default: false

location

Location for the newly created buckets.

Type: string

Choices:

(empty): Empty for default location (US)
asia: Multi-regional location for Asia
eu: Multi-regional location for Europe
us: Multi-regional location for United States
asia-east1: Taiwan
asia-east2: Hong Kong
asia-northeast1: Tokyo
asia-northeast2: Osaka
asia-northeast3: Seoul
asia-south1: Mumbai
asia-south2: Delhi
asia-southeast1: Singapore
asia-southeast2: Jakarta
australia-southeast1: Sydney
australia-southeast2: Melbourne
europe-north1: Finland
europe-west1: Belgium
europe-west2: London
europe-west3: Frankfurt
europe-west4: Netherlands
europe-west6: Zürich
europe-central2: Warsaw
us-central1: Iowa
us-east1: South Carolina
us-east4: Northern Virginia
us-east5: Ohio
us-west1: Oregon
us-west2: California
us-west3: Salt Lake City
us-west4: Las Vegas
northamerica-northeast1: Montréal
northamerica-northeast2: Toronto
southamerica-east1: São Paulo
southamerica-west1: Santiago
asia1: Dual region: asia-northeast1 and asia-northeast2.
eur4: Dual region: europe-north1 and europe-west4.
nam4: Dual region: us-central1 and us-east1.

storage_class

The storage class to use when storing objects in Google Cloud Storage.

Type: string

Choices:

(empty): Default
MULTI_REGIONAL: Multi-regional storage class
REGIONAL: Regional storage class
NEARLINE: Nearline storage class
COLDLINE: Coldline storage class
ARCHIVE: Archive storage class
DURABLE_REDUCED_AVAILABILITY: Durable reduced availability storage class

env_auth

Get GCP IAM credentials from runtime (environment variables or instance meta data if no env vars).

Only applies if service_account_file and service_account_credentials is blank.

Type: bool · Default: false

Choices:

false: Enter credentials in the next step.
true: Get GCP IAM credentials from the environment (env vars or IAM).

Advanced options

The wizard shows these under Advanced options. Most drives work without changing any of them.

token

OAuth Access Token as a JSON blob.

Type: string

auth_url

Auth server URL.

Leave blank to use the provider defaults.

Type: string

token_url

Token server url.

Leave blank to use the provider defaults.

Type: string

client_credentials

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Note that this option is NOT supported by all backends.

Type: bool · Default: false

access_token

Short-lived access token.

Leave blank normally. Needed only if you want use short-lived access token instead of interactive login.

Type: string

directory_markers

Upload an empty object with a trailing slash when a new directory is created

Empty folders are unsupported for bucket based remotes, this option creates an empty object ending with “/”, to persist the folder.

Type: bool · Default: false

no_check_bucket

If set, don’t attempt to check the bucket exists or create it.

This can be useful when trying to minimise the number of transactions rclone does if you know the bucket exists already.

Type: bool · Default: false

decompress

If set this will decompress gzip encoded objects.

It is possible to upload objects to GCS with “Content-Encoding: gzip” set. Normally rclone will download these files as compressed objects.

If this flag is set then rclone will decompress these files with “Content-Encoding: gzip” as they are received. This means that rclone can’t check the size and hash but the file contents will be decompressed.

Type: bool · Default: false

endpoint

Custom endpoint for the storage API. Leave blank to use the provider default.

When using a custom endpoint that includes a subpath (e.g. example.org/custom/endpoint), the subpath will be ignored during upload operations due to a limitation in the underlying Google API Go client library. Download and listing operations will work correctly with the full endpoint path. If you require subpath support for uploads, avoid using subpaths in your custom endpoint configuration.

Type: string

Choices:

storage.example.org: Specify a custom endpoint
storage.example.org:4443: Specifying a custom endpoint with port
storage.example.org:4443/gcs/api: Specifying a subpath, see the note, uploads won’t use the custom path!

encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Type: Encoding · Default: Slash,CrLf,InvalidUtf8,Dot

description

Description of the remote.

Type: string

Limitations

rclone about is not supported by the Google Cloud Storage backend. Backends without this capability cannot determine free space for an rclone mount or use policy mfs (most free space) as a member of an rclone union remote.

See List of backends that do not support rclone about and rclone about.

Google Cloud Storage

At a glance

Setup notes

Service Account support

Service Account Authentication with Access Tokens

1. Create a service account using

2. Attach a Viewer (read-only) or User (read-write) role to the service account

3. Get a temporary access key for the service account

4. Update access_token setting

5. Run rclone as usual

More Info on Service Accounts

Anonymous Access

Application Default Credentials

--fast-list

Custom upload headers

Modification times

Restricted filename characters

Options

Standard options

client_id

client_secret

project_number

user_project

service_account_file

anonymous

object_acl

bucket_acl

bucket_policy_only

location

storage_class

env_auth

Advanced options

token

auth_url

token_url

client_credentials

access_token

directory_markers

no_check_bucket

decompress

endpoint

encoding

description

Limitations

4. Update `access_token` setting

`--fast-list`