From: Sam Hartman Date: Tue, 11 Sep 2001 14:31:17 +0000 (+0000) Subject: Initial revision X-Git-Tag: debian/1.2.0-1~11 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=903aa0cbe587b59893205a6e61b023e9ea647bab;p=packages%2Fo%2Fopenafs.git Initial revision --- diff --git a/src/man/afs_ftpd.1 b/src/man/afs_ftpd.1 new file mode 100644 index 000000000..024d39ac9 --- /dev/null +++ b/src/man/afs_ftpd.1 @@ -0,0 +1,69 @@ +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 diff --git a/src/man/afs_inetd.1 b/src/man/afs_inetd.1 new file mode 100644 index 000000000..503cc5eb8 --- /dev/null +++ b/src/man/afs_inetd.1 @@ -0,0 +1,163 @@ +inetd (AFS version) AFS Commands inetd (AFS version) + + +NAME + + inetd (AFS version) -- initialize Internet service daemon. + + + /etc/inetd [-d] [] + +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 diff --git a/src/man/afs_login.1 b/src/man/afs_login.1 new file mode 100644 index 000000000..8a7bf1f2a --- /dev/null +++ b/src/man/afs_login.1 @@ -0,0 +1,204 @@ +login (AFS version) AFS Commands login (AFS version) + + +NAME + + login (AFS version) -- login to AFS and UNIX file systems. + + + login [] + + 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 diff --git a/src/man/afs_rcp.1 b/src/man/afs_rcp.1 new file mode 100644 index 000000000..947f6d76f --- /dev/null +++ b/src/man/afs_rcp.1 @@ -0,0 +1,134 @@ +rcp (AFS version) AFS Commands rcp (AFS version) + + +NAME + + rcp (AFS version) -- copy file on remote machine. + + + + + rcp [-p] rcp [-r] [-p] + +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 diff --git a/src/man/afs_rlogind.1 b/src/man/afs_rlogind.1 new file mode 100644 index 000000000..f18b9507a --- /dev/null +++ b/src/man/afs_rlogind.1 @@ -0,0 +1,91 @@ +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) diff --git a/src/man/afs_rsh.1 b/src/man/afs_rsh.1 new file mode 100644 index 000000000..98ccaf908 --- /dev/null +++ b/src/man/afs_rsh.1 @@ -0,0 +1,109 @@ +rsh (AFS version) AFS Commands rsh (AFS version) + + +NAME + + rsh (AFS version) -- open shell on remote machine. + + + rsh host [-l ] [-n] host [-l + ] [-n] + +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 diff --git a/src/man/afsd.1 b/src/man/afsd.1 new file mode 100644 index 000000000..e9d44c8d4 --- /dev/null +++ b/src/man/afsd.1 @@ -0,0 +1,462 @@ +afsd AFS Commands afsd + + +NAME + + afsd -- initialize Cache Manager and start related + + daemons. + + + afsd [-blocks ] [-files ] + [-stat ] [-rootvol ] + [-cachedir ] [-mountdir ] + [-verbose] [-debug] [-nosettime] + [-daemons ] [-rmtsys] + [-memcache] [-dcache <# entries>] [-chunksize ] + +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." diff --git a/src/man/dkload.1 b/src/man/dkload.1 new file mode 100644 index 000000000..9bb335640 --- /dev/null +++ b/src/man/dkload.1 @@ -0,0 +1,198 @@ +dkload AFS Commands dkload + + +NAME + + dkload -- incorporate external libraries into kernel + + without rebooting. + + + dkload [-readonly] [-quiet] [-verbose] [-syscallResult + ] + [-path ] [-ld_cmd ] + [-as_cmd ] [-nm_cmd ] + [-libcommon ] [-kernel_alloc ] + + + [-name ] [ ] + +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 ] [-p ] + [-ld ] + [-a ] [-nm ] [-li ] [-k + ] + + + [-na ] [ ] + +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.a". For example, if + 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. diff --git a/src/man/fileserver.1 b/src/man/fileserver.1 new file mode 100644 index 000000000..f83cad76d --- /dev/null +++ b/src/man/fileserver.1 @@ -0,0 +1,177 @@ +fileserver AFS Commands fileserver + + +NAME + + fileserver -- initialize File Server component of fs + + process. + + + /usr/afs/bin/fileserver [-b ] [-banner] [-cb + ] + [-d ] [-k ] [-l ] + [-oldvldb] [-pctspare ] [-rxdbg] + [-rxdbge] [-rxpck] + [-s ] [-spare ] + [-w ] + [-c ] [-ftpck ] [-noauth] + [-p ] [-r ] [-rpck [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs ap -t [-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 diff --git a/src/man/fs_checkservers.1 b/src/man/fs_checkservers.1 new file mode 100644 index 000000000..e0433c9cc --- /dev/null +++ b/src/man/fs_checkservers.1 @@ -0,0 +1,153 @@ +fs checkservers AFS Commands fs checkservers + + +NAME + + fs checkservers -- check status of file server machines. + + + fs checkservers [-cell ] [-all] [-fast] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs checks [-c ] [-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. diff --git a/src/man/fs_checkvolumes.1 b/src/man/fs_checkvolumes.1 new file mode 100644 index 000000000..adf310ee2 --- /dev/null +++ b/src/man/fs_checkvolumes.1 @@ -0,0 +1,44 @@ +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. diff --git a/src/man/fs_cleanacl.1 b/src/man/fs_cleanacl.1 new file mode 100644 index 000000000..2e6643c73 --- /dev/null +++ b/src/man/fs_cleanacl.1 @@ -0,0 +1,83 @@ +fs cleanacl AFS Commands fs cleanacl + + +NAME + + fs cleanacl -- remove obsolete entries from access control + + list. + + + + + fs cleanacl [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs cl [-p ] [-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 diff --git a/src/man/fs_copyacl.1 b/src/man/fs_copyacl.1 new file mode 100644 index 000000000..42570e24c --- /dev/null +++ b/src/man/fs_copyacl.1 @@ -0,0 +1,137 @@ +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 + + + -todir + [-clear] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs co -f -t + [-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 diff --git a/src/man/fs_debug.1 b/src/man/fs_debug.1 new file mode 100644 index 000000000..774b81116 --- /dev/null +++ b/src/man/fs_debug.1 @@ -0,0 +1,110 @@ +fs debug AFS Commands fs debug + + +NAME + + fs debug -- enable/disable Cache Manager debugging trace. + + + fs debug -debug <'on' or 'off'> [-dafs ] + [-dnet ] [-syslog] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs de -de or [-da ] + [-dn ] [-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 diff --git a/src/man/fs_diskfree.1 b/src/man/fs_diskfree.1 new file mode 100644 index 000000000..23f3368a7 --- /dev/null +++ b/src/man/fs_diskfree.1 @@ -0,0 +1,88 @@ +fs diskfree AFS Commands fs diskfree + + +NAME + + fs diskfree -- show information about the partition housing + + a directory/file. + + + + + fs diskfree [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs df [-p ] [-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 diff --git a/src/man/fs_examine.1 b/src/man/fs_examine.1 new file mode 100644 index 000000000..4734061aa --- /dev/null +++ b/src/man/fs_examine.1 @@ -0,0 +1,109 @@ +fs examine AFS Commands fs examine + + +NAME + + fs examine -- show information about volume containing + + specified directory. + + + + + fs examine [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs exa [-p ] [-h] + + + fs listvol [-p ] [-h] + + + fs lv [-p ] [-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 diff --git a/src/man/fs_exportafs.1 b/src/man/fs_exportafs.1 new file mode 100644 index 000000000..8a50e238c --- /dev/null +++ b/src/man/fs_exportafs.1 @@ -0,0 +1,93 @@ +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 [-state <'on' or + 'off'>] [-noconvert] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs exp -t [-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. diff --git a/src/man/fs_flush.1 b/src/man/fs_flush.1 new file mode 100644 index 000000000..6ac3bb76a --- /dev/null +++ b/src/man/fs_flush.1 @@ -0,0 +1,63 @@ +fs flush AFS Commands fs flush + + +NAME + + fs flush -- force Cache Manager to discard a cached + + file/directory. + + + + + fs flush [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs flush [-p ] [-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 diff --git a/src/man/fs_flushvolume.1 b/src/man/fs_flushvolume.1 new file mode 100644 index 000000000..fea28a170 --- /dev/null +++ b/src/man/fs_flushvolume.1 @@ -0,0 +1,65 @@ +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 ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs flushv [-p ] [-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 diff --git a/src/man/fs_getcacheparms.1 b/src/man/fs_getcacheparms.1 new file mode 100644 index 000000000..73be4264c --- /dev/null +++ b/src/man/fs_getcacheparms.1 @@ -0,0 +1,67 @@ +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 of the cache's available 1 + blocks. + + where is the number of 1K byte blocks the Cache + Manager is currently using, and 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 diff --git a/src/man/fs_getcellstatus.1 b/src/man/fs_getcellstatus.1 new file mode 100644 index 000000000..abb105482 --- /dev/null +++ b/src/man/fs_getcellstatus.1 @@ -0,0 +1,74 @@ +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 [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs getce -c [-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 diff --git a/src/man/fs_getserverprefs.1 b/src/man/fs_getserverprefs.1 new file mode 100644 index 000000000..017059bd0 --- /dev/null +++ b/src/man/fs_getserverprefs.1 @@ -0,0 +1,147 @@ +fs getserverprefs AFS Commands fs getserverprefs + + +NAME + + fs getserverprefs -- display Cache Manager's preferences + + for file server machines. + + + fs getserverprefs [-file ] [-numeric] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs gets [-f ] [-n] [-h] + + fs gp [-f ] [-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 diff --git a/src/man/fs_help.1 b/src/man/fs_help.1 new file mode 100644 index 000000000..e5cec0a6f --- /dev/null +++ b/src/man/fs_help.1 @@ -0,0 +1,80 @@ +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] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs h [-t ] [-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 + + + -acl [-clear] [-negative] [-help] + +PRIVILEGE REQUIRED + + None. + +MORE INFORMATION + + fs apropos diff --git a/src/man/fs_listacl.1 b/src/man/fs_listacl.1 new file mode 100644 index 000000000..5a18b6fe2 --- /dev/null +++ b/src/man/fs_listacl.1 @@ -0,0 +1,128 @@ +fs listacl AFS Commands fs listacl + + +NAME + + fs listacl -- show access control list. + + + + + fs listacl [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs la [-p ] [-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 diff --git a/src/man/fs_listcells.1 b/src/man/fs_listcells.1 new file mode 100644 index 000000000..110d195c2 --- /dev/null +++ b/src/man/fs_listcells.1 @@ -0,0 +1,64 @@ +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 diff --git a/src/man/fs_listquota.1 b/src/man/fs_listquota.1 new file mode 100644 index 000000000..d1b5b8d45 --- /dev/null +++ b/src/man/fs_listquota.1 @@ -0,0 +1,84 @@ +fs listquota AFS Commands fs listquota + + +NAME + + fs listquota -- show quota information for the volume + + containing a file/directory. + + + + + fs listquota [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs lq [-p ] [-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 diff --git a/src/man/fs_lsmount.1 b/src/man/fs_lsmount.1 new file mode 100644 index 000000000..3404c967a --- /dev/null +++ b/src/man/fs_lsmount.1 @@ -0,0 +1,96 @@ +fs lsmount AFS Commands fs lsmount + + +NAME + + fs lsmount -- show volume for which directory is a mount + + point. + + + + + fs lsmount -dir [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs ls -d [-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 diff --git a/src/man/fs_mkmount.1 b/src/man/fs_mkmount.1 new file mode 100644 index 000000000..732b0dfc4 --- /dev/null +++ b/src/man/fs_mkmount.1 @@ -0,0 +1,297 @@ +fs mkmount AFS Commands fs mkmount + + +NAME + + fs mkmount -- create a mount point for a volume. + + + fs mkmount -dir -vol [-cell ] [-rw] [-fast] [-root] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs mk -d -v [-c ] + [-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 diff --git a/src/man/fs_monitor.1 b/src/man/fs_monitor.1 new file mode 100644 index 000000000..4dc55dd5b --- /dev/null +++ b/src/man/fs_monitor.1 @@ -0,0 +1,125 @@ +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 or ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs mo [-s or ] [-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. diff --git a/src/man/fs_newcell.1 b/src/man/fs_newcell.1 new file mode 100644 index 000000000..7e0e217d1 --- /dev/null +++ b/src/man/fs_newcell.1 @@ -0,0 +1,87 @@ +fs newcell AFS Commands fs newcell + + +NAME + + fs newcell -- change list of cell's database server + + machines in kernel. + + + + + fs newcell -name -servers + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs n -n -s [-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 diff --git a/src/man/fs_quota.1 b/src/man/fs_quota.1 new file mode 100644 index 000000000..9c61fce65 --- /dev/null +++ b/src/man/fs_quota.1 @@ -0,0 +1,78 @@ +fs quota AFS Commands fs quota + + +NAME + + fs quota -- show percent of quota used for volume + + containing directory/file. + + + + + fs quota [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs q [-p ] [-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 diff --git a/src/man/fs_rmmount.1 b/src/man/fs_rmmount.1 new file mode 100644 index 000000000..b465c4b3f --- /dev/null +++ b/src/man/fs_rmmount.1 @@ -0,0 +1,52 @@ +fs rmmount AFS Commands fs rmmount + + +NAME + + fs rmmount -- destroy mount point. + + + + + fs rmmount -dir [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs rm -d [-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 diff --git a/src/man/fs_setacl.1 b/src/man/fs_setacl.1 new file mode 100644 index 000000000..b016c98d4 --- /dev/null +++ b/src/man/fs_setacl.1 @@ -0,0 +1,204 @@ +fs setacl AFS Commands fs setacl + + +NAME + + fs setacl -- sets access control list for a directory. + + + + + + fs setacl -dir -acl + [-clear] + [-negative] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + + fs sa -d -a [-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 diff --git a/src/man/fs_setcachesize.1 b/src/man/fs_setcachesize.1 new file mode 100644 index 000000000..1e84e94aa --- /dev/null +++ b/src/man/fs_setcachesize.1 @@ -0,0 +1,97 @@ +fs setcachesize AFS Commands fs setcachesize + + +NAME + + fs setcachesize -- set size of disk cache. + + + fs setcachesize [-blocks ] [-reset] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs setca [-b ] [-r] [-h] + + fs cachesize [-b ] [-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 diff --git a/src/man/fs_setcell.1 b/src/man/fs_setcell.1 new file mode 100644 index 000000000..9dc66be1f --- /dev/null +++ b/src/man/fs_setcell.1 @@ -0,0 +1,81 @@ +fs setcell AFS Commands fs setcell + + +NAME + + fs setcell -- allow or disallow running of setuid programs + + from specified cells. + + + + + fs setcell -cell [-suid] [-nosuid] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs setce -c [-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 diff --git a/src/man/fs_setquota.1 b/src/man/fs_setquota.1 new file mode 100644 index 000000000..70e1e3b6f --- /dev/null +++ b/src/man/fs_setquota.1 @@ -0,0 +1,73 @@ +fs setquota AFS Commands fs setquota + + +NAME + + fs setquota -- sets maximum quota for volume containing + + specified directory. + + + fs setquota [-path ] -max [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs sq [-p ] -m [-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 diff --git a/src/man/fs_setserverprefs.1 b/src/man/fs_setserverprefs.1 new file mode 100644 index 000000000..ced4a6c3e --- /dev/null +++ b/src/man/fs_setserverprefs.1 @@ -0,0 +1,232 @@ +fs setserverprefs AFS Commands fs setserverprefs + + +NAME + + fs setserverprefs -- set Cache Manager's preferences for + + file server machines. + + + + + fs setserverprefs [-servers ] + [-file ] [-stdin] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs sets [-se ] [-f ] + [-st] [-h] + + + fs sp [-se ] [-f ] + [-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 diff --git a/src/man/fs_setvol.1 b/src/man/fs_setvol.1 new file mode 100644 index 000000000..bd589f0f8 --- /dev/null +++ b/src/man/fs_setvol.1 @@ -0,0 +1,94 @@ +fs setvol AFS Commands fs setvol + + +NAME + + fs setvol -- set maximum quota and messages for each volume + + containing specified directory. + + + + + fs setvol [-path [-max ] + [-motd ] [-offlinemsg ] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs sv [-p ] [-ma ] + [-mo ] [-o ] [-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 diff --git a/src/man/fs_sysname.1 b/src/man/fs_sysname.1 new file mode 100644 index 000000000..5ff74c717 --- /dev/null +++ b/src/man/fs_sysname.1 @@ -0,0 +1,112 @@ +fs sysname AFS Commands fs sysname + + +NAME + + fs sysname -- report or set CPU/operating system type. + + + fs sysname [-newsys ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + fs sy [-n ] [-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 diff --git a/src/man/fs_whereis.1 b/src/man/fs_whereis.1 new file mode 100644 index 000000000..534a6fdd1 --- /dev/null +++ b/src/man/fs_whereis.1 @@ -0,0 +1,69 @@ +fs whereis AFS Commands fs whereis + + +NAME + + fs whereis -- report name of file server machine(s) housing + + specified file/directory. + + + + + fs whereis [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs whe [-p ] [-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 diff --git a/src/man/fs_whichcell.1 b/src/man/fs_whichcell.1 new file mode 100644 index 000000000..ca9714d24 --- /dev/null +++ b/src/man/fs_whichcell.1 @@ -0,0 +1,61 @@ +fs whichcell AFS Commands fs whichcell + + +NAME + + fs whichcell -- return name of cell to which specified + + file/directory belongs. + + + + + fs whichcell [-path ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + fs whi [-p ] [-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 diff --git a/src/man/fs_wscell.1 b/src/man/fs_wscell.1 new file mode 100644 index 000000000..95d011503 --- /dev/null +++ b/src/man/fs_wscell.1 @@ -0,0 +1,50 @@ +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 diff --git a/src/man/kas.1 b/src/man/kas.1 new file mode 100644 index 000000000..1daec090a --- /dev/null +++ b/src/man/kas.1 @@ -0,0 +1,207 @@ + 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 ] + + 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 ] + + 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 ] + + 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 ] + + 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. diff --git a/src/man/kas_apropos.1 b/src/man/kas_apropos.1 new file mode 100644 index 000000000..9038eaa5a --- /dev/null +++ b/src/man/kas_apropos.1 @@ -0,0 +1,64 @@ +kas apropos AFS Commands kas apropos + + +NAME + + kas apropos -- show each help entry containing keyword. + + + kas apropos -topic [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas a -t [-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 diff --git a/src/man/kas_create.1 b/src/man/kas_create.1 new file mode 100644 index 000000000..7507442fd --- /dev/null +++ b/src/man/kas_create.1 @@ -0,0 +1,107 @@ +kas create AFS Commands kas create + + +NAME + + kas create -- create an entry in the Authentication + + Database. + + + kas create -name [-initial_password + ] + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas c -na [-i ] + [-a ] [-p ] + [-c ] [-s ] [-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 diff --git a/src/man/kas_debuginfo.1 b/src/man/kas_debuginfo.1 new file mode 100644 index 000000000..7aecfe704 --- /dev/null +++ b/src/man/kas_debuginfo.1 @@ -0,0 +1,88 @@ +kas debuginfo AFS Commands kas debuginfo + + +NAME + + kas debuginfo -- produce debugging trace for the + + Authentication Server. + + + kas debuginfo [-hostname ] + [-admin_username ] + [-password_for_admin ] [-cell ] + + + [-servers ] + [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas deb [-ho ] + [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_delete.1 b/src/man/kas_delete.1 new file mode 100644 index 000000000..44d2a1fee --- /dev/null +++ b/src/man/kas_delete.1 @@ -0,0 +1,97 @@ +kas delete AFS Commands kas delete + + +NAME + + kas delete -- delete entry from the Authentication + + Database. + + + kas delete -name + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas del -na [-a ] + [-p ] [-c ] + + + [-s ] [-no] [-h] + + kas rm -na [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_examine.1 b/src/man/kas_examine.1 new file mode 100644 index 000000000..d31c5a533 --- /dev/null +++ b/src/man/kas_examine.1 @@ -0,0 +1,220 @@ +kas examine AFS Commands kas examine + + +NAME + + kas examine -- display information from an Authentication + + Database entry. + + + kas examine -name + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas e -na [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_forgetticket.1 b/src/man/kas_forgetticket.1 new file mode 100644 index 000000000..23a173310 --- /dev/null +++ b/src/man/kas_forgetticket.1 @@ -0,0 +1,57 @@ +kas forgetticket AFS Commands kas forgetticket + + +NAME + + kas forgetticket -- discard all tickets for the issuer. + + + kas forgetticket [-name ] [-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 diff --git a/src/man/kas_getpassword.1 b/src/man/kas_getpassword.1 new file mode 100644 index 000000000..7e207243c --- /dev/null +++ b/src/man/kas_getpassword.1 @@ -0,0 +1,80 @@ +kas getpassword AFS Commands kas getpassword + + +NAME + + kas getpassword -- display octal key from an Authentication + + Database entry. + + + kas getpassword -name [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas getp -n [-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 diff --git a/src/man/kas_getrandomkey.1 b/src/man/kas_getrandomkey.1 new file mode 100644 index 000000000..7098c0852 --- /dev/null +++ b/src/man/kas_getrandomkey.1 @@ -0,0 +1,102 @@ +kas getrandomkey AFS Commands kas getrandomkey + + +NAME + + kas getrandomkey -- generate an encryption key at random. + + + kas getrandomkey + [-admin_username ] + [-password_for_admin ] [-cell ] + + + [-servers ] + [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas getr [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_getticket.1 b/src/man/kas_getticket.1 new file mode 100644 index 000000000..97cc40248 --- /dev/null +++ b/src/man/kas_getticket.1 @@ -0,0 +1,101 @@ +kas getticket AFS Commands kas getticket + + +NAME + + kas getticket -- create a ticket valid for the specified + + server. + + + kas getticket -name + [-admin_username ] + [-password_for_admin ] [-cell ] + + + [-servers ] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas gett -na [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_help.1 b/src/man/kas_help.1 new file mode 100644 index 000000000..edc07d15e --- /dev/null +++ b/src/man/kas_help.1 @@ -0,0 +1,82 @@ +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] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + kas h [-t ] [-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 [-new_passwo + ] [-kvno ] + [-admin_username ] [-cell ] + + + [-servers ] [- + +PRIVILEGE REQUIRED + + None. No password will be prompted for. + +MORE INFORMATION + + kas apropos diff --git a/src/man/kas_interactive.1 b/src/man/kas_interactive.1 new file mode 100644 index 000000000..4688e2fc7 --- /dev/null +++ b/src/man/kas_interactive.1 @@ -0,0 +1,168 @@ +kas interactive AFS Commands kas interactive + + +NAME + + kas interactive -- enter interactive mode for + + Authentication Server. + + + kas interactive + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] [-noauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas i [-a ] [-p + ] + [-c ] [-s ] + [-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 diff --git a/src/man/kas_list.1 b/src/man/kas_list.1 new file mode 100644 index 000000000..4b74b7ea8 --- /dev/null +++ b/src/man/kas_list.1 @@ -0,0 +1,88 @@ +kas list AFS Commands kas list + + +NAME + + kas list -- list all entries in the Authentication + + Database. + + + kas list [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] + [-noauth] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas ls [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_listtickets.1 b/src/man/kas_listtickets.1 new file mode 100644 index 000000000..9525ae5ed --- /dev/null +++ b/src/man/kas_listtickets.1 @@ -0,0 +1,80 @@ +kas listtickets AFS Commands kas listtickets + + +NAME + + kas listtickets -- list all tickets (tokens) for issuer. + + + kas listtickets [-name ] [-long] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas listt [-n ] [-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 diff --git a/src/man/kas_noauthentication.1 b/src/man/kas_noauthentication.1 new file mode 100644 index 000000000..5bd60459e --- /dev/null +++ b/src/man/kas_noauthentication.1 @@ -0,0 +1,62 @@ +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 diff --git a/src/man/kas_quit.1 b/src/man/kas_quit.1 new file mode 100644 index 000000000..d036561f2 --- /dev/null +++ b/src/man/kas_quit.1 @@ -0,0 +1,46 @@ +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 diff --git a/src/man/kas_setfields.1 b/src/man/kas_setfields.1 new file mode 100644 index 000000000..852bd3c42 --- /dev/null +++ b/src/man/kas_setfields.1 @@ -0,0 +1,190 @@ +kas setfields AFS Commands kas setfields + + +NAME + + kas setfields -- set various flags, expiration date and + + ticket lifetime for Authentication + Database entry. + + + kas setfields -name + [-flags ] + [-expiration ] + [-lifetime ] + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] + [-noauth] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas sf -na [-f ] + [-e ] + [-l ] + [-ad ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_setkey.1 b/src/man/kas_setkey.1 new file mode 100644 index 000000000..4f003ea24 --- /dev/null +++ b/src/man/kas_setkey.1 @@ -0,0 +1,159 @@ +kas setkey AFS Commands kas setkey + + +NAME + + kas setkey -- insert octal key directly into key field of + + Database entry. + + + kas setkey -name -new_key [-kvno ] + [-admin_username ] + [-password_for_admin ] [-cell ] + + + [-servers ] + [-noauth] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas setk -na -ne + [-k ] + [-a ] [-p ] + [-c ] [-s ] [-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 diff --git a/src/man/kas_setpassword.1 b/src/man/kas_setpassword.1 new file mode 100644 index 000000000..ba14c8c6e --- /dev/null +++ b/src/man/kas_setpassword.1 @@ -0,0 +1,137 @@ +kas setpassword AFS Commands kas setpassword + + +NAME + + kas setpassword -- change key field in Database entry. + + + kas setpassword -name + [-new_password ] + [-kvno ] + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] + [-noauth] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas sp -na [-ne ] + [-k ] + [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_statistics.1 b/src/man/kas_statistics.1 new file mode 100644 index 000000000..b4ae54770 --- /dev/null +++ b/src/man/kas_statistics.1 @@ -0,0 +1,124 @@ +kas statistics AFS Commands kas statistics + + +NAME + + kas statistics -- display statistics from one + + Authentication Server process. + + + kas statistics + [-admin_username ] + [-password_for_admin ] [-cell ] + [-servers ] + [-noauth] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas sta [-a ] + [-p ] [-c ] + + + [-s ] [-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 diff --git a/src/man/kas_stringtokey.1 b/src/man/kas_stringtokey.1 new file mode 100644 index 000000000..806d4c598 --- /dev/null +++ b/src/man/kas_stringtokey.1 @@ -0,0 +1,70 @@ +kas stringtokey AFS Commands kas stringtokey + + +NAME + + kas stringtokey -- convert a character string into an octal + + string. + + + kas stringtokey -string [-cell ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kas str -s [-c ] [-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 diff --git a/src/man/klog.1 b/src/man/klog.1 new file mode 100644 index 000000000..e329a3bc2 --- /dev/null +++ b/src/man/klog.1 @@ -0,0 +1,319 @@ +klog AFS Commands klog + + +NAME + + klog -- authenticate with Authentication Server to obtain + + token. + + + klog [-x] [-principal ] [-password ] + [-tmp] [-cell ] [-servers ] + [-pipe] [-lifetime ] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + klog [-x] [-pr ] [-pa ] [-t] + [-c ] + + + [-s ] [-pi] + [-l ] [-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: + + -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: + + 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 diff --git a/src/man/knfs.1 b/src/man/knfs.1 new file mode 100644 index 000000000..cace24484 --- /dev/null +++ b/src/man/knfs.1 @@ -0,0 +1,178 @@ +knfs AFS Commands knfs + + +NAME + + knfs -- enable authenticated access to AFS from non- + + supported NFS client using NFS/AFS + Translator. + + + knfs -host [-id ] + [-unlog] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + knfs [-ho ] [-i ] [-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 diff --git a/src/man/kpasswd.1 b/src/man/kpasswd.1 new file mode 100644 index 000000000..acbccb7c1 --- /dev/null +++ b/src/man/kpasswd.1 @@ -0,0 +1,151 @@ +kpasswd AFS Commands kpasswd + + +NAME + + kpasswd -- change password in Authentication Database. + + + kpasswd [-x] [-principal ] + [-password ] + [-newpassword ] [-cell ] + + + [-servers ] [-pipe] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + kpasswd [-x] [-pr ] [-pa ] + [-n ] [-c ] [-s ] + [-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: + + -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): + + -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 diff --git a/src/man/package.1 b/src/man/package.1 new file mode 100644 index 000000000..92ae63e69 --- /dev/null +++ b/src/man/package.1 @@ -0,0 +1,926 @@ +package AFS Commands package + + +NAME + + package -- configure local disk. + + + package [-config ] + [-fullconfig OR stdin for + standard input] + [-overwrite] [-noaction] [-silent] [-verbose] + [-rebootfiles] + [-debug] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + package [-c ] + [-f 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 + + +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 + + +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[] + +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[] [ + ] + +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[] [ + ] + +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 [ ] + +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 %define + +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 , and + 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 + + + [%else [] + + + ] %endif + +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 + + + [%else [] + + + ] %endif + +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 + +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 + +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 diff --git a/src/man/pagsh.1 b/src/man/pagsh.1 new file mode 100644 index 000000000..1fb63d455 --- /dev/null +++ b/src/man/pagsh.1 @@ -0,0 +1,85 @@ +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) diff --git a/src/man/runntp.1 b/src/man/runntp.1 new file mode 100644 index 000000000..49c039915 --- /dev/null +++ b/src/man/runntp.1 @@ -0,0 +1,117 @@ +runntp AFS Commands runntp + + +NAME + + runntp -- initialize Network Time Protocol Daemon. + + + /usr/afs/bin/runntp [-localclock] [-precision ] + + + [-logfile ] [ ] + +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 diff --git a/src/man/salvager.1 b/src/man/salvager.1 new file mode 100644 index 000000000..3db7fa492 --- /dev/null +++ b/src/man/salvager.1 @@ -0,0 +1,101 @@ +salvager AFS Commands salvager + + +NAME + + salvager -- initialize Salvager in BosConfig or manually. + + + /usr/afs/bin/salvager [-f] [-o] [ + []] + +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 diff --git a/src/man/scout.1 b/src/man/scout.1 new file mode 100644 index 000000000..642fd91e1 --- /dev/null +++ b/src/man/scout.1 @@ -0,0 +1,363 @@ +scout AFS Commands scout + + +NAME + + scout -- monitor File Server process on one or more file + + server machines. + + + + + scout -server + [-basename ] + [-frequency ] [-host] + + + [-attention ] + [-debug ] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + scout -s + [-b ] + [-f ] [-ho] + + + [-a ] + [-d ] [-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 . 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 . 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 . 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 . + 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 %. 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 . 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. diff --git a/src/man/tokens.1 b/src/man/tokens.1 new file mode 100644 index 000000000..61b51761a --- /dev/null +++ b/src/man/tokens.1 @@ -0,0 +1,85 @@ +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 diff --git a/src/man/unlog.1 b/src/man/unlog.1 new file mode 100644 index 000000000..d8b11b1e1 --- /dev/null +++ b/src/man/unlog.1 @@ -0,0 +1,70 @@ +unlog AFS Commands unlog + + +NAME + + unlog -- discard all tokens. + + + + + unlog [ ] [-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 diff --git a/src/man/upclient.1 b/src/man/upclient.1 new file mode 100644 index 000000000..10a2c6f7f --- /dev/null +++ b/src/man/upclient.1 @@ -0,0 +1,182 @@ +upclient AFS Commands upclient + + +NAME + + upclient -- initialize client portion of Update Server. + + + /usr/afs/bin/upclient [-t ] [-clear] [-crypt] + +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 diff --git a/src/man/upserver.1 b/src/man/upserver.1 new file mode 100644 index 000000000..857eb336a --- /dev/null +++ b/src/man/upserver.1 @@ -0,0 +1,107 @@ +upserver AFS Commands upserver + + +NAME + + upserver -- initialize server portion of Update Server. + + + + + + /usr/afs/bin/upserver [ ] [-crypt ] + + + [-clear ] + +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 diff --git a/src/man/uss.1 b/src/man/uss.1 new file mode 100644 index 000000000..6d5846d52 --- /dev/null +++ b/src/man/uss.1 @@ -0,0 +1,79 @@ + 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 ] + + 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 ] + + 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. diff --git a/src/man/uss_add.1 b/src/man/uss_add.1 new file mode 100644 index 000000000..a3d81bb8f --- /dev/null +++ b/src/man/uss_add.1 @@ -0,0 +1,286 @@ +uss add AFS Commands uss add + + +NAME + + uss add -- create user account. + + + uss add -user [-realname ] + [-pass ] [-server ] + [-partition ] + [-mount ] + [-uid ] + [-template ] + + + [-verbose] [-var ] + [-cell ] [-admin ] + [-dryrun] [-overwrite] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + uss ad -us [-r ] + [-pas ] [-s ] + [-par ] + [-m ] [-ui ] + [-t ] [-ve] [-va ] + [-c ] [-a ] [-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 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 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. diff --git a/src/man/uss_apropos.1 b/src/man/uss_apropos.1 new file mode 100644 index 000000000..b8cc3458c --- /dev/null +++ b/src/man/uss_apropos.1 @@ -0,0 +1,59 @@ +uss apropos AFS Commands uss apropos + + +NAME + + uss apropos -- show each help entry containing keyword. + + + uss apropos -topic [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + uss ap -t [-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 diff --git a/src/man/uss_bulk.1 b/src/man/uss_bulk.1 new file mode 100644 index 000000000..c1f1d6bce --- /dev/null +++ b/src/man/uss_bulk.1 @@ -0,0 +1,325 @@ +uss bulk AFS Commands uss bulk + + +NAME + + uss bulk -- execute multiple uss commands. + + + uss bulk -file [-template ] + [-verbose] [-cell ] + [-admin ] [-dryrun] + [-overwrite] + [-help] + + uss b -f [-t ] [-v] [-c ] + [-a ] [-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 [:][:][:][:][:{ | :: | : + . . . . et cetera through. . . . + | ::::::::: + [:{savevolume | delvolume | }] + + The exec line + + This line causes the indicated UNIX shell command to be + executed. Its format is + + exec + + 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 , , and + are empty (between a and marketing on the first example + line) since their corresponding variables do not appear in + the template file. The 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 diff --git a/src/man/uss_d_line.1 b/src/man/uss_d_line.1 new file mode 100644 index 000000000..d841ce2a1 --- /dev/null +++ b/src/man/uss_d_line.1 @@ -0,0 +1,116 @@ +Template "D" line AFS Commands Template "D" line + + +NAME + + Template "D" line -- create a directory. + + + D + +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 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 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 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 diff --git a/src/man/uss_delete.1 b/src/man/uss_delete.1 new file mode 100644 index 000000000..fec1f96d9 --- /dev/null +++ b/src/man/uss_delete.1 @@ -0,0 +1,98 @@ +uss delete AFS Commands uss delete + + +NAME + + uss delete -- delete user account from system. + + + uss delete -user + -mountpoint [-savevolume] + [-verbose] [-cell ] + [-admin ] [-dryrun] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + uss d -u -m + [-s] [-v] [-c ] + [-a ] [-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. diff --git a/src/man/uss_e_line.1 b/src/man/uss_e_line.1 new file mode 100644 index 000000000..586b06b16 --- /dev/null +++ b/src/man/uss_e_line.1 @@ -0,0 +1,88 @@ +Template "E" line AFS Commands Template "E" line + + +NAME + + Template "E" line -- create a single-line file. + + + E "" + +DESCRIPTION + + Creates a file anywhere in the file system by echoing what + appears in the 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 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 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 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 + 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 diff --git a/src/man/uss_f_line.1 b/src/man/uss_f_line.1 new file mode 100644 index 000000000..a6bb04c37 --- /dev/null +++ b/src/man/uss_f_line.1 @@ -0,0 +1,82 @@ +Template "F" line AFS Commands Template "F" line + + +NAME + + Template "F" line -- create a file by copying a prototype. + + + F + +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 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 + 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 diff --git a/src/man/uss_g_line.1 b/src/man/uss_g_line.1 new file mode 100644 index 000000000..f367efa15 --- /dev/null +++ b/src/man/uss_g_line.1 @@ -0,0 +1,78 @@ +Template "G" line AFS Commands Template "G" line + + +NAME + + Template "G" line -- define directory for even distribution + + of home directories. + + + G + +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 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 + 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 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 field would specify + simply + + $AUTO/$USER diff --git a/src/man/uss_help.1 b/src/man/uss_help.1 new file mode 100644 index 000000000..881aa6b24 --- /dev/null +++ b/src/man/uss_help.1 @@ -0,0 +1,77 @@ +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] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + uss h [-t ] [-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 [-template ] [-verbose] [-cell ] [-dryr + [-help] + +PRIVILEGE REQUIRED + + None. + +MORE INFORMATION + + uss apropos diff --git a/src/man/uss_l_line.1 b/src/man/uss_l_line.1 new file mode 100644 index 000000000..543359162 --- /dev/null +++ b/src/man/uss_l_line.1 @@ -0,0 +1,50 @@ +Template "L" line AFS Commands Template "L" line + + +NAME + + Template "L" line -- create hard link. + + + L + +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 diff --git a/src/man/uss_s_line.1 b/src/man/uss_s_line.1 new file mode 100644 index 000000000..aaa9dec85 --- /dev/null +++ b/src/man/uss_s_line.1 @@ -0,0 +1,46 @@ +Template "S" line AFS Commands Template "S" line + + +NAME + + Template "S" line -- create symbolic link. + + + S + +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 diff --git a/src/man/uss_v_line.1 b/src/man/uss_v_line.1 new file mode 100644 index 000000000..65f3c7f00 --- /dev/null +++ b/src/man/uss_v_line.1 @@ -0,0 +1,145 @@ +Template "V" line AFS Commands Template "V" line + + +NAME + + Template "V" line -- create a volume. + + + V + + + +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 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 + 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 diff --git a/src/man/uss_x_line.1 b/src/man/uss_x_line.1 new file mode 100644 index 000000000..cb943c1da --- /dev/null +++ b/src/man/uss_x_line.1 @@ -0,0 +1,44 @@ +Template "X" line AFS Commands Template "X" line + + +NAME + + Template "X" line -- execute command. + + + X + +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 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.$ diff --git a/src/man/vldb_convert.1 b/src/man/vldb_convert.1 new file mode 100644 index 000000000..7a1ff8145 --- /dev/null +++ b/src/man/vldb_convert.1 @@ -0,0 +1,264 @@ +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 ] [-from + ] + [-path ] [-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 ] [-f ] + [-p ] [-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. diff --git a/src/man/vos.1 b/src/man/vos.1 new file mode 100644 index 000000000..36aab7da6 --- /dev/null +++ b/src/man/vos.1 @@ -0,0 +1,322 @@ + 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 ] + + 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. diff --git a/src/man/vos_addsite.1 b/src/man/vos_addsite.1 new file mode 100644 index 000000000..00c7dc130 --- /dev/null +++ b/src/man/vos_addsite.1 @@ -0,0 +1,108 @@ +vos addsite AFS Commands vos addsite + + +NAME + + vos addsite -- add definition of ReadOnly site to VLDB + + entry. + + + vos addsite -server + -partition + -id [-cell ] [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos ad -s -p + -i [-c ] [-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 diff --git a/src/man/vos_apropos.1 b/src/man/vos_apropos.1 new file mode 100644 index 000000000..c536ec916 --- /dev/null +++ b/src/man/vos_apropos.1 @@ -0,0 +1,64 @@ +vos apropos AFS Commands vos apropos + + +NAME + + vos apropos -- show each help entry containing keyword. + + + vos apropos -topic [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos ap -t [-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 diff --git a/src/man/vos_backup.1 b/src/man/vos_backup.1 new file mode 100644 index 000000000..2b672c6fc --- /dev/null +++ b/src/man/vos_backup.1 @@ -0,0 +1,72 @@ +vos backup AFS Commands vos backup + + +NAME + + vos backup -- create Backup volume version of one ReadWrite + + volume. + + + vos backup -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos backup -i [-c ] [-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 diff --git a/src/man/vos_backupsys.1 b/src/man/vos_backupsys.1 new file mode 100644 index 000000000..64d90c84b --- /dev/null +++ b/src/man/vos_backupsys.1 @@ -0,0 +1,155 @@ +vos backupsys AFS Commands vos backupsys + + +NAME + + vos backupsys -- create Backup volume version of all + + indicated ReadWrite volumes. + + + vos backupsys [-prefix ] + [-server ] [-partition ] + [-cell ] [-noauth] [-localauth] [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos backups [-pr ] [-s + ] + [-pa ] [-c ] [-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 diff --git a/src/man/vos_create.1 b/src/man/vos_create.1 new file mode 100644 index 000000000..3db49f465 --- /dev/null +++ b/src/man/vos_create.1 @@ -0,0 +1,115 @@ +vos create AFS Commands vos create + + +NAME + + vos create -- create (empty) ReadWrite volume and + + associated VLDB entry. + + + vos create -server -partition -name [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos c -s -p -na + [-c ] [-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. diff --git a/src/man/vos_delentry.1 b/src/man/vos_delentry.1 new file mode 100644 index 000000000..e1ceb3226 --- /dev/null +++ b/src/man/vos_delentry.1 @@ -0,0 +1,159 @@ +vos delentry AFS Commands vos delentry + + +NAME + + vos delentry -- remove specified entry from VLDB. + + + vos delentry -id + [-prefix ] + [-server ] [-partition ] + [-cell ] [-noauth] [-localauth] [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos de -i + [-pr ] + [-s ] [-pa ] [-c ] + [-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 diff --git a/src/man/vos_dump.1 b/src/man/vos_dump.1 new file mode 100644 index 000000000..0d32c20dd --- /dev/null +++ b/src/man/vos_dump.1 @@ -0,0 +1,126 @@ +vos dump AFS Commands vos dump + + +NAME + + vos dump -- convert volume into ASCII format and place in a + + file. + + + vos dump -id -time + [-file ] [-cell ] [-noauth] + [-localauth] + [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos du -i -t [-f + ] + [-c ] [-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 diff --git a/src/man/vos_examine.1 b/src/man/vos_examine.1 new file mode 100644 index 000000000..af22c9456 --- /dev/null +++ b/src/man/vos_examine.1 @@ -0,0 +1,177 @@ +vos examine AFS Commands vos examine + + +NAME + + vos examine -- show information from volume header and VLDB + + about one volume. + + + vos examine -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos e -i [-c ] [-n] [-l] + [-v] [-h] + + vos volinfo -i [-c ] [-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 diff --git a/src/man/vos_help.1 b/src/man/vos_help.1 new file mode 100644 index 000000000..8e129f6e0 --- /dev/null +++ b/src/man/vos_help.1 @@ -0,0 +1,77 @@ +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] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + + + vos h [-t ] [-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 -partition + -name [-cell ] + [-noauth] [-localauth] [-verbose] [-help] + +PRIVILEGE REQUIRED + + None. + +MORE INFORMATION + + vos apropos diff --git a/src/man/vos_listpart.1 b/src/man/vos_listpart.1 new file mode 100644 index 000000000..c63aaaf48 --- /dev/null +++ b/src/man/vos_listpart.1 @@ -0,0 +1,83 @@ +vos listpart AFS Commands vos listpart + + +NAME + + vos listpart -- show all AFS partitions on specified file + + server machine. + + + vos listpart -server [-cell ] + [-noauth] [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos listp -s [-c ] [-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 diff --git a/src/man/vos_listvldb.1 b/src/man/vos_listvldb.1 new file mode 100644 index 000000000..bc6cacc0d --- /dev/null +++ b/src/man/vos_listvldb.1 @@ -0,0 +1,207 @@ +vos listvldb AFS Commands vos listvldb + + +NAME + + vos listvldb -- show information from the VLDB. + + + vos listvldb [-name ] [-server ] [-partition ] [-locked] + [-quiet] + [-cell ] [-noauth] [-localauth] [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos listvl [-na ] [-s ] + [-p ] [-lock] [-q] [-c ] [-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 diff --git a/src/man/vos_listvol.1 b/src/man/vos_listvol.1 new file mode 100644 index 000000000..572218eb4 --- /dev/null +++ b/src/man/vos_listvol.1 @@ -0,0 +1,225 @@ +vos listvol AFS Commands vos listvol + + +NAME + + vos listvol -- show information from volume header(s). + + + vos listvol -server [-partition ] [-fast] + [-long] [-quiet] [-cell ] [-noauth] + [-localauth] + [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos listvo -s [-p ] [-f] + [-lon] [-q] + [-c ] [-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 diff --git a/src/man/vos_lock.1 b/src/man/vos_lock.1 new file mode 100644 index 000000000..b70dabe06 --- /dev/null +++ b/src/man/vos_lock.1 @@ -0,0 +1,74 @@ +vos lock AFS Commands vos lock + + +NAME + + vos lock -- lock a volume entry in the VLDB. + + + vos lock -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos lo -i [-c ] [-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 diff --git a/src/man/vos_move.1 b/src/man/vos_move.1 new file mode 100644 index 000000000..caaae4851 --- /dev/null +++ b/src/man/vos_move.1 @@ -0,0 +1,125 @@ +vos move AFS Commands vos move + + +NAME + + vos move -- move volume to specified other site. + + + vos move -id + -fromserver + -frompartition + -toserver + -topartition + [-cell ] [-noauth] [-verbose] [-localauth] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos m -i -froms + -fromp -tos + -top [-c ] [-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 diff --git a/src/man/vos_partinfo.1 b/src/man/vos_partinfo.1 new file mode 100644 index 000000000..e643d2582 --- /dev/null +++ b/src/man/vos_partinfo.1 @@ -0,0 +1,93 @@ +vos partinfo AFS Commands vos partinfo + + +NAME + + vos partinfo -- show available and total space on specified + + partition(s). + + + vos partinfo -server [-partition ] [-cell ] [-noauth] [-localauth] + [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos p -s [-p ] [-c ] + [-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 diff --git a/src/man/vos_release.1 b/src/man/vos_release.1 new file mode 100644 index 000000000..60447b552 --- /dev/null +++ b/src/man/vos_release.1 @@ -0,0 +1,223 @@ +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 [-f] [-cell ] [-noauth] [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos rel -i [-f] [-c ] + [-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 diff --git a/src/man/vos_remove.1 b/src/man/vos_remove.1 new file mode 100644 index 000000000..e545b612d --- /dev/null +++ b/src/man/vos_remove.1 @@ -0,0 +1,124 @@ +vos remove AFS Commands vos remove + + +NAME + + vos remove -- remove specified volume from a site. + + + vos remove -server -partition -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos remo -s -p + -i [-c ] [-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 diff --git a/src/man/vos_remsite.1 b/src/man/vos_remsite.1 new file mode 100644 index 000000000..3f00e4eeb --- /dev/null +++ b/src/man/vos_remsite.1 @@ -0,0 +1,100 @@ +vos remsite AFS Commands vos remsite + + +NAME + + vos remsite -- remove ReadOnly site definition from a VLDB + + entry. + + + vos remsite -server -partition -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos rems -s -p + -i [-c ] [-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 diff --git a/src/man/vos_rename.1 b/src/man/vos_rename.1 new file mode 100644 index 000000000..5bd0333ce --- /dev/null +++ b/src/man/vos_rename.1 @@ -0,0 +1,70 @@ +vos rename AFS Commands vos rename + + +NAME + + vos rename -- rename a volume. + + + vos rename -oldname + -newname [-cell ] + [-noauth] [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos ren -o -ne [-c + ] + [-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 diff --git a/src/man/vos_restore.1 b/src/man/vos_restore.1 new file mode 100644 index 000000000..cbd91ba32 --- /dev/null +++ b/src/man/vos_restore.1 @@ -0,0 +1,123 @@ +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 -partition -name [-file ] [-id ] [-cell ] + [-noauth] [-localauth] + [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos res -s -p + -na [-f ] [-i + ] + [-c ] [-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 diff --git a/src/man/vos_status.1 b/src/man/vos_status.1 new file mode 100644 index 000000000..e2f706846 --- /dev/null +++ b/src/man/vos_status.1 @@ -0,0 +1,137 @@ +vos status AFS Commands vos status + + +NAME + + vos status -- report activity of Volume Server. + + + vos status -server [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos st -s [-c ] [-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 diff --git a/src/man/vos_syncserv.1 b/src/man/vos_syncserv.1 new file mode 100644 index 000000000..bb12c69f0 --- /dev/null +++ b/src/man/vos_syncserv.1 @@ -0,0 +1,105 @@ +vos syncserv AFS Commands vos syncserv + + +NAME + + vos syncserv -- synchronize VLDB entries that mention a + + given site with volume headers. + + + vos syncserv -server [-partition ] [-cell ] [-noauth] [-localauth] + [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos syncs -s [-p ] + [-c ] [-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 diff --git a/src/man/vos_syncvldb.1 b/src/man/vos_syncvldb.1 new file mode 100644 index 000000000..0d103b0de --- /dev/null +++ b/src/man/vos_syncvldb.1 @@ -0,0 +1,105 @@ +vos syncvldb AFS Commands vos syncvldb + + +NAME + + vos syncvldb -- synchronize VLDB entry with volume headers + + at given site. + + + vos syncvldb -server [-partition ] [-cell ] [-noauth] [-localauth] + [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos syncv -s [-p ] [-c + ] + [-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 diff --git a/src/man/vos_unlock.1 b/src/man/vos_unlock.1 new file mode 100644 index 000000000..d6dc7d4e6 --- /dev/null +++ b/src/man/vos_unlock.1 @@ -0,0 +1,78 @@ +vos unlock AFS Commands vos unlock + + +NAME + + vos unlock -- unlock an entry in the VLDB. + + + vos unlock -id [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos unlock -i [-c ] [-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 diff --git a/src/man/vos_unlockvldb.1 b/src/man/vos_unlockvldb.1 new file mode 100644 index 000000000..059f47aab --- /dev/null +++ b/src/man/vos_unlockvldb.1 @@ -0,0 +1,115 @@ +vos unlockvldb AFS Commands vos unlockvldb + + +NAME + + vos unlockvldb -- unlock all specified locked entries in + + the VLDB. + + + vos unlockvldb [-server ] [-partition + ] + [-cell ] [-noauth] [-localauth] [-verbose] + [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos unlockv [-s ] [-p ] + [-c ] [-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 diff --git a/src/man/vos_zap.1 b/src/man/vos_zap.1 new file mode 100644 index 000000000..f3e6ea268 --- /dev/null +++ b/src/man/vos_zap.1 @@ -0,0 +1,128 @@ +vos zap AFS Commands vos zap + + +NAME + + vos zap -- remove a volume from its site without writing to + + the VLDB. + + + vos zap -server -partition + -id [-force] [-cell ] + [-noauth] + [-localauth] [-verbose] [-help] + +ACCEPTABLE ABBREVIATIONS/ALIASES + + vos z -s -p -i + [-f] [-c ] [-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