S3FS(1)

📦
version 1.97 · 7 versions
, in alpine 3.24, epel 10, epel 9, fedora 43, fedora 44, ubuntu stonking

🌸 S3FS — User Commands, section 1

okay bestie, buckle UP, because S3FS is a whole vibe and we're doing this properly. it's in section 1 of the manual (User Commands, iykyk), and no cap, this thing is long, so we're taking it in pieces. this is piece one. hydrate. 💅

✨ NAME ✨

S3FS — a FUSE-based file system backed by Amazon S3. that's it. that's the name section. iconic minimalism, honestly. 🫶

🎀 SYNOPSIS 🎀

🌈 mounting

s3fs bucket[:/path] mountpoint  [options]

s3fs mountpoint  [options (must specify bucket= option)]

🦋 unmounting

umount mountpoint

For root. 👑

fusermount -u mountpoint

For unprivileged user.

🍓 utility mode (remove interrupted multipart uploading objects)

s3fs --incomplete-mpu-list (-u) bucket

s3fs --incomplete-mpu-abort[=all | =<expire date format>] bucket

💖 DESCRIPTION 💖

so, s3fs is a FUSE filesystem that lets you mount an Amazon S3 bucket as a local filesystem. it stores files natively and transparently in S3, which means — and this is the slay part — you can use other programs to access the same files. the files are just... there. on S3. being normal. ✨

🔐 AUTHENTICATION 🔐

s3fs supports the standard AWS credentials file, which lives here: https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html — and it's stored in ${HOME}/.aws/credentials. 💌

or, if you want a custom passwd file, s3fs supports that too. but heads up: only the AWS credentials file format can be used when an AWS session token is required. no exceptions, bestie, it's giving strict.

the s3fs password file has this format — use this one if you've only got one set of credentials:

accessKeyId:secretAccessKey

if you have more than one set of credentials, this syntax is also recognized:

bucketName:accessKeyId:secretAccessKey

password files can be stored in two locations:

  • /etc/passwd-s3fs — [0640]
  • $HOME/.passwd-s3fs — [0600]

s3fs also recognizes the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. 🫶

👑 OPTIONS 👑

🧚 general options

  • -h, --help — print help. the "help me please" button.
  • --version — print version. the "what era are we in" button.
  • -f — FUSE foreground option — do not run as a daemon. it stays right there with you, in your terminal, watching. 🙈
  • -s — FUSE single-threaded option. this disables multi-threaded operation, so everything happens one at a time, like a very patient queen.

🌸 mount options

all s3fs options must be given in the form where "opt" is:

<option_name>=<option_value>
  • -o bucket — if it is not specified bucket name (and path) in command line, you must specify this option after the -o option for the bucket name.
  • -o default_acl (default="private") — the default canned acl to apply to all written s3 objects, e.g., "private", "public-read". for the full list of canned ACLs, go see https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl. 📋
  • -o retries (default="5") — number of times to retry a failed S3 transaction. it's persistent. it's trying. we respect it.
  • -o tmpdir (default="/tmp") — local folder for temporary files. the little waiting room. 🪑
  • -o use_cache (default="" which means disabled) — local folder to use for local file cache.
  • -o check_cache_dir_exist (default is disable) — if use_cache is set, check if the cache directory exists. if this option is not specified, the directory will be created at runtime when the cache directory does not exist. it's flexible like that. ✨
  • -o del_cache — delete local file cache. it deletes the local file cache when s3fs starts and exits. bye cache, love u, mean it. 👋
  • -o storage_class (default="standard") — store object with specified storage class. possible values: standard, standard_ia, onezone_ia, reduced_redundancy, intelligent_tiering, glacier, glacier_ir, and deep_archive. pick your fighter. 🥊
  • -o use_rrs (default is disable) — use Amazon's Reduced Redundancy Storage. this option can not be specified with use_sse. (can specify use_rrs=1 for old version.) this option has been replaced by the new storage_class option, so it's giving legacy, but we still document it because that's the assignment.
  • -o use_sse (default is disable) — okay this one is a whole saga, sit down. 🍿

it specifies three types of Amazon's Server-Site Encryption: SSE-S3, SSE-C or SSE-KMS. SSE-S3 uses Amazon S3-managed encryption keys, SSE-C uses customer-provided encryption keys, and SSE-KMS uses the master key which you manage in AWS KMS.

you can specify "use_sse" or "use_sse=1" and that enables the SSE-S3 type (use_sse=1 is the old type parameter).

for setting SSE-C, you can specify "use_sse=custom", "use_sse=custom:<custom key file path>" or "use_sse=<custom key file path>" (only <custom key file path> specified is the old type parameter). you can use "c" as the short form of "custom".

the custom key file must be 600 permission. the file can have some lines, each line is one SSE-C key. the first line in the file is used as Customer-Provided Encryption Keys for uploading and changing headers etc. if there are some keys after the first line, those are used for downloading objects which are encrypted by a not-first key. so that, you can keep all SSE-C keys in the file — that's the SSE-C key history, bestie, it's a scrapbook of keys. 📖

if you specify "custom" ("c") without a file path, you need to set the custom key by the load_sse_c option or the AWSSSECKEYS environment. (AWSSSECKEYS environment has some SSE-C keys with ":" separator.)

this option is used to decide the SSE type. so that if you do not want to encrypt an object at uploading, but you need to decrypt an encrypted object at downloading, you can use the load_sse_c option instead of this option. 💡

for setting SSE-KMS, specify "use_sse=kmsid" or "use_sse=kmsid:<kms id>". you can use "k" as the short form of "kmsid". if you can specify the SSE-KMS type with your <kms id> in AWS KMS, you can set it after "kmsid:" (or "k:"). if you specify only "kmsid" ("k"), you need to set the AWSSSEKMSID environment, whose value is <kms id>.

⚠️ you must be careful about the fact that you can not use a KMS id which is not in the same EC2 region. and additionally, if you specify SSE-KMS, your endpoints must use Secure Sockets Layer (SSL) or Transport Layer Security (TLS). no shortcuts, no vibes-only networking. 🔒
  • -o load_sse_c — specify SSE-C keys. this specifies the custom-provided encryption keys file path for decrypting at downloading. if you use the custom-provided encryption key at uploading, you specify it with "use_sse=custom". the file has many lines, one line means one custom key. so that you can keep all SSE-C keys in the file — again, that's the SSE-C key history. the AWSSSECKEYS environment is the same as this file's contents. 💜
  • -o passwd_file (default="") — specify the path to the password file, which takes precedence over the password in $HOME/.passwd-s3fs and /etc/passwd-s3fs. it's the main character of password sources, basically. 👑
  • -o ahbe_conf (default="" which means disabled) — this option specifies the configuration file path, which file is the additional HTTP header by file (object) extension. the configuration file format is below:
line         = [file suffix or regex] HTTP-header [HTTP-values]
file suffix  = file (object) suffix, if this field is empty, it means "reg:(.*)".(=all object).
regex        = regular expression to match the file (object) path. this type starts with "reg:" prefix.
HTTP-header  = additional HTTP header name
HTTP-values  = additional HTTP header value

sample:

.gz                    Content-Encoding  gzip
.Z                     Content-Encoding  compress
reg:^/MYDIR/(.*)[.]t2$ Content-Encoding  text2

a sample configuration file is uploaded in the "test" directory. if you specify this option to set the "Content-Encoding" HTTP header, please take care for RFC 2616. 🎀

  • -o profile (default="default") — choose a profile from ${HOME}/.aws/credentials to authenticate against S3. note: this format matches the AWS CLI format and differs from the s3fs passwd format. don't mix them up, bestie, it's not the same language. 🗣️
  • -o public_bucket (default="" which means disabled) — anonymously mount a public bucket when set to 1. this ignores the $HOME/.passwd-s3fs and /etc/passwd-s3fs files. S3 does not allow copy object api for anonymous users, so s3fs sets the nocopyapi option automatically when the public_bucket=1 option is specified. automatic. seamless. slay. ✨
  • -o connect_timeout (default="300" seconds) — time to wait for connection before giving up. it waits. then it gives up. respect the timeline.
  • -o readwrite_timeout (default="120" seconds) — time to wait between read/write activity before giving up. same energy, different activity. 🦋
  • -o list_object_max_keys (default="1000") — specify the maximum number of keys returned by the S3 list object API. the default is 1000. you can set this value to 1000 or more.
  • -o max_stat_cache_size (default="100,000" entries (about 40MB)) — maximum number of entries in the stat cache and symbolic link cache. that's a lot of entries. it's a big cache. it's eating. 🍽️
  • -o stat_cache_expire (default is 900) — specify expire time (seconds) for entries in the stat cache and symbolic link cache. this expire time indicates the time since cached.
  • -o stat_cache_interval_expire (default is 900) — specify expire time (seconds) for entries in the stat cache and symbolic link cache. this expire time is based on the time from the last access time of those caches. this option is exclusive with stat_cache_expire, and is left for compatibility with older versions. old but not forgotten. 🕯️
  • -o enable_negative_cache (default is enabled negative cache) — this option will keep non-existence of objects in a stat cache. when this negative cache is enabled, it will not process extra HeadObject requests to search for non-existent objects, improving performance. this feature is enabled by default, so there is no need to specify it. it's already on, bestie, you're already living the dream. 😌
  • -o disable_negative_cache (default is enabled negative cache) — by default, s3fs keeps non-existent objects in the stat cache. this option disables this negative caching. this prevents delays in updates due to cache retention. however — and this is the tradeoff, listen — it may increase the number of HeadObject requests to check if an object exists, which may decrease performance. pick your struggle. 💀
  • -o no_check_certificate (by default this option is disabled) — server certificate won't be checked against the available certificate authorities. the certificate just... doesn't get checked. you've been warned, that's the whole warning. 🚨
  • -o ssl_verify_hostname (default="2") — when 0, do not verify the SSL certificate against the hostname.
  • -o ssl_client_cert (default="") — specify an SSL client certificate. specify this optional parameter in the following format:
"<SSL Cert>[:<Cert Type>[:<Private Key>[:<Key Type>
                                       [:<Password>]]]]"
<SSL Cert>: Client certificate.
            Specify the file path or NickName(for NSS, etc.).
<Cert Type>: Type of certificate, default is "PEM"(optional).
<Private Key>: Certificate's private key file(optional).
<Key Type>: Type of private key, default is "PEM"(optional).
<Password>: Passphrase of the private key(optional). It is also
possible to omit this value and specify it using the environment
variable "S3FS_SSL_PRIVKEY_PASSWORD".

okay so that's the setup, the auth, and the entire general + mount option lineup so far — and bestie, there is so much more where that came from. 🌈 keep scrolling, we're not even close to done. 🫶

  • -o nodnscache — okay so bestie, this disables the DNS cache. s3fs is always using DNS cache, and this option makes DNS cache disabled. periodt 💅
  • -o nosscache — this disables SSL session cache. s3fs is always using SSL session cache, and this option makes SSL session cache disabled. 🦋
  • -o multipart_size — default "10". Part size, in MB, for each multipart request. The minimum value is 5 MB and the maximum value is 5 GB. ✨
  • -o multipart_copy_size — default "512". Part size, in MB, for each multipart copy request, used for renames and mixupload. The minimum value is 5 MB and the maximum value is 5 GB. Must be at least 512 MB to copy the maximum 5 TB object size but lower values may improve performance. 👑
  • -o max_dirty_data — default "5120". Flush dirty data to S3 after a certain number of MB written. The minimum value is 50 MB. A -1 value means disable. Cannot be used with nomixupload. ⚠️
  • -o bucket_size — default is maximum long unsigned integer value. The size of the bucket with which the corresponding elements of the statvfs structure will be filled. The option argument is an integer optionally followed by a multiplicative suffix (GB, GiB, TB, TiB, PB, PiB, EB, EiB) (no spaces in between). If no suffix is supplied, bytes are assumed; eg: 20000000, 30GB, 45TiB. Note that s3fs does not compute the actual volume size (too expensive): by default it will assume the maximum possible size; however, since this may confuse other software which uses s3fs, the advertised bucket size can be set with this option. iconic 🌈
  • -o ensure_diskfree — default 0. Sets MB to ensure disk free space. This option means the threshold of free space size on disk which is used for the cache file by s3fs. s3fs makes file for downloading, uploading and caching files. If the disk free space is smaller than this value, s3fs do not use disk space as possible in exchange for the performance. 🛡️
  • -o free_space_ratio — default "10". Sets min free space ratio of the disk. The value of this option can be between 0 and 100. It will control the size of the cache according to this ratio to ensure that the idle ratio of the disk is greater than this value. For example, when the disk space is 50GB, the default value will ensure that the disk will reserve at least 50GB * 10%% = 5GB of remaining space. 🍓
  • -o multipart_threshold — default "25". Threshold, in MB, to use multipart upload instead of single-part. Must be at least 5 MB. 🔥
  • -o singlepart_copy_limit — default "512". Maximum size, in MB, of a single-part copy before trying multipart copy. 💅
  • -o host — default "https://s3.amazonaws.com". Set a non-Amazon host, e.g., https://example.com. 🌐
  • -o servicepath — default "/". Set a service path when the non-Amazon host requires a prefix. 🛤️
  • -o url — default "https://s3.amazonaws.com". Sets the url to use to access Amazon S3. If you want to use HTTP, then you can set "url=http://s3.amazonaws.com". If you do not use https, please specify the URL with the url option. 🔗
  • -o region — default "us-east-1". Sets the region to use on signature version 4. If this option is not specified, s3fs uses "us-east-1" region as the default. If the s3fs could not connect to the region specified by this option, s3fs could not run. But if you do not specify this option, and if you can not connect with the default region, s3fs will retry to automatically connect to the other region. So s3fs can know the correct region name, because s3fs can find it in an error from the S3 server. You can also specify the legacy -o endpoint which means the same thing. 🌍
  • -o sigv2 — default is signature version 4 falling back to version 2. Sets signing AWS requests by using only signature version 2. ✍️
  • -o sigv4 — default is signature version 4 falling back to version 2. Sets signing AWS requests by using only signature version 4. ✍️
  • -o mp_umask — default is "0000". Sets umask for the mount point directory. If allow_other option is not set, s3fs allows access to the mount point only to the owner. In the opposite case s3fs allows access to all users as the default. But if you set the allow_other with this option, you can control the permissions of the mount point by this option like umask. 🔐
  • -o umask — default is "0000". Sets umask for files under the mountpoint. This can allow users other than the mounting user to read and write to files that they did not create. 🔓
  • -o nomultipart — disable multipart uploads. 🚫
  • -o streamupload — default is disable. Enable stream upload. If this option is enabled, a sequential upload will be performed in parallel with the write from the part that has been written during a multipart upload. This is expected to give better performance than other upload functions. Note that this option is still experimental and may change in the future. ⚠️
  • -o max_thread_count — default is "10". This value is the maximum number of parallel requests to be sent, and the number of parallel processes for head requests, multipart uploads and stream uploads. Worker threads will be started to process requests according to this value. 🧵
  • -o enable_content_md5 — default is disable. Allow S3 server to check data integrity of uploads via the Content-MD5 header. This can add CPU overhead to transfers. 🧮
  • -o enable_unsigned_payload — default is disable. Do not calculate Content-SHA256 for PutObject and UploadPart payloads. This can reduce CPU overhead to transfers. 🧮
  • -o ecs — default is disable. This option instructs s3fs to query the ECS container credential metadata address instead of the instance metadata address. 🐳
  • -o iam_role — default is no IAM role. This option requires the IAM role name or "auto". If you specify "auto", s3fs will automatically use the IAM role names that are set to an instance. If you specify this option without any argument, it is the same as that you have specified the "auto". 👑
  • -o imdsv1only — default is to use IMDSv2 with fallback to v1. AWS instance metadata service, used with IAM role authentication, supports the use of an API token. If you're using an IAM role in an environment that does not support IMDSv2, setting this flag will skip retrieval and usage of the API token when retrieving IAM credentials. 🔑
  • -o ibm_iam_auth — default is not using IBM IAM authentication. This option instructs s3fs to use IBM IAM authentication. In this mode, the AWSAccessKey and AWSSecretKey will be used as IBM's Service-Instance-ID and APIKey, respectively. 💙
  • -o ibm_iam_endpoint — default is https://iam.cloud.ibm.com. Sets the URL to use for IBM IAM authentication. 💙
  • -o credlib — default= (empty). Specifies the shared library that handles the credentials containing the authentication token. If this option is specified, the specified credential and token processing provided by the shared library ant will be performed instead of the built-in credential processing. This option cannot be specified with passwd_file, profile, use_session_token, ecs, ibm_iam_auth, ibm_iam_endpoint, imdsv1only and iam_role option. 📚
  • -o credlib_opts — default= (empty). Specifies the options to pass when the shared library specified in credlib is loaded and then initialized. For the string specified in this option, specify the string defined by the shared library. 📚
  • -o use_xattr — default is not handling the extended attribute. Enable to handle the extended attribute (xattrs). If you set this option, you can use the extended attribute. For example, encfs and ecryptfs need to support the extended attribute. Notice: if s3fs handles the extended attribute, s3fs can not work to copy command with preserve=mode. 🏷️
  • -o noxmlns — disable registering xml name space. Disable registering xml name space for response of ListBucketResult and ListVersionsResult etc. Default name space is looked up from "http://s3.amazonaws.com/doc/2006-03-01". This option should not be specified now, because s3fs looks up xmlns automatically after v1.66. ⚠️
  • -o nomixupload — disable copy in multipart uploads. Disable to use PUT (copy api) when multipart uploading large size objects. By default, when doing multipart upload, the range of unchanged data will use PUT (copy api) whenever possible. When nocopyapi or norenameapi is specified, use of PUT (copy api) is invalidated even if this option is not specified. 🚫
  • -o nocopyapi — for other incomplete compatibility object storage. For a distributed object storage which is compatibility S3 API without PUT (copy api). If you set this option, s3fs do not use PUT with "x-amz-copy-source" (copy api). Because traffic is increased 2-3 times by this option, we do not recommend this. ⚠️
  • -o norenameapi — for other incomplete compatibility object storage. For a distributed object storage which is compatibility S3 API without PUT (copy api). This option is a subset of nocopyapi option. The nocopyapi option does not use copy-api for all command (ex. chmod, chown, touch, mv, etc), but this option does not use copy-api for only rename command (ex. mv). If this option is specified with nocopyapi, then s3fs ignores it. ⚠️
  • -o use_path_request_style — (use legacy API calling style). Enable compatibility with S3-like APIs which do not support the virtual-host request style, by using the older path request style. 🛤️
  • -o listobjectsv2 — (use ListObjectsV2). Issue ListObjectsV2 instead of ListObjects, useful on object stores without ListObjects support. 📋
  • -o noua — (suppress User-Agent header). Usually s3fs outputs of the User-Agent in "s3fs/<version> (commit hash <hash>; <using ssl library name>)" format. If this option is specified, s3fs suppresses the output of the User-Agent. 🙈
  • -o cipher_suites — Customize the list of TLS cipher suites. Expects a colon separated list of cipher suite names. A list of available cipher suites, depending on your TLS engine, can be found on the CURL library documentation: https://curl.haxx.se/docs/ssl-ciphers.html 🔐
  • -o instance_name — the instance name of the s3fs mountpoint you've got going right now ✨ This lil name gets tacked onto logging messages and the user agent headers s3fs sends out. Branding, but make it filesystem 💅
  • -o complement_stat (complement lack of file/directory mode) — so if a file or directory object is missing its x-amz-meta-mode header, this makes s3fs fill in the blanks about file/directory mode 🫶 By default s3fs does not complement stat info for an object, which means that object won't be able to be allowed to list/modify. Yeah. Default = sad object, no listing for you 😭
  • -o compat_dir (enable support of alternative directory names) — okay so by default s3fs speaks two different naming schemas to map directory names to S3 objects and back: "dir/" and "dir" 🌸 As a third variant, directories can be figured out indirectly if there's a file object with a path (like "/dir/file") but no parent directory. And this option unlocks a fourth variant, "dir_$folder$", which is what the old-school applications used to make 👑

Heads up tho: s3fs only ever uses the first schema, "dir/", to create S3 objects for directories.

Supporting all these naming schemas costs extra communication effort — more chatter, more work, no cap 📡

And here's the scenario where it saves you: if you don't have access permissions to the bucket and you specify a directory path created by a client that isn't s3fs as the mount point, you cannot start because s3fs can't find the mount point directory 💀 But specify this option and boom, error avoided ✨

  • -o use_wtf8 — support arbitrary file system encoding. S3 requires all object names to be valid UTF-8, periodt. But some clients — notably Windows NFS clients — use their own encoding 🙈 This option re-encodes invalid UTF-8 object names into valid UTF-8 by mapping the offending codes into a 'private' codepage of the Unicode set. Useful on clients that aren't using UTF-8 as their file system encoding 💜
  • -o use_session_token — indicate that a session token should be provided. If your credentials come from environment variables, this switch forces a presence check on the AWS_SESSION_TOKEN variable. Otherwise? An error gets returned, bestie 🚨
  • -o requester_pays (default is disable) — tells s3fs to enable requests involving Requester Pays buckets. It includes the 'x-amz-request-payer=requester' entry in the request header 🧾
  • -o mime (default is "/etc/mime.types") — specify the path of the mime.types file. If you don't set this option, s3fs checks whether "/etc/mime.types" exists and loads that file as the mime information. And if that file doesn't exist on macOS, then "/etc/apache2/mime.types" gets checked as well 🌈
  • -o proxy (default="") — specify a proxy to the S3 server 🛰️ Format it like '[<scheme://]hostname(fqdn)[:<port>]'. The ':<port>' part can also be omitted — and if you omit it, port 443 is used for HTTPS schema, and port 1080 is used otherwise. This option is the same as the curl command's '--proxy(-x)' option and libcurl's 'CURLOPT_PROXY' flag. It's equivalent to — and takes precedence over — the environment variables 'http_proxy', 'all_proxy', etc. 👑
  • -o proxy_cred_file (default="") — this one specifies the file that describes the username and passphrase for authenticating the proxy when the HTTP schema proxy is specified by the 'proxy' option 🔐 Username and passphrase are valid only for HTTP schema. If the HTTP proxy doesn't require authentication, you don't need this option at all. Separate the username and passphrase with a ':' character, and specify each as a URL-encoded string ✨
  • -o ipresolve (default="whatever") — choose what type of IP addresses get used when establishing a connection 🌐 The default ('whatever') can use addresses of all IP versions (IPv4 and IPv6) that your system allows. Specify 'IPv4' and only IPv4 addresses are used. Specify 'IPv6' and only IPv6 addresses will be used. Simple as that 💅
  • -o logfile — specify the log output file. s3fs outputs the log file to syslog 📝 Alternatively, if s3fs is started with the "-f" option specified, the log goes to stdout/stderr. This option lets you pick the log file s3fs writes to. And if you specify a log file with this option, it will reopen the log file when s3fs receives a SIGHUP signal — so you can use SIGHUP for log rotation 🎀
  • -o dbglevel (default="crit") — set the debug message level. Set the value as crit (critical), err (error), warn (warning), info (information) to debug level. Default debug level is critical. If s3fs runs with the "-d" option, the debug level is set to information. And when s3fs catches the signal SIGUSR2, the debug level gets bumped up 📈
  • -o curldbg — put curl debug message. This dumps the debug message from libcurl when specified 🐛 Give it "normal" or "body" for the parameter. Omit the parameter and it's the same as "normal". Specify "body" and some API communication body data will be output in addition to the debug message output you'd get as "normal" 🫧
  • -o no_time_stamp_msg — no time stamp in debug message. By default the time stamp is output to the debug message. Specify this option and the time stamp won't be output in the debug message anymore ⏰ It's the same even if the environment variable "S3FS_MSGTIMESTAMP" is set to "no".
  • -o set_check_cache_sigusr1 (default is stdout) — if the cache is enabled, you can check the integrity of the cache file and the cache file's stats info file 🔍 Specify this option, and when you send the SIGUSR1 signal to the s3fs process it checks the cache status at that time. This option can take a file path as a parameter to output the check result to that file 📄 The file path parameter can be omitted — if omitted, the result goes to stdout or syslog ✨
  • -o update_parent_dir_stat (default is disable) — the parent directory's mtime and ctime get updated when a file or directory is created or deleted (basically when the parent directory's inode is updated) 🌸 By default, parent directory statistics are not updated. Just so you know 💜

🛠️ utility mode options 🛠️

  • -u or --incomplete-mpu-list — lists multipart incomplete objects uploaded to the specified bucket 📋
  • --incomplete-mpu-abort all or date format (default="24H") — delete the multipart incomplete objects uploaded to the specified bucket 🗑️ If "all" is specified for this option, all multipart incomplete objects will be deleted. If you specify no argument as an option, objects older than 24 hours (24H) will be deleted (that's the default value). You can specify an optional date format — it can be given as year, month, day, hour, minute, second, expressed as "Y", "M", "D", "h", "m", "s" respectively. For example, "1Y6M10D12h30m30s" ⏳

🦋 FUSE/MOUNT OPTIONS 🦋

Most of the generic mount options described in 'man mount' are supported, bestie: ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync, async, dirsync 🎀

Filesystems are mounted with '-onodev,nosuid' by default, and that can only be overridden by a privileged user 👑 (so like, know your power level before you try it).

There are many FUSE specific mount options that can be specified — e.g. allow_other ✨ See the FUSE README for the full set 📚

🌐 SERVER URL/REQUEST STYLE 🌐

Be careful when specifying the server endpoint (URL). This is not a drill 💀

If your bucket name contains dots ("."), you should use the path request style (using the "use_path_request_style" option) 🔥

Also, if you're using a server other than Amazon S3, you need to specify the endpoint with the "url" option. And at that time, depending on the server you're using, you may have to specify the path request style ("use_path_request_style" option) 🛰️

💾 LOCAL STORAGE CONSUMPTION 💾

s3fs requires local caching for operation, fr fr. You can enable a local cache with "-o use_cache", or s3fs uses temporary files to cache pending requests to S3 📦

Apart from the requirements discussed below, it's recommended to keep enough cache resp. temporary storage to allow one copy each of all files open for reading and writing at any one time 👑

🌸 Local cache with "-o use_cache" 🌸

s3fs automatically maintains a local cache of files 💖 The cache folder is specified by the parameter of "-o use_cache". It's only a local cache — it can be deleted at any time, and s3fs will rebuild it if necessary. Iconic behaviour, honestly ✨

Whenever s3fs needs to read or write a file on S3, it first creates the file in the cache directory and operates on it 🫶

The amount of local cache storage used can be indirectly controlled with "-o ensure_diskfree" 🎀

🦋 Without local cache 🦋

Since s3fs always requires some storage space for operation, it creates temporary files to store incoming write requests until the required S3 request size is reached and the segment has been uploaded 📤 After that, this data is truncated in the temporary file to free up storage space 🧹

Per file you need at least twice the part size (default 5MB or "-o multipart_size") for writing multipart requests, or space for the whole file if single requests are enabled ("-o nomultipart") 💀

💖 PERFORMANCE CONSIDERATIONS 💖

okay bestie, this section is all about making s3fs go fast. zoom zoom. 🏎️✨

so like, in most cases the backend performance is literally not something you can control, so we're not even gonna talk about it here. not our problem, not our section. 💅

and if you wanna know the tea about local storage usage, that's over in "LOCAL STORAGE CONSUMPTION" — go check it out.

🔥 CPU and Memory Consumption 🔥

s3fs is a multi-threaded application, periodt. depending on the workload it might use up multiple CPUs and a whole bunch of memory. you can keep an eye on all of that CPU and memory consumption with the top utility. she's old, she's reliable, she's watching. 👀

✨ Performance of S3 requests ✨

s3fs ships with several options (like the max_thread_count option, for example) that control behaviour and therefore indirectly control performance. but here's the thing — the possible combos of these options together with all the different S3 backends are so varied that there's genuinely no individual recommendation other than just... the default values. if you want better settings that are tuned to you, you gotta test and measure. that's the vibe check. 📊

now, these two options — "Enable negative cache" (-o enable_negative_cache) and "Disable support of alternative directory names" (-o notsup_compat_dir) — can be used to control shared access to the same bucket by different applications. let's get into it:

  • Enable negative cache (-o enable_negative_cache) — if a bucket is used exclusively by one s3fs instance, you can turn on the cache for non-existent files and directories with -o enable_negative_cache. this kills the repeated requests that check whether an object exists, which saves you time and possibly money. ate. 💸
  • Enable support of alternative directory names (-o compat_dir) — s3fs recognizes dir/ objects as directories. but clients that aren't s3fs might use dir or dir_$folder$ objects as directories, or the directory objects might not exist at all. so for s3fs to recognize those as directories too, you can specify the compat_dir option.
  • Completion of file and directory information (-o complement_stat) — s3fs uses the x-amz-meta-mode header to figure out if an object is a file or a directory. which means objects that don't have that x-amz-meta-mode header may not give you the results you expect (like, the directory just won't display, etc. 😭). by specifying the complement_stat option, s3fs can automatically complete this missing attribute information, and then you get the expected results. slay.

🦋 NOTES 🦋

the maximum size of objects that s3fs can handle depends on Amazon S3, bestie. for example, up to 5 GB when using the single PUT API. and up to 5 TB is supported when the Multipart Upload API is used. big files, big energy. 💪

s3fs leverages /etc/mime.types to "guess" the "correct" content-type based on the file name extension. which means you can literally copy a website to S3 and serve it up directly from S3 with correct content-types! iconic behaviour, no cap. 🌈

👑 SEE ALSO 👑

fuse(8), mount(8), fusermount(1), fstab(5)

💀 BUGS 💀

okay so this one's important, listen up. due to S3's "eventual consistency" limitations, file creation can and will occasionally fail. and even after a successful create, subsequent reads can fail for an indeterminate time — even after one or more successful reads. create and read enough files and you will eventually encounter this failure. 😭

this is not a flaw in s3fs, and it's not something a FUSE wrapper like s3fs can work around. the retries option does not address this issue. nope. nada.

so your application has to either tolerate these failures or compensate for them — for example, by retrying creates or reads. that's on you, bestie. 🫶

🎀 AUTHOR 🎀

s3fs has been written by Randy Rizun <rrizun@gmail.com>. thank you for your service, king. 🫡💖

aaand that's a wrap on the whole page! 🎉 this edition is from the s3fs fam, version vibes dated December 2025, and it's the S3FS(1) manual page — now go mount something gorgeous. bye bestie! 💅✨🌸

📦 where this page comes from