head	1.102;
access;
symbols
	tame-0-4:1.101.0.2
	SFS_O_7_2:1.70
	SFS_O_7_1:1.69
	SFS_0_7:1.64
	AUTHSERV1:1.46.0.2
	PUBKEY2:1.44.0.2
	SFS_0_6:1.44
	EXTAUTH:1.43.0.2
	mp-async-bp:1.37
	mp-async:1.37.0.2
	SFS_0_5:1.20
	SFS_0_4:1.11;
locks; strict;
comment	@# @;


1.102
date	2006.05.30.00.00.19;	author dm;	state Exp;
branches;
next	1.101;

1.101
date	2004.12.10.21.34.05;	author fubob;	state Exp;
branches;
next	1.100;

1.100
date	2004.10.26.02.09.36;	author dm;	state Exp;
branches;
next	1.99;

1.99
date	2004.09.07.17.57.23;	author fubob;	state Exp;
branches;
next	1.98;

1.98
date	2004.06.13.22.49.11;	author dm;	state Exp;
branches;
next	1.97;

1.97
date	2004.06.04.01.03.11;	author dm;	state Exp;
branches;
next	1.96;

1.96
date	2004.05.18.18.26.54;	author dbg;	state Exp;
branches;
next	1.95;

1.95
date	2004.05.14.23.46.03;	author max;	state Exp;
branches;
next	1.94;

1.94
date	2004.05.14.23.41.58;	author max;	state Exp;
branches;
next	1.93;

1.93
date	2004.05.08.20.33.40;	author dm;	state Exp;
branches;
next	1.92;

1.92
date	2004.04.23.21.58.02;	author dm;	state Exp;
branches;
next	1.91;

1.91
date	2004.04.19.21.39.46;	author dm;	state Exp;
branches;
next	1.90;

1.90
date	2004.04.15.07.02.41;	author dm;	state Exp;
branches;
next	1.89;

1.89
date	2004.04.15.06.47.07;	author dm;	state Exp;
branches;
next	1.88;

1.88
date	2004.03.27.19.45.34;	author dm;	state Exp;
branches;
next	1.87;

1.87
date	2004.03.23.01.30.06;	author dbg;	state Exp;
branches;
next	1.86;

1.86
date	2004.03.10.21.34.41;	author kaminsky;	state Exp;
branches;
next	1.85;

1.85
date	2004.03.05.18.04.04;	author kaminsky;	state Exp;
branches;
next	1.84;

1.84
date	2004.03.01.19.50.26;	author fubob;	state Exp;
branches;
next	1.83;

1.83
date	2004.02.29.21.31.41;	author kaminsky;	state Exp;
branches;
next	1.82;

1.82
date	2004.01.07.23.08.45;	author dm;	state Exp;
branches;
next	1.81;

1.81
date	2004.01.06.23.58.07;	author dm;	state Exp;
branches;
next	1.80;

1.80
date	2003.12.24.00.11.15;	author dm;	state Exp;
branches;
next	1.79;

1.79
date	2003.07.10.17.44.20;	author kaminsky;	state Exp;
branches;
next	1.78;

1.78
date	2003.07.10.17.28.02;	author kaminsky;	state Exp;
branches;
next	1.77;

1.77
date	2003.07.10.14.40.33;	author kaminsky;	state Exp;
branches;
next	1.76;

1.76
date	2003.03.07.18.04.34;	author kaminsky;	state Exp;
branches;
next	1.75;

1.75
date	2003.02.27.19.10.13;	author kaminsky;	state Exp;
branches;
next	1.74;

1.74
date	2003.01.09.09.34.51;	author dm;	state Exp;
branches;
next	1.73;

1.73
date	2002.12.28.06.30.58;	author max;	state Exp;
branches;
next	1.72;

1.72
date	2002.12.27.07.09.26;	author dm;	state Exp;
branches;
next	1.71;

1.71
date	2002.12.22.07.27.14;	author dm;	state Exp;
branches;
next	1.70;

1.70
date	2002.12.08.16.07.34;	author dm;	state Exp;
branches;
next	1.69;

1.69
date	2002.12.06.20.05.24;	author max;	state Exp;
branches;
next	1.68;

1.68
date	2002.12.03.21.56.47;	author max;	state Exp;
branches;
next	1.67;

1.67
date	2002.12.03.20.55.48;	author dm;	state Exp;
branches;
next	1.66;

1.66
date	2002.12.03.20.17.18;	author max;	state Exp;
branches;
next	1.65;

1.65
date	2002.12.03.16.55.13;	author dm;	state Exp;
branches;
next	1.64;

1.64
date	2002.11.29.05.06.26;	author max;	state Exp;
branches;
next	1.63;

1.63
date	2002.11.28.20.38.31;	author dm;	state Exp;
branches;
next	1.62;

1.62
date	2002.11.28.14.38.40;	author max;	state Exp;
branches;
next	1.61;

1.61
date	2002.11.28.09.23.55;	author dm;	state Exp;
branches;
next	1.60;

1.60
date	2002.11.28.07.37.44;	author dm;	state Exp;
branches;
next	1.59;

1.59
date	2002.10.29.20.39.07;	author max;	state Exp;
branches;
next	1.58;

1.58
date	2002.10.28.21.44.02;	author max;	state Exp;
branches;
next	1.57;

1.57
date	2002.10.25.22.08.47;	author max;	state Exp;
branches;
next	1.56;

1.56
date	2002.10.23.20.35.37;	author max;	state Exp;
branches;
next	1.55;

1.55
date	2002.10.22.21.51.58;	author max;	state Exp;
branches;
next	1.54;

1.54
date	2002.10.19.13.56.38;	author max;	state Exp;
branches;
next	1.53;

1.53
date	2002.10.18.17.54.20;	author max;	state Exp;
branches;
next	1.52;

1.52
date	2002.10.16.00.28.38;	author max;	state Exp;
branches;
next	1.51;

1.51
date	2002.10.15.22.21.51;	author max;	state Exp;
branches;
next	1.50;

1.50
date	2002.10.15.18.53.31;	author max;	state Exp;
branches;
next	1.49;

1.49
date	2002.10.15.16.04.22;	author max;	state Exp;
branches;
next	1.48;

1.48
date	2002.10.15.04.46.28;	author max;	state Exp;
branches;
next	1.47;

1.47
date	2002.10.15.00.07.35;	author max;	state Exp;
branches;
next	1.46;

1.46
date	2002.07.29.16.10.02;	author max;	state Exp;
branches;
next	1.45;

1.45
date	2002.07.26.15.33.46;	author kaminsky;	state Exp;
branches;
next	1.44;

1.44
date	2002.06.26.06.36.31;	author dm;	state Exp;
branches;
next	1.43;

1.43
date	2002.06.18.18.47.35;	author max;	state Exp;
branches;
next	1.42;

1.42
date	2002.04.10.16.39.49;	author kaminsky;	state Exp;
branches;
next	1.41;

1.41
date	2002.03.22.18.59.32;	author kaminsky;	state Exp;
branches;
next	1.40;

1.40
date	2002.02.27.17.48.47;	author kaminsky;	state Exp;
branches;
next	1.39;

1.39
date	2002.02.24.03.48.25;	author dm;	state Exp;
branches;
next	1.38;

1.38
date	2002.02.14.15.19.11;	author dm;	state Exp;
branches;
next	1.37;

1.37
date	2002.01.30.16.59.53;	author kaminsky;	state Exp;
branches;
next	1.36;

1.36
date	2002.01.11.20.29.49;	author fubob;	state Exp;
branches;
next	1.35;

1.35
date	2001.12.17.21.51.58;	author kaminsky;	state Exp;
branches;
next	1.34;

1.34
date	2001.11.01.04.42.15;	author dm;	state Exp;
branches;
next	1.33;

1.33
date	2001.11.01.03.37.50;	author dm;	state Exp;
branches;
next	1.32;

1.32
date	2001.07.28.04.01.35;	author dm;	state Exp;
branches;
next	1.31;

1.31
date	2001.07.28.03.55.11;	author dm;	state Exp;
branches;
next	1.30;

1.30
date	2001.07.28.03.53.39;	author dm;	state Exp;
branches;
next	1.29;

1.29
date	2001.07.18.03.02.17;	author dm;	state Exp;
branches;
next	1.28;

1.28
date	2001.07.02.14.59.18;	author dm;	state Exp;
branches;
next	1.27;

1.27
date	2001.06.25.06.39.17;	author dm;	state Exp;
branches;
next	1.26;

1.26
date	2001.06.13.01.16.58;	author dm;	state Exp;
branches;
next	1.25;

1.25
date	2000.12.26.03.18.53;	author dm;	state Exp;
branches;
next	1.24;

1.24
date	2000.12.07.04.04.15;	author dm;	state Exp;
branches;
next	1.23;

1.23
date	2000.05.11.18.40.21;	author dm;	state Exp;
branches;
next	1.22;

1.22
date	2000.03.30.22.56.08;	author dm;	state Exp;
branches;
next	1.21;

1.21
date	2000.03.20.02.41.40;	author dm;	state Exp;
branches;
next	1.20;

1.20
date	2000.02.16.18.47.23;	author dm;	state Exp;
branches;
next	1.19;

1.19
date	2000.02.09.22.06.19;	author dm;	state Exp;
branches;
next	1.18;

1.18
date	2000.02.09.21.12.00;	author dm;	state Exp;
branches;
next	1.17;

1.17
date	2000.01.03.04.01.56;	author dm;	state Exp;
branches;
next	1.16;

1.16
date	99.12.31.23.27.42;	author dm;	state Exp;
branches;
next	1.15;

1.15
date	99.12.31.23.27.01;	author dm;	state Exp;
branches;
next	1.14;

1.14
date	99.12.31.01.21.07;	author dm;	state Exp;
branches;
next	1.13;

1.13
date	99.12.29.20.12.03;	author dm;	state Exp;
branches;
next	1.12;

1.12
date	99.12.29.04.47.11;	author dm;	state Exp;
branches;
next	1.11;

1.11
date	99.12.26.16.15.46;	author dm;	state Exp;
branches;
next	1.10;

1.10
date	99.12.26.07.47.05;	author dm;	state Exp;
branches;
next	1.9;

1.9
date	99.12.26.07.41.28;	author dm;	state Exp;
branches;
next	1.8;

1.8
date	99.12.26.06.49.19;	author dm;	state Exp;
branches;
next	1.7;

1.7
date	99.12.24.05.54.18;	author dm;	state Exp;
branches;
next	1.6;

1.6
date	99.12.16.20.11.13;	author dm;	state Exp;
branches;
next	1.5;

1.5
date	99.12.16.02.43.56;	author dm;	state Exp;
branches;
next	1.4;

1.4
date	99.12.08.06.51.28;	author dm;	state Exp;
branches;
next	1.3;

1.3
date	99.12.05.18.14.49;	author dm;	state Exp;
branches;
next	1.2;

1.2
date	99.12.01.02.09.15;	author dm;	state Exp;
branches;
next	1.1;

1.1
date	99.11.30.07.10.48;	author dm;	state Exp;
branches;
next	;


desc
@@


1.102
log
@get rid of uvfs; numerous fixes for 'make distcheck' with recent automake
@
text
@\input texinfo   @@c -*-texinfo-*-
@@c $Id: sfs.texi,v 1.101 2004/12/10 21:34:05 fubob Exp $
@@c %**start of header
@@setfilename sfs.info
@@include version.texi
@@include dirs.texi
@@settitle SFS @@value{VERSION} Manual
@@setchapternewpage off

@@iftex
@@alias dslash = slash
@@end iftex

@@ifnottex
@@macro dslash
/
@@end macro
@@end ifnottex

@@macro hslash
/
@@end macro

@@c %**end of header

@@direntry
* SFS: (sfs).		Self-certifying file system
@@end direntry

@@ifinfo
This file documents SFS, the self-certifying file system.

Copyright 1999--2002 David Mazi@@`eres

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.

@@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@@end ignore
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.
@@end ifinfo

@@c  This title page illustrates only one of the
@@c  two methods of forming a title page.

@@titlepage
@@title SFS @@value{VERSION} Manual
@@c @@subtitle SUBTITLE-IF-ANY
@@author David Mazi@@`eres

@@c  The following two commands
@@c  start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright{} 1999--2002 David Mazi@@`eres

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.
@@end titlepage

@@contents

@@node Top, Overview, (dir), (dir)
@@comment node-name,     next,           previous, up
@@top SFS

@@ifinfo
This file documents SFS, the self-certifying file system.

This document applies to version @@value{VERSION} of the SFS
distribution.
@@end ifinfo

@@menu
* Overview::                    Introduction to SFS
* Installation::                Building and installing the SFS software
* Getting Started::             Play with SFS as quickly as possible
* Administering SFS::           Guide to common administrative tasks
* SFS configuration::           SFS configuration files
* Command reference::           Command usage reference guide
* Environment variables::       Variables recognized by many SFS programs
* Security::                    Security implications of running SFS
* Contacts::                    How to contact the authors, report bugs
* Concept Index::               Index of concepts

@@detailmenu
 --- 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

Administering SFS

* System overview::             Overview of the SFS's various components
* Managing user keys::          Managing your accounts on different servers
* Administrative realms::       Setting up multiple servers in one realm
* Sharing sfs_users files::     

SFS configuration files

* sfs_config::                  System-wide configuration parameters
* sfsrwsd_config::              File server configuration
* sfsrosd_config::              
* sfsauthd_config::             User-authentication daemon configuration
* sfs_hosts::                   DNS override information
* 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
* sfsrosd::                     Daemon implementing read-only file server
* sfsauthd::                    User-authentication server
* sfsrwcd::                     Client for SFS read-write file system protocol
* nfsmounter::                  NFS mounting and unmounting daemon

Security considerations

* new vulnerabilities::         Vulnerabilities created by SFS
* exposed vulnerabilities::     Vulnerabilities exploitable because of SFS
* implementation vulnerabilities::  Vulnerabilities in the SFS implementation

@@end detailmenu
@@end menu

@@node    Overview, Installation, Top, Top
@@comment  node-name,  next,  previous,  up
@@chapter 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:

@@itemize @@bullet
@@item
@@strong{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.

@@item
@@strong{A global namespace.}  SFS mounts all remote file systems under
the directory @@file{/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.

@@item
@@strong{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.
@@end itemize

@@cindex @@var{HostID}
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:

@@display
@@t{/sfs/}@@t{@@@@}@@var{Location}@@t{,}@@var{HostID}
@@end display

or:

@@display
@@t{/sfs/}@@t{@@@@}@@var{Location}@@t{%}@@var{port}@@t{,}@@var{HostID}
@@end display



@@cindex Self-certifying pathname
@@noindent
@@var{Location} is a DNS hostname or an IP address.  @@var{HostID} is a
collision-resistant cryptographic hash of the file server's public
key.  @@var{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 @@dfn{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.

@@cindex Caffeine
No caffeine was used in the original production of the SFS software.

@@node    Installation, Getting Started, Overview, Top
@@comment  node-name,  next,  previous,  up
@@chapter 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:

@@itemize @@bullet
@@item
You must create an @@samp{sfs} user and an @@samp{sfs} group on your
system.  @@xref{--with-sfsuser}, to use a name other than @@samp{sfs}.

@@item
You must use gcc version 2.95.2 or later to compile SFS.
@@end itemize


@@menu
* Requirements::                Requirements for building and running SFS
* Building::                    How to build and install the SFS distribution
* Build Problems::              Common problems compiling the source
@@end menu

@@node Requirements, Building, Installation, Installation
@@comment  node-name,  next,  previous,  up
@@section 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.

@@ignore
@@cindex Linux
We have also run SFS with some success on Linux.  However, you need a
kernel with NFS3 support to run SFS on Linux.  The
@@uref{http:/@@dslash{}www.fs.net@@dslash{}linux@@dslash{}, SFS on linux web
page} has information on installing an SFS-capable Linux kernel.
@@end ignore

In order to compile SFS, you will need the following:

@@enumerate
@@item
gcc-2.95.2 or more recent.  You can obtain this from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}gcc}.
Don't waste your time trying to compile SFS with an earlier version of
gcc.

@@item
gmp-2.0.2 or more recent.  You can obtain this from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}gmp}.  Many
operating systems already ship with gmp.  Note, however, that some Linux
distributions do not include the @@file{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.

@@item
Header files in @@file{/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
@@file{/usr/include}.  SFS needs to see the patched header files to
compile properly.

@@item
128 MB of RAM.  The C++ compiler really needs a lot of memory.

@@item
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.)
@@end enumerate

@@node Building, Build Problems, Requirements, Installation
@@comment  node-name,  next,  previous,  up
@@section Building SFS

Once you have setup your system as described in @@ref{Requirements}, you
are ready to build SFS.

@@enumerate
@@item
Create a user, @@var{sfs-user}, and group, @@var{sfs-group}, for SFS on
your system.  By default, SFS expects the both @@var{sfs-user} and
@@var{sfs-group} to be called @@samp{sfs}.  For instance, you might add
the following line to @@file{/etc/passwd}:

@@example
sfs:*:71:71:Self-certifying file system:/:/bin/true
@@end example

And the following line to @@file{/etc/group}:

@@example
sfs:*:71:
@@end example

Do not put any users in @@var{sfs-group}, not even @@code{root}.  Any
user in @@var{sfs-group} will not be able to make regular use of the
SFS file system.  Moreover, having any unprivileged users in
@@var{sfs-group} causes a security hole.

@@item
Unpack the SFS sources.  For instance, run the commands:

@@example
% gzip -dc sfs-@@value{VERSION}.tar.gz | tar xvf -
% cd sfs-@@value{VERSION}
@@end example

If you determined that you need gmp (@@pxref{Requirements}), you should
unpack gmp into the top-level of the SFS source tree:

@@example
% gzip -dc ../gmp-2.0.2.tar.gz | tar xvf -
@@end example

@@item
Set your @@env{CC} and @@env{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 @@ref{Requirements}.

@@anchor{configure}
@@cindex @@command{configure}
@@item
Configure the sources for your system with the command
@@command{./configure}.  You may additionally specify the following
options:

@@table @@option
@@anchor{--with-sfsuser}
@@item --with-sfsuser=@@var{sfs-user}
If the user you created for SFS is not called @@samp{sfs}.  Do not use an
existing account for @@var{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 @@var{user-name}, you do not
need to recompile SFS, @@ref{sfs_config}.]

@@item --with-sfsgroup=@@var{sfs-group}
@@anchor{--with-sfsgroup}
If the user you created for SFS does not have the same name as
@@var{sfs-user}.  [Note:  If you later change your mind about
@@var{sfs-group}, you do not need to recompile SFS.]

@@item --with-gmp=@@var{gmp-path}
To specify where @@command{configure} should look for gmp (for example,
@@var{gmp-path} might be @@file{/usr/local}).  Note, if you unpacked gmp
into a subdirectory of the SFS source code, you do not need to specify
this option.  @@command{configure} should notice the directory and
compile gmp automatically.

@@item --with-sfsdir=@@var{sfsdir}
To specify a location for SFS to put its working files.  The default is
@@file{/var/sfs}.  [You can change this later, @@ref{sfs_config}.]

@@item --with-etcdir=@@var{etcdir}
To specify where SFS should search for host-specific configuration
files.  The default is @@file{/etc/sfs}.

@@item --datadir=@@var{datadir}
Where SFS places its data files.  The default is
@@file{/usr/local/share}.
@@end table

@@command{configure} accepts all the traditional GNU configuration
options such as @@option{--prefix}.  It also has several options that
are only for developers.  @@strong{Do not use the
@@option{--enable-repo} or @@option{--enable-shlib} options} (unless you
are a gcc maintainer looking for some wicked test cases for your
compiler).  Also, @@strong{Do not use the @@option{--with-openssl}
option}--it is only for use by the developers in compiling some
benchmark code that is not part of the release.

@@item
Build the sources by running @@samp{make}.

@@item
Install the binaries by running @@samp{make install}.  If you are short
on disk space, you can alternatively install stripped binaries by
running @@samp{make install-strip}.

@@item
That's it.  Fire up the client daemon by running @@command{sfscd}.
@@end enumerate

@@node Build Problems,  , Building, Installation
@@comment  node-name,  next,  previous,  up
@@section Problems building SFS

@@cindex Internal compiler error
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 @@code{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
@@code{__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 @@code{make
ECXXFLAGS='-D__attribute__\(x\)='} instead of simply @@code{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 @@code{make sfsagent.o CXXDEBUG=-g} in the
appropriate subdirectory.)

@@cindex Disk Full
If your @@file{/tmp} file system is too small, you may also end up
running out of temporary disk space while compiling SFS.  Set your
@@env{TMPDIR} environment variable to point to a directory on a file
system with more free space (e.g., @@file{/var/tmp}).

@@cindex Virtual memory exhausted
You may need to increase your heap size for the compiler to work.  If
you use a csh-derived shell, run the command @@code{unlimit datasize}.
If you use a Bourne-like shell, run @@code{ulimit -d `ulimit -H -d`}.

@@cindex @@code{___gmp_default_allocate}
On some operating systems, some versions of GMP do not install the
library properly.  If you get linker errors about symbols with names
like @@code{___gmp_default_allocate}, try running the command
@@code{ranlib @@hslash{}usr@@dslash{}local@@dslash{}lib@@dslash{}libgmp.a}
(substituting wherever your GMP library is installed for
@@code{@@hslash{}usr@@dslash{}local}).

@@node Getting Started, Administering SFS, Installation, Top
@@comment  node-name,  next,  previous,  up
@@chapter 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
@@end menu

@@node Quick client setup, Quick server setup, Getting Started, Getting Started
@@comment  node-name,  next,  previous,  up
@@section Quick client setup

SFS clients require no configuration.  Simply run the program
@@command{sfscd}, and a directory @@file{/sfs} should appear on your
system.  To test your client, access our SFS test server.  Type the
following commands:

@@example
% cd /sfs/@@@@sfs.fs.net,uzwadtctbjb3dg596waiyru8cx5kb4an
% cat CONGRATULATIONS
You have set up a working SFS client.
%
@@end example

@@noindent
Note that the @@file{/sfs/@@@@sfs.fs.net,@@dots{}} directory does not need to
exist before you run the @@command{cd} command.  SFS transparently mounts
new servers as you access them.

@@node Quick server setup, Quick user setup, Quick client setup, Getting Started
@@comment  node-name,  next,  previous,  up
@@section Quick server setup

Setting up an SFS server is a slightly more complicated process.  You
must perform at least three steps:

@@enumerate
@@item
Create a public/private key pair for your server.

@@item
Create an @@file{/etc/sfs/sfsrwsd_config} configuration file.

@@item
Configure your machine as an NFS server and export all necessary
directories to @@samp{localhost}.
@@end enumerate

Before you begin, be sure that SFS can figure out your host's
fully-qualified domain name, and that the domain name exists in the
domain name system (DNS)---as opposed to just being some fake host
name listed in @@file{/etc@@dslash{}hosts}.  SFS will use your host's
system name (returned by the @@command{hostname} command), and if that
is not fully-qualified, will append whatever default domain is
specified in @@file{/etc@@dslash{}resolv.conf}.  If this does not result
in a valid DNS domain name, you can either reconfigure your system
such that @@command{hostname} returns a fully-qualified and valid DNS
domain name (recommended), or set the environment variable
@@env{SFS_HOSTNAME} to the fully-qualified DNS name SFS should use
@@pxref{SFS_HOSTNAME}.  If you don't have a DNS name pointing to your
IP address, set @@env{SFS_HOSTNAME} to be the host's IP address.

Now, to create a public/private key pair for your server, run the
commands:
@@example
mkdir /etc/sfs
sfskey gen -P /etc/sfs/sfs_host_key
@@end example

Then you must create an @@file{/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 @@command{Export} directives in the configuration file.  Each
export directive is a line of the form:

@@example
Export @@var{local-directory} @@var{sfs-name}
@@end example

@@var{local-directory} is the name of a local directory on your system
you wish to export.  @@var{sfs-name} is the name you wish that directory
to have in SFS, relative to the previous @@command{Export} directives.
The @@var{sfs-name} of the first @@command{Export} directive must be
@@file{/}.  Subsequent @@var{sfs-name}s must correspond to pathnames that
already exist in the previously exported directories.

Suppose, for instance, that you wish to export two directories,
@@file{/disk/u1} and @@file{/disk/u2} as @@file{/usr1} and @@file{/usr2},
respectively.  You should create a directory to be the root of the
exported namespace, say @@file{@@value{SFSDIR}@@dslash{}root}, create the
necessary @@var{sfs-name} subdirectories, and create a corresponding
@@file{sfsrwsd_config} file.  You might run the following commands to
do this:

@@example
% mkdir @@value{SFSDIR}/root
% mkdir @@value{SFSDIR}/root/usr1
% mkdir @@value{SFSDIR}/root/usr2
@@end example

@@noindent
and create the following @@file{sfsrwsd_config} file:

@@example
Export @@value{SFSDIR}/root /
Export /disk/u1 /usr1
Export /disk/u2 /usr2
@@end example

@@cindex @@file{/etc/exports}
Finally, you must export all the @@var{local-directory}s in your
@@file{sfsrwsd_config} to @@samp{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
@@file{/etc/exports} and run the command @@samp{kill -HUP `cat
/var/run/mountd.pid`}:

@@example
@@value{SFSDIR}/root localhost
/disk/u1 localhost
/disk/u2 localhost
@@end example

On Linux, the syntax for the exports file is:

@@example
@@value{SFSDIR}/root localhost(rw)
/disk/u1 localhost(rw)
/disk/u2 localhost(rw)
@@end example

On Solaris, add the following lines to the file @@file{/etc/dfs/dfstab}
and run @@samp{exportfs -a}:

@@example
share -F nfs -o -rw=localhost @@value{SFSDIR}/root
share -F nfs -o -rw=localhost /disk/u1
share -F nfs -o -rw=localhost /disk/u2
@@end example

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 @@command{mountd} is a
good place to start.)  You can test to see if your NFS server is
configured as expected (independently or running SFS) by running
@@command{showmount} with the @@option{-e} option.  With the example
configuration, you should see something like this:

@@example
% shouwmount -e
@@value{SFSDIR}/root           localhost.your.domain
/disk/u1                localhost.your.domain
/disk/u2                localhost.your.domain
@@end example

Once you have generated a host key, created an @@file{sfsrwsd_config}
file, and reconfigured your NFS server, you can start the SFS server by
running @@command{sfssd}.  Note that a lot can go wrong in setting up an
SFS server.  Thus, we recommend that you first run @@samp{sfssd -d}.  The
@@option{-d} switch will leave @@command{sfssd} in the foreground and send
error messages to your terminal.  If there are problems, you can then
easily kill @@command{sfssd} from your terminal, fix the problems, and
start again.  Once things are working, omit the @@option{-d} flag;
@@command{sfssd} will run in the background and send its output to the
system log.

Note: @@strong{You will not be able to access an SFS server running on
the same machine as the client} unless you run @@command{sfscd} with
the @@option{-l} flag, @@ref{sfscd}.  Attempts to SFS mount a machine on
itself will return the error @@code{EDEADLK} (Resource deadlock
avoided).

@@node Quick user setup,  , Quick server setup, Getting Started
@@comment  node-name,  next,  previous,  up
@@section 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 @@command{sfsagent} on your SFS client to
authenticate you.

To register a public key, log into the file server and run the command:

@@example
sfskey register
@@end example

This should produce something similar to the following output:

@@example
% 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
@@end example

Press @@key{RET} to accept the default key label.  You will then see:

@@example
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            
@@end example

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:

@@example
  UNIX password: 
wrote key: /home/user/.sfs/authkeys/user@@@@server.com#1
%
@@end example

@@noindent
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
@@command{sfskey} your address at that server, e.g., @@samp{sfskey
register user@@@@other.server.com}.)

After registering your public key with an SFS server, you can use the
@@samp{sfskey login} command to access the server.  Get a shell on a
different client machine from the server, and run the command:

@@example
sfskey login @@var{usr}@@@@@@var{server}
@@end example

@@c @@command{sfsagent} program on an SFS client to access the server.  On
@@c the client, run the command:

@@c @@example
@@c sfsagent @@var{user}@@@@@@var{server}
@@c @@end example

@@noindent
@@var{server} is the name of the server on which you registered, and
@@var{user} is your logname on that server.  You should be prompted for
a password, and see something like the following:

@@example
Passphrase for dm@@@@server.com/1024: 
SFS Login as dm@@@@server.com
@@end example

@@noindent
The @@samp{sfskey login} command does three things:  It starts the
@@command{sfsagent} program, which persists in the background to
authenticate you to file servers as needed.  It fetches your private
key from @@var{server} and decrypts it using your passphrase.  Finally,
it fetches the server's public key, and creates a symbolic link from
@@file{/sfs/@@var{server}} to @@file{/sfs/@@@@@@var{server},@@var{HostID}}.
(The passphrase you type is also used to authenticate the server to
the client, so that @@command{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 @@samp{sfskey login} multiple times.  You will be able to
access all the servers you have logged into simultaneously.

@@c However, in general you need not explicitly log in to every server you
@@c wish to access.  If you register the same public key on every server,
@@c you can access all servers after logging into any one of them---so
@@c long as you have some secure way of retrieving the self-certifying
@@c pathname of the server.

While @@command{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; @@command{sfsagent} will automatically authenticate
you to whatever file servers you touch.  Moreover, once you have
access to one SFS file server, you can use it to store symbolic links
to other servers' self-certifying pathnames.

When you are done using SFS, you should run the command

@@example
sfskey kill
@@end example

@@noindent
before logging out.  This will kill your @@command{sfsagent} process
running in the background and get rid of the private keys it was holding
for you in memory.


@@node Administering SFS, SFS configuration, Getting Started, Top
@@comment  node-name,  next,  previous,  up
@@chapter Administering SFS

@@menu
* System overview::             Overview of the SFS's various components
* Managing user keys::          Managing your accounts on different servers
* Administrative realms::       Setting up multiple servers in one realm
* Sharing sfs_users files::     
@@end menu

@@node System overview, Managing user keys, Administering SFS, Administering SFS
@@comment  node-name,  next,  previous,  up
@@section System overview

@@iftex
@@vbox to 2in{@@vskip -1.2in@@image{components,6in,}@@vss}
@@end iftex
@@ifnottex
@@example
   sfskey--+---------------- - - - -----------+
           |                                  |
         agent--+                             |
     agent------+                             |
                |                             |
   +---------------+                       +-------------+
   |         sfscd |-------- - - - --------| sfssd       |
   |            |  |                       |  |          |
   |    sfsrwcd-+  |                       |  +-sfsrwsd--+-+
   |    sfsrocd-+  |                       |  +-sfsrosd  | |
   | nfsmounter-+  |                       |  +-sfsauthd | |
   +---------------+                       +-------------+ |
                |                                          V
+--------+      |                                   +--------+
| kernel |      |                                   | kernel |
|  NFS3  |<-----+                                   |  NFS3  |
| client |                                          | server |
+--------+                                          +--------+

          CLIENT                               SERVER
@@end example
@@end ifnottex
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 @@command{sfscd} gets run by root (typically at boot time).
@@command{sfscd} spawns two other daemons---@@command{nfsmounter} and
@@command{sfsrwcd}.

@@cindex @@command{nfsmounter}
@@command{nfsmounter} handles the mounting and unmounting of NFS file
systems.  In the event that @@command{sfscd} dies, @@command{nfsmounter}
takes over being the NFS server to prevent file system operations from
blocking as it tries to unmount all file systems.  @@strong{Never send
@@command{nfsmounter} a @@code{SIGKILL} signal (i.e., @@samp{kill -9}).}
@@command{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 @@command{nfsmounter} will
likely only make matters worse.

@@command{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 @@command{sfsrwcd}.

@@command{sfsrocd} implements the client-side of the read-only dialect of
SFS.  This program synthesizes a file system by reading blocks
from an @@command{sfsrosd} replica.

Each user of an SFS client machine must run an instance of the
@@command{sfsagent} command.  @@command{sfsagent} serves several purposes.
It handles user authentication as the user touches new file systems.  It
can fetch @@var{HostID}s on the fly, a mechanism called @@dfn{Dynamic
server authentication}.  Finally, it can perform revocation checks on
the @@var{HostID}s of servers the user accesses, to ensure the user does
not access @@var{HostID}s corresponding to compromised private keys.

The @@command{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 @@command{sfskey}, list keys the agent holds,
and delete keys.  @@command{sfskey} will fetch keys from remote servers
using SRP, @@ref{SRP}.  It lets users change their public keys on remote
servers.  Finally, @@command{sfskey} can configure the agent for dynamic
server authentication and revocation checking.

On the server side, the program @@command{sfssd} spawns two subsidiary
daemons, @@command{sfsrwsd} and @@command{sfsauthd}.  If virtual hosts or
multiple versions of the software are running, @@command{sfssd} may spawn
multiple instances of each daemon.  @@command{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.

@@command{sfsrwsd} is the server-side counterpart to @@command{sfsrwcd}.
It communicates with client side @@command{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.  @@command{sfsrwsd} is
the one program in sfs that @@emph{must be configured} before you run it,
@@ref{sfsrwsd_config}.

@@command{sfsrosd} is the server-side counterpart to @@command{sfsrocd}.
A @@command{sfsrosd} replica presents a simple interface for reading
blocks of data.  This program requires @@ref{sfsrosd_config} to select
a set of read-only databases to serve.

@@command{sfsauthd} handles user authentication.  It communicates
directly with @@command{sfsrwsd} to authenticate users of the file system.
It also accepts connections over the network from @@command{sfskey} to
let users download their private keys or change their public keys.


@@node Managing user keys, Administrative realms, System overview, Administering SFS
@@comment  node-name,  next,  previous,  up
@@section Managing user keys


@@node Administrative realms, Sharing sfs_users files, Managing user keys, Administering SFS
@@comment  node-name,  next,  previous,  up
@@section Administrative realms
@@cindex realms

It is inconvenient for users to run @@samp{sfskey login} once for every
server they wish to access.  Though users can register the same public
key on multiple servers, they still cannot access a server without its
self-certifying pathname.

SFS's @@emph{realm} mechanism allows one trusted server to store and
serve the self-certifying pathnames of many other servers.  By
default, SFS servers are not configured to support administrative
realms.  When a user runs @@samp{sfskey login} to a server without a
realm, a symbolic link is created from
@@file{sfs@@dslash{}@@var{server-name}} to the server's self-certifying
pathname.  If, instead, the server is configured to be part of an
administrative realm, @@file{sfs@@dslash{}@@var{server-name}} will be a
directory, and references to names in that directory will
transparently create symbolic links to self-certifying pathnames.

To set up a realm server, you must first create a publicly-readable
directory of symbolic links to self-certifying pathnames of other
servers.  For example, suppose your @@file{sfsrwsd_config} file's root
directory is publicly readable with this configuration:

@@example
Export @@value{SFSDIR}/root / R
@@end example

Create a directory @@file{@@value{SFSDIR}@@dslash{}root@@dslash{}servers}.
Now populate this directory with symbolic links to self-certifying
pathnames.  For example, a server for the realm of machines in DNS
zone @@samp{scs.cs.nyu.edu} might contain the following links:

@@example
pitt -> /sfs/@@@@pitt.scs.cs.nyu.edu,rexmmr795q6enmhsemr5xt5f6jjhjm6h
fdr -> /sfs/@@@@fdr.scs.cs.nyu.edu,hki6vgn6gwkuknve7xqrv4a5mbv76uui
ludlow -> /sfs/@@@@ludlow.scs.cs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz
orchard -> /sfs/@@@@orchard.scs.cs.nyu.edu,4ttg7gvinyxrfe2zgv8mefmjbb3z7iur
@@end example

These links should now also be available in the subdirectory
@@file{servers} of the server's self-certifying pathname.

Finally, to configure your server to support realms, you must add the
following two lines to @@file{@@value{ETCDIR}@@dslash{}sfsauthd_config}.
(If that file does not exist, copy the default file
@@file{@@value{PKGDATADIR}@@dslash{}sfsauthd_config} to
@@file{@@value{ETCDIR}} to add the lines.)

@@example
realm @@var{realm-name}
certpath /servers
@@end example

The @@var{realm-name} can be the name of your primary server, or it
might be your domain name instead (e.g., in the example you can chose
realm name @@samp{scs.cs.nyu.edu} to authenticate a bunch of servers
ending @@samp{.scs.cs.nyu.edu}).

After editing @@file{sfsauthd_config}, you must restart
@@command{sfsauthd} on the server.  The easiest way to do this is to
run the following command as root:

@@example
# kill -1 `cat /var/run/sfssd.pid`
@@end example

Note that if the new @@var{realm-name} is not the same as the server
name (or if you ever change @@var{realm-name}), then users who have
already registered will see a message like the following when they
next log in:

@@example
sfskey: Warning: host for dm@@@@ludlow.scs.cs.nyu.edu is actually server
        @@@@ludlow.scs.cs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz
        This server is claiming to serve host (or realm) scs.cs.nyu.edu,
        but you originally registered on host (or in realm) ludlow.scs.cs.nyu.edu
sfskey: fatal: Invalid connection to authserver.
@@end example

The reason for this error is that, unfortunately, users often chose
the same passwords in multiple administrative realms.  To prevent one
realm from impersonating another in the event that users have recycled
passwords, SFS cryptographically embeds the realm name in the SRP
password information stored at the server.

To correct the problem after changing @@var{realm-name}, users need
only run the command:

@@example
% sfskey update -r [@@var{user}]@@var{server-name}
@@end example

This command will prompt users for their passwords and then ask them
to confirm the change of realm name.

Once your realm is configured and you have updated your account at the
server, you can log into the server with @@samp{sfskey login}.  You
should now see @@file{/sfs@@dslash{}@@var{realm-name}} as an empty
directory on your system.  However, if you access a file name like
@@file{/sfs@@dslash{}@@var{realm-name}@@dslash{}ludlow} and @@file{ludlow}
is a symbolic link in the @@file{servers} directory, then name
@@file{/sfs@@dslash{}@@var{realm-name}@@dslash{}ludlow} will automatically
spring into existence as the appropriate symbolic link.

Note that SFS could immediately populate the directory
@@file{/sfs@@dslash{}@@var{realm-name}} with symbolic links before users
even access the names.  However, many users alias the @@command{ls}
command to @@command{ls -F}, and many versions of Linux ship with an
@@command{ls} command that colorizes output by default.  These
@@command{ls} commands execute a @@code{stat} system call for every file
in a directory, which would be quite expensive in a directory of links
to self-certifying pathnames, as each @@code{stat} call would trigger a
file system mount (and unavailable servers would introduce serious
delays).


@@node Sharing sfs_users files,  , Administrative realms, Administering SFS
@@comment  node-name,  next,  previous,  up
@@section Sharing @@file{sfs_users} files

One often wishes to set up multiple servers to be part of a single
administrative realm and recognize the same set of users.  In such
cases, users can access all servers in the realm by executing a single
@@samp{sfs login} command.  Moreover, users only need to change their
public keys and passwords on a single server for the changes to
propagate to the other ones.

Within an administrative realm, one can classify servers as either
trusted or untrusted.  A trusted server is a machine that all servers
trust to specify the identities of users and servers in the realm.  In
each realm, one of the trusted servers, designated the @@emph{primary},
is the one on which users update their accounts.  Every administrative
realm must have a primary server.  An untrusted server recognizes all
users in the realm, but is not necessarily trusted by users or other
servers in the realm.

As a concrete example, consider a research group with two central file
servers, A and B, and a number of clients C1, C2, @@dots{}, on users'
desks.  Everyone in the group may trust the administrators of servers
A and B, but individual users may have superuser privileges on their
own clients and not be trusted by the rest of the realm.  In
particular, the user of client C1 may wish to set up a file server
accessible to other users in the realm (and possibly also accessible
to some local maintained guest accounts on C1).  C1's owner must be
able to set up this server without it being trusted by the rest of the
realm.

To configure SFS servers as part of a realm, you must first understand
what information a server stores about users.  Each SFS server has one
or more @@file{sfs_users} databases of users on the system.  A database
may contain, among other things, the following information for each
user:

@@itemize @@bullet
@@item
The user's name.

@@item
The user's numeric user ID and login group ID.

@@item
The user's public key.

@@cindex SRP
@@item
The user's ``SRP information.''
@@uref{http:/@@dslash{}srp.stanford.edu@@dslash{},SRP} is the password
authentication protocol used by the @@samp{sfskey login} command.  The
SRP information stored by the server serves two purposes.  First, it
allows the server to verify that a user running @@samp{sfskey login}
knows the right password to access the account.  Second, and equally
important, it allows the server to prove its own identity to the
client executing @@samp{sfskey login}.  Thus, though not equivalent to
the user's password, the SRP information is a secret derived from the
password with which the server can prove its own identity.

@@item
An encrypted copy of the user's private key.
@@end itemize

The first three pieces of information





@@node SFS configuration, Command reference, Administering SFS, Top
@@comment  node-name,  next,  previous,  up
@@chapter SFS configuration files

SFS consists of a number of programs, many of which have configuration
files.  All programs look for configuration files in two
directories---first @@file{@@value{ETCDIR}}, then, if they don't find the file
there, in @@file{@@value{PKGDATADIR}}.  You can change these locations
using the @@option{--with-etcdir} and @@option{--datadir} options to
the @@command{configure} command, @@ref{configure}.

The SFS software distribution installs reasonable defaults in
@@file{@@value{PKGDATADIR}} for all necessary configuration files except
@@file{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 @@file{@@value{ETCDIR}}.

The @@file{sfs_config} file contains system-wide configuration
parameters for most of the programs comprising SFS.  Note that
@@file{@@value{PKGDATADIR}@@dslash{}sfs_config} is always parsed, even if
@@file{@@value{ETCDIR}@@dslash{}sfs_config} exists.  Options in
@@file{@@value{ETCDIR}@@dslash{}sfs_config} simply override the defaults
in @@file{@@value{PKGDATADIR}@@dslash{}sfs_config}.  For all other
configuration files, a file in @@file{@@value{ETCDIR}} entirely
overrides the version in @@file{@@value{PKGDATADIR}}.

If you are running a server, you will need to create an
@@file{sfsrwsd_config} file to tell SFS what directories to export, and
possibly an @@file{sfsauthd_config} if you wish to share the database of
user public keys across several file servers.

The @@file{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.

To run an SFS read-only server, you must create an @@ref{sfsrosd_config}
file to tell SFS which read-only databsses to serve.

@@file{sfs_srp_params} contains some cryptographic parameters for
retrieving keys securely over the network with a passphrase (as with the
@@samp{sfskey add @@var{usr}@@@@@@var{server}} command).

@@file{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
* sfsrosd_config::              
* sfsauthd_config::             User-authentication daemon configuration
* sfs_hosts::                   DNS override information
* sfs_users::                   User-authentication database
* sfssd_config::                Meta-server configuration
* sfs_srp_params::              Default parameters for SRP protocol
* sfscd_config::                Meta-client configuration
@@end menu


@@node sfs_config, sfsrwsd_config, SFS configuration, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfs_config}---system-wide configuration parameters
@@cindex @@file{sfs_config}

@@c @@mp
@@c @@mp @@conffile{sfs_config}{system-wide configuration parameters}
@@c @@mp @@description
The @@file{sfs_config} file lets you set the following system-wide
parameters:

@@table @@samp
@@item sfsdir @@var{directory}
The directory in which SFS stores its working files.  The default is
@@file{/var/sfs}, unless you changed this with the @@option{--with-sfsdir}
option to @@command{configure}.

@@item sfsuser @@var{sfs-user} [@@var{sfs-group}]
As described in @@ref{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, @@var{sfs-user} is @@samp{sfs} and
@@var{sfs-group} is the same as @@var{sfs-user}.  The @@samp{sfsuser}
directive lets you supply either a user and group name, or numeric IDs
to change the default.  Note:  @@strong{If you change @@var{sfs-group},
you must make sure the the program
@@file{@@value{SFSLIBDIR}@@dslash{}suidconnect} is setgid to the new
@@var{sfs-group}.}

@@item anonuser @@{@@var{user} | @@var{uid} @@var{gid}@@}
@@anchor{anonuser}
Specifies an unprivileged user id to be used for anonymous file access.
If specified as @@var{user}, the name @@var{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 @@var{uid} and @@var{gid}.
The default is to use -1 for both the @@var{uid} and @@var{gid}, though
the default @@file{sfs_config} file specifies the user name nobody.

@@item ResvGids @@var{low-gid} @@var{high-gid}
@@anchor{resvgids}
SFS lets users run multiple instances of the @@command{sfsagent} program.
However, it needs to modify processes' group lists so as to know which
file system requests correspond to which agents.  The @@samp{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
@@var{low-gid} and @@var{high-gid} are considered reserved gids.

The setuid root program @@command{newaid} lets users take on any of
these group IDs, @@ref{newaid}.  Thus, make sure these groups are not
used for anything else, or you will create a security hole.  There is
no default for @@samp{ResvGids}.

Note that after changing @@samp{ResvGids}, you must kill and restart
@@command{sfscd} for things to work properly.

@@item RSASize @@var{bits}
Sets the default size of public keys for cryptosystems that are based
on the difficulty of factoring integers.  The Rabin public keys used in
self-certifying pathnames are affected by this parameter.  The default
value of @@var{bits} is 1280.

@@item DlogSize @@var{bits}
Sets the default size of public keys for cryptosystems that are based
on the difficulty of taking discrete logs in subgroups of
@@strong{Z}@@emph{p}*.  This parameter affects SRP parameter and
2-Schnorr key generation.  The default value of @@var{bits} is 1024.

@@item PwdCost @@var{cost}
@@anchor{pwdcost}
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 @@var{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
@@samp{sfskey edit}.

The default value is 12.  @@var{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 @@command{sfskey} command will be
unusable.

@@item LogPriority @@var{facility}.@@var{level}
Sets the syslog facility and level at which SFS should log activity.
The default is @@samp{daemon.notice}.
@@end table
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end


@@node sfsrwsd_config, sfsrosd_config, sfs_config, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfsrwsd_config}---File server configuration
@@cindex @@file{sfsrwsd_config}

@@c @@mp 
@@c @@mp @@conffile{sfsrwsd_config}{file server configuration}
@@c @@mp @@description
@@table @@samp
@@item Hostname @@var{name}
Set the @@var{Location} part of the server's self-certifying pathname.
The default is the current host's fully-qualified hostname.

@@item Keyfile @@var{path}
Tells @@command{sfsrwsd} to look for its private key in file @@var{path}.
The default is @@file{sfs_host_key}.  SFS looks for file names that do
not start with @@file{/} in @@file{@@value{ETCDIR}}, or whatever directory you
specified if you used the @@option{--with-etcdir} option to
@@command{configure} (@@pxref{configure}).

@@item Export @@var{local-directory} @@var{sfs-name} [R|W]
@@anchor{export}
Tells @@command{sfsrwsd} to export @@var{local-directory}, giving it the
name @@var{sfs-name} with respect to the server's self-certifying
pathname.  Appending @@samp{R} to an export directive gives anonymous
users read-only access to the file system under the anonymous user
group IDs specified in @@file{sfs_config}, @@ref{anonuser}.
@@ignore
(See the description of the
@@samp{anonuser}
directive in the
@@file{sfs_config}
man page for more information
.)
@@end ignore
Appending
@@samp{W} gives anonymous users both read and write access.
@@c @@mp @@ignore
@@xref{Quick server setup},
@@c @@mp @@end ignore
@@ignore
See the @@emph{Quick server setup} section of the SFS info pages
@@end ignore
for an example of the @@samp{Export} directive.

There is almost no reason to use the @@samp{W} flag.  The @@samp{R} flag
lets anyone on the Internet issue NFS calls to your kernel as the
anonymous user.  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 @@samp{R}
option---probably just crashing your server but possibly doing worse.

@@item LeaseTime @@var{seconds}
Specifies the amount of time for which SFS clients can cache file
attributes.  During this period, if a file is modified, the server
will call back to the client to let it know that the file's attributes
have changed.  Unfortunately, if a file is modified not through SFS
(e.g., through the local file system interface on the server), the
server may not realize the attributes have changed, and clients may
see stale data for the lease period.  The default lease term is 60
seconds.

@@end table
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end

@@node sfsrosd_config, sfsauthd_config, sfsrwsd_config, SFS configuration
@@comment  node-name, next, previous, up
@@section @@file{sfsrosd_config}---SFSRO server configuration
@@cindex @@file{sfsrosd_config}

@@c @@mp 
@@c @@mp @@conffile{sfsrosd_config}{read-only file server configuration}
@@c @@mp @@description
@@table @@samp

@@item Publishfile @@var{path}
Tells @@command{sfsrosd} to serve the SFS read-only database
contained in file @@var{path}.

@@end table
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end


@@node sfsauthd_config, sfs_hosts, sfsrosd_config, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfsauthd_config}---User-authentication daemon configuration
@@cindex @@file{sfsauthd_config}

@@c @@mp
@@c @@mp @@conffile{sfsauthd_config}{user-authentication daemon configuration}
@@c @@mp @@description
@@table @@samp
@@item Hostname @@var{name}
Set the @@var{Location} part of the server's self-certifying pathname.
The default is the current host's fully-qualified hostname.

@@item Keyfile @@var{path}
Tells @@command{sfsrwsd} to look for its private key in file @@var{path}.
The default is @@file{sfs_host_key}.  SFS looks for file names that do
not start with @@file{/} in @@file{@@value{ETCDIR}}, or whatever directory you
specified if you used the @@option{--with-etcdir} option to
@@command{configure} (@@pxref{configure}).

@@item Userfile [-update] [-create] [-passwd] [-admin] [-hideusers] [-pub=@@var{pubpath}] [-prefix=@@var{prefix}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-groups=@@var{g1}-@@var{g2}] [-groupquota=@@var{limit}] [-refresh=@@var{seconds}] [-timeout=@@var{seconds}] @@var{path}
This specifies a file in which @@command{sfsauthd} should look for user
public keys when authenticating users.  You can specify multiple
@@samp{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.

If @@command{sfsauthd} has been compiled with
@@uref{http://www.sleepycat.com/, Sleepycat database} support, and
@@var{path} ends in @@file{.db/}, @@command{vidb} will consider the user
authentication file to be a database directory.  This offers
considerably greater efficiency for large databases, as databases
directories most operations O(log n) rather than O(n) for flat text
files.  If @@var{path} ends in @@file{.db}, it is assumed to be a
database file.  Database files are similar to database directories,
but can only be used for read-only databases (as they do not support
atomic transactions).  Database files should be used to export
databases via the @@samp{-pub=@@var{pubpath}} option, and to import
read-only databases (by omitting the @@samp{-update} option).

Userfile has the following options:

@@table @@option
@@item -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 be read-only and possibly on a remote machine.
Thus, @@command{sfsauthd} maintains local copies of read-only databases
in @@file{@@value{SFSDIR}/authdb}.  This process ensures that
temporarily unavailable file servers never disrupt
@@command{sfsauthd}'s operation.

@@item -create
Create an empty @@file{sfs_users} file if no such file exists.

@@item -passwd
Treat the Unix passwd file (@@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 @@command{sfsauthd} with their UNIX password, so that they
might register an SFS key (note this also requires the
@@option{-update} flag).  @@xref{sfskey register}, for details on
this. Also important for proper functioning of @@command{rexd}.

@@item -admin
Allow an SFS administrator to make changes to user records that have
the admin flag set in their @@option{privs} field.

@@item -hideusers
When replying to group queries, replace local user names (that appear in
the ownership or membership lists) with a hash of the user's public key.

@@item -pub=@@var{pubpath}
@@command{sfsauthd} supports the secure remote password protocol, or SRP.
SRP lets users connect securely to @@command{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 @@var{path} specified in
@@samp{Userfile} contains these secrets for users opting to use SRP.  The
@@option{-pub} option tells @@command{sfsauthd} to maintain in
@@var{pubpath} a separate copy of the database without secret
information.  @@var{pubpath} might reside on an anonymously readable SFS
file system---other machines can then import the file as a read-only
database using a @@command{Userfile} line with the @@option{-update}
flag.

@@item -prefix=@@var{prefix}
Prepend the prefix @@var{prefix} to usernames in the given userfile.

@@item -uid=@@var{uid} 
@@itemx -uidmap=@@var{u1}-@@var{u2}+@@var{u3}
These options are mutually exclusive.  The first maps every user's credentials
in the given file to the given UID, @@var{uid}.  The second maps users in
the UID range (@@var{u1} to @@var{u2}) to the offset @@var{u3}.  For example, if
you wanted to map users to 1000-2520 to 61000-62520, you would supply
-uidmap=1000-2520+60000.

@@item -gid=@@var{gid}
@@itemx -gidmap=@@var{g1}-@@var{g2}+@@var{g3}
See above.  Functions the same as @@option{uid} and @@option{uidmap}, but 
applies to group IDs, rather than user IDs.  Again, these options
are mutually exclusive.

@@item -groups=@@var{g1}-@@var{g2}
This option tells @@command{sfsauthd} to allow regular (non-admin) users
to add groups.  New group IDs will be in the range @@var{g1} to @@var{g2}.
Administrators can establish per-user quotas to limit the number of
groups that a particular user can create.  User quotas are listed in
the @@var{privs} field of user records as "groupquota"=@@var{quota} where
@@var{quota} is an unsigned integer.

@@item -groupquota=@@var{limit}
Set the default maximum number of groups that any non-administrative user
can create.  Administrative users have the `admin' keyword in the `privs'
field of their user entry.  The authentication server also looks for the
pattern `groupquota=<limit>' in the user record; if found, that per-user
quota takes precedence and overrides this global (UserFile-wide) setting.
If no group quota is specified in either place, the number of groups that a
user can create is unlimited.

@@item -refresh=@@var{seconds}
This option allows the administrator to set a default refresh value for
newly created users and/or groups in this database.  The refresh value is
stored with the user and/or group record and is retured with the record in
response to database queries.  The refresh value tells the entity who is
fetching the record that it can continue to use its cached copy of this
record for @@var{seconds} seconds since the last time it was successfully
updated.  That is, the record does not need refreshing for at least
@@var{seconds} seconds.  If unspecified, the current system default is 3600
seconds (1 hour).

@@item -timeout=@@var{seconds}
This option allows the administrator to set a default timeout value for
newly created users and/or groups in this database.  The timeout value is
stored with the user and/or group record and is retured with the record in
response to database queries.  The timeout value tells the entity who is
fetching the record that---in the event that the authentication server is
unavailable---the entity can continue to use its cached copy of this
record for @@var{seconds} seconds since the last time it was successfully
updated.  If unspecified, the current system default is 604800 seconds (1
week).
@@end table

If no @@samp{Userfile} directive is specified, @@command{sfsauthd} uses
the following default (again, unqualified names are assumed to be in
@@file{@@value{ETCDIR}}):

@@example
Userfile -update -passwd -pub=sfs_users.pub sfs_users
@@end example

@@item DBcache @@var{path}
The @@var{path} to the database that holds the authentication server's
cache.  If unspecified, it defaults to one of the two entries shown
below.  The first applies if Sleepycat (BerkeleyDB) support was compiled
in; otherwise, the second entry applies.  If @@var{path} begins with a
"/" (slash), it is taken to be an absolute path.  If not, it is a path
relative to @@file{@@value{SFSDIR}/authdb}.

@@example
dbcache dbcache.db/
dbcache dbcache
@@end example

@@item DBcache_refresh_delay @@var{seconds}
Specify the frequency (in seconds) that @@command{sfsauthd}
will attempt to refresh its cache.  This value only serves as a
minimum because the server will not attempt to download a remote
user or group more frequently than its individual refresh value
(set by the remote administrator or user).  The special value 
`off' disables the authentication cache as well as symbolic and/or
recursive groups.  The default is `off'.

@@example
dbcache_refresh_delay off
dbcache_refresh_delay 3600
@@end example

@@item Logfile @@var{path}
Use the logfile given by @@var{path} to output the signature log
generated by @@command{sfsauthd}.  The default logfile is
@@file{@@value{SFSDIR}/sign_log}.

@@item SRPfile @@var{path}
Where to find default parameters for the SRP protocol.  Generate such a
file using the @@command{sfskey gensrp} command. The default is
@@file{sfs_srp_params}.  If the default file does not exist, serving
pre-generated SRP parameters is disabled.

@@item Denyfile @@var{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 @@file{sfs_deny}.  If the default file does not exist, we
assume an empty list.

@@item Realm @@var{name}
@@anchor{Realm}
@@cindex realms
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 login 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, @@var{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

@@example
sfskey update -r username@@@@authserver
@@end example

A user logged on to the authserver can use the hostname @@var{-} to
signify the local host:

@@example
sfskey update -r -
@@end example

@@item Certpath @@var{dir} [@@var{dir} ...]
Specify a certification path to return to the client as a result of an
@@command{sfskey login} command; this list of directories will become the
arguments to a dirsearch certprog.  That is, for a certpath "@@var{dir1}
@@var{dir2}" the client will add a certprog "dirsearch @@var{dir1}
@@var{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:

@@example
certpath //dir1 /dir2 @@@@sfs.host.domain,HOSTID/dir2
@@end example

which can also be written

@@example
certpath //dir1
certpath /dir2
certpath @@@@sfs.host.domain,HOSTID/dir2
@@end example

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.
@@end table
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end


@@node sfs_hosts, sfs_users, sfsauthd_config, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfs_hosts}---Host to address mapping overriding DNS
@@cindex @@file{sfs_hosts}

@@c @@mp
@@c @@mp @@conffile{sfs_hosts}{Host to address mapping overriding DNS}
@@c @@mp @@description
All SFS client software uses DNS to locate server names.  This is
somewhat different from typical network utilities, which, often
depending on a configuration file such as @@file{/etc/nsswitch.conf},
can sometimes combine DNS with other techniques, such as scanning the
file @@file{/etc/hosts} or querying NIS (YP) servers.

SFS relies exclusively on DNS for several reasons.  First, the file
system is designed to provide a global namespace.  Using
@@file{/etc/hosts}, for example, it is common for a machine to have two
names---for instance @@samp{hostname}, and @@samp{hostname.domain.com}.
However, were the same file system to be available under two different
self-certifying pathnames, several things would go wrong:  First,
bookmarks to @@file{/sfs/@@@@hostname,.../...} would only work on the
local network.  Even worse, it might be possible to lose a file by
accidentally copying it onto itself, e.g., from
@@file{/sfs/@@@@hostname,.../...} to
@@file{/sfs/@@@@hostname.domain.com,.../...}.  Finally, SFS allows one to
specify a TCP port number other than the default (4) using DNS SRV
records, while non-DNS mechanisms have no means of specifying port
numbers.

Though DNS is fairly ubiquitous, there are situations in which one
might like to have ``internal'' connections to SFS servers routed
differently from ``external'' ones.  For example, when running SFS
servers behind a NAT box, external connections would need to be
directed to the external IP address of the NAT box, while it would be
more efficient to route internal connections directly to the internal
IP address, without going through the NAT.  In such situations, often
the best solution is to set up a split DNS configuration.  When split
DNS is not an option, however, the @@file{sfs_hosts} mechanism will
come in handy.

@@file{sfs_hosts} is a superset of the standard @@file{/etc/hosts} file
format, that additionally allows one to specify a port number by
appending it with a @@samp{%} character at the end of the address.  By
default, the port number is 4.  For example, the following two lines
both specify that @@samp{server.domain.com} is running on port 4 of IP
address @@samp{10.1.1.1}:

@@example
10.1.1.1          server.domain.com
10.1.1.1%4        server.domain.com
@@end example

If you really want @@file{/etc/hosts} to override DNS with SFS, you can
always run @@samp{ln -s ../hosts /etc/sfs/sfs_hosts}, but this is not
recommended.  Solutions involving DNS configuration will be much more
scalable and flexible.

@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end

@@node sfs_users, sfssd_config, sfs_hosts, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfs_users}---User-authentication database
@@cindex @@file{sfs_users}

@@c @@mp
@@c @@mp @@conffile{sfs_users}{user-authentication database}
@@c @@mp @@description
The @@file{sfs_users} file, maintained and used by the
@@command{sfsauthd} program, maps public keys to local users and
groups. It is roughly analogous to the Unix @@file{/etc/passwd} and
@@file{/etc/group} files.  Each line of @@file{sfs_users} can specify a
user or a group.  Users are specified as follows (split into two
lines here only for clarity of presentation):

@@example
USER:@@var{user}:@@var{uid}:@@var{version}:@@var{gid}:@@var{owner}:@@var{pubkey}:@@var{privs}
                          :@@var{srp}:@@var{privkey}:@@var{srvprivkey}:@@var{audit}
@@end example

@@noindent
Note that the first @@samp{USER} is just the literal string
@@samp{USER}.  The rest of the fields have the following meanings:

@@table @@var
@@item user
@@var{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, it is also possible to add SFS users who do not have local
Unix accounts.  It is also possible map multiple public keys to the
same local Unix account, as when several people have an account with
root privileges.  In such cases, each key should be given a unique
name (e.g., @@samp{dm/root}, @@samp{kaminsky/root}, etc.).

@@item uid
@@var{uid} is the user's user ID on the given server.

@@item version
@@var{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.

@@item gid
@@var{gid} is the users's group ID on the given server.

@@item owner
This field is currently ignored, but in a future version may be used
to allow users to create ``guest'' accounts.

@@item pubkey
@@var{pubkey} is an ASCII, human-readable representation of the user's public
key.  Can be either a Rabin or 2-Schnorr public key.

@@item privs
The @@var{privs} field contains a comma-separated list of properties of
the account.  Possible properties are as follows:

@@table @@samp

@@item unix=@@var{account}
This property states that an SFS user corresponds to the local Unix
account @@var{account}.  In many settings, it is common to use the
@@samp{unix=} property to map every SFS user to a local Unix user of
the same name.  The @@samp{unix=} property has several consequences.
First, if there is no local Unix user named @@var{account}, this SFS
user will not be allowed to log in.  Second, when the SFS user logs
in, SFS will search @@file{/etc/group} for additional groups the user
might belong to.  Third, the @@command{rexd} remote login daemon will
allow remote login access to this account, using the shell and home
directory specified in @@file{/etc/passwd}.  Finally, on some operating
systems, SFS enforces account expiration dates specified by
@@file{/etc/shadow} or @@file{/etc/spwd.db}.

@@item admin
Indicates that this particular users has administrative privileges in
SFS.  The option has no effect unless the @@samp{Userfile} directive in
@@file{sfsauthd_config} specifies the @@option{-admin} option.  For
@@file{sfs_users} files with the @@option{-admin} option, the
@@samp{admin} privilege allows users to create and modify other user
records remotely, though currently client-side support for doing this
is limited.

@@item refresh
@@item timeout
These properties are mostly of use with @@command{sfsaclsd}, an
experimental server that is not part of the mainline SFS distribution
yet.
@@end table

@@item srp
@@var{srp} is the server-side information for the SRP protocol,
@@ref{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 @@command{sfskey add} command to
fetch the wrong @@var{HostID}.  Note also that @@var{srp} is specific to
a particular hostname.  If you change the @@var{Location} of a file
server, users will need to register new @@var{SRP}.

@@item privkey
@@var{privkey} is actually opaque to @@command{sfsauthd}.  It is
private, per-user data that @@command{sfsauthd} will return to users who
successfully complete the SRP protocol.  Currently, @@command{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.

@@item srvprivkey
If a user has chosen 2-Schnorr proactive signatures, the server's half
of the private key is kept in this field.

@@item audit
@@var{audit} contains the time, source IP address, and description of the
last update to this field.  Useful in recovering from a compromised key.

@@end table

@@noindent
Each group in @@file{sfs_users} is specified by a line with the
following format:

@@example
GROUP:@@var{group}:@@var{gid}:@@var{version}:@@var{owners}:@@var{members}:@@var{properties}:@@var{audit}
@@end example

@@noindent
Here again the first @@samp{GROUP} is just the literal string
@@samp{GROUP}, while the remaining fields have the following meanings:

@@table @@var

@@item group
The name of the group.

@@item gid
The numeric group ID.

@@item version
@@var{version} is the version number of this record in the database.
The number increments when people edit groups through the
@@command{sfskey} interface.

@@item owners
List of users who are allowed to edit the group membership list.

@@item members
List of users who are in the group.

@@item properties
Properties of the group, mostly of use with @@command{sfsaclsd}, an
experimental server that is not part of the mainline SFS distribution
yet.

@@item audit
Information about the last time this record was modified through the
@@command{sfskey} interface.
@@end table

@@file{sfs_users} files can be stored in one of three formats:  plain
ASCII, database directories, and database files.  (The latter two
require SFS to have been compiled with Sleepycat BerkeleyDB support.)
The format is determined by the extension of the file name.  File
names ending @@file{.db/} are considered database directories; file
names ending @@file{.db} are considered database files; everything else
is considered ASCII.  Only read-only and exported public databases can
be database files; read-write databases must be directories, ending
@@file{.db/}.
@@c It is highly recommended that administrators
@@c @@emph{not} use database files (as opposed to directories) for anything
@@c other than public, read-only @@file{sfs_users} files shared amongst
@@c machines.
(The reason is that read-write database files require write-ahead
logging, which relies on auxiliary files.)
@@c stored in
@@c @@file{@@value{SFSDIR}@@dslash{}dbenv}.  It is easy to forget this and
@@c rename or delete database files stored elsewhere, with the disastrous
@@c result that old log records may get applied to different files.)

You should always edit @@file{sfs_users} files using the
@@ignore
@@command{vidb}(8) command,
@@end ignore
@@c @@mp @@ignore
@@command{vidb} command (@@pxref{vidb}),
@@c @@mp @@end ignore
for two reasons.  First, whenever editing files by hand, you run the
risk of overwriting concurrent updates by @@command{sfsauthd}.
@@command{vidb} acquires the necessary locks to prevent this from
happening.  Second, when editing a database directory or file,
@@command{vidb} translates from the binary database format into the
ASCII format described above; when committing updates, it also
atomically modifies various secondary indexes that SFS relies upon.
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end


@@node sfssd_config, sfs_srp_params, sfs_users, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfssd_config}---Meta-server configuration
@@cindex @@file{sfssd_config}

@@c @@mp
@@c @@mp @@conffile{sfssd_config}{meta-server configuration}
@@c @@mp @@description
@@file{sfssd_config} configures @@command{sfssd}, the server that accepts
connections for @@command{sfsrwsd} and @@command{sfsauthd}.
@@file{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:

@@table @@samp
@@item BindAddr @@var{ip-addr} [@@var{port}]
@@anchor{BindAddr}

Explicitly specifies the IP address and port on which @@command{sfssd}
should listen for TCP connections.  To listen on @@code{INADDR_ANY},
use the value @@samp{0.0.0.0} for @@var{ip-addr}.  If @@var{port} is not
specified, @@command{sfssd} will use the value of the @@env{SFS_PORT}
environment variable, if it exists and is non-zero, or else fall back
to the default port number of 4.

It is important to note the difference between specifying a port
number with the @@env{SFS_PORT} environment variable, and with a
@@samp{BindAddr}
@@ignore
directive.  See the description of the
@@env{SFS_PORT}
environment variable in the
@@command{sfs_environ}
man page for more information.
@@end ignore
@@c @@mp @@ignore
directive (@@pxref{SFS_PORT}).
@@c @@mp @@end ignore

When no @@samp{BindAddr} directive is specified, @@command{sfssd}
attempts to figure out the appropriate port number(s) to bind to
automatically.  It does so by looking for DNS SRV records for the
current hostname (or @@env{SFS_HOSTNAME} environment variable).  This
is quite different from specifying @@samp{BindAddr 0.0.0.0 0}, which
would always bind port 4 or whatever is specified with the
@@env{SFS_PORT} environment variable.

@@c A port number of 0 means to check DNS for port numbers specified in
@@c SRV records, and to use port 4 in the common case that no SRV records
@@c are employed.  @@samp{BindAddr} can be specified multiple times to
@@c listen on multiple addresses and/or ports.

@@item RevocationDir @@var{path}
Specifies the directory in which @@command{sfssd} should search for
revocation/redirection certificates when clients connect to unknown
(potentially revoked) self-certifying pathnames.  The default value is
@@file{@@value{SFSDIR}/srvrevoke}.  Use the command @@samp{sfskey
revokegen} to generate revocation certificates.

@@item HashCost @@var{bits}
@@anchor{HashCost}
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.

@@item Server @@{* | @@@@@@var{Location}[,@@var{HostID}]@@}
Specifies a section of the file that applies connection requests for the
self-certifying pathname @@@@@@var{Location}@@samp{,}@@var{HostID}.  If
@@samp{,}@@var{HostID} is omitted, then the following lines apply to any
connection that does not match an explicit @@var{HostID} in another
@@samp{Server}.  The argument @@samp{*} applies to all clients who do not
have a better match for either @@var{Location} or @@var{HostID}.

@@item Release @@{* | @@var{sfs-version}@@}
Begins a section of the file that applies to clients running SFS release
@@var{sfs-version} or older.  @@samp{*} signifies arbitrarily large SFS
release numbers.  The @@samp{Release} directive does not do anything on
its own, but applies to all subsequent @@samp{Service} directives until
the next @@samp{Release} or @@samp{Server} directive.

@@item Extensions @@var{ext1} [@@var{ext2} @@dots{}]
Specifies that subsequent @@samp{Service} directives apply only to
clients that supply all of the listed extension strings (@@var{ext1},
@@dots{}).  @@samp{Extensions} applies until the next @@samp{Extensions},
@@samp{Release} or @@samp{Server} directive

@@item Service @@var{srvno} @@var{daemon} [@@var{arg} @@dots{}]
Specifies the daemon that should handle clients seeking service number
@@var{srvno}.  SFS defines the following values of @@var{srvno}:

@@display
1. File server
2. Authentication server
3. Remote execution
4. SFS/HTTP (not yet released)
@@end display

@@item Service @@var{srvno} -u @@var{path}
Operates as the above syntax of @@samp{Service}, only instead of
spawning a daemon, connects to the unix-domain socket specified by
@@samp{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.

@@item Service @@var{srvno} -t @@var{host} [@@var{port}]
Specifies that @@command{sfssd} should act as a ``TCP proxy'' for this
particular service, relaying any incoming connections to TCP port
@@var{port} on @@var{host}.  If unspecified, @@var{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:

@@example
server-a.mydomain.com.  IN A    4.3.2.1
server-b.mydomain.com.  IN A    4.3.2.1
@@end example

Then, on your outside machine, you might have the following
@@file{sfssd_config} file:

@@example
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
@@end example

Then on each of the internal machines, be sure to specify
@@samp{Hostname server-A.mydomain.com} and @@samp{Hostname
server-B.mydomain.com} in @@file{sfsrwsd_config}.

@@end table

@@noindent
The default contents of @@file{sfssd_config} is:

@@example
Server *
  Release *
      Service 1 sfsrwsd
      Service 2 sfsauthd
      Service 3 rexd
@@end example

@@noindent
To disable the file server, you can copy this file to
@@file{/etc@@dslash{}sfs@@dslash{}sfssd_config} and comment out the
line @@samp{Service 1 sfsrwsd}.  To disable the remote login server,
comment out the line for @@samp{rexd}.

@@noindent
To run an SFS read-only service, you could specify the lines:

@@example
Server *
  Release *
    Service 1 sfsrosd
@@end example

@@noindent
Note that you may have only one program per service number within a
Release clause.  For instance, you cannot run both @@command{sfsrosd}
and @@command{sfsrwsd} unless the programs appear in separate clauses
such as:

@@example
Server *
  Release *
      Service 1 sfsrwsd
      Service 2 sfsauthd
      Service 3 rexd

Server @@@@snafu.lcs.mit.edu,xzfeqjnareyn2dhqxccd7wrk5m847rh2
  Release *
    Service 1 sfsrosd
@@end example

@@noindent
To run a different server for sfs-0.6 and older clients, you could add
the lines:

@@example
  Release 0.6
    Service 1 /usr/local/lib/sfs-0.6/sfsrwsd
@@end example

@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end 


@@node sfs_srp_params, sfscd_config, sfssd_config, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfs_srp_params}---Default parameters for SRP protocol
@@cindex @@file{sfs_srp_params}

@@c @@mp 
@@c @@mp @@conffile{sfs_srp_params}{default parameters for SRP protocol}
@@c @@mp @@description
Specifies a ``strong prime'' and a generator for use in the SRP
protocol.  SFS ships with a particular set of parameters because
generating new ones can take a considerable amount of CPU time.  You can
replace these parameters with randomly generated ones using the
@@samp{sfskey srpgen -b @@var{bits}} command.

Note that SRP parameters can afford to be slightly shorter than Rabin
public keys, both because SRP is based on discrete logs rather than
factoring, and because SRP is used for authentication, not secrecy.

The format of the file is a single line of the form:

@@display
@@samp{N=0x}@@var{Modulus}@@samp{,g=0x}@@var{Generator}
@@end display

@@var{Modulus} is a prime number, represented in hexadecimal, which
must satisfy the property that (@@var{Modulus}-1)/2 is also prime.
@@var{Generator} is an element of the multiplicative group of integers
modulo @@var{Modulus} such that @@var{Generator} has order
(@@var{Modulus}-1)/2.

@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp @@end 


@@node sfscd_config,  , sfs_srp_params, SFS configuration
@@comment  node-name,  next,  previous,  up
@@section @@file{sfscd_config}---Meta-client configuration
@@cindex @@file{sfscd_config}

@@c @@mp
@@c @@mp @@conffile{sfscd_config}{meta-client configuration}
@@c @@mp @@description
The @@file{sfscd_config} is really part of the SFS protocol
specification.  If you change it, you will no longer be executing the
SFS protocol.  Nonetheless, you need to do this to innovate, and SFS was
designed to make implementing new kinds of file systems easy.

@@file{sfscd_config} takes the following directives:

@@table @@samp
@@item Extension @@var{string}
Specifies that @@command{sfscd} should send @@var{string} to all servers
to advertise that it runs an extension of the protocol.  Most servers
will ignore @@var{string}, but those that support the extension can
pass off the connection to a new ``extended'' server daemon.  You can
specify multiple @@samp{Extension} directives.

@@item Protocol @@var{name} @@var{daemon} [@@var{arg} @@dots{}]
Specifies that pathnames of the form
@@file{/sfs@@dslash{}@@var{name}:@@var{anything}} should be handled by the
client daemon @@var{daemon}.  @@var{name} may not contain any
non-alphanumeric characters.  The @@samp{Protocol} directive is useful
for implementing file systems that are not mounted on self-certifying
file systems.

@@item Release @@{* | @@var{sfs-version}@@}
Begins a section of the file that applies to servers running SFS release
@@var{sfs-version} or older.  @@samp{*} signifies arbitrarily large SFS
release numbers.  The @@samp{Release} directive does not do anything on
its own, but applies to all subsequent @@samp{Program} directives until
the next @@samp{Release} directive.

@@item Libdir @@var{path}
Specifies where SFS should look for daemon programs when their
pathnames do not begin with @@file{/}.  The default is
@@file{/usr/local/lib/sfs-@@value{VERSION}}.  The @@samp{Libdir}
directive does not do anything on its own, but applies to all
subsequent @@samp{Program} directives until the next @@samp{Libdir} or
@@samp{Release} directive.

@@item Program @@var{prog}.@@var{vers} @@var{daemon} [@@var{arg} @@dots{}]
Specifies that connections to servers running Sun RPC program number
@@var{prog} and version @@var{vers} should be handed off to the the local
daemon @@var{daemon}.  SFS currently defines two RPC program numbers.
Ordinary read-write servers use program number 344444, version 3 (a
protocol very similar to NFS3), while read-only servers use program
344446, version 2.  The
@@samp{Program} directive must be preceded by a @@samp{Release} directive.
@@end table

@@noindent
The default @@file{sfscd_config} file is:

@@example
Release *
  Program 344444.3 sfsrwcd
  Program 344446.2 sfsrocd
@@end example

@@noindent
To run a different set of daemons when talking to sfs-0.3 or older
servers, you could add the following lines:

@@example
Release 0.3
  Libdir /usr/local/lib/sfs-0.3
  Program 344444.3 sfsrwcd
@@end example
@@c @@mp @@end description
@@c @@mp @@end conffile
@@c @@mp

@@node Command reference, Environment variables, SFS configuration, Top
@@comment  node-name,  next,  previous,  up
@@chapter Command reference guide

@@menu
* 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
* sfsrosd::                     Daemon implementing read-only file server
* sfsauthd::                    User-authentication server
* sfsrwcd::                     Client for SFS read-write file system protocol
* nfsmounter::                  NFS mounting and unmounting daemon
@@end menu

@@node sfsagent, sfskey, Command reference, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfsagent} reference guide
@@c @@mp 
@@c @@mp @@command{sfsagent}{SFS authentication agent}{1}
@@c @@mp @@description
@@command{sfsagent} is the program users run to authenticate themselves
to remote file servers, to create symbolic links in @@file{/sfs} on the
fly, and to look for revocation certificates.  Many of the features in
@@command{sfsagent} are controlled by the @@command{sfskey} program and
described in the @@command{sfskey} documentation.

Ordinarily, a user runs @@command{sfsagent} at the start of a session.
@@command{sfsagent} runs @@command{sfskey add} to obtain a private key.
As the user touches each SFS file server for the first time, the agent
authenticates the user to the file server transparently using the
private key it has.  At the end of the session, the user should run
@@command{sfskey kill} to kill the agent.
@@c @@mp @@end description

@@c @@mp @@ignore
The usage is as follows:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
sfsagent [-dnkF] -S @@var{sock} [-c [@@var{prog} [@@var{arg} @@dots{}]] | @@var{keyname}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@options
@@table @@option
@@item -d
Stay in the foreground rather than forking and going into the background

@@item -n
Do not attempt to communicate with the SFS file system.  This can be
useful for debugging, or for running an agent on a machine that is not
running an SFS client.  If you specify @@option{-n}, you must also use
the @@option{-S} option, otherwise your agent will be useless as there
will be no way to communicate with it.

@@item -k
Atomically kill and replace any existing agent.  Otherwise, if your
agent is already running, @@command{sfsagent} will refuse to run again.

@@item -F
Turn off forwarding.  By default programs other than the file system
can ask the agent to authenticate the user.  Specifying this option
disables this functionality.

@@item -S @@var{sock}
Listen for connections from programs like @@command{sfskey} on the Unix
domain socket @@var{sock}.  Ordinarily @@command{sfskey} connects to the
agent through the client file system software, but it can use a named
Unix domain socket as well.

@@item -c [@@var{prog} [@@var{arg} @@dots{}]]
By default, @@command{sfsagent} on startup runs the command @@samp{sfskey
add} giving it whatever @@option{-t} option and @@var{keyname} you
specified.  This allows you to fetch your first key as you start or
restart the agent.  If you wish to run a different program, you can
specify it using @@option{-c}.  You might, for instance, wish to run a
shell-script that executes a @@samp{sfskey add} followed by several
@@samp{sfskey certprog} commands.

@@command{sfsagent} runs the program with the environment variable
@@env{SFS_AGENTSOCK} set to @@samp{-0} and a Unix domain socket on
standard input.  Thus, when atomically killing and restarting the agent
using @@option{-k}, the commands run by @@command{sfsagent} talk to the
new agent and not the old.

If you don't wish to run any program at all when starting
@@command{sfsagent}, simply supply the @@option{-c} option with no
@@var{prog}.  This will start an new agent that has no private keys.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp 

@@node sfskey, rex, sfsagent, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfskey} reference guide

@@c @@mp 
@@c @@mp @@command{sfskey}{SFS key manager}{1}
@@c @@mp @@synopsis
@@c @@mpp sfskey [-S @@var{sock}] [-p @@var{pwfd}] 
@@c @@mpp @@var{command} [@@var{arg} @@dots{}]
@@c @@mp @@end synopsis
@@c @@mp @@description
The @@command{sfskey} command performs a variety of key management tasks,
from generating and updating keys to controlling users' SFS agents.  The
general usage for @@command{sfskey} is:

@@example
sfskey [-S @@var{sock}] [-p @@var{pwfd}] @@var{command} [@@var{arg} @@dots{}]
@@end example

@@noindent
@@option{-S} specifies a UNIX domain socket @@command{sfskey} can use to
communicate with your @@command{sfsagent} socket.  If @@var{sock} begins
with @@samp{-}, the remainder is interpreted as a file descriptor number.
The default is to use the environment variable @@env{SFS_AGENTSOCK} if
that exists.  If not, @@command{sfskey} asks the file system for a
connection to the agent.

The @@option{-p} option specifies a file descriptor from which
@@command{sfskey} should read a passphrase, if it needs one, instead of
attempting to read it from the user's terminal.  This option may be
convenient for scripts that invoke @@command{sfskey}.  For operations
that need multiple passphrases, you must specify the @@option{-p} option
multiple times, once for each passphrase.

In SFS 0.7, two-party proactive Schnorr signatures (2-Schnorr for short)
are supported in addition to Rabin signatures.  One half of the  2-Schnorr
key is stored on the designated signature sever, while the other is stored
locally to file, or remotely via SRP.  Unlike Rabin keys, 2-Schnorr keys
can fail to load when a signature server becomes unavailable.  For this 
reason, @@command{sfskey} supports multiple private-key shares that correspond
to the same public key; this way, a user can maintain a series of backup
signature servers in case his primary server becomes unavailable.  By
default, @@command{sfskey} never stores both halves of a 2-Schnorr key
to the same machine, so as to enforce key sharing.  To this effect,
2-Schnorr employs special @@command{sfskey} commands---@@command{sfskey 2gen} 
and @@command{sfskey 2edit}. 

As of SFS 0.7, there is a new convention for saving and naming private
keys.  By default, keys will be stored locally in @@file{$HOME/.sfs/authkeys},
and will be in the following forms:

@@example
    @@var{user}@@@@@@var{host1}#@@var{n}
    @@var{user}@@@@@@var{host1}#@@var{n},@@var{p}.@@var{host2},@@var{m}
@@end example

The first form is for standard Rabin keys.  The second is for 2-Schnorr
proactive signature keys.  In the above examples, @@var{host1} is the
the full hostname of the generating host, @@var{n} is the public key
version, @@var{p} is the priority of the signing host (1 is the highest)
@@var{host2} is the full hostname of the signing host, and @@var{m} is the
private key version.  

In general, these details can remain hidden, in that the symbolic link
@@file{$HOME/.sfs/identity} points to the most recent key generated in
@@file{$HOME/.sfs/authkeys}, and most @@command{sfskey} commands have
reasonable defaults.  However, there is a command-line system for
accessing and generating specific keys.  A blank keyname and the
special keyname @@file{#} refer to the default key
@@file{$HOME/.sfs/identity} during key access and the next available
key during key generation.  Keynames containing a @@file{#} character
but not containing a @@file{/} character are assumed to refer to keys
in the @@file{$HOME/.sfs/authkeys} directory.  When given files of the
form @@file{@@var{prefix}#}, @@command{sfskey} looks in the default
directory for the most recent key with the given @@var{prefix} during key
access, and the next available key with the given @@var{prefix} during key
generation.  For keys of the form @@file{@@var{name}#@@var{suffix}},
@@command{sfskey} will look in the @@file{$HOME/.sfs/authkeys} directory
for keys that match the given name exactly. @@command{sfskey} treats
keys with @@file{/} characters as regular files; it treats keys that
contain @@file{@@@@} characters but no @@file{#} characters as keys stored
on remote machines.

Finally, one should note that SFS keys have both a @@var{keyname} 
and also a @@var{keylabel}.  @@command{sfskey} uses the former to
retrieve keys from the local file system or from remote servers.  The latter
is less important; the @@var{keylabel} is stored internally in the 
private key, and is shown in the output of the @@command{sfskey list}
command.

@@c @@mp @@end description

@@c @@mp @@options
@@table @@samp
@@item sfskey add [-t [hrs:]min] [@@var{keyname}]
@@itemx sfskey add [-t [hrs:]min] [@@var{user}]@@@@@@var{hostname}
The @@command{add} command loads and decrypts a private key, and gives
the key to your agent.  Your agent will use it to try to authenticate
you to any file systems you reference.  The @@option{-t} option specifies
a timeout after which the agent should forget the private key.

In the first form of the command, the key indicated by @@var{keyname}
is loaded.  If @@var{keyname} is omitted, or @@var{#} is supplied, then
the default key is @@file{$HOME@@dslash{}.sfs@@dslash{}identity}. If the
key supplied is a 2-Schnorr key, then @@command{sfskey add} will
attempt to load backup keys should the primary key fail due to an
unavailable signature server.

@@cindex SRP
@@anchor{SRP} The second form of the command fetches a private key over
the network using the
@@uref{http:/@@dslash{}srp.stanford.edu@@dslash{},SRP} protocol.  SRP
lets users establish a secure connection to a server without remembering
its public key.  Instead, to prove their identities to each other, the
user remembers a secret password and the server stores a one-way
function of the password (also a secret).  SRP addresses the fact that
passwords are often poorly chosen; it ensures that an attacker
impersonating one of the two parties cannot learn enough information to
mount an off-line password guessing attack---in other words, the
attacker must interact with the server or user on every attempt to guess
the password.

The @@command{sfskey update}, @@command{sfskey register}, 
@@command{sfskey 2gen} and @@command{sfskey 2edit} commands let users
store their private keys on servers, and retrieve them using the
@@command{add} command.  The private key is stored in encrypted form,
using the same password as the SRP protocol (a safe design as the server
never sees any password-equivalent data).

Because the second form of @@command{sfskey add} establishes a secure
connection to a server, it also downloads the servers HostID securely
and creates a symbolic link from @@file{/sfs/}@@var{hostname} to the
server's self-certifying pathname.

When invoking @@command{sfskey add} with the SRP syntax, @@command{sfskey}
will ask for the user's password with a prompt of the following form:

@@example
Passphrase for @@var{user}@@@@@@var{servername}/@@var{nbits}:
@@end example

@@var{user} is simply the username of the key being fetched from the
server.  @@var{servername} is the name of the server on which the user
registered his SRP information.  It may not be the same as the
@@var{hostname} argument to @@command{sfskey} if the user has supplied a
hostname alias (or CNAME) to @@command{sfskey add}.  Finally, @@var{nbits}
is the size of the prime number used in the SRP protocol.  Higher values
are more secure; 1,024 bits should be adequate.  However, users should
expect always to see the same value for @@var{nbits} (otherwise, someone
may be trying to impersonate the server).

@@item sfskey certclear
Clears the list of certification programs the agent runs.
@@xref{certprog}, for more details on certification programs.

@@item sfskey certlist [-q]
Prints the list of certification programs the agent runs.
@@xref{certprog}, for more details on certification programs.

@@cindex Dynamic server authentication
@@anchor{certprog}
@@item sfskey certprog [-p @@var{prefix}] [-f @@var{filter}] [-e @@var{exclude}] @@var{prog} [@@var{arg} @@dots{}]
The @@command{certprog} command registers a command to be run to lookup
@@var{HostID}s on the fly in the @@file{/sfs} directory.  This mechanism can be
used for @@dfn{dynamic server authentication}---running code to lookup
@@var{HostID}s on-demand.  When you reference the file
@@file{/sfs/@@var{prefix}/@@var{name}}, your agent will run the command:

@@example
@@var{prog} @@var{arg} @@dots{} @@var{name}
@@end example

If the program succeeds and prints @@var{dest} to its standard output,
the agent will then create a symbolic link:

@@example
/sfs/@@var{prefix}/@@var{name} -> @@var{dest}
@@end example

The @@option{-p} flag can be omitted, and the link is
@@samp{/sfs/@@var{name} -> @@var{dest}}.  @@var{prefix} can be more than one
directory deep (i.e., a series of path components separated by
@@samp{/}).  If so, the first certification program whose prefix matches
at the beginning of @@var{prefix} is run.  The remaining path components
are passed to @@var{prog}.  For example:

@@example
NEED EXAMPLE
@@end example

@@var{filter} is a perl-style regular expression.  If it is specified,
then @@var{name} must contain it for the agent to run @@var{prog}.
@@var{exclude} is another regular expression, which, if specified,
prevents the agent from running @@var{prog} on @@var{name}s that contain
it (regardless of @@var{filter}).

@@cindex Certification paths
@@cindex @@command{dirsearch}
The program @@command{dirsearch} can be used with @@command{certprog} to
configure @@dfn{certification paths}---lists of directories in which to
look for symbolic links to @@var{HostID}s.  The usage is:

@@example
dirsearch [-clpq] @@var{dir1} [@@var{dir2} @@dots{}] @@var{name}
@@end example

@@command{dirsearch} searches through a list of directories @@var{dir1},
@@var{dir2}, @@dots{} until it finds one containing a file called
@@var{name}, then prints the pathname @@samp{@@var{dir}/@@var{name}}.  If it
does not find a file, @@command{dirsearch} exits with a non-zero exit
code.  The following options affect @@command{dirsearch}'s behavior:

@@table @@option
@@item -c
Print the contents of the file to standard output, instead of its
pathname.

@@item -l
Require that @@samp{@@var{dir}/@@var{name}} be a symbolic link, and print
the path of the link's destination, rather than the path of the link
itself.

@@item -p
Print the path @@samp{@@var{dir}/@@var{name}}.  This is the default
behavior anyway, so the option @@option{-p} has no effect.

@@item -q
Do not print anything.  Exit abnormally if @@var{name} is not found in
any of the directories.
@@end table

As an example, to lookup self-certifying pathnames in the directories
@@file{$HOME/.sfs/known_hosts} and @@file{/mit}, but only accepting links
in @@file{/mit} with names ending @@file{.mit.edu}, you might execute the
following commands:

@@example
% sfskey certprog dirsearch $HOME/.sfs/known_hosts
% sfskey certprog -f '\.mit\.edu$' /mnt/links
@@end example

@@item sfskey confclear
Clears the confirmation program that the agent runs.
@@xref{confprog}, for more details on confirmation programs.

@@item sfskey conflist [-q]
Prints the confirmation program that the agent runs.
@@xref{confprog}, for more details on confirmation programs.

@@anchor{confprog}
@@item sfskey confprog @@var{prog} [@@var{arg} @@dots{}]
The @@command{confprog} command registers a command to be run by the agent
when it receives an authentication request.  The agent provides the program
with the following command line arguments: the machine making the request,
the machine that the requestor wants to access, the service (e.g., file
system, remote execution facility), the current key that the agent will try
signing with, and a list of all of the keys that the agent has available.
If the confirmation program returns a zero exit status, the agent will
sign with the current key; otherwise, it will refuse to sign with that key
and will try the next available one.

The confirmation program can be very simple (always answer yes, for
example), or quite complex.  SFS comes with an example confirmation program
written in Python/GTK2 (@@file{confirm.py}).  When called, the script can pop
up a dialog box which asks the user what he wants to do with the request.
The user has several options: reject, accept, accept and allow all futures
request from the requesting machine to access the named machine, accept and
allow access from requestor to any machine in the named machine's domain,
or accept and allow access from requestor to any machine.  The script saves
the user's preferences in a data file which it consults on subsequent
invocations.  If the user has chosen to accept a particular request
automatically, the script returns zero (success) without popping up a dialog
box.

Confirmation programs allow the user to manage trust policies when working
with machines that are trusted to different degrees.  For example, a user
might trust the machine on his lan but want to manually confirm requests
from machines in a shared compute cluster.

@@item sfskey delete @@var{keyname}
Deletes private key @@var{keyname} from the agent (reversing the effect
of an @@command{add} command).

@@item sfskey deleteall
Deletes all private keys from the agent.

@@item sfskey edit [-LP] [-o @@var{keyname}] [-c @@var{cost}] [-l @@var{label}] [@@var{keyname}]
Changes the passphrase, passphrase ``cost'', or name of a public key.
Can also download a key from a remote server via SRP and store it in a
file.

@@var{keyname} can be a file name, or it can be of the form
@@samp{[@@var{user}]@@@@@@var{server}}, in which case @@command{sfskey} will
fetch the key remotely and @@var{outfile} must be specified.  If
@@var{keyname} is unspecified the default is @@file{$HOME/.sfs/identity}.
If @@var{keyname} is @@file{#}, then @@command{sfskey edit} will search
for the next appropriate keyname in @@file{$HOME/.sfs/authkeys}.  In this case,
@@command{sfskey edit} will update @@file{$HOME/.sfs/identity} to point to
this new key by default.

The options are:

@@table @@option
@@item -L
Does not set symlink in the case that @@var{keyname} is @@file{#}.

@@item -P
Removes any password from the key, so that the password is stored on
disk in unencrypted form.

@@item -o @@var{keyname}
Specifies the file to which the edited key should be written.  A
@@var{keyname} of @@file{#} implies that @@command{sfskey edit} should
generate the next available default key in @@file{$HOME/.sfs/authkeys}.
A @@var{keyname} of the form @@file{@@var{prefix}#} implies that
@@command{sfskey edit} should generate the next available key in
@@file{$HOME/.sfs/authkeys} with the prefix @@var{prefix}.  A @@var{keyname}
of the form @@file{@@var{prefix}#@@var{suffix}} implies that 
@@command{sfskey edit} should make a key named 
@@file{$HOME/.sfs/authkeys/@@var{prefix}#@@var{suffix}}.

@@item -c @@var{cost}
Override the default computational cost of processing a password, or
@@samp{PwdCost}, @@ref{pwdcost}.

@@item -l @@var{label}
Specifies the label of the key that shows up in @@command{sfskey list}.
@@end table

@@item sfskey 2edit -[Smp] [-l @@var{label}] [-S | -s @@var{srpfile}] [@@var{keyname1} @@var{keyname2} ...]
Refreshes a 2-Schnorr key by re-sharing a secret between a server
and a client. In the case of a compromised client or server, it is 
recommended to refresh a 2-Schnorr key with this command.  If both
the client and the server have been compromised, a refresh will be 
of little use.

Use @@command{sfskey 2edit} by supplying the keys that you wish to have
updated.  Keynames are given in standard @@command{sfskey} style.  Keynames
must be either remote keynames (i.e., contain a @@file{@@@@} but no @@file{#}
character) or stored in the standard keys directory (i.e., contain a @@file{#}
but no @@file{/} character).  For remote keys, SRP will be used to 
download the key from the server, and the updated, encrypted client private
keyhalf will be written back to the server along with the new server
keyhalf.  No file will be saved locally.  For keys stored in 
@@file{$HOME/.sfs/authkeys}, @@command{sfskey 2edit} will update the
server private keyhalf, and write the corresponding client private
keyhalf out to @@file{$HOME/.sfs/authkeys} under a new filename.  By default,
@@command{sfskey 2edit} will also write the new encrypted client private
keyhalf back to the server for later SRP retrieval.

If no key is specified, the default key, @@file{$HOME/.sfs/identity} is 
assumed.

@@table @@option
@@item -E
Do not update the encrypted private client key stored on the server.

@@item -S
Do not update SRP information on the server.  This option cannot be used
if some of the keynames specified are for remote keys.

@@item -m
Refresh multiple keys.  If you have multiple private splits of the same
private key, this flag will automatically update them all, given that
you've specified one of them.  If you run @@command{sfskey 2edit -m},
with no additional arguments or keynames, @@command{sfskey} will refresh
all current default keys.

@@item -p
Change password before writing keys out to disk or server.

@@item -l @@var{label}
Specifies the label of the key that shows up in @@command{sfskey list}.

@@item -s @@var{srpfile}
Get SRP parameters from the file @@var{srpfile}.
@@end table

@@item sfskey gen [-KP] [-b @@var{nbits}] [-c @@var{cost}] [-l @@var{label}] [@@var{keyname}]
Generates a new Rabin public/private key pair and stores it in @@var{keyname}.
It omitted @@var{keyname} defaults to the next available Rabin key
in @@file{$HOME/.sfs/authkeys}.  If @@var{keyname} contains a @@file{/} 
character, it will be treated as a regular Unix file.  If @@var{keyname}
is of the form @@file{@@var{prefix}#}, @@command{sfskey gen} will look for
the next available Rabin key in @@file{$HOME/.sfs/authkeys} with the
prefix @@var{prefix}.  If @@var{keyname} contains a non-terminal @@file{#}
character, it will be treated as a fully-specified keyname to be saved in 
@@file{$HOME/.sfs/authkeys}.

Note that @@command{sfskey gen} is only useful for generating Rabin keys.
Use either @@command{sfskey register} or @@command{sfskey 2gen} to
generate 2-Schnorr keys.

@@table @@option
@@item -K
By default, @@command{sfskey gen} asks the user to type random text with
which to seed the random number generator.  The @@option{-K} option
suppresses that behavior.

@@item -P
Specifies that @@command{sfskey gen} should not ask for a passphrase and
the new key should be written to disk in unencrypted form.

@@item -b @@var{nbits}
Specifies that the public key should be @@var{nbits} long.

@@item -c @@var{cost}
Override the default computational cost of processing a password, or
@@samp{PwdCost}, @@ref{pwdcost}.

@@item -l @@var{label}
Specifies the label of the key that shows up in @@command{sfskey list}.
Otherwise, the user will be prompted for a name.
@@end table

@@item sfskey 2gen [-BEKP] [-a @@{@@var{hostid} | -@@}] [-b @@var{nbits}] [-c @@var{cost}] [-k @@var{okeyname}] [-l @@var{label}] [-S | -s @@var{srpfile}] [-w @@var{wkeyfile}] [@@var{nkeyname}] 
Generates a new 2-Schnorr keypair for each of the servers specified by
the @@option{-a} flag.  All keypairs will correspond to the same
public key.  The new keys will be saved locally to the files given
by @@var{nkeyname} in the usual fashion: if @@var{nkeyname} is of the
form @@var{prefix}#, then @@command{sfskey 2gen} will look for the next
available 2-Schnorr key in @@file{$HOME/.sfs/authkeys} with the prefix
@@var{prefix}.  If no @@var{nkeyname} is given, it will find the next
available keyname in @@file{$HOME/.sfs.authkeys} with the default
prefix (@@var{user}@@@@@@var{host}).

Note that by default, this operation will update the public key, the
encrypted private key, the SRP information, and the server private key
share on all of the servers given.  Specify @@option{-BES} to suppress
updates of these fields.

@@table @@option
@@item -a -
@@item -a @@var{hostid}
Can be specified arbitrarily many times, once for each server that will
accept the server private half of the 2-Schnorr key being generated.  Note
that the same public key will be used for all servers.  To specify the local
host, use the first syntax.  If SRP is used to download a key from host 
@@var{host} (e.g., @@option{-k @@var{user}@@@@@@var{host}}), then you can specify
that host by its simple hostname (e.g., @@option{-a @@var{host}}).  If SRP 
was not used to connect to a host @@var{host}, then @@option{-a} requires
a complete SFS host identifier (i.e., @@@@@@var{Location},@@var{HostID}).

@@item -B
Do not update the public key on the given servers.

@@item -E
Do not update the encrypted private key field on the given servers.

@@item -K
@@itemx -P
@@itemx -c @@var{cost}
@@itemx -l @@var{label}
@@itemx -s @@var{srpfile}
See @@command{sfskey gen}.  These options behave similarly.

@@item -S
Do not update the SRP information on the server.

@@item -b @@var{nbits}
Specifies the number of bits for the 2-Schnorr modulus p.  The security of
2-Schnorr is related to the discrete log problem over Z_p*; values over 1024
are suggested for this parameter, and reasonable defaults are chosen if
this parameter is not specified.

@@item -k @@var{keyname}
Specify this option arbitrarily many times to keys into memory for
@@command{sfskey}.  By default, all keys from @@file{$HOME/.sfs/authkeys}
are loaded and hashed.  Remote keys and local keys in non-standard 
locations can be loaded into the hash with this option.  The keys
will in turn be used to authenticate you to the servers that you 
intend to update.

@@item -w @@var{wkeyfile}
Save the complete Schnorr key (both halves) to the file given.  Note
that it is possible to non-interactively sign with this key, so it is
advised that it not be stored on network-accessible media.  The
intended use for this option is to allow saving of both halves to a 
floppy disk or to a CD-R, so that in a worst case scenario, the original
key is still recoverable.
@@end table

@@item sfskey gethash [-6p] @@var{keyname}
Retrieves a public key specified by @@var{keyname}, which can be local (from
a local file) or remote (from an authentication server).  Remote @@var{keyname}s
can contain fully-specified self-certifying hostnames, or simple DNS names.  In
the latter case, @@command{sfskey} uses SRP to establish a secure connection to
the authentication server.

@@table @@option
@@item -6
Display the hash in base-64 encoding.
@@end table

@@item sfskey group [-a @@var{key}] [-E] [-C] [-L @@var{version}] [-m @@{+|-@@}@@var{membername}] [-o @@{+|-@@}@@var{ownername}] @@var{groupname}
Retrieves, creates, and modifies group lists on an authentication server.
@@var{groupname} is the name of the group, which can take an optional DNS
hostname or self-certifying hostname.  Given a simple DNS hostname, the
server will attempt SRP to retrieve the server's public key.  Using the
@@option{-a} is another way to retrieve the key.

With no options, @@command{sfskey} will query the authentication server for
the group and print out the result.  The group owners and members listed
will be exactly as they appear in the authentication server's database.
The various options are described below.

@@table @@option
@@item -a @@var{key}
This option can be supplied arbitrarily many times, once for each key that
should be loaded into @@command{sfskey} for this session.  Keynames are
specified as described above, and can be remote (via SRP) or the path to a
local file.  Usually it will not be necessary to specify keys in the keys
directory (@@file{$HOME/.sfs/authkeys}) as they are considered automatically.

@@item -E
With this option, @@command{sfskey} will ask the authentication
server to ``expand'' the owners and members lists first by computing the
transitive closure of all groups and remote users.  The expanded group
will contain only public key hashes and user names (local to the remote
authentication server).

@@item -C
This option tells @@command{sfskey} to create a new group called
@@var{groupname}.  If the group already exists, @@command{sfskey} returns
an error.

@@item -L
This option tells @@command{sfskey} to retrieve a group's changelog beginning
at version @@var{version} up through the most recent version.  The changelog
contains the updates made to the group's members list, plus the group's
current refresh and timeout values.

@@item -m @@{+|-@@}@@var{membername}
@@itemx -o @@{+|-@@}@@var{ownername}
This option tells @@command{sfskey} to add (+) or subtract (-) the given
member or owner name to or from the given group.  @@var{membername}s and 
@@var{ownername}s must be of the form "u=<user>", "g=<group>" or 
"p=<pkhash>".  The "<user>" and "<group>" names can be local or remote,
but remote names must contain the fully-qualified self-certifying hostname.
Duplicate member names and owner names are removed from the group before
it is updated.  Removals of names that don't exists on the given list
are ignored.  This option may be given more than once.
@@end table

@@item sfskey help
Lists all of the various @@command{sfskey} commands and their usage.

@@item sfskey hostid @@var{Location}
@@itemx sfskey hostid @@var{Location}@@t{%}@@var{port}
@@itemx sfskey hostid -
Retrieves a self-certifying pathname insecurely over the network and
prints @@samp{@@@@@@var{Location},@@var{HostID}}
or @@samp{@@@@@@var{Location}@@t{%}@@var{port},@@var{HostID}} to standard output.  If
@@var{Location} is simply @@samp{-}, returns the name of the current
machine, which is not insecure.

@@table @@option
@@item -s @@var{service}
The default service is file service, @@samp{sfs} (except when using
@@samp{-}).  This option selects a different SFS service.  Possible
values for @@var{service} are @@samp{sfs}, @@samp{authserv}, and
@@samp{rex}.
@@end table

@@item sfskey kill
Kill the agent.

@@item sfskey list [-ql]
List the public keys whose private halves the the agent holds.

@@table @@option
@@item -q
Suppresses the banner line explaining the output.

@@item -l
Lists the actual value of public keys, in addition the the names of the
keys.
@@end table

@@item sfskey norevokeset @@var{HostID} @@dots{}

@@item sfskey norevokelist

@@item sfskey passwd [-Kp] [-S | -s @@var{srpfile}] [-b @@var{nbits}] [-c @@var{cost}] [-l @@var{label}] [@@var{arg1}] [@@var{arg2}] ...
@@anchor{sfskey passwd}
The @@command{sfskey passwd} command is a high-level command for ``changing
passwords'' in SFS.  In the case of proactive keys, @@command{sfskey passwd}
will simply refresh keys via @@command{sfskey 2edit} functionality.  In
the case of Rabin keys, @@command{sfskey passwd} generates a new Rabin
key and updates the given servers. By default, @@command{sfskey passwd}
assumes standard Rabin keys, and thus treats @@var{arg-i} as 
[@@var{user}][@@@@]@@var{host} arguments.  If @@var{host} is a regular 
hostname, then SRP will be required to authenticate the host.  If @@var{host}
is a full SFS pathname, then @@command{sfskey passwd} will look for keys
in @@file{$HOME/.sfs/authkeys} that can authenticate the user to that particular
server.  In the case of proactive 2-Schnorr keys, @@command{sfskey passwd}
will treat @@var{arg-i} as local or remote keynames.

If no options or arguments are given, @@command{sfskey passwd} will look
to the default key given by @@file{$HOME/.sfs/identity}.  If the default key
is a proactive 2-Schnorr key, then all current 2-Schnorr keys in 
@@file{.sfs/authkeys} are refreshed.  If the default key is a Rabin key,
then the users key on the local machine is updated.

@@table @@option

@@item -p
Specifies proactive mode.  Will treat arguments @@var{arg1} through 
@@var{arg-n} as keynames, whether local or remote.  By default,
@@command{sfskey passwd} operates under the assumption that the key to 
update is a Rabin key.

@@item -K
@@itemx -S
@@itemx -s @@var{srpfile}
@@itemx -b @@var{nbits}
@@itemx -c @@var{cost}
@@itemx -l @@var{label}
These options are the same as for @@command{sfskey gen}.  Briefly,
@@option{-S} turns of SRP, @@option{-K} disables keyboard randomness 
query, @@option{-s} is used to supply an SRP parameters file and is
mutually exclusive with @@option{-S}, @@option{-b} specifies the 
size of the key in bits, @@option{-c} specifies the secret key 
encryption cost, and @@option{-l} specifies the label for the key,
as seen in @@command{sfskey list}.
@@end table


@@item sfskey register [-fgpPK] [-S | -s @@var{srpfile}] [-b @@var{nbits}] [-c @@var{cost}] [-u @@var{user}] [-l @@var{label}] [-w @@var{filename}] [@@var{keyname}]
@@anchor{sfskey register}
The @@command{sfskey register} command lets users who are logged into an
SFS file server register their public keys with the file server for the
first time.  Subsequent changes to their public keys can be
authenticated with the old key, and must be performed using
@@command{sfskey update} or @@command{sfskey 2gen}.  The superuser can also use
@@command{sfskey register} when creating accounts.

@@var{keyname} is the private key to use.  If @@var{keyname} does not exist and 
is a pathname, @@command{sfskey} will create it.  The default @@var{keyname} is
@@file{$HOME/.sfs/identity}, unless @@option{-u} is used, in which case
the default is to generate a new key in the current directory.  For keys
that contain the special trailing character @@file{#}, @@command{sfskey}
will implicitly determine whether the user intends to generate or access
a key.  If the command is invoked as root with the @@option{-u} flag, then
generation is assumed.  Similarly, if any of the options @@option{-bcgp}
are used, generation is assumed.  Otherwise, @@command{sfskey} will first
attempt to access the most recent key matching @@var{keyname}, and then will 
revert to generation if the access fails.

If a user wishes to reuse a public key already registered with another
server, the user can specify @@samp{@@var{user}@@@@@@var{server}} for
@@var{keyname}.

@@table @@option
@@item -f
Force reregistration.  Ordinarily, @@command{sfskey gen} will fail if a 
record for the given user already exists on the server.  

@@item -g
Force key generation.  When using keynames of the form
@@file{@@var{prefix}#}, @@command{sfskey register} will always generate
then next available key with the prefix @@var{prefix} in the standard
keys directory (@@file{$HOME/.sfs/authkeys}).  If @@command{sfskey
register} is being run as root with the @@option{-u} option, then
access to the standard keys directory @@file{$HOME/.sfs/authkeys} will
not be allowed.  Hence, the key will simply be generated in the
current directory.

@@item -p
Generate a new proactive 2-Schnorr key.  Implies the @@option{-g} flag.

@@item -K
@@itemx -P
@@itemx -l @@var{label}
@@itemx -b @@var{nbits}
@@itemx -c @@var{cost}
@@itemx -s @@var{srpfile}
These options are the same as for @@command{sfskey gen}.  @@option{-K} and
@@option{-b} have no effect if the key already exists.  They all imply the
@@option{-g} flag. If @@option{-p} is given, then @@var{-b} will specify
the size of the modulus @@var{p} used in 2-Schnorr.  Without @@option{-p},
@@option{-b} will specify the size of @@var{pq} in Rabin.

@@item -S
Do not register any SRP information with the server---this will prevent
the user from using SRP to connect to the server, but will also prevent
the server from gaining any information that could be used by an
attacker to mount an off-line guessing attack on the user's password.

@@item -u @@var{user}
When @@command{sfskey register} is run as root, specifies a particular
user to register.  

@@item -w @@var{filename}
When generating a proactive key, saves the complete key out to 
the given file.  Will raise an error if supplied without the @@option{-p}
flag.  For security reasons, this should only be used when saving to
removable media (e.g., @@file{/floppy/complete-key-2}).  It is a substantial
security risk to leave the complete key on a file system that might
be compromised.
@@end table

@@file{sfsauthd_config} must have a @@samp{Userfile} with the
@@option{-update} and @@option{-passwd} options to enable use of the 
@@command{sfskey register}, @@ref{sfsauthd_config}.

@@item sfskey reset
Clear the contents of the @@file{/sfs} directory, including all symbolic
links created by @@command{sfskey certprog} and @@command{sfskey add}, and
log the user out of all file systems.

Note that this is not the same as deleting private keys held by the
agent (use @@command{deleteall} for that).  In particular, the effect of
logging the user out of all file systems will likely not be
visible---the user will automatically be logged in again on-demand.

@@item sfskey revokegen [-r @@var{newkeyfile} [-n @@var{newhost}]] [-o @@var{oldhost}] @@var{oldkeyfile}

@@item sfskey revokelist

@@item sfskey revokeclear

@@item sfskey revokeprog [-b [-f @@var{filter}] [-e @@var{exclude}]] @@var{prog} [@@var{arg} @@dots{}]

@@item sfskey select [-f] @@var{keyname}
Select the given key as the default key; set @@file{$HOME/.sfs/identity}
to point to the key given by @@var{keyname}.  It cannot be an SRP key.

@@table @@option
@@item -f
Force overwrite.  If current @@file{$HOME/.sfs/identity} is a regular
file, @@command{sfskey select} will overwrite it.
@@end table


@@item sfskey sesskill @@var{remotehost}
Kill the @@command{rex} session to the server specified by @@var{remotehost},
where @@var{remotehost} is any unique prefix of the remote host's
self-certifying hostname (found under the "TO" column in the output to
@@command{sfskey sesslist}).

@@item sfskey sesslist
List the @@command{rex} sessions that the agent is maintaining.

@@item sfskey srpgen [-b @@var{nbits}] file
Generate a new @@file{sfs_srp_params} file, @@ref{sfs_srp_params}.

@@item sfskey srpclear
Clears the in-memory cache of server self-certifying hostnames built
from SRP results.  @@xref{srplist}, for more details on this cache.

@@anchor{srplist}
@@item sfskey srplist
Prints the in-memory cache of server self-certifying hostnames
built from SRP results.  This cache maps SRP names to self-certifying
hostnames.  SRP names are of the form @@file{user@@@@host}.  Sample output
of the @@command{sfskey srplist} command might be

@@example
% sfskey srplist
alice@@@@pdos.lcs.mit.edu      @@@@amsterdam.lcs.mit.edu,bkfce6jdbmdbzfbct36qgvmpfwzs8exu
alice@@@@redlab.lcs            @@@@redlab.lcs.mit.edu,gnze6vwxtwssr8mc5ibae7mtufhphzsk
alice@@@@ludlow.scs.cs.nyu.edu @@@@ludlow.scs.cs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz
@@end example

Currently, the agent consults this cache and adds new mappings to it
when a user invokes REX with a DNS (SRP) name.  If the name is in the
agent's cache, REX will use the corresponding self-certifying hostname
to authenticate the server.  If not, REX will use SRP to fetch the
server's public key and then add a new mapping to the agent's cache.

@@item sfskey srpcacheprogclear
Clears the SRP cache management program that the agent runs.
@@xref{srpcacheprog}, for more details on cache management programs.

@@item sfskey srpcacheproglist [-q]
Prints the SRP cache management program that the agent runs.
@@xref{srpcacheprog}, for more details on confirmation programs.

@@anchor{srpcacheprog}
@@item sfskey srpcacheprog @@var{prog} [@@var{arg} @@dots{}] The
@@command{srpcacheprog} command registers a command to be run by the agent in
order to manage an on-disk copy of the in-memory SRP name cache (described
above; @@pxref{srplist}).  The agent will invoke the SRP cache management
program with zero arguments when it wants to load the on-disk cache into
memory and exactly one argument when it wants to add a new entry to the
on-disk cache.  If no SRP cache management program is set, the agent will
simply maintain an in-memory version which will be lost when the agent
is restarted.

In the first case (load), the program output must consist of one
mapping per line.  Each mapping must consist of the SRP name followed
by a single space followed by the self-certifying
hostname. @@xref{srplist}, for an example of what each of these fields
might look like.  In the second case (store), the agent's argument to
the program will consist of a single mapping, to be added to the
on-disk cache.  The mapping will have the same format described above:
the SRP name followed by a single space followed by the
self-certifying hostname (no trailing newline).

@@item sfskey update [-fE] [-S | -s @@var{srp_params}] [-r @@var{srpkey}] [-a @@var{okeyname}] [-k @@var{nkeyname}] @@var{server1} @@var{server2} ...
Change a user's public key and SRP information on an SFS file server.
To change public keys, typically you should generate a new public key
and store it in @@file{$HOME/.sfs/identity}.  Then you can run
@@samp{sfskey update [@@var{user}]@@@@@@var{host}} for each server on which
you need to change your public key.

To authenticate you to the servers on which updates are requested,
@@command{sfskey update} will first use the keys given via @@option{-a}
arguments; it will then search keys in the standard key 
directory---@@file{$HOME/.sfs/authkeys}.

At least one @@var{server} argument is required.  As usual, the string 
``-'' denotes the localhost. The servers specified can be either 
full SFS hostnames of the form [@@var{user}]@@@@@@var{Location},@@var{HostId},
or standard hostnames of the form [@@var{user}@@@@]@@var{Location}.  In the
latter case, SRP is assumed, and the corresponding private key is 
automatically loaded into @@command{sfskey}.

The new key that is being pushed to the server is given by the
@@option{-k} flag.  If this is not provided, the default key
@@file{$HOME/.sfs/identity} will be assumed.

The @@option{-r} provides a shortcut for updating SRP information, if, 
for instance, the authserver has changed its realm information.  Invoking
@@command{sfskey update @@option{-r} [@@var{user}]@@@@@@var{host}} is
equivalent to @@command{sfskey update -k [@@var{user}]@@@@@@var{host} @@var{host}}.

Several options control @@command{sfskey update}'s behavior:

@@table @@option
@@item -E
Do not send encrypted secret key information to the server.

@@item -S
Do not send SRP information to the server---this will prevent the user
from using SRP to connect to the server, but will also prevent the
server from gaining any information that could be used by an attacker to
mount an off-line guessing attack on the user's password.  Implies 
@@option{-E}

@@item -a @@var{okeyname}
This option can be supplied arbitrarily many times, once for each key that
should be loaded into @@command{sfskey} for this session.  Keynames are
specified as described above, and can be remote (via SRP) or the path to a
local file.  Usually it will not be necessary to specify keys in the keys
directory (@@file{$HOME/.sfs/authkeys}) as they are considered automatically.

@@item -f
If there is a change in SRP realm information, the @@option{-f} flag
will force an update.  Normally, the user is prompted to verify.

@@item -k @@var{nkeyname}
Specifies the new key to push to the server. Can be an SRP key,
a local file, or a keyname with a '#' sign, signifying a key
stored in the keys directory, @@file{$HOME/.sfs/authkeys}. If this
flag is not specified, @@file{$HOME/.sfs/identity} is assumed.
Note that the @@option{-k} flag can be specified only once.

@@item -r [@@var{user}][@@@@]@@var{host}
Update SRP information of a key on a remote host. Equivalent to
@@command{sfskey update -k [@@var{user}]@@@@@@var{host} [@@var{user}@@@@]@@var{host}}.
Cannot be used with the @@option{-akS} options.

@@item -s
@@var{srp_params} is the path of a file generated by @@command{sfskey
srpgen}, and specifies the parameters to use in generating SRP
information for the server.  The default is to get SRP parameters from
the server, or look in
@@file{@@value{PKGDATADIR}@@dslash{}sfs_srp_params}.
@@end table

@@item sfskey user [-a @@var{key}] @@var{username}
Retrieves a user record from an authentication server.
@@var{username} is the name of the user, which can take an optional DNS
hostname or self-certifying hostname.  Given a simple DNS hostname, the
server will attempt SRP to retrieve the server's public key.  Using the
@@option{-a} is another way to retrieve the key.

@@command{sfskey} will query the authentication server for the user and
print out the result.  

@@table @@option
@@item -a @@var{key}
This option can be supplied arbitrarily many times, once for each key that
should be loaded into @@command{sfskey} for this session.  Keynames are
specified as described above, and can be remote (via SRP) or the path to a
local file.  Usually it will not be necessary to specify keys in the keys
directory (@@file{$HOME/.sfs/authkeys}) as they are considered automatically.
@@end table

@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp

@@node rex, dirsearch, sfskey, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{rex} reference guide

@@c @@mp
@@c @@mp @@command{rex}{remote execution}{1}
@@c @@mp @@synopsis
@@c @@mpp rex [-TAXpv] [-R @@var{port}:@@var{lport}] 
@@c @@mpp @@var{destination} [@@var{command}]
@@c @@mp @@end synopsis
@@c @@mp @@description
@@command{rex} is a remote execution facility which is integrated with
SFS.  The program allows users run to run programs on a remote machine
or obtain a shell.  Like SFS file systems, remote execution servers can
be named by self-certifying path names.

@@noindent
The usage is as follows:

@@example
rex [-TAXpv] [-R @@var{port}:@@var{lport}] @@var{destination} [@@var{command}]
@@end example

@@noindent
@@var{destination} is one of the following:
@@itemize @@bullet
@@item a self-certifying hostname (location:hostid)
@@item a self-certifying pathname (/sfs/... or /symlink-to-sfs/...)
@@item any identifier which when processed through certification programs
will yield a self-certifying pathname
@@end itemize
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -T
Disable pseudo-tty allocation.

@@item -A
Disable SFS agent forwarding.  By default, if there is no
@@command{sfsagent} running on the remote machine, @@command{rex} will
forward agent requests back to the @@command{sfsagent} running on the
local machine (e.g., when a user accesses an SFS file system or runs
@@command{sfskey}).

@@item -X
Disable X forwarding.  By default, the @@command{rex} client will set up
a dummy X server which receives connections from clients on the remote
machine.  These connections are forwarded over the encrypted
@@command{rex} channel to the local X server.  @@command{rex} sets the
@@env{DISPLAY} environment variable appropriately on the remote side.
Furthermore, X connections are authenticated using a `spoofed'
@@var{MIT-MAGIC-COOKIE-1}.

@@item -p
Force @@command{rex} to connect to the @@var{destination} even if
it cannot be resolved into a valid self-certifying path name.

@@item -v
Verbose mode.

@@item -R @@var{port}:@@var{lport}
Forward TCP connections made to @@var{port} on the remote host to 
@@var{lport} on the local machine.
@@end table

The @@command{rex} command supports the escape sequences listed below.
Rex only recognizes the escape character `~' after a newline.
@@itemize
@@item . terminate connection
@@item ^Z suspend connection
@@item ? help message
@@item ~ send the escape character
@@end itemize
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node dirsearch, newaid, rex, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{dirsearch} command
@@cindex @@command{dirsearch}

@@c @@mp
@@c @@mp @@command{dirsearch}{search for file in directories}{1}
@@c @@mp @@description
@@command{dirsearch} looks for a file name in one or more directories.
@@c @@mp @@end description
@@c @@mp @@ignore
The usage is as follows:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
dirsearch [-c | -l | -p | -q] @@var{dir1} [@@var{dir2} ...] @@var{name}
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
Starting with @@var{dir1}, the command searches each directory
specified for a file called @@var{name}.  If such a file is found,
@@command{dirsearch} exits with code 0 and, depending on its options,
may print the file's pathname, contents, or expanded symbolic link
contents.  If none of the directories specified contain a file
@@var{name}, @@command{dirsearch} exits with code 1 and prints no
output.
@@c @@mp @@end description

@@c @@mp @@examples
@@command{dirsearch} is particularly useful for SFS certification
@@pxref{certprog} and revocation programs.  As an example, suppose you
have a directory of symbolic links in your home directory called
@@file{.sfs@@dslash{}bookmarks}.  The directory might contain the
following links:
@@example
sfs.fs.net -> /sfs/@@@@sfs.fs.net,uzwadtctbjb3dg596waiyru8cx5kb4an
sfs.nyu.edu -> /sfs/@@@@sfs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz
@@end example
@@noindent
If you execute the command:
@@example
sfskey certprog dirsearch -l ~/.sfs/bookmarks
@@end example
@@noindent
Then the next time you access @@file{/sfs@@dslash{}sfs.fs.net}, that
pathname will automatically become a symbolic link to your bookmark.
Moreover, the same will happen on remote machines to which you log in
with the @@command{rex} command.
@@c @@mp @@end examples

@@c @@mp @@options
The following mutually exclusive options affect the behavior of
@@command{dirsearch}.  If more than one option is specified, only the
last will have an effect.

@@table @@option
@@item -c
This option prints the contents of the file when it is found, instead
of its pathname.

@@item -l
This option looks for symbolic links.  The file @@var{name} will be
ignored if it is not a symbolic link.  Furthermore, in its output
@@command{dirsearch} will expand the symbolic link.

@@item -p
This option says to print the pathname, which is the default anyway.
Thus, the only effect of @@option{-p} is to undo any previous
@@option{-c}, @@option{-l}, or @@option{-q} option.

@@item -q
This option suppresses any output @@command{dirsearch} would print.
The exit code still indicates whether or not the file exists.
@@end table
@@c @@mp @@end options


@@c @@mp @@end command
@@c @@mp @@end

@@node newaid, ssu, dirsearch, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{newaid} command

@@c @@mp
@@c @@mp @@command{newaid}{Run processes with different sfsagents}{1}
@@c @@mp @@description
The @@command{newaid} command allows root-owned processes to access SFS
file systems using the @@command{sfsagent} of a non-root user.
Additionally, if a system is configured to allow this,
@@command{newaid} permits non-root users to run multiple
@@command{sfsagent} processes, so that different processes owned by
that user access the SFS file system with different agents.  (When
used in The latter mode, @@command{newaid} is similar in function to
the AFS program @@command{pagsh}.)

@@cindex aid
SFS maps file system requests to particular @@command{sfsagent}
processes using the notion of agent ID, or @@dfn{aid}.  Every process
has a 64-bit aid associated with it.  Ordinarily, a process's aid is
simply its 32-bit user ID.  Thus, when a user runs @@command{sfsagent},
both the agent and all of the users' processes have the same aid.

To allow different processes owned by the same user to have different
agents, a system administrator can reserve a range of group IDs for
the purpose of flagging different aids, @@ref{resvgids}.
@@ignore
See the ResvGids directive described in the @@file{sfs_config} man
page for a description of how to do this.
@@end ignore
(Note that after changing @@samp{ResvGids}, you must kill and restart
@@command{sfscd} for things to work properly.)  If the range of
reserved group IDs is @@var{min}@@dots{}@@var{max}, and the @@emph{first}
element of a process's grouplist, @@var{g0}, is at least @@var{min} and
not more than @@var{max}, then a process's aid is computed as
((@@var{g0} - @@var{min} + 1) << 32) | @@var{uid}).  The @@command{newaid}
command therefore lets people insert any of the reserved group IDs at
the start of a process's group list.

For root-owned processes, it is also possible for processes to be
associated with a non-root agent.  In this case, the reserved
@@var{sfs-group} (as a marker) and target user's uid are actually
placed in the process's grouplist, as well as any reserved group ID to
select amongst multiple agents of the same user.
@@c @@mp @@end description

@@c @@mp @@ignore
The usage is:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
newaid [-l] [-@@{u|U@@} @@var{uid}] [-G | -g @@var{gid}] [-C @@var{dir}] [@@var{program} @@var{arg} ...]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description

After making appropriate changes to its user ID and/or grouplists,
@@command{newaid} executes the @@var{program} specified on the command
line.  If no @@var{program} is specified, the program specified by the
environment variable @@env{SHELL} is used by default.
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -l
Run the command as a login shell.  This argument simply prepends a
@@samp{-} character to @@code{argv[0]} when executing @@var{program}.
Command shells interpret this to mean that they are being being run as
login shells, and usually exhibit slightly different behavior.  (For
example @@command{csh} will execute the commands in a user's
@@file{.login} file.)

@@item -u @@var{uid}
For root-owned process, specifies that the @@var{program} should be run
as root, but should be associated with the non-root agent of user
@@var{uid}.

@@item -U @@var{uid}
When @@command{newaid} is invoked by a root-owned processes, this
option sets the real uid to @@var{uid} to run @@var{program}, instead of
running it with uid 0.  This is in itself is not sufficient to ``drop
privileges.''  In particular, @@command{newaid} still does not make any
changes to the process gid or grouplist, beyond manipulating
aid-specific groups.  Since many root-owned processes also have
privileged groups in their grouplist, it is in general
@@strong{insecure} to use @@option{-U} unless you set both the gid and
the whole grouplist to something sensible (i.e., appropriately
unprivileged) before invoking @@command{newaid}.

This option is mostly of use for @@command{login}-like programs that
wish to create a session with a new aid, and do not wish to make the
@@code{setuid} system call themselves.  As an example, the
@@command{rexd} daemon has the server's private key, yet must spawn the
@@command{proxy} program as an unprivileged user.  If it dropped
privileges before executing @@command{proxy}, unprivileged users could
send it signals, risking core dumps.  Moreover, attackers might be
able to exploit weaknesses in the operating system's @@code{ptrace}
system call or @@file{/proc} file system to learn the private key.
@@command{rexd} therefore runs @@command{proxy} through
@@command{newaid}, giving it the @@option{-U} option.

@@item -g @@var{gid}
@@itemx -G
By default @@command{newaid} simply picks the first aid under which no
agent is yet running.  The @@option{-g} option explicitly specifies
that @@var{gid} should be added to the start of the process's group
list (and any previous reserved gid should be removed).  @@option{-G}
says to remove any reserved gid, so that the aid of the resulting
process will just be the user's uid.

@@item -C @@var{dir}
Changes directory to @@var{dir} before running @@var{program}.
@@end table
@@c @@mp @@end options

@@c @@mp @@end command
@@c @@mp @@end


@@node ssu, sfscd, newaid, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{ssu} command

@@c @@mp
@@c @@mp @@command{ssu}{allow unprivileged user to become root}{1}
@@c @@mp @@description
The @@command{ssu} command allows an unprivileged user to become root
on the local machine without changing his SFS credentials.
@@command{ssu} invokes the command @@command{su} to become root.  Thus,
the access and password checks needed to become root are identical to
those of the local operating system's @@command{su} command.
@@command{ssu} also runs @@file{@@value{SFSLIBDIR}@@dslash{}newaid} to
alter the group list so that SFS can recognize the root shell as
belonging to the original user.
@@c @@mp @@end description

@@c @@mp @@ignore
The usage is as follows:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
ssu [-f | -m | -l | -c @@var{command}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@options
@@table @@option
@@item -f
@@itemx -m
These options are passed through to the @@command{su} command.

@@item -l
This option causes the newly spawned root shell to behave like a login
shell.

@@item -c @@var{command}
Tells @@command{ssu} to tell @@command{su} to run @@var{command} rather
than running a shell.
@@end table
@@c @@mp @@end options

@@c @@mp @@bugs
Note, @@command{ssu} does not work on some versions of Linux because of a
bug in Linux.  To see if this bug is present, run the command @@samp{su
root -c ps}.  If this command stops with a signal, your @@command{su}
command is broken and you cannot use @@command{ssu}.
@@c @@mp @@end bugs
@@c @@mp @@end command
@@c @@mp @@end

@@node sfscd, sfssd, ssu, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfscd} command

@@c @@mp 
@@c @@mp @@command{sfscd}{SFS client daemon}{8}
@@c @@mp @@synopsis
@@example
sfscd [-d] [-l] [-L] [-f @@var{config-file}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfscd} is the program to create and serve the @@file{/sfs}
directory on a client machine.  Ordinarily, you should not need to
configure @@command{sfscd} or give it any command-line options.
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -d
Stay in the foreground and print messages to standard error rather than
redirecting them to the system log.

@@item -l
@@cindex @@code{EDEADLK}
@@cindex @@code{Resource deadlock avoided}
Ordinarily, @@command{sfscd} will disallow access to a server running on
the same host.  If the @@var{Location} in a self-certifying pathname
resolves to an IP address of the local machine, any accesses to that
pathname will fail with the error @@code{EDEADLK} (``Resource deadlock
avoided'').

The reason for this behavior is that SFS is implemented using NFS.  Many
operating systems can deadlock when there is a cycle in the mount
graph---in other words when two machines NFS mount each other, or, more
importantly when a machine NFS mounts itself.  To allow a machine to
mount itself, you can run @@command{sfscd} with the @@option{-l} flag.
This may in fact work fine and not cause deadlock on non-BSD systems.

@@item -L
On Linux, the @@option{-L} option disables a number of kludges that work
around bugs in the kernel.  @@option{-L} is useful for people interested
in improving Linux's NFS support.

@@item -f @@var{config-file}
Specify an alternate @@command{sfscd} configuration file,
@@ref{sfscd_config}.  The default, if @@option{-f} is unspecified, is
first to look for @@file{@@value{ETCDIR}@@dslash{}sfscd_config}, then
@@file{@@value{PKGDATADIR}@@dslash{}sfscd_config}.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node sfssd, vidb, sfscd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfssd} command

@@c @@mp 
@@c @@mp @@command{sfssd}{SFS server daemon}{8}
@@c @@mp @@synopsis
@@example
sfssd [-d] [-S @@var{sfs-config-file}] [-f @@var{config-file}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfssd} is the main server daemon run on SFS servers.
@@command{sfssd} itself does not serve any file systems.  Rather, it acts
as a meta-server, accepting connections on TCP port 4 and passing them
off to the appropriate daemon.  Ordinarily, @@command{sfssd} passes all
file system connections to @@command{sfsrwsd}, and all user-key
management connections to @@command{sfsauthd}.  However, the
@@file{sfssd_config} file (@@pxref{sfssd_config}) allows a great deal of
customization, including support for ``virtual servers,'' multiple
versions of the SFS software coexisting, and new SFS-related services
other than the file system and user authentication.
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -d
Stay in the foreground and print messages to standard error rather than
redirecting them to the system log.

@@item -f @@var{config-file}
Specify an alternate @@command{sfssd} configuration file,
@@ref{sfssd_config}.  The default, if @@option{-f} is unspecified, is
first to look for @@file{@@value{ETCDIR}@@dslash{}sfssd_config}, then
@@file{@@value{PKGDATADIR}@@dslash{}sfssd_config}.

@@item -S @@var{sfs-config-file}
Specify an alternate name for the @@file{sfs_config} file,
@@ref{sfssd_config}.  If @@var{sfs-config-file} begins with a @@file{/},
then only this file is parsed.  Otherwise, all the directories
@@file{@@value{PKGDATADIR}} and @@file{@@value{ETCDIR}} are searched in
order, and if no file named @@var{sfs-config-file} is found but a file
@@file{sfs_config} is found, that file is parsed.  However, the process
does not look in @@file{@@value{ETCDIR}} if @@var{sfs-config-file} is
found in @@var{@@value{PKGDATADIR}}.  Thus, if you create a file
@@file{@@value{ETCDIR}@@dslash{}}@@var{sfs-config-file}, it will override
@@file{@@value{ETCDIR}@@dslash{}sfs_config} while still incorporating the
defaults from @@var{@@value{PKGDATADIR}@@dslash{}sfs_config}.

@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node vidb, funmount, sfssd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{vidb} command

@@c @@mp
@@c @@mp @@command{vidb}{manually edit SFS user-authentication database file}{8}
@@c @@mp @@description
@@command{vidb} manually edits an SFS user-authentication file
@@pxref{sfs_users}, acquiring locks to prevent concurrent updates from
overwriting each other.  If @@command{sfsauthd} has been compiled with
@@uref{http://www.sleepycat.com/, Sleepycat database} support, and the
name of the file ends in @@file{.db/}, @@command{vidb} will consider the
user authentication file to be a database directory, and convert the
contents into regular ASCII text for editing.  If the name of the file
ends in @@file{.db}, @@file{vidb} assumes the user authentication file
is database file (unless the pathname corresponds to an existing
directory).  Note that database files (as opposed to directories) are
required to be read-only, and thus cannot be updated by vidb.

@@c For database files, the supporting database files are in
@@c directory @@file{@@value{SFSDIR}@@dslash{}dbenv}.

@@c Note that database files use write-ahead logging, with the logs stored
@@c in the directory for supporting files.  In particular, simply
@@c @@emph{moving or deleting a database file can have disastrous
@@c consequences} when the logs do not reflect the changes.  For instance
@@c old log entries can get applied to a new file, confusingly
@@c resurrecting entries from what you might think was a deleted database.
@@c For this reason, we highly recommend that administrators @@emph{not}
@@c use database files (ending @@file{.db}) for read-write user databases.
@@c (For read-only ``public'' databases, it should be fine.)  Instead,
@@c administrators who want something more efficient than flat text files
@@c should use database directories (ending @@file{.db/}), which provide a
@@c better intuition for what renaming or deleting the database does.

@@c @@mp @@end description
@@c @@mp @@ignore
The usage is:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
vidb [-w] [-R] @@{-S | -a [-f @@var{file}] | [-e @@var{editor}]@@} @@var{sfs-users-file}
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@options
@@command{vidb} has the following options:

@@table @@option
@@c @@item -r
@@c Recovers from a previous edit session.  @@command{vidb} makes a copy of
@@c of @@var{sfs-users-file} to be edited, named by appending @@file{.tmp}
@@c to the file name.  If an editing session crashes, vidb will refuse to
@@c run, as the old temporary file may contain useful data that should
@@c not be deleted.  With @@option{-r}, however, @@command{vidb} removes any
@@c old temporary file.

@@item -a [-f @@var{file}]
The @@option{-a} option @@emph{adds} SFS user records in text form to a
database.  The records are taken from standard input, or from
@@var{file} if specified.  Records for an existing user or group will
replace the values already in the database.  Unlike @@command{vidb}'s
ordinary mode of operation, @@option{-a} does not add all records
atomically.  In the event of a system crash, some but not all of the
records may have been added to the database.  Simply re-running the
same @@command{vidb} command after a crash is perfectly safe, however,
since previously added entries will just be overwritten (by
themselves) the second time through.  For database files, because
@@option{-a} does not accumulate records into one large transaction, it
can be significantly more efficient than simply adding the records in
an editor, using @@command{vidb}'s ordinary mode of operation.

@@item -e @@var{editor}
Specifies the editor to use for editing the file.  The default is to
use the command specified by the environment variable @@env{EDITOR}.
If there is no environment variable and @@option{-e} is not specified,
@@command{vidb} uses @@command{vi}.

@@item -w
One of the points of @@command{vidb} is to avoid concurrent edits to
the database and the corresponding inconsistencies that might result.
Ordinarily, if the database is already being edited, @@command{vidb}
will just exit with an error message.  The @@option{-w} flag tells
@@command{vidb} to wait until it can acquire the lock on the database
before launching the editor.

@@item -R
Runs @@emph{catastrophic recovery} on the database environment.  (For
those familiar with Sleepycat database software, this corresponds to
the @@option{-c} flag of the @@command{db_recover} utility, or the
@@code{DB_RECOVER_FATAL} flag of the API.)  Essentially, @@option{-R}
replays all of the database log records present in the supporting
files directory.  You may need to use this, for example, when
restoring a database from backup tapes if the log files were backed up
more recently than the entire database.  The @@option{-R} has no effect
on flat text databases, or if the @@option{-S} has been specified.
@@strong{Warning:}  The authors have encountered bugs in the
catastrophic recovery code of at least some versions of the Sleepycat
database package.  As a precaution, before attempting to use
@@option{-R}, we strongly recommend salvaging whatever records possible
from the database file itself using @@samp{vidb -S}
@@var{sfs-users-file}@@samp{>}@@samp{saved_sfs_users}.  If, subsequently,
the @@option{-R} option corrupts the database, you can at least salvage
some of the records from the @@file{saved_sfs_users} file.

@@item -S
Attempt to @@emph{salvage} a database file with corrupt or lost logs by
dumping the contents of the database itself.  Ordinarily, databases
use write-ahead logging.  Before opening a database file, both
@@command{vidb} and @@command{sfsauthd} attempt to recover from any
previous incomplete transactions using the log.  The @@option{-S}
option opens and prints out the contents of a database without regard
to the log files.  This is useful if you have lost the log files or
are worried that they are corrupt, or if you wish to examine the
contents of a database you have read but not write permission to.
Ordinarily, however, if you wish to dump the contents of a database to
standard output, use the command @@samp{vidb -e cat}
@@var{sfs-users-file}.

@@end table
@@c @@mp @@end options

@@noindent
Note:
@@c @@mp @@bugs
@@command{vidb} should really recreate any publicly-readable versions
of user authentication databases (either by parsing
@@file{sfsauthd_config} for @@option{-pub=...} options to
@@samp{Userfile} directives or signaling @@command{sfsauthd}).
Currently you must manually kill @@command{sfssd} or @@command{sfsauthd}
for this to happen.

While @@command{vidb} attempts to make the smallest number of changes
to a database, editing sessions that add or remove a large number of
records can potentially exhaust resources such as locks.  Sites with
large user databases can tune the database by creating a file called
@@file{DB_CONFIG} in the database directory.
@@c with supporting files (the directory
@@c itself for @@file{.db/} databases, and
@@c @@file{@@value{SFSDIR}@@dslash{}dbenv} for database files).
The specifics of the configuration file are documented in the
Sleepycat database documentation.  As an example, if performance is
slow and you run out of locks, you can set the cache size to 128MB and
increase the number of locks with the following @@file{DB_CONFIG} file:

@@example
set_cachesize 0 134217728 1
set_lk_max_locks 50000
set_lk_max_objects 50000
@@end example

When editing a database, @@command{vidb} creates a temporary text file
in the @@file{/tmp} directory.  For huge databases, it is conceivable
that @@file{/tmp} does not have enough space.  If this happens,
@@file{/tmp} can be overridden with the @@env{TMPDIR} environment
variable.
@@c @@mp @@end bugs

@@c @@mp @@end command
@@c @@mp @@end


@@node funmount, sfsrwsd, vidb, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{funmount} command

@@c @@mp
@@c @@mp @@command{funmount}{forcibly unmount a file system}{8}

@@c @@mp @@ignore
The @@command{funmount} command is executed as follows:
@@c @@mp @@end ignore

@@c @@mp @@synopsis
@@example
funmount @@var{path}
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{funmount} forcibly attempts to unmount the file system
mounted on @@var{path}.  It is roughly equivalent to running
@@samp{umount -f @@var{path}}.  However, on most operating systems the
@@command{umount} command does a great deal more than simply execute
the @@code{unmount} system call---for instance it may attempt to read
the attributes of the file system being unmounted and/or contact a
remote NFS server to notify it of the unmount operation.  These extra
actions make @@code{umount} hang when a remote NFS server is
unavailable or a loopback server has crashed, which in turn causes the
client to become ever more wedged.  @@command{funmount} can avoid such
situations when you are trying to salvage a machine with bad NFS
mounts without rebooting it.
@@c @@mp @@end description

@@c @@mp @@caveats
SFS will get very confused if you ever unmount file systems from
beneath it.  SFS's @@command{nfsmounter} program tries to clean up the
mess if the client software ever crashes.  Running @@command{funmount}
will generally only make things worse by confusing
@@command{nfsmounter}.
@@c @@mp @@end caveats

@@c @@mp @@bugs
If @@file{/a} is a mount point, and @@file{/a/b} is another mount point,
unmounting @@file{/a} before @@file{/a/b} will cause the latter file
system to become ``lost.''  Once a file system is lost, there is no
way to unmount it without rebooting.  Worse yet, on some operating
systems, commands such as @@command{df} may hang because of a lost file
system.

Many operating systems will not let you unmount a file system (even
forcibly) if a process is using the file system's root directory (for
instance as a current working directory).  Under such circumstances,
@@command{funmount} may fail.  To unmount the file system you must find
and kill whatever process is using the directory.  Utilities such as
@@command{fstat} and @@command{lsof} may be helpful for identifying
processes with a particular file system open.
@@c @@mp @@end bugs
@@c @@mp @@end command
@@c @@mp @@end

@@node sfsrwsd, sfsrosd, funmount, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfsrwsd} daemon

@@c @@mp
@@c @@mp @@command{sfsrwsd}{SFS read-write server}{8}
@@c @@mp @@synopsis
@@example
@@value{SFSLIBDIR}/sfsrwsd [-f @@var{config-file}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfsrwsd} is the program implementing the SFS read-write server.
Ordinarily, you should never run @@command{sfsrwsd} directly, but rather
have @@command{sfssd} do so.  Nonetheless, you must create a
configuration file for @@command{sfsrwsd} before running an SFS server.
@@xref{sfsrwsd_config}, for what to put in your @@file{sfsrwsd_config}
file.
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -f @@var{config-file}
Specify an alternate @@command{sfsrwsd} configuration file,
@@ref{sfsrwsd_config}.  The default, if @@option{-f} is unspecified, is
@@file{@@value{ETCDIR}@@dslash{}sfsrwsd_config}.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node sfsrosd, sfsauthd, sfsrwsd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfsrosd} daemon

@@c @@mp 
@@c @@mp @@command{sfsrosd}{SFS read-only server}{8}
@@c @@mp @@synopsis
@@example
@@value{SFSLIBDIR}/sfsrosd [-f @@var{config-file}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfsrosd} is the program implementing the SFS read-only server.
Ordinarily, you should never run @@command{sfsrwsd} directly, but rather
have @@command{sfssd} do so.  Nonetheless, you must create a
configuration file for @@command{sfsrosd} before running an SFS server.
@@xref{sfsrosd_config}, for what to put in your @@file{sfsrosd_config}
file.
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -f @@var{config-file}
Specify an alternate @@command{sfsrosd} configuration file,
@@ref{sfsrosd_config}.  The default, if @@option{-f} is unspecified, is
@@file{@@value{ETCDIR}@@dslash{}sfsrosd_config}.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end


@@node sfsauthd, sfsrwcd, sfsrosd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfsauthd} daemon

@@c @@mp 
@@c @@mp @@command{sfsauthd}{SFS authentication daemon}{8}
@@c @@mp @@synopsis
@@example
@@value{SFSLIBDIR}/sfsauthd [-u @@var{sockfile}] [-f @@var{config-file}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfsauthd} is the program responsible for authenticating
users.  @@command{sfsrwsd} and other daemons communicate with
@@command{sfsauthd}, forwarding it authentication requests from
@@command{sfsagent} processes on remote client machines.
@@command{sfsauthd} informs requesting daemons of whether
authentication requests are valid, and if so what local credentials to
associate with the remote user agent.  The @@command{sfskey} program
also communicates directly with remote @@command{sfsauthd} processes
when retrieving and updating users keys (with @@command{sfskey add},
@@command{update}, @@command{register}, and more).
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -f @@var{config-file}
Specify an alternate @@command{sfssauthd_config} configuration file,
@@ref{sfsauthd_config}.  The default, if @@option{-f} is unspecified, is
@@file{@@value{ETCDIR}@@dslash{}sfsauthd_config}.
@@item -u @@var{path}
Bind unix domain socket @@var{path}, and accept TCP connections passed
over connections to that socket.  This option allows @@command{sfssd}
to communicate with already running @@command{sfsauthd} commands using
a directive like @@samp{Service 2 -u @@var{path}} in @@file{sfssd_config}
@@ref{sfssd_config}.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node  sfsrwcd, nfsmounter, sfsauthd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{sfsrwcd} daemon

@@c @@mp 
@@c @@mp @@command{sfsrwcd}{SFS read-write protocol client daemon}{8}
@@c @@mp @@synopsis
@@example
@@value{SFSLIBDIR}/sfsrwcd [-u @@var{unknown-user}]
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{sfsrwcd} is the daemon that implements the client side of the
SFS read-write file system protocol.  @@command{sfsrwcd} acts as an NFS
loopback server to the local machines's in-kernel NFS client, and as a
client to a remote SFS server speaking the read-write protocol.  Most
SFS servers use the read-write file system protocol, though several
research projects have implemented other protocols.

The SFS read-write protocol has RPC program number 344444 and version
number 3.  It closely resembles NFS3, but additionally supports leases
on attributes:  for a short period after returning file attributes to
a client, the server commits to notifying the client when the
attributes change.  Leases enable clients to cache file attributes
more aggressively.  In addition, the SFS protocol is encrypted and
authenticated (via a message authentication code), and supports user
authentication via opaque messages, so that users' local
@@command{sfsagent} processes can cryptographically authenticate them
to remote servers.

Ordinarily, @@command{sfsrwcd} is launched by @@command{sfscd}.  The
file @@file{@@value{PKGDATADIR}@@dslash{}sfscd_config}
@@c @@mp @@ignore
(@@pxref{sfscd_config})
@@c @@mp @@end ignore
@@ignore
(see the man page for @@file{sfscd_config}(5))
@@end ignore
contains a configuration directive instructing @@command{sfscd} to run
@@command{sfsrwcd} for the read-write file system protocol (program
344444, version 3):

@@example
  Program 344444.3 sfsrwcd
@@end example

You never need to run @@command{sfsrwcd} directly (in fact,
@@command{sfsrwcd} won't work without the @@command{sfscd} automounter).
However, you might wish to change the options with which
@@command{sfsrwcd} runs.  To do so, create an alternate
@@file{sfscd_config} file in @@file{@@value{ETCDIR}/}.  For instance, you
might use the line:

@@example
  Program 344444.3 sfsrwcd -u unknown
@@end example
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -u @@var{unknown-user}
The @@var{-u} option enables user- and group-ID mapping.
@@command{sfsrwcd} will attempt to map remote user IDs to local user
IDs of authenticated users.  Moreover, when a user belongs to a file's
group on a remote machine, @@command{sfsrwcd} will map the file's gid
to the user's local gid.

@@var{unknown-user} must be the name of a user in the local password
file.  When none of the local users have remote credentials
corresponding to a remote file's owner, @@command{sfsrwcd} maps the
file's uid to the numeric uid of @@var{unknown-user}.  Moreover, when a
user is not in the file's remote group, @@command{sfsrwcd} maps the
file's uid to the numeric gid of @@var{unknown-user} in the password
file.

Note that even with the @@option{-u} option, if a local user's uid and
gid are the same as on the remote machine, no ID mapping occurs, as
the client and server are assumed to be in the same administrative
realm (though of course this might not be true).

ID mapping is not completely reliable, and may result in odd behavior.
In particular for group IDs, no single mapping may work for all local
users.  Thus, one user may see a file belonging to one group, and
another user may see the same file as belonging to
@@var{unknown-user}'s group.  Worse yet, the kernel may cache file
attributes, so that if the two users look at the same file at roughly
the same time, one user may see the other user's mapping.

Despite odd attributes that might result from kernel cache consistency
problems, ID mapping never changes the actual file permissions users
have on files.  Nor does it affect the results of the @@code{access}
system call.  The primary reason for the @@var{-u} flag is that the
Macintosh finder attempts to second-guess file permissions based on
numeric user and group ID, even when these values do not make sense on
the local machine.  Thus, users can be denied access to files they
have legitimate access to (and which the @@code{access} system call
would show they had access to).

Note that when ID mapping is in effect, the @@code{chown} system call
(used by the @@command{chown} and @@command{chgrp} commands) is
disallowed, because its potentially confusing effects would be
concealed by the ID mapping.
@@end table
@@c @@mp @@end options
@@c @@mp @@end command
@@c @@mp @@end

@@node  nfsmounter,  , sfsrwcd, Command reference
@@comment  node-name,  next,  previous,  up
@@section @@command{nfsmounter} daemon

@@cindex @@command{nfsmounter}

@@c @@mp 
@@c @@mp @@command{nfsmounter}{NFS mount/unmount daemon}{8}
@@c @@mp @@synopsis
@@example
@@value{SFSLIBDIR}/nfsmounter [-F] [-P] /@@var{prefix}
@@end example
@@c @@mp @@end synopsis

@@c @@mp @@description
@@command{nfsmounter} is a program that calls the @@code{mount} and
@@code{unmount} (or @@command{umount}, depending on the operating
system) system calls to create NFS mount points for NFS loopback
servers.  An NFS loopback server is a user-level program that speaks
the NFS file system protocol, effectively pretending to be a remote
file server even though it is just a process on the local machine.
SFS is implemented as an NFS loopback server to gain portability,
since most operating systems have built-in NFS clients.  Other file
systems built using the SFS file system toolkit also use
@@command{nfsmounter}.

The only thing you really need to know about nfsmounter is that you
should @@emph{never send @@command{nfsmounter} a @@code{SIGKILL} signal,
e.g., using the @@samp{kill -9} command}.  If an NFS loopback server
seems to be misbehaving, you can find the corresponding
@@code{nfsmounter} process through @@command{ps} (the @@var{prefix}
argument will tell you which directory a particular
@@command{nfsmounter} process is handling, if there are multiple
loopback servers on your machine) and send it a @@code{SIGTERM} signal
(@@samp{kill -15}).  Upon receiving a @@code{SIGTERM},
@@command{nfsmounter} will drop its connection to the NFS loopback
server, take over the UDP sockets corresponding to the mount point,
and do its best to unmount all the file systems.

The rest of this @@command{nfsmounter} description is mostly of
interest to people who are developing NFS loopback servers themselves.

@@command{nfsmounter} must be run as root.  It expects its standard
input (file descriptor 0) to be a Unix-domain socket.  The program
that spawned @@command{nfsmounter} communicates over that socket using
an RPC protocol defined in @@file{@@value{PKGINCLUDEDIR}/nfsmounter.x}.
As part of the mount process, the program that invoked
@@command{nfsmounter} must send it a copy of the server socket for the
NFS loopback server.  When @@command{nfsmounter} detects an end of file
on standard input, it takes over these sockets so as to avoid having
processes hang (which would happen if the NFS loopback server simply
died) and attempts to unmount all file systems.  Thus, it is safe for
NFS loopback servers simply to exit.

If the @@env{SFS_RUNINPLACE} environment variable is set to a directory
and @@command{nfsmounter} detects that its standard input is not a
Unix-domain socket, @@command{nfsmounter} will instead bind Unix-domain
socket @@file{$SFS_RUNINPLACE/runinplace/.nfsmounter} and wait for a
single connection.  The @@command{sfscd} program knows to check for
this socket when @@env{SFS_RUNINPLACE} is set.  This option makes it
easy to run @@command{sfscd} as a non-root user by starting
@@command{nfsmounter} first, which in turn facilitates debugging with
emacs (without having to run everything as root).
@@c @@mp @@end description

@@c @@mp @@options
@@table @@option
@@item -F
Disables forcible unmounting of file systems.  Forcible unmounting is
the system call flag that corresponds to the @@option{-f} flag of the
@@command{umount} command.  If you are developing an NFS loopback
server that seems to panic the kernel a lot on exit, running
@@command{nfsmounter} with @@option{-F} might help.

@@item -P
Always pass absolute pathnames to the @@code{mount} system call.
Ordinarily, as a defensive measure, @@command{nfsmounter} changes
directory to the point where the mount is happening.  This is to avoid
accidentally following a symbolic link and creating a mountpoint on a
directory not under @@var{prefix}.  However, calling @@code{mount} with
a relative pathname cause the @@file{/proc} file system or system
calls like @@code{getfsstat} to return relative pathnames, which can
confuse some applications.

To fix the problem, after creating a mount point, @@command{nfsmounter}
attempts to re-mount or update the mountpoint using the absolute
pathname.  Unfortunately, this trick does not work on some BSD-derived
operating systems, including MacOS.  Moreover, on the Macintosh in
particular, the finder gets very confused by relative mountpoint
names.  Thus, SFS uses the @@option{-P} option to nfsmounter on the
Macintosh.
@@end table
@@c @@mp @@end options

@@c @@mp @@bugs
@@command{nfsmounter} gets very confused if you unmount file systems
out from under it.

On some versions of Linux, if you attempt to create an NFS loopback
mount but are not running @@command{portmap}, it appears to wedge the
mountpoint in way that requires a reboot to recover.  The reason is
that the Linux kernel's NFS client checks to see if the server is
running various auxiliary daemons used for locking, and gets into a
bad state if it cannot map the port.  There should be a way to recover
from this situation, but the author of @@command{nfsmounter} does not
know how.  Running @@command{portmap} after the fact does not help.
Perhaps @@command{nfsmounter} should have its own built-in portmap to
use in the event that port 111 is not yet bound by any process.
@@c @@mp @@end bugs
@@c @@mp @@end command
@@c @@mp @@end

@@node  Environment variables, Security, Command reference, Top
@@comment  node-name,  next,  previous,  up
@@chapter Environment variables

@@c @@mp
@@c @@mp @@command{sfs_environ}{SFS environment variables}{7}
@@c @@mp @@description
The following environment variables affect many of SFS's component
programs.  (Note that for security reasons, the setuid programs
@@command{suidconnect} and @@command{newaid} interpret some of these
slightly differently---ignoring some and dropping privilege if others
are set.)

@@table @@var
@@item ACLNT_TRACE
Used mostly for debugging, @@var{ACLNT_TRACE} causes most SFS commands
to print a trace of all the RPCs they make.  The environment variable
must be set to an integer.  The higher the value, the more trace
information.  The value 1 causes only anomalous situations such as
retransmissions to be reported.  2 causes every RPC to be printed.  4
causes both RPC calls and replies to be printed.  Arguments over 5
cause the actual RPC argument and result data structures to be
pretty-printed--the higher the number the greater the depth to which
recursive data structures will be expanded.  A value of 10 is
generally sufficient to get a very complete RPC trace.

@@item ACLNT_TIME
A boolean value.  When this environment variable and @@var{ACLNT_TRACE}
are both set, the trace includes timestamps as well, which can be
useful in debugging.

@@item ASRV_TRACE
@@itemx ASRV_TIME
These perform an analogous function to @@env{ACLNT_TRACE} and
@@env{ACLNT_TIME}, but print out RPCs received (as a server), rather
than ones made.

@@item BINDADDR
If set, must contain an IPv4 address.  Whenever SFS creates a socket
that would be bound to @@code{INADDR_ANY}, it will be bound to
@@var{BINDADDR} instead (unless @@var{BINDADDR} is no longer a valid
local address).

@@item FDLIM_HARD
@@itemx FDLIM_SOFT
Most of the daemons that comprise SFS use asynchronous I/O to handle
multiple network connections concurrently.  In order to be able to
handle as many concurrent connections as possible, the library raises
the per-process file descriptor limit to the maximum allowable value.
For privileged processes, this additionally means raising the
so-called ``hard'' file descriptor limit.  When raising these values,
if the @@env{FDLIM_SOFT} and @@env{FDLIM_HARD} environment variables are
not set, SFS saves their the old limit values in the environment
variables.

An example of how this is used is by @@command{rexd}, the remote
execution daemon.  @@command{rexd} reduces the file descriptor limits
to the original values specified by these environment variables before
spawning an unprivileged user program.  These variables ordinarily
should not be of concern to users of SFS, and are documented here
mostly for people who notice them and are curious.

@@item SFS_AGENTSOCK
Ordinarily @@command{sfskey} connects to @@command{sfsagent} through the
SFS client daemon, @@command{sfscd}.  However, by passing the
@@option{-S} option to @@command{sfsagent}, it is possible to have
@@command{sfsagent} bind an arbitrary Unix domain socket for
connections.  @@command{SFS_AGENTSOCK} can be set to such a pathname,
and @@command{sfskey} will then connect to that socket.

As a special case, if @@env{SFS_AGENTSOCK} is set to a negative number,
this is interpreted to mean a file descriptor number already connected
to the agent.  This feature is particularly useful when atomically
killing and starting @@command{sfsagent} with the @@option{-k} flag.  In
this case, and program specified on the command line, or the default
@@file{@@value{PKGDATADIR}@@dslash{}agentrc} script, will be run with
@@env{SFS_AGENTSOCK} set to a file descriptor.  Thus, if the script
loads keys into the agent by running @@command{sfskey}, these keys will
be loaded into the new agent (before it takes over), rather than into
the old agent.

@@item SFS_CONFIG
The location in which to find the @@file{sfs_config} file.  By default,
SFS uses configuration files in
@@file{@@value{PKGDATADIR}@@dslash{}sfs_config} and
@@file{@@value{ETCDIR}@@dslash{}sfs_config}.  @@command{sfssd} sets this
environment variable when given the @@option{-S} option, so that
subsidiary daemons read the same configuration file.

@@item SFS_HOSTNAME
@@anchor{SFS_HOSTNAME}
Overrides SFS's default algorithm for figuring out the local hostname.
Several SFS programs must know the machine's fully-qualified hostname.
In particular, this name constitutes the official @@var{Location} in a
server's self-certifying pathname (since a given file system should
have only one self-certifying hostname).  The hostname of an SFS
server must exist in the DNS (as opposed to just
@@file{/etc@@dslash{}hosts}) for many of the servers to work.

The algorithm used by SFS is to determine a host's name is as follows.
It checks the system's name with the @@code{gethostname} system call,
and if it is fully-qualified (i.e., has a ``.domain'' at the end) uses
that.  Otherwise, it appends the default domain name to the system
name.

Sometimes SFS's algorithm will not produce the correct hostname.  In
that case, you can specify the real hostname for each individual
daemon such as @@command{sfsrwsd} and @@command{sfsauthd} in their
confiruation files.  Or, you can just set the environment variable
@@env{SFS_HOSTNAME} before running @@command{sfssd}.  Note that if you
do not have a DNS name, you can also set @@env{SFS_HOSTNAME} to the
numeric IPv4 address of your host, and then use the IP address as the
@@var{Location} in self-certifying pathnames.

@@item SFS_PORT
@@anchor{SFS_PORT}
This variable, if set, specifies official port number of an SFS
server---i.e. the @@file{%@@var{port}} that clients must append to the
hostname in the @@var{Location} of the self-certifying pathname.  By
default (or if @@env{SFS_PORT} is set to 0), the self-ceritying
pathname contains no port number, which means to check DNS for SRV
records, and if none are found to use port 4.

Because servers have only one canonical self-certifying pathname,
setting @@env{SFS_PORT} to 4 is not the same thing as setting it to 0,
even without SRV records.  If you set @@env{SFS_PORT} to 4, then
clients who do not specify @@samp{%4} in the self-certifying pathname
will need to be redirected to a pathname containing @@file{%4} via a
symbolic link, and @@command{pwd} run on a client will show the
@@samp{%4} as part of the self-certifying pathname.

Note further that the effects of this environment variable should not
be confused with the @@samp{BindAddr} option in @@file{sfssd_config},
@@ref{BindAddr}.  For example, if you set up SRV records pointing to
TCP port 5 on your server, you might want to specify @@samp{BindAddr
0.0.0.0 5} in @@file{sfssd_config}, but you almost certainly would not
want to set the @@env{SFS_PORT} environment variable to 5, as setting
@@env{SFS_PORT} to anything other than 0 means the self-certifying
pathname contains @@file{%5}, which in turn means DNS SRV records
should not be used.  (I.e., a client accessing
@@file{@@@@host.domain,@@var{hostid}} would be redirected to
@@file{@@@@host.domain%5,@@var{hostid}}, which would bypass any SRV
records for @@file{host.domain} and, depending on DNS data, might not
even resolve to the same IP address as the pathname without a
@@file{%}.)

@@item SFS_ROOT
Sets the root directory of the SFS file system, which is usually
@@file{/sfs}.  Changing this for anything other than debugging purposes
is not recommended, as many symbolic links will break.

@@item SFS_RUNINPLACE
SFS consists of a large number of interacting daemons.  Ordinarily,
these are launched by @@command{sfscd} and @@command{sfssd}.  If you
wish to run SFS without installing it, however, these commands will
not be able to find the subsidiary daemons they are supposed to
launch.  Setting @@env{SFS_RUNINPLACE} to the root of your build
directory allows SFS to be run without installing it.  Because this
option is mainly used for development, however, several programs
behave slightly differently when it is set.  @@command{sfscd} and
@@command{sfssd} both remain in the forground and send their output to
standard error, rather than to the system log.  Moreover,
@@command{sfsagent} does take steps to protect itself from the
@@code{ptrace} system call, so that you can attach to it with the
debugger when running in place.

@@item TMPDIR
Some SFS programs need to create temporary files or Unix-domain
sockets in the local file system.  By default, these programs use the
@@file{/tmp} directory or created protected subdirectories of
@@file{/tmp}.  However, you can override the location by setting the
@@env{TMPDIR} environment variable.

@@item USER
In various places SFS needs a default username---for example, when
running @@samp{sfskey login}.  SFS looks first at the @@env{USER}
environment variable, then uses the @@code{getlogin} system call, and
if that fails, looks up the current user ID in the system password
file.
@@end table
@@c @@mp @@end description
@@c @@mp @@end command
@@c @@mp @@end


@@node Security, Contacts, Environment variables, Top
@@comment  node-name,  next,  previous,  up
@@chapter Security considerations

SFS shares files between machines using cryptographically protected
communication.  As such, SFS can help eliminate security holes
associated with insecure network file systems and let users share files
where they could not do so before.

That said, there will very likely be security holes attackers can
exploit because of SFS, that they could not have exploited otherwise.
This chapter enumerates some of the security consequences of running
SFS.  The first section describes vulnerabilities that may result from
the very existence of a global file system.  The next section lists bugs
potentially present in your operating system that may be much easier for
attackers to exploit if you run SFS.  Finally the last section attempts
to point out weak points of the SFS implementation that may lead to
vulnerabilities in the SFS software itself.

@@menu
* new vulnerabilities::         Vulnerabilities created by SFS
* exposed vulnerabilities::     Vulnerabilities exploitable because of SFS
* implementation vulnerabilities::  Vulnerabilities in the SFS implementation
@@end menu

@@node new vulnerabilities, exposed vulnerabilities, Security, Security
@@comment  node-name,  next,  previous,  up
@@section Vulnerabilities created by SFS

@@subheading Facilitating exploits

Many security holes can be exploited much more easily if the attacker
can create an arbitrary file on your system.  As a simple example, if a
bug allows attackers to run any program on your machine, SFS allows them
to supply the program somewhere under @@file{/sfs}.  Moreover, the file
can have any numeric user and group (though of course, SFS disables
setuid and devices).

@@subheading @@file{.} in @@env{path}

Another potential problem users putting the current working directory
@@file{.} in their @@var{PATH} environment variables.  If you are browsing
a file system whose owner you do not trust, that owner can run arbitrary
code as you by creating programs named things like @@command{ls} in the
directories you are browsing.  Putting @@file{.} in the @@var{PATH} has
always been a bad idea for security, but a global file system like SFS
makes it much worse.

@@subheading symbolic links from untrusted servers

Users need to be careful about using untrusted file systems as if they
were trusted file systems.  Any file system can name files in any other
file system by symbolic links.  Thus, when randomly overwriting files in
a file system you do not trust, you can be tricked, by symbolic links,
into overwriting files on the local disk or another SFS file system.

As an example of a seemingly appealing use of SFS that can cause
problems, consider doing a @@command{cvs} checkout from an untrusted CVS
repository, so as to peruse someone else's source code.  If you run
@@command{cvs} on a repository you do not trust, the person hosting the
repository could replace the @@file{CVSROOT/history} with a symbolic
link to a file on some other file system, and cause you to append
garbage to that file.

This @@command{cvs} example may or may not be a problem.  For instance,
if you are about to compile and run the software anyway, you are placing
quite a bit of trust in the person running the CVS repository anyway.
The important thing to keep in mind is that for most uses of a file
system, you are placing some amount of trust in in the file server.

@@xref{resvgids}, to see how users can run multiple agents with the
@@command{newaid} command.  One way to cut down on trust is to access
untrusted file servers under a different agent with different private
keys.  Nonetheless, this still allows the remote file servers to serve
symbolic links to the local file system in unexpected places.

@@subheading Leaking information

Any user on the Internet can get the attributes of a
@@var{local-directory} listed in an @@samp{Export} directive
(@@pxref{export}).  This is so users can run commands like @@samp{ls -ld}
on a self-certifying pathname in @@file{/sfs}, even if they cannot change
directory to that pathname or list files under it.  If you wish to keep
attribute information secret on a @@var{local-directory}, you will need
to export a higher directory.  We may later reevaluate this design
decision, though allowing such anonymous users to get attributes
currently simplifies the client implementation.

@@node exposed vulnerabilities, implementation vulnerabilities, new vulnerabilities, Security
@@comment  node-name,  next,  previous,  up
@@section Vulnerabilities exploitable because of SFS

@@subheading NFS server security
@@cindex NFS security
@@anchor{NFS security}

The SFS read-write server software requires each SFS server to run an
NFS server.  Running an NFS server at all can constitute a security
hole.  In order to understand the full implications of running an SFS
server, you must also understand NFS security.

NFS security relies on the secrecy of file handles.  Each file on an
exported file system has associated with it an NFS file handle
(typically 24 to 32 bytes long).  When mounting an NFS file system, the
@@command{mount} command on the client machine connects to a program
called @@command{mountd} on the server and asks for the file handle of
the root of the exported file system.  @@command{mountd} enforces access
control by refusing to return this file handle to clients not authorized
to mount the file system.

Once a client has the file handle of a directory on the server, it sends
NFS requests directly to the NFS server's kernel.  The kernel performs
no access control on the request (other than checking that the user the
client claims to speak for has permission to perform the requested
operation).  The expectation is that all clients are trusted to speak
for all users, and no machine can obtain a valid NFS file handle without
being an authorized NFS client.

To prevent attackers from learning NFS file handles when using SFS, SFS
encrypts all NFS file handles with a 20-byte key using the Blowfish
encryption algorithm.  Unfortunately, not all operating systems choose
particularly good NFS file handles in the first place.  Thus, attackers
may be able to guess your file handles anyway.  In general, NFS file
handles contain the following 32-bit words:

@@itemize @@bullet
@@item A file system ID (containing the device number)
@@item The inode number (i-number) of the file
@@item A generation number that changes when the i-number is recycled
@@end itemize

@@noindent
In addition NFS file handles can contain the following words:

@@itemize @@bullet
@@item A second file system ID word (for a 64-bit fsid)
@@item The length of the file handle data
@@item The i-number of the exported directory
@@item The generation number of the exported directory
@@item Another copy of the file system ID (for the exported directory?)
@@item One or more unused 0 words
@@end itemize

@@noindent
Many of these words can be guessed outright by attackers without their
needing to interact with any piece of software on the NFS server.  For
instance, the file system ID is often just the device number on which
the physical file system resides.  The i-number of the root directory in
a file system is always 2.  The i-number and generation number of the
root directory can also be used as the i-number and generation number of
the ``exported directory''.

On some operating systems, then, the only hard thing for an attacker to
guess is the 32-bit generation number of some directory on the system.
Worse yet, the generation numbers are sometimes not chosen with a good
random number generator.

To minimize the risks of running an NFS server, you might consider
taking the following precautions:

@@itemize @@bullet
@@item
Many operating systems ship with a program called @@command{fsirand} that
re-randomizes all generation numbers in a file system.  Running
@@command{fsirand} may result in much better generation numbers than,
say, a factory install of an operating system.

@@item
In general, you should try to block all external NFS traffic from
reaching your machine.  If you have a firewall, consider filtering ports
111 and 2049 for both TCP and UDP.  If your server's operating system
comes with some sort of IP filtering, you might filter any traffic to
port 2049 that does not come from the loopback interface (though on some
OSes, this could prevent you from acting as an NFS client if you are
still using NFS on your local network---try it to see).

@@item
Most operating systems allow you to export NFS file systems
``read-mostly''---i.e. read-write to a small number of servers and
read-only to everyone else.  The read-only requirement typically is
enforced by the kernel.  Thus, if you can export file systems read-write
to @@samp{localhost} for SFS, but read-only to any client on which an
attacker may have learned an NFS file handle, you may be able to protect
the integrity of your file system under attack.  (Note, however, that
unless you filter forged packets at your firewall, the attacker can put
whatever source address he wants on an NFS UDP packet.)  See the
@@command{mountd} or @@command{exports} manual page for more detail.
@@strong{Note:  under no circumstances should you make your file system
``read-only to the world,'' as this will let anyone find out NFS file
handles.  You want the kernel to think of the file system as read-only
for the world, but @@command{mountd} to refuse to give out file handles
to anybody but @@samp{localhost}.}
@@end itemize

@@subheading @@samp{mountd -n}.

The @@command{mountd} command takes a flag @@option{-n} meaning ``allow
mount requests from unprivileged ports.''  @@strong{Do not ever run use
this flag}.  Worse yet, some operating systems (notably HP-UX 9) always
exhibit this behavior regardless of whether they @@option{-n} flag has
been specified.

The @@option{-n} option to @@command{mountd} allows any user on an NFS
client to learn file handles and thus act as any other user.  The
situation gets considerably worse when exporting file systems to
@@samp{localhost}, however, as SFS requires.  Then everybody on the
Internet can learn your NFS file handles.  The reason is that the
@@command{portmap} command will forward mount requests and make them
appear to come from @@samp{localhost}.

@@subheading @@command{portmap} forwarding

In order to support broadcast RPCs, the @@command{portmap} program will
relay RPC requests to the machine it is running on, making them appear
to come from @@samp{localhost}.  That can have disastrous consequences in
conjunction with @@samp{mountd -n} as described previously.  It can also
be used to work around ``read-mostly'' export options by forwarding NFS
requests to the kernel from @@samp{localhost}.

Operating systems are starting to ship with @@command{portmap} programs
that refuse to forward certain RPC calls including mount and NFS
requests.  Wietse Venema has also written a @@command{portmap}
replacement that has these properties, available from
@@uref{ftp://ftp.porcupine.org/pub/security/index.html}.  It is also a
good idea to filter TCP and UDP ports 111 (@@command{portmap}) at your
firewall, if you have one.

@@subheading Bugs in the NFS implementation

Many NFS implementations have bugs.  Many of those bugs rarely surface
when clients and servers with similar implementation talk to each other.
Examples of bugs we've found include servers crashing when the receive a
write request for an odd number of bytes, clients crashing when they
receive the error @@code{NFS3ERR_JUKEBOX}, and clients using
uninitialized memory when the server returns a @@code{lookup3resok} data
structure with @@code{obj_attributes} having @@code{attributes_follow} set
to false.

SFS allows potentially untrusted users to formulate NFS requests (though
of course SFS requires file handles to decrypt correctly and stamps the
request with the appropriate Unix uid/gid credentials).  This may let
bad users crash your server's kernel (or worse).  Similarly, bad servers
may be able to crash a client.

As a precaution, you may want to be careful about exporting any portion
of a file system to anonymous users with the @@samp{R} or @@samp{W}
options to @@samp{Export} (@@pxref{export}).  When analyzing your NFS code
for security, you should know that even anonymous users can make the
following NFS RPC's on a @@var{local-directory} in your
@@file{sfsrwsd_config} file:  @@code{NFSPROC3_GETATTR},
@@code{NFSPROC3_ACCESS}, @@code{NFSPROC3_FSINFO}, and
@@code{NFSPROC3_PATHCONF}.

On the client side, a bad, non-root user in collusion with a bad file
server can possibly crash or deadlock the machine.  Many NFS client
implementations have inadequate locking that could lead to race
conditions.  Other implementations make assumptions about the
hierarchical nature of a file system served by the server.  By violating
these assumptions (for example having two directories on a server each
contain the other), a user may be able to deadlock the client and create
unkillable processes.

@@subheading @@command{logger} buffer overrun

SFS pipes log messages through the @@command{logger} program to get them
into the system log.  SFS can generate arbitrarily long lines.  If your
@@command{logger} does something stupid like call @@command{gets}, it may
suffer a buffer overrun.  We assume no one does this, but feel the point
is worth mentioning, since not all logger programs come with source.

To avoid using @@command{logger}, you can run @@command{sfscd} and
@@command{sfssd} with the @@option{-d} flag and redirect standard error
wherever you wish manually.


@@node implementation vulnerabilities,  , exposed vulnerabilities, Security
@@comment  node-name,  next,  previous,  up
@@section Vulnerabilities in the SFS implementation

@@subheading Resource exhaustion

The best way to attack the SFS software is probably to cause resource
exhaustion.  You can try to run SFS out of file descriptors, memory, CPU
time, or mount points.

An attacker can run a server out of file descriptors by opening many
parallel TCP connections.  Such attacks can be detected using the
@@command{netstat} command to see who is connecting to SFS (which
accepts connections on port 4).  Users can run the client (also
@@command{sfsauthd}) out of descriptors by connecting many times using
the setgid program @@file{@@value{SFSLIBDIR}@@dslash{}suidconnect}.
These attacks can be traced using a tool like lsof, available from
@@uref{ftp://vic.cc.purdue.edu/pub/tools/unix/lsof}.

SFS enforces a maximum size of just over 64 K on all RPC requests.
Nonetheless, a client could connect 1000 times, on each connection send
the first 64 K of a slightly larger message, and just sit there.  That
would obviously consume about 64 Megabytes of memory, as SFS will wait
patiently for the rest of the request.

A worse problem is that SFS servers do not currently flow-control
clients.  Thus, an attacker could make many RPCs but not read the
replies, causing the SFS server to buffer arbitrarily much data and run
out of memory.  (Obviously the server eventually flushes any buffered
data when the TCP connection closes.)

Connecting to an SFS server costs the server tens of milliseconds of CPU
time.  An attacker can try to burn a huge amount of the server's CPU
time by connecting to the server many times.  The effects of such
attacks can be mitigated using hashcash, @@ref{HashCost}.

Finally, a user on a client can cause a large number of file systems to
be mounted.  If the operating system has a limit on the number of mount
points, a user could run the client out of mount points.

@@subheading Non-idempotent operations

If a TCP connection is reset, the SFS client will attempt to reconnect
to the server and retransmit whatever RPCs were pending at the time the
connection dropped.  Not all NFS RPCs are idempotent however.  Thus, an
attacker who caused a connection to reset at just the right time could,
for instance, cause a @@command{mkdir} command to return @@code{EEXIST}
when in fact it did just create the directory.

@@subheading Injecting packets on the loopback interface

SFS exchanges NFS traffic with the local operating system using the
loopback interface.  An attacker with physical access to the local
Ethernet may be able to inject arbitrary packets into a machine,
including packets to 127.0.0.1.  Without packet filtering in place, an
attacker can also send packets from anywhere making them appear to come
from 127.0.0.1.

On the client, an attacker can forge NFS requests from the kernel to
SFS, or forge replies from SFS to the kernel.  The SFS client encrypts
file handles before giving them to the operating system.  Thus, the
attacker is unlikely to be able to forge a request from the kernel to
SFS that contain a valid file handle.  In the other direction however,
the reply does not need to contain a file handle.  The attacker may well
be able to convince the kernel of a forged reply from SFS.  The attacker
only needs to guess a (possibly quite predictable) 32-bit RPC XID
number.  Such an attack could result, for example, in a user getting the
wrong data when reading a file.

On the server side, you also must assume the attacker cannot guess a
valid NFS file handle (otherwise, you already have no
security---@@pxref{NFS security}).  However, the attacker might again
forge NFS replies, this time from the kernel to the SFS server software.

To prevent such attacks, if your operating system has IP filtering, it
would be a good idea to block any packets either from or to 127.0.0.1 if
those packets do not come from the loopback interface.  Blocking traffic
"from" 127.0.0.1 at your firewall is also a good idea.

@@subheading Causing deadlock

On BSD-based systems (and possibly others) the buffer reclaiming policy
can cause deadlock.  When an operation needs a buffer and there are no
clean buffers available, the kernel picks some particular dirty buffer
and won't let the operation complete until it can get that buffer.  This
can lead to deadlock in the case that two machines mount each other.

@@subheading Getting private file data from public workstations

An attacker may be able to read the contents of a private file shortly
after you log out of a public workstation if the he can then become root
on the workstation.  There are two attacks possible.

First, the attacker may be able to read data out of physical memory or
from the swap partition of the local disk.  File data may still be in
memory if the kernel's NFS3 code has cached it in the buffer cache.
There may also be fragments of file data in the memory of the
@@command{sfsrwcd} process, or out on disk in the swap partition (though
@@command{sfsrwcd} does its best to avoid getting paged out).  The
attacker can read any remaining file contents once he gains control of
the machine.

Alternatively, the attacker may have recorded encrypted session traffic
between the client and server.  Once he gains control of the client
machine, he can attach to the @@command{sfsrwcd} process with the
debugger and learn the session key if the session is still open.  This
will let him read the session he recorded in encrypted form.

To minimize the risks of these attacks, you must kill and restart
@@command{sfscd} before turning control of a public workstation over to
another user.  Even this is not guaranteed to fix the problem.  It will
flush file blocks from the buffer cache by unmounting all file systems,
for example, but the contents of those blocks may persist as
uninitialized data in buffers sitting on the free list.  Similarly, any
programs you ran that manipulated private file data may have gotten
paged out to disk, and the information may live on after the processes
exit.

In conclusion, if you are paranoid, it is best not to use public
workstations.

@@subheading Setuid programs and devices on remote file systems

SFS does its best to disable setuid programs and devices on remote file
servers it mounts.  However, we have only tested this on operating
systems we have access to.  When porting SFS to new platforms, It is
worth testing that both setuid programs and devices do not work over
SFS.  Otherwise, any user of an SFS client can become root.

@@node Contacts, Concept Index, Security, Top
@@comment  node-name,  next,  previous,  up
@@chapter How to contact people involved with SFS

Please report any bugs you find in SFS to
@@email{sfsbug@@@@redlab.lcs.mit.edu}.

You can send mail to the authors of SFS at
@@email{sfs-dev@@@@pdos.lcs.mit.edu}.

There is also a mailing list of SFS users and developers at
@@email{sfs@@@@sfs.fs.net}.  To subscribe to the list, send mail to
@@email{sfs-subscribe@@@@sfs.fs.net}.


@@page
@@node    Concept Index,  , Contacts, Top
@@comment  node-name,  next,  previous,  up
@@unnumbered Concept Index

@@printindex cp

@@bye

@@c Local Variables:
@@c makeinfo-options: "--no-split --fill-column=70"
@@c End:

@@c  LocalWords:  texinfo sfs texi kaminsky Exp setfilename dirs settitle iftex
@@c  LocalWords:  setchapternewpage dslash ifnottex hslash direntry ifinfo Mazi
@@c  LocalWords:  eres titlepage vskip pt filll dir detailmenu SFS's config DNS
@@c  LocalWords:  sfsrwsd sfsauthd sfssd srp params SRP sfscd sfsagent sfskey dc
@@c  LocalWords:  dirsearch newaid sfsagents vidb funmount cindex var HostID dfn
@@c  LocalWords:  noindent xref sfsuser gcc OpenBSD FreeBSD OSF uref linux gmp
@@c  LocalWords:  libgmp gzip gz xvf cd pxref env CC CXX sfsgroup sfsdir etcdir
@@c  LocalWords:  datadir repo shlib openssl noreturn ECXXFLAGS CXXDEBUG tmp csh
@@c  LocalWords:  TMPDIR unlimit datasize ulimit ranlib usr lib uzwadtctbjb dg
@@c  LocalWords:  waiyru cx kb localhost mkdir rw exportfs nfs mountd EDEADLK xt
@@c  LocalWords:  Rabin passphrase logname vbox vss sfsrwcd nfsmounter SIGKILL
@@c  LocalWords:  emph pitt rexmmr enmhsemr jjhjm fdr hki vgn gwkuknve xqrv mbv
@@c  LocalWords:  uui ludlow hcbafipmin eqmsgak heequppitiz ttg gvinyxrfe zgv ls
@@c  LocalWords:  mefmjbb iur PKGDATADIR certpath authserver colorizes stat mp
@@c  LocalWords:  conffile IDs SFSLIBDIR suidconnect setgid anonuser uid gids db
@@c  LocalWords:  ResvGids resvgids setuid RSASize DlogSize Schnorr PwdCost rexd
@@c  LocalWords:  pwdcost LogPriority syslog Keyfile LeaseTime Userfile passwd
@@c  LocalWords:  admin hideusers uidmap gidmap pubpath updatable authdb privs
@@c  LocalWords:  userfile usernames itemx groupquota DBcache Sleepycat dbcache
@@c  LocalWords:  BerkeleyDB Logfile logfile SRPfile gensrp pre Denyfile NIS YP
@@c  LocalWords:  authservers authserver's certprog bookmarks SRV ln pubkey dm
@@c  LocalWords:  privkey srvprivkey username users's proactive BindAddr ip addr
@@c  LocalWords:  INADDR RevocationDir srvrevoke revokegen HashCost ext srvno LP
@@c  LocalWords:  arg unix NATted srpgen PubKeySize Libdir vers dnkF keyname mpp
@@c  LocalWords:  AGENTSOCK pwfd passphrases Keynames keylabel servername nbits
@@c  LocalWords:  CNAME certclear certlist dest perl clpq link's mit edu outfile
@@c  LocalWords:  deleteall Smp srpfile keynames keyhalf KP BEKP hostid okeyname
@@c  LocalWords:  wkeyfile nkeyname keypair keypairs gethash membername pkhash
@@c  LocalWords:  ownername groupname authserv ql norevokeset norevokelist Kp pq
@@c  LocalWords:  authkeys fgpPK bcgp newkeyfile newhost oldhost oldkeyfile fE
@@c  LocalWords:  revokelist revokeclear revokeprog sesskill remotehost sesslist
@@c  LocalWords:  srpkey HostId akS TAXpv lport pagsh grouplist grouplists argv
@@c  LocalWords:  ptrace proc su ps dbenv API cachesize lk umount loopback df ld
@@c  LocalWords:  fstat lsof sockfile sfssauthd cvs CVS CVSROOT inode fsid UDP
@@c  LocalWords:  fsirand OSes UX portmap RPCs Wietse Venema resok obj RPC's XID
@@c  LocalWords:  NFSPROC GETATTR FSINFO PATHCONF netstat hashcash EEXIST cp
@@c  LocalWords:  printindex makeinfo
@


1.101
log
@checkpoint some old docs I forgot about
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.100 2004/10/26 02:09:36 dm Exp $
d131 1
a131 1
* Sharing @@file{sfs_users} files::  Same users recognized by multiple servers
d137 1
a137 1
* sfsrosd_config::              Read-only file server configuration
d789 1
a789 1
* Sharing @@file{sfs_users} files::  Same users recognized by multiple servers
d898 1
a898 1
@@node Administrative realms, Sharing @@file{sfs_users} files, Managing user keys, Administering SFS
d1017 1
a1017 1
@@node Sharing @@file{sfs_users} files,  , Administrative realms, Administering SFS
d1141 1
a1141 1
* sfsrosd_config::              Read-only file server configuration
d1314 2
@


1.100
log
@remove extraneous end tag
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.99 2004/09/07 17:57:23 fubob Exp $
d2015 27
d2142 1
a2142 1
344446, version 1.  The read-only code has not been released yet.  The
d2152 1
@


1.99
log
@start with some generic, incomplete documentation of SFSRO.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.98 2004/06/13 22:49:11 dm Exp $
a3853 1
@@c @@mp @@description
@


1.98
log
@disallow read-write database files
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.97 2004/06/04 01:03:11 dm Exp $
d137 1
d158 1
d810 1
d847 4
d882 5
d1123 3
d1141 1
d1243 1
a1243 1
@@node sfsrwsd_config, sfsauthd_config, sfs_config, SFS configuration
d1312 19
a1330 1
@@node sfsauthd_config, sfs_hosts, sfsrwsd_config, SFS configuration
d2156 1
d3803 1
a3803 1
@@node sfsrwsd, sfsauthd, funmount, Command reference
d3835 35
a3869 1
@@node sfsauthd, sfsrwcd, sfsrwsd, Command reference
@


1.97
log
@update documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.96 2004/05/18 18:26:54 dbg Exp $
d1323 13
d1782 13
a1794 8
is considered ASCII.  It is highly recommended that administrators
@@emph{not} use database files (as opposed to directories) for anything
other than public, read-only @@file{sfs_users} files shared amongst
machines.  (The reason is that read-write database files require
write-ahead logging, which relies on auxiliary files stored in
@@file{@@value{SFSDIR}@@dslash{}dbenv}.  It is easy to forget this and
rename or delete database files stored elsewhere, with the disastrous
result that old log records may get applied to different files.)
d3562 5
a3566 2
directory).  For database files, the supporting database files are in
directory @@file{@@value{SFSDIR}@@dslash{}dbenv}.
d3568 12
a3579 12
Note that database files use write-ahead logging, with the logs stored
in the directory for supporting files.  In particular, simply
@@emph{moving or deleting a database file can have disastrous
consequences} when the logs do not reflect the changes.  For instance
old log entries can get applied to a new file, confusingly
resurrecting entries from what you might think was a deleted database.
For this reason, we highly recommend that administrators @@emph{not}
use database files (ending @@file{.db}) for read-write user databases.
(For read-only ``public'' databases, it should be fine.)  Instead,
administrators who want something more efficient than flat text files
should use database directories (ending @@file{.db/}), which provide a
better intuition for what renaming or deleting the database does.
d3683 8
a3690 7
@@file{DB_CONFIG} in the directory with supporting files (the directory
itself for @@file{.db/} databases, and
@@file{@@value{SFSDIR}@@dslash{}dbenv} for database files).  The
specifics of the configuration file are documented in the Sleepycat
database documentation.  As an example, if performance is slow and you
run out of locks, you can set the cache size to 128MB and increase the
number of locks with the following @@file{DB_CONFIG} file:
@


1.96
log
@typo
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.95 2004/05/14 23:46:03 max Exp $
d158 2
d2105 2
a3719 1
@@cindex @@command{nfsmounter}
d3778 1
a3778 1
@@node sfsauthd,  , sfsrwsd, Command reference
d3817 220
@


1.95
log
@Changed sfskey gethash to use the SHA(SHA(k),k) method by default.
Old method is still available internally, not via sfskey gethash.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.94 2004/05/14 23:41:58 max Exp $
d3122 1
a3122 1
forward agent requests back the @@command{sfsagent} running on the
@


1.94
log
@Refactored sfskey gethash code.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.93 2004/05/08 20:33:40 dm Exp $
a2676 4

@@item -p
Compute a hash as done for SFS pathnames. In other words, if the 
given key is k, compute SHA(SHA(k), k).
@


1.93
log
@improve description of sfs_users
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.92 2004/04/23 21:58:02 dm Exp $
d2667 1
a2667 1
@@item sfskey gethash [-6] @@var{keyname}
d2673 9
@


1.92
log
@death trigger in /tmp
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.91 2004/04/19 21:39:46 dm Exp $
d1615 3
a1617 2
groups. It is roughly analogous to the Unix @@file{/etc/passwd} file.
Each line of @@file{sfs_users} has the following format (split into two
d1621 1
a1621 1
[USER|GROUP]:@@var{user}:@@var{uid}:@@var{version}:@@var{gid}:@@var{owner}:@@var{pubkey}:@@var{privs}
d1625 4
d1633 5
a1637 4
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., @@samp{dm/root}, @@samp{kaminsky/root}, etc.).
d1651 2
a1652 1
This field is ignored as of SFS 0.7.
d1656 1
a1656 1
key.  Can be either a Rabin or 2-Schnorr public key as of SFS 0.7.
d1659 34
a1692 3
The @@var{privs} field indicates whether a field can be updated by 
the SFS admin---given of course that a Userfile is included with the
@@option{-admin} option.
d1699 3
a1701 3
fetch the wrong @@var{HostID}.  Note also that @@var{SRP-info} is specific
to a particular hostname.  If you change the @@var{Location} of a file
server, users will need to register new @@var{SRP-info}.
d1721 69
a1789 4
Note if you edit @@file{sfs_users} files by hand, you risk overwriting
concurrent updates by @@command{sfsauthd}.  Use the @@command{vidb}
@@pxref{vidb} command to lock @@file{sfs_users} files while you edit
them.
@


1.91
log
@use getpeereid if we have it
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.90 2004/04/15 07:02:41 dm Exp $
d3231 2
a3232 2
able to exploit weaknesses in the operating systems @@code{ptrace}
system call or proc file system to learn the private key.
@


1.90
log
@more nits in documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.89 2004/04/15 06:47:07 dm Exp $
d3874 7
@


1.89
log
@some nits in documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.88 2004/03/27 19:45:34 dm Exp $
d1328 1
a1328 1
database is assumed to read-only and possibly on a remote machine.
d1381 1
a1381 1
See above.  Functions the same as @@option{gid} and @@option{gidmap}, but 
d1398 1
a1398 1
quota takes precendent and overrides this global (UserFile-wide) setting.
d1418 2
a1419 2
fetching the record that--in the event that the authentication server is
unavailable---then entity can continue to use its cached copy of this
d1482 2
a1483 2
in the same realm.  Thus, a user that wants to authenticate to a realm,
can contact any authserver in that realm.
@


1.88
log
@sync up sfssd's behavior and documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.87 2004/03/23 01:30:06 dbg Exp $
d624 2
a625 2
In general, the procedure for exporting NFS file systems varies greatly
between operating systems.  Check your operating system's NFS
d627 11
a637 1
good place to start.)
d762 2
a763 2
access to one SFS file server, you can store on it symbolic links
pointing to other servers' self-certifying pathnames.
d1077 1
a1077 1
SFS comprises a number of programs, many of which have configuration
d1097 1
a1097 1
overrides the version in @@file{@@file{PKGDATADIR}}.
@


1.87
log
@typo
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.86 2004/03/10 21:34:41 kaminsky Exp $
d1701 34
a1734 8
Specifies the IP address and port on which @@command{sfssd} should
listen for TCP connections.  The default is @@code{INADDR_ANY} for the
address and 0 (or the value of the @@env{SFS_PORT} environment
variable) for the port number if no @@var{port} is specified.  A port
number of 0 means to check DNS for port numbers specified in SRV
records, and to use port 4 in the common case that no SRV records are
employed.  @@samp{BindAddr} can be specified multiple times to listen
on multiple addresses and/or ports.
d2815 2
a2816 3
Clears the in-memory cache of server self-certifying hostnames
built from SRP results.  @@xref{srplist} for more details on
this cache.
d2850 1
a2850 1
above; @@xref{srplist}).  The agent will invoke the SRP cache management
d2857 8
a2864 7
In the first case (load), the program output must consist of one mapping per
line.  Each mapping must consist of the SRP name followed by a single space
followed by the self-certifying hostname. @@xref{srplist} for an example
of what each of these fields might look like.  In the second case (store),
the agent's argument to the program will consist of a single mapping, to
be added to the on-disk cache.  The mapping will have the same format
described above: the SRP name followed by a single space followed by the
d3757 1
a3757 1
spawning an unprivileged user programs.  These variables ordinarily
d3785 1
a3785 1
environment variable with given the @@option{-S} option, so that
d3799 1
a3799 1
It checks the systems name with the @@code{gethostname} system call,
d3814 1
d3833 3
a3835 3
TCP port 5 on your server, you might want to specify @@samp{BindAddr 5}
in @@file{sfssd_config}, but you almost certainly would not want to set
the @@env{SFS_PORT} environment variable to 5, as setting
@


1.86
log
@Re-do support for saving/restoring an SRP name cache to/from disk so the
agent doesn't directly do IO.  Now we can set an external program to do
the save/restore for us.  A sample shell script is included.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.85 2004/03/05 18:04:04 kaminsky Exp $
d2790 1
a2790 1
built from SRP results.  @@xref{srplist}, for more details on
@


1.85
log
@add support for setting the default group quota + documentation and
a bug fix
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.84 2004/03/01 19:50:26 fubob Exp $
d2287 38
d2787 53
@


1.84
log
@clarify "sfskey hostid" command
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.83 2004/02/29 21:31:41 kaminsky Exp $
d1304 1
a1304 1
@@item Userfile [-update] [-create] [-passwd] [-admin] [-hideusers] [-prefix=@@var{prefix}] [-refresh=@@var{seconds}] [-timeout=@@var{seconds}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-groups=@@var{g1}-@@var{g2}] [-pub=@@var{pubpath}] @@var{path}
a1327 1

d1344 14
d1383 9
a1412 14

@@item -pub=@@var{pubpath}
@@command{sfsauthd} supports the secure remote password protocol, or SRP.
SRP lets users connect securely to @@command{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 @@var{path} specified in
@@samp{Userfile} contains these secrets for users opting to use SRP.  The
@@option{-pub} option tells @@command{sfsauthd} to maintain in
@@var{pubpath} a separate copy of the database without secret
information.  @@var{pubpath} might reside on an anonymously readable SFS
file system---other machines can then import the file as a read-only
database using a @@command{Userfile} line with the @@option{-update}
flag.
@


1.83
log
@add 'sfskey user' command for querying user records
support for refresh/timeout values in sfsauthd
support for disabling the auth cache/symbolic+recursive groups
associated documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.82 2004/01/07 23:08:45 dm Exp $
d2542 2
a2543 1
@@item sfskey hostid @@var{hostname}
d2546 3
a2548 2
prints @@samp{@@@@@@var{Location},@@var{HostID}} to standard output.  If
@@var{hostname} is simply @@samp{-}, returns the name of the current
@


1.82
log
@honor expiration time in password files; this is tested on OpenBSD, but not
linux.  I'm not exactly sure how linux's mechanism works, so this
is a guess...
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.81 2004/01/06 23:58:07 dm Exp $
d1304 1
a1304 1
@@item Userfile [-update] [-create] [-passwd] [-admin] [-hideusers] [-prefix=@@var{prefix}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-groups=@@var{g1}-@@var{g2}] [-pub=@@var{pubpath}] @@var{path}
d1370 22
d1428 14
d2489 11
a2499 9
@@item sfskey group [-a @@var{key}] [-C] [-m @@{+|-@@}@@var{membername}] [-o @@{+|-@@}@@var{ownername}] @@var{groupname}
Retrieves, creates, and modifies group lists on an authentication
server.  If none of @@option{-C}, @@option{-m}, and @@option{-o} is given,
@@command{sfskey} will query the authentication server for the group and
print out the result.  The @@option{-C}, @@option{-m}, and @@option{-o}
options imply group creation and/or update.  @@var{groupname} can be
local (contact the local @@command{sfsauthd}) or remote (contact a
remote @@command{sfsauthd} using a user-specified self-certifying hostname
or SRP).
d2503 12
a2514 6
This argument can be supplied arbitrarily many times, once for each
key that should be loaded into @@command{sfskey} for this session.
Keynames are specified as described above, and can be remote or
local filenames. Usually it will not be necessary to specify keys in the
keys directory (@@file{$HOME/.sfs/authkeys}) as they are considered
automatically. 
d2517 9
a2525 3
This argument tells @@command{sfskey} to create a new group called
@@var{groupname} if it does not already exists.  If the group does exist,
it it modified.
d2529 1
a2529 1
This argument tells @@command{sfskey} to add (+) or subtract (-) the given
d2536 1
a2536 1
are ignored.
d2782 5
a2786 6
This argument can be supplied arbitrarily many times, once for each
key that should be loaded into @@command{sfskey} for this session.
Keynames are specified as described above, and can be remote or
local filenames. Usually it will not be necessary to specify keys in the
keys directory (@@file{$HOME/.sfs/authkeys}) as they are considered
automatically. 
d2812 18
@


1.81
log
@lots of documentation improvements
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.80 2003/12/24 00:11:15 dm Exp $
d543 1
a543 1
@@pxref{SFS_HOSTNAME}.  If you don't have a DNS name pointint to your
@


1.80
log
@document sfs_hosts, fix a bunch of things in the documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.79 2003/07/10 17:44:20 kaminsky Exp $
d106 1
d532 16
a547 1
To create a public/private key pair for your server, run the commands:
d1152 1
d1200 1
a1200 1
The default value is 11.  @@var{cost} is an exponential parameter.
d1240 19
a1258 4
users read-only access to the file system (under user ID -2 and group ID
-2).  Appending @@samp{W} gives anonymous users both read and write
access.  @@xref{Quick server setup}, for an example of the @@samp{Export}
directive.
d1261 7
a1267 7
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 @@samp{R} option---probably just
crashing your server but possibly doing worse.
d1270 9
d1656 9
a1664 3
Specifies the IP address and port on which @@command{sfssd} should listen
for TCP connections.  The default is @@code{INADDR_ANY} for the address
and port 4.
d1808 13
a1820 2
1,024 is a good value for @@var{bits} even if @@samp{PubKeySize} is
slightly larger in @@file{sfs_config}.
d1903 1
a1903 1
@@node Command reference, Security, SFS configuration, Top
d3305 1
a3305 1
on flat text databases, or if the if @@option{-S} has been specified.
d3505 176
d3682 1
a3682 1
@@node Security, Contacts, Command reference, Top
@


1.79
log
@document the "-hideusers" option to the userfile directive in the
sfsauthd_config file
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.78 2003/07/10 17:28:02 kaminsky Exp $
d103 1
a103 1
* Administering SFS::           Guid to common administrative tasks
d134 8
a141 7
* @@file{sfs_config}::           System-wide configuration parameters
* @@file{sfsrwsd_config}::       File server configuration
* @@file{sfsauthd_config}::      User-authentication daemon configuration
* @@file{sfs_users}::            User-authentication database
* @@file{sfssd_config}::         Meta-server configuration
* @@file{sfs_srp_params}::       Default parameters for SRP protocol
* @@file{sfscd_config}::         Meta-client configuration
d422 1
a422 2
Build the sources by running @@samp{make}. Note that a GNU-comptabile
@@samp{make} may be required to build SFS.
d880 1
a880 1
directory of symbolic links to self-certifing pathnames of other
d1059 4
a1062 4
@@file{@@value{PKGDATADIR}} for all configuration files except
@@file{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 @@file{@@value{ETCDIR}}.
d1096 8
a1103 7
* @@file{sfs_config}::           System-wide configuration parameters
* @@file{sfsrwsd_config}::       File server configuration
* @@file{sfsauthd_config}::      User-authentication daemon configuration
* @@file{sfs_users}::            User-authentication database
* @@file{sfssd_config}::         Meta-server configuration
* @@file{sfs_srp_params}::       Default parameters for SRP protocol
* @@file{sfscd_config}::         Meta-client configuration
d1107 1
a1107 1
@@node @@file{sfs_config}, @@file{sfsrwsd_config}, SFS configuration, SFS configuration
a1110 1
@@anchor{sfs_config}
d1163 2
a1164 2
on the diffculty of factoring integers.  The Rabin public keys used in
self-certifying pathnames are affected by this paremeter.  The default
d1169 2
a1170 2
on the diffculty of taking discrete logs in subgroups of
@@strong{Z}@@emph{p}*.  This parameter affects SRP paremeter and
d1198 1
a1198 1
@@node @@file{sfsrwsd_config}, @@file{sfsauthd_config}, @@file{sfs_config}, SFS configuration
a1201 1
@@anchor{sfsrwsd_config}
d1243 1
a1243 1
@@node @@file{sfsauthd_config}, @@file{sfs_users}, @@file{sfsrwsd_config}, SFS configuration
a1246 1
@@anchor{sfsauthd_config}
d1249 1
a1249 1
@@c @@mp @@conffile{sfsauthd_config}{user-authentication daemon confiuration}
d1292 1
a1292 1
might register an SFS key (note this allso requires the
d1449 62
a1510 1
@@node @@file{sfs_users}, @@file{sfssd_config}, @@file{sfsauthd_config}, SFS configuration
a1513 1
@@anchor{sfs_users}
d1597 1
a1597 1
@@node @@file{sfssd_config}, @@file{sfs_srp_params}, @@file{sfs_users}, SFS configuration
a1600 1
@@anchor{sfssd_config}
d1744 1
a1744 1
@@node @@file{sfs_srp_params}, @@file{sfscd_config}, @@file{sfssd_config}, SFS configuration
a1747 1
@@anchor{sfs_srp_params}
d1768 1
a1768 1
@@node @@file{sfscd_config},  , @@file{sfs_srp_params}, SFS configuration
a1771 1
@@anchor{sfscd_config}
d1985 1
a1985 1
signature servers in case his primary server becomes unavailabe.  By
d2087 1
a2087 1
registerd his SRP information.  It may not be the same as the
d2202 1
a2202 1
for the next appropraite keyname in @@file{$HOME/.sfs/authkeys}.  In this case,
d2219 2
a2220 2
generate the next availabe default key in @@file{$HOME/.sfs/authkeys}.
A @@var{keyname} of ther form @@file{@@var{prefix}#} implies that
d2236 1
a2236 1
Refreshes a 2-Schnorr key by resharing a secret between a server
d2290 2
a2291 2
the next avaible Rabin key in @@file{$HOME/.sfs/authkeys} with the
prefix @@var{prefix}.  If @@var{keyname} contains a non-termainl @@file{#}
d2366 1
a2366 1
Speficies the number of bits for the 2-Schnorr modulus p.  The security of
d2407 1
a2407 1
This arugment can be supplied arbitrarily many times, once for each
d2415 1
a2415 1
This arugment tells @@command{sfskey} to create a new group called
d2421 1
a2421 1
This arugment tells @@command{sfskey} to add (+) or subtract (-) the given
d2485 1
a2485 1
is a procative 2-Schnorr key, then all current 2-Schnorr keys in 
d2546 2
a2547 2
then next available key with the prefix @@var{prefx} in the standard
keys direcotry (@@file{$HOME/.sfs/authkeys}).  If @@command{sfskey
d2554 1
a2554 1
Generate a new proctive 2-Schnorr key.  Implies the @@option{-g} flag.
d2582 1
a2582 1
removable media (e.g., @@file{/floppy/complete-key-2}).  It is a susbstantial
d2656 1
a2656 1
for instance, the auth server has changed its realm information.  Invoking
d2674 1
a2674 1
This arugment can be supplied arbitrarily many times, once for each
d2687 1
a2687 1
a local file, or a keyname with a '#' sign, signifyin a key
d2820 1
a2820 1
@@command{dirsearch} is particularly useful for SFS certificaton
d2836 1
a2836 1
pathname will automaticlaly become a symbolic link to your bookmark.
d3163 23
a3185 1
overwriting each other.
d3193 1
a3193 1
vidb [-r] [-w] [-e @@var{editor}] @@var{sfs-users-file}
d3201 28
a3228 7
@@item -r
Recovers from a previous edit session.  @@command{vidb} makes a copy of
of @@var{sfs-users-file} to be edited, named by appending @@file{.tmp}
to the file name.  If an editing session crashes, vidb will refuse to
run, as the old temporarly file may contain useful data that should
not be deleted.  With @@option{-r}, however, @@command{vidb} removes any
old temporary file.
d3231 2
a3232 2
The point of @@command{vidb} is to avoid concurrent edits to the
database and the corresponding inconsistencies that might result.
d3235 35
a3269 2
@@command{vidb} to wait until it can acquire the lock on the database,
and then run.
a3270 5
@@item -e @@var{editor}
Specifies the editor to use for editing the file.  The default is to
use the command specified by the enviornment variable @@env{EDITOR}.
If there is no environment variable and @@option{-e} is not specified,
@@command{vidb} uses @@command{vi}.
d3283 24
d3776 1
a3776 1
ethernet may be able to inject arbitrary packets into a machine,
d3879 38
@


1.78
log
@update docs to metion the -groups option to the userfile directive
in sfsauthd_config
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.77 2003/07/10 14:40:33 kaminsky Exp $
d1265 1
a1265 1
@@item Userfile [-update] [-create] [-passwd] [-admin] [-prefix=@@var{prefix}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-groups=@@var{g1}-@@var{g2}] [-pub=@@var{pubpath}] @@var{path}
d1301 4
@


1.77
log
@document new dbcache directive in the sfsauthd_config file
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.76 2003/03/07 18:04:34 kaminsky Exp $
d1265 1
a1265 1
@@item Userfile [-update] [-create] [-passwd] [-admin] [-prefix=@@var{prefix}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-pub=@@var{pubpath}] @@var{path}
d1319 8
d1370 1
a1370 1
file using the "sfskey gensrp" command. The default is
d1410 1
a1410 1
"sfskey login" command; this list of directories will become the
@


1.76
log
@update sfskey group command
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.75 2003/02/27 19:10:13 kaminsky Exp $
d1340 13
@


1.75
log
@added sfskey gethash and sfskey group
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.74 2003/01/09 09:34:51 dm Exp $
d2342 7
a2348 3
member or owner name to the given group.  Duplicate member names and
owner names are removed from the group before it is updated.  Removals of
names that don't exists are ignored.
@


1.74
log
@more umac hacking
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.73 2002/12/28 06:30:58 max Exp $
d2308 38
@


1.73
log
@Fixed bug in sfskey update -r documentation.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.72 2002/12/27 07:09:26 dm Exp $
d2781 2
a2782 2
reserved group IDs is @@var{min}..@@var{max}, and the @@emph{first}
element of a process's grouplist, @@var{g0} is at least @@var{min} and
d2806 1
d2818 1
a2818 1
Command shells interpret this to mean that they are being being run a
d2836 2
a2837 2
@@strong{insecure} to use @@option{-U} unless you set the both the gid
and the whole grouplist to something sensible (i.e., appropriately
d2842 9
a2850 3
@@code{setuid} system call themselves for fear the the operating
system's @@code{ptrace} system call is broken and would create s
security hole.
@


1.72
log
@implement reverse file descriptor passing
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.71 2002/12/22 07:27:14 dm Exp $
d2572 1
a2572 1
@@command{sfskey update -a @@var{host} [@@var{user}]@@@@@@var{host}}.
@


1.71
log
@start of administering sfs chapter
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.70 2002/12/08 16:07:34 dm Exp $
d983 1
a983 1
cases, users can access all servers in the realm with a single
d990 6
a995 5
trust to specify the identities of users in the realm.  One of the
trusted servers, the primary, is the one on which users update their
accounts.  Every administrative realm must have a primary server.  An
untrusted server recognizes all users in the realm, but is not
necessarily trusted by users or other servers in the realm.
@


1.70
log
@newaid clarified
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.69 2002/12/06 20:05:24 max Exp $
d103 1
a103 1
* System overview::             High-level overview of SFS's components
d125 7
d478 1
a478 1
@@node Getting Started, System overview, Installation, Top
d557 4
a560 4
exported namespace, say @@file{/var/sfs/root}, create the necessary
@@var{sfs-name} subdirectories, and create a corresponding
@@file{sfsrwsd_config} file.  You might run the following commands to do
this:
d563 3
a565 3
% mkdir /var/sfs/root
% mkdir /var/sfs/root/usr1
% mkdir /var/sfs/root/usr2
d572 1
a572 1
Export /var/sfs/root /
d586 1
a586 1
/var/sfs/root localhost
d594 1
a594 1
/var/sfs/root localhost(rw)
d603 1
a603 1
share -F nfs -o -rw=localhost /var/sfs/root
d751 1
a751 1
@@node System overview, SFS configuration, Getting Started, Top
d753 12
a764 1
@@chapter System overview
d853 194
a1046 1
@@node SFS configuration, Command reference, System overview, Top
d1279 4
a1282 3
Thus, @@command{sfsauthd} maintains local copies of read-only databases in
@@file{/var/sfs/authdb}.  This process ensures that temporarily
unavailable file servers never disrupt @@command{sfsauthd}'s operation.
d1343 2
a1344 2
generated by @@command{sfsauthd}.  The default logfile is 
@@file{/var/sfs/sign_log}.
d1360 1
d1540 2
a1541 2
@@file{/var/sfs/srvrevoke}.  Use the command @@samp{sfskey revokegen} to
generate revocation certificates.
@


1.69
log
@Changed documentation for sfskey update; fixed documentation bugs; changed
release to 0.7.1.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.68 2002/12/03 21:56:47 max Exp $
d2543 7
a2549 6
file systems using the @@command{sfsagent} of a non-root user.  If a
system is configured to allow this, @@command{newaid} also permits
non-root users to run multiple @@command{sfsagent} processes, so that
different processes owned by that user access the SFS file system with
different processes.  (When used in The latter mode, @@command{newaid}
is similar in function to the AFS program @@command{pagsh}.)
@


1.68
log
@Bugfix for sfskey gethash
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.67 2002/12/03 20:55:48 dm Exp $
d1076 8
a1083 3
Allows users who do not exist in the database to register initial public
keys by typing their UNIX passwords.  @@xref{sfskey register}, for
details on this. 
d1166 2
a1167 2
If the user is logged on to the authserver, he can use the hostname
@@var{-} to signify the local host:
d2273 11
d2296 1
a2296 1
@@item sfskey update [-E] [-S | -s @@var{srp_params}] [-r @@var{srpkey}] [-a @@{@@var{server} | -@@}] [-k @@var{okeyname}] [@@var{nkeyname}]
a2297 2
The default value for @@var{newkey} is @@file{$HOME/.sfs/identity}.

d2301 1
a2301 1
you needs to change your public key.
d2304 1
a2304 1
@@command{sfskey update} will first use the keys given via @@option{-k}
d2308 11
d2322 1
a2322 1
equivalent to @@command{sfskey update -a @@var{host} [@@var{user}]@@@@@@var{host}}.
d2337 1
a2337 8
@@item -s
@@var{srp_params} is the path of a file generated by @@command{sfskey
srpgen}, and specifies the parameters to use in generating SRP
information for the server.  The default is to get SRP parameters from
the server, or look in
@@file{@@value{PKGDATADIR}@@dslash{}sfs_srp_params}.

@@item -k @@var{keyname}
d2340 4
a2343 2
Keynames are specified as described above, and can be remote,
local filenames, or keys in the @@file{$HOME/.sfs/authkeys} directory.
d2345 10
a2354 10
@@itemx -a -
@@item -a @@var{server}
Can be specified arbitrarily many times, once for each server that
will be updated with the new key given by @@var{nkeyname}. To specify the
local host, use the first syntax.  If SRP is used to download a key
from host @@var{host} (e.g., @@option{-k @@var{user}@@@@@@var{host}}), then
you can specify that host by its simple hostname (e.g., @@option{-a
@@var{host}}).  If SRP was not used to connect to a host @@var{host},
then @@option{-a} requires a complete SFS host identifier (e.g., 
@@@@@@var{Location},@@var{HostID}).
d2361 6
d2368 2
@


1.67
log
@fiddle with variables
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.66 2002/12/03 20:17:18 max Exp $
d1161 2
a1162 5
If the user has a local copy of his private key, in
@@file{~/.sfs/identity} for example, only the second step is necessary.
Also, if the user can login to the authserver, he can replace
@@samp{@@@@authserver,HOSTID} with @@samp{-} (the minus sign).  Thus, in the
simplest case, the user could simply run
d1165 1
a1165 1
sfskey update -a -
@


1.66
log
@Added sfskey update -r for changing realm information.  Changed som
of the documentation accordingly. Added no userfile checking in
sfsauthd startup.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.65 2002/12/03 16:55:13 dm Exp $
d6 1
d841 2
a842 2
directories---first @@file{/etc/sfs}, then, if they don't find the file
there, in @@file{/usr/local/share/sfs}.  You can change these locations
d847 1
a847 1
@@file{/usr/local/share/sfs} for all configuration files except
d850 1
a850 1
creating a new file of the same name in @@file{/etc/sfs}.
d854 6
a859 6
@@file{/usr/local/share/sfs/sfs_config} is always parsed, even if
@@file{/etc/sfs/sfs_config} exists.  Options in
@@file{/etc/sfs/sfs_config} simply override the defaults in
@@file{/usr/local/share/sfs/sfs_config}.  For all other configuration
files, a file in @@file{/etc/sfs} entirely overrides the version in
@@file{/usr/local}.
d920 2
a921 2
@@file{/usr@@dslash{}local@@dslash{}lib@@dslash{}sfs@@dslash{}suidconnect}
is setgid to the new @@var{sfs-group}.}
d1003 1
a1003 1
not start with @@file{/} in @@file{/etc/sfs}, or whatever directory you
d1049 1
a1049 1
not start with @@file{/} in @@file{/etc/sfs}, or whatever directory you
d1118 1
a1118 1
@@file{/etc/sfs}):
d1511 6
a1516 6
Specifies where SFS should look for daemon programs when their pathnames
do not begin with @@file{/}.  The default is
@@file{/usr/local/lib/sfs-@@value{VERSION}}.  The @@samp{Libdir} directive
does not do anything on its own, but applies to all subsequent
@@samp{Program} directives until the next @@samp{Libdir} or @@samp{Release}
directive.
d2319 2
a2320 1
the server, or look in @@file{/usr/local/etc/sfs/sfs_srp_params}.
d2630 8
a2637 8
The @@command{ssu} command allows an unprivileged user to become root on
the local machine without changing his SFS credentials.  @@command{ssu}
invokes the command @@command{su} to become root.  Thus, the access and
password checks needed to become root are identical to those of the
local operating system's @@command{su} command.  @@command{ssu} also
runs @@file{/usr/local/lib/sfs-@@value{VERSION}/newaid} to alter the group
list so that SFS can recognize the root shell as belonging to the
original user.
d2723 2
a2724 2
first to look for @@file{/etc/sfs/sfscd_config}, then
@@file{/usr/local/etc/sfs/sfscd_config}.
d2764 2
a2765 2
first to look for @@file{/etc/sfs/sfssd_config}, then
@@file{/usr@@dslash{}local@@dslash{}etc@@dslash{}sfs@@dslash{}sfssd_config}.
d2771 8
a2778 10
@@file{/usr@@dslash{}local@@dslash{}share@@dslash{}sfs} and
@@file{/etc@@dslash{}sfs} are searched in order, and if no file named
@@var{sfs-config-file} is found but a file @@file{sfs_config} is found,
that file is parsed.  However, the process does not look in
@@file{/etc/sfs} if @@var{sfs-config-file} is found in
@@var{/usr@@dslash{}local@@dslash{}share@@dslash{}sfs}.  Thus, if you
create a file @@file{/etc@@dslash{}sfs@@dslash{}}@@var{sfs-config-file},
it will override @@file{/etc@@dslash{}sfs@@dslash{}sfs_config} while
still incorporating the defaults from
@@var{/usr@@dslash{}local@@dslash{}share@@dslash{}sfs@@dslash{}sfs_config}.
d2917 1
a2917 1
/usr/local/lib/sfs-@@value{VERSION}/sfsrwsd [-f @@var{config-file}]
d2935 1
a2935 1
@@file{/etc/sfs/sfsrwsd_config}.
d2949 1
a2949 1
/usr/local/lib/sfs-@@value{VERSION}/sfsauthd [-u @@var{sockfile}] [-f @@var{config-file}]
d2971 1
a2971 1
@@file{/etc/sfs/sfsauthd_config}.
d3274 1
a3274 2
the setgid program
@@file{/usr@@dslash{}local@@dslash{}lib@@dslash{}sfs@@dslash{}suidconnect}.
@


1.65
log
@documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.64 2002/11/29 05:06:26 max Exp $
d1157 1
a1157 3
sfskey edit -o sfskey.priv username@@@@authserver
sfskey update -a @@@@authserver,HOSTID -k sfskey.priv sfskey.priv
rm sfskey.priv
d2282 1
a2282 1
@@item sfskey update [-E] [-S | -s @@var{srp_params}] [-a @@{@@var{server} | -@@}] [-k @@var{okeyname}] [@@var{nkeyname}]
d2296 5
d2336 5
a2340 1
@@item -B
@


1.64
log
@Fixed small typo in sfs.texi that broke manpager.pl.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.63 2002/11/28 20:38:31 dm Exp $
d68 1
a68 1
Copyright @@copyright{} 1999 David Mazi@@`eres
d198 8
d210 5
a214 4
key.  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 @@dfn{self-certifying pathnames}.
d266 1
a266 1
support.  We have run SFS successfully on OpenBSD, FreeBSD,
d269 1
d275 1
d336 4
a339 4
Do not put any users in @@var{sfs-group}, not even @@code{root}.  Any user
in @@var{sfs-group} will not be able to make regular use of the SFS file
system.  Moreover, having an unprivileged users in @@var{sfs-group}
causes a security hole.
d381 1
a381 1
@@var{user-group}, you do not need to recompile SFS.]
d385 4
a388 1
@@var{gmp-path} might be @@file{/usr/local}).
d404 7
a410 4
options such as @@option{--prefix}.  It also has several options that are
only for developers.  @@strong{Do not use the @@option{--enable-repo} or
@@option{--enable-shlib} options} (unless you are a gcc maintainer
looking for some wicked test cases for your compiler).
d462 4
a465 4
@@cindex Undefined symbol @@code{___gmp_default_allocate} referenced from text 
segment. On some operating systems, some versions of GMP do not install
the library properly.  If you get linker errors about symbols with
names like @@code{___gmp_default_allocate}, try running the command
d523 1
a523 1
To create a public/private key pair for your server, run the command:
d616 5
a620 4
Note: @@strong{You will not be able to access an SFS server using the
same machine as a client} unless you run @@command{sfscd} with the
@@option{-l} flag, @@ref{sfscd}.  Attempts to SFS mount a machine on
itself will return the error @@code{EDEADLK} (Resource deadlock avoided).
d636 32
d669 9
a677 9
This will create a public/private key pair for you and register it with
the server.  (Note that if you already have a public key on another
server, you can reuse that public key by giving @@command{sfskey} your
address at that server, e.g., @@samp{sfskey register
user@@@@other.server.com}.)

After registering your public key with an SFS server, you must run the
@@command{sfsagent} program on an SFS client to access the server.  On
the client, run the command:
d680 1
a680 1
sfsagent @@var{user}@@@@@@var{server}
d683 7
d692 2
a693 11
@@var{user} is your logname on that server.  This command does three
things:  It runs the @@command{sfsagent} program, which persists in the
background to authenticate you to file servers as needed.  It fetches
your private key from @@var{server} and decrypts it using your
passphrase.  Finally, it fetches the server's public key, and creates a
symbolic link from @@file{/sfs/@@var{server}} to
@@file{/sfs/@@@@@@var{server},@@var{HostID}}.

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
the command:
d696 2
a697 1
sfskey add @@var{user}@@@@@@var{server}
d701 29
a729 10
In fact, @@command{sfsagent} runs this exact command for you when you
initially start it up.

While @@command{sfskey} provides a convenient way of obtaining servers'
@@var{HostID}s, it is by no means the only way.  Once you have access to
one SFS file server, you can store on it symbolic links pointing to
other servers' self-certifying pathnames.  If you use the same public
key on all servers, then, you will only need to type your password
once.  @@command{sfsagent} will automatically authenticate you to
whatever file servers you touch.
d788 4
a791 4
@@command{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 @@command{nfsmounter} can only make
matters worse.
d851 2
a852 2
The @@file{sfs_config} file contains system-wide configuration parameters
for most of the programs comprising SFS.  Note that
d856 1
a856 1
@@file{/usr/local/share/sfs/sfs_config}.  For the other configuration
d1141 1
d2878 3
a2880 3
mess if the client software ever crashes.  Running
@@command{funmounter} will generally only make things worse by
confusing @@command{nfsmounter}.
@


1.63
log
@document newaid
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.62 2002/11/28 14:38:40 max Exp $
d2477 1
a2477 1
@@c @@mp @@ ignore
@


1.62
log
@Shorted hyphen runs by one. Other small tweaks.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.61 2002/11/28 09:23:55 dm Exp $
d140 2
a141 1
* ssu::                         Become root without changing SFS credentials
d338 1
a338 1
If you determined that you need gmp @@pxref{Requirements}, you should
d348 1
a348 1
not come with a recent enough version of gcc @@pxref{Requirements}.
d367 1
d844 9
a852 8
As described in @@ref{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, @@var{sfs-user} is @@samp{sfs} and @@var{sfs-group}
is the same as @@var{sfs-user}.  The @@samp{sfsuser} directive lets you
supply either a user and group name, or numeric IDs to change the
default.  Note:  @@strong{If you change @@var{sfs-group}, you must make
sure the the program @@file{/usr/local/lib/sfs/suidconnect} is setgid to
the new @@var{sfs-group}.}
d872 19
a890 8
The setuid root program @@file{/usr/local/lib/sfs/newaid} lets users take
on any of these group IDs.  Thus, make sure these groups are not used
for anything else, or you will create a security hole.  There is no
default for @@samp{ResvGids}.

@@item PubKeySize @@var{bits}
Sets the default number of bits in a public key.  The default value of
@@var{bits} is 1280.
d897 10
a906 6
passwords gets easier.  By increasing the @@var{cost} parameter, you can
maintain the cost of guessing passwords as hardware improves.
@@var{cost} is an exponential parameter.  The default value is 7.  You
probably don't want anything larger than 10.  The maximum value is
32---at which point password hashing will not terminate in any tractable
amount of time and the @@command{sfskey} command will be unusable.
d1490 2
a1491 1
* ssu::                         Become root without changing SFS credentials
d2350 1
a2350 1
@@node dirsearch, ssu, rex, Command reference
d2353 1
d2432 54
d2487 59
a2545 1
@@node ssu, sfscd, dirsearch, Command reference
d2806 1
d3195 2
a3196 2
@@command{netstat} command to see who is connecting to SFS (which accepts
connections on port 4).  Users can run the client (also
d3199 2
a3200 2
@@file{/usr/local/lib/sfs-@@value{VERSION}/suidconnect}.  These attacks
can be traced using a tool like lsof, available from
@


1.61
log
@documentation updates
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.60 2002/11/28 07:37:44 dm Exp $
d1173 1
a1173 1
the SFS admin -- given of course that a Userfile is included with the
d1605 2
a1606 2
2-Schnorr employs special @@command{sfskey} commands -- 
@@command{sfskey 2gen} and @@command{sfskey 2edit}. 
d2157 1
a2157 1
removable media (e.g., @@file{/floppy/complete-key-2}.  It is a susbstantial
d2207 2
a2208 2
arguments; it will then search keys in the standard key directory --
@@file{$HOME/.sfs/authkeys}.
@


1.60
log
@document funmount
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.59 2002/10/29 20:39:07 max Exp $
d139 1
d143 1
d1201 6
d1471 1
d1475 1
d2253 1
a2253 1
@@node rex, ssu, sfskey, Command reference
d2331 83
a2413 1
@@node ssu, sfscd, rex, Command reference
d2520 1
a2520 1
@@node sfssd, funmount, sfscd, Command reference
d2577 65
a2641 1
@@node funmount, sfsrwsd, sfssd, Command reference
d2647 5
d2659 2
a2660 2
The @@command{funmount} command forcibly attempts to unmount the file
system mounted on @@var{path}.  It is roughly equivalent to running
@


1.59
log
@Added sfskey passwd, a "user-friendly" password changing program.
Added documentation, and fixed some bugs in agent/sfskeymgr
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.58 2002/10/28 21:44:02 max Exp $
d32 1
a32 1
Copyright 1999 David Mazi@@`eres
d142 1
d144 1
a144 1
* sfsauthd::                    
d1131 5
a1135 4
The @@file{sfs_users} file, maintained and used by the @@command{sfsauthd}
program, maps public keys to local users and groups. It is roughly analogous to
the Unix @@file{/etc/passwd} file.  Each line of @@file{sfs_users} has the
following format:
d1138 2
a1139 1
[USER|GROUP]:@@var{user}:@@var{uid}:@@var{version}:@@var{gid}:@@var{owner}:@@var{pubkey}:@@var{privs}:@@var{srp}:@@var{privkey}:@@var{srvprivkey}:@@var{audit}
d1258 1
a1258 1
@@dots{}).  @@samp{Extensions} until the next @@samp{Extensions},
d1268 1
a1268 1
3. Remote execution (not yet released)
d1329 1
d1333 7
a1339 1
To run a different server for sfs-0.3 and older clients, you could add
d1343 2
a1344 2
  Release 0.3
    Service 1 /usr/local/lib/sfs-0.3/sfsrwsd
d1466 1
d1468 1
a1468 1
* sfsauthd::                    
a1472 1

d1654 4
a1657 3
the default key is @@file{$HOME/.sfs/identity}. If the key supplied is 
a 2-Schnorr key, then @@command{sfskey add} will attempt to load backup
keys should the primary key fail due to an unavailable signature server.
d2428 1
a2428 1
@@node sfssd, sfsrwsd, sfscd, Command reference
d2485 55
a2539 1
@@node sfsrwsd, sfsauthd, sfssd, Command reference
@


1.58
log
@Bugfixes: sfskey logout, sfskeymgr::check_connect.  Added new functionality
to sfskey 2edit -- namely, the -mp flags.  Added documentation.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.57 2002/10/25 22:08:47 max Exp $
d2022 20
d2043 25
a2067 1
@@item sfskey register [-fgpPKS] [-b @@var{nbits}] [-c @@var{cost}] [-u @@var{user}] [-l @@var{label}] [-w @@var{filename}] [@@var{keyname}]
@


1.57
log
@Added documentation help for -create flag.  Added documentation
to vidb
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.56 2002/10/23 20:35:37 max Exp $
d1831 1
a1831 1
@@item sfskey 2edit -[ES] [-l @@var{label}] [-s @@var{srpfile}] [@@var{keyname1} @@var{keyname2} ...]
d1862 10
@


1.56
log
@Added arbitrary key lengths for 2-Schnorr.  Changed the naming of public
key size constant variables.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.55 2002/10/22 21:51:58 max Exp $
d963 1
a963 1
@@item Userfile [-update] [-passwd] [-admin] [-prefix=@@var{prefix}] [-uid=@@var{uid} | -uidmap=@@var{u1}-@@var{u2}+@@var{u3}] [-gid=@@var{gid} | -gidmap=@@var{g1}-@@var{g2}+@@var{g3}] [-pub=@@var{pubpath}] @@var{path}
d981 3
@


1.55
log
@Added "-w" flag to reg and 2gen so that the whole key can be stored
to floppy.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.54 2002/10/19 13:56:38 max Exp $
d1949 4
a1952 3
Speficies the number of bits in the 2-Schnorr key.  Note as of now,
this option does not do anything -- only 160-bit 2-Schnorr keys can
be generated. 
d2061 3
a2063 1
@@option{-g} flag.
@


1.54
log
@Documentation updates.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.53 2002/10/18 17:54:20 max Exp $
d1904 1
a1904 1
@@item sfskey 2gen [-BEKPS] [-a @@{@@var{hostid} | -@@}] [-b @@var{nbits}] [-c @@var{cost}] [-k @@var{okeyname}] [-l @@var{label}] [-s @@var{srpfile}] [@@var{nkeyname}] 
d1960 8
d2008 2
a2009 1
@@item sfskey register [-fgpPKS] [-b @@var{nbits}] [-c @@var{cost}] [-u @@var{user}] [-l @@var{label}] [@@var{keyname}]
d2071 8
@


1.53
log
@Added the -L feature to sfskey edit -- disable setting the ~/.sfs/identity
link
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.52 2002/10/16 00:28:38 max Exp $
d1094 1
a1094 1
certpath //dir1 /dir2 sfs.host.domain:HOSTID/dir2
d1102 1
a1102 1
certpath sfs.host.domain:HOSTID/dir2
@


1.52
log
@Ready to make a release candidate for SFS 0.7
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.51 2002/10/15 22:21:51 max Exp $
d1785 1
a1785 1
@@item sfskey edit [-P] [-o @@var{keyname}] [-c @@var{cost}] [-l @@var{label}] [@@var{keyname}]
d1793 5
a1797 1
@@var{keyname} is unspecified, the default is @@file{$HOME/.sfs/identity}.
d1802 3
@


1.51
log
@Minor bugfixes to sfsauthd parseconfig.  Made updates to sfs.texi for
sfsauthd_config and sfs_users.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.50 2002/10/15 18:53:31 max Exp $
d975 1
a975 1
keys, update their public keys, and change there server key
d978 1
a978 1
Thus, it maintains local copies of read-only databases in
d985 1
a985 2
details on this.  At most one @@samp{Userfile} can have the @@option{-reg}
option.  @@option{-reg} and @@option{-ro} are mutually exclusive.
d989 1
a989 1
the admin field set.
d1128 1
a1128 1
program, maps public keys to local users and users.  It is roughly analogous to
d1139 1
a1139 1
Ordinarily it the same as a user-name in the local password file.
d1157 1
a1157 1
This field is ignored as of SFS release 0.7.
d1234 1
a1234 1
@@item Server @@{* | @@var{Location}[:@@var{HostID}]@@}
d1236 2
a1237 2
self-certifying pathname @@var{Location}@@samp{:}@@var{HostID}.  If
@@samp{:}@@var{HostID} is omitted, then the following lines apply to any
@


1.50
log
@Bugfixes in sfskey and sfs.texi.  Tried to make the documentation
consistent across the different files.  Added more intelligent -o
option to sfskey edit.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.49 2002/10/15 16:04:22 max Exp $
d191 1
a191 1
@@t{/sfs/}@@var{Location}@@t{:}@@var{HostID}
d197 5
a201 5
collision-resistant cryptographic hash of @@var{Location} and the file
server's public key.  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 @@dfn{self-certifying pathnames}.
d253 1
a253 1
support.  We have run SFS successfully on OpenBSD 2.6, FreeBSD 3.3,
d272 1
a272 1
gmp-2.0.2.  You can obtain this from
d277 2
a278 1
install gmp on your system.
d343 2
a344 3
and C++ compilers you wish to use to compile SFS.  Unless you are using
OpenBSD-2.6, your operating system will not come with a recent enough
version of gcc @@pxref{Requirements}.
d391 2
a392 1
Build the sources by running @@samp{make}.
d440 4
a443 4
@@cindex Undefined symbol @@code{___gmp_default_allocate} referenced from text segment
On some operating systems, some versions of GMP do not install the
library properly.  If you get linker errors about symbols with names
like @@code{___gmp_default_allocate}, try running the command
d471 1
a471 1
% cd /sfs/sfs.fs.net:eu4cvv6wcnzscer98yn4qjpjnn9iv6pi
d478 1
a478 1
Note that the @@file{/sfs/sfs.fs.net:@@dots{}} directory does not need to
d636 1
a636 1
@@file{/sfs/@@var{server}:@@var{HostID}}.
d963 1
a963 1
@@item Userfile [-ro|-reg] [-pub=@@var{pubpath}] [-mapall=@@var{user}] @@var{path}
d973 8
a980 8
@@item -ro
Specifies a read-only user database---typically a file on another SFS
server.  @@command{sfsauthd} will not allow users in a read-only database
to update their public keys.  It also assumes that read-only databases
reside on other machines.  Thus, it maintains local copies of read-only
databases in @@file{/var/sfs/authdb}.  This process ensures that
temporarily unavailable file servers never disrupt @@command{sfsauthd}'s
operation.
d982 1
a982 1
@@item -reg
d988 21
d1020 2
a1021 5
database using the @@option{-ro} option.

@@item -mapall=@@var{user}
Map every entry in the user database to the the local user @@var{user},
regardless of the actual credentials specified by the file.
d1029 1
a1029 1
Userfile -reg -pub=sfs_users.pub sfs_users
d1032 5
d1129 1
a1129 1
program, maps public keys to local users.  It is roughly analogous to
d1134 1
a1134 1
@@var{user}:@@var{public-key}:@@var{credentials}:@@var{SRP-info}:@@var{private-key}
d1146 2
a1147 10
@@item public-key
Public key is simply the user's public key.  A user must posses the
corresponding private key to authenticate himself to servers.

@@item credentials
@@var{credentials} are the credentials associated with a particular SFS
public key.  It is simply a local username to be looked up in the Unix
password and group databases.  Ordinarily, @@var{credentials} should be
the same as @@var{user} unless multiple keys need to be mapped to the
same @@var{credentials}.
d1149 22
a1170 2
@@item SRP-info
@@var{SRP-info} is the server-side information for the SRP protocol,
d1178 2
a1179 2
@@item private-key
@@var{private-key} is actually opaque to @@command{sfsauthd}.  It is
d1184 9
@


1.49
log
@Made some more fixes to sfskey.  Finished updating sfs.texi for the
new sfskey.  Still need work on sfsauthd_config documentation.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.48 2002/10/15 04:46:28 max Exp $
d1741 1
a1741 1
@@item sfskey edit [-P] [-o @@var{outfile}] [-c @@var{cost}] [-l @@var{label}] [@@var{keyname}]
d1758 10
a1767 2
@@item -o @@var{outfile}
Specifies the file to which the edited key should be written.
@


1.48
log
@Added further documentation.  Fixed some bug and behavior inconsistencies
in sfskey.  Also, added a mask field in sfsauth_userinfo for future
changes to the protocol.  This might be useful when it comes to
describing which fields of the userinfo record are set during queries,
and which fields should be updated during updates.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.47 2002/10/15 00:07:35 max Exp $
d1042 1
a1042 1
sfskey update -a authserver:HOSTID sfskey.priv sfskey.priv
d1049 1
a1049 1
@@samp{authserver:HOSTID} with @@samp{-} (the minus sign).  Thus, in the
d1053 1
a1053 1
sfskey update -a - ~/.sfs/identity
d1546 2
a1547 2
@@var{user}@@@@@@var{host1}#@@var{n}
@@var{user}@@@@@@var{host1}#@@var{n},@@var{p}.@@var{host2},@@var{m}
d1557 1
a1557 1
In general, these details can remain hidden, in the symbolic key
d1567 3
a1569 3
form @@file{@@var{name}#}, @@command{sfskey} looks in the default
directory for the most recent key with the given name during key
access, and the next available key with the given name during key
d1576 8
d1597 3
a1599 1
the default key is @@file{$HOME/.sfs/identity}.
d1741 1
a1741 1
@@item sfskey edit [-P] [-o @@var{outfile}] [-c @@var{cost}] [-n @@var{name}] [@@var{keyname}]
d1765 2
a1766 2
@@item -n @@var{name}
Specifies the name of the key that shows up in @@command{sfskey list}.
d1769 1
a1769 1
@@item sfskey 2edit -[ES] [-s @@var{srpfile}] [@@var{keyname1} @@var{keyname2} ...]
d1801 3
d1808 2
a1809 2
@@item sfskey gen [-KP] [-b @@var{nbits}] [-c @@var{cost}] [-n @@var{name}] [@@var{keyname}]
Generates a new public/private key pair and stores it in @@var{keyname}.
d1840 2
a1841 2
@@item -n @@var{name}
Specifies the name of the key that shows up in @@command{sfskey list}.
d1845 1
a1845 1
@@item sfskey 2gen [-BEKPS] [-a @@{@@var{hostid} | -@@}] [-b @@var{nbits}] [-c @@var{cost}] [-k @@var{okeyname}] [-n @@var{ikeyname}] [-s @@var{srpfile}] [@@var{nkeyname}] 
d1847 2
a1848 2
the @@option{-a} flag.  All keypairs will be correspond to the same
public key.  The new keyname will be saved locally to the file given
d1871 1
a1871 1
a complete SFS host ID.
d1881 3
a1883 3
@@itemx -c
@@itemx -n
@@itemx -s
d1899 2
a1900 2
will in turn be used to authenticate the user to the servers that
he intends to update.
d1910 1
a1910 1
prints @@samp{@@var{Location}:@@var{HostID}} to standard output.  If
d1941 1
a1941 1
@@item sfskey register [-fgpPKS] [-b @@var{nbits}] [-c @@var{cost}] [-u @@var{user}] [@@var{key}]
d1973 6
a1978 5
@@file{@@var{keyname}#}, @@command{sfskey register} will always generate
then next available key with the prefix @@var{keyname}.  If
@@command{sfskey register} is being run as root with the @@option{-u} option,
the access to the standard keys directory @@file{$HOME/.sfs/authkeys}
will not be allowed.  Hence, the key will simply be generated in the
d1982 1
a1982 2
Generate a new proctive 2-Schnorr key.  Implies the @@option{-g} flag if 
the @@var{keyname} ends with the special character @@file{#}.
d1986 1
d1991 2
a1992 2
@@option{-b} have no effect if the key already exists.  They all imply 
@@option{-g} if the @@var{keyname} ends with the special character @@file{#}.
d2002 1
a2002 1
user to register.  This can be useful when creating accounts for people.
d2039 1
a2039 1
@@item sfskey update [-E] [-S | -s @@var{srp_params}] [-a @@{@@var{server} | -@@}] [_-k @@var{okeyname}] [@@var{nkeyname}]
d2043 2
a2044 2
To change public keys, typically a user should generate a new public key
and store it in @@file{$HOME/.sfs/identity}.  Then he can run
d2046 1
a2046 1
he needs to change his public key.
d2048 1
a2048 1
To authenticate the user to the servers on which updates are requested,
d2050 1
a2050 1
arguments; it will then search keys in the standard key direction --
d2078 1
d2080 10
a2089 12
@@itemx -a -
Specify the server on which to change the users key.  The server must be
specified as @@samp{@@var{Location}:@@var{HostID}}.  A @@var{server} of
@@samp{-} means to use the local host.  You can specify the @@option{-a}
option multiple times, in which case @@command{sfskey} will attempt to
change @@var{oldkey} to @@var{newkey} on multiple servers in parallel.

If @@var{oldkey} is the name of a remote key---i.e. of the form
@@samp{[@@var{user}]@@@@@@var{host}}---then the default value of @@var{server}
is to use whatever server successfully completes the SRP authentication
protocol while fetching @@var{oldkey}.  Otherwise, if @@var{oldkey} is a
file, the @@option{-a} option is mandatory.
@


1.47
log
@Working on documenting the new sfskey.  In the process, have made some
bugfixes and UI tweaks.  Have also started cleaning up code for sfskey
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.46 2002/07/29 16:10:02 max Exp $
d1528 13
d1759 50
a1808 3
@@item sfskey gen [-KP] [-b @@var{nbits}] [-c @@var{cost}] [-n @@var{name}] [@@var{keyfile}]
Generates a new public/private key pair and stores it in @@var{keyfile}.
It omitted @@var{keyfile} defaults to @@file{$HOME/.sfs/identity}.
d1832 59
d2025 1
a2025 1
@@item sfskey update [-S | -s @@var{srp_params}] [-a @@{@@var{server} | -@@}] @@var{oldkey} [@@var{newkey}]
d2034 5
d2042 3
d2049 2
a2050 1
mount an off-line guessing attack on the user's password.
d2057 6
@


1.46
log
@Fixed typo..
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.45 2002/07/26 15:33:46 kaminsky Exp $
d1527 36
d1567 1
a1567 1
@@item sfskey add [-t [hrs:]min] [@@var{keyfile}]
d1574 3
a1576 3
In the first form of the command, the key is loaded from file
@@var{keyfile}.  The default for @@var{keyfile}, if omitted, is
@@file{$HOME/.sfs/identity}.
d1581 1
a1581 1
@@uref{http:/@@dslash{}srp.stanford.edu@@dslash{}srp/,SRP} protocol.  SRP
d1592 2
a1593 1
The @@command{sfskey update} and @@command{register} commands let users
a1620 1

d1809 1
a1809 1
@@item sfskey register [-KS] [-b @@var{nbits}] [-c @@var{cost}] [-u @@var{user}] [@@var{key}]
d1815 1
a1815 1
@@command{sfskey update}.  The superuser can also use
d1818 2
a1819 2
@@var{key} is the private key to use.  If @@var{key} does not exist and is
a pathname, @@command{sfskey} will create it.  The default @@var{key} is
d1821 10
a1830 2
the default is to generate a new key but not store it anywhere.  If a
user wishes to reuse a public key already registered with another
d1832 1
a1832 1
@@var{key}.
d1835 17
d1853 1
d1856 1
d1858 2
a1859 1
@@option{-b} have no effect if the key already exists.
d1873 2
a1874 2
@@option{-reg} option to enable use of the @@command{sfskey register},
@@ref{sfsauthd_config}.
@


1.45
log
@allow the possibility to select difference service in case each one has
its own self certifying pathname (-s sfs, -s authserv, or -s rex)
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.44 2002/06/26 06:36:31 dm Exp $
d1700 1
a1700 1
Specifies the file two which the edited key should be written.
@


1.44
log
@fix core dump in DNS parser; add -S option to sfssd (request of Marc Merlin)
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.43 2002/06/18 18:47:35 max Exp $
d1745 8
@


1.43
log
@manpager.pl will convert sfs.texi into a series of manpages.
i've updated sfs.texi accordingly.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.42 2002/04/10 16:39:49 kaminsky Exp $
d2012 1
a2012 1
@@c @@mp @@command{sfscd}{SFS client daemon}{5}
d2067 1
a2067 1
@@c @@mp @@command{sfssd}{SFS server daemon}{5}
d2070 1
a2070 1
sfssd [-d] [-f @@var{config-file}]
d2097 17
a2113 1
@@file{/usr/local/etc/sfs/sfssd_config}.
d2124 1
a2124 1
@@c @@mp @@command{sfsrwsd}{SFS read-write server}{5}
d2156 1
a2156 1
@@c @@mp @@command{sfsauthd}{SFS authentication daemon}{5}
@


1.42
log
@better 'sfskey sesskill' syntax (uses prefixes)
better 'sfskey sesslist' output (aligns columns)
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.41 2002/03/22 18:59:32 kaminsky Exp $
d825 3
d890 3
d901 3
d937 3
d947 3
d1090 4
d1101 3
d1149 3
d1160 3
d1290 4
d1301 3
d1315 3
d1326 3
d1394 3
d1415 1
d1417 3
a1419 1

d1432 1
d1434 1
d1436 1
d1438 1
d1442 1
d1444 1
d1490 3
d1498 7
d1527 1
d1529 1
d1873 3
d1881 7
d1908 1
d1910 1
d1951 3
d1959 3
d1970 1
d1972 1
d1974 1
d1976 1
d1980 1
d1982 1
d1996 1
d1998 1
d2003 3
d2011 3
d2017 1
d2019 1
d2023 1
d2025 1
d2058 3
d2066 3
d2072 1
d2074 1
d2085 1
d2087 1
d2099 3
d2107 3
d2113 1
d2115 1
d2122 1
d2124 1
d2131 3
d2139 3
d2145 1
d2147 1
d2158 1
d2160 1
d2173 4
@


1.41
log
@fixed sfsauthd_config section
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.40 2002/02/27 17:48:47 kaminsky Exp $
d1757 5
a1761 2
@@item sfskey sesskill @@var{hostid}
Kill the @@command{rex} session to the server specified by @@var{hostid}.
@


1.40
log
@added "realm" and "certpath" to sfsauthd_config
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.39 2002/02/24 03:48:25 dm Exp $
d1028 1
d1032 8
a1039 1
@@file{~/.sfs/identity} for example, the first step above is unnecessary.
@


1.39
log
@add -t and -u options to Service in sfssd_config; add -u command-line
option to sfsauthd
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.38 2002/02/14 15:19:11 dm Exp $
d999 4
a1002 2
Where to find default parameters for the SRP protocol.  The default is
@@file{sfs_srp_params}.
d1005 61
a1065 2
Specifies a file listing users who should not be able to register public
keys with @@samp{sfskey register}.  The default is @@file{sfs_deny}.
@


1.38
log
@datadir stuff
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.37 2002/01/30 16:59:53 kaminsky Exp $
d89 1
d109 1
d143 1
d150 2
d1124 48
d1297 1
d1917 1
a1917 1
@@node sfsrwsd,  , sfssd, Command reference
d1919 1
a1919 1
@@section @@command{sfsrwsd} command
d1937 32
@


1.37
log
@fixed info for sfsagent and updated sfskey to reflect prefixes
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.36 2002/01/11 20:29:49 fubob Exp $
d373 4
d763 1
a763 1
using the @@option{--with-etcdir} and @@option{--with-datadir} options to
@


1.36
log
@update the truth.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.35 2001/12/17 21:51:58 kaminsky Exp $
d1281 3
a1283 2
Allow forwarding.  This will allow programs other than the file system
to ask the agent to authenticate the user.
d1403 1
a1403 1
@@item sfskey certprog [-s @@var{suffix}] [-f @@var{filter}] [-e @@var{exclude}] @@var{prog} [@@var{arg} @@dots{}]
d1408 1
a1408 1
@@file{/sfs/@@var{name}.@@var{suffix}}, your agent will run the command:
d1418 1
a1418 1
/sfs/@@var{name}.@@var{suffix} -> @@var{dest}
d1421 16
a1436 7
If the @@option{-s} flag is omitted, then neither @@samp{.} nor
@@var{suffix} gets appended to @@var{name}.  In other words, the link is
@@samp{/sfs/@@var{name} -> @@var{dest}}.  @@var{filter} is a perl-style
regular expression.  If it is specified, then @@var{name} must contain it
for the agent to run @@var{prog}.  @@var{exclude} is another regular
expression, which, if specified, prevents the agent from running
@@var{prog} on @@var{name}s that contain it (regardless of @@var{filter}).
@


1.35
log
@updated documentation to include rex
fixed unclear usage message
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.34 2001/11/01 04:42:15 dm Exp $
d217 1
a217 1
No caffeine was used in the production of the SFS software.
@


1.34
log
@image usage
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.33 2001/11/01 03:37:50 dm Exp $
d136 1
d1235 1
d1310 1
a1310 1
@@node sfskey, ssu, sfsagent, Command reference
d1620 6
d1669 67
a1735 1
@@node ssu, sfscd, sfskey, Command reference
@


1.33
log
@add BindAddr option to sfssd_config
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.32 2001/07/28 04:01:35 dm Exp $
d664 1
a664 1
@@vbox to 2in{@@vskip -1.2in@@image{components,6in}@@vss}
@


1.32
log
@2.95.1 -> 2.95.2
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.31 2001/07/28 03:55:11 dm Exp $
d757 2
a758 2
there, in @@file{/usr/local/etc/sfs}.  You can change these locations
using the @@option{--with-etcdir} and @@option{--with-confdir} options to
d762 1
a762 1
@@file{/usr/local/etc/sfs} for all configuration files except
d768 7
a774 1
for most of the programs comprising SFS.
d834 8
d1065 5
@


1.31
log
@test before checking in...
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.30 2001/07/28 03:53:39 dm Exp $
d232 1
a232 1
You must use gcc version 2.95.1 or later to compile SFS.
d398 1
a398 1
from gcc.  If you are not running gcc-2.95.1 or later, you will very
@


1.30
log
@minor fixes
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.29 2001/07/18 03:02:17 dm Exp $
d267 1
a267 1
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dash{}gmp}.  Many
@


1.29
log
@Eliminated the NFSHost option in sfsrwsd_config.  However, now the
LOCAL-DIRECTORY part of an "Export LOCAL-DIRECTORY SFS-NAME" directive can
be an NFS mount point, and sfsrwsd will do the right thing.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.28 2001/07/02 14:59:18 dm Exp $
d260 1
a260 1
gcc-2.95.1 or more recent.  You can obtain this from
d267 1
a267 1
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gmp}.  Many
@


1.28
log
@Add named protocol support for chord.  Also clean up newaid; don't want setuid
root programs depending on obscure casting semantics, since GCC3 might do the
wrong thing.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.27 2001/06/25 06:39:17 dm Exp $
a900 10

@@item NFSHost @@var{NFS-server}
Ordinarily, @@command{sfsrwsd} exports the local file systems of the
machine it is running on.  However, you can also set up one machine to
act as an SFS-proxy for another machine, if you trust the network
between the two machines.  @@samp{NFSHost} tells @@command{sfsrwsd} to
export file systems from host @@var{NFS-server} instead of from the local
machine.  All the @@var{local-directory} entries in @@samp{Export}
directives must exist and be NFS-exported from @@var{NFS-server} to the
machine actually running @@command{sfsrwsd}.
@


1.27
log
@findfs
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.26 2001/06/13 01:16:58 dm Exp $
d1166 8
@


1.26
log
@fix sfskey edit usage
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.25 2000/12/26 03:18:53 dm Exp $
d492 1
@


1.25
log
@Work around bug in texi2html
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.24 2000/12/07 04:04:15 dm Exp $
d1460 1
a1460 1
@@item sfskey edit -P [-o @@var{outfile}] [-c @@var{cost}] [-n @@var{name}] [@@var{keyname}]
@


1.24
log
@random fixups
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.23 2000/05/11 18:40:21 dm Exp $
d19 4
d433 1
a433 1
@@code{ranlib /usr@@dslash{}local@@dslash{}lib@@dslash{}libgmp.a}
d435 1
a435 1
@@code{/usr@@dslash{}local}).
@


1.23
log
@typo
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.22 2000/03/30 22:56:08 dm Exp $
d425 8
d659 1
a659 1
@@image{components,6in}
a683 1

@


1.22
log
@misc hacking
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.21 2000/03/20 02:41:40 dm Exp $
d1065 4
a1068 4
@@samp{:}@@var{HostID} then the following lines apply to any connection
that does not match an explicit @@var{HostID} in another @@samp{Server}.
The argument @@samp{*} applies to all clients who do not have a better
match for either @@var{Location} or @@var{HostID}.
@


1.21
log
@Much improved DNS failover should now work with laptops changing address.
Changed sfskey to pretty much believe the prime in sfs_srp_primes, and skip
the check when that prime matches the one from a remote authserv.
sfskey add is not much more tolerant of CNAMES and such; it now almost
always makes a symbolic link, but uses the hostname that was part of the
SRP protocol.  Also, just for chuckles, print the length of the SRP prime
as part of the password prompt.
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.20 2000/02/16 18:47:23 dm Exp $
d889 12
@


1.20
log
@reverse the sense of the -L flag again
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.19 2000/02/09 22:06:19 dm Exp $
d1330 18
@


1.19
log
@always work around Linux readlink bug; flip the meaning of the -L flag to sfscd
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.18 2000/02/09 21:12:00 dm Exp $
d247 4
a250 6
We have also run SFS with some success on Linux.  However, the Linux
kernel has some bugs that prevent SFS from working properly. You can run
SFS on Linux, but you will need to apply some
@@uref{http:/@@dslash{}www.fs.net@@dslash{}linux@@dslash{}, kernel
patches}.  These patches should still be considered experimental,
however.
d1674 3
a1676 7
On Linux, the @@option{-L} option enables a number of kludges to work
around bugs in the kernel.  Unfortunately, not all kernel bugs can be
worked around in SFS.  Thus, you need to patch the kernel anyway to run
SFS on Linux, and the patch we supply fixes all the problems.  In the
future, however, if Linux includes NFS3 with a correct implementation of
the @@code{nfs_permission} function, the @@option{-L} flag may allow SFS
to work on a stock Linux distribution.
@


1.18
log
@change defaults
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.17 2000/01/03 04:01:56 dm Exp $
d408 8
d1647 1
a1647 1
sfscd [-d] [-l] [-f @@var{config-file}]
d1674 9
@


1.17
log
@fix the figure
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.16 1999/12/31 23:27:42 dm Exp $
d369 1
a369 1
files.  The default is @@file{/etc}.
d465 1
a465 1
Create an @@file{/etc/sfsrwsd_config} configuration file.
d474 1
a474 1
sfskey gen -P /etc/sfs_host_key
d477 5
a481 5
Then you must create an @@file{/etc/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
@@command{Export} directives in the configuration file.  Each export
directive is a line of the form:
d738 4
a741 4
directories---first @@file{/etc}, then, if they don't find the file
there, in @@file{/usr/local/etc}.  You can change these locations using
the @@option{--with-etcdir} and @@option{--sysconfdir} options to the
@@command{configure} command, @@ref{configure}.
d744 1
a744 1
@@file{/usr/local/etc} for all configuration files except
d747 1
a747 1
creating a new file of the same name in @@file{/etc}.
d861 1
a861 1
not start with @@file{/} in @@file{/etc}, or whatever directory you
d899 1
a899 1
not start with @@file{/} in @@file{/etc}, or whatever directory you
d948 1
a948 1
@@file{/etc}):
d1578 1
a1578 1
the server, or look in @@file{/usr/local/etc/sfs_srp_params}.
d1670 2
a1671 2
first to look for @@file{/etc/sfscd_config}, then
@@file{/usr/local/etc/sfscd_config}.
d1701 2
a1702 2
first to look for @@file{/etc/sfssd_config}, then
@@file{/usr/local/etc/sfssd_config}.
d1724 1
a1724 1
@@file{/etc/sfsrwsd_config}.
@


1.16
log
@fix Linux references
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.15 1999/12/31 23:27:01 dm Exp $
d250 1
a250 1
@@uref{http:/@@dslash{}www.fs.net@@dslash{}/linux@@dslash{}, kernel
d265 5
a269 5
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gmp}.  Many operating
systems already ship with gmp.  Note, however, that some Linux
distributions do not include the gmp.h file.  Even if you have
libgmp.so, if you don't have /usr/include/gmp.h, you need to install gmp
on your system.
d272 6
a277 5
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.
d644 4
d669 1
@


1.15
log
@fix Linux references
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.14 1999/12/31 01:21:07 dm Exp $
d2134 1
a2134 1
@@email{sfs-dev@@pdos.lcs.mit.edu}.
@


1.14
log
@some tools to help make distributions
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.13 1999/12/29 20:12:03 dm Exp $
d101 1
d247 6
a252 22
We have also run SFS with some success on Linux, but with
@@uref{http:/@@dslash{}www.pdos.lcs.mit.edu@@dslash{}~kaminsky/nfs3-linux@@dslash{},
kernel patches} to make NFS3 more robust.  These patches are to an old
kernel.  Moreover, because Linux makes incorrect use of the
NFSPROC3_ACCESS RPC, these patches only work when UID's are the same on
clients and servers.  The patches will create a security hole when two
mutually distrustful users use SFS on the same client machine.

Because of some recent Linux kernel changes, it is not even possible to
run SFS on new versions of Linux.  We are working on a modified Linux
kernel that can run SFS.@@footnote{The crux of the problem, for those
curious, is that Linux mounts file systems on name cache entries, rather
than on vnodes or inodes.  When a name cache entry is evicted---for
instance because a local mount point is renamed on a remote NFS server,
Linux forever loses the mount point.  SFS depends deeply on being able
to give different users slightly different views of the @@file{/sfs}
directory.  Even nailing down name cache entries as Linux used to do can
give subtly incorrect behavior and potentially lead to security holes
when two or more mutually distrustful users share the same client
machine.}  We recommend you not even try to run SFS on Linux, as you may
get frustrated and give SFS a bad reputation that persists after we have
a properly fixed up a Linux kernel to work with SFS.
d1721 1
a1721 1
@@node Security, Concept Index, Command reference, Top
d2126 14
d2142 1
a2142 1
@@node    Concept Index,  , Security, Top
@


1.13
log
@fix typo
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.12 1999/12/29 04:47:11 dm Exp $
d283 1
a283 1
libgmp.so, If you don't have /usr/include/gmp.h, you need to install gmp
@


1.12
log
@documentation changes
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.11 1999/12/26 16:15:46 dm Exp $
d274 1
a274 1
@@uref{http:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}gcc}.
d280 1
a280 1
@@uref{http:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gmp}.  Many operating
@


1.11
log
@emil's changes; some reformatting
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.10 1999/12/26 07:47:05 dm Exp $
d192 1
a192 1
Self certifying pathnames let users authenticate servers through a
d396 3
a398 3
Install the sources by running @@samp{make install}.  If you are short on
disk space, you can alternatively install stripped binaries by running
@@samp{make install-strip}.
d2132 9
@


1.10
log
@learning...
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.9 1999/12/26 07:41:28 dm Exp $
d8 11
d26 1
a26 1
This file documents SFS, the self-certifying file sytem.
d87 1
a87 1
This file documents SFS, the self-certifying file sytem.
d96 1
a96 1
* Getting Started::             Play with SFS as quicly as possible
d109 1
a109 1
* Build Problems::              Common problems in compile the source
d138 1
a138 1
* new vulerabilities::          Vulnerabilities created by SFS
d169 1
a169 1
internet can set up an SFS file server without needing to obtain any
d189 1
a189 1
external key management machanisms.  SFS calls the directories on which
d192 1
a192 1
Self certifyinig pathnames let users authenticate servers through a
d223 1
a223 1
You must create a an @@samp{sfs} user and an @@samp{sfs} group on your
d234 1
a234 1
* Build Problems::              Common problems in compile the source
d247 6
a252 6
@@uref{http://www.pdos.lcs.mit.edu/~kaminsky/nfs3-linux/,kernel patches}
to make NFS3 more robust.  These patches are to an old kernel.
Moreover, because Linux makes incorrect use of the NFSPROC3_ACCESS RPC,
these patches only work when UID's are the same on clients and servers.
The patches will create a security hole when two mutually distrustful
users use SFS on the same client machine.
d260 1
a260 1
Linux forever looses the mount point.  SFS depends deeply on being able
d265 3
a267 4
machine.}  We recommend you not even try to run SFS on Linux, as
otherwise you may get frustrated and give SFS a bad reputation that
persists after we have a properly fixed up a Linux kernel to work with
SFS.
d274 3
a276 2
@@uref{http://ftp.gnu.org/pub/gnu/gcc}.  Don't waste your time trying to
compile SFS with an earlier version of gcc.
d279 4
a282 3
gmp-2.0.2.  You can obtain this from @@uref{http://ftp.gnu.org/pub/gmp}.
Many operating systems already ship with gmp.  Note, however, that some
Linux distributions do not include the gmp.h file.  Even if you have
d311 1
a311 1
Create a user, @@var{sfs-user}, and group, @@var{sfs-group} for SFS on
d409 1
a409 1
The most common problem you will encouter is an internal compiler error
d416 1
a416 1
On OSF/1 for the alpha, certain functions using a gcc extention called
d562 1
a562 1
In general, the proceedure for exporting NFS file systems varies greatly
d622 3
a624 3
If, after your agent is already runninig, you wish to fetch a private
key from another server or download another server's public key, you can
run the command:
d717 1
a717 1
servers, Finally, @@command{sfskey} can configure the agent for dynamic
d736 1
a736 1
directly with @@command{sfsrwsd} to authenticat users of the file system.
d822 1
a822 1
However, it needs to modify processes' grouplists so as to know which
d845 1
a845 1
@@var{cost} is an exponential paremeter.  The default value is 7.  You
d964 1
a964 1
Where to find default paremeters for the SRP protocol.  The default is
d1003 1
a1003 1
pasword and group databases.  Ordinarily, @@var{credentials} should be
d1042 1
a1042 1
revocatoin/redirection certificates when clients connect to unknown
d1214 1
a1214 1
As the user touches each SFS file serer for the first time, the agent
d1227 1
a1227 1
Stay in the forground rather than forking and going into the background
d1248 1
a1248 1
unix domain socket as well.
d1259 1
a1259 1
@@command{sfsagent} runs the program with the enironment variable
d1310 12
a1321 11
@@anchor{SRP}
The second form of the command fetches a private key over the network
using the @@uref{http://srp.stanford.edu/srp/,SRP} protocol.  SRP lets
users establish a secure connection to a server without remembering its
public key.  Instead, to prove their identities to each other, the user
remembers a secret password and the server stores a one-way function of
the password (also a secret).  SRP addresses the fact that passwords are
often poorly chosen; it ensures that an attacker impersonating one of
the two parties cannot learn enough information to mount an off-line
password guessing attack---in other words, the attacker must interact
with the server or user on every attempt to guess the password.
d1327 1
a1327 1
never sees any password-equialent data).
d1346 1
a1346 1
HostIDs on the fly in the @@file{/sfs} directory.  This mechanism can be
d1348 1
a1348 1
HostIDs on-demand.  When you reference the file
d1374 1
a1374 1
look for symbolic links to hostids.  The usage is:
d1586 1
a1586 1
information for the serer.  The default is to get SRP parameters from
d1595 1
a1595 1
change @@var{oldkey} to @@var{newkey} on multiple serers in parallel.
d1657 1
a1657 1
Stay in the forground and print messages to standard error rather than
d1666 1
a1666 1
pathname will fil with the error @@code{EDEADLK} (``Resource deadlock
d1704 1
a1704 1
Stay in the forground and print messages to standard error rather than
d1756 1
a1756 1
* new vulerabilities::          Vulnerabilities created by SFS
d1761 1
a1761 1
@@node new vulerabilities, exposed vulnerabilities, Security, Security
d1796 1
a1796 1
respository could replace the @@file{CVSROOT/history} with a symbolic
d1824 1
a1824 1
@@node exposed vulnerabilities, implementation vulnerabilities, new vulerabilities, Security
d2015 1
a2015 1
@@subheading Resrouce exhaustion
@


1.9
log
@add direntry
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.8 1999/12/26 06:49:19 dm Exp $
d11 1
a11 1
* SFS: (sfs):		Self-certifying file system
@


1.8
log
@finishing touches
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.7 1999/12/24 05:54:18 dm Exp $
d9 4
@


1.7
log
@more documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.6 1999/12/16 20:11:13 dm Exp $
d180 1
a180 1
links let file namespace doubles as a key certification namespace.
d230 1
d233 21
a253 12
to make NFS3 more robust.  Note that because of some recent Linux kernel
changes, it is probably no longer possible to run SFS on Linux.
However, we are working on a modified Linux kernel that can run
SFS.@@footnote{The crux of the problem, for those curious, is that Linux
mounts file systems on name cache entries, rather than on vnodes or
inodes.  When a name cache entry is evicted---for instance because a
local mount point is renamed on a remote NFS server, Linux forever
looses the mount point.  SFS depends deeply on being able to give
different users slightly different views of the @@file{/sfs} directory.
Even nailing down name cache entries as Linux used to do can give subtly
incorrect behavior and potentially lead to security holes when two or
more mutually distrustful users share the same client machine.}
d266 1
a266 1
Linux distributios do not include the gmp.h file.  Even if you have
d312 2
a313 2
system.  Moreover, having an unprivileged uses in @@var{sfs-group} causes
a security hole.
d404 1
a404 1
EXCCFLAGS='-D__attribute__\(x\)='} instead of simply @@code{make}.
d497 2
a498 1
@@file{sfsrwsd_config} file.  You should then run the following commands:
d546 1
a546 1
In general the proceedure for exporting NFS file systems varies greatly
d562 4
a565 3
Note: @@strong{You will not be able to access an SFS server from a client
on the same machine} unless you run @@command{sfscd} with the @@option{-l}
flag, @@ref{sfscd}.
d748 1
a748 1
user's public keys across several file servers.
d803 1
a804 1
@@item ResvGids @@var{low-gid} @@var{high-gid}
d822 1
a823 1
@@item PwdCost @@var{cost}
d853 1
a853 1
The default is @@file{sfs_host_key}.  (SFS looks for file names that do
d858 1
a859 1
@@item Export @@var{local-directory} @@var{sfs-name} [R|W]
d891 1
a891 1
The default is @@file{sfs_host_key}.  (SFS looks for file names that do
d917 1
a917 1
keys by typing their UNIX passwords.  See the @@samp{sfskey register} for
d926 7
a932 7
derived a user's password.  The file @@var{path} specified in
@@samp{Userfile} contains these secrets for users opting to use SRP.
@@option{-pub} option tells @@command{sfsauthd} to maintain a separate
copy of the database without secret information in @@var{pubpath}.
@@var{pubpath} might reside on an anonymously readable SFS file
system---other machines can then import the file as a read-only database
using the @@option{-ro} option.
d940 1
a940 1
the followingdefault (again, unqualified names are assumed to be in
d944 1
a944 1
Userfile -reg sfs_users
d986 1
a986 1
public key.  It is simply a local username to be lookup up in the Unix
d1031 1
a1032 1
@@item HashCost @@var{bits}
d1489 1
d2081 34
@


1.6
log
@more security documentation
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.5 1999/12/16 02:43:56 dm Exp $
d82 1
d85 1
a85 1
* Security::                    Security considerations
d105 1
a105 1
* @@file{sfsrwsd_config}::       File server configuration 
d107 1
d114 6
a119 3
* sfsagent::                    
* sfskey::                      
* ssu::                         
d407 1
a407 1
@@node Getting Started, SFS configuration, Installation, Top
d433 1
a433 1
% 
d551 3
d620 1
d626 88
a713 1
@@node SFS configuration, Command reference, Getting Started, Top
d757 1
a757 1
* @@file{sfsrwsd_config}::       File server configuration 
d759 1
d832 1
d866 1
a866 1
@@node @@file{sfsauthd_config}, @@file{sfssd_config}, @@file{sfsrwsd_config}, SFS configuration
d870 1
d944 54
a997 1
@@node @@file{sfssd_config}, @@file{sfs_srp_params}, @@file{sfsauthd_config}, SFS configuration
d1001 1
a1001 1
@@anchor{sfsauthd_config}
d1101 1
d1166 6
a1171 3
* sfsagent::                    
* sfskey::                      
* ssu::                         
d1194 1
a1194 1
sfsagent [-nkF] -S @@var{sock} [-c [@@var{prog} [@@var{arg} @@dots{}]] | @@var{keyname}]
d1198 3
d1282 1
d1553 1
a1553 1
@@item -s 
d1575 1
a1575 1
@@node ssu,  , sfskey, Command reference
d1613 93
d1776 1
a1776 1
@@xref{resvgids}, to see you users can run multiple agents with the
@


1.5
log
@more documenting
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.4 1999/12/08 06:51:28 dm Exp $
d335 1
a335 1
need to recompile SFS, see @@ref{sfs_config}.]
d348 1
a348 1
@@file{/var/sfs}.  [You can change this later, see @@ref{sfs_config}.]
d626 1
a626 1
@@command{configure} command, see @@ref{configure}.
d748 1
d867 6
d1482 2
d1491 2
d1501 7
a1507 6
Finally, users need to be careful about using untrusted file systems as
if they were trusted file systems.  Any file system can name files in
any other file system by symbolic links.  Thus, when randomly
overwriting files in a file system you do not trust, you can be tricked,
by symbolic links, into overwriting files on the local disk or another
SFS file system.
d1529 11
d1545 1
d1547 6
a1552 6
@@noindent
@@strong{NFS server security.}  The SFS read-write server software
requires each SFS server to run an NFS server.  Running an NFS server at
all can constitute a security hole.  In order to understand the full
implications of running an SFS server, you must also understand NFS
security.
d1566 11
a1576 4
client claims to represent has permission to perform the requested
operation).  The expectation is that all clients are trusted, and no
machine that is not an authorized NFS client will ever obtain a valid
NFS file handle.
d1578 5
a1582 1
General NFS server security problems (run fsirand)
d1584 2
a1585 1
mountd -n; pormap forwarding
d1587 8
a1594 1
NFS crashing bugs.  Client and server.
d1596 130
a1725 1
Locking problems.
a1726 1
Logger buffer overrun
d1732 1
a1732 1
NFS/loopback
d1734 81
a1814 1
Many connections to server
d1824 4
@


1.4
log
@little touch-ups I have done as things annoyed me
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.3 1999/12/05 18:14:49 dm Exp $
d83 1
a83 1
* sfskey::                      sfskey user guide
d109 12
d617 1
a617 1
@@node SFS configuration, sfskey, Getting Started, Top
d671 1
a671 1
@@subsection @@file{sfs_config}---system-wide configuration parameters
d694 1
d713 1
d733 1
a733 1
@@subsection @@file{sfsrwsd_config}---File server configuration
d769 1
a769 1
@@subsection @@file{sfsauthd_config}---User-authentication daemon configuration
d810 11
a820 11
@@command{sfsauthd} supports the secure remote password protocol, or
@@uref{http://srp.stanford.edu/srp/,SRP}.  SRP lets users connect
securely to @@command{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 a user's password.  The file
@@var{path} specified in @@samp{Userfile} contains these secrets for users
opting to use SRP.  @@option{-pub} option tells @@command{sfsauthd} to
maintain a separate copy of the database without secret information in
@@var{pubpath}.  @@var{pubpath} might reside on an anonymously readable
SFS file system---other machines can then import the file as a read-only
database using the @@option{-ro} option.
d846 1
a846 1
@@subsection @@file{sfssd_config}---Meta-server configuration
d848 1
d921 1
a921 1
@@subsection @@file{sfs_srp_params}---Default parameters for SRP protocol
d923 1
d940 1
a940 1
@@subsection @@file{sfscd_config}---Meta-client configuration
d1001 74
d1076 1
a1076 1
@@node sfskey, Security, SFS configuration, Top
d1078 1
a1078 1
@@chapter @@command{sfskey} user guide
d1085 1
a1085 1
sfskey [-S @@var{sock}] [-p @@var{pwfd}] command [args]
d1100 2
a1101 2
that need multiple passphrases, you can specify the @@option{-p} option
multiple times.
d1104 33
a1136 1
@@item sfskey add [-t [hrs:]min] [keyfile | [user]@@@@authservhostname]
d1139 2
d1143 46
d1190 23
a1212 1
@@item sfskey certprog [-s suffix] [-f filter] [-e exclude] prog [arg ...]
d1214 8
a1221 1
@@item sfskey delete keyname
d1224 11
d1236 1
a1236 1
@@item sfskey edit -P [-o outfile] [-c cost] [-n name] [keyname]
d1238 41
a1278 1
@@item sfskey gen [-KP] [-b nbits] [-c cost] [-n name] [keyfile]
d1281 1
d1283 6
a1288 1
@@item sfskey hostid hostname
d1291 1
d1293 2
a1294 1
@@item sfskey list
d1296 10
a1305 1
@@item sfskey norevokeset hostid ... 
d1309 37
a1345 1
@@item sfskey register [-KS] [-b nbits] [-c pwdcost] [keyfile]
d1348 8
d1357 1
a1357 1
@@item sfskey revokegen [-r newkeyfile [-n newhost]] [-o oldhost] oldkeyfile
d1363 8
a1370 1
@@item sfskey revokeprog [-b [-f filter] [-e exclude]] prog [arg ...]
d1372 4
a1375 1
@@item sfskey srpgen [-b nbits] file
d1377 29
a1405 1
@@item sfskey update [-S | -s srp_parm_file] [-a @@{server | -@@}] oldkey [newkey]
d1408 14
d1423 24
a1446 1
@@node Security, Concept Index, sfskey, Top
d1450 66
a1515 1
Global file system facilitates exploits
d1517 29
a1545 1
Dot in path.  Symlinks into /dev.
d1551 3
a1553 1
NFS crashing bugs
d1557 9
@


1.3
log
@check in what was sitting in my directory
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.2 1999/12/01 02:09:15 dm Exp $
d83 1
d461 1
a461 1
The @@var{sfs-name} of the first @@command{Export} directive must have be
d465 1
a465 1
Suppose, for instance, that you wished to export two directories,
d467 1
a467 1
respectively.  You would create a directory to be the root of the
d470 1
a470 1
@@file{sfsrwsd_config} file.  You would run the following commands:
d491 1
a491 1
instance, in OpenBSD you would add the following lines to the file
d509 2
a510 2
On Solaris, you would add the following lines to the file
@@file{/etc/dfs/dfstab} and run @@samp{exportfs -a}:
d569 4
a572 3
your private key from @@var{server} and decrypts using your passphrase.
Finally, it fetches the servers public key, and creates a symbolic link 
from @@file{/sfs/@@var{server}} to @@file{/sfs/@@var{server}:@@var{HostID}}.
d594 1
a594 1
When you are done using sfs, you should run the command
d605 1
a605 1
@@node SFS configuration, Security, Getting Started, Top
d676 1
a676 1
is the same as @@var{sfs-user}.  the @@samp{sfsuser} directive lets you
d680 1
a680 1
the new group.}
d702 8
a709 8
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 @@var{cost} parameter, you can maintain
the cost of guessing passwords as hardware improves.  @@var{cost} is an
exponential paremeter.  The default value is 7.  You probably don't want
anything larger than 10.  The maximum value is 32---at which point
password hashing will not terminate in any tractable amount of time and
the @@command{sfskey} command will be unusable.
d729 4
a732 1
The default is @@file{/etc/sfs_host_key}.
d734 1
a734 1
@@item Export @@var{local-directory} @@var{sfs-name}
d737 14
a750 2
pathname.  @@xref{Quick server setup}, for an example of the
@@samp{Export} directive.
a752 1

d765 51
a815 1
The default is @@file{/etc/sfs_host_key}.
a816 2
@@item Userfile [-reg|-ro] [-pub=@@var{pubpath}] [-mapall=@@var{user}] [-prefix=@@var{pref}] @@var{path}
The default value for @@samp{Userfile} is:
d824 4
d835 69
d909 13
d927 132
d1060 1
a1060 1
@@node Security, Concept Index, SFS configuration, Top
@


1.2
log
@Don't daemonize when runinplace is set; a bunch of small builddir cleanups;
clean up sfskey gen stuff in preparation for simple system administration
@
text
@d2 1
a2 1
@@c $Id: sfs.texi,v 1.1 1999/11/30 07:10:48 dm Exp $
d66 2
d81 2
d90 18
a107 3
* Requirements::                System requirements for building SFS
* Building::                    How to build and install SFS
* Build Problems::              Common problems in building SFS
d118 1
a118 1
@@itemize
d129 3
a131 3
realm or 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.
d136 3
a138 2
internet can set up an SFS file server with no need to obtain any kind
of certificates.  New servers are instantly accessible from all clients.
d141 1
d180 1
a180 1
@@node    Installation, Security, Overview, Top
d188 1
a188 1
@@itemize
d199 3
a201 3
* Requirements::                
* Building::                    
* Build Problems::              
d210 16
a225 3
OSF/1 4.0, and Solaris 5.7.  We have also run SFS successfully on Linux,
but with @@uref{http://www.pdos.lcs.mit.edu/~kaminsky/nfs3-linux/,kernel
patches} to make NFS3 more robust.
d308 2
d322 1
a322 1
need to recompile SFS.]
d335 1
a335 1
@@file{/var/sfs}.
d369 1
a369 1
compiler.  You cannot like object files together if they have been
d389 390
a778 1
@@node Security, Concept Index, Installation, Top
a799 1
@@contents
@


1.1
log
@sfscd and sfssd now become daemons without the -d flag; start of documentation
@
text
@d2 1
a2 1
@@c $Id$
d7 1
a7 1
@@setchapternewpage odd
d77 1
a77 1
* Overview::                    Overview of SFS
d155 3
@

