Using Boto

This page describes how gsutil uses a boto configuration file and provides a boto collaboration example.

Using boto with Google Cloud Storage

  • 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_api variable). These variables can be changed by editing the 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 prefer_api and default_project_id variables, respectively). These variables can be changed by editing the file directly. The file also controls credentials and OAuth2 settings, which you typically create by using the gsutil config command.

The default location for the boto configuration file is in the user home directory, ~/.boto, for Linux and Mac OS X, and in %HOMEDRIVE%%HOMEPATH%, for Windows. You can get the location of the configuration file by running the command 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.

For a complete listing of what the boto configuration file contains, see gsutil config.

Collaboration example with boto

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 Platform 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:

  1. Create a central boto configuration file that is readable by all employees.

    This can be done by using gcloud init when 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
     
    [GSUtil]
    parallel_composite_upload_threshold = 150M
    

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

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

    BOTO_PATH =/centralhub/boto.cfg:home/jane/.boto

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.

Send feedback about...

Cloud Storage Documentation