From 8349db5c277d24f51ad5ed69098601307ae89ffe Mon Sep 17 00:00:00 2001 From: braga Date: Thu, 13 Apr 2006 20:16:26 +0000 Subject: [PATCH] Add manpage documentation. --- Makefile.am | 2 +- configure.ac | 2 +- doc/Makefile.am | 2 + doc/curlftpfs.1 | 321 ++++++++++++++++++++++++++++++++++++++++++++++++ ftpfs.c | 75 +++++------ 5 files changed, 363 insertions(+), 39 deletions(-) create mode 100644 doc/Makefile.am create mode 100644 doc/curlftpfs.1 diff --git a/Makefile.am b/Makefile.am index f839db3..2f6d26e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,5 @@ ## Process this file with automake to produce Makefile.in -SUBDIRS = compat +SUBDIRS = compat doc DIST_SUBDIRS = $(SUBDIRS) tests diff --git a/configure.ac b/configure.ac index 1345511..57acea7 100644 --- a/configure.ac +++ b/configure.ac @@ -24,5 +24,5 @@ if test "$have_fuse_opt_parse" = no; then fi AM_CONDITIONAL(FUSE_OPT_COMPAT, test "$have_fuse_opt_parse" = no) -AC_CONFIG_FILES([Makefile compat/Makefile tests/Makefile]) +AC_CONFIG_FILES([Makefile compat/Makefile tests/Makefile doc/Makefile]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..093e1a5 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,2 @@ +man_MANS = curlftpfs.1 +EXTRA_DIST = $(man_MANS) diff --git a/doc/curlftpfs.1 b/doc/curlftpfs.1 new file mode 100644 index 0000000..aee475e --- /dev/null +++ b/doc/curlftpfs.1 @@ -0,0 +1,321 @@ +.TH curlftpfs 1 "12 Apr 2006" "CurlFtpFS 0.6.1" "CurlFtpFS Manual" +.SH NAME +curlftpfs \- mount a ftp host as a local directory +.SH SYNOPSIS +.B curlftpfs [options] +.I host path +.SH DESCRIPTION +The program +.B curlftpfs +is a tool to mount remote ftp hosts as local directories. It connects to the +.I host +FTP server and maps its directory structure to the +.I path +directory. + +curlftpfs is powered by libcurl for all transfer-related features. See +.BR libcurl (3) +for details. The filesystem part is implemented on top of FUSE. +See +.BR http://fuse.sourceforge.net/ +for details. +.SH FTP OPTIONS +.TP +.B "-h/--help" +Print help options. +.TP +.B "-v/--verbose" +Make libcurl print verbose debug output. +.TP +.B "-V/--version" +Print curlftpfs, libcurl and fuse versions. +.TP +.B \-o +Options are specified with a +.B \-o +flag followed by a comma separated string of options. +.RS +.TP +.B cacert= +(SSL) Pass a string naming a file holding +one or more certificates to verify the peer with. + +Note that option is by default set to the system path where +libcurl's cacert bundle is assumed to be stored, as established +at build time. +.TP +.B capath= +(SSL) Tells curlftpfs to use the specified certificate directory to verify the +peer. The certificates must be in PEM format, and the directory must have been +processed using the c_rehash utility supplied with openssl. Using +\fBcapath\fP can allow curlftpfs to make connections much more +efficiently than using \fBcacert\fP if the \fBcacert\fP file contains many CA +certificates. +.TP +.B cert= +(SSL) Tells curlftpfs to use the specified certificate file. The default format +is "PEM" and can be changed with \fBcert_type\fP. +.TP +.B cert_type= +(SSL) Tells curlftpfs what certificate type the provided certificate is in. +PEM, DER and ENG are recognized types. +.TP +.B ciphers= +(SSL) Specifies which ciphers to use in the connection. The list must be +syntactically correct, it consists of one or more cipher strings separated by +colons. Commas or spaces +are also acceptable separators but colons are normally used, , - and + can +be used as operators. Valid examples of cipher lists include 'RC4-SHA', +\'SHA1+DES', 'TLSv1' and 'DEFAULT'. The default list is normally +set when you compile OpenSSL. + +Read up on SSL cipher list details +on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP +.TP +.B connect_timeout= +Maximum time in seconds that you allow the connection to the server to take. +This only limits the connection phase, once curlftpfs has connected this option +is of no more use. +.TP +.B disable_eprt +Tell curlftpfs to disable the use of the EPRT and LPRT commands when doing +active FTP transfers. Curlftpfs will normally always first attempt to use EPRT, +then LPRT before using PORT, but with this option, it will use PORT right +away. EPRT and LPRT are extensions to the original FTP protocol, may not work +on all servers but enable more functionality in a better way than the +traditional PORT command. +.TP +.B disable_epsv +Tell curlftpfs to disable the use of the EPSV command when doing passive FTP +transfers. Curlftpfs will normally always first attempt to use EPSV before +PASV, but with this option, it will not try using EPSV. +.TP +.B engine= +Select the OpenSSL crypto engine to use for cipher operations. Use: +.br +.B "curl \-\-engine list" +.br +to print a list of build-time supported engines. Note that not +all (or none) of the engines may be available at run-time. +.TP +.B ftpfs_debug +Make curlftpfs print lots of debug information. Useful only in conjuntion with +the +.B \-d +option. +.TP +.B ftp_port=
+Reverses the initiator/listener roles when connecting with ftp. This +switch makes curlftpfs use the PORT command instead of PASV. In practice, PORT +tells the server to connect to the client's specified address and port, while +PASV asks the server for an ip address and port to connect to.
+should be one of: +.RS +.IP interface +i.e "eth0" to specify which interface's IP address you want to use +.IP "IP address" +i.e "192.168.10.1" to specify exact IP number +.IP "host name" +i.e "my.host.domain" to specify machine +.IP "-" +make curlftpfs pick the same IP address that is already used for the control +connection +.RE + +Disable the +attempt to use the EPRT command instead of PORT by using \fIdisable_eprt\fP. +EPRT is really PORT++. +.TP +.B interface= +Pass a string as parameter. This set the interface name to use as outgoing +network interface. The name can be an interface name, an IP address or a +host name. +.TP +.B ipv4 +If libcurl is capable of resolving an address to multiple IP versions +(which it is if it is ipv6-capable), this option tells libcurl to resolve +names to IPv4 addresses only. +.TP +.B ipv6 +If libcurl is capable of resolving an address to multiple IP versions +(which it is if it is ipv6-capable), this option tells libcurl to resolve +names to IPv6 addresses only. +.TP +.B key= +(SSL) Private key file name. Allows you to provide your private key in this +separate file. The default format is "PEM" and can be changed with +\fBkey_type\fP. +.TP +.B key_type= +(SSL) Pass a string in +the format of your private key. Supported formats are "PEM", "DER" and +"ENG". + +The format "ENG" enables you to load the private key from a crypto engine. +In this case \fBkey\fP is used as an identifier passed to the engine. +You have to set the crypto engine with \fBengine\fP option. "DER" format key +file currently does not work because of a bug in OpenSSL. +.TP +.B krb4= +Enable kerberos4 authentication and use. The level must be entered and should +be one of 'clear', 'safe', 'confidential' or 'private'. Should you use a +level that is not one of these, 'private' will instead be used. + +This option requires that the libcurl library was built with kerberos4 +support. This is not very common. +.TP +.B no_verify_hostname +(SSL) Curlftpfs will not verify the hostname when connecting to a SSL enabled +server. +.TP +.B pass= +(SSL) Pass phrase for the private key. +.TP +.B proxy= +Use specified HTTP proxy. If the port number is not specified, it is assumed +at port 1080. + +This option overrides existing environment variables that sets +proxy to use. If there's an environment variable setting a proxy, you can +set proxy to "" to override it. + +This options implies the \fBproxytunnel\fP option. + +Starting with libcurl version 7.14.1, the proxy host can be specified the +exact same way as the proxy environment variables, including protocol prefix +(http://) and embedded user + password. +.TP +.B proxytunnel +Tells curlftpfs to use a tunnel proxy. This option is implied by the +\fBproxy\fP option but you need to set it manually if you use the \fIproxy\fP +environment variable. +.TP +.B proxy_anyauth +Tells curl to pick a suitable authentication method when communicating with +the given proxy. This will cause an extra request/response round-trip. +.TP +.B proxy_basic +Tells curlftpfs to use HTTP Basic authentication when communicating with the +given proxy. Basic is the default authentication method curlftpfs is used with +proxies. +.TP +.B proxy_digest +Tells curlftpfs to use HTTP Digest authentication when communicating with the +given proxy. +.TP +.B proxy_ntlm +Tells curlftpfs to use HTTP NTLM authentication when communicating with the +given proxy. +.TP +.B proxy_user= +Specify user and password to use for proxy authentication. +.TP +.B skip_pasv_ip +Tell curlftpfs to not use the IP address the server suggests in its response +to curlftpfs's PASV command when curlftpfs connects the data connection. +Instead curlftpfs will re-use the same IP address it already uses for the +control connection. +.TP +.B ssl +Make curlftpfs use SSL/TLS for both control and data connections. +.TP +.B sslv3 +Forces curlftpfs to use SSL version 3 when negotiating with a remote SSL +server. +.TP +.B ssl_control +Make curlftpfs use SSL/TLS only for the control connection. +.TP +.B ssl_try +Curlftpfs will try to use SSL/TLS for both the control and data connections +but if the server doesn't support it, it will still connect unencrypted. +.TP +.B tcp_nodelay +Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for +details about this option. +.TP +.B tlsv1 +(SSL) Forces curlftpfs to use TSL version 1 when negotiating with a remote TLS +server. +.TP +.B transform_symlinks +Append +.I path +to the absolute symlinks so that they still point inside the ftp directory +structure. Otherwise those links will very probably be broken. +.TP +.B user= +Specify user and password to use for server authentication. Overrides +netrc configuration. +.SH FUSE OPTIONS +.TP +.B "-d" +Enable FUSE debug output. Implies \fB-f\fP. +.TP +.B "-f" +Run curlftpfs in foreground mode. +.TP +.B "-r" +Mount read-only. +.TP +.B "-s" +Disable multi-threaded operation. +.TP +.B \-o +Options are specified with a +.B \-o +flag followed by a comma separated string of options. +.RS +.TP +.B allow_other +Allow access to other users. By default the mount point is only accessible to +the user that mounted it and not even to root. +.TP +.B allow_root +Allow access to root user. By default the mount point is only accessible to +the user that mounted it and not even to root. +.TP +.B debug +enable debug output +.TP +.B direct_io +use direct I/O +.TP +.B fsname=NAME +set filesystem name in mtab +.TP +.B gid=N +set file group +.TP +.B hard_remove +immediate removal (don't hide files) +.TP +.B kernel_cache +Let the kernel VFS do some caching of the files. +.TP +.B large_read +issue large read requests (2.4 only) +.TP +.B max_read=N +set maximum size of read requests +.TP +.B nonempty +allow mounts over non-empty file/dir +.TP +.B readdir_ino +try to fill in d_ino in readdir +.TP +.B uid=N +set file owner +.TP +.B umask=M +set file permissions (octal) +.TP +.B use_ino +let filesystem set inode numbers +.SH AUTHORS +Robson Braga Araujo is the author and maintainer of CurlFtpFS. +.SH WWW +http://curlftpfs.sourceforge.net +.SH "SEE ALSO" +.BR mount (8) diff --git a/ftpfs.c b/ftpfs.c index c4f8baf..563104e 100644 --- a/ftpfs.c +++ b/ftpfs.c @@ -796,47 +796,48 @@ static void usage(const char* progname) { fprintf(stderr, "usage: %s \n" "\n" -" -o opt,[opt...] mount options\n" +"CurlFtpFS options:\n" +" -o opt,[opt...] ftp options\n" " -v --verbose make libcurl print verbose debug\n" " -h --help print help\n" " -V --version print version\n" "\n" -"FTPFS options:\n" -" -o ftpfs_debug print some debugging information\n" -" -o transform_symlinks prepend mountpoint to absolute symlink targets\n" -" -o disable_epsv use PASV, without trying EPSV first\n" -" -o skip_pasv_ip skip the IP address for PASV\n" -" -o ftp_port=STR use PORT with address instead of PASV\n" -" -o disable_eprt use PORT, without trying EPRT first\n" -" -o tcp_nodelay use the TCP_NODELAY option\n" -" -o connect_timeout=N maximum time allowed for connection in seconds\n" -" -o ssl enable SSL/TLS for both control and data connections\n" -" -o ssl_control enable SSL/TLS only for control connection\n" -" -o ssl_try try SSL/TLS first but connect anyway\n" -" -o no_verify_hostname does not verify the hostname (SSL)\n" -" -o cert=STR client certificate file and password (SSL)\n" -" -o cert_type=STR certificate file type (DER/PEM/ENG) (SSL)\n" -" -o key=STR private key file name (SSL)\n" -" -o key_type=STR private key file type (DER/PEM/ENG) (SSL)\n" -" -o pass=STR pass phrase for the private key (SSL)\n" -" -o engine=STR crypto engine to use (SSL)\n" -" -o cacert=STR file with CA certificates to verify the peer (SSL)\n" -" -o capath=STR CA directory to verify peer against (SSL)\n" -" -o ciphers=STR SSL ciphers to use (SSL)\n" -" -o interface=STR specify network interface/address to use\n" -" -o krb4=STR enable krb4 with specified security level\n" -" -o proxy=STR use host:port HTTP proxy\n" -" -o proxytunnel operate through a HTTP proxy tunnel (using CONNECT)\n" -" -o proxy_anyauth pick \"any\" proxy authentication method\n" -" -o proxy_basic use Basic authentication on the proxy\n" -" -o proxy_digest use Digest authentication on the proxy\n" -" -o proxy_ntlm use NTLM authentication on the proxy\n" -" -o user=STR set server user and password\n" -" -o proxy_user=STR set proxy user and password\n" -" -o tlsv1 use TLSv1 (SSL)\n" -" -o sslv3 use SSLv3 (SSL)\n" -" -o ipv4 resolve name to IPv4 address\n" -" -o ipv6 resolve name to IPv6 address\n" +"FTP options:\n" +" ftpfs_debug print some debugging information\n" +" transform_symlinks prepend mountpoint to absolute symlink targets\n" +" disable_epsv use PASV, without trying EPSV first\n" +" skip_pasv_ip skip the IP address for PASV\n" +" ftp_port=STR use PORT with address instead of PASV\n" +" disable_eprt use PORT, without trying EPRT first\n" +" tcp_nodelay use the TCP_NODELAY option\n" +" connect_timeout=N maximum time allowed for connection in seconds\n" +" ssl enable SSL/TLS for both control and data connections\n" +" ssl_control enable SSL/TLS only for control connection\n" +" ssl_try try SSL/TLS first but connect anyway\n" +" no_verify_hostname does not verify the hostname (SSL)\n" +" cert=STR client certificate file (SSL)\n" +" cert_type=STR certificate file type (DER/PEM/ENG) (SSL)\n" +" key=STR private key file name (SSL)\n" +" key_type=STR private key file type (DER/PEM/ENG) (SSL)\n" +" pass=STR pass phrase for the private key (SSL)\n" +" engine=STR crypto engine to use (SSL)\n" +" cacert=STR file with CA certificates to verify the peer (SSL)\n" +" capath=STR CA directory to verify peer against (SSL)\n" +" ciphers=STR SSL ciphers to use (SSL)\n" +" interface=STR specify network interface/address to use\n" +" krb4=STR enable krb4 with specified security level\n" +" proxy=STR use host:port HTTP proxy\n" +" proxytunnel operate through a HTTP proxy tunnel (using CONNECT)\n" +" proxy_anyauth pick \"any\" proxy authentication method\n" +" proxy_basic use Basic authentication on the proxy\n" +" proxy_digest use Digest authentication on the proxy\n" +" proxy_ntlm use NTLM authentication on the proxy\n" +" user=STR set server user and password\n" +" proxy_user=STR set proxy user and password\n" +" tlsv1 use TLSv1 (SSL)\n" +" sslv3 use SSLv3 (SSL)\n" +" ipv4 resolve name to IPv4 address\n" +" ipv6 resolve name to IPv6 address\n" "\n", progname); }