This page describes how gsutil uses a boto configuration file and provides a collaboration example that uses the file. The boto configuration file is also used by boto, which is the Amazon S3 SDK for Python.
Configuration file overview
The default location for the boto configuration file is in the user home
directory, ~/.boto, for Linux and macOS, and in %HOMEDRIVE%%HOMEPATH%,
for Windows. You can get the location of the configuration file by running
gsutil version -l.
You can override where the config file is used by setting the BOTO_CONFIG environment variable. You can also set up a path of boto config files to load by setting the BOTO_PATH environment variable. This could be useful, for example, in data sharing and collaboration scenarios, such as the example below.
When gsutil has been installed as part of the Google Cloud SDK:
The recommended way of installing gsutil is as part of the Google Cloud SDK. When you do so, the boto/gsutil configuration file contains values that control how gsutil behaves, such as which API gsutil preferentially uses (with the
prefer_apivariable). These variables can be changed by editing the configuration file directly. The file does not contain credentials, and it does not control the default project ID, since these are handled by the Cloud SDK.
When gsutil has been installed as a standalone tool:
When gsutil has been installed as a standalone tool, the boto/gsutil configuration file contains values that control how gsutil behaves, such as which API gsutil preferentially uses and the default project ID gsutil uses (with the
default_project_idvariables, respectively). These variables can be changed by editing the configuration file directly. The file also controls credentials and OAuth2 settings, which you typically create by using the
For a complete listing of what the boto configuration file contains, see gsutil config.
Example using the configuration file
In this example, a small company wants to use Cloud Storage as a storage system for their employees. As the IT administrator, you create a project in the Google Cloud Console and create buckets for each employee. To make it easier for employees to use Cloud Storage, you want to create and store company-wide settings, such as a proxy configuration and parallel composite upload thresholds, in a central file that employees can point to in their BOTO configuration path. This eliminates the need for each employee to set the shared parts of the configuration manually and allows you, as the administrator, to easily change these shared configurations if necessary.
To accomplish this, perform the following steps:
Create a central boto configuration file that is readable by all employees.
This can be done by using
gcloud initwhen gsutil is installed as part of the Google Cloud SDK.
The boto configuration file might contain, for example:
[Boto] proxy = yourproxy.com proxy_port = 8080 proxy_type = http [GSUtil] parallel_composite_upload_threshold = 150M
Instruct employees to install the Google Cloud SDK.
During installation, employees need to specify the project ID that the company is using. They also need to generate individual authentication credentials because you cannot share authentication credentials centrally.
Instruct employees to add a BOTO_PATH environment variable.
The BOTO_PATH environment variable lists the path of the centrally located configuration file, followed by the employee's local configuration file. For example, if the central configuration file is located in the directory
centralhub/, then for user
jane, the BOTO_PATH environment variable might be:
When employees run gsutil, they will automatically use the configuration specified in the central boto file. If necessary, the administrator can change the proxy settings, parallel composite upload threshold, and other settings in the central configuration file and have the changes reflected for all employees using the central configuration file.