FUSE-based file system backed by Amazon S3
Go to file
Noah Meyerhans f2f930300a Implement AWS IMDSv2 support
AWS IMDSv2 is a session oriented method for retrieving instance metadata,
including IAM credentials, in Amazon EC2.  It is enabled by default in
non-enforcing mode in AWS (meaning it retains backwards compatibility with
existing IMDSv1 clients), but can be switched to enforcing mode, in which
clients are required to return API tokens with requests.

With this change, we implement support for IMDSv2 and enable it by default when
IAM roles are our source for authentication credentials.  In the event that
s3fs is running in cloud environment offering an IMDSv1-compatible API, we
support graceful fallback to that mode.  It can also be selected explicitly via
the imdsv1only mount option.

More details on IMDSv2 are available at
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html
and
https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/

Signed-off-by: Noah Meyerhans <nmeyerha@amazon.com>
2020-11-07 14:48:52 +09:00
.github Replace all mentions to MacOS X to macOS 2018-10-14 23:23:19 +02:00
doc Added logfile option for non-syslog logging 2020-10-19 20:10:19 +09:00
src Implement AWS IMDSv2 support 2020-11-07 14:48:52 +09:00
test Merge pull request #1440 from gaul/test/undefined-behavior-sanitizer 2020-10-04 23:19:36 +09:00
.clang-tidy Update source for clang-tidy 9.0.0 2020-01-13 20:56:45 +09:00
.gitattributes Added a missing extension to .gitignore, and formatted dot files 2019-01-20 09:18:40 +00:00
.gitignore Added a missing extension to .gitignore, and formatted dot files 2019-01-20 09:18:40 +00:00
.mailmap Add .mailmap 2015-04-27 11:17:39 -07:00
.travis.yml Disable builder for linux-ppc64le 2020-09-25 23:25:36 +09:00
AUTHORS Updated ChangeLog and configure.ac etc for release 1.85 2019-03-11 11:53:57 +00:00
autogen.sh Source file division and set 4 spaces and cleanup 2020-08-26 17:43:50 +09:00
ChangeLog Update ChangeLog and configure.ac for 1.87 2020-08-10 11:52:14 +09:00
COMPILATION.md Added mime option for strict checking of mime types file 2020-03-30 14:41:18 +00:00
configure.ac Remove exceptions from s3fs_strtoofft 2020-10-02 22:53:12 +09:00
COPYING In preparation to remove the unnecessary "s3fs" 2010-11-13 23:59:23 +00:00
INSTALL Replace all mentions to MacOS X to macOS 2018-10-14 23:23:19 +02:00
Makefile.am Source file division and set 4 spaces and cleanup 2020-08-26 17:43:50 +09:00
README.md Update README.md for migrating travis-ci.com 2020-09-21 18:59:45 +09:00

s3fs

s3fs allows Linux and macOS to mount an S3 bucket via FUSE. s3fs preserves the native object format for files, allowing use of other tools like AWS CLI. Build Status Twitter Follow

Features

  • large subset of POSIX including reading/writing files, directories, symlinks, mode, uid/gid, and extended attributes
  • compatible with Amazon S3, and other S3-based object stores
  • allows random writes and appends
  • large files via multi-part upload
  • renames via server-side copy
  • optional server-side encryption
  • data integrity via MD5 hashes
  • in-memory metadata caching
  • local disk data caching
  • user-specified regions, including Amazon GovCloud
  • authenticate via v2 or v4 signatures

Installation

Many systems provide pre-built packages:

  • Amazon Linux via EPEL:

    sudo amazon-linux-extras install epel
    sudo yum install s3fs-fuse
    
  • Arch Linux:

    sudo pacman -S s3fs-fuse
    
  • Debian 9 and Ubuntu 16.04 or newer:

    sudo apt install s3fs
    
  • Fedora 27 or newer:

    sudo dnf install s3fs-fuse
    
  • Gentoo:

    sudo emerge net-fs/s3fs
    
  • RHEL and CentOS 7 or newer through via EPEL:

    sudo yum install epel-release
    sudo yum install s3fs-fuse
    
  • SUSE 12 and openSUSE 42.1 or newer:

    sudo zypper install s3fs
    
  • macOS via Homebrew:

    brew cask install osxfuse
    brew install s3fs
    

Otherwise consult the compilation instructions.

Examples

s3fs supports the standard AWS credentials file stored in ${HOME}/.aws/credentials. Alternatively, s3fs supports a custom passwd file.

The default location for the s3fs password file can be created:

  • using a .passwd-s3fs file in the users home directory (i.e. ${HOME}/.passwd-s3fs)
  • using the system-wide /etc/passwd-s3fs file

Enter your credentials in a file ${HOME}/.passwd-s3fs and set owner-only permissions:

echo ACCESS_KEY_ID:SECRET_ACCESS_KEY > ${HOME}/.passwd-s3fs
chmod 600 ${HOME}/.passwd-s3fs

Run s3fs with an existing bucket mybucket and directory /path/to/mountpoint:

s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs

If you encounter any errors, enable debug output:

s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs -o dbglevel=info -f -o curldbg

You can also mount on boot by entering the following line to /etc/fstab:

mybucket /path/to/mountpoint fuse.s3fs _netdev,allow_other 0 0

or

mybucket /path/to/mountpoint fuse.s3fs _netdev,allow_other 0 0

If you use s3fs with a non-Amazon S3 implementation, specify the URL and path-style requests:

s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs -o url=https://url.to.s3/ -o use_path_request_style

or(fstab)

mybucket /path/to/mountpoint fuse.s3fs _netdev,allow_other,use_path_request_style,url=https://url.to.s3/ 0 0

Note: You may also want to create the global credential file first

echo ACCESS_KEY_ID:SECRET_ACCESS_KEY > /etc/passwd-s3fs
chmod 600 /etc/passwd-s3fs

Note2: You may also need to make sure netfs service is start on boot

Limitations

Generally S3 cannot offer the same performance or semantics as a local file system. More specifically:

  • random writes or appends to files require rewriting the entire object, optimized with multi-part upload copy
  • metadata operations such as listing directories have poor performance due to network latency
  • eventual consistency can temporarily yield stale data(Amazon S3 Data Consistency Model)
  • no atomic renames of files or directories
  • no coordination between multiple clients mounting the same bucket
  • no hard links
  • inotify detects only local modifications, not external ones by other clients or tools

References

  • goofys - similar to s3fs but has better performance and less POSIX compatibility
  • s3backer - mount an S3 bucket as a single file
  • S3Proxy - combine with s3fs to mount Backblaze B2, EMC Atmos, Microsoft Azure, and OpenStack Swift buckets
  • s3ql - similar to s3fs but uses its own object format
  • YAS3FS - similar to s3fs but uses SNS to allow multiple clients to mount a bucket

Frequently Asked Questions

License

Copyright (C) 2010 Randy Rizun rrizun@gmail.com

Licensed under the GNU GPL version 2