octoleo/s3fs-fuse
1
0
Fork 0
mirror of https://github.com/s3fs-fuse/s3fs-fuse.git synced 2024-09-27 16:59:01 +00:00
Code Issues Packages Projects Releases Wiki Activity
be38de5052
s3fs-fuse/doc/man/s3fs.1

114 lines
5.3 KiB
Groff
Raw Normal View History

Committing Ben's man page with some minor fixes and edits. Made sure to include it in the distribution tarball. git-svn-id: http://s3fs.googlecode.com/svn/trunk@313 df820570-a93a-0410-bd06-b72b767a4274
2011-02-11 20:57:44 +00:00
.TH S3FS "1" "February 2011" "S3FS" "User Commands"
.SH NAME
S3FS \- FUSE-based file system backed by Amazon S3
.SH SYNOPSIS
.SS mounting
.TP
Support for mounting a remote directory (issue #7). - fixed a bug in the file cache, it was attempting to set the mtime on symlinks - general code cleanup; moved some string functions to string_util.cpp git-svn-id: http://s3fs.googlecode.com/svn/trunk@345 df820570-a93a-0410-bd06-b72b767a4274
2011-06-26 00:37:52 +00:00
\fBs3fs bucket[:path] mountpoint \fP [options]
Committing Ben's man page with some minor fixes and edits. Made sure to include it in the distribution tarball. git-svn-id: http://s3fs.googlecode.com/svn/trunk@313 df820570-a93a-0410-bd06-b72b767a4274
2011-02-11 20:57:44 +00:00
.SS unmounting
.TP
\fBumount mountpoint
.SH DESCRIPTION
s3fs is a FUSE filesystem that allows you to mount an Amazon S3 bucket as a local filesystem. It stores files natively and transparently in S3 (i.e., you can use other programs to access the same files).
.SH AUTHENTICATION
The s3fs password file has this format (use this format if you have only one set of credentials):
.RS 4
\fBaccessKeyId\fP:\fBsecretAccessKey\fP
.RE
If you have more than one set of credentials, this syntax is also recognized:
.RS 4
\fBbucketName\fP:\fBaccessKeyId\fP:\fBsecretAccessKey\fP
.RE
.PP
Password files can be stored in two locations:
.RS 4
\fB/etc/passwd-s3fs\fP [0600]
\fB$HOME/.passwd-s3fs\fP [0640]
.RE
.SH OPTIONS
.SS "general options"
.TP
\fB\-h\fR \fB\-\-help\fR
print help
.TP
\fB\ \fR \fB\-\-version\fR
print version
.TP
\fB\-f\fR
FUSE foreground option - do not run as daemon.
.TP
\fB\-s\fR
FUSE singlethreaded option (disables multi-threaded operation)
.SS "mount options"
.TP
All s3fs options must given in the form where "opt" is:
<option_name>=<option_value>
.TP
\fB\-o\fR default_acl (default="private")
the default canned acl to apply to all written S3 objects, e.g., "public-read".
Any created files will have this canned acl.
Any updated files will also have this canned acl applied!
.TP
\fB\-o\fR prefix (default="") (coming soon!)
a prefix to append to all S3 objects.
.TP
\fB\-o\fR retries (default="2")
number of times to retry a failed S3 transaction.
.TP
\fB\-o\fR use_cache (default="" which means disabled)
local folder to use for local file cache.
.TP
\fB\-o\fR use_rrs (default="" which means disabled)
use Amazon's Reduced Redundancy Storage.
.TP
\fB\-o\fR passwd_file (default="")
specify the path to the password file, which which takes precedence over the password in $HOME/.passwd-s3fs and /etc/passwd-s3fs
.TP
\fB\-o\fR public_bucket (default="" which means disabled)
anonymously mount a public bucket when set to 1, ignores the $HOME/.passwd-s3fs and /etc/passwd-s3fs files.
.TP
\fB\-o\fR connect_timeout (default="10" seconds)
time to wait for connection before giving up.
.TP
Implemented max_stat_cache_size as an option Resolves issue #157 git-svn-id: http://s3fs.googlecode.com/svn/trunk@316 df820570-a93a-0410-bd06-b72b767a4274
2011-02-12 16:48:23 +00:00
\fB\-o\fR readwrite_timeout (default="30" seconds)
Committing Ben's man page with some minor fixes and edits. Made sure to include it in the distribution tarball. git-svn-id: http://s3fs.googlecode.com/svn/trunk@313 df820570-a93a-0410-bd06-b72b767a4274
2011-02-11 20:57:44 +00:00
time to wait between read/write activity before giving up.
.TP
Implemented max_stat_cache_size as an option Resolves issue #157 git-svn-id: http://s3fs.googlecode.com/svn/trunk@316 df820570-a93a-0410-bd06-b72b767a4274
2011-02-12 16:48:23 +00:00
\fB\-o\fR max_stat_cache_size (default="10000" entries (about 4MB))
maximum number of entries in the stat cache
.TP
Summary of Changes(1.62 -> 1.63) 1) Lifetime for the stats cache Added the new option "stat_cache_expire". This option which is specified by seconds means the lifetime for each stats cache entry. If this option is not specified, the stats cache is kept in s3fs process until the stats cache grown to maximum size. (default) If this option is specified, the stats cache entry is out from the memory when the entry expires time. 2) Enable file permission s3fs before 1.62 did not consider the file access permission. s3fs after this version can consider it. For access permission, the s3fs_getattr() function was divided into sub function which can check the file access permission. It is like access() function. And the function calling the s3fs_getattr() calls this new sub function instead of s3fs_getattr(). Last the s3fs_opendir() function which is called by FUSE was added for checking directory access permission when listing the files in directory. 3) UID/GUID When a file or a directory was created, the s3fs could not set the UID/GID as the user who executed a command. (Almost the UID/GID are root, because the s3fs run by root.) After this version, the s3fs set correct UID/GID as the user who executes the commond. 4) About the mtime If the object does not have "x-amz-meta-mtime" meta, the s3fs uses the "Last-Modified" header instead of it. But the s3fs had a bug in this code, and this version fixed this bug. When user modified the file, the s3fs did not update the mtime of the file. This version fixed this bug. In the get_local_fd() function, the local file's mtime was changed only when s3fs run with "use_cache" option. This version always updates the mtime whether the local cache file is used or not. And s3fs_flush ( ) function set the mtime of local cache file from S3 object mtime, but it was wrong . This version is that the s3fs_flush ( ) changes the mtime of S3 object from the local cache file or the tmpfile . The s3fs cuts some requests, because the s3fs can always check mtime whether the s3fs uses or does not use the local cache file. 5) A case of no "x-amz-meta-mode" If the object did not have "x-amz-meta-mtime" mete, the s3fs recognized the file as not regular file. After this version, the s3fs recognizes the file as regular file. 6) "." and ".." directory The s3fs_readdir() did not return "X" and "XX" directory name. After this version, the s3fs is changed that it returns "X" and "XX". Example, the result of "ls" lists "X" and "XX" directory. 7) Fixed a bug The insert_object() had a bug, and it is fixed. git-svn-id: http://s3fs.googlecode.com/svn/trunk@390 df820570-a93a-0410-bd06-b72b767a4274
2013-02-24 08:58:54 +00:00
\fB\-o\fR stat_cache_expire (default is no expire)
specify expire time(seconds) for entries in the stat cache
.TP
Committing Ben's man page with some minor fixes and edits. Made sure to include it in the distribution tarball. git-svn-id: http://s3fs.googlecode.com/svn/trunk@313 df820570-a93a-0410-bd06-b72b767a4274
2011-02-11 20:57:44 +00:00
\fB\-o\fR url (default="http://s3.amazonaws.com")
sets the url to use to access Amazon S3. If you want to use HTTPS, then you can set url=https://s3.amazonaws.com
Ability to disable multipart uploads - Added 'nomultipart' option to disable multipart uploads - see issue #181 git-svn-id: http://s3fs.googlecode.com/svn/trunk@347 df820570-a93a-0410-bd06-b72b767a4274
2011-06-27 02:21:38 +00:00
.TP
\fB\-o\fR nomultipart - disable multipart uploads
1) Fixed a memory leak and un-closed file discriptor. 2) Added a static table for file discriptors and paths which is keeped until closing. The s3fs_xxxx function called by FUSE is able to use a file disctiptor which is already opened by s3fs_open function. 3) The mknod is changed that it always return error, because it does not work through a network. 4) The symbolic file attribute changed to S_IFLNK | S_IRWXU | S_IRWXG | S_IRWXO. 5) Fixed the truncate function to work. 6) The mkdir and clone_directory_object functions are simplified and are changed to use the common create_directory_object function for these. For fixed a bug that the directory's PID/UID/mode are changed when these are renamed. 7) The get_object_name function is changed to check a object finely. 8) The s3fs_check_service function is changed for "301" response code. 9) Added the noxmlns option for a case of the response without xmlns field. (for the storage compatible with S3) 10) Added the nocopyapi option for the storage compatible with S3 without copy API. * Comments No.9 and No.10 are for the storage compatible with AWS S3. Both option are unnecessary options for AWS S3. In future, for the s3fs's promotion and possibility I would like to add new function. git-svn-id: http://s3fs.googlecode.com/svn/trunk@384 df820570-a93a-0410-bd06-b72b767a4274
2013-01-19 16:05:07 +00:00
.TP
\fB\-o\fR noxmlns - disable registing xml name space.
disable registing 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".
.TP
\fB\-o\fR 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.
Committing Ben's man page with some minor fixes and edits. Made sure to include it in the distribution tarball. git-svn-id: http://s3fs.googlecode.com/svn/trunk@313 df820570-a93a-0410-bd06-b72b767a4274
2011-02-11 20:57:44 +00:00
.SH FUSE/MOUNT OPTIONS
.TP
Most of the generic mount options described in 'man mount' are supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime, noatime, sync async, dirsync). Filesystems are mounted with '-onodev,nosuid' by default, which can only be overridden by a privileged user.
.TP
There are many FUSE specific mount options that can be specified. e.g. allow_other. See the FUSE README for the full set.
.SH NOTES
.TP
Maximum file size=64GB (limited by s3fs, not Amazon).
.TP
If enabled via the "use_cache" option, s3fs automatically maintains a local cache of files in the folder specified by use_cache. Whenever s3fs needs to read or write a file on S3, it first downloads the entire file locally to the folder specified by use_cache and operates on it. When fuse_release() is called, s3fs will re-upload the file to S3 if it has been changed. s3fs uses md5 checksums to minimize downloads from S3.
.TP
The folder specified by use_cache is just a local cache. It can be deleted at any time. s3fs rebuilds it on demand.
.TP
Local file caching works by calculating and comparing md5 checksums (ETag HTTP header).
.TP
s3fs leverages /etc/mime.types to "guess" the "correct" content-type based on file name extension. This means that you can copy a website to S3 and serve it up directly from S3 with correct content-types!
.SH BUGS
Due to S3's "eventual consistency" limitations, file creation can and will occasionally fail. 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 is not something a FUSE wrapper like s3fs can work around. The retries option does not address this issue. Your application must either tolerate or compensate for these failures, for example by retrying creates or reads.
.SH AUTHOR
s3fs has been written by Randy Rizun <rrizun@gmail.com>.
Reference in New Issue Copy Permalink