OPTIONS(SVAS)

Shore Programmer's Manual - 2 August 96

NAME

options \- configuration options used by the Shore Value-Added Server

SYNOPSIS

setenv SHORE_RC configuration-file

svas_option_name:  value

DESCRIPTION

Each of the following options must appear on the command line or in a configuration file. On the command line, each option is prepended with a dash ('-'); in a configuration file, it is prepended by a type, a class, and a program name (in the style of X configuration options).

For applications, the type is "shore", and the class and program name are determined by the application.

For the server, the type is "shore", the class is "server", and program name is the name of the program's executable file ("shore" if it is run as made in the source tree).

Wild cards "?" and "*" may be used as with X configuration options.

EXAMPLE CONFIGURATION FILE ENTRIES

Examples are:

shore.server.shore.sm_logdir: ./log
?.server.shore.sm_logdir: ./log
shore.server.?.sm_logdir: ./log
*.sm_logdir: ./log

EXAMPLE COMMAND LINE ARGUMENTS

The following is a handy script for running a server; this script demonstrates how to set command-line options.

#!/bin/csh -f

#	set INST to your installed location
set INST = /p/shore/installed/nodebug
setenv SHORE_RC $ILIB/options
$INST/bin/shore -sm_diskrw $INST/binb/diskrw \
	-svas_shellrc $INST/lib/shore.rc \
	-svas_tcllib $INST/lib/vas.tcllib -v

SERVER OPTIONS

The following options are used by the Shore Value-Added Server process and its subordinate layers of software. Options that are you must set are marked "Required" below, because they have no defaults.

sm_bufpoolsize: Required. The size of the Storage Manager's buffer pool, in kilobytes. It must be an integer greater than 64. No default value.
sm_locktablesize: Number of entries in the Storage Manager's lock table. Default is 64000.
sm_backgroundflush: Optional. Enables flushing of pages to the disk during otherwise idle periods. Default is "yes".
sm_logdir: Required. The path name of a Unix directory or a raw device in which the recovery log will be written. No default value.
sm_reformat_log: Optional. A Boolean value which, if "yes" or "true", causes the logs to be destroyed and re-created. USE WITH CAUTION. If logs are destroyed and re-created, volumes must also be re-created. Default is "no".
sm_logsize: The maximum size that a log partition(file) may reach. The log has 8 partitions, so this is roughly one eighth of the total log size. The minimum size is 1 megabyte, which is too small for any real work. When the log is on a raw device, this value may be 0, which causes the log size to be calculated. (Setting this to a non-zero value for raw devices is allowed for debugging only.) Default is 10 megabytes.
sm_diskrw: The path name of the program that the Shore Storage Manager will fork to perform disk I/O. The path name should be the place you installed the executable program that was made in the source tree as src/sthread/diskrw. The default value is "diskrw".
sm_logging: A Boolean-valued option that determines whether the Shore Storage Manager will perform logging and recovery during this program execution. If turned off, you cannot abort transactions or roll back to savepoints. The default is true.
sm_errlog: See the description for the option "svas_nfsd_log", below. Default is - (stderr).
sm_errlog_level: See the description for the option "svas_nfsd_log_level", below. Default is error.
svas_serve: This option tells the server what devices to ``serve''. The value must be of the form pathname. The pathname is the Unix path name of the device on which a Shore file system has been made. In other words, the device must have been formatted and a file system must have been made on the device before it can be served. You will use this option when you run a server without a Tcl shell, and you want the server to serve more than one volume. If you have only one volume (the server's root volume), you do not need this option, because the root volume is served by the svas_root option (below). If you want to run your server in the background, without a Tcl shell, and you are running the server for the first time (with no log, and no formatted volumes), you must first start a server with a Tcl shell, use the format, mkfs, serve, and possibly pmount commands in order to format your devices, create Shore file systems, and link them together as desired. Once the file systems are constructed, you can shut down the server and start it again without a Tcl shell, using one or more svas_server configuration options to determine what devices are served.
svas_root: This option determines where the server will find the root of the Shore name space. The value must be of the form pathname volume-id. The pathname is the Unix path name of the device on which the root volume is to be found. The volume-id is the logical volume identifier ("high.low") of the volume whose root directory will correspond to "/". The device must already have been formatted, and the volume must already have been created and formatted as a Shore file system. This option has no default value. If no value is given, the server will come up, to allow devices to be formatted and file systems to be created.
svas_tcllib: The file name of a Tcl library file that will be read when the shell is started (only if the shell was configured into the executable and the shell is started). Not an error if the file does not exist. The binary distribution contains a library file in the lib directory. Default is "vas.tcllib".
svas_shellrc: The file name of a Tcl shell command file that will be read immediately after the shell is started (only if the shell was configured into the executable and the shell is started). Default is "shore.rc".

The next four options determine the ports on which the server serves requests for its various services. Each of these port numbers should be an integer between 1024 and 65535.

svas_nfsd_port: This is the port on which the server receives NFS requests over UDP. Default is 2999.
svas_mountd_port: This is the port on which the server receives MOUNT requests over UDP. Default is 2997.
svas_client_port: This is the port on which the server listens for client requests over TCP. Default is 2999.
svas_remote_port: This is the port on which the server listens for requests from other Shore Value-Added Servers and from the sshutdown program. Default is 2998.

svas_reuse_addrs: When set to "true" or "yes", the addresses constructed from the above ports can be used by more than one process. This alleviates the problem of restarting a server that was not cleanly shut down, and getting the "Address already in use" error from the operating system while it is waiting for the TCP 2*maximum-segment-lifetimes to expire. BEWARE: There is no way to distinguish the crashed-server case from the case in which another server is really up and running. Be sure you are not running a second server with the same configuration as the first!!! The results are undefined. You will probably clobber your log and be unable to recover. Default is "no".

The next five options determine the destinations of messages that are logged by the various services. There are three possible destinations: a file in the Unix file system, the syslog daemon, or the standard error file (usually the terminal). If the value of the option is "-", the standard error file is used. If it is "syslogd", the messages are sent to the syslog daemon. If it is any other string, it is interpreted as a Unix path name.

svas_nfsd_log: The destination of log messages generated by the NFS service. Default is "-".
svas_mountd_log: The destination of log messages generated by the MOUNT service. Default is "-".
svas_client_log: The destination of log messages generated by the Shore client request service. Default is "-".
svas_shell_log: The destination of log messages generated by the Tcl shell on the server. Default is "-".
svas_log: The destination of log messages generated by the Shore, but which do not pertain to one of the three services above. Default is "-".

For each of the above logs, you can control the priority of messages that is logged. Possible are: trace info error internal fatal. They correspond to the levels for logging to the syslog daemon.

svas_nfsd_log_level: Default is error.
svas_mountd_log_level: Default is error.
svas_client_log_level: Default is error.
svas_shell_log_level: Default is error.
svas_log_level: Default is error.

The rest of the server options are Boolean-valued options. Values can be given as "yes", "no", "true", or "false".

svas_nfsd_pmap: If "true" or "yes", the server will register this service with the portmapper. Default is "no".
svas_mountd_pmap: If "true" or "yes", the server will register this service with the portmapper. Default is "no".
svas_remote_pmap: If "true" or "yes", the server will register this service with the portmapper. Default is "no".
svas_client_pmap: If "true" or "yes", the server will register this service with the portmapper. Default is "no".
svas_noshm: If "true" or "yes", the server prohibits the use of shared memory when communicating with clients (overriding client options regarding the use of shared memory). This is for debugging purposes only. Default is "no".
svas_rpc_unregister: If "true" or "yes", and the server is unable to register with the portmapper, it will try to un-register and re-register. For restarting after a crash; avoids running "rpcinfo -d". Default is "no". Use carefully!
svas_print_user_errors: If "true" or "yes", the server will print messages about user errors to the standard output file. Default is "no".
svas_print_user_stats: If "true" or "yes", the server will print statistics to the standard output file every time a client's transaction changes state. Default is "no".
svas_clear_user_stats: If "true" or "yes", the server will clear its statistics every time a client's transaction changes state.
svas_tclshell: If "true" or "yes", the server will start a Tcl shell (if the shell was configured into the executable). Default is "yes".
svas_sysp_cache_size: An integer-valued option, whose value should be a small integer. It determines the size (number of entries in) of the meta-data cache created for each client. The meta-data cache caches system properties of pools and of objects containing indexes, in order to expedite permissions checking during operations on anonymous objects and indexes. This will be removed in later versions of Shore. It is present only for developers' purposes. The default value is 1.
svas_mount_table_size: An integer-valued option, whose value should be a small integer. It determines the size (number of entries in) of the transient mount table. Default is 20.

SHUTDOWN OPTIONS

The shutdown program is a client program, which uses the following options, whose values must match those of the server to be shut down by this program:

svas_remote_pmap
svas_remote_port

and it uses the following client option:

svas_host

CLIENT LIBRARY OPTIONS

The following options are used by the Shore Value-Added Server client library. The client library is included in the Shore language-independent library, so these are avaliable to all application programs that use SDL.

svas_host: The name of the host on which the server runs. The default value is "localhost", which is really the only way Shore is intended to be run. This option is available only for debugging purposes.
svas_log: The name of the Unix file to which the client library will log information as it runs. The value "-" means that information will be logged to the standard error file (usually the terminal). If given the value "syslogd", the client library will log to the syslog daemon, as the facility LOG_USER. The default value is "-" (log to standard error).
svas_shm_small_obj: The number of kilobytes of shared memory to allocate for transferring small objects between the server and the client. The default is 16 (two pages).
svas_shm_large_obj: The number of kilobytes of shared memory to allocate for transferring large objects between the server and the client. The default is 256.
svas_use_pmap: If "yes" or "true", the client library consults the portmapper to locate the server. If "no" or "false", the client library does not contact the portmapper, and uses the value of the option "svas_port" to locate the server. The default is "no".
svas_port: The port at which the server is listening. The default is 2999.
svas_print_user_errors: A Boolean-valued option that determines whether the client library will print messages about user errors to the standard output file. The default is "no".

OBJECT CACHE OPTIONS

See options(oc) for information about options available for client programs that use SDL.

VERSION

This manual page applies to Version 1.0 of theShore software.

SPONSORSHIP

The Shore project is sponsored by the Advanced Research Project Agency, ARPA order number 018 (formerly 8230), monitored by the U.S. Army Research Laboratory under contract DAAB07-92-C-Q508.