config - Obtain credentials and create configuration file

The gsutil config command applies to users who have installed gsutil as a standalone tool. If you installed gsutil via the Cloud SDK, gsutil config will fail unless you are specifically using the -a flag or have configured gcloud to not pass its managed credentials to gsutil (via the command gcloud config set pass_credentials_to_gsutil false). For all other use cases, Cloud SDK users should use the gcloud auth group of commands instead, which will configure OAuth2 credentials that gcloud implicitly passes to gsutil at runtime.

The gsutil config command obtains access credentials for 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.)

By default gsutil config obtains OAuth2 credentials and writes them to the [Credentials] section of the configuration file. Unless otherwise specified, it requests a token allowing full control of resources in several services, e.g. Cloud Storage, Cloud KMS (used for the 'kms' command), and Cloud Pub/Sub (used for the 'notification' command). To request a token with more limited scopes, you can specify additional options (see the OPTIONS section below for the full list). Some examples include:

Create a token with read-only access for storage resources:

gsutil config -r

Create a token with read-write access for storage resources:

gsutil config -w

Create a token with full-control access for storage resources:

gsutil config -f

In addition, -s <scope> can be specified multiple times to request additional scopes, where <scope> is specified using the full URL of the desired scope as listed on https://developers.google.com/identity/protocols/googlescopes.

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. See the list of settings below for supported settings.

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

gsutil config -e

Note that if you are using gsutil through the Cloud SDK, you should instead activate your service account via the gcloud auth activate-service-account command.

When you run gsutil config -e, you will be prompted for the path to your private key file and, if not using a JSON key file, your service account email address and key file password. To get this data, follow the instructions on Service Accounts. Using this information, gsutil populates the "gs_service_key_file" attribute, along with "gs_service_client_id" and "gs_service_key_file_password" if not using a JSON key file.

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/identity/protocols/OAuth2ServiceAccount for further information on service account authentication.

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 (or ";" for Windows). 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.

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]).

With the exception of setting up gsutil to work through a proxy, most users won't need to edit values in the boto configuration file; values found in the file tend to be of more specialized use than command line option-controllable features. For information on setting up gsutil to work through a proxy, see the comments preceding the proxy settings in your .boto file.

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_host_header
  gs_json_host
  gs_json_host_header
  gs_json_port
  gs_oauth2_refresh_token
  gs_port
  gs_secret_access_key
  gs_service_client_id
  gs_service_key_file
  gs_service_key_file_password
  s3_host
  s3_host_header
  s3_port

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

[GoogleCompute]
  service_account

[GSUtil]
  check_hashes
  content_language
  decryption_key1 ... 100
  default_api_version
  default_project_id
  disable_analytics_prompt
  encryption_key
  json_api_version
  max_upload_compression_buffer_size
  parallel_composite_upload_component_size
  parallel_composite_upload_threshold
  sliced_object_download_component_size
  sliced_object_download_max_components
  sliced_object_download_threshold
  parallel_process_count
  parallel_thread_count
  gzip_compression_level
  prefer_api
  resumable_threshold
  resumable_tracker_dir (deprecated in 4.6, use state_dir)
  rsync_buffer_lines
  software_update_check_period
  state_dir
  tab_completion_time_logs
  tab_completion_timeout
  task_estimation_threshold
  test_cmd_regional_bucket_location
  test_notification_url
  use_magicfile
  test_hmac_service_account
  test_hmac_alt_service_account
  test_hmac_list_service_account

[OAuth2]
  client_id
  client_secret
  oauth2_refresh_retries
  provider_authorization_uri
  provider_label
  provider_token_uri
  token_cache

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.