config - Obtain credentials and create configuration file

Synopsis

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

Description

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

Configuring Service Account Credentials

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.

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:

/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, 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.

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

-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 (devstorage.full_control scope).
Note that this does not provide non-storage scopes, such as those
needed to edit Pub/Sub and KMS resources (used with the
'notification' and 'kms' commands).

-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 with read-only access (devstorage.read_only scope).

--reauth

Request token with reauth access (accounts.reauth scope).

-s <scope>

Request a specific OAuth2 <scope> instead of the default(s). This
option may be repeated to request multiple scopes, and may be used
in conjuction with other flags that request a specific scope.