Synopsis

gsutil [-D] config [-a] [-b] [-e] [-f] [-o <file>] [-r] [-s <scope>] [-w]

Description

The gsutil config command obtains access credentials for Google Cloud Storage and writes a boto/gsutil configuration file containing the obtained credentials along with a number of other configuration-controllable values.

Unless specified otherwise (see OPTIONS), the configuration file is written to ~/.boto (i.e., the file .boto under the user’s home directory). If the default file already exists, an attempt is made to rename the existing file to ~/.boto.bak; if that attempt fails the command will exit. A different destination file can be specified with the -o option (see OPTIONS).

Because the boto configuration file contains your credentials you should keep its file permissions set so no one but you has read access. (The file is created read-only when you run gsutil config.)

Credentials

By default gsutil config obtains OAuth2 credentials, and writes them to the [Credentials] section of the configuration file. The -r, -w, -f options (see OPTIONS below) cause gsutil config to request a token with restricted scope; the resulting token will be restricted to read-only operations, read-write operations, or all operations (including acl get/set, defacl get/set, and logging get/’set on’/’set off’ operations). In addition, -s <scope> can be used to request additional (non-Google-Storage) scopes.

If you want to use credentials based on access key and secret (the older authentication method before OAuth2 was supported) instead of OAuth2, see help about the -a option in the OPTIONS section.

If you wish to use gsutil with other providers (or to copy data back and forth between multiple providers) you can edit their credentials into the [Credentials] section after creating the initial configuration file.

Configuring Service Account Credentials

You can configure credentials for service accounts using the gsutil config -e option. Service accounts are useful for authenticating on behalf of a service or application (as opposed to a user).

When you run gsutil config -e, you will be prompted for your service account email address and the path to your private key file. To get these data, visit the Google Developers Console , click on the project you are using, then click “APIs & auth”, then click “Credentials”, then click “CREATE NEW CLIENT ID”; on the pop-up dialog box select “Service account” and click “Create Client ID”. This will download a private key file, which you should move to somewhere accessible from the machine where you run gsutil. Make sure to set its protection so only the users you want to be able to authenticate have access.

Note that your service account will NOT be considered an Owner for the purposes of API access (see gsutil help creds for more information about this). See https://developers.google.com/accounts/docs/OAuth2ServiceAccount for further information on service account authentication.

Configuration File Selection Procedure

By default, gsutil will look for the configuration file in /etc/boto.cfg and ~/.boto. You can override this choice by setting the BOTO_CONFIG environment variable. This is also useful if you have several different identities or cloud storage environments: By setting up the credentials and any additional configuration in separate files for each, you can switch environments by changing environment variables.

You can also set up a path of configuration files, by setting the BOTO_PATH environment variable to contain a ”:” delimited path. For example setting the BOTO_PATH environment variable to:

/etc/projects/my_group_project.boto.cfg:/home/mylogin/.boto

will cause gsutil to load each configuration file found in the path in order. This is useful if you want to set up some shared configuration state among many users: The shared state can go in the central shared file ( /etc/projects/my_group_project.boto.cfg) and each user’s individual credentials can be placed in the configuration file in each of their home directories. (For security reasons users should never share credentials via a shared configuration file.)

Configuration File Structure

The configuration file contains a number of sections: [Credentials], [Boto], [GSUtil], and [OAuth2]. If you edit the file make sure to edit the appropriate section (discussed below), and to be careful not to mis-edit any of the setting names (like “gs_access_key_id”) and not to remove the section delimiters (like “[Credentials]”).

Additional Configuration-controllable Features

With the exception of setting up gsutil to work through a proxy (see below), most users won’t need to edit values in the boto configuration file; values found in there tend to be of more specialized use than command line option-controllable features.

The following are the currently defined configuration settings, broken down by section. Their use is documented in comments preceding each, in the configuration file. If you see a setting you want to change that’s not listed in your current file, see the section below on Updating to the Latest Configuration File.

The currently supported settings, are, by section:

[Credentials]
  aws_access_key_id
  aws_secret_access_key
  gs_access_key_id
  gs_host
  gs_json_host
  gs_json_port
  gs_oauth2_refresh_token
  gs_port
  gs_secret_access_key
  s3_host
  s3_port

[Boto]
  proxy
  proxy_port
  proxy_user
  proxy_pass
  http_socket_timeout
  https_validate_certificates
  debug
  max_retry_delay
  num_retries

[GSUtil]
  check_hashes
  content_language
  default_api_version
  default_project_id
  json_api_version
  parallel_composite_upload_component_size
  parallel_composite_upload_threshold
  parallel_process_count
  parallel_thread_count
  prefer_api
  resumable_threshold
  resumable_tracker_dir
  rsync_buffer_lines
  software_update_check_period
  use_magicfile

[OAuth2]
  client_id
  client_secret
  oauth2_refresh_retries
  provider_authorization_uri
  provider_label
  provider_token_uri
  token_cache

Updating To The Latest Configuration File

We add new configuration controllable features to the boto configuration file over time, but most gsutil users create a configuration file once and then keep it for a long time, so new features aren’t apparent when you update to a newer version of gsutil. If you want to get the latest configuration file (which includes all the latest settings and documentation about each) you can rename your current file (e.g., to ‘.boto_old’), run gsutil config, and then edit any configuration settings you wanted from your old file into the newly created file. Note, however, that if you’re using OAuth2 credentials and you go back through the OAuth2 configuration dialog it will invalidate your previous OAuth2 credentials.

If no explicit scope option is given, -f (full control) is assumed by default.

Options