sfs_environ7

Overview

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

ACLNT_TRACE

Used mostly for debugging, 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.

ACLNT_TIME

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

ASRV_TRACE

ASRV_TIME

These perform an analogous function to ACLNT_TRACE and ACLNT_TIME, but print out RPCs received (as a server), rather than ones made.

BINDADDR

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

FDLIM_HARD

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 FDLIM_SOFT and 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 rexd, the remote execution daemon. 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.

SFS_AGENTSOCK

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

As a special case, if 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 sfsagent with the -k flag. In this case, and program specified on the command line, or the default /usr/local/share/sfs/agentrc script, will be run with SFS_AGENTSOCK set to a file descriptor. Thus, if the script loads keys into the agent by running sfskey, these keys will be loaded into the new agent (before it takes over), rather than into the old agent.

SFS_CONFIG

The location in which to find the sfs_config file. By default, SFS uses configuration files in /usr/local/share/sfs/sfs_config and /etc/sfs/sfs_config. sfssd sets this environment variable when given the -S option, so that subsidiary daemons read the same configuration file.

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 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 /etc/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 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 sfsrwsd and sfsauthd in their confiruation files. Or, you can just set the environment variable SFS_HOSTNAME before running sfssd. Note that if you do not have a DNS name, you can also set SFS_HOSTNAME to the numeric IPv4 address of your host, and then use the IP address as the Location in self-certifying pathnames.

SFS_PORT

This variable, if set, specifies official port number of an SFS server--i.e. the %port that clients must append to the hostname in the Location of the self-certifying pathname. By default (or if 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 SFS_PORT to 4 is not the same thing as setting it to 0, even without SRV records. If you set SFS_PORT to 4, then clients who do not specify %4 in the self-certifying pathname will need to be redirected to a pathname containing %4 via a symbolic link, and pwd run on a client will show the %4 as part of the self-certifying pathname.

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

SFS_ROOT

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

SFS_RUNINPLACE

SFS consists of a large number of interacting daemons. Ordinarily, these are launched by sfscd and 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 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. sfscd and sfssd both remain in the forground and send their output to standard error, rather than to the system log. Moreover, sfsagent does take steps to protect itself from the ptrace system call, so that you can attach to it with the debugger when running in place.

TMPDIR

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

USER

In various places SFS needs a default username--for example, when running sfskey login. SFS looks first at the USER environment variable, then uses the getlogin system call, and if that fails, looks up the current user ID in the system password file.