gcsfuse CLI

This page describes the gcsfuse command-line options used to interact with Cloud Storage FUSE. If you're using the Cloud Storage FUSE CSI driver to mount your buckets to your local file system in Google Kubernetes Engine, see Mount options for the Cloud Storage FUSE CSI driver.

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

Option Description Valid value Default value
--anonymous-access Disables authentication for requests. This option should be set if you're using a custom endpoint that doesn't support authentication. This option should also be set if you're using Cloud Storage FUSE with public buckets. Boolean value: true, false. false
--app-name The application name of the mount. String value, for example: my-bucket-mount. ""
--billing-project Specifies a project to use for billing when the mounted bucket is accessed. This option is often required when mounting a bucket enabled with Requester Pays. String value representing a project ID. ""
--cache-dir

Specifies the directory for storing file cache data.

To learn how to enable file caching, see Use file caching.

 A path, for example: /tmp/gcsfuse-cache-path. ""
--client-protocol Specifies the protocol used for communicating with the Cloud Storage backend.
  • http1 for HTTP/1.1
  • http2 for HTTP/2
  • grpc for gRPC
 http1
--config-file Specifies the path to the configuration file you want to use to configure Cloud Storage FUSE behaviors. A path, for example: /etc/gcsfuse.yaml. ""
--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 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. An endpoint, for example: http://localhost:443/storage/v1. ""
--debug_fuse (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. Boolean value: true, false. false if --debug_fuse is not specified. true if --debug_fuse is specified.
--debug_gcs (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. Boolean value: true, false. false if --debug_gcs is not specified. true if --debug_gcs is specified.
--debug_invariants Exits the program when internal invariant violations are detected. Boolean value: true, false. false
--debug_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, debug, info, warning, and error logs. Boolean value: true, false. false
--dir-mode Permissions bits for directories, in octal. Integer between 000 and 777 (inclusive). 755
--enable-nonexistent-type-cache 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. Boolean value: true, false. false
--file-cache-cache-file-for-range-read 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 option should be set to true if you plan to perform several random reads or partial reads.

Note: If you perform a partial read starting at offset 0, Cloud Storage FUSE asynchronously downloads and caches the full object.

 Boolean value: true, false. false
--file-cache-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. Integer 50
--file-cache-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. To learn more about parallel downloads and configure its supporting properties, see Improve read performance using parallel downloads.

To use parallel downloads, you must first enable file caching.

 Boolean value: true, false. false
--file-cache-max-parallel-downloads The maximum number of goroutines that can be spawned at any given time across all the download jobs of files.
  • Integer
  • -1: Specifies unlimited parallel downloads.
  • 0: Disables parallel downloads. Can only be used if --enable-parallel-downloads is not passed or is passed as false.
  • >0: Specifies no upper limit. Cloud Storage FUSE internally limits the value based on the maximum number of goroutines that can be spawned specified by your machine's configuration.
 Twice the number of CPU cores on your machine or 16, whichever is higher.
--file-mode Specifies permissions bits for files, in octal. Integer between 000 and 777 (inclusive). 644
--foreground Runs the gcsfuse command in the foreground. Boolean value: true, false. false
--gid Specifies the Group Identifier (GID) owner of all inodes.
  • Integer representing a GID.
  • -1: The GID of the caller is used.
 -1
--help Displays help about Cloud Storage FUSE. None None
--version Displays the Cloud Storage FUSE version you have installed. None None
--http-client-timeout Specifies how long the Cloud Storage FUSE HTTP client can wait to get a response from the server before timing out. Duration, for example: 1h10m10s for 1 hour, 10 minutes, and 10 seconds. 0s specifies no timeout. 0s
--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. Boolean value: true, false. true
--implicit-dirs Implicitly includes folders and managed folders. See the files and directories documentation in GitHub for more information. Boolean value: true, false. false
--kernel-list-cache-ttl-secs 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.
  • Integer representing seconds, for example: 10 (10 seconds).
  • 0: Disables list caching.
  • -1: Bypasses entry expiration and always returns the list response from the cache when it's available.
 0
--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. A path, for example: /home/example_user/gcloud-key.json. When this option is not set, Application Default Credentials are used.
--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. Floating point number. -1 specifies no limit. -1
--limit-ops-per-sec Specifies a limit for operations performed per second, measured over a 30-second window. Floating point number. -1 specifies no limit. -1
--log-file Specifies the file for storing logs that can be parsed by Fluentd. A path, for example: /tmp/user-example-bucket-gcsfuse-logs.txt. stdout when Cloud Storage FUSE is run in the foreground or syslog when Cloud Storage FUSE is run in the background
--log-format Specifies the format of the log file.
  • text
  • json
 json
--log-rotate-backup-file-count The maximum number of rotated log files to retain, excluding the active file that logs are written to.
  • Integer
  • 0: Retains all rotated log files
 10
--log-rotate-compress Specifies whether rotated log files are compressed using gzip. Boolean value: true, false. true
--log-rotate-max-file-size-mb The maximum size in megabytes (MB) that log files can reach before being rotated. Integer. The minimum value is 1. 512
--log-severity

The severity level you want Cloud Storage FUSE to generate logs for. The severity levels are ordered from lowest severity to highest severity. For example, when you specify warning, Cloud Storage FUSE generates logs for warnings and errors. Generally, we recommend using the info severity level.
  • trace
  • debug
  • info
  • warning
  • error
  • off: Disables all logging.
 info
--max-conns-per-host Specifies the maximum number of TCP connections allowed per server. This becomes effective when --client-protocol is set to http1. Integer between 0 and 2147483647. 0 specifies no limit on TCP connections. 0
--max-idle-conns-per-host Specifies the maximum number of idle connections allowed per server. This becomes effective when --client-protocol is set to http1. Integer between 0 and 2147483647. 0 specifies no limit on idle connections. 0
--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. Duration, for example: 1h5m50s (1 hour, 5 minutes, and 50 seconds) or 60s (60 seconds). 30s
--metadata-cache-negative-ttl-secs

Defines the time to live (TTL) in seconds of negative stat cache entries, which store results for non-existent files in the cache.
  • Integer representing seconds, for example: 10 (10 seconds).
  • 0: Disables negative stat caching.
  • -1: Allows unlimited negative stat caching and disables a TTL expiration.
 5
--metadata-cache-ttl-secs Defines the time to live (TTL) in seconds of cached metadata entries.
  • Integer representing seconds, for example: 30 (30 seconds).
  • -1: Bypass TTL expiration and serve files from the cache whenever they're available.
  • 0: Use the most up-to-date file. 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.
 60
-o 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 option. Mount options in FUSE, for example:
  • rw: Mount as read-write.
  • ro: Mount as read-only.
 ""
--only-dir Mounts only a specific directory within a bucket. A path, for example: /etc/gcsfuse.yaml. ""
--rename-dir-limit Allows the renaming of directories containing fewer descendants than the specified limit. Integer between 0 and 2147483647. 0
--retry-multiplier Specifies the multiplier for exponential backoff between consecutive retries. Floating-point number. 2
--reuse-token-from-url Specifies whether to reuse the token acquired from --token-url. Boolean value: true, false. true
--sequential-read-size-mb Specifies the chunk size of the data to be downloaded from Cloud Storage, in megabytes (MB). Integer between 1 and 1024. 200
--stackdriver-export-interval Exports metrics to stackdriver with the specified interval. Duration, for example: 1h5m50s (1 hour, 5 minutes, and 50 seconds). 0s specifies no exporting. 0s
--stat-cache-capacity (deprecated) Specifies the number of entries that the stat cache can hold. This option has been replaced by the --stat-cache-max-size-mb option. Integer 4096
--stat-cache-max-size-mb The maximum size memory that the stat cache can use, in MiB. The stat cache is always entirely kept in memory.
  • Integer. We recommend the following:
    • 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.
  • -1: Sets no limit, where the stat cache use as much memory as needed.
  • 0: Disables the stat cache.
 32
--stat-cache-ttl (deprecated) Specifies how long to cache StatObject results and inode attributes. This option has been replaced by the --metadata-cache-ttl-secs option. Duration, for example: 20s (20 seconds). 60s
--temp-dir Specifies a path to the temporary directory where writes are staged prior to being uploaded to Cloud Storage. A path, for example: /mnt/ssd/example-user-gcsfuse-temp-dir. /tmp
--token-url Specifies a URL for getting an access token when the --key-file is absent. A URL. ""
--type-cache-ttl (deprecated) Specifies how long to cache the mapping between names and files or directories in directory inodes, in seconds. This option has been replaced by the --metadata-cache-ttl-secs option. Duration in seconds, for example: 20s (20 seconds). 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.
  • Integer. We recommend the following:
    • 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.
  • -1: Specifies no limit and lets the type cache use as much memory as needed.
  • 0: Disables the type cache.
 4
--uid Specifies the User Identifier (UID) owner of all inodes.
  • Integer representing a UID.
  • -1: The UID of the caller is used.
 -1