+++ /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
projects / packages / o / openafs.git / commitdiff