Cloud Storage FUSE configuration file

This page describes how to use a Cloud Storage FUSE configuration file to configure the behavior of Cloud Storage FUSE in a persistent manner. To use the configuration file, specify the path to the configuration file in the --config-file flag as part of your mount command.

The configuration file is a YAML file that uses the following format and fields. Some of the fields can also be specified by using command-line options.

app-name: "APP_NAME"
write:
  create-empty-file: CREATE_EMPTY_FILE
logging:
  file-path: "FILE_PATH"
  format: FORMAT
  severity: SEVERITY
  log-rotate:
    max-file-size-mb: MAX_FILE_SIZE
    backup-file-count: BACKUP_FILE_COUNT
    compress: COMPRESS
file-cache:
  max-size-mb: MAX_SIZE
  cache-file-for-range-read: CACHE_FILE_FOR_RANGE_READ
  enable-parallel-downloads: ENABLE_PARALLEL_DOWNLOADS
  parallel-downloads-per-file: PARALLEL_DOWNLOADS_PER_FILE
  max-parallel-downloads: MAX_PARALLEL_DOWNLOADS
  download-chunk-size-mb: DOWNLOAD_CHUNK_SIZE
metadata-cache:
  enable-nonexistent-type-cache: ENABLE_NONEXISTENT_TYPE_CACHE
  stat-cache-max-size-mb: STAT_CACHE_MAX_SIZE
  ttl-secs: TTL_SECS
  type-cache-max-size-mb: TYPE_CACHE_MAX_SIZE
cache-dir: "CACHE_DIR"
only-dir: "ONLY_DIR"
gcs-auth:
  anonymous-access: ANONYMOUS_ACCESS
  key-file: "KEY_FILE"
  reuse-token-from-url: REUSE_TOKEN_FROM_URL
  token-url: "TOKEN_URL"
gcs-connection:
  billing-project: "BILLING_PROJECT"
  client-protocol: CLIENT_PROTOCOL
  custom-endpoint: "CUSTOM_ENDPOINT"
  http-client-timeout: HTTP_CLIENT_TIMEOUT
  limit-bytes-per-sec: "LIMIT_BYTES_PER_SEC"
  limit-ops-per-sec: "LIMIT_OPS_PER_SEC"
  max-conns-per-host: MAX_CONNS_PER_HOST
  max-idle-conns-per-host: MAX_IDLE_CONNS_PER_HOST
  sequential-read-size-mb: SEQUENTIAL_READ_SIZE
implicit-dirs: IMPLICIT_DIRS
file-system:
  kernel-list-cache-ttl-secs: KERNEL_LIST_CACHE_TTL_SECS
  ignore-interrupts: IGNORE_INTERRUPTS
  dir-mode: "DIR_MODE"
  file-mode: "FILE_MODE"
  fuse-options: FUSE_OPTIONS
  gid: GID
  rename-dir-limit: RENAME_DIR_LIMIT
  temp-dir: "TEMP_DIR"
  uid: UID
foreground: FOREGROUND
gcs-retries:
  max-retry-sleep: MAX_RETRY_SLEEP
  multiplier: "MULTIPLIER"
metrics:
  stackdriver-export-interval: STACKDRIVER_EXPORT_INTERVAL
debug:
  log-mutex: LOG_MUTEX
  exit-on-invariant-violation: EXIT_ON_INVARIANT_VIOLATION

Configuration fields

The following table describes the fields you can specify in your configuration file. Unless stated otherwise, all fields are optional.

Field	Description
`app-name`	The application name of the mount.
`create-empty-file`	A Boolean value that specifies whether or not to create a zero-byte file in Cloud Storage when you start writing to a new file in the mounted bucket. If this field is unspecified, the value defaults to `false`.
`file-path`	The path to the log file where logs will be written, specified as a string. For example, `/var/log`. If this field is unspecified, the logs are routed to stdout when Cloud Storage FUSE runs in foreground mode and to syslogs when Cloud Storage FUSE runs in background mode.
`format`	The format in which logs are generated, expressed as an enum. Values are `text` or `json`. If this field is unspecified, the value defaults to `json`.
`severity`	The severity of logs you want Cloud Storage FUSE to generate, expressed as an enum. The severity levels are ordered from lowest severity to highest severity: `trace` `debug` `info` `warning` `error` When you specify a severity level, Cloud Storage FUSE generates logs having equal or higher severity. For example, when you specify `warning`, Cloud Storage FUSE generates logs for warnings and errors. You can also specify `off` to turn off all logging. Generally, we recommend using the `info` severity level. The severity level is automatically set to `trace` if any of the following options are specified as part of your command: `--debug_fuse` `--debug_gcs` `--debug_mutex` If this field is unspecified, the value defaults to `info`. Note: Using either the `trace` or `debug` severity levels when file caching is enabled can result in performance degradation due to logging overhead and should only be used temporarily or during troubleshooting.
`max-file-size-mb`	The maximum size in megabytes (MB) that log files can reach before being rotated. The minimum value is `1`. If this field is unspecified, the value defaults to `512`.
`backup-file-count`	The maximum number of rotated log files to retain, excluding the active file to which logs are written. When the value is set to `0`, all rotated log files are retained. If this field is unspecified, the value defaults to `10`.
`compress`	A Boolean value that specifies whether rotated log files are compressed using gzip. If this field is unspecified, the value defaults to `true`.
`max-size-mb`	The maximum size in MiB that the file cache can use. If present, `max-size-mb` enables file caching in Cloud Storage FUSE and is useful if you want to limit the total capacity the Cloud Storage FUSE cache can use within its mounted directory. Specify `-1` to use the cache's entire available capacity in the directory you specify for `cache-dir`. Specify `0` to disable the file cache. If this field is unspecified, the value defaults to `-1`.
`cache-file-for-range-read`	A Boolean value that determines whether the full object should be downloaded asynchronously and stored in the Cloud Storage FUSE cache directory when the first read is done from a non-zero offset. This should be set to `true` if you plan on performing several random reads or partial reads. If this field is unspecified, the value defaults to `false`. Note that if you do a partial read starting at offset `0`, Cloud Storage FUSE always asynchronously downloads and caches the full object.
`enable-parallel-downloads`	Accelerates reads of large files by using the file cache directory as a prefetch buffer using multiple workers to download large files in parallel. The default value is `false`. To use parallel downloads, you must enable file caching. To learn more about parallel downloads and configure its supporting properties, see Improve read performance using parallel downloads.
`parallel-downloads-per-file`	Specifies the number of maximum goroutines to spawn per file to download the object from Cloud Storage into the file cache. The default value is `16`.
`max-parallel-downloads`	The maximum number of goroutines that can be spawned at any given time across all the download jobs of files. The default is twice the number of CPU cores on the machine. To bypass a limit, specify a value of `-1`.
`download-chunk-size-mb`	Specifies the size of each read request in MiB that each goroutine makes to Cloud Storage when downloading the object into the file cache. The default value is `50`.
`enable-nonexistent-type-cache`	Creates a type cache entry with the type `NonexistentType` if a file is not found in Cloud Storage. If the file gets created in Cloud Storage but the `NonexistentType` entry for the file is cached, then Cloud Storage FUSE cannot request that file until the `NonexistentType` entry is removed from the type cache. The default value is `false`.
`stat-cache-max-size-mb`	The maximum size in MiB that the stat cache can use. The stat cache is always entirely kept in memory. Specify `32` if your workload involves up to 20,000 files. If your workload is larger than 20,000 files, increase the size by values of 10 for every additional 6,000 files, which is an average of about 1,500 bytes per file. Specify `-1` to let the stat cache use as much memory as needed. Specify `0` to disable the stat cache. If this field is unspecified, the value defaults to `32`.
`ttl-secs`	Defines the time to live (TTL) of cached metadata entries, expressed in seconds. Specify `-1` to bypass a TTL expiration and serve the file from the cache whenever it's available. Specify `0` to ensure that the most up to date file is read. Using this value issues a Get metadata call to make sure that the object generation for the file in the cache matches what's stored in Cloud Storage. To learn more, see Configuring cache invalidation. If this field is unspecified, the value defaults to `60s`.
`type-cache-max-size-mb`	The maximum size in MiB per directory that the type cache can use. The type cache is always entirely kept in memory. Specify `4` if the maximum number of files within a single directory from the bucket you're mounting contains 20,000 files or less. If the maximum number of files within a single directory that you're mounting contains more than 20,000 files, increase the value by `1` for every 5,000 files, which is an average of about 200 bytes per file. Specify `-1` to let the type cache use as much memory as needed. Specify `0` to disable the type cache. If this field is unspecified, the value defaults to `4`.
`cache-dir`	Specifies the directory for storing file cache data. This field must be specified in order to enable file caching.
`only-dir`	Mounts only a specific directory within a bucket.
`anonymous-access`	Disables authentication for requests. Set this field if you're using a custom endpoint that doesn't support authentication or if you're using Cloud Storage FUSE to mount public buckets. The default value is `false`.
`key-file`	Specifies an absolute path to the credential JSON key file for authenticating requests to Cloud Storage. By default, Cloud Storage FUSE uses Application Default Credentials to authenticate requests.
`reuse-token-from-url`	Specifies that the token acquired from `token-url` be used. The default value is `true`.
`token-url`	Specifies a URL for getting an access token when the `key-file` is absent.
`billing-project`	Specifies a project to use for billing when the mounted bucket is accessed. This flag is often required when mounting a bucket enabled with Requester Pays. The default project is none.
`client-protocol`	Specifies the protocol used for communicating with the Cloud Storage backend. The value can be `http1` for HTTP/1.1 or `http2` for HTTP/2. The default value is `http1`.
`custom-endpoint`	Specifies an alternative custom endpoint for fetching data. The custom endpoint must support the equivalent resources and operations as the Cloud Storage JSON endpoint, `https://storage.googleapis.com/storage/v1`. If a custom endpoint is not specified, Cloud Storage FUSE uses the global Cloud Storage JSON API endpoint, `https://storage.googleapis.com/storage/v1`. If authentication isn't supported on the custom endpoint you specify, set the `anonymous-access` flag to `true` to bypass authentication.
`http-client-timeout`	Specifies how long the Cloud Storage FUSE HTTP client can wait to get a response from the server before timing out. The default value is `0s`, which indicates no timeout.
`limit-bytes-per-sec`	Specifies the bandwidth limit at which Cloud Storage FUSE can read data from Cloud Storage, measured over a 30-second window. The default limit value is `"-1"`, which specifies no limit.
`limit-ops-per-sec`	Specifies a limit for operations performed per second, measured over a 30-second window. The default limit value is `"-1"`, which specifies no limit.
`max-conns-per-host`	Specifies the maximum number of TCP connections allowed per server. This becomes effective when `client-protocol` is set to `http1`. The default value is `0`, which specifies that there is no limit on TCP connections except for limitations set by your machine's specifications.
`max-idle-conns-per-host`	Specifies the maximum number of idle connections allowed per server. The default value is `100`.
`sequential-read-size-mb`	Specifies the chunk size of the data to be downloaded from Cloud Storage, in megabytes (MB). The default value is `200`.
`implicit-dirs`	Implicitly includes folders and managed folders. See the files and directories documentation in GitHub for more information.
`kernel-list-cache-ttl-secs`	Enables the list cache and defines the time to live (TTL) in seconds of cached list entries. Memory allocation for the list cache is controlled by the kernel based on available memory. The default value is `0` which disables list caching. To set the `kernel-list-cache-ttl-secs` field, specify a positive value in seconds to keep the directory list response in the kernel's page cache. To bypass entry expiration and always return the list response from the cache when it's available, specify a value of `-1`.
`ignore-interrupts`	Instructs Cloud Storage FUSE to ignore system interrupt signals, like SIGINT triggered by `Control+C`. This prevents signals from terminating in-flight operations. Values are `true` or `false`. The default value is `true`.
`dir-mode`	Permissions bits for directories, in octal. The default value is `"755"`.
`file-mode`	Specifies permissions bits for files, in octal. The default value is `"644"`.
`fuse-options`	Specifies additional system-specific mount options.
`gid`	Specifies the Group Identifier (GID) owner of all inodes. The default GID value is `-1`.
`rename-dir-limit`	Allows the renaming of directories containing fewer descendants than the specified limit. The default limit value is `0`.
`temp-dir`	Specifies a path to the temporary directory where writes are staged prior to being uploaded to Cloud Storage. The default value is your system default, such as `"/tmp"`.
`uid`	Specifies the User Identifier (UID) owner of all inodes. The default UID value is `-1`.
`foreground`	Runs the `gcsfuse` command in the foreground. The default value is `false`.
`max-retry-sleep`	Specifies the maximum duration that Cloud Storage FUSE is allowed to sleep in a retry loop with exponential backoff. Once the backoff duration exceeds the specified maximum duration, the retry continues with the specified maximum duration. The default limit value is `30s` (30 seconds).
`multiplier`	Specifies the exponential backoff between retries, where the value is the multiplier for the subsequent wait time based on the prior wait time. The default value is `"2"`.
`stackdriver-export-interval`	Exports metrics to Cloud Monitoring with the specified interval. The default value is `0s` (0 seconds), which specifies no exporting.
`log-mutex`	Prints debug messages when a mutex is held too long. If this option is specified, the severity level of logs is automatically set to `trace`, which includes trace logs, debug logs, info logs, warning logs, and error logs. The default value is `false`.
`exit-on-invariant-violation`	Exits the program when internal variant violations are detected. The default value is `false`.