config - Obtain credentials and create configuration file
Synopsis
gsutil [-D] config (-a|-e) [-n] [-o <file>]
Description
The gsutil config
command generally applies to users who have legacy
standalone installations of gsutil. If you installed gsutil via the Cloud SDK,
gsutil config
fails 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 configures OAuth2 credentials that gcloud implicitly passes to
gsutil at runtime. To check if you are using gsutil from the Cloud SDK or as a
legacy standalone, use gsutil version -l
and in the output look for
"using cloud sdk".
Important: The default behavior for the gsutil config
command is to obtain
user account credentials for authentication. However, user account credentials
are no longer supported for standalone gsutil. For this reason, running the
default gsutil config
command fails, and using any of the following flags
causes the command to fail: -b
, -f
, -r
, --reauth
, -s
,
-w
. When using standalone gsutil, it's recommended that you use
service account credentials via the -e
flag.
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 exits. 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
.)
Configuring Service Account Credentials
Service accounts are useful for authenticating on behalf of a service or
application (as opposed to a user). If you use gsutil as a legacy
stand-alone tool, you configure credentials for service accounts using the
-e
option:
gsutil config -e
Note that if you use gsutil through the Cloud SDK, you instead activate your service account via the gcloud auth activate-service-account command.
When you run gsutil config -e
, you are 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
in the boto configuration file. If not using a JSON key file, gsutil also
populates the "gs_service_client_id" and "gs_service_key_file_password"
attributes.
Note that your service account is NOT considered an Owner for the purposes of API access. See https://developers.google.com/identity/protocols/OAuth2ServiceAccount for further information on service account authentication.
If you want to use credentials based on access key and secret (the older
authentication method before OAuth2 was supported), see 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 boto configuration file.
Options
- -a
Prompt for Cloud Storage access key and secret (the older authentication method before OAuth2 was supported) instead of obtaining an OAuth2 token.
- -e
Prompt for service account credentials. This option requires that
-a
is not set.- -n
Write the configuration file without authentication configured. This flag is mutually exclusive with all flags other than
-o
.- -o <file>
Write the configuration to <file> instead of ~/.boto. Use
-
for stdout.