This is sfs.info, produced by makeinfo version 4.2 from sfs.texi. START-INFO-DIR-ENTRY * SFS: (sfs). Self-certifying file system END-INFO-DIR-ENTRY This file documents SFS, the self-certifying file system. Copyright 1999-2002 David Mazie`res Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: sfs.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) SFS *** This file documents SFS, the self-certifying file system. This document applies to version 0.7.2 of the SFS distribution. * Menu: * Overview:: Introduction to SFS * Installation:: Building and installing the SFS software * Getting Started:: Play with SFS as quickly as possible * System overview:: High-level overview of SFS's components * SFS configuration:: SFS configuration files * Command reference:: Command usage reference guide * Security:: Security implications of running SFS * Contacts:: How to contact the authors, report bugs * Concept Index:: Index of concepts --- The Detailed Node Listing --- Installation * Requirements:: Requirements for building and running SFS * Building:: How to build and install the SFS distribution * Build Problems:: Common problems compiling the source Getting Started * Quick client setup:: How to set up an SFS client * Quick server setup:: How to set up an SFS server * Quick user setup:: How to get started as an SFS user SFS configuration files * `sfs_config':: System-wide configuration parameters * `sfsrwsd_config':: File server configuration * `sfsauthd_config':: User-authentication daemon configuration * `sfs_users':: User-authentication database * `sfssd_config':: Meta-server configuration * `sfs_srp_params':: Default parameters for SRP protocol * `sfscd_config':: Meta-client configuration Command reference guide * sfsagent:: Run by each user for authentication to servers * sfskey:: Controls the agent * rex:: Remote execution facility * dirsearch:: Search for file name in directories * newaid:: Run processes with different sfsagents * ssu:: Become root without changing sfsagents * sfscd:: Daemon run by root on all client machines * sfssd:: Daemon run by root on all server machines * vidb:: Manually edit user-authentication database * funmount:: Forcibly unmount file systems * sfsrwsd:: Daemon implementing read-write file server * sfsauthd:: User-authentication server Security considerations * new vulnerabilities:: Vulnerabilities created by SFS * exposed vulnerabilities:: Vulnerabilities exploitable because of SFS * implementation vulnerabilities:: Vulnerabilities in the SFS implementation  File: sfs.info, Node: Overview, Next: Installation, Prev: Top, Up: Top Introduction ************ SFS is a network file system that lets you access your files from anywhere and share them with anyone anywhere. SFS was designed with three goals in mind: * *Security.* SFS assumes that malicious parties entirely control the network. It ensures that control of the network only lets them delay the file system's operation or conceal the existence of servers until reliable network communication is reestablished. * *A global namespace.* SFS mounts all remote file systems under the directory `/sfs'. The contents of that directory is identical on every client in the world. Clients have no notion of administrative realm and no site-specific configuration options. Servers grant access to users, not to clients. Thus, users can access their files wherever they go, from any machine they trust that runs the SFS client software. * *Decentralized control.* SFS does not rely on any privileged authority to manage the global namespace. Anyone with a machine on the Internet can set up an SFS file server without needing to obtain any kind of certificates. New servers are instantly accessible from all clients in the world. SFS achieves these goals by separating key management from file system security. It names file systems by the equivalent of their public keys. Every remote file server is mounted under a directory of the form: /sfs/@LOCATION,HOSTID or: /sfs/@LOCATION%PORT,HOSTID LOCATION is a DNS hostname or an IP address. HOSTID is a collision-resistant cryptographic hash of the file server's public key. PORT is an optional TCP port number (the default is 4). This naming scheme lets an SFS client authenticate a server given only a file name, freeing the client from any reliance on external key management mechanisms. SFS calls the directories on which it mounts file servers "self-certifying pathnames". Self-certifying pathnames let users authenticate servers through a number of different techniques. As a secure, global file system, SFS itself provides a convenient key management infrastructure. Symbolic links let the file namespace double as a key certification namespace. Thus, users can realize many key management schemes using only standard file utilities. Moreover, self-certifying pathnames let people bootstrap one key management mechanism using another, making SFS far more versatile than any file system with built-in key management. Through a modular implementation, SFS also pushes user authentication out of the file system. Untrusted user processes transparently authenticate users to remote file servers as needed, using protocols opaque to the file system itself. Finally, SFS separates key revocation from key distribution. Thus, the flexibility SFS provides in key management in no way hinders recovery from compromised keys. No caffeine was used in the original production of the SFS software.  File: sfs.info, Node: Installation, Next: Getting Started, Prev: Overview, Up: Top Installation ************ This section describes how to build and install the SFS on your system. If you are too impatient to read the details, be aware of the two most important points: * You must create an `sfs' user and an `sfs' group on your system. *Note --with-sfsuser::, to use a name other than `sfs'. * You must use gcc version 2.95.2 or later to compile SFS. * Menu: * Requirements:: Requirements for building and running SFS * Building:: How to build and install the SFS distribution * Build Problems:: Common problems compiling the source  File: sfs.info, Node: Requirements, Next: Building, Prev: Installation, Up: Installation Requirements ============ SFS should run with minimal porting on any system that has solid NFS3 support. We have run SFS successfully on OpenBSD, FreeBSD, Linux, OSF/1 4.0, and Solaris 5.7. In order to compile SFS, you will need the following: 1. gcc-2.95.2 or more recent. You can obtain this from `ftp://ftp.gnu.org/pub/gnu/gcc'. Don't waste your time trying to compile SFS with an earlier version of gcc. 2. gmp-2.0.2 or more recent. You can obtain this from `ftp://ftp.gnu.org/pub/gnu/gmp'. Many operating systems already ship with gmp. Note, however, that some Linux distributions do not include the `gmp.h' header file. Even if you have libgmp.so, if you don't have /usr/include/gmp.h, you need to install gmp on your system. Note that more recent versions (4.0 and above) allow SFS to run significantly faster than it did with previous ones. 3. Header files in `/usr/include' that match the kernel you are running. Particularly on Linux where the kernel and user-land utilities are separately maintained, it is easy to patch the kernel without installing the correspondingly patched system header files in `/usr/include'. SFS needs to see the patched header files to compile properly. 4. 128 MB of RAM. The C++ compiler really needs a lot of memory. 5. 550 MB of free disk space to build SFS. (Note that on ELF targets, you may be able to get away with considerably less. A build tree on FreeBSD only consumes about 200 MB.)  File: sfs.info, Node: Building, Next: Build Problems, Prev: Requirements, Up: Installation Building SFS ============ Once you have setup your system as described in *Note Requirements::, you are ready to build SFS. 1. Create a user, SFS-USER, and group, SFS-GROUP, for SFS on your system. By default, SFS expects the both SFS-USER and SFS-GROUP to be called `sfs'. For instance, you might add the following line to `/etc/passwd': sfs:*:71:71:Self-certifying file system:/:/bin/true And the following line to `/etc/group': sfs:*:71: Do not put any users in SFS-GROUP, not even `root'. Any user in SFS-GROUP will not be able to make regular use of the SFS file system. Moreover, having any unprivileged users in SFS-GROUP causes a security hole. 2. Unpack the SFS sources. For instance, run the commands: % gzip -dc sfs-0.7.2.tar.gz | tar xvf - % cd sfs-0.7.2 If you determined that you need gmp (*note Requirements::), you should unpack gmp into the top-level of the SFS source tree: % gzip -dc ../gmp-2.0.2.tar.gz | tar xvf - 3. Set your `CC' and `CXX' environment variables to point to the C and C++ compilers you wish to use to compile SFS. Some operating systems do not come with a recent enough version of gcc *Note Requirements::. 4. Configure the sources for your system with the command `./configure'. You may additionally specify the following options: `--with-sfsuser=SFS-USER' If the user you created for SFS is not called `sfs'. Do not use an existing account for SFS-USER--even a trusted account--as processes running with that user ID will not be able to access SFS. [Note: If you later change your mind about USER-NAME, you do not need to recompile SFS, *Note sfs_config::.] `--with-sfsgroup=SFS-GROUP' If the user you created for SFS does not have the same name as SFS-USER. [Note: If you later change your mind about SFS-GROUP, you do not need to recompile SFS.] `--with-gmp=GMP-PATH' To specify where `configure' should look for gmp (for example, GMP-PATH might be `/usr/local'). Note, if you unpacked gmp into a subdirectory of the SFS source code, you do not need to specify this option. `configure' should notice the directory and compile gmp automatically. `--with-sfsdir=SFSDIR' To specify a location for SFS to put its working files. The default is `/var/sfs'. [You can change this later, *Note sfs_config::.] `--with-etcdir=ETCDIR' To specify where SFS should search for host-specific configuration files. The default is `/etc/sfs'. `--datadir=DATADIR' Where SFS places its data files. The default is `/usr/local/share'. `configure' accepts all the traditional GNU configuration options such as `--prefix'. It also has several options that are only for developers. *Do not use the `--enable-repo' or `--enable-shlib' options* (unless you are a gcc maintainer looking for some wicked test cases for your compiler). Also, *Do not use the `--with-openssl' option*-it is only for use by the developers in compiling some benchmark code that is not part of the release. 5. Build the sources by running `make'. Note that a GNU-comptabile `make' may be required to build SFS. 6. Install the binaries by running `make install'. If you are short on disk space, you can alternatively install stripped binaries by running `make install-strip'. 7. That's it. Fire up the client daemon by running `sfscd'.  File: sfs.info, Node: Build Problems, Prev: Building, Up: Installation Problems building SFS ===================== The most common problem you will encounter is an internal compiler error from gcc. If you are not running gcc-2.95.2 or later, you will very likely experience internal compiler errors when building SFS and need to upgrade the compiler. You must `make clean' after upgrading the compiler. You cannot link object files together if they have been created by different versions of the C++ compiler. On OSF/1 for the alpha, certain functions using a gcc extension called `__attribute__((noreturn))' tend to cause internal compiler errors. If you experience internal compiler errors when compiling SFS for the alpha, try building with the command `make ECXXFLAGS='-D__attribute__\(x\)='' instead of simply `make'. Sometimes, a particular source file will give particularly stubborn internal compiler errors on some architectures. These can be very hard to work around by just modifying the SFS source code. If you get an internal compiler error you cannot obviously fix, try compiling the particular source file with a different level of debugging. (For example, using a command like `make sfsagent.o CXXDEBUG=-g' in the appropriate subdirectory.) If your `/tmp' file system is too small, you may also end up running out of temporary disk space while compiling SFS. Set your `TMPDIR' environment variable to point to a directory on a file system with more free space (e.g., `/var/tmp'). You may need to increase your heap size for the compiler to work. If you use a csh-derived shell, run the command `unlimit datasize'. If you use a Bourne-like shell, run `ulimit -d `ulimit -H -d`'. On some operating systems, some versions of GMP do not install the library properly. If you get linker errors about symbols with names like `___gmp_default_allocate', try running the command `ranlib /usr/local/lib/libgmp.a' (substituting wherever your GMP library is installed for `/usr/local').  File: sfs.info, Node: Getting Started, Next: System overview, Prev: Installation, Up: Top Getting Started *************** This chapter gives a brief overview of how to set up an SFS client and server once you have compiled and installed the software. * Menu: * Quick client setup:: How to set up an SFS client * Quick server setup:: How to set up an SFS server * Quick user setup:: How to get started as an SFS user  File: sfs.info, Node: Quick client setup, Next: Quick server setup, Prev: Getting Started, Up: Getting Started Quick client setup ================== SFS clients require no configuration. Simply run the program `sfscd', and a directory `/sfs' should appear on your system. To test your client, access our SFS test server. Type the following commands: % cd /sfs/@sfs.fs.net,uzwadtctbjb3dg596waiyru8cx5kb4an % cat CONGRATULATIONS You have set up a working SFS client. % Note that the `/sfs/@sfs.fs.net,...' directory does not need to exist before you run the `cd' command. SFS transparently mounts new servers as you access them.  File: sfs.info, Node: Quick server setup, Next: Quick user setup, Prev: Quick client setup, Up: Getting Started Quick server setup ================== Setting up an SFS server is a slightly more complicated process. You must perform at least three steps: 1. Create a public/private key pair for your server. 2. Create an `/etc/sfs/sfsrwsd_config' configuration file. 3. Configure your machine as an NFS server and export all necessary directories to `localhost'. To create a public/private key pair for your server, run the commands: mkdir /etc/sfs sfskey gen -P /etc/sfs/sfs_host_key Then you must create an `/etc/sfs/sfsrwsd_config' file based on which local directories you wish to export and what names those directories should have on clients. This information takes the form of one or more `Export' directives in the configuration file. Each export directive is a line of the form: Export LOCAL-DIRECTORY SFS-NAME LOCAL-DIRECTORY is the name of a local directory on your system you wish to export. SFS-NAME is the name you wish that directory to have in SFS, relative to the previous `Export' directives. The SFS-NAME of the first `Export' directive must be `/'. Subsequent SFS-NAMEs must correspond to pathnames that already exist in the previously exported directories. Suppose, for instance, that you wish to export two directories, `/disk/u1' and `/disk/u2' as `/usr1' and `/usr2', respectively. You should create a directory to be the root of the exported namespace, say `/var/sfs/root', create the necessary SFS-NAME subdirectories, and create a corresponding `sfsrwsd_config' file. You might run the following commands to do this: % mkdir /var/sfs/root % mkdir /var/sfs/root/usr1 % mkdir /var/sfs/root/usr2 and create the following `sfsrwsd_config' file: Export /var/sfs/root / Export /disk/u1 /usr1 Export /disk/u2 /usr2 Finally, you must export all the LOCAL-DIRECTORYs in your `sfsrwsd_config' to `localhost' via NFS version 3. The details of doing this depend heavily on your operating system. For instance, in OpenBSD you must add the following lines to the file `/etc/exports' and run the command `kill -HUP `cat /var/run/mountd.pid`': /var/sfs/root localhost /disk/u1 localhost /disk/u2 localhost On Linux, the syntax for the exports file is: /var/sfs/root localhost(rw) /disk/u1 localhost(rw) /disk/u2 localhost(rw) On Solaris, add the following lines to the file `/etc/dfs/dfstab' and run `exportfs -a': share -F nfs -o -rw=localhost /var/sfs/root share -F nfs -o -rw=localhost /disk/u1 share -F nfs -o -rw=localhost /disk/u2 In general, the procedure for exporting NFS file systems varies greatly between operating systems. Check your operating system's NFS documentation for details. (The manual page for `mountd' is a good place to start.) Once you have generated a host key, created an `sfsrwsd_config' file, and reconfigured your NFS server, you can start the SFS server by running `sfssd'. Note that a lot can go wrong in setting up an SFS server. Thus, we recommend that you first run `sfssd -d'. The `-d' switch will leave `sfssd' in the foreground and send error messages to your terminal. If there are problems, you can then easily kill `sfssd' from your terminal, fix the problems, and start again. Once things are working, omit the `-d' flag; `sfssd' will run in the background and send its output to the system log. Note: *You will not be able to access an SFS server running on the same machine as the client* unless you run `sfscd' with the `-l' flag, *Note sfscd::. Attempts to SFS mount a machine on itself will return the error `EDEADLK' (Resource deadlock avoided).  File: sfs.info, Node: Quick user setup, Prev: Quick server setup, Up: Getting Started Getting started as an SFS user ============================== To access an SFS server, you must first register a public key with the server, then run the program `sfsagent' on your SFS client to authenticate you. To register a public key, log into the file server and run the command: sfskey register This should produce something similar to the following output: % sfskey register sfskey: /home/user/.sfs/random_seed: No such file or directory sfskey: creating directory /home/user/.sfs sfskey: creating directory /home/user/.sfs/authkeys Creating new key: user@server.com#1 (Rabin) Key Label: user@server.com#1 Press to accept the default key label. You will then see: Enter passphrase: Again: sfskey needs secret bits with which to seed the random number generator. Please type some random or unguessable text until you hear a beep: 64 At this point, type 64 random characters to seed the random number generator, until you hear a bell. You will then be prompted for your UNIX password. If all goes well you should see a message line: UNIX password: wrote key: /home/user/.sfs/authkeys/user@server.com#1 % The above procedure creates a public/private key pair for you and registers it with the server. (Note that if you already have a public key on another server, you can reuse that public key by giving `sfskey' your address at that server, e.g., `sfskey register user@other.server.com'.) After registering your public key with an SFS server, you can use the `sfskey login' command to access the server. Get a shell on a different client machine from the server, and run the command: sfskey login USR@SERVER SERVER is the name of the server on which you registered, and USER is your logname on that server. You should be prompted for a password, and see something like the following: Passphrase for dm@server.com/1024: SFS Login as dm@server.com The `sfskey login' command does three things: It starts the `sfsagent' program, which persists in the background to authenticate you to file servers as needed. It fetches your private key from SERVER and decrypts it using your passphrase. Finally, it fetches the server's public key, and creates a symbolic link from `/sfs/SERVER' to `/sfs/@SERVER,HOSTID'. (The passphrase you type is also used to authenticate the server to the client, so that `sfskey' can fetch the server's public key securely.) If, after your agent is already running, you wish to fetch a private key from another server or download another server's public key, you can run `sfskey login' multiple times. You will be able to access all the servers you have logged into simultaneously. While `sfskey' provides a convenient way of authenticating oneself to servers and obtaining their self-certifying pathnames, it is by no means the only way. If you use the same public key on all servers, you will only need to type your password once to download your private key; `sfsagent' will automatically authenticate you to whatever file servers you touch. Moreover, once you have access to one SFS file server, you can store on it symbolic links pointing to other servers' self-certifying pathnames. When you are done using SFS, you should run the command sfskey kill before logging out. This will kill your `sfsagent' process running in the background and get rid of the private keys it was holding for you in memory.  File: sfs.info, Node: System overview, Next: SFS configuration, Prev: Getting Started, Up: Top System overview *************** sfskey--+---------------- - - - -----------+ | | agent--+ | agent------+ | | | +---------------+ +-------------+ | sfscd |-------- - - - --------| sfssd | | | | | | | | sfsrwcd-+ | | +-sfsrwsd--+-+ | nfsmounter-+ | | +-sfsauthd | | +---------------+ +-------------+ | | V +--------+ | +--------+ | kernel | | | kernel | | NFS3 |<-----+ | NFS3 | | client | | server | +--------+ +--------+ CLIENT SERVER SFS consists of a number interacting programs on both the client and the server side. On the client side, SFS implements a file system by pretending to be an NFS server and talking to the local operating system's NFS3 client. The program `sfscd' gets run by root (typically at boot time). `sfscd' spawns two other daemons--`nfsmounter' and `sfsrwcd'. `nfsmounter' handles the mounting and unmounting of NFS file systems. In the event that `sfscd' dies, `nfsmounter' takes over being the NFS server to prevent file system operations from blocking as it tries to unmount all file systems. *Never send `nfsmounter' a `SIGKILL' signal (i.e., `kill -9').* `nfsmounter''s main purpose is to clean up the mess if any other part of the SFS client software fails. Whatever bad situation SFS has gotten your machine into, killing `nfsmounter' will likely only make matters worse. `sfsrwcd' implements the ordinary read-write file system protocol. As other dialects of the SFS protocol become available, they will be implemented as daemons running alongside `sfsrwcd'. Each user of an SFS client machine must run an instance of the `sfsagent' command. `sfsagent' serves several purposes. It handles user authentication as the user touches new file systems. It can fetch HOSTIDs on the fly, a mechanism called "Dynamic server authentication". Finally, it can perform revocation checks on the HOSTIDs of servers the user accesses, to ensure the user does not access HOSTIDs corresponding to compromised private keys. The `sfskey' utility manages both user and server keys. It lets users control and configure their agents. Users can hand new private keys to their agents using `sfskey', list keys the agent holds, and delete keys. `sfskey' will fetch keys from remote servers using SRP, *Note SRP::. It lets users change their public keys on remote servers. Finally, `sfskey' can configure the agent for dynamic server authentication and revocation checking. On the server side, the program `sfssd' spawns two subsidiary daemons, `sfsrwsd' and `sfsauthd'. If virtual hosts or multiple versions of the software are running, `sfssd' may spawn multiple instances of each daemon. `sfssd' listens for TCP connections on port 4. It then hands each connection off to one of the subsidiary daemons, depending on the self-certifying pathname and service requested by the client. `sfsrwsd' is the server-side counterpart to `sfsrwcd'. It communicates with client side `sfsrwcd' processes using the SFS file system protocol, and accesses the local disk by acting as a client of the local operating system's NFS server. `sfsrwsd' is the one program in sfs that _must be configured_ before you run it, *Note sfsrwsd_config::. `sfsauthd' handles user authentication. It communicates directly with `sfsrwsd' to authenticate users of the file system. It also accepts connections over the network from `sfskey' to let users download their private keys or change their public keys.  File: sfs.info, Node: SFS configuration, Next: Command reference, Prev: System overview, Up: Top SFS configuration files *********************** SFS comprises a number of programs, many of which have configuration files. All programs look for configuration files in two directories--first `/etc/sfs', then, if they don't find the file there, in `/usr/local/share/sfs'. You can change these locations using the `--with-etcdir' and `--datadir' options to the `configure' command, *Note configure::. The SFS software distribution installs reasonable defaults in `/usr/local/share/sfs' for all configuration files except `sfsrwsd_config'. On particular hosts where you wish to change the default behavior, you can override the default configuration file by creating a new file of the same name in `/etc/sfs'. The `sfs_config' file contains system-wide configuration parameters for most of the programs comprising SFS. Note that `/usr/local/share/sfs/sfs_config' is always parsed, even if `/etc/sfs/sfs_config' exists. Options in `/etc/sfs/sfs_config' simply override the defaults in `/usr/local/share/sfs/sfs_config'. For all other configuration files, a file in `/etc/sfs' entirely overrides the version in ``PKGDATADIR''. If you are running a server, you will need to create an `sfsrwsd_config' file to tell SFS what directories to export, and possibly an `sfsauthd_config' if you wish to share the database of user public keys across several file servers. The `sfssd_config' file contains information about which protocols and services to route to which daemons on an SFS server, including support for backwards compatibility across several versions of SFS. You probably don't need to change this file. `sfs_srp_params' contains some cryptographic parameters for retrieving keys securely over the network with a passphrase (as with the `sfskey add USR@SERVER' command). `sfscd_config' Contains information about extensions to the SFS protocol and which kinds of file servers to route to which daemons. You almost certainly should not touch this file unless you are developing new versions of the SFS software. Note that configuration command names are case-insensitive in all configuration files (though the arguments are not). * Menu: * `sfs_config':: System-wide configuration parameters * `sfsrwsd_config':: File server configuration * `sfsauthd_config':: User-authentication daemon configuration * `sfs_users':: User-authentication database * `sfssd_config':: Meta-server configuration * `sfs_srp_params':: Default parameters for SRP protocol * `sfscd_config':: Meta-client configuration  File: sfs.info, Node: `sfs_config', Next: `sfsrwsd_config', Prev: SFS configuration, Up: SFS configuration `sfs_config'--system-wide configuration parameters ================================================== The `sfs_config' file lets you set the following system-wide parameters: `sfsdir DIRECTORY' The directory in which SFS stores its working files. The default is `/var/sfs', unless you changed this with the `--with-sfsdir' option to `configure'. `sfsuser SFS-USER [SFS-GROUP]' As described in *Note Building::, SFS needs its own user and group to run. This configuration directive lets you set the user and group IDs SFS should use. By default, SFS-USER is `sfs' and SFS-GROUP is the same as SFS-USER. The `sfsuser' directive lets you supply either a user and group name, or numeric IDs to change the default. Note: *If you change SFS-GROUP, you must make sure the the program `/usr/local/lib/sfs-0.7.2/suidconnect' is setgid to the new SFS-GROUP.* `anonuser {USER | UID GID}' Specifies an unprivileged user id to be used for anonymous file access. If specified as USER, the name USER will be looked up in the password file, and the login group of that user used as the group id. Can alternatively be specified as a numeric UID and GID. The default is to use -1 for both the UID and GID, though the default `sfs_config' file specifies the user name nobody. `ResvGids LOW-GID HIGH-GID' SFS lets users run multiple instances of the `sfsagent' program. However, it needs to modify processes' group lists so as to know which file system requests correspond to which agents. The `ResvGids' directive gives SFS a range of group IDs it can use to tag processes corresponding to a particular agent. (Typically, a range of 16 gids should be plenty.) Note that the range is inclusive--both LOW-GID and HIGH-GID are considered reserved gids. The setuid root program `newaid' lets users take on any of these group IDs, *Note newaid::. Thus, make sure these groups are not used for anything else, or you will create a security hole. There is no default for `ResvGids'. Note that after changing `ResvGids', you must kill and restart `sfscd' for things to work properly. `RSASize BITS' Sets the default size of public keys for cryptosystems that are based on the diffculty of factoring integers. The Rabin public keys used in self-certifying pathnames are affected by this paremeter. The default value of BITS is 1280. `DlogSize BITS' Sets the default size of public keys for cryptosystems that are based on the diffculty of taking discrete logs in subgroups of *Z*_p_*. This parameter affects SRP paremeter and 2-Schnorr key generation. The default value of BITS is 1024. `PwdCost COST' Sets the computational cost of processing a user-chosen password. SFS uses passwords to encrypt users' private keys. Unfortunately, users tend to choose poor passwords. As computers get faster, guessing passwords gets easier. By increasing the COST parameter, you can maintain the cost of guessing passwords as hardware improves. The change will apply to new keys, and to old keys after people run `sfskey edit'. The default value is 11. COST is an exponential parameter. Thus, you probably don't want anything too much larger. The maximum value is 32--at which point password hashing will not terminate in any tractable amount of time and the `sfskey' command will be unusable. `LogPriority FACILITY.LEVEL' Sets the syslog facility and level at which SFS should log activity. The default is `daemon.notice'.  File: sfs.info, Node: `sfsrwsd_config', Next: `sfsauthd_config', Prev: `sfs_config', Up: SFS configuration `sfsrwsd_config'--File server configuration =========================================== `Hostname NAME' Set the LOCATION part of the server's self-certifying pathname. The default is the current host's fully-qualified hostname. `Keyfile PATH' Tells `sfsrwsd' to look for its private key in file PATH. The default is `sfs_host_key'. SFS looks for file names that do not start with `/' in `/etc/sfs', or whatever directory you specified if you used the `--with-etcdir' option to `configure' (*note configure::). `Export LOCAL-DIRECTORY SFS-NAME [R|W]' Tells `sfsrwsd' to export LOCAL-DIRECTORY, giving it the name SFS-NAME with respect to the server's self-certifying pathname. Appending `R' to an export directive gives anonymous users read-only access to the file system (under user ID -2 and group ID -2). Appending `W' gives anonymous users both read and write access. *Note Quick server setup::, for an example of the `Export' directive. There is almost no reason to use the `W' flag. The `R' flag lets anyone on the Internet issue NFS calls to your kernel as user -2. SFS filters these calls; it makes sure that they operate on files covered by the export directive, and it blocks any calls that would modify the file system. This approach is safe given a perfect NFS3 implementation. If, however, there are bugs in your NFS code, attackers may exploit them if you have the `R' option--probably just crashing your server but possibly doing worse. `LeaseTime SECONDS'  File: sfs.info, Node: `sfsauthd_config', Next: `sfs_users', Prev: `sfsrwsd_config', Up: SFS configuration `sfsauthd_config'--User-authentication daemon configuration =========================================================== `Hostname NAME' Set the LOCATION part of the server's self-certifying pathname. The default is the current host's fully-qualified hostname. `Keyfile PATH' Tells `sfsrwsd' to look for its private key in file PATH. The default is `sfs_host_key'. SFS looks for file names that do not start with `/' in `/etc/sfs', or whatever directory you specified if you used the `--with-etcdir' option to `configure' (*note configure::). `Userfile [-update] [-create] [-passwd] [-admin] [-prefix=PREFIX] [-uid=UID | -uidmap=U1-U2+U3] [-gid=GID | -gidmap=G1-G2+G3] [-pub=PUBPATH] PATH' This specifies a file in which `sfsauthd' should look for user public keys when authenticating users. You can specify multiple `Userfile' directives to use multiple files. This can be useful in an environment where most user accounts are centrally maintained, but a particular server has a few locally-maintained guest (or root) accounts. Userfile has the following options: `-update' Specifies a user database as updatable. Users can register new public keys, update their public keys, and change their server key information on writable databases. If this command is not given, the database is assumed to read-only and possibly on a remote machine. Thus, `sfsauthd' maintains local copies of read-only databases in `/var/sfs/authdb'. This process ensures that temporarily unavailable file servers never disrupt `sfsauthd''s operation. `-create' Create an empty `sfs_users' file if no such file exists. `-passwd' Treat the Unix passwd file (`/etc/passwd' on most machines) as part of this userfile. Use password, shell and home directory information. Allows users who do not exist in the database to log into `sfsauthd' with their UNIX password, so that they might register an SFS key (note this allso requires the `-update' flag). *Note sfskey register::, for details on this. Also important for proper functioning of `rexd'. `-admin' Allow an SFS administrator to make changes to user records that have the admin flag set in their `privs' field. `-prefix=PREFIX' Prepend the prefix PREFIX to usernames in the given userfile. `-uid=UID' `-uidmap=U1-U2+U3' These options are mutually exclusive. The first maps every user's credentials in the given file to the given UID, UID. The second maps users in the UID range (U1 to U2) to the offset U3. For example, if you wanted to map users to 1000-2520 to 61000-62520, you would supply -uidmap=1000-2520+60000. `-gid=GID' `-gidmap=G1-G2+G3' See above. Functions the same as `gid' and `gidmap', but applies to group IDs, rather than user IDs. Again, these options are mutually exclusive. `-pub=PUBPATH' `sfsauthd' supports the secure remote password protocol, or SRP. SRP lets users connect securely to `sfsauthd' with their passwords, without needing to remember the server's public key. To prove its identity through SRP, the server must store secret data derived from a user's password. The file PATH specified in `Userfile' contains these secrets for users opting to use SRP. The `-pub' option tells `sfsauthd' to maintain in PUBPATH a separate copy of the database without secret information. PUBPATH might reside on an anonymously readable SFS file system--other machines can then import the file as a read-only database using a `Userfile' line with the `-update' flag. If no `Userfile' directive is specified, `sfsauthd' uses the following default (again, unqualified names are assumed to be in `/etc/sfs'): Userfile -update -passwd -pub=sfs_users.pub sfs_users `Logfile PATH' Use the logfile given by PATH to output the signature log generated by `sfsauthd'. The default logfile is `/var/sfs/sign_log'. `SRPfile PATH' Where to find default parameters for the SRP protocol. Generate such a file using the "sfskey gensrp" command. The default is `sfs_srp_params'. If the default file does not exist, serving pre-generated SRP parameters is disabled. `Denyfile PATH' Specify a file containing a list of users that are to be explicitly denied the ability to register and update keys on the authserver. The default is `sfs_deny'. If the default file does not exist, we assume an empty list. `Realm NAME' Define the realm to which this authserver will belong. Authentication information (including SRP) can be shared amongst authservers that are in the same realm. Thus, a user that wants to authenticate to a realm, can contact any authserver in that realm. If the realm directive does NOT appear in this file, the authserver will not join any realm. This behavior is the default. If the realm directive does appear, NAME cannot be empty. NOTE: Changing an authserver's realm after users have already registered using SRP requires all users to update their authentication data because the realm is bound into the stored SRP information. Specifically, each user will need to run sfskey update -r username@authserver A user logged on to the authserver can use the hostname - to signify the local host: sfskey update -r - `Certpath DIR [DIR ...]' Specify a certification path to return to the client as a result of an "sfskey login" command; this list of directories will become the arguments to a dirsearch certprog. That is, for a certpath "DIR1 DIR2" the client will add a certprog "dirsearch DIR1 DIR2" to the user's agent. The certification path will be tagged with a prefix equal to the authserver's realm (see above). NOTE: The certpath directive only makes sense if the authserver is part of a realm. The certpath will be ignored if the realm directive isn't specified. There are three ways to specify a certpath directory: certpath //dir1 /dir2 @sfs.host.domain,HOSTID/dir2 which can also be written certpath //dir1 certpath /dir2 certpath @sfs.host.domain,HOSTID/dir2 A directory starting with two slashes ("//") is considered relative to the client machine's root ("/"). A directory starting with one slash ("/") is relative to the authserver's self-certifying pathname (the authserver performs the substitution before is sends the dir). The third form is a fully specified directory on SFS. The default certpath is empty.  File: sfs.info, Node: `sfs_users', Next: `sfssd_config', Prev: `sfsauthd_config', Up: SFS configuration `sfs_users'--User-authentication database ========================================= The `sfs_users' file, maintained and used by the `sfsauthd' program, maps public keys to local users and groups. It is roughly analogous to the Unix `/etc/passwd' file. Each line of `sfs_users' has the following format (split into two lines here only for clarity of presentation): [USER|GROUP]:USER:UID:VERSION:GID:OWNER:PUBKEY:PRIVS :SRP:PRIVKEY:SRVPRIVKEY:AUDIT USER USER is the unique name of a public key in the database. Ordinarily it is the same as a username in the local password file. However, in certain cases it may be useful to map multiple public keys to the same local account (for instance if several people have an account with root privileges). In such cases, each key should be given a unique name (e.g., `dm/root', `kaminsky/root', etc.). UID UID is the user's user ID on the given server. VERSION VERSION is the version number of this record in the users database. Upon registration, this value is set to 1. Upon every subsequent update, this value is incremented by 1. GID GID is the users's group ID on the given server. OWNER This field is ignored as of SFS 0.7. PUBKEY PUBKEY is an ASCII, human-readable representation of the user's public key. Can be either a Rabin or 2-Schnorr public key as of SFS 0.7. PRIVS The PRIVS field indicates whether a field can be updated by the SFS admin--given of course that a Userfile is included with the `-admin' option. SRP SRP is the server-side information for the SRP protocol, *Note SRP::. Unlike the previous fields, this information must be kept secret. If the information is disclosed, an attacker may be able to impersonate the server by causing the `sfskey add' command to fetch the wrong HOSTID. Note also that SRP-INFO is specific to a particular hostname. If you change the LOCATION of a file server, users will need to register new SRP-INFO. PRIVKEY PRIVKEY is actually opaque to `sfsauthd'. It is private, per-user data that `sfsauthd' will return to users who successfully complete the SRP protocol. Currently, `sfskey' users this field to store an encrypted copy of a user's private key, allowing the user to retrieve the private key over the network. SRVPRIVKEY If a user has chosen 2-Schnorr proactive signatures, the server's half of the private key is kept in this field. AUDIT AUDIT contains the time, source IP address, and description of the last update to this field. Useful in recovering from a compromised key. Note if you edit `sfs_users' files by hand, you risk overwriting concurrent updates by `sfsauthd'. Use the `vidb' *note vidb:: command to lock `sfs_users' files while you edit them.  File: sfs.info, Node: `sfssd_config', Next: `sfs_srp_params', Prev: `sfs_users', Up: SFS configuration `sfssd_config'--Meta-server configuration ========================================= `sfssd_config' configures `sfssd', the server that accepts connections for `sfsrwsd' and `sfsauthd'. `sfssd_config' can be used to run multiple "virtual servers", or to run several versions of the server software for compatibility with old clients. Directives are: `BindAddr IP-ADDR [PORT]' Specifies the IP address and port on which `sfssd' should listen for TCP connections. The default is `INADDR_ANY' for the address and port 4. `RevocationDir PATH' Specifies the directory in which `sfssd' should search for revocation/redirection certificates when clients connect to unknown (potentially revoked) self-certifying pathnames. The default value is `/var/sfs/srvrevoke'. Use the command `sfskey revokegen' to generate revocation certificates. `HashCost BITS' Specifies that clients must pay for connections by burning CPU time. This can help reduce the effectiveness of denial-of-service attacks. The default value is 0. The maximum value is 22. `Server {* | @LOCATION[,HOSTID]}' Specifies a section of the file that applies connection requests for the self-certifying pathname @LOCATION`,'HOSTID. If `,'HOSTID is omitted, then the following lines apply to any connection that does not match an explicit HOSTID in another `Server'. The argument `*' applies to all clients who do not have a better match for either LOCATION or HOSTID. `Release {* | SFS-VERSION}' Begins a section of the file that applies to clients running SFS release SFS-VERSION or older. `*' signifies arbitrarily large SFS release numbers. The `Release' directive does not do anything on its own, but applies to all subsequent `Service' directives until the next `Release' or `Server' directive. `Extensions EXT1 [EXT2 ...]' Specifies that subsequent `Service' directives apply only to clients that supply all of the listed extension strings (EXT1, ...). `Extensions' applies until the next `Extensions', `Release' or `Server' directive `Service SRVNO DAEMON [ARG ...]' Specifies the daemon that should handle clients seeking service number SRVNO. SFS defines the following values of SRVNO: 1. File server 2. Authentication server 3. Remote execution 4. SFS/HTTP (not yet released) `Service SRVNO -u PATH' Operates as the above syntax of `Service', only instead of spawning a daemon, connects to the unix-domain socket specified by `path' to communicate with an already running daemon. This option may be useful when debugging SFS servers, as the server for a particular service on a particular self-certifying pathname can be run under the debugger and receive connections on the usual SFS port without interfering with other servers on the same machine. `Service SRVNO -t HOST [PORT]' Specifies that `sfssd' should act as a "TCP proxy" for this particular service, relaying any incoming connections to TCP port PORT on HOST. If unspecified, PORT is the default SFS TCP port 4. This syntax is useful in a NATted environment. For instance, suppose you have two SFS servers with addresses 10.0.0.2 and 10.0.0.3 on a private network, and one machine 10.0.0.1 with an externally visible interface 4.3.2.1. You can use this proxy syntax to export the internal file systems. The easiest way is to pick two DNS names for the new servers, but point them at your outside server. For example: server-a.mydomain.com. IN A 4.3.2.1 server-b.mydomain.com. IN A 4.3.2.1 Then, on your outside machine, you might have the following `sfssd_config' file: Server server-a.mydomain.com Release * Service 1 -t 10.0.0.2 Service 2 -t 10.0.0.2 Service 3 -t 10.0.0.2 Server server-b.mydomain.com Release * Service 1 -t 10.0.0.3 Service 2 -t 10.0.0.3 Service 3 -t 10.0.0.3 Then on each of the internal machines, be sure to specify `Hostname server-A.mydomain.com' and `Hostname server-B.mydomain.com' in `sfsrwsd_config'. The default contents of `sfssd_config' is: Server * Release * Service 1 sfsrwsd Service 2 sfsauthd Service 3 rexd To disable the file server, you can copy this file to `/etc/sfs/sfssd_config' and comment out the line `Service 1 sfsrwsd'. To disable the remote login server, comment out the line for `rexd'. To run a different server for sfs-0.6 and older clients, you could add the lines: Release 0.6 Service 1 /usr/local/lib/sfs-0.6/sfsrwsd