gcsfuse CLI

This page describes the gcsfuse command-line options used to interact with Cloud Storage FUSE.

Synopsis

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Where:

  • GLOBAL_OPTIONS are the options that control how the mount is set up and how Cloud Storage FUSE behaves.

  • BUCKET_NAME is the name of the bucket to mount. For example, my-mount-bucket. Optional. Exclude a bucket name from this command to perform dynamic mounting.

  • MOUNT_POINT is the local directory where the bucket will be mounted. For example, /path/to/mount/point.

Description

The gcsfuse CLI is used to mount Cloud Storage buckets as file systems on a local machine.

Global options

Global options Description
--anonymous-access BOOLEAN Disables authentication for requests. This flag should be set if you're using a custom endpoint that doesn't support authentication. This flag should also be set if you're using Cloud Storage FUSE with public buckets. The default value is false.
--app-name VALUE The application name of the mount.
--billing-project VALUE 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.
--cache-dir VALUE Specifies the directory for storing file cache data.

Note: To enable file caching, you must specify a directory using --cache-dir and use the --file-cache-max-size-mb flag to specify either a positive integer that denotes a specific maximum file cache size limit in mebibytes (MiB) or use a value of -1 to specify no limit.
--client-protocol VALUE Specifies the protocol used for communicating with the Cloud Storage backend. The value must be http1 for HTTP/1.1 or http2 for HTTP/2. The default value is http1.
--config-file VALUE Specifies the path to the configuration file you want to use to configure Cloud Storage FUSE behaviors. For example, --config-file /etc/gcsfuse.yaml
--custom-endpoint VALUE 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 isn't 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.
--debug_fuse BOOLEAN Deprecated. Enables FUSE-related debugging output. This option has been replaced by the --log-severity option. To enable debugging output, set the --log-severity option to trace, which includes trace, debug, info, warning, and error logs.
--debug_gcs BOOLEAN Deprecated. Prints Cloud Storage request and timing information. This option has been replaced by the --log-severity option. To enable debugging output, set the --log-severity option to trace, which includes trace, debug, info, warning, and error logs.
--debug_invariants BOOLEAN Exits the program when internal invariant violations are detected. The default value is false.
--debug_mutex BOOLEAN 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, debug, info, warning, and error logs. The default value is false.
--dir-mode VALUE Permissions bits for directories, in octal. The minimum value is 000 and the maximum value is 777. The default value is 755.
--enable-nonexistent-type-cache BOOLEAN Creates a type cache entry with the type NonexistentType if a file isn't 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.
--file-cache-cache-file-for-range-read BOOLEAN

Determines whether the full object should be downloaded asynchronously and stored in the Cloud Storage FUSE cache directory when the first read is completed from a non-zero offset. This flag should be set to true if you plan to perform several random reads or partial reads. If this field is unspecified, the value defaults to false.

Note: If you perform a partial read starting at offset 0, Cloud Storage FUSE asynchronously downloads and caches the full object.
--file-cache-download-chunk-size-mb VALUE

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.
--file-cache-enable-parallel-downloads BOOLEAN

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.
--file-cache-max-parallel-downloads VALUE

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 your machine or 16, whichever is higher. To specify no limit, enter a value of -1.
--file-mode VALUE Specifies permissions bits for files, in octal. The minimum value is 000 and the maximum value is 777. The default value is 644.
--foreground BOOLEAN Runs the gcsfuse command in the foreground. The default value is false.
--gid VALUE Specifies the Group Identifier (GID) owner of all inodes. The value must be an integer. The default value is -1.
--help or -h Displays help about Cloud Storage FUSE.
version or -v Displays the Cloud Storage FUSE version you have installed.
--http-client-timeout VALUE Specifies how long the Cloud Storage FUSE HTTP client can wait to get a response from the server before timing out. The value must be a time duration. For example, 1h10m10s. The default value is 0s, which indicates no timeout.
--ignore-interrupts VALUE 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.
--implicit-dirs BOOLEAN

Implicitly includes folders and managed folders.

See the files and directories documentation in GitHub for more information. The default value is false.
--kernel-list-cache-ttl-secs VALUE Enables the list cache and defines the time to live (TTL) in seconds of cached list entries. The list cache is kept in memory in the page cache, which 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 flag, specify a positive integer 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.
--key-file VALUE 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.
--limit-bytes-per-sec VALUE Specifies the bandwidth limit at which Cloud Storage FUSE can read data from Cloud Storage, measured over a 30-second window. The value must be a floating point number. The default value is -1, which specifies no limit.
--limit-ops-per-sec VALUE Specifies a limit for operations performed per second, measured over a 30-second window. The value must be a floating-point number. The default value is -1, which specifies no limit.
--log-file VALUE Specifies the file for storing logs that can be parsed by Fluentd. When not provided, plain text logs are printed to stdout when Cloud Storage FUSE is run in the foreground, or to syslog when Cloud Storage FUSE is run in the background.
--log-format VALUE Specifies the format of the log file. The value must be either text or json. The default value is json.
--log-rotate-backup-file-count VALUE The maximum number of rotated log files to retain, excluding the active file that logs are written to. When the value is set to 0, all rotated log files are retained. If this field is unspecified, the value defaults to 10.
--log-rotate-compress BOOLEAN A boolean value that specifies whether rotated log files are compressed using gzip. If this flag is unspecified, the value defaults to true.
--log-rotate-max-file-size-mb VALUE 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.
--log-severity ENUM

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. Generally, we recommend using the info severity level. You can also specify off to turn off all logging. If you specify --debug_mutex as part of your command, the severity level is automatically set to trace and overrides log-severity.

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 such as during troubleshooting.
--max-conns-per-host VALUE Specifies the maximum number of TCP connections allowed per server. This becomes effective when --client-protocol is set to http1. The value must be between 0 to 2147483647. 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 VALUE Specifies the maximum number of idle connections allowed per server. The value must be between 0 to 2147483647. The default value is 100.
--max-retry-sleep VALUE Specifies the maximum duration that Cloud Storage FUSE is allowed to sleep in a retry loop with exponential backoff. The value must be a time duration value. For example, 1h5m50s (1 hour, 5 minutes, and 50 seconds) or 60s (60 seconds). Once the backoff duration exceeds the specified maximum duration, the retry continues with the specified maximum duration. The default value is 30s.
--metadata-cache-ttl-secs VALUE

Defines the time to live (TTL) in seconds of cached metadata entries.

  • To bypass a TTL expiration and serve the file from the cache whenever it's available, specify a value of -1.
  • To use the most up to date file, specify a value of 0. 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 60 (60 seconds).
-o VALUE

Specifies additional system-specific mount options.

Most generic mount options in FUSE such as suid are supported by Cloud Storage FUSE and can be passed along with the -o flag.

Some commonly used mount options that are available with the -o flag include the following:

  • rw: mount as read-write.
  • ro: mount as read-only.

For more information on other supported mount options, see the Linux FUSE documentation.
--only-dir VALUE Mounts only a specific directory within a bucket.
--rename-dir-limit VALUE Allows the renaming of directories containing fewer descendants than the specified limit. The value must be between 0 to 2147483647. The default limit value is 0.
--retry-multiplier VALUE Specifies the multiplier for exponential backoff between consecutive retries. The value must be a floating-point number. The default value is 2.
--reuse-token-from-url Specifies whether to reuse the token acquired from --token-url. The default value is true.
--sequential-read-size-mb VALUE Specifies the chunk size of the data to be downloaded from Cloud Storage, in megabytes (MB). The value must be between 1 and 1024. The default value is 200.
--stackdriver-export-interval VALUE Exports metrics to stackdriver with the specified interval. The value must be a time duration. For example, 1h10m10s. The default value is 0s, which specifies no exporting.
--stat-cache-capacity VALUE Deprecated. Specifies the number of entries that the stat cache can hold. This impacts memory consumption. The value must be an integer. The default value is 4096.

This flag has been replaced by --stat-cache-max-size-mb. To specify the maximum size in mebibytes (MiB) that the stat cache can use, use the --stat-cache-max-size-mb flag.
--stat-cache-max-size-mb VALUE

The maximum size in mebibytes (MiB) that the stat cache can use. The stat cache is always entirely kept in memory.

  • Specify a value of 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, where the stat cache uses an average of 1,500 MiB per file.
  • To let the stat cache use as much memory as needed, meaning to set no limit, specify a value of -1.
  • To disable the stat cache, specify a value of 0.

If this field is unspecified, the value defaults to 32.
--stat-cache-ttl VALUE Deprecated. Specifies how long to cache StatObject results and inode attributes. The default value is 60s (60 seconds).

This flag has been replaced by --metadata-cache-ttl-secs. To specify the time to live (TTL) in seconds for cached metadata entries, use the --metadata-cache-ttl-secs flag.
--temp-dir VALUE 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, most likely /tmp.
--token-url VALUE Specifies a URL for getting an access token when the --key-file is absent.
--type-cache-ttl VALUE Deprecated. Specifies how long to cache the mapping between names and files or directories in directory inodes. This option has been replaced by the --metadata-cache-ttl-secs option. To specify the length of time you want to set for the type cache, use the --metadata-cache-ttl-secs option, which specifies the time to live (TTL) of metadata entries of both stat and type caches. The default value for --metadata-cache-ttl-secs is 60s (60 seconds).
--type-cache-max-size-mb VALUE

The maximum size in MiB per directory that the type cache can use. The type cache is always entirely kept in memory.

  • Specify a value of 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 around 200 bytes per file.
  • To let the type cache use as much memory as needed, in other words, to specify no limit, specify a value of -1.
  • To disable the type cache, specify a value of 0.

If this field is unspecified, the value defaults to 4.
--uid VALUE Specifies the User Identifier (UID) owner of all inodes. The value must be an integer. The default UID value is -1.