--- /dev/null
+ftpd (AFS version) AFS Commands ftpd (AFS version)
+
+
+NAME
+
+ ftpd (AFS version) -- initialize Internet File Transfer
+
+ Protocol server.
+
+
+ /usr/etc/ftpd [-d] [-l] [-ttimeout]
+
+DESCRIPTION
+
+ Functions like the standard UNIX ftpd, except that it also
+ authenticates the issuer of the ftp command (who is
+ presumably working on a remote machine) with the
+ Authentication Server in the local cell (the home cell of
+ the machine where ftpd is running). The authentication is
+ based on the user name and password provided at the ftp
+ prompts on the remote machine. The Cache Manager on the
+ machine running ftpd stores the newly created token,
+ identifying it by PAG rather than by the user's UNIX UID.
+
+ The issuer of ftp may be working in a foreign cell, as long
+ as the user name and password provided are valid in the cell
+ where ftpd is running.
+
+ If the user name under which ftp is issued does not exist in
+ the Authentication Database for the cell where ftpd is
+ running, or the issuer provides the wrong password, then
+ ftpd logs the user into the UNIX file system of the machine
+ where ftpd is running. The success of this local login
+ depends on the user name appearing in the local password
+ file and on the user providing the correct local password.
+ In the case of a local login, AFS server processes consider
+ the issuer of ftp to be anonymous.
+
+ In the configuration recommended by Transarc Corporation,
+ the AFS version of ftpd is substituted for the standard
+ version (only one of the versions can run at a time). The
+ administrator then has two choices:
+
+ - name the binary for the AFS version something like
+ ftpd.afs, leaving the standard version as ftpd.
+ Change inetd.conf to refer to ftpd.afs; the
+ standard version is not referenced.
+
+ - name the binary for the AFS version ftpd and
+ rename the binary for the standard version to
+ something like ftpd.old. No change to inetd.conf
+ is necessary, but it is not as obvious that the
+ standard version of ftpd is no longer in use.
+
+ARGUMENTS
+
+ See the UNIX manual page for ftpd.
+
+
+
+PRIVILEGE REQUIRED
+
+ See the UNIX manual page for ftpd.
+
+MORE INFORMATION
+
+ UNIX manual page for ftp
+
+ UNIX manual page for ftpd
--- /dev/null
+inetd (AFS version) AFS Commands inetd (AFS version)
+
+
+NAME
+
+ inetd (AFS version) -- initialize Internet service daemon.
+
+
+ /etc/inetd [-d] [<configfile>]
+
+DESCRIPTION
+
+ Functions like the standard UNIX inetd in invoking an
+ Internet service daemon (itself called "inetd") that handles
+ remotely-issued commands. The AFS inetd enables users of
+ the remote services it supports to access those services as
+ authenticated AFS users, provided that the supported
+ services are also AFS versions capable of passing AFS tokens
+ (authentication information). Examples of supported
+ services are rcp and rsh.
+
+ AFS inetd can service the standard UNIX versions of the
+ remote services, but it is instead recommended that the
+ standard UNIX version of inetd be run in parallel with the
+ AFS version. Name the AFS version something like inetd.afs
+ and use it to service requests from AFS-modified programs;
+ use standard inetd to service requests from standard UNIX
+ programs. This separation requires using two different
+ inetd.conf files, as described in the
+ REQUIREMENTS/RESTRICTIONS section.
+
+REQUIREMENTS/RESTRICTIONS
+
+ Several configuration changes are necessary for token
+ passing to work correctly with the AFS version of inetd.
+ There may be other UNIX-based requirements/restrictions not
+ mentioned here; consult the UNIX manual page. (One
+ important restriction is that there can be no blank lines in
+ the configuration file other than at the end.)
+
+ The requirements/restrictions include the following. They
+ assume that inetd.afs is running in parallel with standard
+ inetd.
+
+ - For token passing to work, the request must come
+ from the AFS version of the remote service (such
+ as AFS rcp or AFS rsh). If the remote service is
+ the standard UNIX version, it will not pass
+ tokens. The issuer of the remote command is
+ authenticated only in the local UNIX file system,
+ not with AFS, so the AFS server processes in the
+ local cell consider the issuer to be anonymous.
+
+ - The machine's reboot configuration file (/etc/rc
+ or equivalent) should be altered so that it starts
+ both standard inetd and inetd.afs.
+
+ - An AFS-specific inetd.conf file, perhaps called
+ inetd.conf.afs, should exist alongside the
+ standard one. When initializing inetd.afs,
+ specify this configuration file rather than the
+ standard one.
+
+ Each line in the inetd.conf.afs file must include
+
+
+
+ an additional field, fifth from the left, to
+ specify the identity under which the program is to
+ run. The normal choice is "root." The following
+ sample shows the only lines that should appear in
+ this file:
+
+ ta-rauth stream tcp nowait root internal
+ shell stream tcp nowait root /usr/etc/r
+ login stream tcp nowait root /usr/etc/r
+
+ Substitute appropriate values for the binary
+ locations and names on the shell and login lines.
+ Include the login line only if the AFS version of
+ login is also in use in the cell; otherwise, refer
+ to login in the standard inetd.conf instead. In
+ addition, if the inetd.cond.afs file is used on a
+ machine with a Sun system type, change rshd to
+ in.rshd and change rlogind.afs to in.rlogind.afs
+ on the shell and login lines, respectively.
+
+ - The standard inetd.conf (referred to by the
+ standard inetd) should be altered: comment out the
+ shell line and, if the AFS version of login is in
+ use in the cell, the login line. References to
+ these programs appear in inetd.conf.afs instead.
+ Retain the login line if AFS login is not being
+ used. Alter the ftp line to refer to the AFS
+ version of ftpd, if it was substituted for the
+ standard version. Do not insert the extra fifth
+ column into standard inetd.conf if it does not
+ already appear there. See the EXAMPLE section
+ below for an illustration.
+
+ - The following two lines must appear in the
+ /etc/services file on the machine running inetd
+ (as well as on the machine running modified rcp or
+ rsh). On NeXT machines, this information must
+ appear in the NetInfo database rather than in
+ /etc/services.
+
+ auth 113/tcp authentication
+ ta-rauth 601/tcp rauth
+
+ARGUMENTS
+
+ See the UNIX manual page for inetd.
+
+EXAMPLE
+
+ The following are sample inetd.conf.afs and inetd.conf
+ files, appropriate for use when inetd.afs is running in
+ parallel with standard inetd and AFS login is being used in
+ the cell. Changes to standard inetd.conf include
+ referencing the AFS version of the ftpd binary and
+ commenting out shell and login. The example inetd.conf does
+ not include the extra fifth column. Do not use these
+ examples without modifying them appropriately for the local
+ machine type or cell.
+
+
+
+ # AFS version of Internet server configuration datab
+ #(EXAMPLE ONLY)
+ #
+ ta-rauth stream tcp nowait root internal
+ shell stream tcp nowait root /usr/etc/rshd
+ login stream tcp nowait root /usr/etc/rlogind.afs
+
+
+
+ # Standard version of Internet server configuration
+ #(EXAMPLE ONLY)
+ #
+ ftp stream tcp nowait /etc/ftpd.afs ftpd
+ telnet stream tcp nowait /etc/telnetd teln
+ #shell stream tcp nowait /etc/rshd rshd
+ #login stream tcp nowait /etc/rlogind rlog
+ finger stream tcp nowait /usr/etc/fingd fing
+ uucp stream tcp nowait /etc/uucpd uucp
+ exec stream tcp nowait /etc/rexecd rexe
+ comsat dgram udp wait /etc/comsat coms
+ talk dgram udp wait /etc/talkd talk
+ ntalk dgram udp wait /usr/etc/ntalkd talk
+ time dgram udp wait /etc/miscd time
+
+PRIVILEGE REQUIRED
+
+ See the UNIX manual page for inetd.
+
+MORE INFORMATION
+
+ rcp (AFS version)
+
+ rsh (AFS version)
+
+ UNIX manual page for inetd
--- /dev/null
+login (AFS version) AFS Commands login (AFS version)
+
+
+NAME
+
+ login (AFS version) -- login to AFS and UNIX file systems.
+
+
+ login [<user name>]
+
+ Authenticates the issuer with the AFS Authentication Server
+ in the local cell and logs him or her into the local
+ machine's UNIX file system. More precisely, AFS login:
+
+ - creates a new "process authentication group" (PAG)
+ associated with the issuer and the command shell
+ where the command is issued. A PAG is a number
+ guaranteed to identify the issuer uniquely to the
+ local Cache Manager. The Cache Manager uses the
+ PAG, instead of the issuer's UNIX UID, to identify
+ him or her in the credential structure that it
+ creates to track each user.
+
+ - authenticates the user with the AFS Authentication
+ Server and obtains a "token"; the other AFS server
+ processes in the cell accept the token as partial
+ proof that the user is a legitimate AFS user. The
+ Cache Manager stores the token in the credential
+ structure along with the PAG, and presents it to
+ AFS server processes as necessary.
+
+ - logs the user into the local UNIX file system
+
+ The lifetime of the token resulting from this command is the
+ smallest of the following:
+
+ - the "maximum ticket lifetime" recorded in the
+ "afs" entry in the Authentication Database. The
+ default is 100 hours. Administrators can inspect
+ this value using kas examine, and change it using
+ kas setfields.
+
+ - the "maximum ticket lifetime" recorded in the
+ issuer's Authentication Database entry. The
+ default is 25 hours for user entries created by
+ the AFS 3.1 or later version of the Authentication
+ Server, and 100 hours for user entries created by
+ the AFS 3.0 version of the Authentication Server.
+ Administrators and the user himself/herself can
+ inspect this value using kas examine, and
+ administrators can change it using kas setfields.
+
+ - the "maximum ticket lifetime" recorded in the
+ "krbtgt.CELLNAME" entry in the Authentication
+ Database; this entry corresponds to the ticket-
+ granting ticket used internally in generating the
+ token. The default is 720 hours (30 days).
+
+ If none of these defaults have been changed, then the
+ standard token lifetime is 25 hours for users whose
+ Authentication Database entries were created by the AFS 3.1
+ or later version of the Authentication Server, and 100 hours
+ for users whose Authentication Database entries were created
+ by the AFS 3.0 version of the Authentication Server. The
+
+
+
+ user can issue klog to request a token with a different
+ lifetime.
+
+ Using a PAG instead of the UNIX UID to distinguish users has
+ two advantages.
+
+ - It means that processes spawned by the user
+ inherit the PAG and so share the token; thus they
+ gain access to AFS as the authenticated user.
+ This is important in many environments where, for
+ example, printer and other daemons run under
+ identities (such as "root") that the AFS server
+ processes recognize only as anonymous. Unless
+ PAGs are used, such daemons cannot access
+ information in directories protected against
+ system:anyuser.
+
+ - It closes a potential security loophole: UNIX
+ allows anyone already logged in as "root" on a
+ machine to assume any other identity by issuing
+ su. If the credential structure were identified
+ by a UNIX UID rather than a PAG, then assuming the
+ same UID would mean being able to use the token,
+ too. Use of a PAG as an identifier eliminates
+ that possibility.
+
+ The process of authenticating with the AFS Authentication
+ Server is as follows:
+
+ 1. The login program checks the user's entry in the
+ local /etc/passwd file.
+
+ If no entry exists, or if an asterisk ( * )
+ appears in the password field, the login attempt
+ fails.
+
+ If the entry exists, the attempt proceeds to step
+ LOGIN.PAG.
+
+ 2. The login program invokes the command that
+ creates a PAG.
+
+ 3. The login program converts the password provided
+ by the user into an encryption key and encrypts a
+ packet of data with the key. It sends the packet
+ to an AFS Authentication Server. The
+ Authentication Server decrypts the packet and,
+ depending on the success of the decryption,
+ judges the password to be correct or incorrect.
+ (Consult the AFS System Administrator's Guide for
+ more information on the "mutual authentication"
+ procedure used to verify the password in this
+ step.)
+
+ If the Authentication Server judges the password
+ incorrect, the user does not receive an AFS
+ token. The attempt proceeds to step LOGIN.LOCAL.
+ If the Authentication Server judges the password
+ correct, it issues a token to the user as proof
+ of AFS authentication. The login program also
+ logs the user into the local UNIX file system.
+
+
+
+ Step LOGIN.LOCAL is skipped.
+
+ 4. If no AFS token was granted in step 3, the login
+ programattempts to log the user into the local
+ UNIX file system, by comparing the password
+ provided to the local password file (/etc/passwd,
+ for instance).
+
+ If the provided password is incorrect, or the
+ password field in the local password file
+ contains anything other than a 13-character
+ UNIX-encrypted password string, then the login
+ attempt fails.
+
+ If the password is correct, the user is logged
+ into the local UNIX file system only. (The
+ success of this attempt and the failure of the
+ AFS authentication implies that the AFS and local
+ passwords are different and that the issuer
+ provided the latter.)
+
+WARNINGS
+
+ Each PAG uses two of the memory slots that the kernel uses
+ to record the UNIX groups associated with a user. If none
+ of these slots are available, the PAG creation fails. The
+ use of two group slots per PAG does not present a problem
+ with most operating systems, which make at least 16 slots
+ available.
+
+ The AFS version of login is based on the Berkeley 4.3
+ Distribution and does not include the modified features
+ included in some proprietary versions of login.
+
+ The AFS version of login works only on machines that have
+ run afsd.
+
+ARGUMENTS
+
+ See the UNIX manual page for login. The AFS version does
+ not impose any stronger restrictions on acceptable user
+ names than does the UNIX file system.
+
+OUTPUT
+
+ To distinguish the AFS version of login from other versions,
+ one of the following banners appears on standard out
+ (stdout) when the command executes successfully.
+
+ AFS 3.0 Login
+
+ or
+
+ AFS 3.2 (R) Login
+
+ Various error messages appear if the login attempt is not
+ successful. The "login:" prompt normally returns following
+ the error messages, giving the user another chance to type
+ the password correctly.
+
+PRIVILEGE REQUIRED
+
+
+
+ None.
+
+
+
+MORE INFORMATION
+
+ rlogind (AFS version)
+
+ UNIX manual page for login
--- /dev/null
+rcp (AFS version) AFS Commands rcp (AFS version)
+
+
+NAME
+
+ rcp (AFS version) -- copy file on remote machine.
+
+
+ +
+ rcp [-p] <file1> <file2> rcp [-r] [-p] <file> <directory>
+
+DESCRIPTION
+
+ Functions like the standard UNIX rcp, except it allows the
+ issuer to use the remote machine's Cache Manager to access
+ AFS files as an authenticated AFS user. The command passes
+ a copy of the AFS token which the issuer obtained on the
+ local machine to the remote machine's Cache Manager. The
+ remote Cache Manager can use the token to gain authenticated
+ access to AFS.
+
+ Token passing is most effective if both the remote machine
+ and local machine belong to the same cell, because rcp can
+ pass only one token even if the user has several tokensMit
+ passes the token that is marked [1] in the output from the
+ tokens command. If the remote and local machine are not in
+ the same cell, the possibilities are:
+
+ - the token passed is for the cell to which the
+ remote machine belongs. The issuer accesses the
+ remote cell's AFS file tree as an authenticated
+ AFS user, but is considered anonymous in the local
+ cell. This means that the issuer can only
+ exercise the access rights granted to
+ system:anyuser in the local AFS file tree. For
+ instance, a file being copied into the local cell
+ can only be copied into a UNIX directory or an AFS
+ directory where system:anyuser has the INSERT
+ right.
+
+ - the token passed is for the cell to which the
+ local machine belongs. The issuer accesses the
+ remote cell's AFS file tree as anonymous, and so
+ can only exercise the access rights granted to
+ system:anyuser.
+
+ In addition to running the AFS version of the rcp binary on
+ the machine where the rcp command is issued, other
+ configuration changes are necessary for token passing to
+ work properly. See the REQUIREMENTS/RESTRICTIONS section
+ for a list.
+
+ The AFS version of rcp is compatible with the standard
+ inetd, but token passing works only if the AFS versions of
+ both programs are being used. If only one of them is
+ modified, the issuer will access AFS files through the
+ remote machine as anonymous.
+
+WARNINGS
+
+ AFS rcp does not allow "third party copies", in which
+ neither source nor target file is on the current machine.
+ Standard UNIX rcp claims to provide this functionality.
+
+ The protections required on the .rhosts file in order for
+
+
+
+ token passing to work with this command (see the
+ REQUIREMENTS/RESTRICTIONS section) are the opposite of those
+ necessary for token creation to work with the AFS version of
+ rlogind.
+
+ For security's sake, use the AFS version of rcp only in
+ conjunction with PAGs, either by using the AFS version of
+ login or always issuing pagsh before obtaining tokens.
+
+REQUIREMENTS/RESTRICTIONS
+
+ Several configuration requirements and restrictions are
+ necessary for token passing to work correctly with the AFS
+ version of rcp. Some of these are also necessary with the
+ standard UNIX version, but are included here because the
+ issuer accustomed to AFS protections may not consider them.
+ There may be other UNIX-based requirements/restrictions not
+ mentioned here; consult the UNIX manual page. (One
+ important one is that no stty commands may appear in the
+ issuer's shell initialization file, such as .cshrc.)
+
+ The requirements/restrictions for token passing include the
+ following.
+
+ - The local machine must be running the AFS version
+ of rcp, with the rcp binary file locally installed
+ to grant setuid privilege to the owner, "root".
+
+ - The remote machine must be running the AFS version
+ of inetd.
+
+ - The following two lines must appear in the
+ /etc/services file on the local machine (as well
+ as on the remote machine running modified inetd).
+ On NeXT machines, this information must appear in
+ the NetInfo database rather than in /etc/services.
+
+ auth 113/tcp authentication
+ ta-rauth 601/tcp rauth
+
+ - If rcp is to consult an .rhosts file on the remote
+ machine, the file must have UNIX protections no
+ more liberal than -rw-r--r--. If .rhosts resides
+ in a user home directory in AFS, the home
+ directory must also grant the LOOKUP and READ
+ rights to system:anyuser.
+
+ARGUMENTS
+
+ Consult the UNIX manual page for rcp.
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ inetd (AFS version)
+
+ UNIX manual page for rcp
+
+ rlogind (AFS version)
+
+
+
+ tokens
--- /dev/null
+rlogind (AFS version) AFS Commands rlogind (AFS version)
+
+
+NAME
+
+ rlogind (AFS version) -- initialize remote login server.
+
+
+ /etc/rlogind
+
+DESCRIPTION
+
+ Functions like the standard UNIX rlogind, except that it is
+ appropriate only for cells using the AFS version of the
+ login program supplied by Transarc Corporation.
+
+ The AFS modifications to rlogind are strictly internal and
+ are necessary so that remote AFS authentication is possible
+ with the rlogin command. When a user issues rlogin, the AFS
+ version of rlogind running on the remote machine invokes the
+ AFS version of login; the user therefore obtains AFS tokens
+ on the remote machine.
+
+ In the configuration recommended by Transarc Corporation,
+ the AFS version of rlogind is substituted for the standard
+ versionMbut only if the AFS version of login is also being
+ used in the cell. (Only one version of rlogind can run on a
+ machine at a time.) The administrator then has two choices:
+
+ - name the binary for the AFS version something like
+ rlogind.afs, leaving the standard version as
+ rlogind. Refer to rlogind.afs in inetd.conf.afs
+ (the AFS version of inetd.conf), and comment out
+ the reference to standard rlogind in standard
+ inetd.conf.
+
+ - name the binary for the AFS version rlogind and
+ rename the binary for the standard version to
+ something like rlogind.old. Refer to rlogind in
+ inetd.conf.afs (the AFS version of inetd.conf),
+ and comment out the reference to rlogind in
+ standard inetd.conf.
+
+WARNINGS
+
+ The AFS version of rlogind is not available for the AIX
+ 2.2.1 operating system. (AIX 2.2.1 does not include the
+ standard rlogind either.)
+
+ Do not install the AFS version of rlogind if the AFS version
+ of login is not being used in the cell.
+
+ Remote AFS authentication is possible with rlogin only if
+
+ EITHER no .rhosts file exists on the machine where rlogind
+ is running
+
+ OR .rhosts exists on the machine where rlogind is running, b
+ has mode bits more liberal than -rw-r--r--. If .rhosts has
+ mode bits as restrictive as -rw-r--r--, then rlogind logs th
+ issuer of the remote rlogin command into the local UNIX file
+ system without prompting for a password. The issuer does no
+ tokens (authenticate with AFS), because that requires provid
+ password. The user can, however, obtain tokens by issuing p
+
+
+
+ and klog after establishing the connection.
+
+ The protection required on .rhosts for token creation to
+ work properly are exactly opposite those necessary for the
+ AFS versions of rcp and rsh to handle tokens properly. The
+ recommended solution is to configure .rhosts so that rcp and
+ rsh work properly and to use telnet instead of rlogin.
+
+ No modifications to rlogin itself are necessary for AFS
+ authentication to work.
+
+PRIVILEGE REQUIRED
+
+ See the UNIX manual page for rlogind.
+
+MORE INFORMATION
+
+ login (AFS version)
+
+ rcp (AFS version)
+
+ UNIX manual page for rlogind
+
+ rsh (AFS version)
--- /dev/null
+rsh (AFS version) AFS Commands rsh (AFS version)
+
+
+NAME
+
+ rsh (AFS version) -- open shell on remote machine.
+
+
+ rsh host [-l <username>] [-n] <command> host [-l
+ <username>] [-n] <command>
+
+DESCRIPTION
+
+ Functions like the standard UNIX rsh, except that it allows
+ the issuer to execute commands on the remote machine as an
+ authenticated AFS user. The command passes a copy of the
+ AFS token that the issuer has obtained on the local machine
+ to the remote machine's Cache Manager. The remote Cache
+ Manager can use the token to have the issuer recognized as
+ an authenticated AFS user.
+
+ Token passing is most effective if both the remote machine
+ and local machine belong to the same cell, because rsh can
+ pass only one token even if the user has severalMit passes
+ the token that is marked [1] in the output from the tokens
+ command. If the remote and local machine are not in the
+ same cell, the token should be for the cell to which the
+ remote machine belongs, so that the remote cell's server
+ processes will recognize the issuer as authenticated.
+
+ In addition to running the AFS version of the rsh binary on
+ the machine where the rsh command is issued, other
+ configuration changes are necessary for token passing to
+ work properly. See the REQUIREMENTS/RESTRICTIONS section
+ for a list.
+
+ The AFS version of rsh is compatible with the standard
+ inetd, but token passing only works if the AFS versions of
+ both programs are being used. If only one of them is
+ modified, the issuer will access AFS files through the
+ remote machine as anonymous.
+
+WARNINGS
+
+ The protections required on the .rhosts file for token
+ passing to work correctly with this command (see the
+ REQUIREMENTS/RESTRICTIONS section) are the opposite of those
+ necessary for token creation to work correctly with the AFS
+ version of rlogind.
+
+ For security's sake, use the AFS version of rsh only in
+ conjunction with PAGs, either by using the AFS version of
+ login or always issuing pagsh before obtaining tokens.
+
+REQUIREMENTS/RESTRICTIONS
+
+ Several configuration requirements and restrictions are
+ necessary for token passing to work correctly with the AFS
+ version of rsh. Some of these are also necessary with the
+ standard UNIX version, but are included here because the
+ issuer used to AFS protections may not be inclined to think
+ of them. There may be other UNIX-based
+ requirements/restrictions not mentioned here; consult the
+ UNIX manual page. (One important one is that no stty
+
+
+
+ commands may appear in the issuer's shell initialization
+ file, such as .cshrc.)
+
+ The requirements/restrictions for token passing include the
+ following.
+
+ - The local machine must be running the AFS version
+ of rsh, with the binary file locally installed to
+ grant setuid privilege to the owner, "root".
+
+ - The remote machine must be running the AFS version
+ of inetd.
+
+ - The following two lines must appear in the
+ /etc/services file on the local machine (as well
+ as on the remote machine running modified inetd).
+ On NeXT machines, this information must appear in
+ the NetInfo database rather than in /etc/services.
+
+ auth 113/tcp authentication
+ ta-rauth 601/tcp rauth
+
+ - If rsh is to consult an .rhosts file on the remote
+ machine, the file must have UNIX protections no
+ more liberal than -rw-r--r--. If .rhosts resides
+ in a user home directory in AFS, the home
+ directory must also grant the LOOKUP and READ
+ rights to system:anyuser.
+
+ARGUMENTS
+
+ Consult the UNIX manual page for rsh.
+
+MORE INFORMATION
+
+ inetd (AFS version)
+
+ UNIX manual page for rsh
+
+ rlogind (AFS version)
+
+ tokens
--- /dev/null
+afsd AFS Commands afsd
+
+
+NAME
+
+ afsd -- initialize Cache Manager and start related
+
+ daemons.
+
+
+ afsd [-blocks <number of cache blocks>] [-files <number of
+ cache files>]
+ [-stat <number of status cache entries>] [-rootvol <root
+ volume>]
+ [-cachedir <cache directory>] [-mountdir <AFS mount
+ directory>]
+ [-verbose] [-debug] [-nosettime]
+ [-daemons <number of background daemons>] [-rmtsys]
+ [-memcache] [-dcache <# entries>] [-chunksize <chunk
+ exponent>]
+
+ACCEPTABLE ABBREVIATIONS
+
+ This command does not use the syntax conventions of the AFS
+ command suites. Therefore, "afsd" and all switches and
+ flags must be typed in full.
+
+DESCRIPTION
+
+ Initializes the Cache Manager on an AFS client machine by
+ transferring AFS-related configuration information into
+ kernel memory and starting several daemons. More
+ specifically, afsd
+
+ - sets a field in kernel memory that defines which
+ cell the machine belongs to. Some Cache
+ Manager-internal operations and system calls
+ consult this field to learn which cell to execute
+ in. (The AFS command interpreters refer to
+ /usr/vice/etc/ThisCell instead.)
+
+ This information is transferred into the kernel
+ from the file /usr/vice/etc/ThisCell and cannot be
+ changed until afsd runs again.
+
+ - places in kernel memory the names and Internet
+ addresses of the database server machines in the
+ local cell and (optionally) foreign cells. The
+ appearance of a cell's database server machines in
+ this list enables the Cache Manager to contact
+ them and so to access files in the cell. Omission
+ of a cell from this list, or incorrect information
+ about its database server machines, prevents the
+ Cache Manager from accessing files in it.
+
+ This information is transferred into the kernel
+ from the file /usr/vice/etc/CellServDB. After
+ initialization, use the fs newcell command to
+ change the kernel-resident list without having to
+ reboot.
+
+ - determines whether the cache is on disk or in
+ machine memory. The default is to use a disk
+ cache. If the -memcache argument is provided,
+
+
+
+ space is allocated in machine memory for caching,
+ and disk space is not used even if the machine has
+ a disk.
+
+ - defines the name of the local disk directory
+ devoted to caching, when -memcache is not used.
+ If necessary, afsd creates the directory (as long
+ as its parent directory exists). It does not
+ remove from the disk the directory that formerly
+ served this function, if any.
+
+ The second field in the file
+ /usr/vice/etc/cacheinfo is the source for this
+ name, and the standard value is /usr/vice/cache.
+ Use the -cachedir argument to override the value
+ from cacheinfo.
+
+ - sets the size of the cache, for both disk and
+ memory caches.
+
+ The afsd program consults the third field in the
+ file /usr/vice/etc/cacheinfo to learn the default
+ cache size in kilobyte blocks. The value should
+ not exceed 90% to 95% of the disk space available
+ on the cache partition (with a disk cache) or of
+ the machine's memory (with a memory cache). This
+ is because the cache implementation itself
+ requires a small amount of disk or machine memory.
+
+ For either a disk or memory cache, use the -blocks
+ argument to override the value from cacheinfo.
+
+ For a memory cache, the issuer can also override
+ the cacheinfo value by providing either
+
+ * both -dcache and -chunksize, to set both
+ number of dcache entries and chunk size (see
+ below for definition of these parameters).
+ In this case, afsd derives cache size
+ (overriding the cacheinfo value) by
+ multiplying the two values. Using this
+ combination is not recommended, as it
+ requires the issuer to perform the
+ calculation beforehand to determine the
+ resulting cache size.
+
+ * -dcache by itself. In this case, afsd derives
+ cache size (overriding the cacheinfo value)
+ by multiplying -dcache by the default chunk
+ size of 8 kilobytes. Using this argument is
+ not recommended, as it requires the issuer to
+ perform the calculation beforehand to
+ determine the resulting cache size.
+
+ For a disk cache, the value defined in cacheinfo
+ or with -blocks is an absolute upper limit on
+ cache size; values provided for other arguments
+ cannot result in a larger cache.
+
+ After initialization, use fs setcachesize to
+ change the size of a disk cache without having to
+
+
+
+ reboot; the value set with that command is
+ overridden the next time afsd runs. The
+ fs setcachesize command does not work for memory
+ caches. Instead, the machine must be rebooted.
+
+ - sets the size of each "chunk" of data in the
+ cache, and by implication the amount of data that
+ the Cache Manager requests at a time from the File
+ Server (how much data per "fetch" RPC, since AFS
+ uses partial file transfer).
+
+ For a disk cache, each chunk is called a "V file",
+ so this parameter sets the maximum size of each V
+ file; the default is 64 kilobytes. See below for
+ more on V files.
+
+ For a memory cache, each chunk is a collection of
+ memory blocks allocated together, so this sets the
+ size of each collection; the default is 8
+ kilobytes.
+
+ For both types of cache, use the -chunksize
+ argument to change the default chunk size. To
+ guarantee proper chunk sizes, the integer provided
+ is used as an exponent on the number 2; see the
+ ARGUMENTS section for details. For a memory
+ cache, if total cache size divided by chunk size
+ leaves a remainder, afsd rounds down the number of
+ dcache entries. resulting in a slightly smaller
+ cache (see below for more on dcache entries).
+
+ - sets the number of empty "V files" created in the
+ cache directory for a disk cache. Each file is a
+ cache chunk, and the Cache Manager caches data in
+ them as needed. By default, each "V" file can
+ accommodate up to 64 kilobytes of data, since 64
+ kilobytes is the default size of a disk cache
+ chunk.
+
+ A memory cache cannot use V files because it does
+ not use disk memory; instead the number of chunks
+ is equivalent to the number of "dcache entries"
+ (see below).
+
+ The default number of V files is 1000; use the
+ -files argument to override it. Since by default
+ each V file can accommodate 64 kilobytes, the only
+ reason to increase from the default of 1000 is if
+ the cache size is greater than about 64 megabytes
+ (or the chunk size has been changed with the
+ -chunksize argument discussed above).
+
+ - sets the number of "dcache entries" allocated in
+ machine memory for storing information about the
+ chunks in the cache.
+
+ With a disk cache, the file
+ /usr/vice/cache/CacheItems on disk contains one
+ entry for each V file. Some of the CacheItems
+ entries, by default 100, are duplicated as dcache
+ entries in machine memory for quicker access.
+
+
+
+ With a memory cache, there is no CacheItems file,
+ so all information about cache chunks must be in
+ memory as dcache entries. There must be one
+ dcache entry for each cache chunk, so for a memory
+ cache number of dcache entries equals number of
+ cache chunks. There is no default number of
+ dcache entries for a memory cache; instead, afsd
+ derives it by dividing cache size by chunk size.
+
+ Use the -dcache argument to set the number of
+ dcache entries. This is not recommended for
+ either type of cache. Increasing the number of
+ dcache entries for a disk cache may improve
+ performance marginally because more entries are
+ retrieved from memory rather than from disk, but
+ is not generally necessary. Using this argument
+ is not recommended for a memory cache because it
+ requires the issuer to pre-calculate cache size by
+ multiplying this value times chunk size (either
+ the default 8 kilobytes or the value of
+ -chunksize).
+
+ - sets the number of "stat" entries available in
+ machine memory for caching status information
+ about cached AFS files.
+
+ The default is 300; use the -stat argument to
+ override the default.
+
+ - defines the directory in the machine's file name
+ space at which the AFS file tree is mounted.
+
+ The first field in the file
+ /usr/vice/etc/cacheinfo is the source for the
+ default directory name. The standard value is
+ /afs. Use the -mountdir argument to override the
+ value from cacheinfo.
+
+ - defines which volume corresponds to the root of
+ the AFS file tree.
+
+ The default is root.afs; use the -rootvol argument
+ to override it. Note that although the volume
+ name should be given in the "base" (ReadWrite)
+ form, the Cache Manager retains its bias for
+ accessing the ReadOnly version of the volumeMin
+ the default case, root.afs.readonlyMif it is
+ available.
+
+ - randomly selects a file server machine in the
+ local cell as the source for the "correct" time.
+ Every five minutes thereafter, the local clock is
+ adjusted (if necessary) to match the file server
+ machine's clock.
+
+ Use the -nosettime flag to prevent afsd from
+ selecting a time standard. This is recommended
+ only on file server machines that are also acting
+ as clients. File server machines maintain the
+ correct time using the Network Time Protocol
+ Daemon instead.
+
+
+
+ In addition to setting cache configuration parameters, afsd
+ starts up the following three types of daemons. On most
+ system types, these daemons appear as nameless entries in
+ the output of the ps command:
+
+ - a "callback" daemon that handles callbacks. It
+ also responds to the File Server's periodic
+ probes, which check that the client machine is
+ still alive.
+
+ - a "maintenance" daemon that performs routine
+ periodic maintenance tasks, including
+
+ * performing garbage collection
+
+ * synchronizing files
+
+ * probing the fileserver process on file server
+ machines every few minutes
+
+ * refreshing information from ReadOnly volumes
+ once per hour
+
+ * doing delayed writes for NFS clients if the
+ machine is running the NFS/AFS Translator
+
+ * keeping the machine's clock synchronized with
+ the chosen file server machine's
+
+ - "background" daemons that improve performance by
+ pre-fetching files and performing background
+ (delayed) writes of saved data into AFS.
+
+ The default number of background daemons is 2,
+ usually enough to handle up to 5 simultaneous
+ users of the machine. Use the -daemons argument
+ to increase the number of background daemons, if
+ the machine serves more users. No more than 6
+ background daemons should ever be necessary.
+
+ The default number of daemons is four (one callback daemon,
+ one maintenance daemon, and two background daemons). The
+ issuer can alter only the number of background daemons; afsd
+ always initializes one callback daemon and one maintenance
+ daemon.
+
+ AFS includes three configuration scripts that can be used to
+ modify some Cache Manager parameters on a client machine
+ that uses a disk cache. Named rc.afsd.small, rc.afsd.med,
+ and rc.afsd.large, the configuration scripts specify
+ suitable, predefined values for the afsd command's -stat,
+ -dcache, -daemons, and -volumes switches. They define
+ increasingly greater values for these switches according to
+ the configuration and usage patterns of the client machine
+ on which the afsd command is run. Refer to the AFS System
+ Administrator's Guide for more information about the scripts
+ and how to use them.
+
+ARGUMENTS
+
+ -blocks specifies the number of kilobyte blocks to be made
+
+
+
+ available for caching in the machine's cache
+ directory (for a disk cache) or memory (for a
+ memory cache), overriding the default defined in
+ the third field of /usr/vice/etc/cacheinfo. It
+ should not exceed 90% to 95% of the actual space
+ available. If using a memory cache, do not
+ combine this argument with -dcache, since doing so
+ could result in a chunk size that was not an
+ exponent of 2.
+
+ -files specifies the number of V files to be created in
+ the cache directory for a disk cache, overriding
+ the default of 1000. Each V file can accommodate
+ a "chunk" of data, which for a disk cache is 64
+ kilobytes by default. Thus the default of 1000 is
+ adequate for any cache smaller than 64 megabytes
+ (unless chunk size is changed with -chunksize).
+ Do not combine this argument with -memcache.
+
+ -stat specifies the number of entries in the machine's
+ memory for recording status information about the
+ AFS files in the cache. This value overrides the
+ default of 300.
+
+ -rootvol names the Read Write volume corresponding to the
+ root directory for the AFS file tree (which is
+ usually /afs). This value overrides the default
+ of root.afs.
+
+ -cachedir names the local disk directory to be used as the
+ cache. This value overrides the default defined
+ in the second field of /usr/vice/etc/cacheinfo
+ (typically, /usr/vice/cache).
+
+ -mountdir names the local disk directory on which to mount
+ the AFS file tree. This value overrides the
+ default defined in the first field of
+ /usr/vice/etc/cacheinfo (typically, /afs). If
+ /afs is not used, the machine cannot access the
+ AFS global name space.
+
+ -daemons specifies the number of "background" daemons to
+ run on the machine. These daemons improve
+ efficiency by doing pre-fetching and background
+ writing of saved data. This value overrides the
+ default of 2, which is adequate for a machine
+ serving up to five users. It does not change the
+ number of "callback" or "maintenance" daemons,
+ which is always one each.
+
+ -verbose causes afsd to produce a more detailed trace of
+ its activities than the default one. The trace
+ displays on standard out (stdout) unless it is
+ piped into a file.
+
+ -debug causes afsd to produce a highly detailed trace of
+ its activities, potentially useful to a developer
+ for debugging purposes. The trace goes to
+ standard output (stdout) by default.
+
+ -nosettime
+
+
+
+ prevents the machine from selecting at random a
+ local file server machine to act as a source for
+ the "correct" time. If this flag is omitted, the
+ machine selects a file server machine as a time
+ standard, and every five minutes thereafter
+ adjusts its clock to avoid drifting from the
+ standard.
+
+ -rmtsys initializes an additional "remote-system" daemon
+ to execute AFS-specific system calls on behalf of
+ NFS client machines. This flag is necessary only
+ if the machine is an NFS/AFS translator machine,
+ and if users on its NFS clients want to execute
+ AFS commands.
+
+ -memcache causes afsd to initialize a memory cache rather
+ than a disk cache. Do not combine this flag with
+ -files.
+
+ -dcache sets the number of "dcache entries" in memory,
+ which are used to store information about cache
+ chunks. For a disk cache, this overrides the
+ default of 100. For a memory cache, this argument
+ effectively sets the number of cache chunks. Use
+ of this argument is not recommended for a memory
+ cache, because it requires the issuer to
+ pre-calculate the resulting total cache size
+ (derived by multiplying this value by chunk size).
+ Do not combine this argument with -blocks, since
+ doing so could result in a chunk size that was not
+ an exponent of 2.
+
+ -chunksize
+ sets the size of each cache chunk. The integer
+ provided, which should be between 0 and 20, is
+ used as an exponent on the number 2. It overrides
+ 16
+ the default of 16 for a disk cache (2 is 64
+ 13
+ kilobytes) and 13 for a memory cache (2 is 8
+ kilobytes). A value of 0 or less, or greater than
+ 20, sets chunk size to the appropriate default.
+ Values less than 10 (which sets chunk size to a
+ 10
+ kilobyte, 2 ) are not recommended. Combining
+ this argument with -dcache is not recommended
+ because it requires that the issuer pre-calculate
+ the cache size that results.
+
+EXAMPLE
+
+ This command is normally included in an initialization file
+ such as /etc/rc, rather than typed at the command shell
+ prompt. For most disk caches, the appropriate form is
+
+ /usr/vice/etc/afsd
+
+ The following is appropriate when enabling a machine to act
+ as an NFS/AFS Translator machine serving more than five
+ users.
+
+ /usr/vice/etc/afsd -daemons 4 -rmtsys
+
+
+
+ The following initializes a memory cache and sets chunk size
+ 14
+ to 16 kilobytes (2 ).
+
+ /usr/vice/etc/afsd -memcache -chunksize 14
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged into the machine's UNIX file system as
+ "root."
--- /dev/null
+dkload AFS Commands dkload
+
+
+NAME
+
+ dkload -- incorporate external libraries into kernel
+
+ without rebooting.
+
+
+ dkload [-readonly] [-quiet] [-verbose] [-syscallResult
+ <number>]
+ [-path <object path>] [-ld_cmd <loader path>]
+ [-as_cmd <assembler path>] [-nm_cmd <nm path>]
+ [-libcommon <path>] [-kernel_alloc <path>]
+ +
+ [-name <library name>] [<library to incorporate> ]
+
+ACCEPTABLE ABBREVIATIONS
+
+ This command does not use the syntax conventions of the AFS
+ command suites. Therefore, "dkload" must be typed in full
+ and switches must always be included, though they may be
+ shortened as indicated.
+
+ dkload [-r] [-q] [-v] [-s <number>] [-p <object path>]
+ [-ld <loader path>]
+ [-a <assembler path>] [-nm <nm path>] [-li <path>] [-k
+ <path>]
+ +
+ [-na <library name>] [<library to incorporate> ]
+
+DESCRIPTION
+
+ Loads one or more libraries into the memory version of the
+ local machine's kernel. It does not alter the disk version
+ of the kernel (/vmunix or equivalent). Its intended use is
+ loading the AFS routine library, lib.afs, into the kernel on
+ client machines.
+
+ The dynamic loader begins by requesting (from a low-level
+ kernel routine) allocation of a certain amount of memory in
+ which to load the libraries. It resolves cross-references
+ between procedures in the existing kernel and in the
+ libraries (referred to as "linking" the two). The result is
+ a list of memory addresses for the cross-referenced
+ procedures, which the dynamic loader stores in a table. It
+ generates an executable version of the libraries with
+ correct addresses inserted for all of the necessary kernel
+ variables and procedures, and loads the executable into the
+ memory space allocated in the first phase.
+
+REQUIREMENTS
+
+ The dkload binary file should be available in the current
+ working directory, or the issuer must specify a pathname in
+ the command name. The standard directory is
+ /usr/vice/etc/dkload on client machines and
+ /usr/afs/bin/dkload on file server machines.
+
+ The file kalloc.o should be available in the current working
+ directory, or the issuer must specify a pathname with either
+ the -kernel_alloc or -path argument. This file helps in the
+ first phase of dynamic loading: allocating kernel memory
+
+
+
+ for the libraries. It is generated automatically during the
+ compilation of the dkload program.
+
+ The file libcommon.a should be available in the current
+ working directory, or the issuer must specify a pathname
+ with either the -libcommon or -path argument. This file
+ helps in the second phase of dynamic loading: resolving
+ cross-references. It is generated automatically during the
+ compilation of the dkload program.
+
+ The library file(s) to be loaded (such as lib.afs) should be
+ available in the current working directory, or the issuer
+ must use the -path argument to specify the correct path.
+
+ The binary files for the standard UNIX commands ld, as and
+ nm should be available in a local disk directory included in
+ the issuer's $PATH environment variable. Otherwise, the
+ issuer needs to use the -ld_cmd, -as_cmd and/or -nm_cmd
+ arguments to specify the correct pathname.
+
+ARGUMENTS
+
+ -readonly directs the command interpreter to report
+ the actions it would perform if executing
+ the command, rather than actually performing
+ it.
+
+ -quiet suppresses the trace of actions that by
+ default appears on standard output (stdout).
+
+ -verbose increases the amount of information in the
+ trace that appears on standard output
+ (stdout). Multiple instances of this flag
+ may be provided, resulting (up to a certain
+ point) in a increasing level of detail in
+ the trace.
+
+ -syscallResult specifies the memory address at which
+ allocation begins when the -readonly flag is
+ provided. This is useful when the issuer
+ wants to specify a memory address obtained
+ during a previous aborted run of dkload.
+
+ Provide this argument only when using
+ -readonly. The value may be either a large
+ decimal or hexidecimal number (the latter
+ beginning with 0x). If this flag is not
+ provided, the value defaults to 0xc1456780,
+ which may not be acceptable on all machine
+ types but has the advantage that it causes
+ allocation to begin well above the addresses
+ used by standard libraries.
+
+ -path specifies the directory in which the command
+ interpreter can find kalloc.o, libcommon.a
+ and each library to be loaded, if they are
+ not in the current working directory. The
+ value of this argument is overridden by
+ -kernel_alloc and -libcommon, or the
+ pathnames given for each library to
+ incorporate.
+
+
+
+ -ld_cmd specifies the pathname to the binary for the
+ UNIX ld command, which the kernel dynamic
+ loader uses during the linking phase.
+
+ This argument is necessary only if the
+ issuer's $PATH environment variable will not
+ lead to the correct binary file. The binary
+ file cannot be in AFS, for instance, since
+ the dynamic loader runs before the machine
+ can access AFS.
+
+ -as_cmd specifies the pathname to the binary for the
+ UNIX as command, which the kernel dynamic
+ loader uses during the linking phase.
+
+ This argument is necessary only in the
+ conditions specified under -ld_cmd.
+
+ -nm_cmd specifies the pathname to the binary for the
+ UNIX nm command, which the kernel dynamic
+ loader uses during the linking phase.
+
+ This argument is necessary only in the
+ conditions specified under -ld_cmd.
+
+ -libcommon specifies the pathname of the libcommon.a
+ file.
+
+ This argument is necessary only if the file
+ does not reside in the current working
+ directory or if the -path argument does not
+ indicate the correct directory for it.
+
+ -kernel_alloc specifies the pathname of the kalloc.o file.
+
+ This argument is necessary only in the
+ conditions specified under -libcommon.
+
+ -name specifies the variable part of the library
+ name to be loaded: the command interpreter
+ loads the library called
+ "lib<library name>.a". For example, if
+ <library name> is afs, then libafs.a gets
+ loaded.
+
+ Provide this argument OR library to
+ incorporate.
+
+ library to incorporate names each library to be incorporated
+ into the kernel.
+
+ Provide this argument OR -name.
+
+EXAMPLE
+
+ The following loads in the AFS libraries. It assumes that
+ all files can be found in the current directory or other
+ expected place. The issuer desires extra trace information.
+
+ % dkload -verbose -name afs
+
+
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged into the machine's UNIX file system as
+ "root" or at least have w access to /dev/mem and /dev/kmem.
--- /dev/null
+fileserver AFS Commands fileserver
+
+
+NAME
+
+ fileserver -- initialize File Server component of fs
+
+ process.
+
+
+ /usr/afs/bin/fileserver [-b <buffers>] [-banner] [-cb
+ <callbacks>]
+ [-d <debug level>] [-k <stack size>] [-l <large vnodes>]
+ [-oldvldb] [-pctspare <percent>] [-rxdbg]
+ [-rxdbge] [-rxpck]
+ [-s <small vnodes>] [-spare <kilobyte blocks>]
+ [-w <callback wait interval>]
+ [-c <check interval>] [-ftpck <r ftp packets>] [-noauth]
+ [-p <LWPs>] [-r <r retry count>] [-rpck <r
+ packets
+
+DESCRIPTION
+
+ Initializes the File Server component of the fs process.
+
+ The arguments on fileserver allow the issuer to control many
+ aspects of its behavior, as detailed in the ARGUMENTS
+ section.
+
+ Perhaps the most important aspect to control from an
+ administrative standpoint is that by default the File Server
+ allows users to store up to a megabyte (1024 kilobytes) of
+ data in a volume after the volume's quota is exceeded. The
+ user still cannot create new files after quota is exceeded.
+ The issuer of this command can change the default with the
+ -spare or -pctspare arguments:
+
+ - -spare specifies the number of kilobytes over
+ quota the File Server will allow. To make users
+ unable to store files after the quota is exceeded,
+ specify a value of 0.
+
+ - -pctspare expresses the amount of excess the File
+ Server will allow as a percentage of the volume's
+ quota.
+
+WARNING
+
+ This command is not normally issued at the command shell
+ prompt, but rather placed into a file server machine's
+ /usr/afs/local/BosConfig with the bos create command. If it
+ is ever issued at the command shell prompt, the issuer must
+ be working on a file server machine.
+
+ Several of this command's arguments are intended for use by
+ AFS developers only. Changing them from their default
+ values is strongly discouraged and may result in
+ unpredictable File Server behavior. The relevant arguments
+ are marked in the ARGUMENTS section.
+
+ This command does not use the syntax conventions of the AFS
+ command suites, so the command and switch names must be
+ typed in full.
+
+ Do not specify both -spare and -pctspare. Doing so causes
+
+
+
+ the File Server to exit, leaving an error message in
+ /usr/afs/logs/FileLog.
+
+ARGUMENTS
+
+ -b sets the number of directory buffers, which are
+ 2 kilobytes each. Provide a positive integer.
+ The default is 70.
+
+ -banner causes the File Server to prints the following
+ banner to /dev/console about every 10 minutes.
+
+ File Server is running at time.
+
+ -cb sets the number of callbacks the File Server
+ can track. Provide a positive integer. The
+ default is 20,000.
+
+ -d sets the detail level for the debugging trace
+ the File Server produces in
+ /usr/afs/logs/FileLog. Provide a positive
+ integer; higher values (up to a point) produce
+ greater detail. The default level of 0
+ produces no trace.
+
+ -k sets the LWP stack size in units of 1 kilobyte.
+ Provide a positive integer. The default is 24
+ (kilobytes). Do not set this argument lower
+ than the default.
+
+ -l sets the number of large vnodes to use (for
+ tracking directory elements). Provide a
+ positive integer. The default is 200.
+
+ -oldvldb directs the File Server to use the pre-AFS 3
+ volume location facility rather than the VLDB
+ and VL Server.
+
+ -pctspare specifies the amount by which the File Server
+ will allow a volume to exceed its quota, as a
+ percentage of the quota. Provide an integer
+ between 0 and 99. A value of 0 prevents the
+ volume from ever exceeding its quota. Do not
+ combine this argument with -spare.
+
+ -rxdbg sends an Rx debugging trace to the rx_dbg file
+ in the current working directory.
+
+ -rxdbge sends an Rx event debugging trace to the rx_dbg
+ file in the current working directory.
+
+ -rxpck sets the number of extra Rx packets to reserve.
+ Provide a positive integer. The default is
+ 100. Do not use this argument; changing its
+ default may cause unpredictable behavior.
+
+ -s sets the number of small vnodes to use (for
+ tracking file elements). Provide a positive
+ integer. The default is 200.
+
+ -spare specifies the number of extra kilobytes the
+
+
+
+ File Server will allow users to store in a
+ volume after its quota is exceeded. Provide a
+ positive integer. A value of 0 prevents the
+ volume from ever exceeding its quota. Do not
+ combine this argument with -pctspare.
+
+ -w sets the interval at which daemons spawned by
+ the File Server perform their maintenance
+ tasks. The default is 300 seconds (5 minutes).
+ Do not use this argument; changing its default
+ may cause unpredictable behavior.
+
+ -c is not implemented.
+
+ -ftpck is obsolete.
+
+ -noauth is obsolete.
+
+ -p is obsolete.
+
+ -r is obsolete.
+
+ -rpck is obsolete.
+
+EXAMPLES
+
+ The following bos create command creates an fs process on
+ fs2.transarc.com that allows volumes to exceed their quota
+ by 10%.
+
+ Type the command on a single line.
+
+ % bos create fs2.transarc.com fs fs "/usr/afs/bin/fileserver
+ -pctspare 10"
+ /usr/afs/bin/volserver /usr/afs/bin/salvager
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList to place this
+ command in /usr/afs/local/BosConfig, because that is the
+ privilege required to issue bos create.
+
+MORE INFORMATION
+
+ bos create
--- /dev/null
+ AFS Commands
+
+ 1. The fs Commands
+
+ ------------------------------------------------------------
+
+ This command defines the fs commands that users and system
+ administrators employ to contact the File Server and to
+ configure the Cache Manager. It assumes the reader is
+ familiar with the concepts described in the AFS System
+ Administrator's Guide.
+
+ Some fs commands extend UNIX file system semantics by
+ invoking file-related functions that UNIX does not provide
+ (setting access control lists, for example). Other fs
+ commands help users control the performance of the Cache
+ Manager running on their local client workstation. When
+ using fs commands, pay particular attention to the kind of
+ privilege required, as it varies from command to command.
+
+ Refer to the Command Summary at the end of this document for
+ a complete list of fs commands and their syntax.
+
+ 1.1 Common Arguments and Flags
+ All fs commands accept the following optional flag. It is
+ listed in the command descriptions and is described in
+ detail here:
+
+ [-help]
+
+ This flag has the same function as the fs help command: It
+ prints a command's online help message on the screen. No
+ other arguments or flags should be provided at the same time
+ as this flag. If they are, this flag overrides them, and
+ the only effect of issuing the command is that the help
+ message appears.
+ AFS Command Reference Manual The fs Commands 2
+
+
+ 1.2 The Privileges Required for fs Commands
+ The privileges required for fs commands vary more than those
+ required for commands in other suites. Pay special
+ attention to the PRIVILEGE REQUIRED section of each command
+ description.
+
+ The various types of necessary privilege include
+
+
+ - Having certain rights on a directory's access
+ control list. For example, creating and removing
+ mount points requires ADMINISTER, INSERT, and
+ DELETE rights for the directory in which the mount
+ point resides. Setting a directory's access
+ control list requires certain rights, too.
+
+ - Being logged in as the super-user "root" in the
+ UNIX file system of the machine on which the
+ command is being issued. This is necessary when
+ issuing commands that affect Cache Manager
+ configuration.
+
+ - Belonging to the system:administrators group in
+ the Protection Database. See the fs setvol
+ command for an example.
+
+ - No privilege. Many fs commands simply list
+ information and so do not require any special
+ privilege.
--- /dev/null
+fs apropos AFS Commands fs apropos
+
+
+NAME
+
+ fs apropos -- show each help entry containing keyword.
+
+
+ fs apropos -topic <help string> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs ap -t <help string> [-h]
+
+DESCRIPTION
+
+ Displays the first line of the online help entry for any fs
+ command that has help string in its name or short
+ description.
+
+ARGUMENTS
+
+ -topic
+ specifies the keyword string for which to search. If
+ it is more than a single word, surround it with double
+ quotes or other delimiters. This argument is
+ case-sensitive; type help strings for fs commands in
+ lowercase letters.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The first line of a command's online help entry names the
+ command and briefly describes what it does. The fs apropos
+ command displays that first line for any fs command where
+ help string is part of the command name or first line.
+
+ To see the remaining lines in a help entry, which provide
+ the command's alias (if any) and syntax, use the fs help
+ command.
+
+EXAMPLES
+
+ The following lists all fs commands that have the word
+ "cache" in their operation codes or short online
+ descriptions:
+
+ % fs apropos -topic cache
+ setcachesize: set cache size
+ flush: flush file from cache
+ getcacheparms: get cache usage info
+ monitor: set cache monitor host address
+
+
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs help
--- /dev/null
+fs checkservers AFS Commands fs checkservers
+
+
+NAME
+
+ fs checkservers -- check status of file server machines.
+
+
+ fs checkservers [-cell <cell to check>] [-all] [-fast]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs checks [-c <cell to check>] [-a] [-f] [-h]
+
+DESCRIPTION
+
+ Lists any file server machines in the indicated cell(s) that
+ meet two conditions:
+
+ 1. The Cache Manager has been in contact with the
+ fileserver process running on the machine, and/or
+ may need to contact it in future. (Reasons for
+ wanting to contact a file server machine might
+ include holding a callback from that machine or
+ having locked files on it.)
+
+ 2. The fileserver process on the machine is not
+ currently responding to Cache Manager probes
+ (implying that it is not responding to Cache
+ Manager file requests either).
+
+ The Cache Manager constantly maintains a list of file server
+ machines that meet the first condition, updating it every
+ four to ten minutes by attempting to contact the fileserver
+ process on each machine in the list. When a process does
+ not respond to the probe, the Cache Manager marks it as
+ non-functioning. If a machine that previously did not
+ respond begins to respond again, the Cache Manager erases
+ the "not functioning" mark.
+
+ This command forces the Cache Manager to update its
+ information immediately (rather than waiting the standard
+ interval). The Cache Manager probes the fileserver process
+ on the machines in the specified cell that meet the first
+ condition above, records those that do not respond, and
+ reports the result. If the issuer includes the -fast flag,
+ the Cache Manager outputs the list it already has at the
+ time the command is issued instead of probing the machines
+ again.
+
+ By default, the Cache Manager probes machines in the local
+ cell only. If the -all flag is used, it probes all machines
+ (from all cells) that meet the first condition. If a cell
+ name is specified with -cell, The Cache Manager probes the
+ machines in that cell only.
+
+WARNING
+
+ It can take quite a while for this command to produce its
+ entire output if a number of machines in the Cache Manager's
+ list are in fact down when the command is issued. The delay
+ is because after issuing the probe the Cache Manager waits a
+ standard timeout period before concluding that the
+
+
+
+ fileserver is not responding; this allows for the
+ possibility of slow cross-network communication. If it is
+ important that the command shell prompt return quickly, the
+ issuer may wish to put this command in the background. It
+ is harmless to interrupt the command (with Ctrl-C or another
+ interrupt signal).
+
+ This command is not guaranteed to check the status of all
+ file server machines in a cell. The Cache Manager probes
+ only those machines that meet the first condition mentioned
+ above.
+
+ARGUMENTS
+
+ -cell specifies the complete name of the cell whose file
+ server machines the Cache manager should probe
+ (shortened forms are not acceptable). Provide this
+ argument OR -all; it may be combined with -fast.
+
+ -all causes the Cache Manager to probe all machines that
+ meet the first condition mentioned above. Provide
+ this argument OR -cell; it may be combined with -fast.
+
+ -fast tells the Cache Manager to display its current list of
+ down machines, rather than probing any machines. The
+ displayed output may be up to 10 minutes old.
+
+ -dir is obsolete, but can still be provided on the
+ command-line. Previous versions of this command
+ required a directory argument. If the issuer includes
+ it by accident, a warning message appears, but the
+ command still executes correctly.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ If the Cache Manager gets a response from all of the
+ machines that it probes (i.e., all such machines are
+ functioning normally), the output is
+
+ All servers are running.
+
+ (Remember that this message does not imply that all file
+ server machines in the cell are running. It reports the
+ status of only those that the Cache Manager tries to probe.)
+
+ If a machine fails to respond to the Cache Manager's probe
+ within the timeout period, the output displays its name.
+ The format of a machine name (name in uppercase, name in
+ lowercase, or Internet address in four-field decimal form)
+ depends on the state of the local cell's name server at the
+ time the command is issued.
+
+EXAMPLES
+
+ In the following example, the issuer chooses to see the
+ Cache Manager's current list of down machines that belong to
+
+
+
+ the local cell, rather than waiting for it to probe them
+ again. The output indicates that all machines responded to
+ the previous probe.
+
+ % fs checks -f All servers are running.
+
+ The following example checks file server machines in all
+ cells that the Cache Manager has previously contacted. It
+ reports that the machines fs1.transarc.com and
+ vice3.andrew.cmu.edu did not respond to the machine's probe.
+
+ % fs checkservers -all & These servers are still down:
+ fs1.transarc.com VICE3.ANDREW.CMU.EDU
+
+ The following example checks machines in the athena.mit.edu
+ cell only:
+
+ % fs checks athena.mit.edu & %All servers are running.
+
+PRIVILEGE REQUIRED
+
+ None.
--- /dev/null
+fs checkvolumes AFS Commands fs checkvolumes
+
+
+NAME
+
+ fs checkvolumes -- force Cache Manager to update volume-
+
+ related information.
+
+
+ fs checkvolumes [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs checkv [-h]
+
+DESCRIPTION
+
+ Forces the Cache Manager to discard its table of mappings
+ between volume names and volumeID numbers. The Cache
+ Manager needs the information in the table to fetch files,
+ so this command will force it to fetch the most current
+ information available at the File Server about a volume's
+ contents before it can fetch any more files.
+
+ This command is most useful if the issuer knows that a
+ volume's name has changed, or that there has been a release
+ of new ReadOnly replicas, because issuing it forces the
+ Cache Manager to reference the volume with the new name, or
+ the new ReadOnly replica.
+
+ Normally the Cache Manager flushes the table and constructs
+ a new one once per hour anyway.
+
+ARGUMENTS
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+PRIVILEGE REQUIRED
+
+ None.
--- /dev/null
+fs cleanacl AFS Commands fs cleanacl
+
+
+NAME
+
+ fs cleanacl -- remove obsolete entries from access control
+
+ list.
+
+
+ +
+ fs cleanacl [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs cl [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Removes from the access control list of each specified
+ directory or file any entries that specify a user or group
+ no longer found in the Protection Database. When a
+ user/group is removed from the Protection Database, its AFS
+ UID appears on access control lists rather than its name.
+ This command removes such "abandoned" AFS UIDs from access
+ control lists.
+
+ Cleaning access control lists in this way not only keeps
+ them from becoming crowded with irrelevant information, but
+ also prevents the new possessor of a recycled AFS UID from
+ obtaining access intended for the former possessor of the
+ ID. (Note that recycling IDs is not recommended in any
+ case.)
+
+ARGUMENTS
+
+ -path specifies a file or directory for which the associated
+ access control list is to be cleaned. If a filename
+ is specified, the ACL of the file's parent directory
+ is cleaned. If the issuer omits this switch, the
+ current working directory is assumed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ If there are no obsolete AFS UIDs on the ACL, the following
+ message appears:
+
+ Access list for directory is fine.
+
+ Otherwise, the output reports the resulting state of the
+ ACL, following the header
+
+ Access list for directory is now
+
+
+
+EXAMPLES
+
+ In the following example, the user pat cleans the ACL on the
+ current directory and its subdirectories called reports and
+ sources. The ACLs for the first two have no obsolete AFS
+ UIDs on them, but sources does.
+
+ % fs cl . ./reports ./sources Access list for . is fine.
+ Access list for ./reports is fine. Access list for
+ ./sources is now Normal rights: system:authuser rl
+ pat rlidwka
+
+PRIVILEGE REQUIRED
+
+ Issuer must have ADMINISTER rights to the directory; by
+ default, the owner of the directory and members of
+ system:administrators do.
+
+MORE INFORMATION
+
+ fs listacl
--- /dev/null
+fs copyacl AFS Commands fs copyacl
+
+
+NAME
+
+ fs copyacl -- copy access control list from one directory
+
+ to one or more other directories.
+
+
+ fs copyacl -fromdir <source directory>
+ +
+ -todir <destination directory>
+ [-clear] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs co -f <source directory> -t <destination directory>
+ [-c] [-h]
+
+DESCRIPTION
+
+ Copies the access control list (ACL) from the source
+ directory to each destination directory. The command does
+ not affect entries on the ACL of the source directory. It
+ affects entries on the ACL of each destination directory as
+ follows:
+
+ - If an entry is unique to the ACL of the source
+ directory, it is copied to the ACL of the
+ destination directory.
+
+ - If an entry exists on the ACLs of both
+ directories, it is changed on the ACL of the
+ destination directory to match the rights granted
+ on the ACL of the source directory.
+
+ - If an entry is unique to the ACL of the
+ destination directory and the -clear flag is
+ omitted, the entry is not affected.
+
+ - If an entry is unique to the ACL of the
+ destination directory and the -clear flag is
+ included, the entry is removed.
+
+ Use the -clear flag to completely replace the ACL of each
+ destination directory with that of the source directory.
+
+ARGUMENTS
+
+ -fromdir
+ specifies the source directory whose ACL is to be
+ copied to each destination directory. Abbreviated
+ pathnames are interpreted relative to the directory in
+ which the command is issued. If a filename is
+ provided, the file's parent directory is used as the
+ source directory.
+
+ -todir
+ specifies one or more destination directories to
+ receive the ACL from the source directory.
+ Abbreviated pathnames are interpreted relative to the
+ directory in which the command is issued. A filename
+
+
+
+ cannot be specified with this switch.
+
+ -clear
+ removes all existing entries from the ACL of each
+ destination directory before copying the ACL from the
+ source directory. The ACL of each destination
+ directory is thus completely replaced with the ACL of
+ the source directory. If the issuer omits this flag,
+ entries that exist on the ACL of a destination
+ directory but not on the ACL of the source directory
+ are not affected.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ The following example uses the fs copyacl command to copy
+ the ACL from the current directory to the subdirectory named
+ reports. Entries on the ACL of the current directory are
+ not affected. Because the -clear option is not used,
+ entries on the ACL of the reports directory that are not on
+ the ACL of the current directory remain unaffected as well.
+
+ % fs la . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+
+ Access list for reports is
+ Normal rights:
+ pat rl
+ pat:friends rl
+ Negative rights
+ jones rlidwka
+
+ % fs co . reports
+
+ % fs la . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+
+ Access list for reports is
+ Normal rights:
+ pat rlidwka
+ pat:friends rl
+ smith rlidwk
+ Negative rights
+ jones rlidwka
+
+
+
+PRIVILEGE REQUIRED
+
+ Issuer must have LOOKUP right to the source directory and
+ ADMINISTER right to each destination directory. To issue
+ the command with a filename used for source directory, the
+ issuer must have both the LOOKUP and READ rights on the ACL
+ of the file's parent directory.
+
+MORE INFORMATION
+
+ fs listacl
+
+ fs setacl
--- /dev/null
+fs debug AFS Commands fs debug
+
+
+NAME
+
+ fs debug -- enable/disable Cache Manager debugging trace.
+
+
+ fs debug -debug <'on' or 'off'> [-dafs <afs debug level>]
+ [-dnet <network debug level>] [-syslog] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs de -de <on> or <off> [-da <afs debug level>]
+ [-dn <network debug level>] [-s] [-h]
+
+DESCRIPTION
+
+ Determines whether the Cache Manager records information
+ about its activities that may prove helpful in debugging or
+ other trouble-shooting. The output goes into the file
+ /usr/vice/etc/AFSLog (unless an alternate directory or name
+ is specified for the file with the -logfile switch of the
+ afsd command). See the ARGUMENTS section for information
+ about the different types of debugging output that can be
+ written to the file.
+
+ You can use the more command (or an equivalent command such
+ as the pg command on AIX systems) to read the debugging
+ output recorded in the AFSLog file. You must be logged in
+ as root on the machine on which the AFSLog file resides to
+ read the file. Interpreting the output requires familiarity
+ with the AFS source code.
+
+ARGUMENTS
+
+ -debug
+ controls whether debugging information is produced.
+ The legal values are on, which directs debugging
+ information into the AFSLog file, and off, which stops
+ the recording of information in the file.
+
+ -dafs determines the types of debugging information the
+ Cache Manager produces about its activities. The
+ following list describes the legal values for this
+ switch and the type of debugging output each causes
+ the Cache Manager to write to the AFSLog file:
+
+ - 1, which causes the Cache Manager to write
+ standard debugging information. Using this
+ value provides a good deal of general
+ output.
+
+ - 2, which causes the Cache Manager to write
+ low-level debugging information about the
+ AFS network. Use this value only if you are
+ convinced that network problems exist.
+
+ - 4, which causes the Cache Manager to write
+ debugging information about the RX protocol.
+
+ - 8, which causes the Cache Manager to write
+ debugging information about the interface
+ layer to AFS. This value is not useful on
+
+
+
+ machines running a Sun operating system.
+
+ In addition, if a value of 1, 4, or 8 is specified,
+ the Cache Manager also records in the AFSLog file the
+ AFS UID of each user who accesses data from a file
+ server machine. It records the appropriate AFS UID
+ with each operation that accesses data.
+
+ The legal values can be added to specify different
+ combinations of output. For example, a value of 15
+ specifies that all possible types of output are to be
+ provided. The default value of 1 is used if no value
+ is specified.
+
+ Note: The AFSLog file also records the type of volume
+ (ReadWrite, ReadOnly, or Backup) accessed from a file
+ server machine. The type of the volume is displayed
+ along with the volumeID in the "state" flag in bitmap
+ form. If a ReadWrite volume is accessed, the bits are
+ clear; if a ReadOnly volume is accessed, the 1 bit is
+ set; if a Backup volume is accessed, the 4 bit is set.
+
+ -dnet is not currently implemented and should not be used.
+
+ -syslog
+ specifies that debugging output is to be redirected to
+ the syslogd daemon. This flag can be used only on
+ machines running Sun OS 4.1 or higher.
+
+EXAMPLES
+
+ The following turns on debugging using the default debugging
+ level of 1:
+
+ % fs de on
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ afsd
--- /dev/null
+fs diskfree AFS Commands fs diskfree
+
+
+NAME
+
+ fs diskfree -- show information about the partition housing
+
+ a directory/file.
+
+
+ +
+ fs diskfree [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs df [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Provides information about the partition that houses the
+ volume containing the specified directory or file. See the
+ OUTPUT section for a complete explanation of the information
+ provided. To learn more about the volume itself, use the fs
+ examine command.
+
+ARGUMENTS
+
+ -path specifies a file or directory about whose host
+ partition information is desired. If the issuer omits
+ this argument, the current working directory is
+ assumed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ Note: The numbers that appear in this output may not always
+ agree with the corresponding numbers in the output of the
+ standard UNIX df command. The main reason is that the df
+ output reflects the state of partitions exactly when the
+ command is issued. The numbers in this command's output may
+ be up to 5 minutes old, as the Cache Manager polls the File
+ Server for partition information at that frequency. Another
+ potential difference: the partition size reported by the
+ UNIX df command includes some reserved space that does not
+ show up in this report of partition size, and so is likely
+ to be about 10% larger.
+
+ The output reports the following information about each
+ partition that houses a specified directory or file:
+
+ - the name of the volume that contains the directory
+ or file
+
+ - the total size in kilobyte blocks of the partition
+ that stores the named volume
+
+ - the number of kilobyte blocks used on the
+ partition
+
+ - the number of kilobyte blocks available on the
+
+
+
+ partition
+
+ - the percentage of the partition's total space used
+
+EXAMPLES
+
+ The following shows the output for the partition housing the
+ volume user.smith in the Transarc Corporation cell:
+
+ % fs df /afs/transarc.com/usr/smith
+ Volume Name kbytes used avail %used
+ user.smith 333305 286710 46595 86%
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs examine
--- /dev/null
+fs examine AFS Commands fs examine
+
+
+NAME
+
+ fs examine -- show information about volume containing
+
+ specified directory.
+
+
+ +
+ fs examine [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs exa [-p <dir/file path> ] [-h]
+ +
+ fs listvol [-p <dir/file path> ] [-h]
+ +
+ fs lv [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Displays information about the volume containing each
+ specified directory or file. The information includes the
+ file's quota and current size. See the OUTPUT section for a
+ complete explanation of the information provided. While
+ this command provides the most information about a volume,
+ the fs listquota and fs quota commands are also available to
+ display information about a volume.
+
+ARGUMENTS
+
+ -path specifies each file and/or directory for which
+ information about the host volume is desired. Omit
+ this switch to display information about the volume
+ that contains the current working directory.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ Note: The partition-related numbers that appear in this
+ output may not always agree with the corresponding numbers
+ in the output of the standard UNIX df command. The main
+ reason is that the df output reflects the state of
+ partitions exactly when the command is issued. The numbers
+ in this command's output may be up to 5 minutes old, as the
+ Cache Manager polls the File Server for partition
+ information at that frequency. Another potential
+ difference: the partition size reported by the UNIX df
+ command includes some reserved space that does not show up
+ in this report of partition size, and so is likely to be
+ about 10% larger.
+
+
+
+ The output reports the following information about each
+ volume that contains a specified directory or file:
+
+ - the volumeID number (abbreviated in the output as
+ "vid") of the volume
+
+ - the volume's name
+
+ - the current "offline" message associated with the
+ volume, as set by a system administrator using the
+ fs setvol command
+
+ - the current "message of the day" associated with
+ the volume, as set by a system administrator using
+ the fs setvol command
+
+ - the volume's maximum size quota, in kilobyte
+ blocks
+
+ - its current size, in kilobyte blocks
+
+ - the number of kilobyte blocks still available on
+ the disk partition that houses the volume and the
+ partition's total size
+
+EXAMPLES
+
+ The following shows the output for the volume user.smith
+ (and the partition housing it) in the Transarc Corporation
+ cell:
+
+ % fs exa /afs/transarc.com/usr/smith
+ Volume status for vid = 50489902 named user.smith
+ Current maximum quota is 15000
+ Current blocks used are 5073
+ The partition has 46383 blocks available out of 333305
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs listquota
+
+ fs quota
+
+ fs setquota
--- /dev/null
+fs exportafs AFS Commands fs exportafs
+
+
+NAME
+
+ fs exportafs -- report or set whether machine can export
+
+ AFS to clients of alternate file
+ systems.
+
+
+ fs exportafs -type <exporter name> [-state <'on' or
+ 'off'>] [-noconvert] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs exp -t <exporter name> [-s <'on' or 'off'>] [-n] [-h]
+
+DESCRIPTION
+
+ This command performs one of the following, depending on
+ whether the issuer provides the -state argument:
+
+ - It sets whether the machine is accessible as a
+ server of the non-AFS file system exporter name,
+ able to be mounted by clients of that file system.
+
+ - It reports on the current status of the machine.
+
+ The command's -noconvert flag can be used to indicate
+ whether mode bits of exported directories and files are to
+ be converted. By default, the group and other mode bits of
+ exported directories and files are changed to match the user
+ bits.
+
+ARGUMENTS
+
+ -type names the alternate file system for which the setting
+ is to be changed or reported. Only lowercase letters
+ are acceptable. The only legal value is nfs.
+
+ -state
+ controls whether the workstation is accessible as a
+ server of the non-AFS file system or not. The legal
+ values are on, which enables the workstation as a
+ server, and off, which makes it inaccessible as a
+ server. If the issuer omits this argument, the output
+ reports the current setting.
+
+ -noconvert
+ determines whether the group and other bits on
+ exported files and directories are converted to match
+ the user bits. By default, the group and other bits
+ on exported files and directories are made to match
+ the user bits. Specify this flag to leave the bits as
+ they are in AFS.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+
+
+OUTPUT
+
+ When the -state argument is omitted, the output reports the
+ name of the non-AFS file system and whether the workstation
+ is enabled as a server of it.
+
+EXAMPLES
+
+ The following shows that this machine is enabled as an NFS
+ server (i.e., it is running the AFS/NFS Translator):
+
+ % fs exportafs nfs Exporter type: nfs is currently enabled
+ for AFS
+
+ The following shows that the machine is not enabled as an
+ NFS server:
+
+ % fs exportafs nfs Sorry, the nfs-exporter type is
+ currently not supported on this AFS client
+
+ The following prevents the machine from acting as an NFS
+ server:
+
+ % fs exp nfs off
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged in as "root" in the UNIX file system
+ of the machine on which the command is being issued.
--- /dev/null
+fs flush AFS Commands fs flush
+
+
+NAME
+
+ fs flush -- force Cache Manager to discard a cached
+
+ file/directory.
+
+
+ +
+ fs flush [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs flush [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Forces the Cache Manager to remove each specified directory
+ or file from its caches of data and status information. The
+ result is that the next time data from a flushed directory
+ or file is requested, the Cache Manager contacts the File
+ Server for the most current version, along with a new
+ callback (if necessary) and associated status information.
+ This command does not discard data from application program
+ buffers or data that has been altered in the cache but not
+ yet written back to the central copy maintained by the File
+ Server.
+
+ The fs flushvolume command can be used to flush all data
+ that resides in the same volume as a specified file or
+ directory.
+
+ARGUMENTS
+
+ -path specifies each file or directory to be flushed. In
+ the case of a directory element, only the element
+ itself is flushed, not data cached from files or
+ subdirectories that reside in it. If this argument is
+ omitted, the current directory is flushed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ The following flushes from the cache the file projectnotes
+ in the current working directory and all data from the
+ subdirectory plans:
+
+ % fs flush projectnotes ./plans/*
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs flushvolume
--- /dev/null
+fs flushvolume AFS Commands fs flushvolume
+
+
+NAME
+
+ fs flushvolume -- force Cache Manager to discard any cached
+
+ data from the volume containing
+ specified file/directory.
+
+
+ +
+ fs flushvolume [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs flushv [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Forces the Cache Manager to remove cached data (but not the
+ cached status information) for all files and directories
+ that reside in the same volume as each specified directory
+ or file. The result is that the next time the Cache Manager
+ needs anything from a flushed volume, it contacts the File
+ Server for the most current version, along with a new
+ callback (if necessary). This command does not discard data
+ from application program buffers or data that has been
+ altered in the cache but not yet written back to the central
+ copy maintained by the File Server.
+
+ The fs flush command can be used to flush individual files
+ and directories.
+
+ARGUMENTS
+
+ -path specifies one file or directory from each volume that
+ the Cache Manager is to flush completely from its
+ cache. If this argument is omitted, all data from the
+ volume that contains the current directory is flushed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ The following flushes from the cache all data that comes
+ from the volume that contains the current working directory
+ and the directory reports at the same level in the file
+ tree:
+
+ % fs flushv . ../reports
+
+PRIVILEGE REQUIRED
+
+ None.
+
+
+
+MORE INFORMATION
+
+ fs flush
--- /dev/null
+fs getcacheparms AFS Commands fs getcacheparms
+
+
+NAME
+
+ fs getcacheparms -- show current size of data cache and
+
+ amount being used.
+
+
+ fs getcacheparms [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs getca [-h]
+
+DESCRIPTION
+
+ Displays the current size of the cache that the Cache
+ Manager has at its disposal, and the amount it is using at
+ the moment the command is issued. The command works both on
+ machines using a memory cache and on machines using a disk
+ cache.
+
+ This information comes from the kernel of the workstation on
+ which the command is issued. On machines using a disk
+ cache, the current cache size may disagree with the default
+ setting specified in the file /usr/vice/etc/cacheinfo, if
+ someone has set it with the fs setcachesize command.
+
+ARGUMENTS
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ The output is of the form
+
+ AFS using <amount> of the cache's available <size> 1
+ blocks.
+
+ where <amount> is the number of 1K byte blocks the Cache
+ Manager is currently using, and <size> the total number of
+ blocks available to the Cache Manager (the current cache
+ size).
+
+EXAMPLES
+
+ The following shows the output on a machine with a 25000
+ kilobyte cache.
+
+ % fs getca
+ AFS using 22876 of the cache's available 25000 1K by
+ blocks.
+
+
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs setcachesize
--- /dev/null
+fs getcellstatus AFS Commands fs getcellstatus
+
+
+NAME
+
+ fs getcellstatus -- show whether workstation can run setuid
+
+ programs
+ from specified cell(s), and whether cell
+ is using the old VLDB.
+
+
+ +
+ fs getcellstatus -cell <cell name> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs getce -c <cell name> [-h]
+
+DESCRIPTION
+
+ Reports whether the workstation allows programs fetched from
+ the specified cell(s) to run with setuid privilege. System
+ administrators set a cell's setuid status on a
+ per-workstation basis with the fs setcell command.
+
+ If a cell is using the AFS 2.0 method for tracking volume
+ location rather than the VLDB, the output reports this also
+ (see the OUTPUT section).
+
+ARGUMENTS
+
+ -cell names the cell(s) for which setuid status is desired.
+ Provide the complete Internet-style name for each cell
+ (unlike the common -cell argument in other command
+ suites, it is not possible to abbreviate this one).
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ Possible output values are
+
+ - no setuid allowed, indicating that programs from
+ the cell may not run with setuid privilege.
+
+ - setuid allowed, indicating that programs from the
+ cell may run with setuid privilege.
+
+ - using old VLDB, indicating that the cell is still
+ using the AFS 2.0 volume location method.
+
+
+
+EXAMPLES
+
+ The following indicates that programs from the cell
+ oldcell.com may not run with setuid privilege and that the
+ cell is still using the old volume location method:
+
+ % fs getce oldcell.com Cell oldcell.com status: no setuid
+ allowed, using old VLDB
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs setcell
--- /dev/null
+fs getserverprefs AFS Commands fs getserverprefs
+
+
+NAME
+
+ fs getserverprefs -- display Cache Manager's preferences
+
+ for file server machines.
+
+
+ fs getserverprefs [-file <dir/file path>] [-numeric]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs gets [-f <dir/file path>] [-n] [-h]
+
+ fs gp [-f <dir/file path>] [-n] [-h]
+
+DESCRIPTION
+
+ Displays the Cache Manager's preferences for file server
+ machines. A preference consists of the name or IP address
+ of a file server machine followed by its "rank." The rank
+ is a positive integer in the range from 1 to 65,534.
+
+ A file server machine's rank determines the Cache Manager's
+ preference for selecting it when the Cache Manager must
+ access a ReadOnly replica that resides on it. The Cache
+ Manager compares the rank of the server machine with the
+ ranks of other server machines that house the replica. It
+ then attempts to access the replica on the server machine
+ that has the lowest integer rank.
+
+ If it cannot access the replica on the machine with the
+ lowest rank (possibly because the machine or the network on
+ which the machine is located is down), the Cache Manager
+ attempts to access the replica from the server machine with
+ the next lowest rank. It continues in this manner until it
+ either accesses the replica or determines that all of the
+ file server machines on which the replica resides are
+ unavailable.
+
+ The Cache Manager records addresses and ranks for all local
+ file server machines. It also records addresses and ranks
+ for all foreign file server machines that house a volume it
+ has accessed or for which a rank has been specified with the
+ fs setserverprefs command. It stores the addresses and
+ ranks in the kernel of the client machine.
+
+ Information displayed with this command is sent to stdout by
+ default. The -file switch can be used to direct the output
+ to a file.
+
+
+
+ARGUMENTS
+
+ -file specifies the pathname of a file to which
+ the file server machine names and ranks are
+ to be written. Omit this switch to display
+ the machine names and ranks on stdout.
+
+ -numeric specifies that the IP addresses of the file
+ server machines are to be displayed. Omit
+ this flag to display the names of the file
+ server machines. Because including this
+ flag skips the resolution of IP addresses to
+ machine names, information is displayed more
+ quickly than if the option is omitted.
+ (This flag is especially useful if the
+ output is intended to be used as input to
+ the fs setserverprefs command, in which case
+ it does not matter whether names or
+ addresses are used.)
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ The output displays a separate line for each file server
+ machine that has a rank in the kernel of the machine on
+ which the command is issued. Each line displays the name of
+ a file server machine followed by its rank, as follows:
+
+ first machine name rank
+ second machine name rank
+ . . . . . .
+
+ If the -numeric flag is included with the command, the
+ output displays the IP addresses of the file server machines
+ instead of their names. The address of a machine is also
+ displayed if the Cache Manager cannot resolve a file server
+ machine's name based on the machine's address at the time
+ the command is issued.
+
+EXAMPLES
+
+ The following displays the preferences (the list of file
+ server machines and their respective ranks) associated with
+ a Cache Manager. The output in the example truncates the
+ complete list of server machine names and ranks. Note that
+ the IP addresses, not the names, of some machines are
+ displayed because their addresses cannot be resolved.
+
+
+
+ % fs gets
+ fs5.transarc.com 20000
+ fs1.transarc.com 40000
+ fs3.transarc.com 20001
+ fs4.transarc.com 40001
+ fs2.transarc.com 25000
+ 121.86.3.37 40002
+ fserver1.andrew.cmu.edu 40000
+ 121.86.3.34 40001
+ server1.athena.mit.edu 1000
+ . . . . . . .
+
+ The following displays the same Cache Manager's preferences,
+ but the -numeric flag is included to display only the IP
+ addresses of the file server machines, not their names. The
+ example output again truncates the complete list of server
+ machine names and ranks.
+
+ % fs gets -n
+ 128.21.6.214 20000
+ 128.2.11.9 40000
+ 128.2.11.12 20001
+ 128.2.11.13 40001
+ 128.2.11.11 25000
+ 121.86.3.37 40002
+ 121.86.3.31 40000
+ 121.86.3.34 40001
+ 145.2.50.121 1000
+ . . . . .
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs setserverprefs
--- /dev/null
+fs help AFS Commands fs help
+
+
+NAME
+
+ fs help -- show syntax of specified fs commands or list
+
+ functional descriptions of all fs
+ commands.
+
+
+ +
+ fs help [-topic <help string> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs h [-t <help string> ] [-h]
+
+DESCRIPTION
+
+ Displays the first line (name and short description) of
+ every fs command's online help entry if no help string is
+ provided. For each operation code specified with -topic, it
+ outputs the entire help entry. See the OUTPUT section.
+
+ARGUMENTS
+
+ -topic specifies the operation codes for which
+ syntax is to be provided. If the issuer
+ omits this argument, the output instead
+ provides a short description of all fs
+ commands.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ The online help entry for each fs command consists of two or
+ three lines:
+
+ - The first line names the command and briefly
+ describes what it does.
+
+ - The second line displays any aliases the command
+ has (this line does not appear for every command).
+
+ - The final line, which begins with "Usage:", lists
+ the command's arguments and flags in the
+ prescribed order. Online help entries use the
+ same symbols (for example, brackets) as the
+ command definitions in this manual. For an
+ explanation of their meaning, see page v of the
+ introductory About This Manual chapter.
+
+
+
+EXAMPLES
+
+ The following displays the online help entry for the
+ fs setacl command:
+
+ % fs help setacl
+ fs setacl: set access control list
+ aliases: sa
+ +
+ Usage: fs setacl -dir <directory>
+ +
+ -acl <access list entries> [-clear] [-negative] [-help]
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs apropos
--- /dev/null
+fs listacl AFS Commands fs listacl
+
+
+NAME
+
+ fs listacl -- show access control list.
+
+
+ +
+ fs listacl [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs la [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Displays the access control list (ACL) associated with each
+ directory. It is legal to provide a filename rather than a
+ directory name for directory, in which case the ACL of the
+ file's parent directory is displayed (because it is not
+ possible to set an ACL for an individual file, the file is
+ inheriting the ACL from its parent directory). Omit this
+ switch to display the ACL of the current working directory.
+
+ Users who possess the ADMINISTER right on an ACL may change
+ the ACL with the fs setacl command or copy the ACL from a
+ different directory to it with the fs copyacl command.
+
+WARNING
+
+ The appearance of a user/group on the Negative rights list
+ does not guarantee that the person is denied those rights.
+ If system:anyuser is granted any rights on the Normal rights
+ list, a user need only unlog to obtain those rights.
+
+ARGUMENTS
+
+ -path specifies each file and/or directory for
+ which to display the associated ACL. If
+ this argument is omitted, the output
+ displays the ACL associated with the current
+ working directory. If it is a filename, the
+ ACL displayed is associated with the file's
+ parent directory.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ The first line of the output names the directory associated
+ with the access control list. If the issuer used shorthand
+ notation (such as "." for the current directory) when
+ indicating the directory, it may appear here rather than the
+ full pathname of the directory.
+
+
+
+ The "Normal rights:" header indicates the list of users who
+ have normal rights to the directory. Each following line
+ lists a user/group name and the set of rights the user/group
+ may exercise. The possible rights and their meanings are
+
+
+ - r = READ the contents of files in the directory
+
+ - w = WRITE (modify) the contents of files in the
+ directory
+
+ - l = LOOKUP status information about the files in
+ the directory
+
+ - d = DELETE files from the directory
+
+ - i = INSERT new files into the directory
+
+ - k = LOCK; set read or write locks on the files in
+ the directory
+
+ - a = ADMINISTER; change the rights on the access
+ control list
+
+ - A, B, C, D, E, F, G, H; by default, these have no
+ meaning to AFS server processes. Administrators
+ and application programs may assign meanings to
+ them and place them on ACLs to control access to
+ the directory's contents in new ways. The letters
+ must be uppercase.
+
+ A "Negative rights:" header may appear next, if any negative
+ rights have been specified for this directory. The format
+ of this list is the same as that of the Normal rights list.
+ The difference is that the user(s)/group(s) listed are
+ denied rather than granted the specified rights.
+
+EXAMPLES
+
+ The following displays the ACL associated with user pat's
+ home directory and its private subdirectory when the
+ fs listacl command is issued in the home directory:
+
+ % fs la . private Access list for . is Normal rights:
+ system:authuser rl pat rlidwka pat:friends rlid
+ Negative rights: smith rlidwka
+
+ Access list for private is Normal rights: pat rlidwka
+
+
+
+PRIVILEGE REQUIRED
+
+ To issue this command with a directory name argument, issuer
+ must have the LOOKUP right on the directory's ACL. To issue
+ command with a filename argument, the issuer must have both
+ the LOOKUP and READ rights on the ACL of the file's parent
+ directory.
+
+MORE INFORMATION
+
+ fs cleanacl
+
+ fs copyacl
+
+ fs setacl
--- /dev/null
+fs listcells AFS Commands fs listcells
+
+
+NAME
+
+ fs listcells -- show database server machines in cell(s)
+
+ known to Cache Manager.
+
+
+ fs listcells [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs listc [-h]
+
+DESCRIPTION
+
+ Formats and displays the Cache Manager's kernel-resident
+ list of the database server machines in its home cell and
+ foreign cells.
+
+ At each reboot of the workstation, the Cache Manager copies
+ the contents of /usr/vice/etc/CellServDB into the kernel. It
+ is possible to modify the kernel-resident list between
+ reboots using fs newcell.
+
+ARGUMENTS
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output contains a line for each cell for which the
+ kernel has a list of database server machines. The cell
+ name is followed by a list of its database server machines
+ (referred to as "hosts").
+
+ The format of each machine name (name in uppercase, name in
+ lowercase, or Internet address in four-field decimal form)
+ depends on the state of the local cell's name server at the
+ time the command is issued.
+
+EXAMPLES
+
+ The following shows output for several cells as
+ illustrations of the different formats for machine names:
+
+ % fs listc
+ Cell transarc.com on hosts fs1.transarc.com fs2.transarc
+ Cell andrew.cmu.edu on hosts VICE11.FS.ANDREW.CMU.EDU
+ VICE2.FS.ANDREW.CMU.EDU VICE7.FS.ANDREW.CMU.EDU.
+ Cell athena.mit.edu on hosts 18.80.0.2 orf.mit.edu
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs newcell
--- /dev/null
+fs listquota AFS Commands fs listquota
+
+
+NAME
+
+ fs listquota -- show quota information for the volume
+
+ containing a file/directory.
+
+
+ +
+ fs listquota [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs lq [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Displays information about the size and quota of the volume
+ containing each specified directory or file. See the OUTPUT
+ section for a complete explanation of the information
+ provided.
+
+ARGUMENTS
+
+ -path specifies each file and/or directory for which
+ information about the host volume is desired. If the
+ issuer omits this argument, the current directory is
+ assumed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output reports the following information about each
+ volume that contains a specified directory or file:
+
+ - the name of the volume
+
+ - its maximum size quota, in kilobytes
+
+ - its current size, in kilobytes
+
+ - the percentage of its quota that its current size
+ represents
+
+ - the percentage of the volume's disk partition that
+ is full. This is usually unrelated to how much of
+ the user's quota is used, since it depends on all
+ the volumes on the partition. A large value may
+ nevertheless prevent a user from being able to
+ store more data on the partition.
+
+
+
+EXAMPLES
+
+ The following shows the output for the volume user.smith in
+ the Transarc Corporation cell:
+
+ % fs lq /afs/transarc.com/usr/smith
+ Volume Name Quota Used % Used Partition
+ user.smith 15000 5071 34% 86%
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs diskfree
+
+ fs examine
+
+ fs quota
+
+ fs setquota
+
+ fs setvol
--- /dev/null
+fs lsmount AFS Commands fs lsmount
+
+
+NAME
+
+ fs lsmount -- show volume for which directory is a mount
+
+ point.
+
+
+ +
+ fs lsmount -dir <directory> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs ls -d <directory> [-h]
+
+DESCRIPTION
+
+ Outputs the name of the volume(s) for which each directory
+ is the root directory. If directory is not a mount point or
+ is not in AFS, an error message appears.
+
+ The association between directory and a volume name was
+ created with the fs mkmount command.
+
+ARGUMENTS
+
+ -dir names the directory that serves as a mount point for a
+ volume. The last element in the pathname that the
+ issuer provides must be an actual name, not "dot" (.)
+ or "dot dot" (. .), which the fs command interpreter
+ does not understand in this case.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output is of the form:
+
+ 'directory' is a mount point for volume 'volume name'
+
+ A hash sign (#) preceding volume name indicates that
+ directory is a regular mount point.
+
+ A percent sign (%) preceding volume name indicates that
+ directory is a ReadWrite mount point.
+
+ If directory is a cellular mount point, then a cell name and
+ colon precede volume name in addition to the hash sign or
+ percent sign.
+
+
+
+ If directory is not a mount point, the output reads:
+
+ 'directory' is not a mount point.
+
+EXAMPLES
+
+ The following shows the mount point for the home directory
+ of user smith in the Transarc Corporation cell:
+
+ % fs ls /afs/transarc.com/usr/smith
+ '/afs/transarc.com/usr/smith' is a mount point for
+ volume '#user.smith'
+
+ The following shows both the regular and ReadWrite mount
+ points for the Transarc Corporation cell's root.cell volume.
+
+ % fs ls /afs/transarc.com
+ '/afs/transarc.com' is a mount point for volume '#ro
+
+ % fs ls /afs/.transarc.com
+ '/afs/.transarc.com' is a mount point for volume
+ '%root.cell'
+
+ The following shows a cellular mount point: the Andrew
+ cell's root.cell volume as mounted in the Transarc
+ Corporation cell's tree.
+
+ % fs ls /afs/andrew.cmu.edu
+ '/afs/andrew.cmu.edu' is a mount point for volume
+ '#andrew.cmu.edu:root.cell'
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs mkmount fs rmmount
--- /dev/null
+fs mkmount AFS Commands fs mkmount
+
+
+NAME
+
+ fs mkmount -- create a mount point for a volume.
+
+
+ fs mkmount -dir <directory> -vol <volume name> [-cell <cell
+ name>] [-rw] [-fast] [-root] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs mk -d <directory> -v <volume name> [-c <cell name>]
+ [-rw] [-f] [-ro] [-h]
+
+DESCRIPTION
+
+ Creates a mount point called directory for the volume volume
+ name. The volume's root directory is also named directory.
+ Mount points look and act just like standard UNIX directory
+ structures, because when the Cache Manager encounters a
+ mount point directory in a pathname, it knows to look in the
+ indicated volume for the elements listed under directory.
+
+ It is possible, although not recommended, to create more
+ than one mount point to a volume.
+
+ Types of mount points
+
+ There are several types of mount points, because mount
+ points can vary along three dimensions. The following will
+ discuss the three dimensions in turn, explaining how they
+ affect the Cache Manager's interpretation of the mount
+ point.
+
+ Dimension 1: Volume Type
+
+ The first dimension concerns which type of volume
+ (ReadWrite, ReadOnly or Backup) is named in the mount point.
+ ReadOnly and Backup volumes are distinguished by a .readonly
+ or .backup extension, respectively. When a mount point
+ names a volume with either extension, the Cache Manager
+ accesses the specified volume only, ignoring Dimension 2
+ (the mount point's type). In other words, the Cache Manager
+ will never access the ReadWrite version of a volume if the
+ mount point explicitly names the ReadOnly or Backup version.
+ If the named ReadOnly or Backup volume is inaccessible, the
+ Cache Manager reports an error.
+
+ If the volume name does not include a .backup or .readonly
+ extension, then the volume is ReadWrite. The Cache Manager
+ considers Dimension 2.
+
+ Dimension 2: Mount Point Type
+
+ Note: This dimension is relevant only if the volume
+ indicated in the mount point is ReadWrite. Only Dimension 1
+ is relevant if the named volume is ReadOnly or Backup.
+
+ The second dimension concerns whether the mount point itself
+ is "regular" or "ReadWrite":
+
+ - When the Cache Manager encounters a regular mount
+
+
+
+ point (one naming a ReadWrite volume), it tries to
+ access a copy of the volume that is of same type
+ (ReadWrite or ReadOnly) as the volume which houses
+ the mount point. If there is no volume of the
+ same type, it will access the type that is
+ available.
+
+ Almost all mount points are of this type. Its
+ advantage is that the Cache Manager is free to
+ access the most readily available form of the
+ volume. When the Cache Manager starts in a
+ ReadOnly volume, this type of mount point means
+ that it traverses a "ReadOnly path," which can be
+ efficient because no callbacks are necessary.
+
+ The issuer creates a regular mount point by
+ providing only the required -dir and -vol
+ arguments.
+
+ - When the Cache Manager encounters a ReadWrite
+ mount point, it accesses only the ReadWrite
+ version of the indicated volume. (This assumes
+ that the volume does not have a .backup or
+ .readonly extension. Mounting a Backup or
+ ReadOnly volume with a ReadWrite mount point is
+ possible but unnecessary, as the Cache Manager
+ handles those volume types in the same way whether
+ their mount point is regular or ReadWrite. See
+ Dimension 1.)
+
+ A ReadWrite mount point is generally used to mount
+ only one volume in a cell: its root.cell volume at
+ the second level in the file tree, just below
+ /afs. Conventionally, root.cell is also mounted
+ with a regular mount point at the same level. The
+ two mount points are distinguished by the
+ placement of a period at the start of the
+ ReadWrite mount point's name (see the EXAMPLES
+ section). The existence of a ReadWrite mount
+ point for root.cell allows the system
+ administrator to switch onto a "ReadWrite" path
+ and thus be sure he or she is accessing the
+ ReadWrite version of a volume when that is
+ important.
+
+ The issuer creates a ReadWrite mount point by
+ adding the -rw flag.
+
+ Dimension 3: Cellular versus Local
+
+ The third dimension concerns which cell the volume resides
+ in. A cellular mount point indicates to the Cache Manager
+ that the volume resides in a foreign cell (and specifies
+ which one). If the mount point is not cellular, then the
+ Cache Manager assumes that the volume resides in the same
+ cell as the mount point does.
+
+ Normally, cellular mount points are used only at the second
+ level in a cell's file tree (i.e., at the "cell" level just
+ below /afs), to mount the root.cell volumes for foreign
+ cells that are to be visible in the local cell. It is
+
+
+
+ possible to create cellular mount points (mount foreign
+ volumes) at other levels in the tree. Doing so is not
+ recommended, however, as it can make it difficult to
+ determine which cell a given pathname leads to.
+
+ Cellular mount points can be either regular or ReadWrite:
+
+ - A regular cellular mount point not only tells the
+ Cache Manager to cross into a foreign cell, but
+ also to access the ReadOnly version of the
+ indicated volume if possible. The advantage is
+ that the Cache Manager traverses a "ReadOnly path"
+ in the foreign cell, even if the mount point for
+ the indicated volume resides in a ReadWrite
+ volume. This is particularly useful when crossing
+ into foreign cells that are too small to replicate
+ their root.afs volume.
+
+ To create a regular cellular mount point, the
+ issuer uses the -cell argument to specify the cell
+ name, and adds the -root flag.
+
+ - A ReadWrite cellular mount point tells the Cache
+ Manager to cross into a foreign cell and access
+ the ReadWrite version of the volume (assuming that
+ the volume does not have a .backup or .readonly
+ extension). Use of this type of mount point is
+ discouraged, because accessing ReadWrite volumes
+ means the File Server has to issue callbacks, an
+ extra load it is not fair to impose from outside
+ the cell. In general, only a cell's own
+ administrators need to access the ReadWrite
+ version of a volume.
+
+ To create a ReadWrite cellular mount point, the
+ issuer uses the -cell argument to specify the cell
+ name, and adds both the -root and -rw flags.
+ Because this is not recommended, no example of it
+ appears below.
+
+ Mounting foreign volumes in foreign cells
+
+ In addition to mounting volumes in the local cell, the
+ fs mkmount allows a user who possesses the necessary access
+ rights in a foreign cell to create a regular, non-cellular
+ mount point in a foreign cell's file tree while working on a
+ machine in his or her local cell. In other words, the
+ issuer can mount a volume from a foreign cell in that cell's
+ file space as though he or she were working at a machine in
+ that cell.
+
+ To mount a foreign volume in foreign cell, specify the cell
+ name with -cell, but do not use the -root flag.
+
+
+
+ Distinguishing the types of mount points
+
+ The output of fs lsmount uses various symbols to distinguish
+ the different types of mount points. See the Output section
+ of that command's description.
+
+ARGUMENTS
+
+ -dir names the directory to be created as a mount point to
+ the named volume. It should not already exist. If
+ the issuer does not specify a pathname, the mount
+ point is created as a subdirectory of the current
+ working directory.
+
+ -vol names the volume to be mounted. Add the .readonly or
+ .backup extension if appropriate. The volumeID is
+ also acceptable.
+
+ Note: When creating a cellular mount point, do not
+ specify the cell name as part of this argument, as was
+ necessary in previous versions of AFS that did not
+ have the -root flag. Instead, include the -root flag
+ and use the -cell argument to specify the cell name;
+ the command interpreter will automatically prepend the
+ cell name to the volume name, separating them with a
+ colon.
+
+ -cell names the cell in which the volume resides. When
+ creating a cellular mount point, combine this argument
+ with the -root flag. When mounting a foreign volume
+ in a foreign cell, use this argument alone.
+
+ -rw designates the mount point as ReadWrite, which forces
+ the Cache Manager to access only the ReadWrite copy of
+ a volume that does not have a .backup or .readonly
+ extension. Without this flag, the mount point is
+ regular.
+
+ -fast indicates that the VL Server should not check that
+ there is a VLDB entry for the volume to be mounted.
+ By default, the VL Server does check and prints a
+ warning message if there is no VLDB entry; the mount
+ point is created in any case.
+
+ -root creates a cellular mount point.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ Note: These examples illustrate only the recommended
+ combinations and use of arguments. The OUTPUT section of
+ fs lsmount's description shows what each mount point looks
+ like.
+
+ The following creates a regular mount point. It mounts
+ user.smith at /afs/transarc.com/usr/smith.
+
+
+
+ % cd /afs/transarc.com/usr % fs mk smith user.smith
+
+
+
+ The following creates both a ReadWrite and regular mount
+ point for the Transarc Corporation cell's root.cell volume,
+ in that cell's file tree. It follows the convention of
+ putting a period at the beginning of the ReadWrite mount
+ point's name.
+
+ % fs mk /afs/transarc.com root.cell % fs mk
+ /afs/.transarc.com root.cell -rw
+
+ The following mounts the root.cell volume belonging to
+ Carnegie Mellon University's Andrew cell in the Transarc
+ Corporation cell's file tree, creating a regular, cellular
+ mount point called andrew.cmu.edu. When a Transarc
+ Corporation Cache Manager encounters this mount point, it
+ will cross into the Andrew cell on a ReadOnly path.
+
+ % fs mk /afs/andrew.cmu.edu root.cell -c andrew.cmu.edu
+ -root
+
+ The following illustrates the creation of a mount point in a
+ foreign cell, using Transarc Corporation's regular cell
+ (transarc.com) as the local cell and its test cell
+ (test.transarc.com) as the foreign cell. Suppose that while
+ working on a machine belonging to the transarc.com cell, a
+ Transarc Corporation user wants to mount a test.transarc.com
+ volume called user.test5 at
+ /afs/test.transarc.com/usr/test5. She has the INSERT and
+ ADMINISTER rights for /afs/test.transarc.com/usr. Note that
+ the effect is just the same as if the issuer were working on
+ a machine belonging to the test.transarc.com cell and
+ omitted the -c test.transarc.com part of the command.
+
+ % cd /afs/test.transarc.com/usr % fs mk test5 user.test5 -c
+ test.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must have INSERT and ADMINISTER access for the
+ directory that is to contain the mount point.
+
+MORE INFORMATION
+
+ fs lsmount fs rmmount
--- /dev/null
+fs monitor AFS Commands fs monitor
+
+
+NAME
+
+ fs monitor -- direct reports on file system activity to
+
+ specified machine, or report current
+ monitoring machine.
+
+
+ fs monitor [-server <host name> or <off>] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs mo [-s <host name> or <off>] [-h]
+
+DESCRIPTION
+
+ Depending on whether the issuer provides the -server
+ argument, and its value when provided:
+
+ EITHER sets where the Cache Manager sends messages about
+ file system activity (including its transactions with the Fi
+
+ OR disables message sending
+
+ OR reports the current destination for messages.
+
+ The messages are of a less technical nature than those
+ generated by the fs debug command. They are at the level of
+ file fetches and stores.
+
+ In order for the messages to be displayed, the specified
+ destination machine must be running a monitoring program
+ that "listens" to the correct UDP socket. If the destination
+ machine is not running such a program, then the messages are
+ lost.
+
+WARNING
+
+ The effect of this command endures even after the issuer
+ logs out. See the EXAMPLE section below.
+
+ Transarc Corporation does not provide a monitoring program
+ appropriate for use with this command, but such a program,
+ called "Console", is available as part of the Andrew Toolkit
+ developed at Carnegie Mellon University's Information
+ Technology Center.
+
+ If no monitoring program is available, it is best to provide
+ a value of off for -server.
+
+
+
+ARGUMENTS
+
+ -server has two legal values: off or a machine name host
+ name.
+
+ If set to off, then the Cache Manager does not
+ generate any reports on its role in file system
+ activities. This setting is recommended if the
+ machine is not running a monitoring program capable
+ of intercepting and displaying the messages
+ produced.
+
+ The issuer may otherwise specify a machine name host
+ name to which the Cache Manager will send messages.
+ The host name must be a complete Internet-style
+ machine name, and a monitoring program should be
+ running on the machine. If no such program is
+ running, the messages will simply be lost.
+
+ If the issuer does not provide this argument, the
+ current monitor setting is displayed.
+
+ -help prints the online help entry for this command. Do
+ not provide any other arguments or flags with this
+ one. See section 3.1 in the Reference Manual for
+ more details.
+
+OUTPUT
+
+ When no arguments are provided, the output will report the
+ name of the machine to which monitoring messages are being
+ sent:
+
+ Using host machine for monitor services.
+
+ If monitoring is disabled, the output reports
+
+ Cache monitoring is currently disabled.
+
+EXAMPLES
+
+ The following shows that monitoring messages are being sent
+ to machineQ.transarc.com.
+
+ % fs mo
+ Using host machineQ.transarc.com for monitor service
+
+ The following sets the machine's monitoring machine to
+ machineB.transarc.com.
+
+ % fs monitor machineB.transarc.com
+ fs: new monitor host set.
+
+ As an example of the "lingering" effect of this command,
+ suppose that a user working on machineA.transarc.com issues
+ the example command, and then logs out. When another user
+ logs on to machineA, he or she will not see any messages
+ about file system activity; instead, users of machineB will
+ continue to see messages from both machineB (their local
+ machine) and machineA (the remote machine). To avoid this,
+ the original user on machineA should issue the fs monitor
+
+
+
+ command again before logging out, specifying host name to be
+ machineA.transarc.com.
+
+PRIVILEGE REQUIRED
+
+ None.
--- /dev/null
+fs newcell AFS Commands fs newcell
+
+
+NAME
+
+ fs newcell -- change list of cell's database server
+
+ machines in kernel.
+
+
+ +
+ fs newcell -name <cell name> -servers <primary servers>
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs n -n <cell name> -s <primary servers> [-h]
+
+DESCRIPTION
+
+ Removes the Cache Manager's kernel-resident list of database
+ server machines for the cell cell name, replacing it with
+ primary servers.
+
+ This command does not make permanent changes in the
+ workstation's /afs/vice/etc/CellServDB file, the contents of
+ which are transferred into the kernel at each reboot. In
+ other words, rebooting the workstation will overwrite the
+ changes made with this command, unless the issuer changes
+ CellServDB in the same way.
+
+ Changes made with this command do appear in the output of
+ fs listcells, since that command consults the in-kernel list
+ rather than CellServDB.
+
+ This command may be used to introduce a completely new cell
+ into the kernel-resident list, but it is not possible to
+ make a cell inaccessible with this command (i.e., remove it
+ from the kernel-resident list by not providing any instances
+ for -server). To do that, the user must alter CellServDB
+ and reboot the machine.
+
+WARNING
+
+ Some commands work correctly only when both CellServDB and
+ the kernel-resident list correctly list a cell's database
+ server machines. The need of such commands for correct
+ information in CellServDB precludes use of this command.
+ The klog command is a prominent example.
+
+ARGUMENTS
+
+ -name is the complete Internet-style name of the cell for
+ which the in-kernel list of database server machines
+ will change. It may be the local cell or a foreign
+ cell.
+
+ -servers
+ names the database server machine(s) for the cell in
+ question. Provide the complete Internet-style
+ machine name for each machine.
+
+ -help prints the online help entry for this command. Do
+
+
+
+ not provide any other arguments or flags with this
+ one. See section 3.1 in the Reference Manual for
+ more details.
+
+EXAMPLES
+
+ The following changes the machine's kernel-resident list of
+ database server machines for the Transarc Corporation cell
+ to include fs1.transarc.com and fs2.transarc.com.
+
+ % fs n transarc.com fs1.transarc.com fs2.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged in as "root" in the UNIX file system
+ of the machine on which the command is being issued.
+
+MORE INFORMATION
+
+ fs listcells
--- /dev/null
+fs quota AFS Commands fs quota
+
+
+NAME
+
+ fs quota -- show percent of quota used for volume
+
+ containing directory/file.
+
+
+ +
+ fs quota [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs q [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Displays the percent of maximum quota currently used by the
+ volume that contains each specified directory or file. This
+ is the least informative but quickest fs command that
+ provides quota information about a volume. The fs examine
+ and fs listquota commands provide more complete information.
+
+ The system administrator may set quota with the fs setquota
+ or fs setvol command.
+
+ARGUMENTS
+
+ -path specifies each file and/or directory for which quota
+ information about the host volume is desired. If the
+ issuer omits this argument, the current directory is
+ assumed.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output reports the percent of quota used. It does not
+ name the host volume.
+
+EXAMPLES
+
+ The following lists the percent quota used of the volume
+ housing the current working directory:
+
+ % fs quota
+ 17% of quota used.
+
+
+
+ The following lists the percent quota used of both the
+ volume housing the current working directory's parent
+ directory and the volume housing the directory named
+ /afs/transarc.com/usr/smith:
+
+ % fs quota .. /afs/transarc.com/usr/smith
+ 43% of quota used.
+ 92% of quota used.
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs examine
+
+ fs listquota
+
+ fs setquota
+
+ fs setvol
--- /dev/null
+fs rmmount AFS Commands fs rmmount
+
+
+NAME
+
+ fs rmmount -- destroy mount point.
+
+
+ +
+ fs rmmount -dir <directory> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs rm -d <directory> [-h]
+
+DESCRIPTION
+
+ Removes the mount point called directory from the file
+ system. The corresponding volume remains in the system, but
+ will be inaccessible if there are no other mount points for
+ it.
+
+ARGUMENTS
+
+ -dir names the mount point to be deleted from the file
+ system. The last element in the pathname that the
+ issuer provides must be an actual name, not "dot" (.)
+ or "dot dot" (. .), which the fs command interpreter
+ does not understand in this case.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ The following removes the mount points jones and terry from
+ the current working directory (assume it is
+ /afs/transarc.com/usr).
+
+ % fs rm jones terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must have DELETE access for the directory containing
+ the mount point.
+
+MORE INFORMATION
+
+ fs lsmount fs mkmount
--- /dev/null
+fs setacl AFS Commands fs setacl
+
+
+NAME
+
+ fs setacl -- sets access control list for a directory.
+
+
+ + +
+ fs setacl -dir <directory> -acl <access list entries>
+ [-clear]
+ [-negative] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ + +
+ fs sa -d <directory> -a <access list entries> [-c] [-n]
+ [-h]
+
+DESCRIPTION
+
+ Puts the specified access list entries on the access control
+ list (ACL) of each specified directory.
+
+WARNING
+
+ If the ACL already grants certain rights to a user or group,
+ the rights specified with access list entries replace them,
+ rather than just being added to them.
+
+ Setting negative rights is generally unnecessary and not
+ recommended. Simply omitting a user or group from the
+ Normal rights list is normally adequate to prevent access.
+ In particular, note that it is futile to deny rights that
+ are granted to system:anyuser on the same ACL; all the user
+ needs to do is issue the unlog command to receive the denied
+ rights.
+
+ARGUMENTS
+
+ -dir specifies each directory for which the
+ access control list is to change.
+ Abbreviated pathnames are interpreted
+ relative to the directory in which the
+ command is issued.
+
+ -acl defines a list of one or more entries, each
+ of which specifies
+
+ - a user name or group name (letters
+ all lowercase)
+
+ - the access right(s) to be
+ associated with the user/group
+
+ in that order, separated by a space. This
+ argument is unusual in requiring two parts
+ for each instance. The accepted
+ abbreviation of each right and the meaning
+ of the right follows:
+
+ r READ. Allows the possessor to read the
+ contents of files in the directory and
+ to "stat" (issue ls -l for) file and
+
+
+
+ subdirectory elements in the directory.
+
+ w WRITE. Allows the possessor to modify
+ the contents of files in the directory
+ and to change their UNIX mode bits with
+ chmod.
+
+ l LOOKUP. Allows the possessor to list
+ the names of files and subdirectories
+ in the directory (for example, by
+ issuing ls). The possessor may "stat"
+ (issue ls -l for) the directory itself
+ (but not for files and subdirectories
+ in it) and may examine the directory's
+ ACL.
+
+ d DELETE. Allows the possessor to remove
+ files from the directory.
+
+ i INSERT. Allows the possessor to create
+ new files in the directory or move
+ existing files into it.
+
+ k LOCK. Allows the possessor to run
+ programs that need to issue the "flock"
+ system call on files in the directory.
+
+ a ADMINISTER. Allows the possessor to
+ change the directory's ACL.
+
+ A, B, C, D, E, F, G, H; by default, these
+ have no meaning to AFS server
+ processes. Administrators and
+ application programs may assign
+ meanings to them and place them on ACLs
+ to control access to the directory's
+ contents in new ways. The letters must
+ be uppercase.
+
+ all all seven standard rights (rlidwka).
+
+ none no rights. Removes the user/group from
+ the ACL, but may not guarantee they
+ have no rights if they belong to groups
+ that remain on the ACL.
+
+ read both r and l.
+
+ write
+ all rights except ADMINISTER (rlidwk).
+
+ It is legal to mix the individual letters
+ and the words within access list entries,
+ but not within an individual pairing of
+ user/group and rights.
+
+ -clear removes all existing entries on each access
+ control list before placing access list
+ entries on it. This should be used with
+ caution: if access list entries does not
+ grant all rights to the owner of the
+
+
+
+ directory, it can become awkward for the
+ owner to access items in the directory. In
+ particular, not having the LOOKUP right
+ makes it impossible to resolve the "dot" ( .
+ ) and "dot dot" ( . . ) shorthand from
+ within the directory.
+
+ -negative puts the specified access list entries in
+ the Negative rights section of each access
+ control list. The user/group is thus
+ explicitly denied the indicated rights, even
+ if entries on the accompanying Normal rights
+ section of the access control list grant
+ them rights. However, it is possible to
+ unlog to obtain rights granted to
+ system:anyuser on the Normal rights section
+ of the same ACL; see the WARNING above.
+
+ This flag affects all directories and access
+ list entries specified. Its use is not
+ recommended; see the WARNING section above.
+ If the issuer omits this flag, the access
+ list entries go into the Normal rights
+ section of the access control list.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+EXAMPLES
+
+ The following example adds two entries to the Normal rights
+ part of the current working directory's ACL: the first entry
+ grants READ and LOOKUP rights to pat:friends, while the
+ other (using the write shorthand) gives all rights except
+ ADMINISTER to smith.
+
+ % fs sa . pat:friends rl smith write
+
+ The following shows the effect of the -clear flag on the ACL
+ of the subdirectory reports by showing the ACL before and
+ after the command is issued:
+
+ % fs la reports Access list for reports is Normal rights:
+ system:authuser rl pat:friends rlid smith rlidwk
+ pat rlidwka Negative rights: terry rl
+
+ % fs sa -clear reports pat all smith write system:anyuser rl
+ % fs la reports Access list for reports is Normal rights:
+ system:anyuser rl smith rlidwk pat rlidwka
+
+
+
+ The following shows how the -dir and -acl switches are
+ necessary when more than one directory is specified. The
+ new entry granting READ, LOOKUP, and INSERT rights to
+ pat:friends is added to the ACL for both the current
+ directory and its public subdirectory.
+
+ % fs sa -d . public -a pat:friends rli
+
+PRIVILEGE REQUIRED
+
+ Issuer must have ADMINISTER rights to the directory; the
+ directory's owner and members of system:administrators
+ always do.
+
+MORE INFORMATION
+
+ fs copyacl
+
+ fs listacl
--- /dev/null
+fs setcachesize AFS Commands fs setcachesize
+
+
+NAME
+
+ fs setcachesize -- set size of disk cache.
+
+
+ fs setcachesize [-blocks <size in 1K byte blocks>] [-reset]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs setca [-b <size in 1K byte blocks>] [-r] [-h]
+
+ fs cachesize [-b <size in 1K byte blocks>] [-r] [-h]
+
+DESCRIPTION
+
+ On machines using a disk cache, changes the amount of local
+ disk space that the Cache Manager may use for its data
+ cache. Specify the number in kilobyte blocks. This command
+ is not operative on machines using memory caching.
+
+ To return the cache size to the default value specified in
+ /usr/vice/etc/cacheinfo on the client's local disk, specify
+ 0 as the number of kilobyte blocks. The cacheinfo file is
+ human-readable and visible with the cat command. The third
+ and final field is the number of kilobyte blocks allocated
+ to the cache at reboot. The chapter in the AFS System
+ Administrator's Guide on client machine configuration
+ further describes the contents of cacheinfo.
+
+ To return the cache size to the value set when the machine
+ was last booted, use the -reset flag instead of the -blocks
+ argument. This is normally the amount specified in
+ cacheinfo, unless the -blocks argument was used on afsd to
+ override the cacheinfo value.
+
+ The fs getcacheparms command displays the current actual
+ cache size and the amount of space in use, both for disk and
+ memory caches.
+
+WARNINGS
+
+ This command is not operative on machines using memory
+ caching, and will result in an error message.
+
+ On machines using a disk cache, do not set the cache size to
+ exceed 90% of the actual disk space available for the cache
+ directory. The cache implementation itself requires a small
+ amount of room on the partition.
+
+ARGUMENTS
+
+ -blocks
+ specifies the number of 1 kilobyte blocks the Cache
+ Manager may devote to the cache. Specifying a value
+ of "0" sets cache size to the default specified in
+ cacheinfo. This implies that the smallest possible
+ cache size is 1 kilobyte, not 0.
+
+ -reset
+ returns the cache size to the value set when the
+
+
+
+ machine was last booted. This agrees with the value
+ in cacheinfo unless the -blocks argument was used on
+ afsd.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ The following sets the disk cache size to 25000 kilobyte
+ blocks.
+
+ % fs setca 25000
+
+ Both of the following reset the disk cache size to the value
+ in cacheinfo, assuming that the -blocks argument on afsd was
+ not used.
+
+ % fs setcachesize 0 % fs setca -r
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged in as "root" in the UNIX file system
+ of the machine on which the command is being issued.
+
+MORE INFORMATION
+
+ fs getcacheparms
--- /dev/null
+fs setcell AFS Commands fs setcell
+
+
+NAME
+
+ fs setcell -- allow or disallow running of setuid programs
+
+ from specified cells.
+
+
+ +
+ fs setcell -cell <cell name> [-suid] [-nosuid] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs setce -c <cell name> [-s] [-n] [-h]
+
+DESCRIPTION
+
+ Determines whether the workstation allows programs whose
+ binary files reside in the indicated cells to execute with
+ setuid privilege. By default, programs originating in the
+ local cell (as determined by /usr/vice/etc/ThisCell) may run
+ with setuid privilege, but programs originating in foreign
+ cells may not. Use the fs getcellstatus command to displays
+ a cell's current status in this respect.
+
+ Include the -suid flag with the command to allow programs
+ from the specified cells to execute with setuid privilege;
+ include the -nosuid flag with the command to prohibit
+ programs from the specified cells from executing with setuid
+ privilege. Use either the -suid flag or the -nosuid flag.
+ Omit both flags to prevent programs from the specified cells
+ from executing with setuid privilege.
+
+ARGUMENTS
+
+ -cell names each cell from which to allow or
+ disallow programs to execute with setuid
+ privilege. Provide the complete Internet-
+ style cell name of each cell (unlike the
+ -cell argument common to many commands, the
+ cell argument of this command does not
+ accept abbreviated cell names).
+
+ -suid allows programs from cell name to execute
+ with setuid privilege. Provide it or
+ provide -nosuid. Omit both flags to prevent
+ programs from cell name from executing with
+ setuid privilege.
+
+ -nosuid prevents programs from cell name from
+ executing with setuid privilege. Provide it
+ or provide -suid. Omit both flags to
+ prevent programs from cell name from
+ executing with setuid privilege.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+EXAMPLES
+
+
+
+ The following enables programs whose binary files reside in
+ the Transarc Cell to execute with setuid privilege in the
+ local cell:
+
+ % fs setc transarc.com -s
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged in as "root" in the UNIX file system
+ of the machine on which the command is issued.
+
+MORE INFORMATION
+
+ fs getcellstatus
--- /dev/null
+fs setquota AFS Commands fs setquota
+
+
+NAME
+
+ fs setquota -- sets maximum quota for volume containing
+
+ specified directory.
+
+
+ fs setquota [-path <dir/file path>] -max <max quota in
+ kbytes> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs sq [-p <dir/file path>] -m <max quota in kbytes> [-h]
+
+DESCRIPTION
+
+ Sets the maximum size quota for the volume that contains the
+ specified directory or file. The fs examine and fs
+ listquota commands show the current maximum quota. The fs
+ quota command shows the percent of maximum quota used.
+
+ The fs setvol command can be used to set the quota on
+ multiple volumes at once. It can also be used to create
+ messages associated with the volumes.
+
+ARGUMENTS
+
+ -path names the directory or file for which quota
+ on the host volume is to be set. If this
+ argument is omitted, the current working
+ directory is used; in this case, the -max
+ switch must be used.
+
+ -max specifies the maximum amount of disk space
+ the volume can use. Express it in kilobyte
+ blocks (a value of 1024 is one megabyte). A
+ value of 0 grants an unlimited quota, but
+ the size of the disk partition that houses
+ the volume places an absolute limit on the
+ volume's maximum size.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+EXAMPLES
+
+ The following imposes a maximum quota of 3000 kilobytes on
+ the volume that houses the directory
+ /afs/transarc.com/usr/smith:
+
+ % fs sq /afs/transarc.com/usr/smith 3000
+
+PRIVILEGE REQUIRED
+
+ Issuer must belong to the system:administrators group in the
+ Protection Database.
+
+MORE INFORMATION
+
+
+
+ fs examine
+
+ fs listquota
+
+ fs quota
+
+ fs setvol
--- /dev/null
+fs setserverprefs AFS Commands fs setserverprefs
+
+
+NAME
+
+ fs setserverprefs -- set Cache Manager's preferences for
+
+ file server machines.
+
+
+ +
+ fs setserverprefs [-servers <machine name and rank> ]
+ [-file <dir/file path>] [-stdin] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs sets [-se <machine name and rank> ] [-f <dir/file
+ path>]
+ [-st] [-h]
+ +
+ fs sp [-se <machine name and rank> ] [-f <dir/file path>]
+ [-st] [-h]
+
+DESCRIPTION
+
+ Sets the Cache Manager's preference for one or more file
+ server machines. Each Cache Manager stores a table of file
+ server machines and their respective "ranks." A file server
+ machine's rank is an integer in the range from 1 to 65,534
+ that determines the Cache Manager's preference for selecting
+ the server machine when the Cache Manager must access a
+ ReadOnly replica that resides on it. Ranks bias the Cache
+ Manager to prefer to access replicas on "near" server
+ machines rather than those on "distant" server machines.
+
+ When the Cache Manager needs to access a ReadOnly replica,
+ it first contacts the Volume Location (VL) Server to
+ ascertain the names of the file server machines on which the
+ replica resides. It then checks its internal table to
+ determine the rank associated with each of the file server
+ machines. After comparing the ranks of the machines, it
+ attempts to access the replica on the server machine that
+ has the lowest integer rank.
+
+ If the Cache Manager cannot access the replica on the
+ machine with the lowest rank (possibly because of a server
+ process, machine, or network outage), it attempts to access
+ the replica on the machine with the next lowest rank. It
+ continues in this way until it either accesses the replica
+ or determines that all of the file server machines on which
+ the replica is housed are unavailable.
+
+ Each time it is initialized with the afsd command, the Cache
+ Manager assigns preferences to any database server machines
+ listed in the local /usr/vice/etc/CellServDB file that are
+ also file server machines. It stores the preferences as
+ machine IP addresses and associated ranks in the kernel of
+ the client machine. (See the DETERMINING PREFERENCES
+ section for more information about how the Cache Manager
+ determines actual file server machine ranks.) Because they
+ are stored in the kernel, the preferences are recalculated
+ when the client machine is rebooted.
+
+ The Cache Manager assigns ranks to file server machines in
+
+
+
+ the local cell and from foreign cells as necessary. When it
+ needs to access a ReadOnly volume, it first determines the
+ machines on which the replica resides. It then assigns
+ ranks to any of the machines that do not already have them
+ and stores the ranks in the kernel, after which it uses the
+ ranks as the basis of its selection of the file server
+ machine from which to access the replica.
+
+ The fs setserverprefs command can be used to define or
+ change the rank associated with a local or foreign file
+ server machine. If the Cache Manager has no rank for the
+ machine, the command defines the machine's initial rank. If
+ the Cache Manager already has a rank for the machine, the
+ command changes the rank to match the one specified by the
+ issuer; the old rank is overwritten.
+
+ Preferences are specified as pairs of values. The first
+ value is the file server machine, the second the machine's
+ rank. File server machines can be specified by name or by
+ IP address. Depending on the naming service available at
+ the time the command is issued, abbreviated forms of machine
+ names may be allowed. See the introductory About This
+ Manual chapter for more information.
+
+ Pairs of file server machines and their ranks can be
+ specified
+
+ - on the command line with the -servers switch
+
+ - from a file with the -file switch
+
+ - from stdin with the -stdin flag
+
+ The -file switch and -stdin flag are especially useful for
+ configuring multiple Cache Managers in a cell with the same
+ preferences. The -file switch can be used to indicate a
+ file created manually or generated automatically with the fs
+ getserverprefs command. Similarly, the -stdin flag can be
+ used to accept preferences piped directly from another
+ process (possibly from another Cache Manager with the fs
+ getserverprefs command). The -servers, -file, and -stdin
+ switches and flag are not mutually exclusive, so multiple
+ sources of preferences are permitted.
+
+ It is possible for the Cache Manager or a user to assign the
+ same rank to multiple file server machines housing a replica
+ of the same volume. In this case, the Cache Manager uses
+ methods described in the following section, ASSIGNING
+ PREFERENCES, to break the tie. It then increments the ranks
+ of the file server machines from which it does not access
+ the replica.
+
+ASSIGNING PREFERENCES
+
+ When initially assigning preferences, the Cache Manager
+ bases the ranks on IP addresses, rather than on actual
+ physical considerations such as location or distance. It
+ calculates file server machine ranks according to the
+ following heuristic:
+
+ - If the client machine is also a file server
+
+
+
+ machine, the machine receives a rank of 5000.
+
+ - If the client machine is in a subnet, all file
+ server machines in the same subnet as the client
+ machine receive an initial rank of 20000.
+
+ - All file server machines in the same network as
+ the client machine receive an initial rank of
+ 30000.
+
+ - All file server machines on the distant ends of
+ point-to-point links from the client machine
+ receive an initial rank of 30000.
+
+ - All file server machines on networks not directly
+ connected to the client machine receive a rank of
+ 40000.
+
+ - All file server machines for which no network
+ locality information can be determined receive a
+ default rank of 40000.
+
+ The Cache Manager also considers additional metrics
+ associated with networks, subnets, and interfaces when it
+ determines ranks.
+
+ If the same ReadOnly replica is stored on multiple file
+ server machines that have the same rank, the Cache Manager
+ employs the metrics mentioned previously to resolve the
+ duplicate rank collisions. If necessary, the Cache Manager
+ randomizes its ranking of the tied machines. It resolves
+ the ties internally by incrementing by one the ranks of the
+ machines from which it chooses not to access the replica.
+
+NOTE
+
+ The Cache Manager consults preferences only when accessing
+ ReadOnly replicas of volumes. It does not consider the
+ preferences when contacting the VL Server on a database
+ server machine to determine the location of a volume. Its
+ access of database server machines is still random.
+
+ARGUMENTS
+
+ -servers specifies one or more pairs of file server
+ machines and their respective ranks.
+ Identify file server machines by name or by
+ IP address. See the DESCRIPTION section for
+ more information on specifying file server
+ machines and their ranks.
+
+ -file specifies the pathname of a file that
+ contains pairs of file server machines and
+ their respective ranks. Identify file
+ server machines by name or by IP address.
+ See the DESCRIPTION section for more
+ information on specifying file server
+ machines and their ranks.
+
+ -stdin indicates that pairs of file server machines
+ and their respective ranks are to be read
+
+
+
+ from stdin. Identify file server machines
+ by name or by IP address. See the
+ DESCRIPTION section for more information on
+ specifying file server machines and their
+ ranks.
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+EXAMPLES
+
+ The following sets preference ranks for three file server
+ machines. In this example, the server machines have no
+ replicas in common, so no potential collisions are
+ associated with their all having the same rank.
+
+ % fs sets -se fs1.transarc.com 10000 fs2.transarc.com 10000
+ \ 128.2.11.12 10000
+
+ The following defines a rank for one file server machine
+ from the command line and reads ranks for additional file
+ server machines from a file named prefs.txt in the current
+ directory:
+
+ % fs sets -se fs4.transarc.com 10010 -f prefs.txt
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged in as "root" in the UNIX file system
+ of the machine on which the command is issued.
+
+MORE INFORMATION
+
+ fs getserverprefs
--- /dev/null
+fs setvol AFS Commands fs setvol
+
+
+NAME
+
+ fs setvol -- set maximum quota and messages for each volume
+
+ containing specified directory.
+
+
+ +
+ fs setvol [-path <dir/file path> [-max <disk space quota
+ in 1K units>]
+ [-motd <message of the day>] [-offlinemsg <offline
+ message>]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs sv [-p <dir/file path> ] [-ma <disk space quota in 1K
+ units>]
+ [-mo <message of the day>] [-o <offline message>] [-h]
+
+DESCRIPTION
+
+ Sets maximum quota for the volumes that contain each
+ specified directory or file. It is also possible to use
+ -motd and -offlinemsg to create messages associated with the
+ volume, which appear when the fs examine command is issued.
+
+ The fs examine command displays all the information that can
+ be altered with this command. The fs listquota command
+ displays maximum quota, and the fs quota command displays
+ the percent quota used.
+
+ The fs setquota command sets maximum quota on one volume at
+ a time.
+
+ARGUMENTS
+
+ -path names each file and/or directory for which
+ quota and messages on the host volumes are
+ to be set. Omit this switch to affect the
+ volume that contains the current working
+ directory.
+
+ -max specifies the maximum amount of disk space
+ the volume can use. Express it in kilobyte
+ blocks (a value of 1024 is one megabyte). A
+ value of 0 grants an unlimited quota, but
+ the size of the disk partition housing the
+ volume places an absolute limit on the
+ volume's maximum size.
+
+ -motd specifies a "message of the day" displayed
+ with the fs examine command. It can be used
+ to alert users to anything of interest
+ concerning the volume.
+
+ -offlinemsg specifies a message displayed with the fs
+ examine command. It can be used to explain
+ why the volume is currently offline.
+
+ -help prints the online help entry for this
+
+
+
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+EXAMPLES
+
+ The following imposes a 6500 kilobyte quota on the volumes
+ housing the /afs/transarc.com/usr/smith and
+ /afs/transarc.com/usr/pat home directories:
+
+ % cd /afs/transarc.com/usr % fs sv -p smith pat -ma 6500
+
+PRIVILEGE REQUIRED
+
+ Issuer must belong to the system:administrators group in the
+ Protection Database.
+
+MORE INFORMATION
+
+ fs examine
+
+ fs listquota
+
+ fs quota
+
+ fs setquota
--- /dev/null
+fs sysname AFS Commands fs sysname
+
+
+NAME
+
+ fs sysname -- report or set CPU/operating system type.
+
+
+ fs sysname [-newsys <new sysname>] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs sy [-n <new sysname>] [-h]
+
+DESCRIPTION
+
+ Depending on whether the issuer provides the -newsys
+ argument,
+
+ EITHER sets the indicator of CPU/operating system type in th
+ the machine on which the command is issued
+
+ OR reports the current setting.
+
+ If the command is issued on an AFS client machine, the value
+ is set/reported for the machine itself.
+
+ If the command is issued on an NFS client machine accessing
+ AFS via the NFS/AFS Translator, then the specified CPU/OS
+ value is set/reported for the NFS client machine. The
+ information is in a record maintained by the AFS client
+ machine serving as the NFS client's NFS/AFS translator
+ machine. The translator machine maintains a separate record
+ for each user logged into the NFS client. This implies that
+ if a user adopts a new identity (UNIX UID) during a login
+ session on the NFS clientMperhaps using suMhe or she must
+ issue this command again. Setting this indicator allows the
+ translator machine to provide the NFS client with the proper
+ version of program binaries when the user issues commands
+ for which the binaries are kept in the AFS file tree.
+
+ The Cache Manager's main use of this indicator is as a value
+ for the "@sys" variable which can occur in AFS pathnames.
+ As the Cache Manager interprets pathnames, it substitutes
+ the indicator's value for any occurrence of @sys. See the
+ EXAMPLES section for an example. (Note that @sys should be
+ used sparingly, as it can make the effect of changing
+ directories unpredictable; see the AFS System
+ Administrator's Guide for further information.)
+
+ARGUMENTS
+
+ -newsys specifies the new setting of the CPU/operating
+ system indicator for the machine on which it is
+ issued. If the issuer omits it, the output shows
+ the current setting. Consult the AFS System
+ Administrator's Guide for a complete list of the
+ legal values and the CPU/OS types they represent.
+
+ -help prints the online help entry for this command. Do
+ not provide any other arguments or flags with this
+ one. See section 3.1 in the Reference Manual for
+ more details.
+
+
+
+OUTPUT
+
+ The output reports the machine's system type in the format
+
+ Current sysname is 'system type'
+
+EXAMPLES
+
+ The following shows the output produced on a Sun
+ SPARCStation running SunOS 4.1:
+
+ % fs sy Current sysname is 'sun4c_41'
+
+ The following defines a machine to be a DECStation running
+ Ultrix 4.1:
+
+ % fs sysname pmax_ul4
+
+ When the Cache Manager on the machine encounters a pathname
+ with the @sys variable in it, it substitutes pmax_ul4 for
+ the variable. For instance, this machine would interpret
+ the pathname
+
+ /afs/transarc.com/@sys/usr/bin
+ as
+ /afs/transarc.com/pmax_ul4/usr/bin
+ and would access the volume corresponding to that directory.
+ A machine whose CPU/OS type was rt_aos4 would interpret the
+ same pathname as
+
+ /afs/transarc.com/rt_aos4/usr/bin
+
+ and so would access a volume different from that accessed by
+ the DECStation.
+
+PRIVILEGE REQUIRED
+
+ None, if the machine is an NFS client. If the machine is an
+ AFS client, the issuer must be logged into the local UNIX
+ file system as "root."
+
+
+
+MORE INFORMATION
+
+ fs exportafs
--- /dev/null
+fs whereis AFS Commands fs whereis
+
+
+NAME
+
+ fs whereis -- report name of file server machine(s) housing
+
+ specified file/directory.
+
+
+ +
+ fs whereis [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs whe [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Returns the name of the file server machines that house each
+ specified directory or file. See the OUTPUT section for a
+ description of the information displayed.
+
+ARGUMENTS
+
+ -path specifies each file or directory whose location is to
+ be returned. Each specified file or directory must
+ reside in AFS (not on a local disk). If the issuer
+ omits this argument, the location of the working
+ directory is returned.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output includes a line for each specified directory or
+ file. It names the file server machine on which the volume
+ that houses the specified directory or file resides. A list
+ of multiple machines indicates that the directory or file is
+ in a replicated volume.
+
+ Machine names usually have a suffix indicating their cell
+ membership. If some question remains, the fs whichcell
+ command names the cell in which a directory or file resides.
+
+EXAMPLES
+
+ The following indicates that the directory /afs/transarc.com
+ resides in a replicated volume located on both
+ fs1.transarc.com and fs3.transarc.com:
+
+ % fs whe /afs/transarc.com File /afs/transarc.com is on
+ hosts fs1.transarc.com fs3.transarc.com
+
+
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs whichcell
+
+ fs wscell
--- /dev/null
+fs whichcell AFS Commands fs whichcell
+
+
+NAME
+
+ fs whichcell -- return name of cell to which specified
+
+ file/directory belongs.
+
+
+ +
+ fs whichcell [-path <dir/file path> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ fs whi [-p <dir/file path> ] [-h]
+
+DESCRIPTION
+
+ Returns the name of the cell in which the volume that houses
+ each indicated directory or file resides. See the OUTPUT
+ section for a description of the information displayed.
+
+ARGUMENTS
+
+ -path specifies each file and/or directory whose cell
+ membership is to be returned. Each specified
+ directory or file must reside in AFS (not on a local
+ disk). If the issuer omits this argument, the cell of
+ the working directory is returned.
+
+ -help prints the online help entry for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 3.1 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output includes a line for each specified directory or
+ file, naming the cell in which the directory or file
+ resides.
+
+EXAMPLES
+
+ The following shows that the current directory resides in a
+ volume in the Transarc Corporation cell:
+
+ % fs whi File . lives in cell 'transarc.com'
+
+PRIVILEGE REQUIRED
+
+ None.
+
+
+
+MORE INFORMATION
+
+ fs whereis
+
+ fs wscell
--- /dev/null
+fs wscell AFS Commands fs wscell
+
+
+NAME
+
+ fs wscell -- return name of cell to which workstation
+
+ belongs.
+
+
+ fs wscell [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ fs ws [-h]
+
+DESCRIPTION
+
+ Returns the name of the home cell for the workstation from
+ which the command is issued.
+
+ARGUMENTS
+
+ -help prints the online help entry for this
+ command. Do not provide any other arguments
+ or flags with this one. See section 3.1 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ The reported cell name comes from the file
+ /usr/vice/etc/ThisCell on the workstation's local disk.
+
+EXAMPLES
+
+ The following results when the fs wscell is issued on a
+ machine in the Transarc Corporation cell:
+
+ % fs wscell
+ This workstation belongs to cell 'transarc.com'
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ fs whereis
+
+ fs whichcell
--- /dev/null
+ AFS Commands
+
+
+NAME
+ AFS Commands
+
+
+ 1. The kas Commands
+
+ ------------------------------------------------------------
+
+ This chapter defines the kas commands that system
+ administrators use to contact the Authentication Server. It
+ assumes the reader is familiar with the concepts described
+ in the AFS System Administrator's Guide.
+
+ The kas command interface allows system administrators to
+ create, modify, examine and delete entries in the
+ Authentication Database maintained by the Authentication
+ Server. Individual users may use the kas setpassword
+ command to change their own password (as well as the more
+ standard, non-kas command, kpasswd).
+
+ Refer to the Command Summary at the end of this document for
+ a complete list of kas commands and their syntax.
+ AFS Command Reference Manual The kas Commands 2
+
+
+ 1.1 The kas Interface
+ The kas command interface differs slightly from the others
+ described in this manual. The Authentication Server
+ authenticates issuers of kas commands directly rather than
+ accepting a ticket from the Ticket Granting Service as most
+ other servers do. Thus most commands require that the
+ issuer provide his or her password at the time of issue.
+
+
+
+ 1.1.1 Interactive Mode
+ Providing the password each time could get tedious if the
+ user needed to execute a whole set of commands, so kas
+ provides an "interactive" mode in which it is not necessary
+ to provide a password repeatedly.
+
+
+ 1.1.1.1 Entering Interactive Mode
+ There are several ways to enter interactive mode:
+
+ - Use the kas interactive command.
+
+ - Type kas without any operation code. By default,
+ the command interpreter establishes a connection
+ with each Authentication Server in the local cell.
+ They attempt to authenticate the user logged into
+ the machine from which the command is issued,
+ based on the password the issuer provides at the
+ prompt. The issuer may specify an alternate
+ identity, password, cell name and/or list of
+ Authentication Servers by using the first four
+ common arguments described in section 4.3 in the
+ Reference Manual . Type kas followed by a user
+ name and cell name, separated by an "@" sign
+ (example: kas smith@transarc.com). The
+ Authentication Server attempts to authenticate the
+ specified user in the specified cell, and prompts
+ for his or her password in the specified cell.
+ This method is most useful when the issuer wishes
+ to enter interactive mode with a different
+ identity in a different cell.
+
+
+ 1.1.1.2 Effects of Entering Interactive Mode
+ While in interactive mode:
+
+
+ - The "ka>" prompt replaces the issuer's regular
+ prompt.
+
+ - It is no longer necessary or legal to type kas at
+ the beginning of a command. Type the operation
+ code as the first part of the command.
+
+ - The Authentication Server does not prompt for the
+ issuer's password at each command. This is the
+ mode's main advantage.
+
+ - The issuer's identity and cell are set and cannot
+ be changed without leaving interactive mode, so it
+ is not legal to provide any of the common
+ AFS Command Reference Manual The kas Commands 3
+
+
+ arguments described fully in section 4.3 in the
+ Reference Manual , except for -help.
+
+ 1.2 Information in the Authentication Database
+ Both individual users and servers have entries in the
+ Authentication Database. The two most important fields in
+ an entry are:
+
+ - the name
+
+ - the key (a scrambled form of name's password,
+ suitable for use as an encryption key)
+
+ For individual users, the name field holds the user name as
+ typed at login, and key holds a scrambled form of the
+ password the user has created.
+
+ Server entries are the same as user entries. The entry name
+ for the AFS server processes is "afs". A server entry's key
+ field contains the server encryption key that the Ticket
+ Granting Service (TGS) uses to seal the tickets it gives to
+ clients so that they may contact the server processes.
+
+ 1.3 Common Arguments and Flags
+ When not in interactive mode, most kas commands accept the
+ following optional arguments and flags. Some of these are
+ unavailable in interactive mode because the information they
+ provide is established while entering interactive mode, and
+ cannot be changed from within interactive mode. They are
+ listed in the command descriptions where they apply, and are
+ described in detail below:
+
+ [-admin_username <admin principal to use for
+ authentication>]
+
+ This argument allows the issuer to assume the identity of
+ the specified user name (which is referred to as an "admin
+ principal"). By default, the Authentication Server attempts
+ to authenticate the user logged into the local workstation.
+
+ [-password_for_admin <admin password>]
+
+ This argument provides the Authentication Server with the
+ password needed to prove that the issuer of the command (the
+ admin principal) is legitimate (which it will if it matches
+ the password stored in the Authentication Database for the
+ issuer). Note that providing this argument on the command
+ line reveals the password on the screen. Issuers may prefer
+ to respond to the prompt that will appear if this argument
+ is not provided, as the password does not echo visibly in
+ that case.
+
+ [-cell <cell name>]
+
+ This argument specifies that the command should be run in a
+ different cell, specified by cell name. By default,
+ commands are executed in the local cell, as defined in
+ /usr/vice/etc/ThisCell on the client machine on which the
+ command is issued. The issuer may abbreviate cell name to
+ the shortest form that distinguishes it from the other cells
+ listed in /usr/vice/etc/CellServDB on the client machine on
+ AFS Command Reference Manual The kas Commands 4
+
+
+ which the command is issued.
+
+ +
+ [-servers <explicit list of authentication servers> ]
+
+ This argument causes the kas command interpreter to
+ establish a connection with the Authentication Server
+ running on each specified database server machine. It then
+ chooses one of these at random to execute each subsequent
+ command. The issuer may abbreviate the machine name to the
+ extent the cell's name server will accept.
+
+ By default, the kas command interpreter establishes a
+ connection with each machine listed in the local
+ workstation's copy of /usr/vice/etc/CellServDB, and then
+ chooses one of those at random for command execution.
+
+ This option is useful for testing specific servers if
+ problems are encountered.
+
+ [-noauth]
+
+ This flag instructs indicated Authentication Server(s) not
+ to authenticate the issuer of the command, and thus
+ establishes an unauthenticated connection between the issuer
+ and the Authentication Server (he or she is recognized as
+ the unprivileged user anonymous). It is useful only when
+ authorization checking is disabled on the file server
+ machine (during the installation of a file server machine or
+ when bos setauth has been used during other unusual
+ circumstances). In normal circumstances, the Authentication
+ Server allows only authorized (privileged) users to issue
+ most kas commands, and will refuse to execute the requested
+ actions even if the -noauth flag is used.
+
+ [-help]
+
+ This flag has the same function as the kas help command: it
+ prints the command's online help message on the screen. No
+ other arguments or flags should be provided at the same
+ time. Even if they are, this flag overrides them, and the
+ only effect of issuing the command is that the help message
+ appears.
+
+ 1.4 The Privilege Required for kas Commands
+ The Authentication Server considers privileged those users
+ who have the ADMIN flag turned on in their Authentication
+ Database entry. See the kas setfields command to learn how
+ to turn on the ADMIN flag. Most kas commands require that
+ the issuer be privileged. All commands will prompt for a
+ password, unless the issuer has entered interactive mode.
--- /dev/null
+kas apropos AFS Commands kas apropos
+
+
+NAME
+
+ kas apropos -- show each help entry containing keyword.
+
+
+ kas apropos -topic <help string> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas a -t <help string> [-h]
+
+DESCRIPTION
+
+ Displays the first line of the help entry for any kas
+ command that has help string in its name or short
+ description.
+
+ARGUMENTS
+
+ -topic
+ specifies the keyword string to search for. If it is
+ more than a single word, surround it with double
+ quotes or other delimiters. Type all help strings for
+ kas commands in all lowercase letters, except the word
+ "AuthServer."
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 4.3 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The first line of a command's online help entry names the
+ command and briefly describes what it does. The kas apropos
+ command displays that first line for any kas command where
+ help string is part of the command name or first line.
+
+ To see the remaining lines in a help entry, which provide
+ the command's alias (if any) and syntax, use the kas help
+ command.
+
+EXAMPLE
+
+ The following lists all kas commands that have the word
+ "key" in their operation code or short online description.
+
+ % kas a key
+ getrandomkey: get a random key
+ setkey: set a user's key
+ stringtokey: convert a string to a key
+
+
+
+PRIVILEGE REQUIRED
+
+ None. No password will be prompted for.
+
+MORE INFORMATION
+
+ kas help
--- /dev/null
+kas create AFS Commands kas create
+
+
+NAME
+
+ kas create -- create an entry in the Authentication
+
+ Database.
+
+
+ kas create -name <name of user> [-initial_password
+ <initial password>]
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ] [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas c -na <name of user> [-i <initial password>]
+ [-a <admin principal to use for authentication>] [-p <admin
+ password>]
+ [-c <cell name>] [-s <explicit list of authentication
+ +
+ servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Creates an entry in Authentication Database for name of
+ user. The Authentication Server converts initial password
+ into a form suitable for use as an encryption key, and
+ places it in the entry's key field.
+
+ARGUMENTS
+
+ -name specifies the name of the new
+ Authentication Database entry. It will be
+ the user name under which the user logs in
+ to the system.
+
+ -initial_password specifies a character string that will
+ become the user's password. The
+ Authentication Server scrambles it into an
+ octal key and places it in the key field
+ of the Database entry. If the issuer does
+ not provide it, it will be prompted for
+ (if it is not provided at the prompt the
+ create operation fails). The advantage of
+ waiting for the prompt is that the
+ password does not echo on the screen.
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. See
+ section 4.3 in the Reference Manual for
+ more details. -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+
+
+
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+EXAMPLE
+
+ The following shows the prompts that appear when someone
+ authenticated as admin creates an Authentication Database
+ entry for the user smith, and does not specify smith's
+ initial password on the command line. The passwords typed
+ at the prompts do not echo visibly.
+
+ % kas cr smith Password for admin: initial_password:
+ Verifying, please re-enter initial_password:
+
+PRIVILEGE REQUIRED
+
+ Issuer must have the ADMIN flag set in his or her
+ Authentication Database entry.
+
+MORE INFORMATION
+
+ kas examine
--- /dev/null
+kas debuginfo AFS Commands kas debuginfo
+
+
+NAME
+
+ kas debuginfo -- produce debugging trace for the
+
+ Authentication Server.
+
+
+ kas debuginfo [-hostname <authentication server host name>]
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of authentication servers> ]
+ [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas deb [-ho <authentication server host name>]
+ [-a <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-n] [-he]
+
+DESCRIPTION
+
+ Displays information on the standard output device (stdout)
+ which is helpful in debugging the Authentication Server.
+ This information is useful only for someone familiar with
+ the implementation of the Authentication Server and the
+ internal structure of the Authentication Database. Most
+ system administrators will not find it helpful.
+
+ARGUMENTS
+
+ -hostname names the database server machine for
+ which to display debugging information
+ about the Authentication Server instance
+ it is running.
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. See
+ section 4.3 in the Reference Manual for
+ more details. -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+
+
+
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+PRIVILEGE REQUIRED
+
+ None. A password will be prompted for unless the -noauth
+ flag is provided. The issuer must type some character
+ string at the prompt, but even providing the wrong one does
+ not prevent the command from being executed, despite
+ possible error messages.
+
+MORE INFORMATION
+
+ kas statistics
--- /dev/null
+kas delete AFS Commands kas delete
+
+
+NAME
+
+ kas delete -- delete entry from the Authentication
+
+ Database.
+
+
+ kas delete -name <name of user>
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ] [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas del -na <name> [-a <admin principal to use for
+ authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+ kas rm -na <name> [-a <admin principal to use for
+ authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Removes the entry name of user from the Authentication
+ Database. If name of user is a user, he or she becomes
+ unable to log in. If name of user is a server, it becomes
+ unreachable, because the TGS can no longer has anything with
+ which to seal tickets for the server.
+
+ARGUMENTS
+
+ -name specifies the name of the Database entry
+ to delete
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. See
+ section 4.3 in the Reference Manual for
+ more details. -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details.
+
+ -cell specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+
+
+
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+EXAMPLE
+
+ In the following the issuer admin enters interactive mode in
+ order to make it more convenient to delete three accounts at
+ once. The password typed at the prompt does not echo
+ visibly.
+
+ % kas Password for admin: ka> del smith ka> del pat ka>
+ del terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must have the ADMIN flag set in his or her
+ Authentication Database entry.
+
+MORE INFORMATION
--- /dev/null
+kas examine AFS Commands kas examine
+
+
+NAME
+
+ kas examine -- display information from an Authentication
+
+ Database entry.
+
+
+ kas examine -name <name of user>
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ] [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas e -na <name of user> [-a <admin principal to use for
+ authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Formats and displays information from the Authentication
+ Database entry for name. See the OUTPUT section for
+ details.
+
+ARGUMENTS
+
+ -name specifies the Database entry from which to
+ display information.
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+
+
+
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+
+
+OUTPUT
+
+ The output reports, in this order:
+
+ - the name of the entry
+
+ - one or more status flags, which will only appear
+ if a system administrator has used the
+ kas setfields command to change a flag from its
+ default value. A plus sign (+) will separate the
+ flags if more than one appears. The non-default
+ values which may appear, and their meanings, are:
+
+ * ADMIN. the user is allowed to issue
+ privileged kas commands (Default: NOADMIN.)
+
+ * NOTGS. the Ticket Granting Service will
+ refuse to issue tickets to the user (Default:
+ TGS.)
+
+ * NOSEAL. the Ticket Granting Service cannot
+ use the contents of this entry's key field as
+ an encryption key (Default: SEAL.)
+
+ * NOCPW. the user or server cannot change
+ his/her/its own password or key (Default:
+ CPW.)
+
+ - the word "key" followed by the key version number
+ in parentheses.
+
+ The octal key itself appears only if authorization
+ checking is disabled on the database server
+ machine to which the kas examine command is
+ directed with the -servers argument (see the
+ EXAMPLES section). The reasoning behind this
+ requirement is two-fold. First, it implies that
+ only someone authorized to issue the bos setauth
+ command or with "root" access to the database
+ server machine's local disk is able to see actual
+ keys from the Authentication Database. Second, it
+ makes it clear that the system is in a compromised
+ state of security while keys are being displayed
+ on the screen. Both turning off authorization
+ checking and displaying keys on a screen are
+ serious security risks.
+
+ In the normal cases when authorization checking is
+ enabled on the database server machine, a
+ "checksum" appears instead of the key. This is a
+ decimal number derived by encrypting a constant
+ with the key. In the case of the "afs" key, this
+ number can be compared to the checksum with the
+ corresponding key version number in the output of
+ the bos listkeys command.
+
+ - the date that the user changed his/her own
+ password, indicated as "last cpw" (which stands
+ for "last change of password")
+
+ - the date on which the entry expires. If this is a
+
+
+
+ user entry, the user will be unable to
+ authenticate with the Authentication Server after
+ this date.
+
+ - the maximum length of time that tickets issued for
+ this entry may be valid
+
+ - the date of the last modification to the entry,
+ indicated as "last mod," and the user name of the
+ person who issued the modifying command. Password
+ changes made by the user himself/herself are
+ recorded as "last cpw" instead.
+
+EXAMPLES
+
+ In each of the examples, the password typed at the prompt
+ does not echo visibly.
+
+ The following shows the privileged user smith examining her
+ own Authentication Database entry. Note the ADMIN flag,
+ which shows that smith is privileged.
+
+ % kas e smith
+ Password for smith:
+ User data for smith (ADMIN)
+ key (0) cksum is 3414844392, last cpw: Wed Jan 3 16:05:44
+ entry expires on never. Max ticket lifetime 100.00 hours.
+ last mod on Thu Dec 21 08:22:29 1989 by admin
+
+ In the following the regular user terry examines her own
+ entry and tries to examine pat's.
+
+ % kas
+ Password for terry:
+ ka> ex terry
+ User data for terry
+ key (0) cksum is 529538018, last cpw: Fri Jan 19 9
+ entry expires on never. Max ticket lifetime 100.00
+ last mod on Thu Dec 21 08:43:29 1989 by admin
+ ka> ex pat
+ kas:examine: caller not authorized getting informati
+
+
+ In the following an administrator logged in as the
+ privileged user admin uses bos setauth to turn off
+ authorization checking on the database server machine
+ db1.transarc.com so that he can look at the key in the afs
+ entry. He enters interactive mode to open a connection with
+ the Authentication Server on db1.transarc.com only and uses
+ the -noauth flag to prevent that server from attempting to
+ authenticate him.
+
+ % bos setauth db1.transarc.com off
+ % kas i -servers db1.transarc.com -noauth
+ ka> examine afs -servers db1.transarc.com
+ User data for afs
+ key (12): \357\253\304\352a\236\253\352, last cpw:
+ entry expires on never. Max ticket lifetime 100.00
+ last mod on Thu Jan 11 14:53:29 1990 by admin
+
+PRIVILEGE REQUIRED
+
+
+
+ A user may examine his or her own entry. To examine others'
+ entries, the issuer must have the ADMIN flag set in his or
+ her Authentication Database entry.
+
+ To look at actual keys, authorization checking must be
+ disabled on the database server machine with bos setauth,
+ which implies being listed in /usr/afs/etc/UserList; it is
+ not necessary to have the ADMIN flag in addition.
+
+MORE INFORMATION
+
+ bos listkeys
+
+ bos setauth
+
+ kas setfields
--- /dev/null
+kas forgetticket AFS Commands kas forgetticket
+
+
+NAME
+
+ kas forgetticket -- discard all tickets for the issuer.
+
+
+ kas forgetticket [-name <name of server>] [-all] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas f [-h]
+
+DESCRIPTION
+
+ Discards all tickets that the Authentication Server has
+ registered for the issuer. This includes the AFS server
+ ticket from each cell in which the user has authenticated,
+ and any tickets that the user may have acquired during this
+ kas session (either by virtue of entering the session or
+ using kas getticket).
+
+ARGUMENTS
+
+ -name specifies which ticket should be discarded. Provide
+ this argument OR the -all flag.
+
+ Note:This argument is not currently implemented: all
+ tickets are discarded no matter which ticket which
+ ticket name is specified here.
+
+ -all indicates that all tickets should be discarded.
+ Provide this flag OR the -name argument. In the
+ current implementation, this flag is more sensible
+ because it matches what actually happens no matter
+ which option the issuer chooses.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 4.3 in the Reference Manual for more
+ details.
+
+EXAMPLES
+
+ Both of the following discard all tickets for the issuer.
+
+ % kas forgetticket -all % kas f
+
+PRIVILEGE REQUIRED
+
+ None. There is no prompt for a password, and the issuer
+ does not have to have the ADMIN flag set in his or her
+ Database entry. The deletion can affect only the issuer
+ anyway.
+
+MORE INFORMATION
--- /dev/null
+kas getpassword AFS Commands kas getpassword
+
+
+NAME
+
+ kas getpassword -- display octal key from an Authentication
+
+ Database entry.
+
+
+ kas getpassword -name <name of user> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas getp -n <name of user> [-h]
+
+DESCRIPTION
+
+ Prints out the contents (an octal-format encryption key) of
+ the key field for the Database entry name of user.
+
+WARNING
+
+ This command works only if the Authentication Server has
+ been compiled with a special flag; this is normally done
+ only for cells in the process of converting from use of AFS
+ 2.0-style authentication to AFS 3.0 authentication.
+ Moreover, this command does not work if issued on an AFS
+ client. The issuer must be logged into a machine running
+ the specially-compiled Authentication Server (a database
+ server machine or other machine running an isolated
+ Authentication Server).
+
+ The recommended way to examine the octal form of keys is
+ with kas examine when authorization checking is disabled.
+ That command shows a "checksum" when authorization checking
+ is enabled, which may be suitable for some purposes.
+
+ Even when the other conditions are met, this command does
+ not work for entries where the name includes a period (these
+ entries are generally for the Authentication Server's
+ internal use anyway).
+
+ARGUMENTS
+
+ -name names the entry from which the key field should be
+ printed out.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 4.3 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output simply prints the key after a "Key:" header. It
+ does not report the key version number, but that is
+ available from kas examine.
+
+EXAMPLE
+
+ The following shows a user using this command to examine
+ afs's password.
+
+
+
+ % kas getp afs
+ Key: \020\354\315\310\313\023W\370
+
+PRIVILEGE REQUIRED
+
+ None. There is no prompt for a password, and the issuer
+ does not have to have the ADMIN flag set in his or her
+ Database entry. It is assumed that any machine running the
+ Authentication Server is secured by having only a limited
+ number of people in its local /etc/passwd file.
+
+MORE INFORMATION
+
+ kas examine
--- /dev/null
+kas getrandomkey AFS Commands kas getrandomkey
+
+
+NAME
+
+ kas getrandomkey -- generate an encryption key at random.
+
+
+ kas getrandomkey
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of authentication servers> ]
+ [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas getr [-a <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-n] [-h]
+
+DESCRIPTION
+
+ Returns a key generated at random (i.e., not derived from
+ any known password). This is useful mainly for testing and
+ debugging the Authentication Server.
+
+WARNINGS
+
+ The output of this command is visible on the issuer's
+ screen, making it a potential security risk to use the key
+ in an actual Authentication Database entry (such as the
+ "afs" entry).
+
+ If the -noauth flag is used, the connection to the
+ Authentication Server is not authenticated, so the randomly
+ generated key crosses the network unencrypted. The
+ potential security risk in using the key as an actual
+ encryption key is even greater in this case.
+
+ARGUMENTS
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+
+
+
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+OUTPUT
+
+ Following a "Key:" header, the output displays the octal and
+ hexadecimal forms of the key.
+
+EXAMPLE
+
+ The following shows terry issuing this command.
+
+ % kas getr
+ Password for terry:
+ Key: \230\206\370v1\334\373\346 (98.86.f8.76 31.dc.f
+
+PRIVILEGE REQUIRED
+
+ None, but the correct password must be provided at the
+ prompt if the key is to be encrypted while crossing the
+ network. If the -noauth flag is used, a password is not
+ prompted for.
+
+MORE INFORMATION
--- /dev/null
+kas getticket AFS Commands kas getticket
+
+
+NAME
+
+ kas getticket -- create a ticket valid for the specified
+
+ server.
+
+
+ kas getticket -name <name of server>
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of authentication servers> ]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas gett -na <name of server> [-a <admin principal to use
+ for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Instructs the Ticket Granting Service to create a ticket for
+ the issuer of the command, which he or she can use for
+ secured communication with name of server. The ticket is
+ sealed with the contents of the key field in name of
+ server's Database entry.
+
+ This command is functionally similar to klog. It is useful
+ primarily for debugging purposes, and is not recommended as
+ the normal way to obtain tickets. Also, while it is
+ possible to make name of server an individual user as well
+ as a server process, such a ticket is useless because the
+ user's workstation will not know what to do with it.
+
+ARGUMENTS
+
+ -name specifies the Database entry from which to
+ use the key. It may include a cell
+ specification (example:
+
+ kas getticket afs@transarc.com
+
+ gets a ticket good for all AFS servers in
+ the Transarc Corporation cell).
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+
+
+
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+EXAMPLE
+
+ The following shows the regular user terry obtaining a
+ ticket for the AFS server processes in her home cell.
+
+ % kas gett afs Password for terry:
+
+PRIVILEGE REQUIRED
+
+ None. However, the issuer must provide his or her correct
+ password.
+
+MORE INFORMATION
--- /dev/null
+kas help AFS Commands kas help
+
+
+NAME
+
+ kas help -- show syntax of specified kas command(s) or list
+
+ functional description for all of them.
+
+
+ +
+ kas help [-topic <help string> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ kas h [-t <help string> ] [-h]
+
+DESCRIPTION
+
+ Displays the first line (name and short description) of
+ every kas command's help entry, if no help string is
+ provided. For each operation code specified with -topic, it
+ outputs the entire help entry. See the Output section
+ below.
+
+ARGUMENTS
+
+ -topic
+ specifies the operation code(s) for which syntax is to
+ be provided. If the issuer omits it, the output
+ instead provides a short description of all kas
+ commands.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 4.3 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The online help entry for each kas command consists of two
+ or three lines:
+
+ - The first line names the command and briefly
+ describes what it does
+
+ - If the command has aliases, they will appear on
+ the next line
+
+ - The final line, which begins with "Usage:", lists
+ the command's arguments and flags in the
+ prescribed order. Online help entries use the
+ same symbols (brackets, etc.) as the command
+ definitions in this manual. For an explanation of
+ their meaning, see page v of the introductory
+ About This Manual chapter.
+
+
+
+EXAMPLE
+
+ The following displays the online help entry for the
+ kas setpassword command.
+
+ % kas help setpassword
+ kas setpassword: set a user's password
+ aliases: sp
+ Usage: kas setpassword -name <name of user> [-new_passwo
+ <new password>] [-kvno <key version number>]
+ [-admin_username <admin principal to use for authenticat
+ [-password_for_admin <password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of authentication servers> ] [-
+
+PRIVILEGE REQUIRED
+
+ None. No password will be prompted for.
+
+MORE INFORMATION
+
+ kas apropos
--- /dev/null
+kas interactive AFS Commands kas interactive
+
+
+NAME
+
+ kas interactive -- enter interactive mode for
+
+ Authentication Server.
+
+
+ kas interactive
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ] [-noauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas i [-a <admin principal to use for authentication>] [-p
+ <admin password>]
+ [-c <cell name>] [-s <explicit list of authentication
+ +
+ servers> ]
+ [-n] [-h]
+
+DESCRIPTION
+
+ Enters interactive mode. By establishing an authenticated
+ connection in this way, the issuer will not have to type his
+ or her password at each command as would be necessary in
+ regular mode. The authenticated connection lasts for one
+ hour unless the maximum ticket lifetime for the issuer or
+ the Authentication Server is shorter.
+
+ It is also possible to establish an unauthenticated
+ connection under the identity anonymous by using the -noauth
+ flag. During normal operation, there is no point to doing
+ so, because the Authentication Server still does
+ authorization checking and will not allow anonymous, who is
+ unprivileged by definition, to perform privileged commands.
+
+ A possible situation in which an issuer might wish to enter
+ interactive mode unauthenticated is if he or she knows that
+ attempting to authenticate will cause a problem, but wants
+ to list some unprivileged information. Attempting to
+ authenticate could cause a problem, for instance, if the
+ Authentication Server no longer knows the key used to seal
+ the ticket the user has (perhaps it is no longer in
+ /usr/afs/etc/KeyFile).
+
+ The other repercussions of entering interactive mode are:
+
+ - A "ka>" prompt replaces the issuer's regular
+ prompt
+
+ - It is no longer necessary or legal to type kas at
+ the beginning of a command. Type the operation
+ code as the first part of the command
+
+ - It is not useful to include the common arguments
+ described in section 4.3 in the Reference Manual :
+
+
+
+ -admin_username, -password_for_admin, -cell,
+ -servers. They are ignored, because the variables
+ corresponding to them are set as the issuer enters
+ interactive mode, and cannot be changed without
+ leaving interactive mode. It is legal to provide
+ the -help flag.
+
+ There are two additional ways to enter interactive mode:
+
+ 1. Type kas without any operation code. By default,
+ the command interpreter establishes a connection
+ with all of the Authentication Servers in the
+ local cell. They attempt to authenticate the
+ user logged into the machine from which the
+ command is issued, based on the password the
+ issuer provides at the prompt. The issuer may
+ specify an alternate identity, password, cell
+ name and/or list of Authentication Servers by
+ using the first four common arguments described
+ in section 4.3 in the Reference Manual . Type
+ kas followed by a user name and cell name,
+ separated by an "@" sign (example: kas
+ smith@transarc.com). The Authentication Server
+ attempts to authenticate the specified user in
+ the specified cell, and prompts for his or her
+ password in the specified cell. This method is
+ most useful when the issuer wishes to enter
+ interactive mode with a different identity than
+ the one under which he or she is currently logged
+ on.
+
+ARGUMENTS
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. Using this
+ argument on this command is useful only
+ when authorization checking is disabled on
+
+
+
+ the file server machine (during the
+ installation of a file server machine or
+ when bos setauth has been used during
+ other unusual circumstances). Under
+ normal authorization checking
+ circumstances, the Authentication Servers
+ will allow only authorized (privileged)
+ users to issue commands that change the
+ status of a server or configuration file,
+ even if the -noauth flag was used when
+ entering interactive mode. See section
+ 4.3 in the Reference Manual for more
+ details. -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+EXAMPLE
+
+ The following shows a user entering interactive mode as the
+ privileged user admin.
+
+ % kas i admin Password for admin: ka>
+
+PRIVILEGE REQUIRED
+
+ None. A password will be prompted for, and something must
+ be typed in response, but the issuer needs to provide the
+ correct password only if he or she wishes to issue
+ privileged commands while in interactive mode. If he or she
+ provides an wrong character string, the Authentication
+ Server assigns the unprivileged identity anonymous.
+
+MORE INFORMATION
+
+ (kas) noauthentication (kas) quit
--- /dev/null
+kas list AFS Commands kas list
+
+
+NAME
+
+ kas list -- list all entries in the Authentication
+
+ Database.
+
+
+ kas list [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ]
+ [-noauth] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas ls [-a <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-n] [-h]
+
+DESCRIPTION
+
+ Lists the names of all the entries (server and individual
+ user) in the Authentication Database.
+
+ARGUMENTS
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. Note
+ that provided here the password is visible
+ on the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+
+
+OUTPUT
+
+ Each entry appears on its own line. Some entries have been
+ created by the Authentication Server for its own internal
+ use (for instance, AuthServer.Admin).
+
+EXAMPLE
+
+ The following example is for the cell small.edu, which has
+ five users in it (the other entries are for the
+ Authentication Server's internal use).
+
+ % kas list AuthServer.Admin krbtgt.SMALL.EDU afs admin
+ pat smith jones terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must have the ADMIN flag set in his or her
+ Authentication Database entry.
+
+MORE INFORMATION
--- /dev/null
+kas listtickets AFS Commands kas listtickets
+
+
+NAME
+
+ kas listtickets -- list all tickets (tokens) for issuer.
+
+
+ kas listtickets [-name <name of server>] [-long] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas listt [-n <name of server>] [-l] [-h]
+
+DESCRIPTION
+
+ Lists all the tickets (tokens) for the issuer, if no
+ arguments are provided. If name of server is provided,
+ lists only the ticket good for that server process ("afs" is
+ the most common server). If the -long switch is provided,
+ the output shows octal strings representing the session key
+ and ticket itself.
+
+ARGUMENTS
+
+ -name specifies the server name for which to list the
+ ticket.
+
+ -long specifies that the output should display the octal
+ number strings constituting the session key and
+ ticket, along with other information (see the OUTPUT
+ section). The session key is the one also found
+ within the ticket.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this one.
+ See section 4.3 in the Reference Manual for more
+ details.
+
+OUTPUT
+
+ The output reports for whom the ticket is valid and the
+ ticket's expiration date. If no cell specification appears,
+ then the ticket is valid in the local cell.
+
+ If the -long flag is used, the output displays the octal
+ numbers making up the session key and ticket, along with the
+ key version number and the number of bytes in the ticket
+ (this should always be 56). If a "[>> POSTDATED <<]" marker
+ appears where the expiration date normally does, the ticket
+ does not become valid until the indicated time. (Only
+ internal calls can create a postdated ticket; there is no
+ standard interface that allows users to do this.)
+
+
+
+EXAMPLES
+
+ The following two examples are for a user with AFS UID 1020
+ in the transarc.com cell and AFS UID 35 in the
+ test.transarc.com cell. He is working on a machine in the
+ former cell and is authenticated in both cells.
+
+ % kas listtickets
+
+ User's (AFS ID 1020) tokens for afs [Expires Wed Jan
+ User's (AFS ID 35@test.transarc.com) tokens for afs@
+ [Expires Wed Jan 3 13:54:26 1990]
+
+ % kas listtickets afs -l
+
+ User's (AFS ID 1020) tokens for afs [Expires Wed Jan
+ SessionKey: \375\205\351\227\032\310\263\013
+ Ticket: (kvno = 0, len = 56): \033\005\221S\203d\312
+
+PRIVILEGE REQUIRED
+
+ None. A password is not prompted for.
+
+MORE INFORMATION
--- /dev/null
+kas noauthentication AFS Commands kas noauthentication
+
+
+NAME
+
+ kas noauthentication -- discard authenticated identity in
+
+ interactive mode.
+
+
+ (kas) noauthentication [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ (kas) n [-h]
+
+DESCRIPTION
+
+ Instructs the Authentication Server to close the (presumably
+ authenticated) connection established when the issuer
+ entered interactive mode. It opens a new unauthenticated
+ connection, assigning the issuer the unprivileged identity
+ anonymous. It does not actually flush the user's tokens
+ from the Cache Manager's memory (as unlog or
+ kas forgetticket do).
+
+ This command is useful only in interactive mode, in which
+ case the issuer should omit the kas command suite name. If
+ issued in non-interactive mode, it has no effect.
+
+ Like the -noauth flag available on a few kas commands (e.g.,
+ kas interactive) this command is only useful in unusual
+ circumstances. During normal operation, there is no point
+ to throwing away an authenticated identity (becoming
+ anonymous). The Authentication Server still does
+ authorization checking and will not allow anonymous, who is
+ unprivileged by definition, to perform privileged commands.
+
+ARGUMENTS
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 4.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following discards the authentication information with
+ which the user entered interactive mode.
+
+ kas> no
+
+
+
+PRIVILEGE REQUIRED
+
+ None. Because this command may be issued only while in
+ interactive mode, no password is prompted for.
+
+MORE INFORMATION
+
+ kas interactive
--- /dev/null
+kas quit AFS Commands kas quit
+
+
+NAME
+
+ kas quit -- leave interactive mode.
+
+
+ (kas) quit [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ (kas) q [-h]
+
+DESCRIPTION
+
+ Leaves interactive mode. This command terminates the
+ authenticated connection, so the Authentication Server will
+ again require a password when another kas command is issued.
+
+ This command is useful only in interactive mode, in which
+ case the issuer should omit the kas command suite name. If
+ issued in non-interactive mode, it has no effect.
+
+ARGUMENTS
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 4.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following shows the return of the normal command shell
+ prompt when the issuer leaves interactive mode.
+
+ ka> quit %
+
+PRIVILEGE REQUIRED
+
+ None. Because this command may be issued only while in
+ interactive mode, no password is prompted for.
+
+MORE INFORMATION
+
+ kas interactive
--- /dev/null
+kas setfields AFS Commands kas setfields
+
+
+NAME
+
+ kas setfields -- set various flags, expiration date and
+
+ ticket lifetime for Authentication
+ Database entry.
+
+
+ kas setfields -name <name of user>
+ [-flags <hex flag value or flag name expression>]
+ [-expiration <date of account expiration>]
+ [-lifetime <maximum ticket lifetime>]
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ]
+ [-noauth] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas sf -na <name of user> [-f <hex flag value or flag name
+ expression>]
+ [-e <date of account expiration>]
+ [-l <maximum ticket lifetime>]
+ [-ad <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Changes the Authentication Database entry for name of user
+ in the manner specified by the various optional arguments,
+ which may occur singly or in combination. See the ARGUMENTS
+ section for a description of the values that may be set.
+
+ The results of this command are visible in the output of the
+ kas examine command.
+
+ARGUMENTS
+
+ -name specifies the entry to be affected.
+
+ -flags sets any one of four toggling flags in name's
+ entry. The default is for none of the flags to be
+ set. A value of 0 returns all four flags to their
+ defaults. The following explains the four
+ non-default values to set, their meanings and the
+ associated defaults:
+
+ - ADMIN (Hex equivalent: 0x004). The name of
+ user is allowed to issue privileged kas
+ commands (Default: NOADMIN).
+
+ - NOTGS (Hex equivalent: 0x008). The Ticket
+ Granting Service will refuse to issue tickets
+ to name of user (Default: TGS).
+
+ - NOSEAL (Hex equivalent: 0x020). The Ticket
+
+
+
+ Granting Service cannot use the contents of
+ this entry's key field as an encryption key
+ (Default: SEAL).
+
+ - NOCPW (Hex equivalent: 0x040). The name of
+ user cannot change his/her/its own password
+ or key (Default: CPW).
+
+ Both upper and lower-case letters are acceptable
+ in specifying values for the flags.
+
+ To restore the ADMIN flag to its default, specify
+ NOADMIN. To restore the other flags to their
+ defaults, omit the NO (i.e., type TGS, SEAL or
+ CPW).
+
+ To set more than one flag at once, connect them
+ with plus signs (example: NOTGS+ADMIN+CPW). To
+ remove all the current flag settings before
+ setting new ones, precede the whole list with an
+ equal sign (example: =NOTGS+ADMIN+CPW).
+
+ -expiration
+ determines when the entry itself expires, which
+ will render an individual user unable to log in to
+ the system, and a server unreachable. The default
+ is never.
+
+ There are three types of legal values:
+
+ - never, which allows the issuer to return
+ the expiration time to its default after
+ having set it to a date.
+
+ - mm/dd/yy specifies 12:00 a.m. on the
+ indicated date (month/day/year).
+ Examples : 1/23/90, 10/7/89.
+
+ - "mm/dd/yy hh:mm" specifies a time
+ "hh:mm" (hour:minutes) on the indicated
+ date (month/day/year). The time should
+ be in 24-hour format (for example, 20:30
+ is 8:30 p.m.) Date format is the same
+ as for a date alone. Surround the
+ entire instance with quotes because it
+ contains a space. Examples : "1/23/90
+ 22:30", "10/7/89 3:45".
+
+ Legal values for yy run from 00 to 37, which are
+ interpreted as the years 2000-2037, and from 70 to
+ 99 which are interpreted as 1970-1999. (This
+ restriction is because the Authentication Server
+ converts the date into the number of seconds
+ elapsed since 1 February 1970, to comply with the
+ standard UNIX date representation; dates later
+ than sometime in February 2038 exceed the
+ representation's capacity.)
+
+ -lifetime specifies the upper limit on the validity lifetime
+ that the TGS may stamp on a ticket issued to an
+ individual or for a server. That is, if name of
+
+
+
+ user is an individual, this value is the maximum
+ lifetime of a ticket issued to the user. If name
+ of user is a server such as "afs," this value is
+ the maximum lifetime of a ticket that the TGS
+ issues to clients in order to contact the server.
+
+ To specify a number of hours, include a colon in
+ the number (example: 1:00 means one hour).
+ Otherwise, the number is assumed to be in seconds
+ (so 3600 means one hour). If this argument is not
+ provided, the default setting is 100:00 hours
+ (360000 seconds).
+
+ -admin_username
+ specifies the user name under which the issuer
+ wishes to perform the command. If the issuer does
+ not provide it, the current identity is used. See
+ section 4.3 in the Reference Manual for more
+ details. -password_for_admin
+ specifies the issuer's password. If provided
+ here, the password is visible on the screen. If
+ the issuer does not provide it, it will be
+ prompted for and not be visible on the screen.
+ See section 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the command, if
+ not the local cell. See section 4.3 in the
+ Reference Manual for more details. -servers
+ specifies the database server machine(s) with
+ which to establish a connection. See section 4.3
+ in the Reference Manual for more details. -noauth
+ establishes an unauthenticated connection between
+ the Authentication Servers and issuer, whom they
+ assign the unprivileged identity anonymous rather
+ than attempting mutual authentication. See
+ section 4.3 in the Reference Manual for more
+ details.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 4.3 in the Reference Manual for
+ more details.
+
+EXAMPLE
+
+ In the following, admin grants administrative privilege to
+ smith, and makes smith's entry expire at midnight on 31
+ December 1995.
+
+ % kas sf smith ADMIN 12/31/95 Password for admin:
+
+PRIVILEGE REQUIRED
+
+ Issuer must have the ADMIN flag set in his or her
+ Authentication Database entry.
+
+MORE INFORMATION
+
+ kas examine
--- /dev/null
+kas setkey AFS Commands kas setkey
+
+
+NAME
+
+ kas setkey -- insert octal key directly into key field of
+
+ Database entry.
+
+
+ kas setkey -name <name of user> -new_key <eight byte new
+ key> [-kvno <keyversion number>]
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of authentication servers> ]
+ [-noauth] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas setk -na <name of user> -ne <eight byte new key>
+ [-k <key version number>]
+ [-a <admin principal to use for authentication>] [-p <admin
+ password>]
+ [-c <cell name>] [-s <explicit list of authentication
+ +
+ servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Accepts the octal number string eight byte new key, places
+ it in the key field of the Database entry for name of user
+ and marks it with key version number key version number.
+ This command makes most sense when name of user is a server
+ process (such as "afs") rather than an individual user, as
+ discussed in the Warning section. For individual users, use
+ the kas setpassword command instead.
+
+ When changing the key in a server entry, remember to alter
+ the /usr/afs/etc/KeyFile with the bos addkey command and use
+ the same key version number in both places.
+
+WARNING
+
+ Using this command to change user passwords is needlessly
+ complicating, for the following reason. The Authentication
+ Database stores both user passwords and server keys as octal
+ strings, never as character strings. When a character
+ string is provided in the kas setpassword command (see
+ above), the Authentication Server calls an algorithm to
+ convert the string into an octal-form encryption key, then
+ stores the key in the key field of the appropriate entry.
+ The kas setkey command (this one) bypasses the conversion
+ algorithm, entering eight byte new key directly into the key
+ field. If an octal string is simply invented, there is no
+ way to discover which character string it corresponds to.
+ To use this command to change a user password, the issuer
+ would need to translate the password character string into
+ an octal key using kas stringtokey and specify the
+ resulting string as eight byte new key here. Otherwise, the
+ user would not know what password to type at login.
+
+ The main use for this command is to set server encryption
+
+
+
+ keys, if the system administrator first executes the bos
+ addkey command to add a new key to /usr/afs/etc/KeyFile.
+ That command accepts only strings and converts them into
+ octal keys, just like kas setpassword, but the output from
+ the bos listkeys command will then reveal the converted
+ octal form of the string, which is the eight byte new key
+ that should be specified here.
+
+ARGUMENTS
+
+ -name specifies the entry for which to replace
+ the key field.
+
+ -new_key specifies a string of eight bytes, each
+ consisting of EITHER a three-digit octal
+ number preceded by a backslash OR a single
+ ASCII character. The issuer must provide
+ it on the command line where it is
+ visible, as there is no prompt for it.
+
+ Outside interactive mode, surround
+ octalkey with single quotes, or the shell
+ will throw away the backslashes. When in
+ interactive mode, do not include the
+ single quotes.
+
+ -kvno specifies the key version number
+ associated with the new key. It must be
+ an integer in the range 0 through 255. In
+ addition, 999 is reserved for the "bcrypt"
+ key used in AFS 2.0 authentication. If
+ the issuer does not provide this argument,
+ it defaults to 0, which is probably not
+ desirable for server keys.
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+
+
+
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+
+
+EXAMPLE
+
+ The following shows admin setting the "afs" key with key
+ version number 15.
+
+ % kas setk afs \222\260\334\241c\212\274W 15 Password for
+ admin:
+
+PRIVILEGE REQUIRED
+
+ Individual users may use this command to change their own
+ keys, though this is not advised for the reasons stated in
+ the WARNING section. To change server encryption keys or
+ the key field in another user's entry, issuer must have the
+ ADMIN flag set in his or her Authentication Database entry.
+
+MORE INFORMATION
+
+ bos addkey bos listkeys kas setpassword
--- /dev/null
+kas setpassword AFS Commands kas setpassword
+
+
+NAME
+
+ kas setpassword -- change key field in Database entry.
+
+
+ kas setpassword -name <name of user>
+ [-new_password <new password>]
+ [-kvno <key version number>]
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ]
+ [-noauth] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas sp -na <name of user> [-ne <new password>]
+ [-k <key version number>]
+ [-a <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-no] [-h]
+
+DESCRIPTION
+
+ Accepts a character string new password of unlimited length,
+ scrambles it into a form suitable for use as an encryption
+ key, and places it in the key field of name's Authentication
+ Database entry.
+
+ There is little reason to type new password on the command
+ line, where it is visible. If the issuer does not provide
+ the password on the command line, a
+
+ new_password:
+
+ prompt appears, followed by a second prompt requesting a
+ repetition of the new password. In both cases the password
+ does not echo visibly. The second prompt guarantees that
+ the issuer did not make a typing mistake when responding to
+ the first prompt.
+
+ When adding server keys (such as "afs"), remember to add the
+ new key to the /usr/afs/etc/KeyFile using the bos addkey
+ command and to use the same key version number there as
+ here. See the AFS System Administrator's Guide for
+ instructions.
+
+
+
+ARGUMENTS
+
+ -name specifies the entry for which to replace
+ the key field.
+
+ -new_password is the character string the user will type
+ when logging in. It should be 8
+ characters or less, as some non-AFS
+ programs cannot handle longer passwords.
+ The Authentication Server scrambles it
+ into a string of octal numbers before
+ storing it in the key field.
+
+ -kvno specifies the key version number
+ associated with the new key. It must be
+ an integer between 0 and 255. In
+ addition, 999 is reserved for the "bcrypt"
+ key used in AFS 2.0 authentication. If
+ the issuer does not provide this argument,
+ it defaults to 0, which is probably not
+ desirable for server keys.
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the
+ current identity is used. See section 4.3
+ in the Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. If
+ provided here, the password is visible on
+ the screen. If the issuer does not
+ provide it, it will be prompted for and
+ not be visible on the screen. See section
+ 4.3 in the Reference Manual for more
+ details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See
+ section 4.3 in the Reference Manual for
+ more details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. See
+ section 4.3 in the Reference Manual for
+ more details. -noauth
+ establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command.
+ Do not provide any other arguments or
+ flags with this one. See section 4.3 in
+ the Reference Manual for more details.
+
+EXAMPLE
+
+ The following shows privileged user admin changing pat's
+ password (presumably because pat forgot the former password
+ or got locked out of his account in some other way.
+
+
+
+ % kas sp pat
+ Password for admin:
+ new_password:
+ Verifying, please re-enter new_password:
+
+
+
+PRIVILEGE REQUIRED
+
+ An individual user may change his or her own password,
+ although use of the kpasswd command is recommended instead.
+ To change another user's password or the password (server
+ encryption key) for server processes such as "afs", issuer
+ must have the ADMIN flag set in his or her Authentication
+ Database entry.
+
+MORE INFORMATION
+
+ bos addkey kas setkey
--- /dev/null
+kas statistics AFS Commands kas statistics
+
+
+NAME
+
+ kas statistics -- display statistics from one
+
+ Authentication Server process.
+
+
+ kas statistics
+ [-admin_username <admin principal to use for
+ authentication>]
+ [-password_for_admin <admin password>] [-cell <cell name>]
+ [-servers <explicit list of authentication
+ +
+ servers> ]
+ [-noauth] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas sta [-a <admin principal to use for authentication>]
+ [-p <admin password>] [-c <cell name>]
+ +
+ [-s <explicit list of authentication servers> ] [-n] [-h]
+
+DESCRIPTION
+
+ Displays statistics from one of the cell's database server
+ machines. It is recommended that the issuer use -servers to
+ specify one machine name. Otherwise, the command
+ interpreter displays statistics for a machine chosen at
+ random from all the database server machines with which it
+ has established connections.
+
+WARNING
+
+ If this command is issued in interactive mode, it is not
+ possible to specify a file server machine because the
+ -servers argument is inoperative. If the issuer is
+ interested in a particular file server machine, it is best
+ to leave interactive mode.
+
+ARGUMENTS
+
+ -admin_username specifies the user name under which the
+ issuer wishes to perform the command. If
+ the issuer does not provide it, the current
+ identity is used. See section 4.3 in the
+ Reference Manual for more details.
+ -password_for_admin
+ specifies the issuer's password. Note that
+ provided here the password is visible on the
+ screen. If the issuer does not provide it,
+ it will be prompted for and not be visible
+ on the screen. See section 4.3 in the
+ Reference Manual for more details. -cell
+ specifies the cell in which to run the
+ command, if not the local cell. See section
+ 4.3 in the Reference Manual for more
+ details. -servers
+ specifies the database server machine(s)
+ with which to establish a connection. It is
+ recommended that the issuer use this
+
+
+
+ argument and specify a single machine.
+
+ -noauth establishes an unauthenticated connection
+ between the Authentication Servers and
+ issuer, whom they assign the unprivileged
+ identity anonymous rather than attempting
+ mutual authentication. See section 4.3 in
+ the Reference Manual for more details.
+ -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 4.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The information includes:
+
+ - server's network address number and last startup
+ date
+
+ - number of requests and aborted requests for
+ various services: authentication, ticket
+ granting, password setting, entry listing, etc
+
+ - number of entries with ADMIN flag
+
+EXAMPLE
+
+ The following show the output when someone authenticated as
+ the privileged user admin issues this command about
+ fs1.transarc.com.
+
+ % kas stat -s fs1.transarc.com
+ 56 allocs, 46 frees, 0 password changes
+ Hash table utilization = 0.100000%
+ From host c037cf05 started at Tue Mar 20 12:42:02 19
+ of 88 requests for Authenticate, 18 were aborted.
+ of 14 requests for GetTicket, 0 were aborted.
+ of 4 requests for CreateUser, 1 were aborted.
+ of 12 requests for SetFields, 4 were aborted.
+ of 3 requests for DeleteUser, 0 were aborted.
+ of 23 requests for GetEntry, 4 were aborted.
+ of 18 requests for ListEntry, 0 were aborted.
+ of 2 requests for GetStats, 1 were aborted.
+ of 2 requests for GetRandomKey, 0 were aborted.
+ Used 6.015 seconds of CPU time.
+ 1 admin accounts
+
+PRIVILEGE REQUIRED
+
+ Issuer must have the ADMIN flag set in his or her
+ Authentication Database entry.
+
+MORE INFORMATION
+
+ kas debuginfo
--- /dev/null
+kas stringtokey AFS Commands kas stringtokey
+
+
+NAME
+
+ kas stringtokey -- convert a character string into an octal
+
+ string.
+
+
+ kas stringtokey -string <password string> [-cell <cell
+ name>] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kas str -s <password string> [-c <cell name>] [-h]
+
+DESCRIPTION
+
+ Converts the character string password string into an octal
+ string suitable for use as an encryption key. This is
+ useful for showing what form a given password would take in
+ the cell.
+
+ The algorithm that the Authentication Server uses to
+ generate keys combines password string with the cell's name
+ during the generation, so use of cell name allows the issuer
+ to see what a string would look like when scrambled into a
+ key in a certain cell.
+
+ARGUMENTS
+
+ -string specifies the password-like character string
+ to be converted into a key.
+
+ -cell specifies the cell name to be used in
+ converting password string into a key. If
+ the issuer does not provide it, the default
+ is the cell in which the command is issued.
+ Provide a complete Internet-style name.
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 4.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The output is of the form:
+
+ Converting password string in realm 'cell name yield
+
+EXAMPLE
+
+ The following shows a user in the Transarc Corporation cell
+ deriving the octal key equivalent of the string "new_pswd".
+
+ % kas str new_pswd
+ Converting new_pswd in realm 'TRANSARC.COM' yields
+ key='\255\364b\354\221s\235\313'.
+
+
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ kas getrandomkey kas setkey
--- /dev/null
+klog AFS Commands klog
+
+
+NAME
+
+ klog -- authenticate with Authentication Server to obtain
+
+ token.
+
+
+ klog [-x] [-principal <user name>] [-password <user's
+ password>]
+ [-tmp] [-cell <cell name>] [-servers <explicit list of
+ +
+ servers> ]
+ [-pipe] [-lifetime <ticket lifetime in hh[:mm[:ss]]>]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ klog [-x] [-pr <user name>] [-pa <user's password>] [-t]
+ [-c <cell name>]
+ +
+ [-s <explicit list of servers> ] [-pi]
+ [-l <ticket lifetime in hh[:mm[:ss]]>] [-h]
+
+DESCRIPTION
+
+ Authenticates the issuer in the indicated cell. The issuer
+ obtains a token accepted by the AFS server processes in that
+ cell. The Cache Manager stores the token in a credential
+ structure associated with the issuer. If the issuer already
+ has a token for the cell, the token resulting from this
+ command replaces it in the credential structure.
+
+ By default, the token generated is appropriate for the local
+ cell (the one to which the local machine belongs): the
+ command interpreter contacts an Authentication Server in the
+ local cell, chosen at random from the list in
+ /usr/vice/etc/CellServDB, and requests a token for the
+ issuer logged into the local machine. Use the -principal,
+ -cell and/or -servers arguments to specify a different
+ identity, cell or set of Authentication Servers
+ respectively. See the ARGUMENTS section for further
+ explanation.
+
+ This command does not change the identity under which the
+ issuer is logged into the local UNIX file system.
+
+ The issuer (or user indicated with -principal) does not have
+ to appear in the local password file (/etc/passwd or
+ equivalent) to issue this command; in previous versions of
+ this command, users had to add the -x flag if they did not
+ appear in that file.
+
+ During a single login on a given machine, a user can be
+ authenticated in multiple cells simultaneously, but can have
+ only one token at a time for each cell (i.e., can only
+ authenticate under one identity per cell).
+
+ The lifetime of the token resulting from this command is the
+ smallest of the following:
+
+ - the lifetime requested by the issuer with the
+
+
+
+ -lifetime argument. If the issuer does not
+ include this argument, the value defaults to 720
+ hours (30 days).
+
+ - the "maximum ticket lifetime" recorded in the
+ "afs" entry in the Authentication Database. The
+ default is 100 hours. Administrators can inspect
+ this value using kas examine, and change it using
+ kas setfields.
+
+ - the "maximum ticket lifetime" recorded in the
+ issuer's Authentication Database entry. The
+ default is 25 hours for user entries created by
+ the AFS 3.1 or later version of the Authentication
+ Server, and 100 hours for user entries created by
+ the AFS 3.0 version of the Authentication Server.
+ Administrators and the user himself/herself can
+ inspect this value using kas examine, and
+ administrators can change it using kas setfields.
+
+ - the "maximum ticket lifetime" recorded in the
+ "krbtgt.CELLNAME" entry in the Authentication
+ Database; this entry corresponds to the ticket-
+ granting ticket used internally in generating the
+ token. The default is 720 hours (30 days).
+
+ If none of these defaults have been changed, then the
+ standard token lifetime is 25 hours for users whose
+ Authentication Database entries were created by the AFS 3.1
+ or later version of the Authentication Server, and 100 hours
+ for users whose Authentication Database entries were created
+ by the AFS 3.0 version of the Authentication Server. The
+ user can issue klog to request a token with a different
+ lifetime.
+
+ The maximum lifetime for any token is 720 hours (30 days),
+ and the minimum is 5 minutes. Between these values, token
+ lifetimes are not granted on a linear scale; only certain
+ values are possible.
+
+ Lifetimes between 5 minutes and 10 hours 40 minutes are
+ granted at 5 minute intervals, rounding up. For example, if
+ the issuer requests a lifetime of 12 minutes, the token's
+ actual lifetime is 15 minutes.
+
+ For token lifetimes greater than 10 hours 40 minutes,
+ consult the following table, which presents the possible
+ times in units of hours:minutes:seconds. The number in
+ parentheses is a translation to daysd hoursh; the minutes
+ and seconds are the same as in the corresponding hourly
+ time. For example, 282:22:17 means 282 hours, 22 minutes
+ and 17 seconds, which translates to 11d 18h (11 days and 18
+ hours, etc.). If the issuer requests a lifetime between two
+ values, the token's lifetime is rounded up to the higher
+ value.
+
+ 11:24:15 (0d 11h) 33:14:21 (1d 09h)
+ 12:11:34 (0d 12h) 35:32:15 (1d 11h)
+ 13:02:09 (0d 13h) 37:59:41 (1d 13h)
+ 13:56:14 (0d 13h) 40:37:19 (1d 16h)
+ 14:54:03 (0d 14h) 43:25:50 (1d 19h)
+
+
+
+ 15:55:52 (0d 15h) 46:26:01 (1d 22h)
+ 17:01:58 (0d 17h) 49:38:40 (2d 01h)
+ 18:12:38 (0d 18h) 53:04:37 (2d 05h)
+ 19:28:11 (0d 19h) 56:44:49 (2d 08h)
+ 20:48:57 (0d 20h) 60:40:15 (2d 12h)
+ 22:15:19 (0d 22h) 64:51:57 (2d 16h)
+ 23:47:38 (0d 23h) 69:21:04 (2d 21h)
+ 25:26:21 (1d 01h) 74:08:46 (3d 02h)
+ 27:11:54 (1d 03h) 79:16:23 (3d 07h)
+ 29:04:44 (1d 05h) 84:45:16 (3d 12h)
+ 31:05:22 (1d 07h) 90:36:53 (3d 18h)
+
+WARNING
+
+ This command does not create a new "process authentication
+ group" (commonly abbreviated PAG; see the description of the
+ pagsh command in this chapter to learn about PAGs). Users
+ in cells not using the AFS version of login should issue
+ pagsh before issuing this command, so that the tokens get
+ stored in a credential structure that is identified by PAG
+ rather than UNIX UID. The potential security problem with a
+ credential structure identified by UID is that anyone
+ already logged in as "root" on a machine is allowed to
+ assume any other identity by issuing su. If the credential
+ structure is identified by UID rather than PAG, then when
+ "root" assumes another UID it can use the token, too. Use
+ of a PAG as an identifier eliminates that possibility.
+
+ If the issuer entered the current session by issuing the AFS
+ login command, his or her credential structure is already
+ identified by a PAG. Issuing klog during the same session
+ creates a new token associated with the existing PAG.
+
+ARGUMENTS
+
+ -x appears only for backwards compatibility. Its
+ former function is now the default behavior of
+ this command, as mentioned in the DESCRIPTION
+ section.
+
+ -principal
+ is the user name under which the issuer wishes to
+ authenticate. By default, the Authentication
+ Server attempts to authenticate the user logged
+ into the local machine's UNIX file system. This
+ argument allows the issuer to specify a different
+ user name.
+
+ -password specifies the issuer's password (or that of user
+ name if principal is provided). Use of this
+ argument is STRONGLY DISCOURAGED, as it makes the
+ password visible on the command line. If the
+ issuer omits this argument, klog prompts for the
+ password and does not echo it visibly:
+
+ Password: <user's password>
+
+ -tmp indicates that a copy of the "ticket-granting
+ ticket" should be placed in a file on the local
+ machine's /tmp directory. The file is called
+ /tmp/tktUnix_UID (example for user with UNIX UID
+
+
+
+ 1000: /tmp/tkt1000).
+
+ The ticket-granting ticket is an intermediate
+ ticket that the Ticket Granting Service requires
+ of clients who desire server tickets (the extra
+ level of indirection increases security). Putting
+ the ticket-granting ticket into /tmp allows
+ standard Kerberos applications to access it and
+ use it for obtaining server tickets. If this flag
+ is omitted, the Cache Manager discards the
+ ticket-granting ticket after it obtains the AFS
+ server ticket.
+
+ -cell specifies the cell in which the issuer wishes to
+ authenticate, by directing the command to that
+ cell's Authentication Servers. During a single
+ login on a given machine, a user may be
+ authenticated in multiple cells simultaneously,
+ but can have only one token at a time for each of
+ them (i.e., can only authenticate under one
+ identity per cell per machine).
+
+ If this argument is omitted, the command is
+ executed in the local cell, as defined in
+ /usr/vice/etc/ThisCell on the client machine on
+ which the command is issued. The issuer may
+ abbreviate cell name to the shortest form that
+ distinguishes it from the other cells listed in
+ /usr/vice/etc/CellServDB on the client machine on
+ which the command is issued.
+
+ -servers causes the command interpreter to establish a
+ connection with the Authentication Server running
+ on each specified database server machine. It
+ then chooses one of these at random to execute the
+ command. The command accepts shortened machine
+ names, but exactly which abbreviations are
+ acceptable depends on the state of the cell's name
+ server at the time the command is issued.
+
+ If this argument is omitted, the command
+ interpreter establishes a connection with each
+ machine listed for the indicated cell in the local
+ workstation's copy of /usr/vice/etc/CellServDB,
+ and then chooses one of those at random for
+ command execution.
+
+ This option is useful for testing specific servers
+ if problems are encountered.
+
+ -pipe indicates that the command should run without
+ printing anything on the screen, including prompts
+ or error messages. The klog command interpreter
+ Server expects to receive the password from
+ standard input (stdin). The issuer is discouraged
+ from using this argument; it is for use by
+ application programs rather than human users.
+
+ -lifetime indicates the lifetime that the issuer wishes the
+ token to have. The value provided is considered
+ in the lifetime calculation described in the
+
+
+
+ DESCRIPTION section above, along with the maximum
+ ticket lifetimes mentioned there. The DESCRIPTION
+ section also explains how the actual lifetime of
+ the token is determined, since not all times are
+ possible. If this argument is not provided, it
+ defaults to 720 hours. The format for specifying
+ the lifetime is
+
+ hh[:mm[:ss]]
+
+ Legal values for hh (hours) range from 00 through
+ 720. Legal values for mm and ss (minutes and
+ seconds) range from 00 through 59.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one.
+
+EXAMPLES
+
+ Most often, this command is issued without arguments. The
+ appropriate password is for the person currently logged into
+ the local UNIX file system. The ticket's lifetime is
+ calculated as described in the DESCRIPTION section above (if
+ no defaults have been changed, it is 25 hours for a user
+ whose Authentication Database entry was created by the AFS
+ 3.1 or later version of the Authentication Server, 100 hours
+ for a user whose Authentication Database entry was created
+ with the AFS 3.0 version).
+
+ % klog Password:
+
+ The following allows the issuer working on a machine in the
+ Transarc cell to authenticate as admin in the Transarc test
+ cell, even though he or she is logged into the Transarc
+ machine under a different name.
+
+ % klog admin -c test.transarc.com Password: <admin's
+ password>
+
+ In the following, the issuer requests a ticket lifetime of
+ 104 hours 30 minutes (4 days 8 hours 30 minutes). Presuming
+ that this lifetime is allowed by the maximum ticket
+ lifetimes and other factors described in the DESCRIPTION
+ section, the token will have an actual lifetime of
+ 110:44:28, which the next largest possible value.
+
+ % klog -life 104:30 Password:
+
+
+
+PRIVILEGE REQUIRED
+
+ None. An entry for the issuer must exist in the
+ Authentication Database, and the issuer must supply the
+ correct password.
+
+MORE INFORMATION
+
+ pagsh
--- /dev/null
+knfs AFS Commands knfs
+
+
+NAME
+
+ knfs -- enable authenticated access to AFS from non-
+
+ supported NFS client using NFS/AFS
+ Translator.
+
+
+ knfs -host <host name> [-id <user ID (decimal)>]
+ [-unlog] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ knfs [-ho <host name>] [-i <user ID (decimal)>] [-u]
+ [-he]
+
+DESCRIPTION
+
+ When issued on an NFS/AFS Translator machine, creates a PAG
+ associated with the indicated NFS client machine (host
+ name), and optionally, the user ID (user ID) that the issuer
+ is using on host name. It associates the issuer's existing
+ AFS token(s) with a new credential structure identified by
+ the new PAG.
+
+ Issue this command only over a connection (perhaps
+ established at the console or via telnet) to the AFS client
+ machine serving as the NFS/AFS translator machine for host
+ name, never on the NFS client machine itself. Before
+ issuing it, obtain AFS tokens on the translator machine for
+ every cell to be contacted during the login session on host
+ name. The Cache Manager on the translator machine then uses
+ the credential structure identified by the new PAG when
+ accessing AFS on behalf of the issuer working on the NFS
+ client machine. (If the issuer dos not use the -id
+ argument, he or she may actually be sharing the credential
+ structure with other users on the NFS client machine; see
+ the WARNINGS section for details.)
+
+ This command allows the issuer to obtain authenticated
+ access to AFS (via the NFS/AFS Translator) while working on
+ an NFS client machine (host name) of a system type for which
+ AFS is not available. Users working on NFS client machines
+ of system types for which AFS is available (and for which
+ the cell has purchased a license) do not need this command,
+ because the klog command is available for those machine
+ types.
+
+ The -unlog flag discards the tokens in the credential
+ structure identified by the PAG, but does not destroy the
+ credential structure itself. The Cache Manager on the
+ translator machine retains the credential structure until
+ the next reboot, and uses it each time the issuer accesses
+ AFS through the translator machine. The credential
+ structure only has tokens in it if the issuer re-issues knfs
+ on the translator machine each time he or she logs into the
+ NFS client machine.
+
+WARNINGS
+
+ Although the -id argument is optional, not using it can
+
+
+
+ create potential security problems and confusion about which
+ users are using which tokens, as described in the following.
+
+ The security problems arise because if the issuer does not
+ use -id, then his or her tokens are associated with a
+ "generic" credential structure identified by a PAG that is
+ associated only with host name, not with the specific
+ issuer. Every user working on host name who also does not
+ use the -id argument shares the same generic credential
+ structure and so uses the issuer's tokens. This includes
+ users on host name who do not issue knfs at all. If another
+ user subsequently issues knfs without -id, his or her tokens
+ replace the previous issuer's tokens in the credential
+ structure, and everyone shares the new tokens instead.
+ Similarly, when an issuer discards tokens with the -unlog
+ flag and does not use -id, then everyone using the generic
+ credential structure becomes unauthenticated at the same
+ time.
+
+ The sharing of tokens that result from not using -id is
+ acceptable from a security standpoint only if
+
+ - host name is used by only one person
+
+ - it is acceptable that all of host name's users who
+ do not have their own credential structure (do not
+ use -id) have the same access to AFS files. They
+ should be aware that they are subject to token
+ sharing.
+
+ The DESCRIPTION section mentioned that using the -unlog flag
+ does not destroy the credential structure, but only discards
+ the tokens associated with it. The Cache Manager on the
+ translator machine retains the credential structure until
+ the next reboot and uses it whenever the issuer accesses AFS
+ through the translator machine. One implication is that
+ once the issuer issues knfs using the -id argument, he or
+ she cannot use the generic credential structure until the
+ machine is rebooted.
+
+ This command does not make it possible for users working on
+ non-supported machine types to issue AFS commands. This is
+ possible only on NFS clients of a system type for which AFS
+ is available (and for which the cell has purchased AFS).
+
+ARGUMENTS
+
+ -host names the NFS client machine the issuer is
+ working on. A full name is safest, but
+ abbreviated forms are acceptable depending
+ on the state of the cell's name server at
+ the time the command is issued.
+
+ -id specifies the issuer's user ID on the NFS
+ client (a UNIX UID or equivalent), which NFS
+ passes to the translator machine to identify
+ the user.
+
+ -unlog discards the tokens in the credential
+ structure identified by the PAG associated
+ with -host and, optionally, -id.
+
+
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one.
+
+EXAMPLE
+
+ The following shows a typical use of this command. The
+ issuer smith is working on nfs-client1.transarc.com and has
+ user ID 1020 on that machine. He is accessing AFS through
+ the translator machine called translator4.transarc.com. He
+ telnets to translator4 and uses AFS login as smith in the
+ Transarc cell. He the uses klog to obtain tokens in the
+ Transarc test cell (test.transarc.com) as admin. The knfs
+ command instructs the Cache Manager on translator4 to
+ associate both tokens with the PAG identified by nfs-client1
+ and user ID 1020. He exits the telnet connection and works
+ normally on nfs-client1.
+
+ % telnet translator4.transarc.com
+ . . .
+ login: smith
+ Password:
+ AFS 3.2 (R) login
+ % klog admin -c test.transarc.com
+ Password:
+ % knfs nfs-client1.transarc.com 1020
+ % exit
+
+ The following shows smith telnetting again to translator4
+ and discarding his tokens.
+
+ % telnet translator4.transarc.com
+ . . .
+ login: smith
+ Password:
+ AFS 3.2 (R) login
+ % knfs nfs-client1.transarc.com 1020 -unlog
+ % exit
+
+PRIVILEGE REQUIRED
+
+ None, but issuer must provide correct password(s) when
+ obtaining tokens on translator machine.
+
+MORE INFORMATION
+
+ klog login (AFS version) pagsh
--- /dev/null
+kpasswd AFS Commands kpasswd
+
+
+NAME
+
+ kpasswd -- change password in Authentication Database.
+
+
+ kpasswd [-x] [-principal <user name>]
+ [-password <user's current password>]
+ [-newpassword <user's new password>] [-cell <cell name>]
+ +
+ [-servers <explicit list of servers> ] [-pipe] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ kpasswd [-x] [-pr <user name>] [-pa <user's password>]
+ [-n <user's new password>] [-c <cell name>] [-s <explicit
+ +
+ list of servers> ]
+ [-pi] [-h]
+
+DESCRIPTION
+
+ Changes password for indicated user in Authentication
+ Database. By default, the change occurs in the local cell's
+ Authentication Database for the user logged into the local
+ machine's UNIX file system.
+
+ The issuer (or user indicated with -principal) does not have
+ to appear in the local password file (/etc/passwd or
+ equivalent) to issue this command; in previous versions of
+ this command, users had to add the -x flag if they did not
+ appear in that file.
+
+ARGUMENTS
+
+ -x appears only for backwards compatibility.
+ Its former function is now the default
+ behavior of this command, as mentioned in
+ the DESCRIPTION section.
+
+ -principal names the Authentication Database entry in
+ which to change the password. If this
+ argument is omitted, the change is in the
+ entry of the person logged into the local
+ machine's UNIX file system.
+
+ -password specifies the current password. It is NOT
+ recommended that the issuer provide this
+ argument on the command line. If it is
+ omitted, the new password is prompted for
+ and does not echo visibly:
+
+ Old password: <user's password>
+
+ -newpassword specifies the new password, which the
+ kpasswd command interpreter converts into an
+ encryption key (string of octal numbers)
+ before sending it to the Authentication
+ Server for storage in the user's
+ Authentication Database entry. Unlike the
+ UNIX passwd command, kpasswd does not
+ restrict passwords to 8 characters; it
+
+
+
+ accepts passwords of virtually any length.
+ All AFS commands that require passwords
+ (klog, the kas suite, kpasswd, and the AFS
+ version of login) can handle passwords
+ longer than 8 characters, but some non-AFS
+ programs cannot. This is a consideration if
+ non-AFS programs handle AFS passwords in the
+ local environment.
+
+ It is NOT recommended that the issuer
+ provide this argument on the command line.
+ If it is omitted, it is prompted for and
+ does not echo visibly:
+
+ New password (RETURN to abort): <new pas
+ Retype new password: <new password>
+
+ -cell specifies the cell in which to change the
+ password, by directing the command to that
+ cell's Authentication Servers. By default,
+ the command is executed in the local cell,
+ as defined in /usr/vice/etc/ThisCell on the
+ client machine on which the command is
+ issued. The issuer may abbreviate cell name
+ to the shortest form that distinguishes it
+ from the other cells listed in
+ /usr/vice/etc/CellServDB on the client
+ machine on which the command is issued.
+
+ -servers causes the command interpreter to establish
+ a connection with the Authentication Server
+ running on each specified database server
+ machine. It then chooses one of these at
+ random to execute the command. The issuer
+ may abbreviate the machine name to the
+ extent the cell's name server will accept.
+
+ By default, the command interpreter
+ establishes a connection with each machine
+ listed for the indicated cell in the local
+ workstation's copy of
+ /usr/vice/etc/CellServDB, and then chooses
+ one of those at random for command
+ execution.
+
+ This option is useful for testing specific
+ servers if problems are encountered.
+
+ -pipe indicates that the command should run
+ without printing anything on the screen,
+ including prompts or error messages. The
+ kpasswd command interpreter expects to
+ receive all necessary arguments, each on a
+ separate line, from standard input (stdin).
+ The issuer is discouraged from including
+ this argument; it is for use by application
+ programs rather than human users.
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one.
+
+
+
+EXAMPLE
+
+ The following shows the typical use of this command, when
+ the issuer wishes to change his or her own password.
+
+ % kpasswd
+ Changing password for 'user' in cell 'cellname'.
+ Old password:
+ New password (RETURN to abort):
+ Verifying, please re-enter new_password:
+
+PRIVILEGE REQUIRED
+
+ Issuer must provide correct current password.
+
+MORE INFORMATION
+
+ klog
+
+ kas setpassword
--- /dev/null
+package AFS Commands package
+
+
+NAME
+
+ package -- configure local disk.
+
+
+ package [-config <base name of configuration file>]
+ [-fullconfig <full name of config file> OR stdin for
+ standard input]
+ [-overwrite] [-noaction] [-silent] [-verbose]
+ [-rebootfiles]
+ [-debug] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ package [-c <base name of configuration file>]
+ [-f <full name of config file> OR stdin for standard input]
+ [-o] [-n] [-s] [-v] [-r] [-d] [-h]
+
+DESCRIPTION
+
+ Configures the machine's local disk to comply with the
+ indicated configuration file. By default, package does
+ nothing to elements on disk that have no counterpart in the
+ configuration file, but the issuer can have package remove
+ any element found in a directory on disk that is not also
+ found in that directory in the configuration file. See the
+ "R" update code in the definition of the "D" line.
+
+ If an element named in the configuration file already exists
+ on disk but is not identical to the configuration file
+ element, then package updates the existing disk version.
+ For example, if an element exists on disk as a symbolic link
+ but is defined as a directory or file in the configuration
+ file, then package will replace the symbolic link with a
+ directory or file. The same holds for directory or file
+ elements on disk that appear in the configuration file as a
+ symbolic link. Similarly, if the contents of a file do not
+ match those in the "source" file referred to in the
+ configuration file, then package overwrites the existing
+ file with the contents of the source file. The issuer can
+ specify different updating behavior through the use of
+ "update codes" on the lines in the configuration file. See
+ the definition of the "F" line.
+
+ARGUMENTS
+
+ -config specifies the pathname of the configuration
+ file to use, ending in the file's "base
+ name", which omits the suffix that indicates
+ the machine type. Package can determine a
+ machine's type and automatically select the
+ appropriate version of the base file name.
+ An example of the proper value for this
+ argument is staff rather than
+ staff.rt_aix221.
+
+ If only a file name is provided, package
+ looks for it in the current working
+ directory. It also interprets partial
+ pathnames relative to that directory.
+
+ Provide this argument OR -fullconfig.
+
+
+
+ -fullconfig specifies the configuration file to use. It
+ accepts two types of values:
+
+ - the full pathname of the
+ configuration file to use,
+ complete with an extension
+ indicating the machine-type
+ (examples: staff.rt_aos4,
+ staff.dkload.pmax_ul3)
+
+ - the string stdin, which indicates
+ that the issuer will provide
+ configuration information via
+ standard input (stdin), either as
+ a piped file or by typing the
+ configuration file at the
+ keyboard. Type ^D (Control-D) to
+ conclude the input.
+
+ Provide this argument OR -config.
+
+ -overwrite tells package to overwrite elements on the
+ local disk with the source version indicated
+ in the configuration file, even if the disk
+ version's "user" w mode bit is turned off.
+ Files protected by the I update code are not
+ overwritten; see the "F" line definition.
+
+ -noaction indicates that package should not actually
+ perform the command, but instead should
+ print a list (at standard out) of any
+ problems it would encounter in executing the
+ command. If the -verbose flag is added,
+ package produces a trace of all the actions
+ it would perform in executing the command,
+ but does not actually perform them.
+
+ -silent suppresses some of the trace messages that
+ package produces at standard out by default.
+ It still reports on major problems
+ encountered.
+
+ -verbose indicates that package should produce a more
+ detailed trace of its actions (at standard
+ out). The trace records on the transfer and
+ ownership/mode bit setting of each element
+ in the configuration file.
+
+ -rebootfiles indicates that package should not overwrite
+ any element marked with the Q update-mode
+ code in the configuration file. This
+ effectively prevents the machine from
+ rebooting automatically again when package
+ is invoked from /etc/rc.
+
+ -debug enables debugging output, which is directed
+ to standard out (stdout) unless the issuer
+ directs it into a file. By default, no
+ debugging output is produced.
+
+ -help prints the online help for this command. Do
+
+
+
+ not provide any other arguments or flags
+ with this one.
+
+EXAMPLES
+
+ This command is usually invoked in an initialization file
+ such as /etc/rc, rather than typed at the command shell
+ prompt.
+
+ The following invokes the version of the staff configuration
+ file appropriate for this machine's system type, and
+ produces verbose output.
+
+ /etc/package -c staff -v
+
+ The following tells package to use the configuration file
+ whose basename is stored in /.package on the local machine.
+ This can be convenient because the administrator can put it
+ (the same command) in every machine's /etc/rc file and still
+ configure machines differently, by putting the appropriate
+ basename in /.package.
+
+ /etc/package -c `cat /.package` -v
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged into the machine's UNIX file system as
+ the super user "root."
+
+
+
+ Configuration File "B" Line -- define block special device.
+
+
+ B <device name> <major device number> <minor device
+ number>
+ <owner name> <group name> <mode bits>
+
+DESCRIPTION
+
+ Defines a block special device, such as a disk, that deals
+ with input in units of multi-byte blocks.
+
+ARGUMENTS
+
+ B should be a capital letter and tells the
+ command interpreter that this line defines a
+ block special device.
+
+ device name names the block special device being defined.
+
+ major device number
+ specifies the device's major device number.
+ To learn the correct value, consult
+ documentation provided by the machine and/or
+ operating system's manufacturer.
+
+ minor device number
+ specifies the device's minor device number.
+ To learn the correct value, consult
+ documentation provided by the
+ machine/operating system's manufacturer.
+
+ owner name names the owner for the device in the UNIX
+ file system (the user who will appear in the
+ device's "owner" field in the output from
+ ls -l).
+
+ group name names the group for the device in the UNIX
+ file system (the group that will appear in
+ the device's group field in the output from
+ ls -lg).
+
+ mode bits defines the mode bits that protect the device
+ in the UNIX file system. Legal values are
+ the standard three- or four-digit decimal
+ numbers corresponding to combinations of
+ rights. Example: 755 corresponds to
+ rwxr-xr-x.
+
+EXAMPLE
+
+ The following defines disk /dev/hd0a with major and minor
+ device numbers 1 and 0.
+
+ B /dev/hd0a 1 0 root wheel 644
+
+
+
+ Configuration File "C" Line -- define character special
+
+ device.
+
+
+ C <device name> <major device number> <minor device
+ number>
+ <owner name> <group name> <mode bits>
+
+DESCRIPTION
+
+ Defines a character special device, such as a terminal or
+ tty, that deals with input in single character units.
+
+ARGUMENTS
+
+ C should be a capital letter and tells the
+ command interpreter that this line defines a
+ character special device.
+
+ device name names the character special device being
+ defined.
+
+ major device number
+ specifies the device's major device number.
+ To learn the correct value, consult
+ documentation provided by the
+ machine/operating system's manufacturer.
+
+ minor device number
+ specifies the device's minor device number.
+ To learn the correct value, consult
+ documentation provided by the
+ machine/operating system's manufacturer.
+
+ owner name names the owner for the device in the UNIX
+ file (the user who will appear in the
+ device's "owner" field in the output from
+ ls -l).
+
+ group name names the group for the device in the UNIX
+ file system (the group that will appear in
+ the device's group field in the output from
+ ls -lg).
+
+ mode bits defines the mode bits that protect the device
+ in the UNIX file system. Legal values are
+ the standard three- or four-digit decimal
+ numbers corresponding to combinations of
+ rights. Example: 644 corresponds to rw-r--
+ r--.
+
+EXAMPLE
+
+ The following defines tty /dev/ttyp5 with major and minor
+ device numbers 6 and 5.
+
+ C /dev/ttyp5 6 5 root wheel 666
+
+
+
+ Configuration File "D" Line -- define directory.
+
+
+ D[<update code>] <directory> <owner name> <group name> <mode
+ bits>
+
+DESCRIPTION
+
+ Names a directory to be created on the local disk. If a
+ directory of this name already exists, package does nothing.
+ However, if an element of the same name exists on disk as a
+ symbolic link, package replaces the symbolic link with an
+ actual directory.
+
+ARGUMENTS
+
+ D should be a capital letter and tells the command
+ interpreter that this line creates a directory.
+
+ update code
+ is optional and if provided should follow the
+ letter D directly, without an intervening space.
+ Choose one of the two legal values:
+
+ - X, which indicates that the directory is a
+ lost+found directory (used by the fsck
+ program).
+
+ - R, which indicates that package should
+ remove any files from the local disk
+ directory that do not appear in the
+ configuration file. It will also remove any
+ subdirectories of the directory, and files
+ in them, that do not appear in the
+ configuration file.
+
+ owner name
+ names the owner for the directory in the UNIX file
+ system (the user who will appear in the
+ directory's "owner" field in the output from
+ ls -l).
+
+ group name
+ names the group for the directory in the UNIX file
+ system (the group that will appear in the
+ directory's group field in the output from
+ ls -lg).
+
+ mode bits defines the mode bits that protect the directory
+ in the UNIX file system. Legal values are the
+ standard three- or four-digit decimal numbers
+ corresponding to combinations of rights. Example:
+ 755 corresponds to rwxr-xr-x.
+
+EXAMPLE
+
+ The following defines the /usr directory.
+
+ DR /usr root wheel 755
+
+
+
+ Configuration File "F" Line -- create/update file.
+
+
+ F[<update code>] <file> <source file> [<owner name> <group
+ name>
+ <mode bits>]
+
+DESCRIPTION
+
+ Names a file to be created on the local disk. Its contents
+ come from the indicated source file, which may reside either
+ in AFS or on the local disk itself. If package cannot
+ locate the source file, it aborts.
+
+ If a file of this name already exists on disk, then its
+ contents are updated with (overwritten by) the contents of
+ the source file, unless the I update code is used to prevent
+ that. Other update codes also modify the way in which the
+ update takes place; see the ARGUMENTS section.
+
+ If a symbolic link or directory exists on disk under this
+ name, package replaces it with the indicated file.
+
+ARGUMENTS
+
+ F should be a capital letter and tells the command
+ interpreter that this line creates/updates a file.
+
+ update code
+ determines the manner in which the source file is
+ used to update the contents of the file, if the
+ latter already exists on the local disk. This
+ argument is optional and if provided should follow
+ the letter F directly, without an intervening
+ space. Any number of the update-mode codes may
+ combined with one another, in any order. The
+ legal values are:
+
+ - A, which indicates that the pathname in the
+ source file slot is the complete pathname of
+ the source file, including the filename. By
+ default, the source file pathname does not
+ include a file name at the endMinstead,
+ package appends the name in the file slot to
+ the source file pathname in order to
+ determine the source file's full name.
+ Thus, this code allows the name of the file
+ being created to differ from the name of the
+ source file. See also the EXAMPLE(S)
+ section.
+
+ - I, which indicates that the file should not
+ be overwritten if it already exists on the
+ local disk. If it does not exist, then
+ package creates it, and copies the contents
+ of the source file into it.
+
+ - O, which indicates that package should save
+ the existing local disk version of the file
+ with a .old extension, before overwriting
+ its contents with the source file's.
+
+
+
+ - Q, which indicates that if package
+ overwrites the file, then it should exit
+ with status code 4. If the standard
+ package-related changes have been made to
+ /etc/rc, then status code 4 will cause an
+ automatic reboot of the machine. This is
+ useful in cases where the machine must
+ reboot in order for updates to the file to
+ have any effect (/vmunix is a common
+ example).
+
+ file specifies the complete pathname of the file to be
+ created or updated on the local disk.
+
+ source file
+ specifies the file (in AFS or on the local disk)
+ whose contents should be used to create or update
+ the disk file.
+
+ If the A update code appears on the line, this
+ slot should specify the source file's complete
+ pathname. Otherwise, this slot should specify
+ only the part of the pathname that precedes the
+ name of the local disk file. As an example,
+ suppose that the configuration file is for a
+ Transarc cell machine running AIX 2.2.1, so that
+ the source for the local disk file called
+ /bin/grep is /afs/transarc.com/rt_aix221/bin/grep.
+ If the A does not appear, then the proper filler
+ for the source file slot is
+ /afs/transarc.com/rt_aix221. See also the
+ EXAMPLE(S) section.
+
+ owner name
+ names the owner for the file in the UNIX file
+ system (the user who will appear in the file's
+ "owner" field in the output from ls -l).
+
+ This slot may be left empty, in which case the
+ file's owner is set to match the source file's
+ owner. If this slot is empty, the group name and
+ mode bits slots must also be empty.
+
+ group name
+ names the group for the file in the UNIX file
+ system (the group that will appear in the file's
+ group field in the output from ls -lg).
+
+ This slot may be left empty, in which case the
+ file's group is set to match the source file's
+ group. If this slot is empty, the owner name and
+ mode bits slots must also be empty.
+
+ mode bits defines the mode bits that protect the file in the
+ UNIX file system. Legal values are the standard
+ three- or four-digit decimal numbers corresponding
+ to combinations of rights. Example: 755
+ corresponds to rwxr-xr-x.
+
+ This slot may be left empty, in which case the
+ file's mode bits are set to match the source
+
+
+
+ file's mode bits. If this slot is empty, the
+ owner name and group name slots must also be
+ empty.
+
+EXAMPLES
+
+ The following, appropriate for a machine running AIX 2.2.1
+ in the Transarc cell, creates/updates the file /bin/grep on
+ the local disk, using /afs/transarc.com/rt_aix221/bin/grep
+ as the source.
+
+
+ F /bin/grep /afs/transarc.com/rt_aix221 root wheel 7
+
+ The next example specifies an absolute pathname for the
+ source file, as indicated by the A update code. The Q code
+ makes package return status code 4 as it exits, prompting a
+ reboot of the machine if the standard package-related
+ changes have been made to /etc/rc. This example also leaves
+ the owner name, group name and mode bits slots empty, so
+ that the disk file adopts the source file's values for those
+ slots.
+
+
+ FAQ /usr/vice/etc/ThisCell /afs/transarc.com/common/
+
+
+
+ Configuration File "L" Line -- create symbolic link.
+
+
+ L[<update code>] <link> <actual file> [<owner name>
+ <group name> <mode bits>]
+
+DESCRIPTION
+
+ Creates a symbolic link to a directory or file that exists
+ either in AFS or elsewhere on the local disk. If package
+ cannot access the actual directory/file, it aborts.
+
+ If a file or directory currently exists on the local disk
+ under this name, package replaces it with a symbolic link.
+
+ARGUMENTS
+
+ L should be a capital letter and tells the command
+ interpreter that this is a symbolic link
+ definition.
+
+ update code
+ modulates the way that package creates the
+ symbolic link, as discussed for each code. It is
+ optional and if provided should follow the letter
+ L directly, without an intervening space. The two
+ legal update-mode codes may combined with one
+ another, in either order. The legal values are:
+
+ - A, which indicates that the pathname in the
+ actual file slot is the complete pathname of
+ the actual file, including the filename. By
+ default, the actual file pathname does not
+ include a file name at the endMinstead,
+ package appends the name in the link slot to
+ the actual file pathname in order to
+ determine the actual file's full name.
+ Thus, this code allows the name of the
+ symbolic link being created to differ from
+ the name of the actual file. See also the
+ EXAMPLE(S) section.
+
+ - I, which indicates that the symbolic link
+ should not be overwritten if it already
+ exists on the local disk. If it does not
+ exist, then package creates it.
+
+ link specifies the complete pathname of the symbolic
+ link to be created on the local disk.
+
+ actual file
+ specifies the file (in AFS or on the local disk)
+ to which the symbolic link refers.
+
+ If the A update code appears on the line, this
+ slot should specify the actual file's complete
+ pathname. Otherwise, this slot should specify
+ only the part of the pathname that precedes the
+ name of the local disk link. As an example,
+ suppose that the configuration file is for a
+ Transarc cell machine running Ultrix 3.0, so that
+
+
+
+ /etc/ftpd is a symbolic link to
+ /afs/transarc.com/vax_ul3/etc/ftpd. If the A does
+ not appear, then the proper filler for this slot
+ is /afs/transarc.com/vax_ul3, not
+ /afs/transarc.com/vax_ul3/etc/ftpd. See also the
+ EXAMPLE(S) section.
+
+ owner name
+ names the owner for the symbolic link in the UNIX
+ file system (the user who will appear in the
+ symbolic link's "owner" field in the output from
+ ls -l).
+
+ This slot may be left empty, in which case the
+ symbolic link's owner is set to match the UNIX
+ user name of the issuer of the package command
+ (i.e., "root"). If this slot is empty, the group
+ name and mode bits slots must also be empty.
+
+ group name
+ names the group for the symbolic link in the UNIX
+ file system (the group that will appear in the
+ symbolic link's group field in the output from
+ ls -lg).
+
+ This slot may be left empty, in which case the
+ symbolic link's group is set to match the group
+ for the issuer of the package command (defined in
+ the issuer's /etc/rc entry. If this slot is
+ empty, the owner name and mode bits slots must
+ also be empty.
+
+ mode bits defines the mode bits that protect the symbolic
+ link in the UNIX file system. Legal values are
+ the standard three- or four-digit decimal numbers
+ corresponding to combinations of rights. Example:
+ 755 corresponds to rwxr-xr-x.
+
+ This slot may be left empty, in which case the
+ symbolic link's mode bits are set to 777
+ (rwxrwxrwx). If this slot is empty, the owner
+ name and group name slots must also be empty.
+
+EXAMPLES
+
+ The following, appropriate for a machine running Ultrix 3.0
+ in the Transarc cell, creates a symbolic link from /etc/ftpd
+ on the local disk to the file
+ /afs/transarc.com/vax_ul3/etc/ftpd in AFS.
+
+
+ L /etc/ftpd /afs/transarc.com/vax_ul3 root wheel 644
+
+ The next example uses an absolute pathname (as indicated by
+ the A update code), because the symbolic link and actual
+ file names differ. This example also leaves the owner name,
+ group name and mode bits slots empty, so that the symbolic
+ link adopts values for those slots from the actual file.
+
+
+ LA /etc/printcap /afs/transarc.com/common/etc/printca
+
+
+
+ Configuration File "S" Line -- define socket.
+
+
+ S <socket name> [<owner name> <group name> <mode bits>]
+
+DESCRIPTION
+
+ Defines a socket (a communications device for UDP and TCP/IP
+ connections).
+
+ARGUMENTS
+
+ S should be a capital letter and tells the command
+ interpreter that this is a socket definition.
+
+ socket name
+ names the socket being defined.
+
+ owner name
+ names the owner for the socket in the UNIX file
+ system (the user who will appear in the socket's
+ "owner" field in the output from ls -l).
+
+ This slot may be left empty, in which case the
+ socket's owner is set to match the UNIX user name
+ of the issuer of the package command (i.e.,
+ "root"). If this slot is empty, the group name
+ and mode bits slots must also be empty.
+
+ group name
+ names the group for the socket in the UNIX file
+ system (the group that will appear in the socket's
+ group field in the output from ls -lg).
+
+ This slot may be left empty, in which case the
+ socket's group is set to match the group for the
+ issuer of the package command (defined in the
+ issuer's /etc/rc entry. If this slot is empty,
+ the owner name and mode bits slots must also be
+ empty.
+
+ mode bits defines the mode bits that protect the socket in
+ the UNIX file system. Legal values are the
+ standard three- or four-digit decimal numbers
+ corresponding to combinations of rights. Example:
+ 755 corresponds to rwxr-xr-x.
+
+ This slot may be left empty, in which case the
+ socket's mode bits are set to 777 (rwxrwxrwx), as
+ modulated by the cell's umask. If this slot is
+ empty, the owner name and group name slots must
+ also be empty.
+
+EXAMPLE
+
+ The following defines the socket /dev/printer:
+
+
+ S /dev/printer root wheel 777
+
+
+
+ Configuration File %define -- define variable or declare
+
+ string.
+
+
+ %define <variable> <value> %define <declaration>
+
+DESCRIPTION
+
+ If followed by two arguments, defines the second argument as
+ the value of the first, which may appear as a variable (in
+ the form ${variable}) in the same or other prototype/library
+ files. The second argument is substituted for occurrences
+ of the variable wherever it occurs.
+
+ If followed by a single argument, declares the argument to
+ be defined, making it available for use as a controller in
+ %ifdef and %ifndef statements. That is, %ifdef statements
+ mentioning this variable will resolve as "true," %ifndef
+ statements as "false."
+
+ARGUMENTS
+
+ variable as the first of two arguments, specifies the
+ name of the variable for which a value is
+ defined. This argument may appear in
+ variable form (i.e., as ${variable}) in this
+ or other prototype/library files.
+
+ value as the second of two arguments, specifies
+ the value to be assigned to variable-form
+ occurrences of the first argument.
+
+ declaration as the single argument, declares the
+ indicated string to be defined.
+
+EXAMPLES
+
+ The following defines the value for the variable
+ ${diskmode}. This variable is used elsewhere in the
+ template to fill the <owner name>, <group name> and
+ <mode bit> slots on a "D", "F" or "L" line.
+
+
+ %define diskmode root wheel 644
+
+ The following declares the string "afsd" to be defined.
+
+
+ %define afsd
+
+
+
+ Configuration File %ifdef -- specify action to perform if
+
+ value is declared or defined.
+
+
+ %ifdef <declaration>
+ +
+ <action> [%else [<declaration>]
+ +
+ <alternate action> ] %endif <declaration>
+
+DESCRIPTION
+
+ Specifies the action(s) to perform if the indicated
+ declaration has been made with a single-argument %define
+ statement, or if the indicated variable has a value.
+
+ The optional %else statement specifies alternate action(s)
+ to perform if the indicated declaration has never been made,
+ or has been undone with %undef.
+
+ It is possible to nest any number of %ifdef and %ifndef
+ statements.
+
+ARGUMENTS
+
+ declaration specifies the string that must be declared,
+ or variable that must be defined, if the
+ action is to be performed. Its second
+ occurrence (following %else) is optional,
+ serving only to clarify which %ifdef the
+ %else belongs to. The first and third
+ occurrences (the latter following %endif)
+ are required.
+
+ action specifies each action to perform if the
+ %ifdef statement resolves to "true." Each
+ action should appear on a separate line.
+ Both "%-statements" and definition lines are
+ acceptable actions.
+
+ alternate action
+ specifies each action to perform if the
+ %ifdef statement resolves to "false." Each
+ action should appear on a separate line.
+ Both "%-statements" and definition lines are
+ acceptable actions.
+
+EXAMPLE
+
+ The following specifies that if the string rt_aos4 is
+ currently declared, then the three indicated library files
+ will be included in the configuration file resulting from
+ compilation of this prototype file.
+
+ %ifdef rt_aos4
+ %include ${wsadmin}/lib/rt_aos4.readonly
+ %include ${wsadmin}/lib/rt_aos4.generic
+ %include ${wsadmin}/lib/rt_aos4.generic.dev
+ %endif rt_aos4
+
+
+
+ Configuration File %ifndef -- specify action to perform if
+
+ value is not declared or defined.
+
+
+ %ifndef <declaration>
+ +
+ <action> [%else [<declaration>]
+ +
+ <alternate action> ] %endif <declaration>
+
+DESCRIPTION
+
+ Specifies the action(s) to perform if the indicated
+ declaration has never been made or has been undone with an
+ %undef statement, or if the indicated variable does not have
+ a value.
+
+ The optional %else statement specifies alternate action(s)
+ to perform if the indicated declaration/definition has been
+ made, or if the variable does have a value.
+
+ It is possible to nest any number of %ifdef and %ifndef
+ statements.
+
+ARGUMENTS
+
+ declaration specifies which string must not be declared,
+ or which variable must not be defined, in
+ order for action to be performed. Its
+ second occurrence (following %else) is
+ optional, serving only to clarify which
+ %ifdef the %else belongs to. The first and
+ third occurrences (the latter following
+ %endif) are required.
+
+ action specifies each action to perform if the
+ %ifndef statement resolves to "true" (i.e.,
+ the string is not declared or variable is
+ not defined). Each action should appear on
+ a separate line. Both "%-statements" and
+ definition lines are acceptable actions.
+
+ alternate action
+ specifies each action to perform if the
+ %ifndef statement resolves to "false" (i.e.,
+ the string is declared or variable does have
+ a defined value). Each action should appear
+ on a separate line. Both "%-statements" and
+ definition lines are acceptable actions.
+
+
+
+EXAMPLE
+
+ The following, appropriate for the Transarc Corporation
+ cell, defines "transarc.com" as the value of the ${cell}
+ variable if it does not already have a value.
+
+
+ %ifndef cell
+ %define cell transarc.com
+ %endif cell
+
+
+
+ Configuration File %include -- include library file.
+
+
+ %include <file pathname>
+
+DESCRIPTION
+
+ Causes contents of indicated library file to be included in
+ configuration file resulting from compilation of this
+ prototype file.
+
+ARGUMENTS
+
+ file pathname specifies the complete pathname of the
+ library file to be included. The pathname
+ may include variables.
+
+EXAMPLE
+
+ The following includes the file base.generic from the lib
+ subdirectory of the directory in which the cell keeps
+ package related files. The ${wsadmin} variable will be
+ resolved to an actual pathname (such as
+ /afs/transarc.com/wsadmin) during compilation.
+
+
+ %include ${wsadmin}/lib/base.generic
+
+
+
+ Configuration File %undef -- declare value to be defined no
+
+ longer.
+
+
+ %undef <declaration>
+
+DESCRIPTION
+
+ Specifies that the indicated string is no longer defined.
+ Any %ifndef statements involving this string will then
+ resolve as "true," %ifdef statements as "false."
+
+ARGUMENTS
+
+ declaration specifies the string that should no longer
+ is no longer defined.
+
+EXAMPLE
+
+ The following declares the string "afsd" not to be defined.
+
+
+ %undef afsd
--- /dev/null
+pagsh AFS Commands pagsh
+
+
+NAME
+
+ pagsh -- create new process authentication group (PAG).
+
+
+ pagsh
+
+DESCRIPTION
+
+ Creates a new command shell (owned by the issuer of the
+ command) and associates a new "process authentication group"
+ (PAG) with the shell and the user. A PAG is a number
+ guaranteed to identify the issuer of commands in the new
+ shell uniquely to the local Cache Manager. The PAG is used,
+ instead of the issuer's UNIX UID, to identify him or her in
+ the credential structure that the Cache Manager creates to
+ track each user.
+
+ Any additional tokens issued to the user (presumably for
+ other cells) become associated with the PAG, rather than
+ with the user's UNIX UID. This method for distinguishing
+ users has two advantages.
+
+ - It means that processes spawned by the user
+ inherit the PAG and so share the token; thus they
+ gain access to AFS as the authenticated user. In
+ many environments, for example, printer and other
+ daemons run under identities (such as "root") that
+ the AFS server processes recognize only as
+ anonymous. Unless PAGs are used, such daemons
+ cannot access files protected against
+ system:anyuser.
+
+ - It closes a potential security loophole: UNIX
+ allows anyone already logged in as "root" on a
+ machine to assume any other identity by issuing
+ su. If the credential structure were identified
+ by a UNIX UID rather than a PAG, then assuming the
+ same UID would mean being able to use the token,
+ too. Use of a PAG as an identifier eliminates
+ that possibility.
+
+WARNINGS AND REQUIREMENTS
+
+ Each PAG created uses two of the memory slots that the
+ kernel uses to record the UNIX groups associated with a
+ user. If none of these slots are available, the pagsh
+ command fails. This is not a problem with most operating
+ systems, which make at least 16 slots available per user.
+
+ Users in cells not using the AFS version of login should
+ issue this command before issuing klog. If they do not,
+ then the Cache Manager stores the token in a credential
+ structure identified by UNIX UID rather than PAG. This
+ creates the potential security loophole described in the
+ DESCRIPTION section.
+
+ If the command is to be issued on NFS client machines for
+ which AFS is available, the pagsh binary accessed by the NFS
+ client must be owned by, and grant setuid privilege to,
+ "root." The complete set of mode bits should be -rwsr-xr-x.
+
+
+
+ This is not a requirement when the command is issued on AFS
+ client machines.
+
+EXAMPLE
+
+ The following shows the only possible use of the command.
+
+ % pagsh
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ klog
+
+ login (AFS version)
--- /dev/null
+runntp AFS Commands runntp
+
+
+NAME
+
+ runntp -- initialize Network Time Protocol Daemon.
+
+
+ /usr/afs/bin/runntp [-localclock] [-precision <small
+ negative integer>]
+ +
+ [-logfile <pathname>] [<machine name> ]
+
+DESCRIPTION
+
+ Initializes the Network Time Protocol Daemon and related
+ programs on the local machine. It also constructs the
+ ntp.conf configuration file.
+
+ This command is intended as a convenient interface to the
+ standard ntpd program, to be used on AFS file server
+ machines.
+
+WARNING
+
+ A cell in which the NTPD was running before the introduction
+ of AFS does not need to use runntp. It is an error to run
+ two NTPDs on one machine.
+
+ This command is not normally issued at the command shell
+ prompt, but rather placed into a file server machine's
+ /usr/afs/local/BosConfig with the bos create command.
+
+ This command does not use the syntax conventions of the AFS
+ command suites, so the command and switch names must be
+ typed in full.
+
+ARGUMENTS
+
+ -localclock
+ tells NTPD to use the local machine's internal
+ clock as a possible source of the correct time in
+ case a network partition separates the machine
+ from the specified machine name(s). Cells
+ connected to the Internet should not normally use
+ this flag. In cells that experience frequent
+ separations from the network (voluntary or
+ otherwise), it should be used only on the system
+ control machine.
+
+ -precision
+ specifies the precision of the local clock. This
+ argument is not normally provided. As ntpd
+ initializes, it determines the precision of the
+ local clock on its own. If the argument is
+ provided, it should be a small integer preceded by
+ a hyphen to show that it is negative. The value
+ is used as an exponent on the number 2, and the
+ result interpreted as the frequency, in fractions
+ of a second, at which the local clock tics
+ (advances).
+
+ For example, a value of -6, which translates to
+
+
+
+ -6
+ 2 or 1/64, means that the local clock tics once
+ every 1/64th of a second, or has a precision of
+ about 60 tics per second. A value of -7
+ translates to about 100 tics per second. A value
+ of -10 translates to about 1000 tics per second (a
+ millisecond clock).
+
+ -logfile indicates the pathname of the file in which to
+ store log output from NTPD. Indicate a location
+ on the file server machine's local disk, not in
+ AFS; a suitable location might be
+ /usr/afs/logs/ntp.log. The log records
+ information about which machines are serving as
+ time sources and peers, what adjustments have been
+ made to reduce drift, and so on. Use ntpd's
+ debugging mechanism to control the amount of
+ information produced. If this argument is
+ omitted, the information is discarded.
+
+ machine name
+ is the complete Internet-style host name of each
+ machine the local machine should consult for the
+ correct time. Preferably the machines are outside
+ the cell.
+
+ In general, this argument is necessary only on the
+ system control machine. If the issuer omits it,
+ then the local machine consults its
+ /usr/afs/etc/CellServDB file and uses the machines
+ listed there as time sources.
+
+ See the AFS Installation Guide or consult AFS
+ Product Support at Transarc for advice on
+ selecting appropriate time sources.
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList to place this
+ command in /usr/afs/local/BosConfig, because that is the
+ privilege required to issue bos create.
+
+MORE INFORMATION
+
+ bos create
+
+ UNIX manual page for ntp
+
+ UNIX manual page for ntpd
+
+ UNIX manual page for ntpdc
--- /dev/null
+salvager AFS Commands salvager
+
+
+NAME
+
+ salvager -- initialize Salvager in BosConfig or manually.
+
+
+ /usr/afs/bin/salvager [-f] [-o] [<partition name>
+ [<volumeID>]]
+
+DESCRIPTION
+
+ Initializes the Salvager component of the fs process, which
+ corrects corruption in ReadWrite volumes where possible.
+ Unlike most other AFS file server processes, this process
+ can also be started from the command line. It produces a
+ trace of its actions in /usr/afs/logs/SalvageLog.
+
+ If the Salvager detects corruption in ReadOnly or Backup
+ volumes, it removes them rather than attempting to correct
+ the corruption; it records the removal in SalvageLog. If
+ desired, the issuer can recreate the ReadOnly or Backup
+ version by issuing vos release or vos backup, respectively.
+
+ The Salvager normally salvages only those ReadWrite volumes
+ that are marked as having been active when a crash occurred.
+ To have it salvage all relevant ReadWrite volumes, add the
+ -f flag.
+
+ The number of volumes the Salvager attempts to salvage
+ depends on the combination of arguments and flags used. To
+ salvage:
+
+ - volumes on all /vicepx partitions on a file server
+ machine, provide no arguments
+
+ - volumes on a certain partition, specify the
+ partition's full (/vicepx-style) name as partition
+ name
+
+ - one particular ReadWrite volume, specify its
+ partition as partition name and its volumeID
+ number as volumeID
+
+WARNING
+
+ This command does not use the syntax conventions of the AFS
+ command suites, so the command and switch names must be
+ typed in full.
+
+ARGUMENTS
+
+ -f inspects all volumes for corruption, not just
+ those that are marked as having been active
+ when a crash occurred.
+
+ -o enables the Salvager to remove volumes that are
+ too damaged to be removed in the normal manner.
+ Do not Use this argument unless a member of the
+ AFS Product Support staff has directed its use.
+ In normal cases, use the -force flag on the
+ vos zap command instead. If this flag is
+ provided, it should be combined with partition
+
+
+
+ name and volumeID.
+
+ partition name
+ specifies which partition the Salvager should
+ inspect for corruption. If it is omitted,
+ every /vicepx partition on the file server
+ machine is inspected.
+
+ volumeID number
+ specifies the volumeID number of the Read Write
+ volume to salvage.
+
+EXAMPLES
+
+ The following command instructs the Salvager to attempt to
+ salvage the volume with volume ID 258347486 on /vicepg on
+ the local machine.
+
+ % /usr/afs/bin/salvager /vicepg 258347486
+
+PRIVILEGE REQUIRED
+
+ Issuer must be logged into the local UNIX file system as
+ "root" to issue this command to the shell.
+
+ Issuer must be listed in /usr/afs/etc/UserList to place this
+ command in /usr/afs/local/BosConfig, because that is the
+ privilege required to issue bos create.
+
+MORE INFORMATION
+
+ bos create
+
+ bos salvage
--- /dev/null
+scout AFS Commands scout
+
+
+NAME
+
+ scout -- monitor File Server process on one or more file
+
+ server machines.
+
+
+ +
+ scout -server <File Server name(s) to monitor>
+ [-basename <base server name>]
+ [-frequency <poll frequency, in seconds>] [-host]
+ +
+ [-attention <specify attention (highlighting) level> ]
+ [-debug <turn debugging on to the named file>] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ scout -s <File Server name(s) to monitor>
+ [-b <base server name>]
+ [-f <poll frequency, in seconds>] [-ho]
+ +
+ [-a <specify attention (highlighting) level> ]
+ [-d <turn debugging on to the named file>] [-he]
+
+DESCRIPTION
+
+ Displays statistics gathered from the File Server process
+ running on each machine specified with -server. The OUTPUT
+ section explains the meaning of the statistics and describes
+ how they appear on the screen.
+
+REQUIREMENTS
+
+ In addition to the scout binary, the machine must be able to
+ access the "curses" graphics package, since scout's display
+ abilities rely on it. Most UNIX distributions include
+ curses as a standard utility.
+
+ Both "dumb" terminals and windowing systems that emulate
+ terminals can display scout's statistics. The scout display
+ makes use of reverse video and cursor addressing, so for the
+ display to look its best, the display environment should
+ support those features (most windowing systems do, most dumb
+ terminals do not). To let scout know what type of
+ environment is being used, the user should set the
+ environment variable TERM to the correct terminal type, or
+ one with characteristics similar to the actual ones. For
+ machines running AIX, the recommended setting for TERM is
+ vt100, as long as the terminal is similar to that. For
+ other operating systems, the wider range of acceptable
+ values includes xterm, xterms, vt100, vt200 and wyse85.
+
+
+
+ARGUMENTS
+
+ -server names each File Server process to monitor, by
+ identifying the file server machine it is running
+ on. Complete Internet-style host names are best,
+ unless the -basename argument is used. In that
+ case, specify only the unique initial part of each
+ machine name, omitting the domain/cell name suffix
+ (or "basename") common to all the names.
+ Shortened unambiguous names are legal when the
+ -basename argument is not used, but in that case
+ their correct resolution depends on the state of
+ the cell's naming service at the time the command
+ is issued.
+
+ -basename specifies the basename (domain/cell name) suffix
+ common to all of the file server machine names
+ specified with -server, and is automatically
+ appended to them. This argument is normally the
+ name of the cell to which the machines belong. Do
+ not include the period that separates this suffix
+ from the distinguishing part of each file server
+ machine name, but do include any periods that
+ occur within the suffix itself. (For example, in
+ the Transarc Corporation cell, the proper value
+ would be "transarc.com", not ".transarc.com".)
+
+ -frequency
+ indicates how often scout should probe the File
+ Server processes. Specify a number of seconds
+ greater than 0. The default is 60 seconds.
+
+ -host causes the banner line to display the name of the
+ machine that is running scout. The default is not
+ to display the machine name in the banner.
+
+ -attention
+ defines a list of one or more entries, each of
+ which pairs a type of statistic and a threshold
+ value. When the value of the statistic exceeds
+ the indicated threshold value, scout highlights
+ the value. The pairs may appear in any order.
+ Legal values for the pairs are
+
+ - conn <connections>. Indicates the maximum
+ number of connections that the File Server
+ may have open to client machines before the
+ value is highlighted. Highlighting goes
+ away when the value goes back below the
+ threshold. By default, no threshold is set.
+
+ Example of a legal value: conn 300
+
+ - fetch <bytes fetched>. Indicates the
+ maximum number of bytes of data that clients
+ can have fetched from the File Server before
+ the value is highlighted. Highlighting goes
+ away when the value goes back below the
+ threshold, but this is possible only if the
+ File Server is restarted, at which time the
+ value returns to 0. By default, no
+
+
+
+ threshold is set.
+
+ Example of a legal value: fetch 45000
+
+ - store <bytes stored>. Indicates the maximum
+ number of bytes of data that clients can
+ have sent to the File Server for storage
+ before the value is highlighted.
+ Highlighting goes away when the value goes
+ back below the threshold, but this is
+ possible only if the File Server is
+ restarted, at which time the value returns
+ to 0. By default, no threshold is set.
+
+ Example of a legal value: store 120000
+
+ - ws <number of active client machines>.
+ Indicates the maximum number of "active"
+ client machines the File Server can be
+ serving before the value is highlighted.
+ "Active" machines are defined as those that
+ have communicated with the File Server in
+ the last 15 minutes. Highlighting goes away
+ when the value goes back below the
+ threshold. By default, no threshold is set.
+
+ Example of a legal value: ws 65
+
+ - disk <percent full>%. Indicates the maximum
+ percentage of the disk that can be full
+ before the value is highlighted; in that
+ case legal values are the integers between 0
+ and 99.
+
+ Examples of legal values: disk 90% and disk
+ 72%.
+
+ OR
+
+ disk <minimum blocks free>. Indicates the
+ minimum number of kilobyte blocks that must
+ be available on the partition if the value
+ is not to be highlighted.
+
+ Examples of legal values: disk 1500 and
+ disk 5000.
+
+ Specify one type of value or the other.
+ Highlighting goes away when the value goes
+ back below the percent threshold or above
+ the blocks-free threshold. By default, the
+ threshold is 95%.
+
+ -debug enables debugging output and directs it into the
+ specified file. Providing a complete pathname is
+ best; otherwise it is interpreted relative to the
+ current working directory. By default, no
+ debugging output is produced.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+
+
+
+ one.
+
+OUTPUT
+
+ Scout can display statistics either in a dedicated window or
+ on a plain screen if a windowing environment is not
+ available. For best results, the window or screen should
+ have the ability to print in reverse video.
+
+ The scout screen has three main parts: the banner line, the
+ statistics display region and the message/probe line.
+
+ The Banner Line
+
+ The word "Scout" appears in the banner line at the top of
+ the window or screen, to indicate that scout is running.
+ Additional information may appear in the banner line if the
+ system administrator includes the appropriate
+ flags/arguments on the command line. By default, this
+ information does not appear.
+
+ - The name of the machine executing scout. The
+ -hostname flag causes scout to display this
+ machine name in the banner line. This is useful
+ in cases where the administrator wants to run
+ scout on several machines, but view the output on
+ only one machine (to achieve this, he or she could
+ open several windows on a machine, then telnet to
+ a different machine in each one in order to run
+ scout there).
+
+ An example: if a user runs scout on the machine
+ client1.transarc.com and use the -hostname flag,
+ the banner line will read
+
+
+ [client1.transarc.com] Scout
+
+ - The ``basename'' of the file server machines being
+ monitored. Scout identifies a File Server process
+ by the name of the file server machine it is
+ running on. If all of the machine names in a
+ scout window end in the same string (share the
+ same basename), then it is useful to display the
+ basename in one place rather than on every machine
+ name. The -basename argument causes scout to
+ display the indicated basename on the banner line.
+ The issuer then leaves the basename off of each
+ file server machine name provided, specifying only
+ the distinguishing prefix rather than the complete
+ machine name.
+
+ An example, if a user specifies a value of
+ transarc.com for -basename, the banner line will
+ read
+
+
+ Scout for transarc.com
+
+ The Statistics Display Region
+
+ In this region, which takes up the majority of the window,
+
+
+
+ Scout displays the statistics gathered for each File Server
+ process. Each process appears on its own line.
+
+ The region is divided into six columns, labeled as indicated
+ and displaying the following information:
+
+ - Conn: number of connections with clients. The
+ first column displays the number of RPC
+ connections open between the File Server process
+ and client machines. This number should equal or
+ exceed the number in the Ws column (explained
+ below). It can exceed it because each process
+ access group (PAG) requires a separate RPC
+ connection, and one client machine can handle
+ several PAGs. The administrator can use the
+ -attention argument to specify the value at which
+ entries in the column should be highlighted.
+
+ - Fetch: bytes fetched from File Server. The second
+ column displays the number of bytes of data that
+ client machines have fetched from the File Server
+ process. This number is reset to zero each time
+ the File Server process restarts. The
+ administrator can use the -attention argument to
+ specify the value at which entries in the column
+ should be highlighted.
+
+ - Store: bytes stored by the File Server. The third
+ column displays the number of bytes of data that
+ client machines have sent to the File Server
+ process for storage. This number is reset to zero
+ each time the File Server process restarts. The
+ administrator can use the -attention argument to
+ specify the value at which entries in the column
+ should be highlighted.
+
+ - Ws: number of "active" client machines. The
+ fourth column displays the number of client
+ machines (workstations) that have communicated
+ with the File Server process within the last 15
+ minutes. This number is likely to be smaller than
+ the number in the Conn column, because a single
+ client machine can have several connections open
+ to one File Server. The administrator can use the
+ -attention argument to specify the value at which
+ entries in the column should be highlighted.
+
+ - File server machine name. The fifth, unlabeled,
+ column displays the name of the file server
+ machine on which the File Server process is
+ running. If a name is too long to fit in the
+ field, it is truncated and an asterisk (*) appears
+ as the last character in the name. Using the
+ -basename argument is a good way to avoid
+ truncation, but only if all machine names end in a
+ common string. Entries in this column become
+ highlighted if the File Server process does not
+ respond to scout's probes.
+
+ - Disk attn: disk usage. The sixth column displays
+ how many kilobyte blocks are available on each AFS
+
+
+
+ disk partition on the file server machine. The
+ display for each partition has the form
+
+
+ x:free_blocks
+
+ where x indicates the partition name. For
+ example, a:8949 specifies that partition /vicepa
+ has 8,949 free kilobyte blocks. The available
+ space may be displayed for up to 10 partitions.
+ If the window is not wide enough for all of the
+ partition entries to appear on a single line,
+ scout automatically creates multiple lines,
+ "stacking" the partition entries into sub-columns
+ within the Disk attn column.
+
+ The label on the Disk attn column indicates the
+ threshold at which values are highlighted. By
+ default, the label is
+
+
+ Disk attn: > 95% used
+
+ because by default scout highlights the entry for
+ any partition that is over 95% full. The
+ administrator may use the -attention argument to
+ change this default to either another percentage
+ or a minimum number of free blocks.
+
+ The Message/Probe Line
+
+ The bottom line of the scout screen indicates how many times
+ scout has "probed" the File Server processes for statistics.
+ The columns in the Statistics Display region above this line
+ display the result of the latest probe. By default, scout
+ probes the File Servers every 60 seconds, but the
+ administrator can use the -frequency argument to specify a
+ different number of seconds.
+
+EXAMPLE
+
+ See the chapter on scout in the AFS System Administrator's
+ Guide, which illustrates the on-screen displays that result
+ from different combinations of switches and flags.
+
+PRIVILEGE REQUIRED
+
+ None.
--- /dev/null
+tokens AFS Commands tokens
+
+
+NAME
+
+ tokens -- display all tokens.
+
+
+ tokens
+
+DESCRIPTION
+
+ Instructs the Cache Manager on the local machine to display
+ all tokens (tickets) it has for the issuer. AFS server
+ processes require that their clients present a token as
+ evidence that they have authenticated in the server's local
+ cell.
+
+OUTPUT
+
+ The output lists one token for each cell in which the user
+ is authenticated. The output indicates:
+
+ - the user's AFS UID, if it is available for display
+
+ - the server for which the token is valid (normally,
+ "afs"). This includes a cell specification.
+
+ - the day and time the token expires
+
+ An --End of list-- message appears at the end of the output.
+ If the user is not authenticated in any cell, this message
+ is all that appears.
+
+EXAMPLES
+
+ The following shows the output when the issuer is not
+ authenticated in any cell.
+
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ [ 1] --End of list--
+
+ The following shows the output when the issuer is
+ authenticated in Transarc Corporation cell, where he or she
+ has AFS UID 1000.
+
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ [ 1]User's (AFS ID 1000) tokens for afs@transarc.co
+ [Expires Jan 2 10:
+ [ 2] --End of list--
+
+ The following shows the output when the issuer is
+ authenticated in Transarc Corporation cell, Andrew cell at
+ Carnegie Mellon University and Athena cell at MIT. The user
+ has different AFS UIDs in the three cells. Tokens for last
+ cell are expired:
+
+
+
+ % tokens
+ Tokens held by the Cache Manager:
+
+ [ 1]User's (AFS ID 1000) tokens for afs@transarc.co
+ [Expires Jan 3 10:00]
+ [ 2]User's (AFS ID 4286) tokens for afs@andrew.cmu.
+ [Expires Jan 3 1:34]
+ [ 3]User's (AFS ID 22) tokens for afs@athena.mit.ed
+ [>>Expired<<]
+ [ 4] --End of list--
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ klog
+
+ unlog
--- /dev/null
+unlog AFS Commands unlog
+
+
+NAME
+
+ unlog -- discard all tokens.
+
+
+ +
+ unlog [<cell name> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ This command does not use the conventions of the AFS command
+ suites. Therefore "unlog" and "-help" must be typed in
+ full.
+
+DESCRIPTION
+
+ Instructs the Cache Manager on the local machine to discard
+ the specified token(s) currently held for the issuer. If no
+ cell names are provided, the Cache Manager discards the
+ token for the local cell and all tokens for foreign cells.
+
+WARNINGS
+
+ Specifying one or more cell names may cause brief
+ "authentication outages," during which the issuer has no
+ valid tokens in any cell. This is because the command
+ actually discards all tokens and then restores those that
+ the issuer did not specify with cell name (and so presumably
+ wishes to retain). The authentication outage may interrupt
+ the operation of jobs that require authentication.
+
+ARGUMENTS
+
+ cellname specifies each cell for which the Cache
+ Manager should discard the token. If
+ omitted, all tokens are discarded.
+ Abbreviated cell names are acceptable, but
+ which abbreviations are legal depends on the
+ naming service available in the cell at the
+ time the command is issued.
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one.
+
+EXAMPLE
+
+ The following discards all tokens.
+
+ % unlog
+
+ The following discards only the tokens for the transarc.com
+ and athena.mit.edu cells.
+
+ % unlog transarc.com athena
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+
+
+ klog
+
+ tokens
--- /dev/null
+upclient AFS Commands upclient
+
+
+NAME
+
+ upclient -- initialize client portion of Update Server.
+
+
+ /usr/afs/bin/upclient <source machine> [-t <checking
+ frequency>] [-clear] [-crypt] <directory to
+ +
+ check>
+
+DESCRIPTION
+
+ Initializes the client portion of the Update Server. It
+ checks periodically that the files in the specified
+ directories on the local machine match those files in the
+ corresponding directory on the source machine. If a file
+ does not match, this process overwrites the local file with
+ the file from the source machine.
+
+ The -clear and -crypt flags determine whether or not
+ upclient requests that upserver encrypt the contents of the
+ files it is distributing before transferring them across the
+ network. The request applies to the files in all
+ directories requested by upclient (whereas upserver supports
+ different levels of encryption for different directories).
+ The upserver will comply with a request only if it protects
+ the directory to the same extent as specified in its
+ initialization command (i.e., will not fill an upclient's
+ request for -clear transfer if the upserver is set for
+ -crypt).
+
+ By default, the upclient in the United States edition of AFS
+ requests encryption. The upclient in the international
+ edition of AFS does not request encryption, because the
+ international edition does not provide encryption
+ capability. The -crypt flag is not available in the
+ international edition of this command.
+
+WARNING
+
+ This command is not normally issued at the command shell
+ prompt, but rather placed into a file server machine's
+ /usr/afs/local/BosConfig with the bos create command. If it
+ is ever issued at the command shell prompt, the issuer must
+ be working on a file server machine. The upclient process
+ uses the local KeyFile when generating a key for mutually
+ authenticating with the upserver process; they always
+ mutually authenticate, whether or not the data they pass is
+ encrypted.
+
+ This command does not use the syntax conventions of the AFS
+ command suites, so the command and switch names must be
+ typed in full.
+
+ The -crypt flag is not available in the international
+ edition of AFS.
+
+ Cells using the international edition of AFS should not use
+ the Update Server to distribute the contents of
+ /usr/afs/etc. The contents of this directory are sensitive,
+ and the international edition of AFS does not provide any
+
+
+
+ facility for encrypting files before transfer across the
+ network.
+
+ARGUMENTS
+
+ source machine
+ names either the cell's system control machine
+ (if directory to check is /usr/afs/etc) or the
+ binary distribution machine for the local
+ machine's CPU/operating system type (if
+ directory to check is /usr/afs/bin).
+
+ -t specifies how often the upclient process should
+ check directory to check, in number of seconds.
+ If omitted, this argument default to 300 (5
+ minutes). This number effectively determines
+ how long it will take for changes made on
+ source machine to propagate to this machine.
+
+ -clear indicates that upclient requests upserver to
+ transfer information in unencrypted form. Use
+ this flag to change the default for the United
+ States edition of AFS.
+
+ -crypt indicates that upclient requests upserver to
+ transfer information in encrypted form. With
+ the United States edition of AFS, use this flag
+ to set the default explicitly. This flag is
+ not available with the international edition of
+ AFS.
+
+ directory to check
+ names each directory to check for modified
+ files. The usual choices are:
+
+ - /usr/afs/bin, in which case the
+ recommended name for the process
+ (assigned with the -instance argument
+ on bos create) is upclientbin. The
+ source machine should be the binary
+ distribution machine for the local
+ machine's CPU/operating system type.
+ It is recommended that the -clear
+ flag be used for /usr/afs/bin, since
+ binaries are not particularly
+ sensitive and encrypting them can
+ take a long time.
+
+ - /usr/afs/etc, in which case the
+ recommended name for the process
+ (assigned with the -instance argument
+ on bos create) is upclientetc. The
+ source machine should be the system
+ control machine.
+
+ Note: This option is discouraged for
+ the international edition of AFS.
+ See the WARNING above.
+
+ - both /usr/afs/bin and /usr/afs/etc,
+ in which case the recommended name
+
+
+
+ for the process (assigned with the
+ -instance argument on bos create) is
+ upclient. The source machine should
+ be the system control machine and
+ also the binary distribution machine
+ for this machine's CPU/operating
+ system type.
+
+ Note: This option is discouraged for
+ the international edition of AFS.
+ See the WARNING above.
+
+EXAMPLES
+
+ The following bos create command creates an upclient process
+ on fs4.transarc.com that refers to fs1.transarc.com as the
+ source for both /usr/afs/bin and /usr/afs/etc (thus
+ fs1.transarc.com is both the system control machine and the
+ binary distribution machine of fs4.transarc.com's type).
+ The updates are transferred every 120 seconds. The command
+ requests /usr/afs/bin in unencrypted form. It does not
+ specify a level of encryption for /usr/afs/etc, so the
+ default is used:
+
+ - with the United States edition of AFS, upclient
+ requests /usr/afs/etc in encrypted form.
+
+ - with the international edition of AFS, upclient
+ requests /usr/afs/etc in unencrypted form, because
+ encryption of user-level data is not possible.
+ Thus, this command is not suitable with the
+ international editionMthe Update Server should not
+ be used to update /usr/afs/etc.
+
+ Type the command on a single line.
+
+ % bos create fs4.transarc.com upclient simple
+ "/usr/afs/bin/upclient fs1.transarc.com -t 120
+ /usr/afs/etc -clear /usr/afs/bin"
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList to place this
+ command in /usr/afs/local/BosConfig, because that is the
+ privilege required to issue bos create.
+
+MORE INFORMATION
+
+ bos create
+
+ upserver
--- /dev/null
+upserver AFS Commands upserver
+
+
+NAME
+
+ upserver -- initialize server portion of Update Server.
+
+
+ + +
+ /usr/afs/bin/upserver [<directory> ] [-crypt <directory> ]
+ +
+ [-clear <directory> ]
+
+DESCRIPTION
+
+ Initializes the server portion of the Update Server
+ (upserver process), specifying which of its local disk
+ directories the process is willing to distribute in response
+ to requests from the client portion of the Update Server
+ (upclient process) running on other machines. If no
+ directories are specified, the server portion can distribute
+ the contents of any directory on its local disk.
+
+ The command also determines whether the upserver is willing
+ to distribute a directory's contents in unencrypted form or
+ not. By default, the encryption level is -clear, meaning
+ that upserver transfers the directory's contents in
+ unencrypted form unless an upclient requests encryption.
+ When -crypt is specified for a directory, the upserver will
+ refuse an upclient's request for unencrypted transfer. With
+ the United States edition of AFS, the effect of -crypt is to
+ guarantee that upserver transfers a directory's contents
+ only in encrypted form. With the international edition, the
+ effect of -crypt is to prevent upserver from ever
+ transferring the directory's contents, because the upclient
+ has no way to comply with the requirement that it request
+ the contents in encrypted form (the -crypt flag on upclient
+ is not available in the international edition). Use -crypt
+ and -clear to toggle the level of encryption for directories
+ as appropriate (the EXAMPLES section illustrates their use).
+
+WARNING
+
+ This command is not normally issued at the command shell
+ prompt, but rather placed into a file server machine's
+ /usr/afs/local/BosConfig with the bos create command. If it
+ is ever issued at the command shell prompt, the issuer must
+ be working on a file server machine. The upserver process
+ uses the local KeyFile when handling keys for mutually
+ authenticating with the upclient process and encrypting
+ data. The two processes always mutually authenticate,
+ whether or not data is encrypted.
+
+ This command does not use the syntax conventions of the AFS
+ command suites, so the command and switch names must be
+ typed in full.
+
+ Cells using the international edition of AFS should not use
+ the Update Server to distribute the contents of
+ /usr/afs/etc. The contents of this directory are sensitive,
+ and the international edition of AFS does not provide any
+ facility for encrypting them before transfer across the
+ network. One way to prevent this distribution is to mark
+ /usr/afs/etc with -crypt.
+
+
+
+ARGUMENTS
+
+ directory names each directory to be distributed in
+ unencrypted form (because they appear before the
+ first -crypt or -clear flag). If omitted, all
+ directories on the machine's local disk are
+ eligible for distribution.
+
+ -crypt precedes a list of one or more directories which
+ upserver will distribute only in encrypted form.
+
+ -clear precedes a list of one or more directories which
+ upserver may distribute in unencrypted form (but
+ if upclient requests them in encrypted form, then
+ upserver encrypts them). This argument is
+ necessary only if the issuer has previously used
+ -crypt on the command line and wishes to switch
+ back to unencrypted form.
+
+EXAMPLES
+
+ The last parameter (enclosed in quotes) in the following
+ bos create command causes the upserver to distribute
+ /usr/afs/bin in unencrypted form and /usr/afs/etc in
+ encrypted form.
+
+ % bos create fs1.transarc.com upserver simple
+ "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc"
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList to place this
+ command in /usr/afs/local/BosConfig, because that is the
+ privilege required to issue bos create.
+
+MORE INFORMATION
+
+ bos create
+
+ upclient
--- /dev/null
+ AFS Commands
+
+ 1. The uss Commands and Template Lines
+
+ ------------------------------------------------------------
+
+ The uss commands help administrators create user accounts in
+ their system more easily and efficiently. Without them,
+ administering accounts can become time consuming. Creating
+ an account "by hand" requires issuing at least six separate
+ commands to five different AFS servers, whereas a single
+ uss add command can accomplish all the equivalent actions
+ once the issuer sets up the necessary template. Even
+ better, a single issue of the the uss bulk command can
+ create multiple accounts at once, after the necessary
+ preparations have been made.
+
+ Refer to chapter 11 in the Reference Manual for a complete
+ summary list of uss commands and their syntax.
+
+ 1.1 Common Arguments and Flags
+ Most uss commands accept the following optional arguments
+ and flags. They are listed in the command descriptions
+ where they apply, and are described here in detail:
+
+ [-cell <cell name>]
+
+ This argument specifies that the command should be run in
+ the cell specified by cell name. By default, commands are
+ executed in the local cell, as defined in
+ /usr/vice/etc/ThisCell on the client machine on which the
+ command is issued. The issuer may abbreviate cell name to
+ the shortest form that distinguishes it from the other cells
+ listed in /usr/vice/etc/CellServDB on the client machine on
+ which the command is issued.
+
+ [-admin <administrator to authenticate>]
+
+ This argument names the user name whom the Authentication
+ Servers should authenticate for purposes of creating an
+ Authentication Database entry. If the issuer does not
+ provide it, the authentication is attempted for the
+ effective user name (the one under which the issuer is
+ logged into the local machine's UNIX file system). With or
+ without this argument, UNIX commands invoked by this command
+ (for instance, /etc/chown) are executed under the effective
+ user name.
+ l
+ AFS Command Reference ManuaThe uss Commands and Template Li
+
+
+ [-dryrun]
+
+ This flag indicates that the command interpreter should not
+ actually execute the command, but should report all the
+ actions it would perform if executing it. This flag is
+ useful for verifying that the account will be configured as
+ the issuer wishes. It does not, however, necessarily reveal
+ failures that will result if the uss command interpreter
+ encounters any circumstances that make it impossible to
+ carry out a requested action. Combining this flag with
+ -verbose yields more information.
+
+ [-help]
+
+ This flag has the same function as the bos help command: it
+ prints the command's online help message on the screen. No
+ other arguments or flags should be provided at the same
+ time. Even if they are, this flag overrides them, and the
+ only effect of issuing the command is that the help message
+ appears.
+
+
+
+ 1.1.1 The Privilege Required for uss Commands
+ The issuer of a uss command must have all the rights
+ required for performing the equivalent actions individually.
+ See the PRIVILEGE REQUIRED section of each command
+ description for details.
--- /dev/null
+uss add AFS Commands uss add
+
+
+NAME
+
+ uss add -- create user account.
+
+
+ uss add -user <login name> [-realname <full name in
+ quotes>]
+ [-pass <initial passwd>] [-server <file server for home
+ volume>]
+ [-partition <file server's disk partition for home volume>]
+ [-mount <home directory mount point>]
+ [-uid <uid to assign the user>]
+ [-template <pathname of template file>]
+ +
+ [-verbose] [-var <auxiliary argument pairs (num val)> ]
+ [-cell <cell name>] [-admin <administrator to
+ authenticate>]
+ [-dryrun] [-overwrite] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ uss ad -us <login name> [-r <full name in quotes>]
+ [-pas <initial passwd>] [-s <file server for home volume>]
+ [-par <file server's disk partition for home volume>]
+ [-m <home directory mount point>] [-ui <uid to assign the
+ user>]
+ [-t <pathname of template file>] [-ve] [-va <auxiliary
+ +
+ argument pairs (num val)> ]
+ [-c <cell name>] [-a <administrator to authenticate>] [-d]
+ [-o] [-h]
+
+DESCRIPTION
+
+ Creates entries in the Protection Database and
+ Authentication Database for the user name login name. If
+ initial passwd is provided, it is stored as the user's
+ password in the Authentication Database after conversion
+ into a form suitable for use as an encryption key. , or the
+ By default, the Protection Server automatically allocates an
+ AFS UID for the new user; the issuer may specify an
+ alternate with the -uid argument.
+
+ The other results of the command depend on what appears in
+ the template file specified with pathname of template file.
+ The issuer must provide any argument whose corresponding
+ variable appears in the template (the ARGUMENTS section
+ below maps the arguments and variables). If the issuer
+ provides an argument for which the corresponding variable
+ does not appear in the template, the value is ignored.
+ Failure to provide a value for a variable causes the account
+ creation to fail at the point where the command interpreter
+ first encounters the variable in the template.
+
+ Syntax definitions for the lines in the template follow
+ descriptions of the uss commands.
+
+WARNING
+
+ If this command is issued on a machine running Ultrix and
+ the template file being used is not 0-length, the user must
+
+
+
+ use the -admin argument to adopt a privileged AFS identity
+ while remaining "root" in the local machine's UNIX file
+ system. Ultrix allows only "root" to issue the /etc/chown
+ command that uss add invokes to set the owner of files and
+ directories created by template lines. At the same time,
+ AFS allows only a privileged administrator to issue the AFS
+ commands invoked; "root" is not normally a privileged AFS
+ administrator.
+
+ Other operating systems allow users other than "root" to
+ issue /etc/chown, but users may still find it convenient to
+ adopt different identities in the AFS and UNIX file systems.
+ Being authenticated in AFS as a privileged user is required
+ under all operating systems.
+
+ARGUMENTS
+
+ -user specifies the user name that the user will type at
+ the login prompt. It also becomes the name of the
+ user's Protection and Authentication Database
+ entries.
+
+ Corresponding variable in template: $USER.
+
+ -realname specifies the user's real name. Surround it with
+ double quotes as delimiters, since it contains
+ spaces and possibly punctuation. If not provided,
+ it defaults to the user name provided with -user.
+
+ Corresponding variable in template: $NAME. The
+ most common use for this variable is when creating
+ a file to be incorporated as an entry in the
+ cell's /etc/passwd file.
+
+ -pass defines the user's initial password. Many UNIX
+ applications and utilities require that this be no
+ longer than eight characters; the AFS commands
+ that handle passwords accept strings of virtually
+ unlimited length. If not provided, this argument
+ defaults to the string changeme.
+
+ Corresponding variable in the template: none.
+
+ -server specifies the file server machine on which the
+ user's volume will reside.
+
+ Corresponding variable in template: $SERVER.
+
+ -partition
+ specifies the partition on file server for home
+ volume on which the user's volume will reside.
+
+ Corresponding variable in template: $PART.
+
+ -mount specifies the pathname to the user's home
+ directory. If the issuer does not provide a full
+ pathname, it is interpreted relative to the
+ working directory.
+
+ Corresponding variable in template: $MTPT, but on
+ the "V" line only. Occurrences of $MTPT on lines
+
+
+
+ following the "V" line take their value from the
+ "V" line's <mount point> field. Thus the exact
+ value of this command line argument becomes the
+ value for post-"V" line occurrences of $MTPT only
+ if $MTPT appears alone in the <mount point> field.
+
+ -uid specifies the AFS UID to be assigned to the new
+ user. It should be a positive integer. The
+ issuer may wish to pre-verify with pts listmax
+ that the intended number is greater than the
+ current largest AFS UID: if the requested AFS UID
+ is already in use, the account creation will
+ terminate with an error. If the issuer does not
+ provide this argument, the Protection Server
+ assigns an AFS UID automatically; as with manual
+ account creation, automatic allocation is
+ preferred.
+
+ Corresponding variable in template: $UID.
+
+ -template specifies which template the command interpreter
+ should consult. If the issuer does not provide
+ this argument, the command interpreter looks for a
+ template called uss.template in the following
+ directories, which it searches in this order:
+
+ 1. the working directory
+
+ 2. /afs/cellname/common/uss, where
+ cellname names the local cell
+
+ 3. /etc
+
+ If the issuer provides a name other than
+ uss.template without a pathname, the command
+ interpreter looks for it in the directories just
+ listed, in the same order. If the issuer provides
+ a full or partial pathname, the command
+ interpreter consults the specified file without
+ consulting the directories just listed; it
+ interprets partial pathnames relative to the
+ working directory.
+
+ If the template is 0-length, the new account will
+ consist solely of Protection and Authentication
+ Database entries.
+
+ -verbose causes the command interpreter to produce a more
+ detailed trace of the actions it is executing. By
+ default, only warnings and error messages appear.
+
+ -var specifies values for each of the number variables
+ $1 through $9 found in the template. The number
+ variables allow the issuer to provide values for
+ variables not built-in to the uss add command.
+
+ Corresponding variables in template: $1 through
+ $9.
+
+
+
+ Each instance of this argument has two parts,
+ separated by a space:
+
+ - an integer between 1 and 9, not preceded
+ by the dollar sign. Each number matches
+ the variable in the template.
+
+ - a value
+
+ See the chapter on uss in the AFS System
+ Administrator's Guide for further explanation.
+
+ -cell specifies the cell in which to run the command.
+ See section 7.1 in the Reference Manual for more
+ details. -admin
+ names the user whom the Authentication Servers
+ should authenticate for purposes of creating an
+ Authentication Database entry. See section 7.1 in
+ the Reference Manual for more details. Note:
+ Issuers of this command on machines running Ultrix
+ must use this argument in order to adopt an
+ privileged AFS identity while remaining "root" in
+ the local machine's UNIX file system. See the
+ preceding WARNING.
+
+ -dryrun indicates that the command interpreter should not
+ actually execute the command, but should report
+ all the actions it would perform if executing it.
+ See section 7.1 in the Reference Manual for more
+ details.
+
+ -overwrite
+ instructs the command interpreter to overwrite any
+ directories, files and links that exist in the
+ file system and for which it also finds
+ definitions on template "D", "E", "F", "L" and "S"
+ lines. If this flag is omitted, the command
+ interpreter prompts once for confirmation that the
+ issuer really wants to overwrite all such
+ elements.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 7.1 in the Reference Manual for
+ more details.
+
+EXAMPLES
+
+ When the template is 0-length, the following creates a
+ "dummy" account called admin with entries in the Protection
+ and Authentication Databases only.
+
+ % uss add admin
+
+ The combination of the following "V" line in the template
+ uss.tpl and uss add command creates Protection and
+ Authentication Database entries for user name smith. It
+ would also create a volume called user.smith with a quota of
+ 2500 kilobyte blocks, mounted at
+ /afs/transarc.com/usr/smith, the ACL for which gives smith
+ all rights. See the description of the "V" line for an
+
+
+
+ explanation of its fields. Note that only the template's
+ name is provided, not its pathname, as it is assumed it
+ resides in one of the three expected directories.
+
+ V user.$USER $SERVER.transarc.com /vice$PART $1
+ /afs/transarc.com/usr/$USER $UID $USER all
+
+ % uss add smith "John Smith" js_pswd fs2 b -t uss.tpl -v 1
+ 2500
+
+ The chapter on uss in the AFS System Administrator's Guide
+ presents more extended examples of template lines and
+ commands.
+
+PRIVILEGE REQUIRED
+
+ Issuer (or person named with -admin flag) must belong to the
+ system:administrators group in the Protection Database and
+ must have the ADMIN flag in his or her Authentication
+ Database entry. If the template contains a "V" line, the
+ issuer must be listed in /usr/afs/etc/UserList and must have
+ at least ADMINISTER and INSERT rights in the directory where
+ the mount point is to be created. If the template includes
+ lines that create other types of objects (directories, files
+ or links), the issuer must have the privilege(s) necessary
+ to create them.
+
+ Under Ultrix, only "root" can issue the /etc/chown command
+ invoked when a file or directory is created. See the
+ WARNING section.
--- /dev/null
+uss apropos AFS Commands uss apropos
+
+
+NAME
+
+ uss apropos -- show each help entry containing keyword.
+
+
+ uss apropos -topic <help string> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ uss ap -t <help string> [-h]
+
+DESCRIPTION
+
+ Displays the first line of the help entry for any uss
+ command that has help string in its name or short
+ description.
+
+ARGUMENTS
+
+ -topic specifies the keyword string to search for. If it
+ is more than a single word, surround it with
+ double quotes or other delimiters. Type all help
+ strings for uss commands in all lowercase letters.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 7.1 in the Reference Manual for
+ more details.
+
+OUTPUT
+
+ The first line of a command's online help entry names the
+ command and briefly describes what it does. The uss apropos
+ command displays that first line for any uss command where
+ help string is part of the command name or first line.
+
+ To see the remaining lines in a help entry, which provide
+ the command's alias (if any) and syntax, use the uss help
+ command.
+
+EXAMPLE
+
+ The following lists all uss commands that have the word
+ "create" in their operation code or short online
+ description.
+
+ % uss apropos create
+ add: create a new user
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ uss help
--- /dev/null
+uss bulk AFS Commands uss bulk
+
+
+NAME
+
+ uss bulk -- execute multiple uss commands.
+
+
+ uss bulk -file <bulk input file> [-template <pathname of
+ template file>]
+ [-verbose] [-cell <cell name>]
+ [-admin <administrator to authenticate>] [-dryrun]
+ [-overwrite]
+ [-help]
+
+ uss b -f <bulk input file> [-t <pathname of template
+ file>] [-v] [-c <cell name>]
+ [-a <administrator to authenticate>] [-d] [-o] [-h]
+
+DESCRIPTION
+
+ Executes the uss commands listed in bulk input file, which
+ must already exist. If bulk input file has add commands in
+ it that create complete (rather than authentication-only)
+ accounts, then the issuer must also specify a template using
+ pathname of template file.
+
+WARNING
+
+ The following warning applies when all of the following are
+ true:
+
+ - this command is issued on machines running Ultrix
+
+ - the bulk file contains add lines
+
+ - the template file used for the account creations
+ is not 0-length.
+
+ In this set of circumstances, the issuer must use the -admin
+ argument to adopt a privileged AFS identity while remaining
+ "root" in the local machine's UNIX file system. Ultrix
+ allows only "root" to issue the /etc/chown command that the
+ add command invokes to set the owner of files and
+ directories created by template lines. At the same time,
+ AFS allows only a privileged administrator to issue the AFS
+ commands invoked; "root" is not normally a privileged AFS
+ administrator.
+
+ Other operating systems allow users other than "root" to
+ issue /etc/chown, but users may still find it convenient to
+ adopt different identities in the AFS and UNIX file systems.
+ Being authenticated in AFS as a privileged user is required
+ under all operating systems.
+
+ARGUMENTS
+
+ -file names the file containing the uss commands to
+ execute. If the issuer does not provide a
+ pathname, the command interpreter assumes the file
+ is in the working directory. The BULK FILE FORMAT
+ section details the proper format for command
+ lines in the bulk file.
+
+ -template names the template file for any add commands that
+
+
+
+ appear in the bulk input file. If the issuer does
+ not provide a pathname, the command interpreter
+ assumes the template file is in the working
+ directory. See the AFS System Administrator's
+ Guide for a definition of template format.
+
+ -verbose causes the command interpreter to produce (on
+ stdout) a more detailed trace of the actions it is
+ executing. By default, only warnings and error
+ messages appear.
+
+ -cell specifies the cell in which to run the command.
+ See section 7.1 in the Reference Manual for more
+ details. -admin
+ names the user whom the Authentication Servers
+ should authenticate for purposes of creating an
+ Authentication Database entry. See section 7.1 in
+ the Reference Manual for more details. Note: When
+ the bulk file contains add lines, issuers of the
+ uss bulk command on machines running Ultrix must
+ use this argument in order to adopt an privileged
+ AFS identity while remaining "root" in the local
+ machine's UNIX file system. See the preceding
+ WARNING.
+
+ -dryrun indicates that the command interpreter should not
+ actually execute the command, but should report
+ all the actions it would perform if executing it.
+ See section 7.1 in the Reference Manual for more
+ details.
+
+ -overwrite
+ instructs the command interpreter (when add lines
+ appear in the bulk file) to overwrite any
+ directories, files and links that exist in the
+ file system related to the user for which it also
+ finds definitions on template "D", "E", "F", "L"
+ and "S" lines. If this flag is omitted, the
+ command interpreter prompts, once for each add
+ line in the bulk file, for confirmation that the
+ issuer really wants to overwrite those elements.
+ This flag should not be used if the bulk file does
+ not contain add lines.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 7.1 in the Reference Manual for
+ more details.
+
+BULK FILE FORMAT
+
+ Five types of command lines can appear in the bulk file:
+ add, delete, exec, savevolume, and delvolume. Each command
+ line should have a carriage return only at the end, even
+ though it may cover several lines on the screen.
+
+
+
+ The add line
+
+ Each add line is the equivalent of a uss add command issued
+ on the command line. Begin the line with "add" only, not
+ "uss add", and provide the arguments in the same order they
+ would appear on the uss add command line, separating each
+ with a colon. Only the first argument, corresponding to the
+ command line argument -user, is required. To omit a value
+ for an argument (presumably because it is optional or the
+ template specifies a constant value for it), type nothing
+ between two colons. After the last argument provided, end
+ the line with either a colon and carriage return, or a
+ carriage return alone.
+
+ The eighth through seventeenth fields are for assigning
+ values to the number variables, with the fields listed in
+ increasing numerical order. The issuer must indicate either
+ a value or an empty field (nothing between two colons) for
+ every variable that precedes the last one being assigned an
+ actual value. It is acceptable, but not necessary, to
+ indicate empty fields for any number variables following the
+ last one actually assigned a value.
+
+ The following concrete representation uses the same
+ identifiers for arguments as the uss add definition. The "{
+ }" notation indicates that each entry between vertical bars
+ is one possible choice. Remember that an instruction like
+ this would appear on a single line in the actual bulk file.
+
+ add <login name>[:<full name>][:<initial passwd>][:<file
+ [:<file server's disk partition for home volume>][:<home
+ [:<uid to assign the user>][:{<var1> | :<var1>:<var2> | :
+ . . . . et cetera through. . . .
+ | :<var1>:<var2>:<var3>:<var4>:<var5>:<var6>:<var7>:<var8
+
+ Do not surround full name with double quotes in the bulk
+ file, even though its counterpart on the regular uss add
+ command line must be so surrounded.
+
+ The EXAMPLES section below may help to clarify the format of
+ the add line.
+
+ The delete line
+
+ Each delete line is the equivalent of a uss delete command
+ issued on the command line. Begin the line with "delete"
+ only, not "uss delete", and provide the arguments in the
+ same order they would appear on the uss delete command line,
+ separating each with a colon. Provide values for at least
+ the first two arguments (corresponding to -user and
+ -mountpoint on the command line). The third field,
+ corresponding to -savevolume, is optional; there are three
+ possible values:
+
+ - if the word savevolume appears, the volume and
+ VLDB entry will not be removed
+
+ - if the word delvolume appears, the volume and VLDB
+ entry will be removed
+
+ - if the field is blank, then the volume will be
+
+
+
+ treated according to the prevailing default (see
+ the following description of the savevolume and
+ delvolume lines to learn how to set the default).
+
+ After the last argument provided, end the line with either a
+ colon and carriage return or a carriage return alone.
+
+ The following concrete representation uses the same
+ identifiers for arguments as does the uss delete definition.
+ The "{ }" notation indicates that each entry between a
+ vertical line is one possible choice. Remember that an
+ instruction like this would appear on a single line in the
+ actual bulk file. The EXAMPLES section illustrates use of
+ this line.
+
+ delete <account name>:<full mount point pathname>
+ [:{savevolume | delvolume | }]
+
+ The exec line
+
+ This line causes the indicated UNIX shell command to be
+ executed. Its format is
+
+ exec <command string to execute>
+
+ The savevolume and delvolume lines
+
+ The savevolume and delvolume lines set the default treatment
+ of volumes in delete lines that follow them in the bulk
+ file. The savevolume line prevents the removal of volume
+ and VLDB entry for all subsequent delete lines. The
+ delvolume line causes the removal of volume and VLDB entry
+ for all subsequent delete lines. The default treatment if
+ neither line appears in a bulk file is to remove the volume
+ and VLDB; delete lines that appear before the first
+ savevolume line are also treated this way.
+
+ An explicit savevolume or delvolume instruction in the third
+ field of an individual delete line overrides the default in
+ effect at the time. If nothing appears in the third field,
+ the default is obeyed.
+
+ Neither command takes arguments (the word savevolume or
+ delvolume should appear by itself on the line). The effect
+ of either line lasts until the end of the bulk file, or
+ until its opposite appears in the file. Multiple instances
+ of each command can be used to toggle back and forth between
+ removal and non-removal of volumes.
+
+EXAMPLES
+
+ The following shows the proper format for an add line in the
+ bulk file when only the first (required) argument is
+ provided, and when the first three arguments are provided.
+ In the first case, the user's "real name" is set to anderson
+ and password to changeme (the defaults).
+
+ add anderson
+ add smith:John Smith:js_pswd
+
+ The following add line example supposes that the Transarc
+
+
+
+ Corporation cell uses a template with the following "V" line
+ in it:
+
+ V user.$USER $SERVER.transarc.com /vicep$PART 2000
+ /afs/transarc.com/usr/$3/$USER $UID $USER all
+
+ To create an account for users John Smith from the Marketing
+ Department and Pat Jones from the Finance Department, the
+ appropriate add commands in the bulk file might be:
+
+ add smith:John Smith::fs1:a:::::marketing
+ add jones:Pat Jones::fs3:c:::::finance
+
+ The effect would be to establish an account called smith in
+ the Protection and Authentication Databases, with an initial
+ password changeme and a value for $UID provided by the
+ Protection Server. His volume, user.smith, would reside on
+ partition "/vicepa" of file server machine
+ "fs1.transarc.com" and would be mounted at
+ /afs/transarc.com/usr/marketing/smith. He would own his
+ home directory and have full access to it. The account for
+ jones would be similar, except that it would reside on
+ partition "/vicepc" of file server machine
+ "fs3.transarc.com" and would be mounted at
+ /afs/transarc.com/usr/finance/jones.
+
+ Notice that the fields corresponding to <home directory
+ mount point>, <uid to assign the user>, <var1> and <var2>
+ are empty (between a and marketing on the first example
+ line) since their corresponding variables do not appear in
+ the template file. The <initial passwd> field is also
+ empty.
+
+ The issuer could, if he or she choose, specify values/empty
+ fields for all nine number variables. In this case, the
+ bulk file lines shown above would look like:
+
+ add smith:John Smith::fs1:a:::::marketing::::::
+ add jones:Pat Jones::fs3:c:::::finance::::::
+
+ The following shows a complete bulk file containing a set of
+ delete lines combined with a savevolume line. Because
+ smith, pat, and rogers appear before the savevolume command
+ and their third field is blank, the volume will be removed.
+ The volume for terry will not be removed, but johnson's will
+ be because the delvolume in the third field overrides the
+ current default.
+
+ delete smith:/afs/transarc.com/usr/smith
+ delete pat:/afs/transarc.com/usr/pat
+ delete rogers:/afs/transarc.com/usr/rogers
+ savevolume
+ delete terry:/afs/transarc.com/usr/terry
+ delete johnson:/afs/transarc.com/usr/johnson:delvolu
+
+ The following exec example supposes that the bulk file
+ contains a set of add lines followed by delete lines. The
+ operator places this line between the two sets to flag when
+ the additions are finished and the deletions beginning.
+
+ exec echo "Additions completed; beginning deletions.
+
+
+
+PRIVILEGE REQUIRED
+
+ Issuer (or person named by -admin argument) must have the
+ privileges necessary to run all of the commands in the bulk
+ file individually.
+
+MORE INFORMATION
--- /dev/null
+Template "D" line AFS Commands Template "D" line
+
+
+NAME
+
+ Template "D" line -- create a directory.
+
+
+ D <pathname> <mode> <owner> <access list>
+
+DESCRIPTION
+
+ Creates a directory anywhere in the file system. It
+ intended use is to create a subdirectory in the home
+ directory defined on the preceding "V" line.
+
+ The "D" line should appear after the "V" line if any
+ variables in it take their values from the "V" line
+ (notably, $MTPT). Any number of "D" lines may appear in a
+ template.
+
+WARNING
+
+ Using the "D" line to create directories outside AFS (e.g.,
+ in the UNIX file system of the workstation where the uss
+ command is being issued) introduces two complications:
+
+ - The first complication arises if the issuer wishes
+ to set the <owner> field to something other than
+ his or her own user name or UNIX UID. The default
+ owner of a UNIX file system directory is the user
+ who created it (in this case, the issuer of the
+ uss command). Changing this default, which uss
+ will attempt if anything other than the issuer's
+ name appears in the <owner> field, requires
+ issuing the chown command, which in turn requires
+ being the super-user "root". If the issuer wishes
+ to specify an alternate owner, he or she must be
+ "root" in the UNIX file system and use the -admin
+ flag in order to be recognized in AFS as a
+ privileged administrator. See the description of
+ the -admin argument for uss add and uss bulk.
+
+ - The second complication is that it is not possible
+ to associate an ACL with a non-AFS directory, so
+ uss will always print a warning message about
+ that. It will create the directory nonetheless,
+ and the <access list> field must always be
+ provided.
+
+ The preferred method for automatic placement of directories
+ on the local disk is the package program, which runs as
+ "root".
+
+ARGUMENTS
+
+ D should be a capital letter and tells the command
+ interpreter that this is a directory-creation
+ instruction.
+
+ pathname is the full pathname of the directory.
+
+ mode sets the UNIX mode bits for the directory.
+ Provide a four-digit decimal number in this field,
+
+
+
+ such as 0755 or 0744. Keep in mind that the
+ "user" x bit must be turned on for a directory.
+
+ owner names the directory's owner (in the UNIX file
+ system sense). If the directory is being placed
+ in AFS, the $UID variable should appear in this
+ field. If the directory is being placed into the
+ UNIX file system rather than AFS, this field must
+ contain the user name or UNIX UID of the uss
+ command's issuer, or the account creation will
+ abort at that point.
+
+ access list
+ defines the access control list for the new home
+ directory. It must be included for non-AFS
+ directories, even though it is ignored in that
+ case. The list may define one or more pairs, each
+ consisting of
+
+ - a user name or Protection Database group
+ name
+
+ - the access rights
+
+ separated by a space. See the fs setacl command
+ to learn about the access rights available with
+ AFS.
+
+ At the least, the new user needs to be given all
+ access rights. This could be achieved with
+
+ $USER all
+
+ Unlike the "V" line, there are no default pairs on
+ the ACL of a directory created with a "D" line.
+ However, as with the "V" line it is not possible
+ to grant any rights to the issuer of the uss
+ command. As the last step in account creation,
+ the uss command interpreter automatically deletes
+ that person from any access control lists set
+ during the creation process.
+
+EXAMPLE
+
+ The following creates a public directory in the user's home
+ directory, makes the user own the directory and gives
+ him/her all access rights.
+
+ D $MTPT/public 0755 $UID $USER all
--- /dev/null
+uss delete AFS Commands uss delete
+
+
+NAME
+
+ uss delete -- delete user account from system.
+
+
+ uss delete -user <login name>
+ -mountpoint <mount point for user's volume> [-savevolume]
+ [-verbose] [-cell <cell name>]
+ [-admin <administrator to authenticate>] [-dryrun] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ uss d -u <login name> -m <mount point for user's volume>
+ [-s] [-v] [-c <cell name>]
+ [-a <administrator to authenticate>] [-d] [-h]
+
+DESCRIPTION
+
+ Deletes an AFS user account from the system by deleting the
+ user's
+
+ - Protection Database entry
+
+ - Authentication Database entry
+
+ - volume and VLDB entry, unless the issuer includes
+ the -savevolume flag to prevent the deletion. If
+ the volume is to be deleted, the issuer may first
+ wish to transfer its contents to tape for possible
+ restoration.
+
+ - the home directory mount point from the file tree.
+ This happens even if the -savevolume flag is
+ provided.
+
+ARGUMENTS
+
+ -user specifies the user name to remove from the
+ Protection and Authentication Databases.
+
+ -mountpoint
+ specifies the pathname to the user's home
+ directory. The volume mounted at that location is
+ deleted from the system. If the issuer does not
+ provide a full pathname, it is interpreted
+ relative to the working directory.
+
+ -savevolume
+ prevents the user's volume and VLDB entry from
+ being deleted from the system.
+
+ -verbose causes the command interpreter to produce on
+ standard output (stdout) a more detailed trace of
+ the actions it is executing. By default, only
+ warnings and error messages appear.
+
+ -cell specifies the cell in which to run the command.
+ See section 7.1 in the Reference Manual for more
+ details. -admin
+ names the user whom the Authentication Servers
+ should authenticate for purposes of creating an
+
+
+
+ Authentication Database entry. See section 7.1 in
+ the Reference Manual for more details. -dryrun
+ indicates that the command interpreter should not
+ actually execute the command, but should report
+ all the actions it would perform if executing it.
+ See section 7.1 in the Reference Manual for more
+ details.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 7.1 in the Reference Manual for
+ more details.
+
+EXAMPLES
+
+ The following removes smith's user account from the
+ transarc.com cell, but prevents deletion of the user.smith
+ volume.
+
+ % uss del smith /afs/transarc.com/usr/smith -save
+
+PRIVILEGE REQUIRED
+
+ Issuer (or person named by -admin argument) must belong to
+ the system:administrators group in the Protection Database,
+ must have the ADMIN flag in his or her Authentication
+ Database entry, and must have at least ADMINISTER and DELETE
+ rights in the directory from which the mount point is to be
+ removed. To remove volumes (i.e., if the -savevolume flag
+ is not used), the issuer must be listed in
+ /usr/afs/etc/UserList.
--- /dev/null
+Template "E" line AFS Commands Template "E" line
+
+
+NAME
+
+ Template "E" line -- create a single-line file.
+
+
+ E <pathname> <mode> <owner> "<contents>"
+
+DESCRIPTION
+
+ Creates a file anywhere in the file system by echoing what
+ appears in the <contents> field into the new file. Its
+ intended use is the creation of files in the new user home
+ directory or its subdirectories.
+
+ The "E" line's advantage over the "F" line is that variables
+ may appear in the <contents> field. The command interpreter
+ replaces the variables with appropriate values before
+ creating the file. (In contrast, the contents of a file
+ created using the "F" line are the same for everyone.)
+ However, the "E" line restricts the contents of the new file
+ to a single line, since no carriage returns (newline
+ characters) can occur in the <contents> field.
+
+ An "E" line should appear in the template after the "D" line
+ that creates the directory the file is to reside in. Any
+ number of "E" lines may appear in a template.
+
+WARNING
+
+ Using the "E" line to create a file outside AFS (e.g., in
+ the UNIX file system of the client machine where the uss
+ command is being issued) introduces a potential complication
+ if the issuer wishes to set the <owner> field to something
+ other than his or her own user name or UNIX UID. The
+ default owner of a UNIX file system directory is the user
+ who created it (in this case, the issuer of the uss
+ command). Changing this default, which uss will attempt if
+ anything other than the issuer's name appears in the <owner>
+ field, requires issuing the chown command, which in turn
+ requires being the super-user "root". If the issuer wishes
+ to specify an alternate owner, he or she must be "root" in
+ the UNIX file system and use the -admin flag in order to be
+ recognized in AFS as a privileged administrator. See the
+ description of the -admin argument for uss add and uss bulk.
+
+ The preferred method for automatic placement of files on the
+ local disk is the package program, which runs as "root".
+
+ARGUMENTS
+
+ E should be a capital letter and tells the command
+ interpreter that this is a file-creation
+ instruction.
+
+ pathname is the full pathname of the file to be created.
+
+ mode sets the UNIX mode bits for the file. Provide a
+ four-digit decimal number in this field, such as
+ 0666 or 0644.
+
+ owner names the file's owner (in the UNIX file system
+
+
+
+ sense). If the file is being placed in AFS, the
+ $UID variable should appear in this field. If the
+ file is being placed into the UNIX file system
+ rather than AFS, this field must contain the user
+ name or UNIX UID of the uss command's issuer, or
+ the account creation will abort at that point.
+
+ contents defines the one-line string that is to become the
+ contents of the new file. Surround it with double
+ quotes in case it contains spaces. It may contain
+ variables, which the command interpreter will
+ resolve before creating the file, but may not
+ contain carriage returns (newline characters).
+
+EXAMPLE
+
+ The following creates an file in the current working
+ directory called user_name.etcp containing an entry suitable
+ for incorporating into the cell's global /etc/passwd file.
+
+ E $USER.etcp 0644 root "$USER:X:$UID:10:$NAME:$MTP
--- /dev/null
+Template "F" line AFS Commands Template "F" line
+
+
+NAME
+
+ Template "F" line -- create a file by copying a prototype.
+
+
+ F <pathname> <mode> <owner> <prototype>
+
+DESCRIPTION
+
+ Creates a file anywhere in the file system by copying the
+ contents of an existing "prototype" file into the new file.
+ Its intended use is creation of standard files in the new
+ user's home directory or a subdirectory of it. Include one
+ "F" line for each file to be created.
+
+ "F" lines should appear in the template after the "D" lines
+ that define the subdirectories they go in. Any number of
+ "F" lines may appear in a template.
+
+WARNING
+
+ Using the "F" line to create a file outside AFS (e.g., in
+ the UNIX file system of the client machine where the uss
+ command is being issued) introduces a potential complication
+ if the issuer wishes to set the <owner> field to something
+ other than his or her own user name or UNIX UID. The
+ default owner of a UNIX file system directory is the user
+ who created it (in this case, the issuer of the uss
+ command). Changing this default, which uss will attempt if
+ anything other than the issuer's name appears in the <owner>
+ field, requires issuing the chown command, which in turn
+ requires being the super-user "root". If the issuer wishes
+ to specify an alternate owner, he or she must be "root" in
+ the UNIX file system and use the -admin flag in order to be
+ recognized in AFS as a privileged administrator. See the
+ description of the -admin argument for uss add and uss bulk.
+
+ The preferred method for automatic placement of files on the
+ local disk is the package program, which runs as "root".
+
+ARGUMENTS
+
+ F should be a capital letter and tells the command
+ interpreter that this is a file-creation
+ instruction.
+
+ pathname is the full pathname of the file to be created.
+
+ mode sets the UNIX mode bits for the file. Provide a
+ four-digit decimal number in this field, such as
+ 0666 or 0644.
+
+ owner names the file's owner (in the UNIX file system
+ sense). If the directory is being placed in AFS,
+ the $UID variable should appear in this field. If
+ the directory is being placed into the UNIX file
+ system rather than AFS, this field must contain
+ the user name or UNIX UID of the uss command's
+ issuer, or the account creation will abort at that
+ point.
+
+ prototype specifies the complete pathname of the file whose
+
+
+
+ contents are to be copied into the new file. It
+ may reside in either AFS or the local UNIX file
+ system.
+
+EXAMPLE
+
+ The following, appropriate for the Transarc Corporation
+ cell, copies a standard .login file (kept in
+ /afs/transarc.com/common/uss/skel) into user home
+ directories. This would appear on a single line in the
+ actual template.
+
+ F $MTPT/.login 0644 $UID
+ /afs/transarc.com/common/uss/skel/.login
--- /dev/null
+Template "G" line AFS Commands Template "G" line
+
+
+NAME
+
+ Template "G" line -- define directory for even distribution
+
+ of home directories.
+
+
+ G <directory>
+
+DESCRIPTION
+
+ Defines a directory to be considered as a value for the
+ $AUTO variable. Define a separate "G" line for each
+ directory to be considered. All "G" lines, and there may be
+ any number, must appear in the template before any
+ occurrences of the $AUTO variable.
+
+ The intended use of the "G" line is to distribute user
+ accounts randomly among several directories, rather than
+ using divisions that reflect real-world divisions (such as
+ departmental affiliation).
+
+ Creating multiple "usr" directories in this fashion (perhaps
+ numbered as usr1, usr2 and so on) is useful mostly in a very
+ large cell where having all user home directories together
+ in one usr directory could cause slow lookup. In such a
+ case, the $AUTO variable goes in the <mount point> field in
+ the "V" line. The command interpreter then selects from
+ among the directories defined on "G" lines the one with the
+ fewest entries. See the chapter on uss in the AFS System
+ Administrator's Guide for more information.
+
+ARGUMENTS
+
+ G should be a capital letter and tells the
+ command interpreter that this line defines a
+ directory to be considered as a value for
+ the $AUTO variable.
+
+ directory defines a pathname. It may be either a
+ complete pathname or only the final element
+ (the directory itself). The choice affects
+ the form of the "V" line <mount-point>
+ field's value, as shown in the EXAMPLES
+ section.
+
+EXAMPLES
+
+ If the Transarc Corporation cell's administrators decided to
+ distribute user home directories evenly into three
+ directories, they would define three "G" lines:
+
+ G usr1
+ G usr2
+ G usr3
+
+ and then put
+
+ /afs/transarc.com/$AUTO/$USER
+
+ in the "V" line <mount-point> field.
+
+
+
+ Alternatively, they could put the entire pathname for the
+ usr directories on the "G" line:
+
+ G /afs/transarc.com/usr1
+ G /afs/transarc.com/usr2
+ G /afs/transarc.com/usr3
+
+ in which case the "V" line <mount-point> field would specify
+ simply
+
+ $AUTO/$USER
--- /dev/null
+uss help AFS Commands uss help
+
+
+NAME
+
+ uss help -- show syntax of specified uss command(s) or list
+
+ functional description for all of them.
+
+
+ +
+ uss help [-topic <help string> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ uss h [-t <help string> ] [-h]
+
+DESCRIPTION
+
+ Displays the first line (name and short description) of
+ every uss command's help entry, if no help string is
+ provided. For each operation code specified with -topic, it
+ outputs the entire help entry. See the Output section
+ below.
+
+ARGUMENTS
+
+ -topic specifies the operation code(s) for which syntax
+ is to be provided. If it is omitted, the output
+ instead provides a short description of all uss
+ commands.
+
+ -help prints the online help for this command. Do not
+ provide any other arguments or flags with this
+ one. See section 7.1 in the Reference Manual for
+ more details.
+
+OUTPUT
+
+ The online help entry for each uss command consists of two
+ or three lines.
+
+ - The first line names the command and briefly
+ describes what it does.
+
+ - If the command has aliases, they will appear on
+ the next line.
+
+ - The final line, which begins with "Usage:", lists
+ the command's arguments and flags in the
+ prescribed order. Online help entries use the
+ same symbols (brackets, etc.) as the command
+ definitions in this manual. For an explanation of
+ their meaning, see page v of the introductory
+ About This Manual chapter.
+
+
+
+EXAMPLE
+
+ The following displays the online help entry for the
+ uss bulk command.
+
+ % uss help bulk
+ uss bulk: bulk input mode
+ Usage: uss bulk -file <bulk input file> [-template <path
+ of template file>] [-verbose] [-cell <cell name>] [-dryr
+ [-help]
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ uss apropos
--- /dev/null
+Template "L" line AFS Commands Template "L" line
+
+
+NAME
+
+ Template "L" line -- create hard link.
+
+
+ L <existing-file> <link>
+
+DESCRIPTION
+
+ Creates a "hard link" between two files, as achieved by the
+ standard Unix ln command. An explanation of links is beyond
+ the scope of this document, but the basic effect is to
+ create a second name for an existing file, so that it can be
+ accessed via either name. It does not create a second copy
+ of the file.
+
+ AFS allows hard links only between files that reside in the
+ same directory. This restriction is necessary to eliminate
+ the confusion that would result from associating two
+ potentially different ACLs (those of the two directories)
+ with the same file. However, symbolic links are legal
+ between two files that reside in different directories and
+ even volumes (see the section on the template "S" line).
+
+ "L" lines should appear in the template after "D" lines;
+ they should also appear after "F" and "E" lines if either of
+ the files being linked were created on such a line. Any
+ number of "L" lines may appear in a template.
+
+ARGUMENTS
+
+ L should be a capital letter and tells the
+ command interpreter that this instruction
+ creates a hard link.
+
+ existing-file is the complete pathname of the existing
+ file.
+
+ link is the complete pathname of the second name
+ for the file.
+
+EXAMPLE
+
+ The following links the file mail to the file mbox in the
+ home directory.
+
+ L $MTPT/mbox $MTPT/mail
--- /dev/null
+Template "S" line AFS Commands Template "S" line
+
+
+NAME
+
+ Template "S" line -- create symbolic link.
+
+
+ S <existing-file> <link>
+
+DESCRIPTION
+
+ Creates a "symbolic link" between two files, as achieved by
+ the standard Unix ln -s command. An explanation of links is
+ beyond the scope of this document, but the basic effect is
+ to create a second name for an existing file, so that it can
+ be accessed via either name. It does not create a second
+ copy of the file.
+
+ AFS allows symbolic links to cross mount points (that is,
+ the linked files may reside in different volumes).
+
+ "S" lines should appear in the template after "D" lines;
+ they should also appear after "F" and "E" lines if either of
+ the files being linked were created on such a line. Any
+ number of "S" lines may appear in a template.
+
+ARGUMENTS
+
+ S should be a capital letter and tells the
+ command interpreter that this instruction
+ creates a symbolic link.
+
+ existing-file is the complete pathname of the existing
+ file.
+
+ link is the complete pathname of the second name
+ for the file.
+
+EXAMPLE
+
+ The following, appropriate for the Transarc Corporation
+ cell, links the file outgoing in the Mail subdirectory to
+ the file /afs/transarc.com/common/mail/outgoing.
+
+ S /afs/transarc.com/common/mail/outgoing $MTPT/Mail/o
--- /dev/null
+Template "V" line AFS Commands Template "V" line
+
+
+NAME
+
+ Template "V" line -- create a volume.
+
+
+ V <volume name> <server> <partition> <quota> <mount point>
+ <owner>
+ <access list>
+
+DESCRIPTION
+
+ Has several effects:
+
+ - creates a volume
+
+ - creates a VLDB entry for the volume
+
+ - mounts the volume in the file system at the
+ indicated place in the file tree, effectively
+ creating the user's home directory
+
+ - sets the owner of the home directory
+
+ - sets the home directory's access control list
+
+ A template file may contain only one "V" line, and must
+ contain one unless the file is 0-length. No other lines are
+ necessary. (This does not imply that the "V" line must be
+ the first line in the template when there are others. If
+ the $AUTO variable appears on the "V" line, then the "G"
+ lines that provide values for it must appear above the "V"
+ line.)
+
+ARGUMENTS
+
+ V should be a capital letter and tells the command
+ interpreter that this is a volume-creation
+ instruction.
+
+ volume name
+ is the volume's name, under which it will be
+ listed in the VLDB.
+
+ By convention, AFS user volume names have a user.
+ prefix followed by the user name. This is achieved
+ by specifying
+
+ user.$USER
+
+ in this field.
+
+ server is the file server machine that will house the
+ volume. It is safest to provide a complete
+ Internet-style host name in this field. The
+ interpretation of a shortened form depends on the
+ state of the cell's name server when the uss add
+ command is executed.
+
+
+
+ partition defines which partition on server will house the
+ volume.
+
+ Acceptable variants of the standard /vicepx-style
+ name are:
+
+ /vicepa = vicepa = a =
+
+ /vicepb = vicepb = b =
+
+ and so on up to
+
+ /vicepz = vicepz = z =
+
+ quota defines the maximum amount of disk space the
+ volume will be able to take up. Specify a number
+ of kilobyte blocks (so a value of 1024 means a
+ megabyte).
+
+ mount point
+ defines the directory to be created as a mount
+ point for the volume. The specified directory
+ serves as the root directory for the volume named
+ in the <volume name> field.
+
+ By convention, AFS cells call home directories by
+ the user's user name, so the $USER variable may be
+ part of this field.
+
+ Note: This field defines the value of any
+ occurrences of the $MTPT variable on subsequent
+ lines in the template.
+
+ owner names the owner (in the UNIX file system sense) of
+ the home directory named in the <mount point>
+ field. This field should contain the $UID
+ variable.
+
+ access list
+ defines the access control list for the new home
+ directory. The list may define one or more pairs,
+ each consisting of
+
+ - a user name or Protection Database group
+ name
+
+ - the access rights
+
+ separated by a space. See the fs setacl command
+ to learn about the access rights available with
+ AFS.
+
+ At the least, the new user needs to be given all
+ access rights. This could be achieved with
+
+ $USER all
+
+ The pairs specified are added to a default pair
+ that grants system:anyuser the READ and LOOKUP
+ rights. Do not attempt to grant any rights to the
+ issuer of the uss command. As the last step in
+
+
+
+ account creation, the uss command interpreter
+ automatically deletes that person from any access
+ control lists set during the creation process.
+
+
+
+EXAMPLE
+
+ The following, appropriate for the Transarc Corporation
+ cell, creates a volume called user.user name on the /vicepa
+ partition of the specified file server machine, assigning it
+ a quota of 3000 kilobyte blocks. The volume is mounted in
+ /afs/transarc.com/usr as the value of $USER. The user owns
+ the home directory and has all access rights to it. This
+ line would appear on a single line in the actual template.
+
+ V user.$USER $SERVER.transarc.com /vicepa 3000
+ /afs/transarc.com/usr/$USER $UID $USER all
--- /dev/null
+Template "X" line AFS Commands Template "X" line
+
+
+NAME
+
+ Template "X" line -- execute command.
+
+
+ X <command>
+
+DESCRIPTION
+
+ Executes the indicated command, which may be a standard UNIX
+ or AFS command. The command may include any standard
+ template variables, which the uss command interpreter will
+ resolve before passing the command on to the appropriate
+ other command interpreter.
+
+ "X" lines should appear in the template after the definition
+ of any elements they affect or variables they refer to. Any
+ number of "X" lines may appear in a template. Each line
+ must be a single line only (cannot contain carriage returns
+ or new line characters within the <command> field).
+
+ARGUMENTS
+
+ X should be a capital letter and tells the
+ command interpreter that this instruction
+ executes a command.
+
+ command is the command to be executed. Surround it
+ with double quotes in case it contains
+ spaces. It may contain variables, which the
+ command interpreter will resolve before
+ executing the command, but may not contain
+ carriage returns (newline characters).
+
+EXAMPLE
+
+ The following, appropriate for the Transarc Corporation
+ cell, mounts the Backup version of the user's volume at the
+ OldFiles subdirectory.
+
+ X "fs mkm /afs/transarc.com/usr/$USER/OldFiles user.$
--- /dev/null
+vldb_convert AFS Commands vldb_convert
+
+
+NAME
+
+ vldb_convert -- convert Volume Location Database from AFS
+
+ 3.1 to AFS 3.2.
+
+
+ vldb_convert [initcmd] [-to <goal version>] [-from
+ <current version>]
+ [-path <pathname>] [-showversion] [-help]
+
+ACCEPTABLE ABBREVIATIONS
+
+ The name of this command must be typed in full. However,
+ its switches can be omitted (if appropriate) or abbreviated
+ as follows:
+
+ vldb_convert [-t <goal version>] [-f <current version>]
+ [-p <pathname>] [-s] [-h]
+
+DESCRIPTION
+
+ Converts a Volume Location Database (VLDB) from AFS 3.1
+ format to AFS 3.2 format. Due to a limitation in the VLDB
+ in prior versions of AFS, a cell could have no more than 31
+ file server machines. With the AFS 3.2 version of the VLDB,
+ a cell can have as many as 255 file server machines.
+
+ The vldb_convert command converts an existing AFS 3.1 VLDB
+ for use as an AFS 3.2 VLDB. It reads the
+ /usr/afs/db/vldb.DB0 database file for the old VLDB and
+ writes a new, converted version of the database into a
+ temporary file in the /usr/afs/db directory. If successful,
+ it then removes the old vldb.DB0 file from the directory and
+ replaces it with the new version from the temporary file.
+ After the conversion, the database functions as it did
+ before, with the exception that it can accommodate the
+ entries for the additional file server machines. The binary
+ file for the vldb_convert command resides in /usr/afsws/etc.
+
+ The command requires the file system in which the VLDB
+ resides to have free space at least equivalent to the size
+ of the old VLDB plus 9 kilobytes. Because the command
+ removes the old VLDB and replaces it with the new version of
+ the database, the additional space is required only while
+ the command executes. (The new version of the database
+ requires a small amount of additional space, but the
+ difference is inconsequential.)
+
+ Begin the conversion of the VLDB by shutting down the Volume
+ Location (VL) Servers on all three database server machines.
+ (The instructions assume the cell has three database server
+ machines; adjust the steps accordingly if it has fewer.)
+ This causes a service outage in the cell, but the outage for
+ the entire conversion procedure should last no more than 15
+ to 20 minutes.
+
+ Replace the AFS 3.1 version of the /usr/afs/bin/vlserver
+ file on all three database server machines with the AFS 3.2
+ version of the file. The new VL Server understands the
+ format of the new version of the VLDB. The old version of
+
+
+
+ the VL Server cannot be run with the new version of the
+ VLDB, and vice versa. Make sure you replace the vlserver
+ binary files on each binary distribution machine; otherwise,
+ the Update Servers overwrite the version stored on the
+ database server machines by automatically propagating the
+ old version of the binary file to the machines.
+
+ Determine which database server machine has the lowest IP
+ address; Ubik will use this machine as the synchronization
+ site when the VL Servers are restarted. Remove the VLDB
+ from the other two database server machines by deleting the
+ /usr/afs/db/vldb.DB0 database and /usr/afs/db/vldb.DBSYS1
+ log files from the other machines. Remove only the
+ /usr/afs/db/vldb.DBSYS1 log file from the database server
+ machine with the lowest IP address. Do not remove the
+ /usr/afs/db/vldb.DB0 database file from the machine with the
+ lowest IP address.
+
+ Copy the /usr/afs/db/vldb.DB0 file on the database server
+ machine with the lowest IP address to a different directory.
+ Then execute the vldb_convert command on that machine. The
+ command takes no more than a few minutes to complete.
+ However, it displays no messages while it executes.
+
+ When the command is finished, restart the VL Server on the
+ machine with the lowest IP address. Then restart the VL
+ Servers on the remaining two database server machines. Ubik
+ elects the database server machine with the lowest IP
+ address as the synchronization site and distributes the copy
+ of the new VLDB from that machine to the other two database
+ server machines. The VLDB is then available.
+
+ The vldb_convert command can be also used to convert the
+ VLDB from AFS 3.2 format back to AFS 3.1 format. The
+ command's -to and -from switches are used to specify the
+ direction of the conversion. The -to switch specifies the
+ version to which the database is to be converted; the -from
+ switch indicates the version from which the database is to
+ be converted.
+
+ Both switches accept a 1, to indicate 3.1, or a 2, to
+ indicate 3.2. When converting from 3.1 to 3.2, specify -to
+ as 2 and -from as 1. Should the need to revert to 3.1
+ arise, specify -to as 1 and -from as 2. When converting
+ from 3.1 to 3.2, you can omit both options; the command
+ automatically converts the database to the next higher
+ version.
+
+ Finally, the command can be used to display the version of
+ the current VLDB. The -showversion flag directs the command
+ to display the version number (3.1 or 3.2) of the VLDB at
+ the time the command is issued. Do not specify the -to or
+ -from switch if the -showversion flag is used.
+
+
+
+NOTE
+
+ The vldb_convert command is also useful as a means of
+ removing from the VLDB entries for server machines that
+ house no volumes. When a file server machine name or its IP
+ address is changed, the VLDB still contains an entry for the
+ previous name or address. This becomes a problem only when
+ the administrators in a large cell must change the names or
+ IP addresses of a significant number of machines, in which
+ case it is conceivable (though highly unlikely) that all 255
+ possible file server machine entries will be taken.
+
+ If this problem occurs in a cell, the administrators can
+ execute vldb_convert with a value of 2 for both its -to and
+ -from switches. The command removes the entries for all
+ unreferenced servers from the VLDB. The steps described
+ previously for executing the command (shutting down the
+ servers, removing the copies of the VLDB) must be executed
+ as they are for initially upgrading the database.
+
+WARNING
+
+ Copy the /usr/afs/db/vldb.DB0 file to a different directory
+ after the VL Servers are shut down but before the
+ vldb_convert command is run. The command should perform the
+ conversion without problems. Also, it does not remove the
+ old database file until it has successfully completed the
+ conversion. However, if anything happens to disrupt the
+ conversion or if the operation fails for any reason, copying
+ the database beforehand allows the VLDB to be restored from
+ the copy.
+
+ Leave no VL Servers running while the conversion is in
+ progress. If a number of VL Servers sufficient for Ubik to
+ attain a quorum are available while the conversion is in
+ progress, changes made while the conversion is underway are
+ lost when the new version of the VLDB is distributed.
+
+ Ensure that all VL Servers are referencing the same version
+ of the VLDB at all times. The 3.1 version of the VL Server
+ can reference only the 3.1 version of the VLDB, and the 3.2
+ version of the VL Server can use only the 3.2 version of the
+ VLDB. The 3.1 version of the VL Server is not compatible
+ with the 3.2 version of the VLDB, and vice versa. For this
+ reason, the vldb_convert command must be used to convert the
+ existing VLDB to the new format before the new version of
+ the VL Server distributed from the cell's binary
+ distribution machines via the Update Server can be used.
+
+ Specify only valid, correct values for the -to and -from
+ switches. Specifying invalid or incorrect values for these
+ switches can result in damage to the VLDB. This is another
+ reason to copy the vldb.DB0 database file to a different
+ directory before using the vldb_convert command.
+
+ Finally, the entire procedure takes no more than a few
+ minutes to complete. However, because volumes are
+ inaccessible while the procedure is underway, it is best to
+ perform the operation over a weekend or overnight to disrupt
+ the fewest users.
+
+
+
+ARGUMENTS
+
+ initcmd is an optional string that accommodates the
+ command's use of the AFS command parser. It
+ can be omitted and ignored.
+
+ -to indicates the version of the VLDB to which
+ the current version of the database is to be
+ converted. Valid values are 1, indicating
+ that the existing version of the database is
+ to be converted to AFS 3.1 format, or 2,
+ indicating that the existing version of the
+ database is to be converted to AFS 3.2
+ format. See the DESCRIPTION section for
+ information about the possible combinations
+ of the -to and -from switches and the
+ effects of omitting the switches.
+
+ -from indicates the version of the current VLDB.
+ Valid values are 1, indicating that the
+ existing version of the database is in AFS
+ 3.1 format, or 2, indicating that the
+ existing version of the database is in AFS
+ 3.2 format. See the DESCRIPTION section for
+ information about the possible combinations
+ of the -to and -from switches and the
+ effects of omitting the switches.
+
+ -path provides the complete pathname of the
+ vldb.DB0 database file if the file is kept
+ in an alternate directory (or has a
+ different name). Always include the name of
+ the file, even if it is vldb.DB0. By
+ default, the command converts the vldb.DB0
+ database file in the /usr/afs/db directory.
+ Use this switch only if the database is
+ stored in a different directory (or has a
+ different name).
+
+ -showversion displays the version (3.1 or 3.2) of the
+ current VLDB. Include the -path switch if
+ the VLDB is stored in a directory other than
+ /usr/afs/db. If you use this flag, the -to
+ and -from switches are ignored.
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one.
+
+EXAMPLE
+
+ The following, issued on the database server machine with
+ the lowest IP address, executes the vldb_convert command to
+ convert the VLDB from AFS 3.1 format to AFS 3.2 format:
+
+ % vldb_convert
+
+PRIVILEGE REQUIRED
+
+ The issuer must be able to read, delete, and write to the
+ /usr/afs/db/vldb.DB0 and /usr/afs/db/vldb.DBSYS1 files on
+
+
+
+ all database server machines. The issuer must also be able
+ to insert, write to, and delete files in the /usr/afs/db
+ directories on the machines.
+
+ In addition, to install the new version of the VL Server,
+ the issuer must be able to delete the /usr/afs/bin/vlserver
+ file on all database server machines (or on all binary
+ distribution machines). The issuer must also be able to
+ insert files in the /usr/afs/bin directories on the
+ machines.
+
+ An issuer who is logged into the UNIX file systems of the
+ database server machines as "root" has the necessary rights
+ to perform the entire conversion procedure.
--- /dev/null
+ AFS Commands
+
+ 1. The vos Commands
+
+ ------------------------------------------------------------
+
+ This command defines the vos commands that system
+ administrators use to contact the Volume Server and Volume
+ Location (VL) Server. It assumes the reader is familiar
+ with the concepts described in AFS System Administrator's
+ Guide.
+
+ System administrators use vos commands to instruct the
+ Volume Server to create, move, delete, replicate and backup
+ volumes. The Volume Location (VL) Server automatically
+ records in the Volume Location Database (VLDB) any changes
+ in volume status and location that result from vos commands.
+ Operators can use other vos commands to obtain information
+ from VLDB records. Vos commands also help operators dump
+ copies of volumes to disk and restore them to the file
+ system if necessary.
+
+ Note that vos commands are "idempotent." This means that if
+ execution of a certain command is interrupted in the middle
+ by a server or process failure, then a subsequent execution
+ of the same command picks up at the interruption point,
+ rather than at the very beginning of the operation. (This
+ does not apply if the issuer explicitly interrupts the
+ operation with ^C or another interrupt signal. In that
+ case, the volume is left locked and the issuer must unlock
+ it with vos unlock before proceeding.) Idempotency implies
+ that before executing a command, the Volume and VL Servers
+ check to see if running it will have any effect (i.e.,
+ whether the state that will result from running the command
+ already holds). If the desired end-state already holds,
+ there is no need to run the command again, no matter how
+ many times it is subsequently issued. If the end-state does
+ not yet hold, the command should pick up where necessary to
+ achieve it.
+
+ Refer to the Command Summary at the end of this document for
+ a complete list of vos commands and their syntax.
+
+ 1.1 The Information in VLDB Entries
+ The Volume Location Database (VLDB), maintained by the
+ Volume Location (VL) Server, records a large range of
+ information about all the volumes in a cell. A separate
+ copy of the VLDB resides on each database server machine. To
+ keep the copies synchronized, the VL Server uses the AFS's
+ library of database management facilities, called Ubik.
+
+ It is important that the information in the VLDB correspond
+ to the status of the actual volumes on the servers as much
+ of the time as possible. For this reason, any vos command
+ that affects volume status also changes the corresponding
+ VLDB entry automatically, as noted in the command
+ descriptions below. (It is possible for the VLDB and
+ servers to disagree if vos operations are interrupted before
+ completion; see the vos syncserv and vos syncvldb commands.)
+
+ There is an entry in the VLDB for each ReadWrite volume.
+ The entry also records information about the ReadOnly and
+ Backup version of the volume; ReadOnly and Backup volumes do
+ AFS Command Reference Manual The vos Commands 2
+
+
+ not have their own VLDB entries. (The one exception to this
+ rule is that a ReadOnly volume may have its own VLDB entry
+ if its ReadWrite source has been removed.)
+
+ The following information is available from a VLDB entry:
+
+ - the name of the ReadWrite version of the volume.
+ The ReadOnly version automatically has the same
+ name with a .readonly extension, the Backup
+ version with a .backup extension
+
+ - the ReadWrite volumeID number. A volumeID number
+ is simply an identification number guaranteed to
+ be unique within a cell. In almost all cases, the
+ VL Server allocates volumeID numbers
+ automatically, but some commands allow the issuer
+ to assign volumeIDs explicitly. Each of the three
+ versions of a volume has a different volumeID
+ number; they often run consecutively, especially
+ if the VL Server assigned them, but this is not a
+ requirement.
+
+ - the ReadOnly volumeID number. All copies of the
+ ReadOnly version share the same ID.
+
+ - the Backup volumeID number
+
+ - the ReleaseClone volumeID number, if a
+ ReleaseClone exists. See the description of
+ vos release for more about the ReleaseClone.
+
+ - one or more site definitions, each of which
+ specifies a file server machine name and partition
+ name. Site definitions specify the location of
+ the ReadWrite version and each copy of the
+ ReadOnly version (if any). No site definition is
+ necessary for the Backup version, if any, because
+ it always resides at the same site as its
+ ReadWrite source. There can be one ReadWrite
+ definition and up to six ReadOnly definitions.
+
+ - one or more site flags associated with each site
+
+ One site flag tells what type of volume resides at
+ the site, and has value RW for ReadWrite or RO for
+ ReadOnly.
+
+ The other possible site flag marks the copy at
+ that site as NEW or OLD. Normally, this type of
+ flag will not appear; its presence indicates that
+ an error occurred as new ReadOnly clones were
+ being distributed to their sites. See the
+ description of the vos release command for further
+ explanation.
+
+ - one status flag for each of the three versions--
+ ReadWrite, ReadOnly and Backup. This flag
+ indicates whether the version actually exists at
+ at least one site: valid indicates that it does,
+ invalid that it does not. Note that there is not
+ a separate status flag for each site.
+ AFS Command Reference Manual The vos Commands 3
+
+
+ - a site count, which tells how many copies exist of
+ the ReadWrite and ReadOnly versions of the volume.
+ There is only one ReadWrite copy, but as many as
+ six ReadOnly copies may exist.
+
+ - an indication if the VLDB entry is locked. Since
+ being unlocked is the default state, there is no
+ explicit indicator if the VLDB entry is unlocked.
+ See the descriptions of the vos lock and
+ vos unlock commands.
+
+ The vos listvldb command displays much of the information
+ from the VLDB described above. The vos examine command also
+ displays VLDB information, in combination with volume header
+ information.
+
+ 1.2 The Information in Volume Headers
+ The previous section explained that there is a single VLDB
+ entry for each ReadWrite volume and all of its (ReadOnly and
+ Backup) clones. In contrast, there is a separate volume
+ header at the site of each copy of the volume, no matter its
+ version. The volume header is the volume in a senseMit is a
+ data structure that records which physical memory addresses
+ on the partition are storing the files in the volume. The
+ volume header binds all the files into a logical unit
+ without requiring that they be stored in contiguous memory
+ blocks.
+
+ In addition to data location, the volume header records
+ other information about the volume, some of it redundant
+ with the VLDB so that the Volume Server can access the
+ information even when the VLDB is unavailable.
+
+ The information in the volume header includes:
+
+ - the name of this copy of the volume, with
+ .readonly or .backup extension if appropriate
+
+ - its volumeID number
+
+ - its type (RW for ReadWrite, RO for ReadOnly, BK
+ for Backup)
+
+ - its size in kilobytes (so 1024 means a megabyte)
+
+ - its status at the site, which is unrelated to the
+ locked/unlocked status of the VLDB entry. There
+ are three possibilities:
+
+ * On-line means that the volume is fully
+ accessible through the file system
+
+ * needs salvage means that the volume is
+ probably corrupted. Run the Salvager using
+ the bos salvage command.
+
+ * Off-line means that the volume is not
+ accessible, but there is no reason to suspect
+ that it is corrupted
+
+ - a Parent ID number, which is the volumeID of this
+ AFS Command Reference Manual The vos Commands 4
+
+
+ volume's ReadWrite source. If this volume is the
+ ReadWrite version itself, this ID should match the
+ previously mentioned volumeID.
+
+ - a Clone ID number, which is the volumeID number of
+ the last clone made from this volume's ReadWrite
+ source for the purposes of replication. It may
+ match the ReadOnly volumeID or ReleaseClone ID,
+ dependingon whether or not the release was
+ successful.
+
+ - a Backup ID number, which is the volumeID of the
+ Backup version of this volume. If this volume is
+ the Backup version itself, this ID should match
+ the previously mentioned volumeID.
+
+ - a quota, which is the maximum amount of disk space
+ the ReadWrite version of the volume may occupy.
+ It does not apply sensibly to ReadOnly or Backup
+ volumes, but is reported for convenience anyway.
+
+ - its creation date, which is the day and time when
+ this copy of the volume was created (for ReadOnly
+ and Backup copies, this means cloned/released).
+ If the volume has been restored with
+ backup diskrestore, backup volrestore or vos
+ restore, this is the restore time.
+
+ - its date of last update, which is the day and time
+ when the contents of this volume last changed.
+ For ReadOnly and Backup volumes, this should match
+ the creation date, since they are not allowed to
+ change.
+ AFS Command Reference Manual The vos Commands 5
+
+
+ - the number of times the volume has been accessed
+ since the later of
+
+ * 12:00 a.m. on the day the command is issued
+
+ * the last time the volume changed location
+
+ An access is defined as a fetch or store operation
+ on any file system object stored in the volume.
+
+ The vos listvol command displays information from the volume
+ header (as does the vos examine command, in combination with
+ VLDB information).
+
+ 1.3 Common Arguments and Flags
+ Most vos commands accept the following optional arguments
+ and flags. They are listed in the command descriptions
+ where they apply, and are described in detail below:
+
+ [-cell <cell name>]
+
+ This argument specifies that the command should be run in a
+ different cell, specified by cell name. By default,
+ commands are executed in the local cell, as defined in
+ /usr/vice/etc/ThisCell on the client machine on which the
+ command is issued. The issuer may abbreviate cell name to
+ the shortest form that distinguishes it from the other cells
+ listed in /usr/vice/etc/CellServDB on the client machine on
+ which the command is issued.
+
+ [-noauth]
+
+ This flag instructs the Volume and/or Volume Location Server
+ not to authenticate the user of the command, and thus
+ establishes an unauthenticated connection between the user
+ and the server (the user is recognized as the unprivileged
+ user anonymous). It is useful only when authorization
+ checking is disabled on the file server machine (during the
+ installation of a file server machine or when bos setauth
+ has been used during other unusual circumstances). In
+ normal circumstances, the Volume and VL Servers allow only
+ authorized (privileged) users to issue commands that change
+ the status of a volume or VLDB entry, and will refuse to
+ perform such an action even if the -noauth flag is used.
+
+ [-localauth]
+
+ This flag instructs the vos command interpreter running on
+ the local machine to construct a server ticket using the
+ server encryption key with the highest key version number in
+ /usr/afs/etc/KeyFile on the local machine. The command
+ interpreter presents the ticket to the Volume and/or Volume
+ Location Server to use in mutual authentication.
+
+ This argument is only useful for commands issued on file
+ server machines, since client workstations do not have a
+ KeyFile. It is intended for cron-type processes or jobs
+ included in the machine's /usr/afs/local/BosConfig file. An
+ example might be a command that automatically runs the
+ vos backup command on certain volumes in preparation for
+ archival backups. See the chapter in the AFS System
+ AFS Command Reference Manual The vos Commands 6
+
+
+ Administrator's Guide about backing up the system. The flag
+ can also be used if the user is unable to authenticate but
+ is logged into the local UNIX file system as "root".
+
+ [-verbose]
+
+ This flag tells the Volume Server and/or VL Server to
+ display messages about the operations they are performing
+ while executing the command. Useful mainly for debugging
+ and tracing purposes.
+
+ [-help]
+
+ This flag has the same function as the vos help command: it
+ prints the command's online help message on the screen. No
+ other arguments or flags should be provided at the same
+ time. Even if they are, this flag overrides them, and the
+ only effect of issuing the command is that the help message
+ appears.
+
+ 1.4 The Privilege Required for vos Commands
+ The Volume and Volume Location Servers consider privileged
+ those users listed in the file /usr/afs/etc/UserList on a
+ file server machines' local disk. This list is maintained
+ on each file server machine's local disk using bos commands.
+
+ Most vos commands require privilege; only those that list
+ volume-related information do not.
--- /dev/null
+vos addsite AFS Commands vos addsite
+
+
+NAME
+
+ vos addsite -- add definition of ReadOnly site to VLDB
+
+ entry.
+
+
+ vos addsite -server <machine name for new site>
+ -partition <partition name for new site>
+ -id <volume name or ID> [-cell <cell name>] [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos ad -s <machine name for new site> -p <partition name
+ for new site>
+ -i <volume name or ID> [-c <cell name>] [-n] [-l] [-v]
+ [-h]
+
+DESCRIPTION
+
+ Defines future sites that will receive copies of the
+ ReadOnly version of a volume, in preparation for actually
+ creating and distributing the ReadOnly version using
+ vos release. A site is defined as a certain file server
+ machine and partition.
+
+ The VLDB status flag for the ReadOnly version of the volume
+ remains invalid, since an actual copy of the ReadOnly volume
+ does not yet exist at the site.
+
+ If defining more than one replication site for a given
+ ReadWrite source, issue this command repeatedly.
+
+WARNING
+
+ Do not define more than six ReadOnly sites with this
+ command. Each VLDB entry can store up to seven site entries
+ (the ReadWrite site counts as one).
+
+ No more that 3500 volumes should reside on one partition. A
+ greater number can cause the AFS Salvager process to
+ malfunction. It is the issuer's responsibility to check
+ that releasing a ReadOnly volume to a site defined with this
+ command will not cause the limit to be exceeded. The
+ vos listvol command reports the number of volumes on a
+ partition.
+
+ARGUMENTS
+
+ -server names the file server machine where the copy
+ is to reside. Abbreviated forms of machine
+ names may be allowed depending on the naming
+ service available at the time the command is
+ issued; see page xii in the introductory
+ About This Manual chapter. -partition
+ names the particular partition on that file
+ server machine where the copy is to reside.
+ In addition to the full /vicepx form of a
+ partition name, three shorter forms are
+ acceptable; see page xii in the introductory
+
+
+
+ About This Manual chapter. -id
+ specifies either the complete name or
+ volumeID number of the ReadWrite source
+ volume.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following, appropriate in the Transarc Corporation cell,
+ defines a ReadOnly site for the cell's root.afs volume.
+
+ % vos ad fs7.transarc.com /vicepb root.afs
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos listvol
+
+ vos release
--- /dev/null
+vos apropos AFS Commands vos apropos
+
+
+NAME
+
+ vos apropos -- show each help entry containing keyword.
+
+
+ vos apropos -topic <help string> [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos ap -t <help string> [-h]
+
+DESCRIPTION
+
+ Displays the first line of the help entry for any vos
+ command that has help string in its name or short
+ description.
+
+ARGUMENTS
+
+ -topic specifies the keyword string to search for.
+ If it is more than a single word, surround
+ it with double quotes or other delimiters.
+ Type all help strings for vos commands in
+ all lowercase letters, except the word
+ "VLDB."
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The first line of a command's online help entry names the
+ command and briefly describes what it does. The vos apropos
+ command displays that first line for any vos command where
+ help string is part of the command name or first line.
+
+ To see the remaining lines in a help entry, which provide
+ the command's alias (if any) and syntax, use the vos help
+ command.
+
+EXAMPLE
+
+ The following lists all vos commands that have the word
+ "lock" in their operation code or short online description.
+
+ % vos ap lock
+ lock: lock VLDB entry for a volume
+ unlock: release lock on VLDB entry for a volume
+ unlockvldb: unlock all the locked entries in the VLD
+
+
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos help
--- /dev/null
+vos backup AFS Commands vos backup
+
+
+NAME
+
+ vos backup -- create Backup volume version of one ReadWrite
+
+ volume.
+
+
+ vos backup -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos backup -i <volume name or ID> [-c <cell name>] [-n]
+ [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Clones the indicated ReadWrite volume to create a Backup
+ version. Names the Backup version by adding a .backup
+ extension to the ReadWrite source's name. It places the
+ Backup version at the same site as the ReadWrite, and
+ changes the VLDB status flag for the Backup to valid.
+
+ If a Backup version already exists, this new clone replaces
+ it. The status flag remains valid.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of the ReadWrite source
+ volume.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following creates a Backup version of the volume
+ user.smith.
+
+ % vos backup user.smith
+
+PRIVILEGE REQUIRED
+
+
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos backupsys
--- /dev/null
+vos backupsys AFS Commands vos backupsys
+
+
+NAME
+
+ vos backupsys -- create Backup volume version of all
+
+ indicated ReadWrite volumes.
+
+
+ vos backupsys [-prefix <common prefix on volume(s)>]
+ [-server <machine name>] [-partition <partition name>]
+ [-cell <cell name>] [-noauth] [-localauth] [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos backups [-pr <common prefix on volume(s)>] [-s
+ <machine name>]
+ [-pa <partition name>] [-c <cell name>] [-n] [-l] [-v]
+ [-h]
+
+DESCRIPTION
+
+ Clones each indicated ReadWrite volume to make a Backup
+ version of it. Names each Backup version by adding a
+ .backup extension to the name of its ReadWrite source. It
+ places each Backup at the same site as its source, and
+ changes the VLDB status flag for each Backup to valid.
+
+ If a Backup version already exists for a volume, the new
+ clone replaces it. The status flag remains valid.
+
+ By combining the -prefix, -server and -partition arguments
+ in different ways, it is possible to create Backup copies of
+ varying numbers of volumes. The possibilities are listed
+ here from most to least inclusive
+
+ To create a Backup version of:
+
+ - every ReadWrite volume in the system, omit all
+ three arguments. This could take a rather long
+ time to execute, depending on the number of
+ volumes.
+
+ - every ReadWrite volume whose name begins with a
+ certain character string (for example, sys. or
+ user.), regardless of site, use -prefix.
+
+ - every ReadWrite volume on a file server machine,
+ specify the file server name with -server.
+
+ - every ReadWrite volume that resides on a partition
+ of the same name (for instance, on /vicepa on any
+ file server machine), specify the partition name
+ with -partition.
+
+ - every ReadWrite volume on a certain partition of a
+ file server machine, specify both -server and
+ -partition.
+
+
+
+ - every ReadWrite volume with a certain prefix that
+ resides on a file server machine, combine -prefix
+ and -server. The -prefix argument may also be
+ combined with -partition, or both -server and
+ -partition, in this way.
+
+ - a single ReadWrite volume, give its complete name
+ as -prefix. This is actually better done with the
+ vos backup command, which employs a more
+ streamlined technique for finding a single volume.
+
+ARGUMENTS
+
+ -prefix specifies a character string of any length.
+ Every volume whose name begins with this
+ exact string will be cloned (subject to
+ modulations from -server and -partition).
+ Include field separators (such as periods)
+ if appropriate. This argument may be
+ combined with -server and/or -partition.
+
+ -server names the file server machine where the
+ ReadWrite source volume(s) reside.
+ Abbreviated forms of machine names may be
+ allowed depending on the naming service
+ available at the time the command is issued;
+ see page xii in the introductory About This
+ Manual chapter. This argument may be
+ combined with -prefix and/or -partition.
+
+ -partition names the particular partition where the
+ ReadWrite source volume(s) reside. In
+ addition to the full /vicepx form of a
+ partition name, three shorter forms are
+ acceptable; see page xii in the introductory
+ About This Manual chapter. This argument
+ may be combined with -prefix and/or -server.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+
+
+EXAMPLES
+
+ The following creates a Backup version of every volume in
+ the cell's file system whose name begins with "user".
+
+ % vos backups user
+
+ The following, appropriate in the Transarc Corporation cell,
+ creates a Backup version of every volume on the file server
+ machine fs3.transarc.com.
+
+ % vos backups -s fs3.transarc.com
+
+ The following, appropriate in the Transarc Corporation cell,
+ creates a Backup version of every volume on the /vicepc
+ partition of the file server machine fs5.transarc.com.
+
+ % vos backups -s fs5.transarc.com -p c
+
+ The following, appropriate in the Transarc Corporation cell,
+ creates a Backup version of every volume on the file server
+ machine db1.transarc.com whose name begins with "sys".
+
+ % vos backups sys db1.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos backup
--- /dev/null
+vos create AFS Commands vos create
+
+
+NAME
+
+ vos create -- create (empty) ReadWrite volume and
+
+ associated VLDB entry.
+
+
+ vos create -server <machine name> -partition <partition
+ name> -name <volume name> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos c -s <machine name> -p <partition name> -na <volume
+ name>
+ [-c <cell name>] [-no] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Creates a ReadWrite volume, names it volume name and places
+ it at the site specified by machine name and partition name.
+ The volume automatically receives a volumeID number,
+ recorded in both the VLDB and the volume header. The VLDB
+ status flag for the ReadWrite site is set to valid.
+
+ If this command succeeds, then the volume is available for
+ use, though it must be mounted in the file system before its
+ contents are accessible. Use the fs mkmount command to
+ mount a volume.
+
+ This command creates a default ACL associated with the
+ volume's "root directory" (which takes the same name as
+ volume's mount point when the volume is mounted with
+ fs mkmount). The ACL grants all seven access rights to
+ system:administrators. The volume's space quota is set to
+ 5000 kilobyte blocks by default.
+
+ The Volume Location Server also pre-allocates, and records
+ in the VLDB, volumeID numbers for the ReadOnly and Backup
+ versions that may be created later. It does not actually
+ create those types of volumes or place anything at a
+ ReadOnly or Backup site, so the status flags for ReadOnly
+ and Backup are set to invalid.
+
+WARNING
+
+ No more that 3500 volumes should reside on one partition. A
+ greater number can cause the AFS Salvager process to
+ malfunction. It is the issuer's responsibility to check
+ that issuing this command will not cause the limit to be
+ exceeded. The vos listvol command reports the number of
+ volumes on a partition.
+
+
+
+ARGUMENTS
+
+ -server names the file server machine on which to
+ create the new ReadWrite volume.
+ Abbreviated forms of machine names may be
+ allowed depending on the naming service
+ available at the time the command is issued;
+ see page xii in the introductory About This
+ Manual chapter. -partition
+ names the particular partition where the
+ ReadWrite volume is to reside. In addition
+ to the full /vicepx form of a partition
+ name, three shorter forms are acceptable;
+ see page xii in the introductory About This
+ Manual chapter. -name
+ specifies a name for the ReadWrite volume,
+ preferably descriptive of its contents. It
+ may be no longer than 22 characters, but may
+ contain upper- and lowercase letters,
+ numbers and punctuation. By convention,
+ periods separate the fields in a name. Do
+ not use the extension .backup or .readonly
+ on ReadWrite volume names; the Volume Server
+ automatically adds these extensions when
+ creating those volume types.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following creates the ReadWrite volume user.pat on the
+ /vicepf partition of fs4.transarc.com.
+
+ % vos c fs4.transarc.com /vicepf user.pat
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
--- /dev/null
+vos delentry AFS Commands vos delentry
+
+
+NAME
+
+ vos delentry -- remove specified entry from VLDB.
+
+
+ vos delentry -id <volume name or ID>
+ [-prefix <prefix of volume whose VLDB entry is to be
+ deleted>]
+ [-server <machine name>] [-partition <partition name>]
+ [-cell <cell name>] [-noauth] [-localauth] [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos de -i <volume name or ID>
+ [-pr <prefix of volume whose VLDB entry is to be deleted>]
+ [-s <machine name>] [-pa <partition name>] [-c <cell
+ name>]
+ [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Removes the VLDB entry for the indicated volume(s) from the
+ VLDB. Each volume may be any of the three types (ReadWrite,
+ ReadOnly or Backup), but the entire entry is removed no
+ matter which type is provided. The command has no effect on
+ the actual volumes on file server machines, if they exist.
+
+ This command is useful if the system administrator is
+ certain that a volume removal was not recorded in the VLDB
+ (perhaps the vos zap command was used), and does not want to
+ take the time to use vos syncserv and vos syncvldb to
+ synchronize an entire file server machine.
+
+ By using the -id argument alone, or combining the -prefix,
+ -server and -partition arguments in different ways, it is
+ possible to remove the VLDB entry for varying numbers of
+ volumes. To remove the VLDB entry for:
+
+ - a single volume, provide its complete name or
+ volumeID number as -id.
+
+ - every volume whose name begins with a certain
+ character string (for example, sys. or user.),
+ regardless of site, use -prefix.
+
+ - every volume listed as residing on a certain file
+ server machine, specify the file server name with
+ -server.
+
+ - every volume listed as residing on a partition of
+ the same name (for instance, on /vicepa on any
+ file server machine), specify the partition name
+ with -partition.
+
+ - every volume on a certain partition of a file
+ server machine, specify both -server and
+ -partition.
+
+ - every volume with a certain prefix that resides on
+ a file server machine, combine -prefix and
+
+
+
+ -server. The -prefix argument may also be
+ combined with -partition, or both -server and
+ -partition, in this way.
+
+WARNING
+
+ This command should not be used as the standard way to
+ remove a volume, as it is likely to put the VLDB out of sync
+ with the volumes on servers. Use vos remove instead.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of the volume, which may be
+ ReadWrite, ReadOnly or Backup. The entire
+ entry is removed, no matter which type is
+ provided. Provide this argument OR some
+ combination of -prefix, -server and
+ -partition.
+
+ -prefix specifies a character string of any length.
+ Every VLDB listing a volume whose name
+ begins with this exact string will be
+ removed (subject to modulations from -server
+ and -partition). Include field separators
+ (such as periods) if appropriate. This
+ argument may be combined with -server and/or
+ -partition.
+
+ -server names a file server machine. If the VLDB
+ entry mentions this file server machine as
+ the site for a volume, the entry will be
+ removed. Abbreviated forms of machine names
+ may be allowed depending on the naming
+ service available at the time the command is
+ issued; see page xii in the introductory
+ About This Manual chapter. This argument
+ may be combined with -prefix and/or
+ -partition.
+
+ -partition names a partition. If the VLDB entry
+ mentions this partition as the site for a
+ volume, the entry will be removed. In
+ addition to the full /vicepx form of a
+ partition name, three shorter forms are
+ acceptable; see page xii in the introductory
+ About This Manual chapter. This argument
+ may be combined with -prefix and/or -server.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+
+
+
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLES
+
+ The following removes the VLDB entry for the volume
+ user.temp.
+
+ % vos del user.temp
+
+ The following removes all VLDB entries that describe volumes
+ stored on fs3.transarc.com whose names begin with the string
+ "test".
+
+ % vos del -pr test -s fs3.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos remove vos remsite vos syncserv vos syncvldb vos zap
--- /dev/null
+vos dump AFS Commands vos dump
+
+
+NAME
+
+ vos dump -- convert volume into ASCII format and place in a
+
+ file.
+
+
+ vos dump -id <volume name or ID> -time <dump from time>
+ [-file <dump file>] [-cell <cell name>] [-noauth]
+ [-localauth]
+ [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos du -i <volume name or ID> -t <dump from time> [-f
+ <dump file>]
+ [-c <cell name>] [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Converts the contents of the indicated volume, which may be
+ of any type, into ASCII format. If the -file argument is
+ provided, the converted volume contents are placed in it.
+ If the argument is not provided, the contents are directed
+ to standard output (stdout), from which the issuer may pipe
+ them elsewhere if desired.
+
+ It is possible to dump either the entire volume, or only
+ those files in it modified since a specified time (the
+ latter is referred to as a "incremental" dump), by
+ specifying the proper value for -time.
+
+ Dumping does not affect any status or site flags in the
+ volume header or VLDB. It does, however, make the volume
+ inaccessible during the duration of the dump.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of the volume, which may be
+ ReadWrite, ReadOnly or Backup.
+
+ -time determines whether the dump is full or
+ incremental, and in the latter case, from
+ what date the dump is done. There are three
+ types of legal values:
+
+ - 0 creates a full dump.
+
+ - mm/dd/yy specifies 12:00 a.m. on the
+ indicated date (month/day/year) and
+ creates an incremental dump including
+ only elements with modification time
+ stamps later than this date. Examples
+ : 1/23/90, 10/7/89.
+
+ - "mm/dd/yy hh:mm" specifies a time
+ "hour:minutes" on the indicated date
+ (month/day/year) and creates an
+ incremental dump including only
+ elements with modification time stamps
+
+
+
+ later than this time. The time should
+ be in 24-hour format (for example,
+ 20:30 is 8:30 p.m.) Surround the
+ entire instance with quotes because it
+ contains a space. Examples : "1/23/90
+ 22:30", "10/7/89 3:45".
+
+ -file directs the dump into the indicated file,
+ which is created in the current working
+ directory if no full or relative pathname is
+ provided. If the issuer does not provide
+ this argument, the dump is directed to
+ standard output (stdout).
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to trace their execution of the command.
+ See section 8.3 in the Reference Manual for
+ more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLES
+
+ The following executes a full dump of the volume user.terry
+ into the file /afs/transarc.com/common/dumps/terry.dump in
+ the current working directory.
+
+ % vos dump user.terry 0 terry.dump
+
+ The following executes an incremental dump of the volume
+ user.smith into the file smith.900131.dump in the current
+ working directory. Only those files in the volume with
+ modification time stamps later than 6:00 p.m. on 31 February
+ 1990 are included in the dump.
+
+ % vos dump user.smith "1/31/90 18:00" smith.090131.dump
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server,
+ and must have WRITE access in the directory where the dump
+ file is to reside.
+
+MORE INFORMATION
+
+ vos restore
--- /dev/null
+vos examine AFS Commands vos examine
+
+
+NAME
+
+ vos examine -- show information from volume header and VLDB
+
+ about one volume.
+
+
+ vos examine -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos e -i <volume name or ID> [-c <cell name>] [-n] [-l]
+ [-v] [-h]
+
+ vos volinfo -i <volume name or ID> [-c <cell name>] [-n]
+ [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Formats and displays information from both the VLDB entry
+ and the volume header for the indicated volume, which may be
+ of any of the three types.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of the volume, which may be
+ ReadWrite, ReadOnly or Backup.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The first seven lines of the output show information from
+ the volume header, and the remaining lines come from the
+ VLDB. Sections 8.1 in the Reference Manual and VOSHEADER
+ provide more complete explanations of these fields than
+ appear here.
+
+ The first line of the output shows information from the
+ volume header, in this order:
+
+
+
+ - the volume's name.
+
+ - its volumeID.
+
+ - its type (RW for ReadWrite, RO for ReadOnly, BK
+ for Backup).
+
+ - its size in kilobytes (so 1000 means a megabyte).
+
+ - its status at the server. The possible values are
+ On-line, Off-line and needs salvage, the meanings
+ of which section 8.2 in the Reference Manual
+ explains in full. In short, On-line indicates
+ that the volume is accessible, whereas the other
+ two indicate a possible problem with the volume.
+
+ The second line shows the volume's site (file server machine
+ and partition).
+
+ The third line shows the Parent (ReadWrite), Clone
+ (ReleaseClone or Backup) and Backup volume IDs associated
+ with this volume. One should match the volumeID number that
+ appears on the first line.
+
+ The fourth line shows the quota allotted to the ReadWrite
+ copy of the volume, expressed in kilobyte blocks.
+
+ The fifth line shows the creation date of this volume. If
+ the volume has been restored with backup diskrestore,
+ backup volrestore or vos restore, this is the restore time.
+
+ The sixth line shows the update date when the contents of
+ this volume last changed. For ReadOnly and Backup volumes,
+ this should match the creation date.
+
+ The seventh line reports how many times the volume has been
+ accessed since the later of
+
+ - 12:00 a.m. on the day the command is issued
+
+ - the last time the volume changed location
+
+ An access is defined as a fetch or store operation on any
+ file system object stored in the volume.
+
+ Following a blank line, information from the VLDB entry
+ appears:
+
+ If the VLDB entry is locked, a LOCKED indicator appears
+ alone on a line at the top of this part of the output.
+
+ The volumeID numbers allocated to the ReadWrite, ReadOnly,
+ Backup versions of the volume, and the ReleaseClone version
+ if it exists. The first three types are also marked with a
+ status flag of either valid or invalid. The valid flag
+ indicates that at least one copy of that version of the
+ volume exists at an actual site. If the ReleaseClone ID
+ appears here, then one or more OLD or NEW flags should
+ appear on the site definition lines below.
+
+ The next line indicates the number of separate sites
+
+
+
+ (partition/file server machine pairs) where copies exist.
+ It should match the number of sites shown on the following
+ line(s).
+
+ Each of the remaining lines show where the ReadWrite copy
+ (and by implication, Backup) and each ReadOnly copy of the
+ volume resides, specified by machine name, partition name
+ and type (RW or RO). The presence of NEW or OLD flags on
+ these lines indicates a failed release; they should appear
+ only if the ReleaseClone ID also appears above.
+
+EXAMPLE
+
+ The following shows the output for the Transarc Corporation
+ cell's volume called usr with two ReadOnly replication sites
+ (this volume is mounted at /afs/transarc.com/usr). For the
+ sake of illustration, the output shows the volume as locked.
+ If it weren't, the LOCKED line would simply be missing.
+
+ % vos examine usr
+ usr 536870981 RW 3459 K On-line
+ fs2.transarc.com /vicepb
+ Parent 5360870981 Clone 536870982 Backup 536870
+ MaxQuota 40000 K
+ Creation Mon Jun 12 15:22:06 1989
+ Last Update Fri Jun 16 09:34:35 1989
+ 5719 accesses in the past day
+
+ LOCKED
+ readWriteID 536870981 valid
+ readOnlyID 536870982 valid
+ backUpID 536870983 invalid
+ number of sites -> 3
+ server fs1.transarc.com partition /vicepa RO Site
+ server fs3.transarc.com partition /vicepa RO Site
+ server fs2.transarc.com partition /vicepb RW Site
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos diskrestore vos listvol
+
+ vos listvldb vos restore
--- /dev/null
+vos help AFS Commands vos help
+
+
+NAME
+
+ vos help -- show syntax of specified vos command(s) or list
+
+ functional description for all of them.
+
+
+ +
+ vos help [-topic <help string> ] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ +
+ vos h [-t <help string> ] [-h]
+
+DESCRIPTION
+
+ Displays the first line (name and short description) of
+ every vos command's help entry, if no help string is
+ provided. For each operation code specified with -topic, it
+ outputs the entire help entry. See the Output section
+ below.
+
+ARGUMENTS
+
+ -topic specifies the operation code(s) for which
+ syntax is to be provided. If it is omitted,
+ the output instead provides a short
+ description of all vos commands.
+
+ -help prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The online help entry for each vos command consists of two
+ or three lines:
+
+ - The first line names the command and briefly
+ describes what it does.
+
+ - If the command has aliases, they will appear on
+ the next line.
+
+ - The final line, which begins with "Usage:", lists
+ the command's arguments and flags in the
+ prescribed order. Online help entries use the
+ same symbols (brackets, etc.) as the command
+ definitions in this manual. For an explanation of
+ their meaning, see page v of the introductory
+ About This Manual chapter.
+
+
+
+EXAMPLE
+
+ The following displays the online help entry for the
+ vos create command.
+
+ %vos help create
+ vos create: create a new volume
+ Usage: vos create -server <machine name> -partition
+ <partition name> -name <volume name> [-cell <cell name>]
+ [-noauth] [-localauth] [-verbose] [-help]
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos apropos
--- /dev/null
+vos listpart AFS Commands vos listpart
+
+
+NAME
+
+ vos listpart -- show all AFS partitions on specified file
+
+ server machine.
+
+
+ vos listpart -server <machine name> [-cell <cell name>]
+ [-noauth] [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos listp -s <machine name> [-c <cell name>] [-n] [-l]
+ [-v] [-h]
+
+DESCRIPTION
+
+ Lists all of the valid AFS partitions on the indicated file
+ server machine, without consulting the VLDB.
+
+ARGUMENTS
+
+ -server names the file server machine for which to
+ list the partitions. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -cell
+ specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The output consists of a list of partition names of the form
+ /vicepx, following the header:
+
+ The partitions on the server are:
+
+ The last line of the output reports the total number of
+ partitions.
+
+
+
+EXAMPLE
+
+ The following lists the partitions on fs1.transarc.com.
+
+ % vos listpart fs1.transarc.com
+ The partitions on the server are:
+ /vicepa
+ /vicepb
+ /vicepc
+ /vicepd
+ Total -> 4
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos partinfo
--- /dev/null
+vos listvldb AFS Commands vos listvldb
+
+
+NAME
+
+ vos listvldb -- show information from the VLDB.
+
+
+ vos listvldb [-name <volume name or ID>] [-server <machine
+ name>] [-partition <partition name>] [-locked]
+ [-quiet]
+ [-cell <cell name>] [-noauth] [-localauth] [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos listvl [-na <volume name or ID>] [-s <machine name>]
+ [-p <partition name>] [-lock] [-q] [-c <cell
+ name>] [-no] [-loca] [-v] [-h]
+
+DESCRIPTION
+
+ Formats and displays information from the VLDB entry for the
+ volume(s) indicated by the combination of the arguments
+ provided. The possibilities are listed here from most to
+ least inclusive
+
+ To display:
+
+ - every entry in the VLDB, provide no arguments.
+ This can take a very long time, depending on the
+ number of entries.
+
+ - every VLDB entry that mentions a certain file
+ server machine as the site of a ReadWrite or
+ ReadOnly version of a volume, specify the
+ machine's name with -server.
+
+ - every VLDB entry that mentions a certain partition
+ on any file server machine as the site of a
+ ReadWrite or ReadOnly version of a volume, specify
+ the partition name with -partition.
+
+ - every VLDB entry that mentions a certain partition
+ on a certain file server machine as the site of a
+ ReadWrite or ReadOnly version of a volume, combine
+ -server and -partition.
+
+ - a single VLDB entry, specify a volume name or ID
+ number with -name.
+
+ - the VLDB entry only for the volumes with locked
+ VLDB entries found at a certain site, combine the
+ -locked flag with any of arguments that define
+ sites.
+
+ARGUMENTS
+
+ -name specifies either the complete name or
+ volumeID number of a volume of any of the
+ three types.
+
+ -server names a file server machine. Abbreviated
+ forms of machine names may be allowed
+
+
+
+ depending on the naming service available at
+ the time the command is issued; see page xii
+ in the introductory About This Manual
+ chapter. This argument may be combined with
+ -partition.
+
+ -partition names a partition. In addition to the full
+ /vicepx form of a partition name, three
+ shorter forms are acceptable; see page xii
+ in the introductory About This Manual
+ chapter. This argument may be combined with
+ -server.
+
+ -locked indicates that the output will show only
+ locked VLDB entries. May be used alone, or
+ combined with one or more of -name, -server
+ or -partition.
+
+ -quiet suppresses the lines that appear at the
+ beginning and end of the output, which
+ specify the machine/partition the listing is
+ for, and the total number of entries
+ reported.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ The first line specifies the machine and/or partition for
+ which output is given. If the -quiet flag is added, this
+ line does not appear.
+
+ The VLDB entry for each volume includes the following
+ information:
+
+ - If the VLDB entry is locked, a LOCKED indicator
+ appears alone on a line at the top of the output.
+
+ - The normal first line displays the volume's name.
+
+ - Next appear the volumeID numbers for the
+ ReadWrite, ReadOnly, Backup copies of the volume,
+ and for the ReleaseClone copy if it exists. The
+
+
+
+ first three types are also marked with a status
+ flag of either valid or invalid. The valid flag
+ indicates that at least one copy of that version
+ of the volume exists at an actual site. If the
+ ReleaseClone ID appears here, then one or more OLD
+ or NEW flags should appear on the site definition
+ lines below.
+
+ - The next-to-last line indicates the number of
+ separate sites (partition/file server machine
+ pairs) where copies exist. It should match the
+ number of sites shown on the following line(s).
+
+ - Each of the remaining lines show where the
+ ReadWrite copy (and by implication, Backup) and
+ each ReadOnly copy of the volume resides,
+ specified by file server machine name, partition
+ name and type (RW or RO). The presence of NEW or
+ OLD flags on these lines indicates a failed
+ release; they should appear only if the
+ ReleaseClone ID also appears above.
+
+ If the output includes more than one VLDB entry, the very
+ last line of the output shows the total number of entries
+ reported. This line does not appear if the -quiet flag is
+ used.
+
+EXAMPLE(S)
+
+ The following displays VLDB information the Transarc
+ Corporation volume called usr, which has with two ReadOnly
+ replication sites:
+
+ % vos listvldb usr
+ usr
+ readWriteID 536870981 valid
+ readOnlyID 536870982 valid
+ backUpID 536870983 invalid
+ number of sites -> 3
+ server fs1.transarc.com partition /vicepa RO Site
+ server fs3.transarc.com partition /vicepa RO Site
+ server fs2.transarc.com partition /vicepb RW Site
+
+ The following shows entries for two of the volumes that
+ reside on fs4.transarc.com. The VLDB entry for the first is
+ currently locked.
+
+ % vos listvldb -s fs4.transarc.com
+ . . . .
+ . . . .
+ LOCKED
+ user.smith
+ readWriteID 278541326 valid
+ readOnlyID 278541327 invalid
+ backUpID 278542328 valid
+ number of sites -> 1
+ server fs4.transarc.com partition /vicepg RW Site
+
+
+
+ user.terry
+ readWriteID 354287190 valid
+ readOnlyID 354287191 invalid
+ backUpID 354287192 valid
+ number of sites -> 1
+ server fs4.transarc.com partition /vicepc RW Site
+ . . . .
+ . . . .
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos examine vos listvol vos lock vos unlock vos unlockvldb
--- /dev/null
+vos listvol AFS Commands vos listvol
+
+
+NAME
+
+ vos listvol -- show information from volume header(s).
+
+
+ vos listvol -server <machine name> [-partition <partition
+ name>] [-fast]
+ [-long] [-quiet] [-cell <cell name>] [-noauth]
+ [-localauth]
+ [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos listvo -s <machine name> [-p <partition name>] [-f]
+ [-lon] [-q]
+ [-c <cell name>] [-n] [-loc] [-v] [-h]
+
+DESCRIPTION
+
+ Formats and displays information from the volume header of
+ the indicated volumes: the volume's name, volumeID number,
+ type, size and status at the server.
+
+ To display volume header information for:
+
+ - every volume on a file server machine, specify the
+ machine's name with -server.
+
+ - every volume at a particular site, provide the
+ file server machine name with -server and the
+ partition with -partition.
+
+ARGUMENTS
+
+ -server names a file server machine. Abbreviated
+ forms of machine names may be allowed
+ depending on the naming service available at
+ the time the command is issued; see page xii
+ in the introductory About This Manual
+ chapter. This argument may be combined with
+ -partition.
+
+ -partition names a partition. In addition to the full
+ /vicepx form of a partition name, three
+ shorter forms are acceptable; see page xii
+ in the introductory About This Manual
+ chapter. The -server argument must be
+ provided along with this argument.
+
+ -fast indicates that the output should display
+ only the volumeID numbers of all volumes at
+ the indicated location.
+
+ -long indicates that the output should include the
+ IDs of all volumes associated with the
+ volume, the ReadWrite volume's quota,
+ creation date and update date. See the
+ Output section below.
+
+ -quiet suppresses the lines that appear at the
+ beginning and end of the output, which total
+
+
+
+ the number of volumes listed.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+OUTPUT
+
+ By default, the output puts the volumes in alphabetical
+ order by name and lists for each volume:
+
+ - the volume name.
+
+ - the volumeID number.
+
+ - the type (possible values: RW for ReadWrite, RO
+ for ReadOnly and BK for Backup).
+
+ - the current size in Kbytes.
+
+ - the status at the server. The possible values are
+ On-line, Off-line and needs salvage. On-line
+ indicates that the volume is accessible, whereas
+ the other two indicate a possible problem with the
+ volume. See section 8.2 in the Reference Manual
+ for further details.
+
+ The first line of the output tells how many volumes appear
+ in the listing, and the last line how many of those are
+ on-line, off-line and busy. These lines do not appear if
+ the -quiet flag is used.
+
+ If the -fast flag is added, the output lists only the volume
+ ID number of each volume, arranged in increasing numerical
+ order, and omits the last line.
+
+ If the -long flag is added, the output includes all of the
+ information in the default listing and adds the following
+ for each volume.
+
+ - the site (file server machine and partition)
+
+ - the Parent (ReadWrite), Clone (ReleaseClone or
+ Backup) and Backup volume IDs associated with the
+ volume. One should match the regular volumeID
+
+
+
+ number. See section 8.2 in the Reference Manual
+ for a more complete explanation. the maximum
+ quota allotted to the ReadWrite copy of the
+ volume, in kilobytes
+
+ - the creation date. If the volume has been
+ restored with backup diskrestore,
+ backup volrestore or vos restore, this is the
+ restore time.
+
+ - the update date, when the contents of this volume
+ last changed. For ReadOnly and Backup volumes,
+ this should match the creation date.
+
+ - the number of times the volume has been accessed
+ since the later of
+
+ * 12:00 a.m. on the day the command is issued
+
+ * the last time the volume changed location
+
+ An access is defined as a fetch or store operation
+ on any file system object stored in the volume.
+
+EXAMPLES
+
+ The following shows selected parts of the default listing
+ for the /vicepb partition on fs2.transarc.com.
+
+ % vos listvol fs2.transarc.com b
+ Total number of volumes on server fs2.transarc.com
+ \ partition /vicepb :
+ sys 1969534847 RW 1582 K On-
+ sys.backup 1969535105 BK 1582 K On-
+ . . . . .
+ . . . . .
+ user.pat 1969534536 RW 17518 K On-
+ user.pat.backup 1969534538 BK 17537 K On-
+ Total volumes onLine 66 ; Total volumes offLine 0 ;
+ Total bus
+
+ The following shows the output when the -fast flag is added.
+
+ % vos listvol fs2.transarc.com b -fast
+ Total number of volumes on server fs2.transarc.com
+ partition /vicepb :
+ 1969516782
+ 1969516784
+ .
+ .
+ 1969535796
+ Total volumes onLine 66 ; Total volumes offLine 0 ;
+ Total bus
+
+
+
+ The following shows two volumes from the output that appears
+ when the -long flag is added.
+
+ % vos listvol fs2.transarc.com b -long
+ Total number of volumes on server fs2.transarc.com
+ \ partition /vicepb :
+ . . . . .
+ . . . . .
+ user.pat 1969534536 RW 17518 K On-
+ fs2.transarc.com /vicepb
+ Parent 1969534536 Clone 0 Backup 19695
+ MaxQuota 20000 K
+ Creation Mon Jun 12 09:02:25 1989
+ Last Update Thu Jan 4 17:39:34 1990
+ 1573 accesses in the past day
+ user.pat.backup 1969534538 BK 17537 K On-
+ fs2.transarc.com /vicepb
+ Parent 1969534536 Clone 0 Backup 19695
+ MaxQuota 20000 K
+ Creation Fri Jan 5 06:37:59 1990
+ Last Update Fri Jan 5 06:37:59 1990
+ 0 accesses in the past day
+ . . . . .
+ . . . . .
+ Total volumes onLine 66 ; Total volumes offLine 0 ;
+ Total bus
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ backup diskrestore
+
+ backup volrestore
+
+ vos examine vos listvldb vos restore
--- /dev/null
+vos lock AFS Commands vos lock
+
+
+NAME
+
+ vos lock -- lock a volume entry in the VLDB.
+
+
+ vos lock -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos lo -i <volume name or ID> [-c <cell name>] [-n] [-l]
+ [-v] [-h]
+
+DESCRIPTION
+
+ Locks the VLDB entry for the indicated volume, such that no
+ one else can execute an operation that requires writing in
+ that entry. Note that this blocks operations on all of the
+ volume associated with that entry, not just the one
+ specified as -id.
+
+WARNING
+
+ This command should not be used in normal circumstances. It
+ is useful if the system administrator wishes to guarantee
+ that no one else manipulates the volume until the lock is
+ released, and there is reason to believe that locking will
+ not happen automatically.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of a volume of the any of
+ the three types.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+
+
+EXAMPLE
+
+ The following locks the VLDB entry for user.terry.
+
+ % vos lo user.terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos unlock vos unlockvldb
--- /dev/null
+vos move AFS Commands vos move
+
+
+NAME
+
+ vos move -- move volume to specified other site.
+
+
+ vos move -id <volume name or ID>
+ -fromserver <machine name on source>
+ -frompartition <partition name on source>
+ -toserver <machine name on destination>
+ -topartition <partition name on destination>
+ [-cell <cell name>] [-noauth] [-verbose] [-localauth]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos m -i <volume name or ID> -froms <machine name on
+ source>
+ -fromp <partition name on source> -tos <machine name on
+ destination>
+ -top <partition name on destination> [-c <cell name>] [-n]
+ [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Moves the indicated ReadWrite volume from its current site
+ (specified with -fromserver and -frompartition) to the
+ destination site (specified with -toserver and
+ -topartition).
+
+ This command automatically removes the Backup copy from the
+ current site, if it exists. To create a new Backup at the
+ destination site, use vos backup.
+
+ It is not possible actually to move a ReadOnly or Backup
+ volume. For ReadOnly volumes, the corresponding action is
+ to create a new ReadOnly site (with vos addsite and
+ vos release) and then remove an existing one (with
+ vos remove). The only way to move a Backup volume is to
+ move its ReadWrite source and then issue vos backup.
+
+WARNING
+
+ No more that 3500 volumes should reside on one partition. A
+ greater number can cause the AFS Salvager process to
+ malfunction. It is the issuer's responsibility to check
+ that issuing this command will not cause the limit to be
+ exceeded. The vos listvol command reports the number of
+ volumes on a partition.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of a ReadWrite volume.
+
+ -fromserver names the file server machine where the
+ volume currently resides. Abbreviated forms
+ of machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -frompartition
+
+
+
+ names the partition where the volume
+ currently resides. In addition to the full
+ /vicepx form of a partition name, three
+ shorter forms are acceptable; see page xii
+ in the introductory About This Manual
+ chapter.
+
+ -toserver names the file server machine to which the
+ volume should move. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -topartition
+ names the partition to which the volume
+ should move. In addition to the full
+ /vicepx form of a partition name, three
+ shorter forms are acceptable; see page xii
+ in the introductory About This Manual
+ chapter.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following moves the volume user.smith from /vicepb on
+ fs3.transarc.com to /vicepg on fs7.transarc.com.
+
+ % vos move user.smith fs3.transarc.com b fs7.transarc.com g
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on both
+ -fromserver and -toserver.
+
+MORE INFORMATION
+
+ vos addsite vos listvol vos remove
+
+ vos backup vos release
--- /dev/null
+vos partinfo AFS Commands vos partinfo
+
+
+NAME
+
+ vos partinfo -- show available and total space on specified
+
+ partition(s).
+
+
+ vos partinfo -server <machine name> [-partition <partition
+ name>] [-cell <cell name>] [-noauth] [-localauth]
+ [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos p -s <machine name> [-p <partition name>] [-c <cell
+ name>]
+ [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Lists the amount of space available and total size on either
+ all of the partitions on the indicated file server machine
+ (if -partition is omitted) or the specified partition on
+ that file server machine. The VLDB is not consulted.
+
+ARGUMENTS
+
+ -server names the file server machine for which to
+ inspect the partitions. Abbreviated forms
+ of machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -partition
+ names the particular partition to inspect.
+ In addition to the full /vicepx form of a
+ partition name, three shorter forms are
+ acceptable; see page xii in the introductory
+ About This Manual chapter.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+
+
+OUTPUT
+
+ Note: The total partition size reported in this command may
+ not agree with the same figure in the output of the standard
+ UNIX df command. The df total size includes some reserved
+ space that does not show up in this report, and so is likely
+ to be about 10% larger.
+
+ The output reports the amount of space available and total
+ space for each specified partition.
+
+EXAMPLE
+
+ The following lists all the partitions on fs2.transarc.com.
+
+ % vos p fs2.transarc.com
+ Free space on partition /vicepa : 27301 K blocks out
+ Free space on partition /vicepb : 13646 K blocks out
+ Free space on partition /vicepc : 31798 K blocks out
+ Free space on partition /vicepd : 33302 K blocks out
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
+
+ vos listpart
--- /dev/null
+vos release AFS Commands vos release
+
+
+NAME
+
+ vos release -- place ReadOnly versions of a ReadOnly volume
+
+ at the sites indicated in the VLDB
+ entry.
+
+
+ vos release -id <volume name or ID> [-f] [-cell <cell
+ name>] [-noauth] [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos rel -i <volume name or ID> [-f] [-c <cell name>]
+ [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Clones the indicated ReadWrite volume and places a copy of
+ the clone at each ReadOnly site indicated in the VLDB entry.
+ Each copy is named after the ReadWrite source, with the
+ addition of a .readonly extension. When at least one site
+ successfully receives its copy of the clone, the VLDB status
+ flag for ReadOnly is set to valid.
+
+ The issuer must already have defined the ReadOnly sites
+ using vos addsite.
+
+ The vos release command is no more difficult to use than any
+ other vos command, but exactly what happens internally
+ during its execution is somewhat complicated. The
+ complexity is necessary in order to ensure that all copies
+ of the volume's ReadOnly version match both the ReadWrite
+ source and each other. If all the ReadOnly copies are not
+ the same, then users might see different data depending on
+ which copy of the volume they happen to access--obviously
+ not a satisfactory situation. To make sure that all
+ ReadOnly copies match each other and the ReadWrite source,
+ releases should be "all-or-nothing"--either all ReadOnly
+ sites receive the new clone, or all sites keep the ReadOnly
+ version they currently have.
+
+ The "all-or-nothing" requirement has two main implications
+ that affect the issuer:
+
+ - he or she needs to be alert for error messages
+ that indicate an unsuccessful release, and/or
+ check the VLDB entry to make sure certain
+ error-signalling flags are not present
+
+ - he or she needs to decide whether to use the -f
+ flag
+
+ The following two subsections discuss these two
+ implications.
+
+ Flags that indicate a failed release
+
+ If the vos release command fails before the ReadOnly volume
+ is in place at every defined site, an error message will
+ specify which sites did not receive the ReadOnly volume. To
+
+
+
+ give the issuer a backup method for determining if a release
+ has completed (and for its own internal use), the Volume
+ Server and VL Server set various flags while executing the
+ following vos release steps. The presence of some of these
+ flags after an apparent completion signals failure. After
+ determining the cause of the failure, the issuer should
+ attempt to eliminate the cause and then continue to issue
+ the vos release commands as many times as necessary to make
+ sure the release completes successfully.
+
+ The steps during a release, and the flags set, are
+
+ 1. Before cloning begins, the VL Server sets the
+ site flag for the present ReadOnly entries in the
+ VLDB to OLD.
+
+ 2. The VL Server sets the site flag for the
+ ReadWrite source to NEW.
+
+ 3. The Volume Server clones the ReadWrite source, if
+ required. It assigns the clone a temporary
+ volumeID number and the VL Server puts that
+ number in the releaseClone field in the source's
+ VLDB entry. (The discussion below on the use of
+ the -f flag describes when the Volume Server
+ should make a new clone, and how it uses the
+ releaseClone ID in case a release is not
+ completely successful.)
+
+ 4. The Volume Server distributes a copy of the
+ ReleaseClone to each ReadOnly site previously
+ defined in the VLDB (using vos addsite). The VL
+ Server changes the site flag for each ReadOnly
+ site from OLD to NEW as soon as the site
+ successfully receives the new clone.
+
+ 5. When all the ReadOnly copies are successfully
+ released, the VL Server clears all the NEW site
+ flags, leaving that part of the site flag field
+ empty. Because it is no longer needed, the
+ Volume Server deletes the ReleaseClone from the
+ system and its ID from the VLDB.
+
+ The presence of NEW and/or OLD site flags in the VLDB after
+ the "completion" of a release indicates that it was not
+ successful. As mentioned above, an unsuccessful release
+ unfortunately makes it possible that Cache Managers could
+ see different versions of a volume, depending on which File
+ Server they contact. In practice, this is likely to happen
+ only if they flush their caches in order to pick up the new
+ release, but the operator should avert the possibility by
+ taking whatever steps are necessary to make the release
+ successful.
+
+ Using the -f flag
+
+ If the issuer wants to make sure that the Volume Server
+ releases a brand new clone to the ReadOnly sites, he or she
+ can include the -f flag. The flag "forces" the Volume
+ Server to make a new clone of the ReadWrite source volume
+ and distribute it to all the possible ReadOnly sites.
+
+
+
+ If the issuer does not include the -f flag, the Volume
+ Server's course of action depends on whether all of the
+ ReadOnly sites already have identical copies of the volume:
+
+ - If all the sites currently have the same copy, the
+ Volume Server infers that the previous vos release
+ command must have completed successfully, and that
+ no new ReadOnly sites have been defined since.
+ Assuming that the issuer wants to release a brand
+ new clone, the Volume Server makes one and
+ distributes it to all the defined sites.
+
+ - If all the sites do not have the same copy, then
+ the Volume Server concludes that either the
+ previous vos release command failed in the middle
+ or else a system administrator has defined a new
+ ReadOnly site since the last release. (A possible
+ reason for failure of a release is that one or
+ more sites were inaccessible at the time.) The
+ Volume Server does not need to make an entirely
+ new clone, however. Instead, it distributes the
+ clone with the releaseClone volumeID to the sites
+ that do not have it yet (step 3 in the Reference
+ Manual above defines the ReleaseClone). If this
+ release also fails, the operator needs to issue
+ more vos release commands until the same copy
+ exists at all sites.
+
+WARNING
+
+ There should be a maximum of seven sites defined in the VLDB
+ entry for the volume (one ReadWrite site and up to six
+ ReadOnly sites).
+
+ No more that 3500 volumes should reside on one partition. A
+ greater number can cause the AFS Salvager process to
+ malfunction. It is the issuer's responsibility to check
+ that issuing this command will not cause the limit to be
+ exceeded. The vos listvol command reports the number of
+ volumes on a partition.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of a ReadWrite volume.
+
+ -f determines whether the Volume Server makes a
+ new clone before distributing it to the
+ ReadOnly sites, in interaction with the
+ state of the ReadOnly copies already at
+ sites. The section entitled Using the -f
+ flag describes all the issues.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+
+
+
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following clones the ReadWrite volume usr and releases
+ it to the ReadOnly sites defined in its VLDB entry.
+
+ % vos release usr
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos addsite vos listvol
+
+ vos syncserv vos syncvldb
--- /dev/null
+vos remove AFS Commands vos remove
+
+
+NAME
+
+ vos remove -- remove specified volume from a site.
+
+
+ vos remove -server <machine name> -partition <partition
+ name> -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos remo -s <machine name> -p <partition name>
+ -i <volume name or ID> [-c <cell name>] [-n] [-l] [-v]
+ [-h]
+
+DESCRIPTION
+
+ Removes the indicated volume from the site specified by
+ -server and -partition. The VLDB records the removal, with
+ the precise results described below.
+
+ Use this command to remove any of the three types of
+ volumes; the exact effect differs for the types:
+
+ - Removing a ReadWrite volume automatically removes
+ its associated Backup copy as well. The site
+ information for both is removed from the VLDB
+ entry, and their status flags are set to invalid,
+ but their volumeIDs are still recorded. ReadOnly
+ sites, if any, are not affected. The whole VLDB
+ entry is removed if there are no ReadOnly sites.
+
+ - Removing ReadOnly copies is on a site-by-site
+ basis, as specified by -server and -partition. The
+ specified site is erased from the VLDB entry. If
+ no ReadOnly sites remain, the VLDB status flag for
+ ReadOnly changes to invalid, but the ReadOnly
+ volumeID is still recorded.
+
+ - Removing a Backup copy marks it as invalid in the
+ VLDB entry, but does not erase its volumeID.
+
+ This command is appropriate in almost all circumstances.
+ Other commands (vos delentry, vos remsite and vos zap) are
+ available for removing volumes or VLDB entries, but by
+ definition they can put the volumes and VLDB out of sync.
+ Use them only in the special circumstances mentioned in
+ their command descriptions.
+
+ARGUMENTS
+
+ -server names the file server machine where the
+ volume resides. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -partition
+ names the particular partition to inspect.
+ In addition to the full /vicepx form of a
+
+
+
+ partition name, three shorter forms are
+ acceptable; see page xii in the introductory
+ About This Manual chapter.
+
+ -id specifies either the complete name or
+ volumeID number of a volume of the any of
+ the three types. When removing a ReadOnly or
+ Backup volume, avoid accidently removing the
+ ReadWrite source by:
+
+ EITHER specifying the appropriate extension
+ if providing a name
+
+ OR using the appropriate volumeID number if
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLES
+
+ The following removes the ReadWrite volume user.terry and
+ its Backup version, if any, from their site (/vicepc on
+ fs3.transarc.com).
+
+ % vos remo fs3.transarc.com c user.terry
+
+ The following removes the ReadOnly volume root.afs.readonly
+ from one of its sites, /vicepa on fs1.transarc.com.
+
+ % vos remo fs1.transarc.com a root.afs.readonly
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+
+
+MORE INFORMATION
+
+ vos delentry vos remsite vos zap
--- /dev/null
+vos remsite AFS Commands vos remsite
+
+
+NAME
+
+ vos remsite -- remove ReadOnly site definition from a VLDB
+
+ entry.
+
+
+ vos remsite -server <machine name> -partition <partition
+ name> -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos rems -s <machine name> -p <partition name>
+ -i <volume name or ID> [-c <cell name>] [-n] [-l] [-v]
+ [-h]
+
+DESCRIPTION
+
+ Removes the ReadOnly replication site specified by -machine
+ and -partition from the VLDB entry for the indicated volume,
+ which is ReadWrite.
+
+WARNING
+
+ This command should not be used as the standard way to
+ remove a ReadOnly volume, as it can put the VLDB out of sync
+ with the volumes on servers. Use vos remove instead.
+
+ This command is useful for removing ReadOnly sites that were
+ mistakenly created with the vos addsite command, before the
+ vos release command actually releases them. If a ReadOnly
+ copy already exists at the site, it is not affected.
+ However, if this ReadOnly site was the last site housing any
+ version of the volume, then the entire VLDB entry will
+ disappear, even if a copy of the ReadOnly version still
+ actually exists at the site. The discrepancy will not be
+ noticed until someone runs the vos syncserv and vos syncvldb
+ commands.
+
+ARGUMENTS
+
+ -server specifies the file server machine part of
+ the site definition to be removed.
+ Abbreviated forms of machine names may be
+ allowed depending on the naming service
+ available at the time the command is issued;
+ see page xii in the introductory About This
+ Manual chapter. -partition
+ specifies the partition name part of the
+ site definition to be removed. In addition
+ to the full /vicepx form of a partition
+ name, three shorter forms are acceptable;
+ see page xii in the introductory About This
+ Manual chapter. -id
+ specifies either the complete name or
+ volumeID number of a ReadWrite volume.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+
+
+
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following removes the mistakenly defined ReadOnly site
+ viceph on fs5.transarc.com from the VLDB entry for volume
+ root.cell.
+
+ % vos remsite fs5.transarc.com h root.cell
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos delentry vos remove vos zap
--- /dev/null
+vos rename AFS Commands vos rename
+
+
+NAME
+
+ vos rename -- rename a volume.
+
+
+ vos rename -oldname <old volume name>
+ -newname <new volume name> [-cell <cell name>]
+ [-noauth] [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos ren -o <old volume name> -ne <new volume name> [-c
+ <cell name>]
+ [-no] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Changes the name of ReadWrite volume specified with -oldname
+ to the name specified with -newname. The names of the
+ ReadWrite's ReadOnly copies and Backup copy, if any, change
+ automatically to match.
+
+ After issuing this command, remember to correct any mount
+ points that refer to the old volume name, by removing the
+ old mount point with fs rmmount and creating a new one with
+ fs mkmount.
+
+ARGUMENTS
+
+ -oldname is the current name of the ReadWrite volume.
+
+ -newname is the desired new name for the volume.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+
+
+EXAMPLE
+
+ The following changes the mistaken volume name sun3_41.afsws
+ to the correct alternative sun3_41.usr.afsws.
+
+ % vos ren sun3_41.afsws sun3_41.usr.afsws
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
--- /dev/null
+vos restore AFS Commands vos restore
+
+
+NAME
+
+ vos restore -- convert ASCII file into proper volume format
+
+ and
+ place it into the file system.
+
+
+ vos restore -server <machine name> -partition <partition
+ name> -name <name of volume to restore> [-file <dump
+ file>] [-id <volume ID>] [-cell <cell name>]
+ [-noauth] [-localauth]
+ [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos res -s <machine name> -p <partition name>
+ -na <name of volume to be restored> [-f <dump file>] [-i
+ <volume ID>]
+ [-c <cell name>] [-no] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Converts the dump file indicated with -file from ASCII into
+ the volume format appropriate for the machine specified as
+ -server, and restores it as a ReadWrite volume to the site
+ specified by -server and -partition. It assigns it the name
+ indicated with -name, and resets the volume's "creation
+ date," stored in the volume header, to match the restore
+ time. If -file is not provided, the issuer must provide
+ input from standard input (stdin), presumably through a
+ pipe.
+
+ The issuer may optionally specify a volumeID number as -id,
+ but this is not generally recommended; the Volume Server
+ allocates one otherwise. If used, it should be a number
+ that the issuer knows is available and has a particular
+ reason for using.
+
+ If the name indicated is the name of an existing (ReadWrite)
+ volume, the contents of the dump file will overwrite the
+ existing volume, after the command interpreter prompts for
+ confirmation that this is acceptable. The volume retains
+ its current volumeID number.
+
+ARGUMENTS
+
+ -server names the file server machine onto which to
+ restore the volume. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -partition
+ names the partition onto which to restore
+ the volume. In addition to the full /vicepx
+ form of a partition name, three shorter
+ forms are acceptable; see page xii in the
+ introductory About This Manual chapter.
+ -name
+ specifies the name under which to restore
+
+
+
+ the volume. If a volume already exists
+ under that name, it will be overwritten
+ after the issuer is prompted for
+ confirmation.
+
+ -file names the dump file the Volume Server should
+ restore. If the issuer provides a full or
+ relative pathname, the Volume Server looks
+ for the file there; otherwise it looks in
+ the current working directory. If the
+ issuer does not provide this argument, he or
+ she must provide input through standard
+ input (stdin).
+
+ -id specifies the volumeID number to assign to
+ the restored volume.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following restores the contents of the dump file
+ /afs/transarc.com/common/dumps/terry.dump to the /vicepc
+ partition on fs3.transarc.com. The restored volume is
+ called user.terry.
+
+ % cd /afs/transarc.com/common/dumps % vos res terry.dump
+ fs3.transarc.com c user.terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos dump vos examine
+
+ vos listvol
--- /dev/null
+vos status AFS Commands vos status
+
+
+NAME
+
+ vos status -- report activity of Volume Server.
+
+
+ vos status -server <machine name> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos st -s <machine name> [-c <cell name>] [-n] [-l]
+ [-v] [-h]
+
+DESCRIPTION
+
+ Reports on what the Volume Server on a certain file server
+ machine is doing at the moment the command is issued. If
+ there is no activity, it returns nothing.
+
+ Useful mainly if there is concern that the Volume Server is
+ not performing requested actions.
+
+ARGUMENTS
+
+ -server names a file server machine. Abbreviated
+ forms of machine names may be allowed
+ depending on the naming service available at
+ the time the command is issued; see page xii
+ in the introductory About This Manual
+ chapter. -cell
+ specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+
+
+OUTPUT
+
+ There are two possible types of output.
+
+ The following message indicates that the Volume Server is
+ not currently performing any actions.
+
+ No active transactions on machine name
+
+ The other possible output is a set of information which is
+ probably more useful to programmers than to system
+ administrators. A full understanding of all the fields
+ requires familiarity with the code for the Volume Server, as
+ many of the fields report ID numbers and flag values that
+ the Volume Server sets for internal use.
+
+ Among the fields of possible interest to an administrator
+ are:
+
+ - created on the first line, which indicates the
+ time at which this transaction started
+
+ - attachFlags on the second line, where a value of
+ offline indicates that the volume is not available
+ for other read or write operations during this
+ transaction
+
+ - volume on the third line, which specifies the
+ affected volume's ID number
+
+ - partition on the third line, which indicates where
+ the affected volume resides (at the beginning of
+ the transaction if this is a move)
+
+ - procedure on the third line, which indicates the
+ internal subprocedure being executed
+
+ A fourth line may appear during certain transactions, and
+ includes the following fields:
+
+ - packetRead tracks whether information is being
+ read into the volume. Its absolute value is not
+ informative, but the way it changes shows whether
+ the vos restore command is executing properly. As
+ vos status is issued repeatedly during a restore,
+ readNext should increase monotonically to indicate
+ that information is being read into the volume.
+
+ - packetSend tracks whether information is being
+ sent out of the volume. Its absolute value is not
+ informative, but the way it changes shows whether
+ the vos dump command is executing properly. As
+ vos status is issued repeatedly during a dump,
+ transmitNext should increase monotonically to
+ indicate that information is being transferred
+ from the volume into the dump file.
+
+ The lastReceiveTime and lastSendTime are for internal use.
+
+
+
+EXAMPLE
+
+ The following illustrates the kind of output that might be
+ seen if the Volume Server on fs1.transarc.com is executing a
+ dump when this command is issued.
+
+ % vos status fs1.transarc.com
+ --------------------------------------------
+ transaction: 575 created: Tue Jan 2 8:34:56 1990
+ attachFlags: offline
+ volume: 536871080 partition: /vicepb procedure: Dump
+ packetRead: 2 lastReceiveTime: 113313 packetSend: 24
+ lastSendTime: 113317
+ --------------------------------------------
+
+PRIVILEGE REQUIRED
+
+ None.
+
+MORE INFORMATION
--- /dev/null
+vos syncserv AFS Commands vos syncserv
+
+
+NAME
+
+ vos syncserv -- synchronize VLDB entries that mention a
+
+ given site with volume headers.
+
+
+ vos syncserv -server <machine name> [-partition <partition
+ name>] [-cell <cell name>] [-noauth] [-localauth]
+ [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos syncs -s <machine name> [-p <partition name>]
+ [-c <cell name>] [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Finds and inspects the VLDB entries for volumes (ReadWrite,
+ ReadOnly and Backup) residing on the file server machine
+ specified by -serverMEITHER all of the volumes OR only the
+ volumes on the optionally specified -partition. It checks
+ that everything in the VLDB entry is correct, including the
+ reported sites of all copies (even though that requires
+ looking at volumes on servers other than -server). There
+ are several possible changes it can make:
+
+ - If a volume header is marked Off-line, but the
+ corresponding VLDB entry is normal, then the
+ volume is brought on-line. (Note that the Off-line
+ flag does not indicate the volume is corrupted.)
+
+ - If there are two copies of a given volume at
+ different sites, both marked Off-line, the newer
+ volume is brought on-line and the older one is
+ deleted from its site and the VLDB. (This
+ situation could arise if the execution of a
+ vos move command were interrupted).
+
+ - If a volume recorded in the VLDB does not exist at
+ the indicated site, then the VLDB entry is
+ changed. In the case of ReadWrite, Backup and the
+ last site for ReadOnly, that means changing the
+ appropriate VLDB status flag to invalid.
+
+ Run this command, preferably on all file server machines,
+ after vos syncvldb has been run on all file server machines.
+
+ARGUMENTS
+
+ -server names the file server machine for which to
+ check entries in the VLDB. Abbreviated
+ forms of machine names may be allowed
+ depending on the naming service available at
+ the time the command is issued; see page xii
+ in the introductory About This Manual
+ chapter. -partition
+ names the partition for which to check VLDB
+ entries. In addition to the full /vicepx
+ form of a partition name, three shorter
+
+
+
+ forms are acceptable; see page xii in the
+ introductory About This Manual chapter.
+ -cell
+ specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following alters the VLDB entries of volumes whose site
+ definitions mention fs3.transarc.com to match the volume
+ header.
+
+ % vos syncserv fs3.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos move vos syncvldb
--- /dev/null
+vos syncvldb AFS Commands vos syncvldb
+
+
+NAME
+
+ vos syncvldb -- synchronize VLDB entry with volume headers
+
+ at given site.
+
+
+ vos syncvldb -server <machine name> [-partition <partition
+ name>] [-cell <cell name>] [-noauth] [-localauth]
+ [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos syncv -s <machine name> [-p <partition name>] [-c
+ <cell name>]
+ [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Inspects the volumes housed on the file server machine
+ indicated with -serverMEITHER all of the volumes OR only the
+ volumes on the optionally specified -partition. It checks
+ that the VLDB properly records every volume whose volume
+ header is marked On-line. In case of discrepancies, this
+ command alters VLDB entries to reflect the true status of
+ volumes on -server. It has other side effects:
+
+ - If it finds a Backup volume whose ReadWrite source
+ no longer exists at the same site, it removes the
+ Backup. The VLDB status flag for the Backup
+ changes to invalid. The issuer will have to issue
+ the vos backup command to create a new Backup if
+ desired.
+
+ - The VL Server keeps track of the next available
+ volumeID number with a counter. This command
+ changes the counter to the highest volumeID number
+ found.
+
+ - If it encounters multiple ReadOnly copies of a
+ volume at the same site, or multiple Backup
+ copies, it removes all but the newest one (as
+ determined by the Creation Date field in the
+ volume header) from that site.
+
+ After running this command, execute vos syncserv, preferably
+ on all file server machines in the cell.
+
+ARGUMENTS
+
+ -server names the file server machine from which to
+ compare volumes to VLDB entries.
+ Abbreviated forms of machine names may be
+ allowed depending on the naming service
+ available at the time the command is issued;
+ see page xii in the introductory About This
+ Manual chapter. -partition
+ names the partition from which to compare
+ volumes to VLDB entries. In addition to the
+ full /vicepx form of a partition name, three
+
+
+
+ shorter forms are acceptable; see page xii
+ in the introductory About This Manual
+ chapter.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following makes sure that the VLDB matches the volume
+ headers found at sites on fs4.transarc.com.
+
+ % vos syncvldb fs4.transarc.com
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos backup vos syncserv
--- /dev/null
+vos unlock AFS Commands vos unlock
+
+
+NAME
+
+ vos unlock -- unlock an entry in the VLDB.
+
+
+ vos unlock -id <volume name or ID> [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos unlock -i <volume name or ID> [-c <cell name>] [-n]
+ [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Releases the lock on the VLDB entry for the indicated
+ volume.
+
+WARNING
+
+ This command should not be used under normal circumstances.
+
+ It is useful if the VLDB entry is locked but there is no
+ reason to suspect inconsistency within the volume or between
+ it and the VLDB. Note that it is possible to list
+ information from locked VLDB entries, even though they
+ cannot be manipulated in other ways.
+
+ The vos unlockvldb unlocks several VLDB entries at once, or
+ even the entire VLDB. The vos lock command locks a VLDB
+ entry so that no one else may perform an action that would
+ require writing the VLDB.
+
+ARGUMENTS
+
+ -id specifies either the complete name or
+ volumeID number of a volume of any of the
+ three types.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE(S)
+
+
+
+ The following unlocks the VLDB entry for user.terry.
+
+ % vos unlock user.terry
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos lock vos unlockvldb
--- /dev/null
+vos unlockvldb AFS Commands vos unlockvldb
+
+
+NAME
+
+ vos unlockvldb -- unlock all specified locked entries in
+
+ the VLDB.
+
+
+ vos unlockvldb [-server <machine name>] [-partition
+ <partition name>]
+ [-cell <cell name>] [-noauth] [-localauth] [-verbose]
+ [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos unlockv [-s <machine name>] [-p <partition name>]
+ [-c <cell name>] [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Releases the lock on the VLDB entries indicated by the
+ combination of arguments provided. To unlock:
+
+ - all entries in the VLDB, provide no arguments.
+
+ - all entries that mention a file server machine in
+ a site definition, provide its name with -server.
+
+ - all entries that mention a partition on any file
+ server machine in a site definition, provide the
+ partition name with -partition.
+
+ - all entries that mention a specific site, provide
+ both -server and -partition.
+
+ - a single volume, use the vos unlock command
+ instead.
+
+WARNING
+
+ This command should not be issued under normal
+ circumstances.
+
+ It is useful if VLDB entries for volumes at a certain site
+ are locked but there is no reason to suspect inconsistency
+ within the volume or between it and the VLDB. Note that it
+ is possible to list information from locked VLDB entries,
+ even though they cannot be manipulated in other ways.
+
+ The vos lock command locks a VLDB entry so that no one else
+ may perform an action that would require writing the VLDB.
+
+ARGUMENTS
+
+ -server names the file server machine for which to
+ unlock VLDB entries. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -partition
+ names the partition for which to unlock VLDB
+
+
+
+ entries. In addition to the full /vicepx
+ form of a partition name, three shorter
+ forms are acceptable; see page xii in the
+ introductory About This Manual chapter.
+ -cell
+ specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLES
+
+ The following unlocks all locked entries in the VLDB.
+
+ % vos unlockvldb
+
+ The following unlocks all locked VLDB entries that mention
+ /vicepa in a site definition.
+
+ % vos unlockvldb -p a
+
+ The following unlocks all locked VLDB entries that refer to
+ volumes on the /vicepc partition of fs3.transarc.com.
+
+ % vos unlockvldb fs3.transarc.com c
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos lock vos unlock
--- /dev/null
+vos zap AFS Commands vos zap
+
+
+NAME
+
+ vos zap -- remove a volume from its site without writing to
+
+ the VLDB.
+
+
+ vos zap -server <machine name> -partition <partition name>
+ -id <volume ID> [-force] [-cell <cell name>]
+ [-noauth]
+ [-localauth] [-verbose] [-help]
+
+ACCEPTABLE ABBREVIATIONS/ALIASES
+
+ vos z -s <machine name> -p <partition name> -i <volume
+ ID>
+ [-f] [-c <cell name>] [-n] [-l] [-v] [-h]
+
+DESCRIPTION
+
+ Removes the volume with the volumeID number -id from the
+ site defined by -server and -partition, without attempting
+ to change the corresponding VLDB entry.
+
+ The -force flag removes a volume even if it cannot be
+ "attached" (brought online), which can happen either because
+ the volume is extremely damaged or because the Salvager
+ functioned abnormally. Without this flag, this command
+ cannot remove volumes that are not attachable. See also the
+ WARNINGS section.
+
+WARNINGS
+
+ This command should not be used as the standard way to
+ remove a volume, as it is likely to put the VLDB out of sync
+ with the volumes on servers. Use vos remove instead.
+
+ This command is useful in situations where it is important
+ to delete the volume, but for some reason the VLDB is
+ unreachable (the VL Server may be down). The issuer may
+ remove the VLDB entry later with vos remove or vos delentry,
+ or it will be removed automatically when someone runs
+ vos syncserv and vos syncvldb.
+
+ To remove a ReadOnly site defined in the VLDB by mistake,
+ before a copy actually exists at the site, use vos remsite.
+ To remove an entire VLDB entry without affecting volumes at
+ their sites, use vos delentry.
+
+ Do not use the -force flag if the volume is online, but only
+ when attempts to remove the volume with vos remove or
+ vos zap have failed and/or the volume definitely cannot be
+ attached. After using -force, make sure that the volume's
+ VLDB entry is also removed (issue vos delentry if
+ necessary).
+
+ Adding the -force flag makes the command take considerably
+ longerMabout as long as a salvage of the relevant
+ partitionMsince the Volume Server examines all inodes on the
+ partition for traces of the volume.
+
+
+
+ARGUMENTS
+
+ -server names the file server machine from which to
+ remove the volume. Abbreviated forms of
+ machine names may be allowed depending on
+ the naming service available at the time the
+ command is issued; see page xii in the
+ introductory About This Manual chapter.
+ -partition
+ names the partition from which to remove the
+ volume. In addition to the full /vicepx
+ form of a partition name, three shorter
+ forms are acceptable; see page xii in the
+ introductory About This Manual chapter.
+
+ -id specifies the volumeID number of the volume
+ to remove, which may be of any of the three
+ types. The volume name is not acceptable.
+
+ -force tells the Volume Server to delete the volume
+ even though it cannot be attached (brought
+ online). Use only after failed attempts to
+ remove the volume with vos remove and vos
+ zap without this flag.
+
+ -cell specifies the cell in which to run the
+ command. See section 8.3 in the Reference
+ Manual for more details. -noauth
+ tells the Volume and Volume Location Servers
+ to assign the identity anonymous to the
+ issuer. See section 8.3 in the Reference
+ Manual for more details. -localauth
+ constructs a server ticket using a key from
+ /usr/afs/etc/KeyFile. See section 8.3 in
+ the Reference Manual for more details.
+ -verbose
+ tells the Volume and Volume Location Servers
+ to report on what they are doing as they
+ execute the command. See section 8.3 in the
+ Reference Manual for more details. -help
+ prints the online help for this command. Do
+ not provide any other arguments or flags
+ with this one. See section 8.3 in the
+ Reference Manual for more details.
+
+EXAMPLE
+
+ The following removes the volume with volumeID 536870988
+ from /vicepf of fs6.transarc.com, without noting the change
+ in the VLDB.
+
+ % vos zap fs6.transarc.com f 536870988
+
+
+
+PRIVILEGE REQUIRED
+
+ Issuer must be listed in /usr/afs/etc/UserList on -server.
+
+MORE INFORMATION
+
+ vos delentry vos remove vos remsite
git://git.openafs.org / openafs.git / commitdiff