config - Obtain credentials and create configuration file
gsutil [-D] config [-a] [-b] [-e] [-f] [-n] [-o <file>] [-r] [-s <scope>] [-w]
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.)
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 this data, follow the instructions on Service Accounts.
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.
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 (or ";" for Windows). For example setting the BOTO_PATH environment variable to:
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, 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_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 proxy_rdns http_socket_timeout 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 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 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 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.
|-a||Prompt for Google Cloud Storage access key and secret (the older authentication method before OAuth2 was supported) instead of obtaining an OAuth2 token.|
|-b||Causes gsutil config to launch a browser to obtain OAuth2 approval and the project ID instead of showing the URL for each and asking the user to open the browser. This will probably not work as expected if you are running gsutil from an ssh window, or using gsutil on Windows.|
|-e||Prompt for service account credentials. This option requires that -a is not set.|
|-f||Request token with full-control access (default).|
|-n||Write the configuration file without authentication configured. This flag is mutually exlusive with all flags other than -o.|
|-o <file>||Write the configuration to <file> instead of ~/.boto. Use '-' for stdout.|
|-r||Request token restricted to read-only access.|
|-s <scope>||Request additional OAuth2 <scope>.|
|-w||Request token restricted to read-write access.|