From: Russ Allbery Date: Sat, 29 May 2010 21:45:04 +0000 (-0500) Subject: Comprehensive edit of Admin Guide chapter two (first 20%) X-Git-Tag: openafs-devel-1_5_75~187 X-Git-Url: https://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=7c167febd559de70ec8abd74a34bbc15f44945fd;hp=67e837374649d4def8df6371f104c8b2af928e2a Comprehensive edit of Admin Guide chapter two (first 20%) Update and revise chapter two (Issues in Cell Configuration and Administration) of the Administration Guide for current AFS and current computing concepts. Remove references to an AFS-provided login utility and discuss local login configuration for Kerberos more generically. Further clarify the role of ssh in ensuring the user has access to files in AFS during remote login. Improve the inode and namei discussion slightly. Update the setuid discussion for the new default of disabling setuid for cells and for the known security flaws in enabling setuid. Modernize terminology for DNS around cell naming and remove the descriptions of TLDs. We can now assume our target audience knows this stuff. Move index terms into the appropriate section for what's being indexed in a few more cases. Lots of other, more minor wording changes and updates. Change-Id: Id8b1ace5afca6b8b7b2082a9a0779a4b91c89dcd Reviewed-on: http://gerrit.openafs.org/2065 Reviewed-by: Derrick Brashear Reviewed-by: Jeffrey Altman Tested-by: Jeffrey Altman --- diff --git a/doc/xml/AdminGuide/auagd007.xml b/doc/xml/AdminGuide/auagd007.xml index e4bfa01..5963b4f 100644 --- a/doc/xml/AdminGuide/auagd007.xml +++ b/doc/xml/AdminGuide/auagd007.xml @@ -68,7 +68,7 @@ For directories, AFS ignores the UNIX mode bits. For files, AFS uses only the first set of mode bits (the owner bits) , and their meaning + role="bold">owner bits), and their meaning interacts with permissions on the directory's ACL. See How AFS Interprets the UNIX Mode Bits. @@ -78,7 +78,9 @@ A directory's ACL protects all of the files in a directory in the same manner. To apply a more restrictive set of AFS permissions to certain file, place it in directory with - a different ACL. + a different ACL. If a directory must contain files with + different permissions, use symbolic links to point to files + stored in directories with different ACLs. @@ -108,12 +110,12 @@ - AFS enables users to define the groups of other users. Placing - these groups on ACLs extends the same permissions to a number of - exactly specified users at the same time, which is much more - convenient than placing the individuals on the ACLs directly. See - Administering the Protection - Database. + AFS enables users to create groups and add other users to + those groups. Placing these groups on ACLs extends the same + permissions to a number of exactly specified users at the same time, + which is much more convenient than placing the individuals on the + ACLs directly. See Administering the + Protection Database. There are also system-defined groups, system:anyuser and Just as the AFS filespace is distinct from each machine's local file system, AFS authentication is separate from local - login. This has two practical implications, which are discussed - further in Using an AFS-modified login - Utility. + login. This has two practical implications, which will already be + familiar to users and system administrators who use Kerberos for + authentication. + - To access AFS files, users must both log into the local - machine's UNIX file system and authenticate with the AFS - authentication service. (Logging into the local UNIX file - system is necessary because the AFS filespace is accessed - through the Cache Manager, which resides in the local - machine's kernel.) - - AFS provides a modified login utility for each system - type that accomplishes both local login and AFS authentication - in one step, based on a single password. If you choose not to - use the AFS-modified login utility, your users must login and - authenticate in separate steps, as detailed in the - OpenAFS User Guide. + To access AFS files, users must log into the local + machine as normal, obtain Kerberos tickets, and then obtain + AFS tokens. This process can often be automated through the + system authentication configuration so that the user logs into + the system as normal and obtains Kerberos tickets and AFS + tokens transparently. If you cannot or chose not to configure + the system this way, your users must login and authenticate in + separate steps, as detailed in the OpenAFS User + Guide. Passwords may be stored in two separate places: the - Kerberos Server and, optionally, each machine's local password - file (/etc/passwd or - equivalent) for the UNIX file system. A user's passwords in - the two places can differ if desired, though the resulting - behavior depends on whether and how the cell is using an - AFS-modified login utility. + Kerberos KDC and, optionally, each machine's local user + database (/etc/passwd or + equivalent) for the local system. A user's passwords in the + two places can differ if desired. - + @@ -177,7 +174,8 @@ Commands This section summarizes how AFS modifies the functionality of - some UNIX commands. + some UNIX commands. + chmod command @@ -207,20 +205,20 @@ bits on AFS files. For more information, see Determining if a Client Can Run Setuid Programs. + + - - chown command + + chown command - AFS compared to UNIX - + AFS compared to UNIX + - - commands + + commands - chown (AFS compared to UNIX) - - - + chown (AFS compared to UNIX) + The chown @@ -230,20 +228,20 @@ Only members of the system:administrators group can issue this command on AFS files. + + - - chgrp command + + chgrp command - AFS compared to UNIX - + AFS compared to UNIX + - - commands + + commands - chgrp (AFS compared to UNIX) - - - + chgrp (AFS compared to UNIX) + The chgrp @@ -253,70 +251,57 @@ Only members of the system:administrators can issue this command on AFS files and directories. + + - - groups command + + groups command + AFS compared to UNIX + - AFS compared to UNIX - + + id command + AFS compared to UNIX + - - commands + + commands + groups (AFS compared to UNIX) + - groups (AFS compared to UNIX) - - - + + commands + id (AFS compared to UNIX) + - The groups - command + The groups and id + commands If the user's AFS tokens are associated with a process - authentication group (PAG), the output of this command can - include one or two large numbers. To learn about PAGs, see - Identifying AFS Tokens by + authentication group (PAG), the output of these commands may + include one or two large numbers. These are artificial + groups used by the OpenAFS Cache Manager to track the PAG on + some platforms. Other platforms may use other methods, such + as native kernel support for a PAG or a similar concept, in + which case the large GIDs may not appear. To learn about + PAGs, see Identifying AFS Tokens by PAG. - - - login utility - - AFS compared to UNIX - - - - commands - - login (AFS compared to UNIX) - - - - The login - utility - - - AFS-modified login utilities both log the issuer into - the local file system and authenticate the user with the AFS - authentication service. See Using an - AFS-modified login Utility. - - - ln command + + ln command - AFS compared to UNIX - + AFS compared to UNIX + - - commands + + commands - ln (AFS compared to UNIX) - - - + ln (AFS compared to UNIX) + The ln command @@ -325,40 +310,54 @@ This command cannot create hard links between files in different AFS directories. See Creating Hard Links. + + - - sshd command + + sshd command - AFS compared to UNIX - + AFS compared to UNIX + - - commands + + commands - sshd (AFS compared to UNIX) - - - + sshd (AFS compared to UNIX) + - - The sshd daemon + + ssh command - - The OpenSSH - project provides an sshd daemon that uses the GSSAPI - protocol to pass Kerberos tickets between machines. + AFS compared to UNIX + - - ssh command + + commands - AFS compared to UNIX - + ssh (AFS compared to UNIX) + - - commands + + The sshd daemon and ssh + command - ssh (AFS compared to UNIX) - + + In order for a user to have access to files stored in + AFS, that user needs to have Kerberos tickets and an AFS token + on the system from which they're accessing AFS. This has an + implication for users who log in remotely via protocols such + as Secure Shell (SSH): that log-in process must create local + Kerberos tickets and an AFS token on the system, or the user + will have to separately authenticate to Kerberos and AFS + after logging in. + + The OpenSSH + project provides an SSH client and server that uses + the GSS-API protocol to pass Kerberos tickets between + machines. With a suitable SSH client, this allows users to + delegate their Kerberos tickets to the remote machine, and + that machine to store those tickets and obtain AFS tokens as + part of the log-in process. @@ -371,11 +370,18 @@ - inode-based fileserver + file server machine + inode-based + + + + file server machine + namei-based - namei-based fileserver + namei + definition @@ -413,19 +419,22 @@ The fileserver uses either of two formats for storing data - on disk. The inode format uses a combination of regular files and - extra fields stored in the inode data structures that are normally - reserved for use by the operating system. The namei interface uses - normal file storage and does not use special structures. The - choice of storage formats is chosen at compile time and the two - formats are incompatible. The storage format must be consistent - for the fileserver binaries and all vice partitions on a given - fileserver machine. + on disk. The inode-based format uses a combination of regular + files and extra fields stored in the inode data structures that + are normally reserved for use by the operating system. The namei + format uses normal file storage and does not use special + structures. The choice of storage formats is chosen at compile + time and the two formats are incompatible. The inode format is + only available on certain platforms. The storage format must be + consistent for the fileserver binaries and all vice partitions on + a given file server machine. - This section on fsck advice only applies to the - inode-based fileserver binaries. On servers using namei-based - binaries, the vendor-supplied fsck is required. + + This section on fsck advice only applies to the inode-based + fileserver binaries. On servers using namei-based binaries, the + vendor-supplied fsck can be used as normal. + If you are using AFS fileserver binaries compiled with the inode-based format, never run the standard UNIX Instead, use the version of the fsck program that is included in the AFS - distribution. The OpenAFS Quick Beginnings + distribution. The OpenAFS Quick Start Guide explains how to replace the vendor-supplied fsck program with the AFS version as you install each server machine. @@ -456,16 +465,23 @@ binaries in use on the machine. If you ever accidentally run the standard version of the - program, contact your AFS support provider or refer to the OpenAFS support web page for support options. It is sometimes possible to recover volume data from the lost+found directory. If the data is not recoverabled, then restoring from backup is recommended. - Running the fsck binary supplied by the operating - system vendor on an fileserver using inode-based binaries will - result in data corruption! + + Running the fsck binary supplied by the operating system + vendor on an fileserver using inode-based file storage will result + in data corruption! + + + + + Creating Hard Links hard link @@ -478,10 +494,6 @@ on hard links in AFS - - - - Creating Hard Links AFS does not allow hard links (created with the UNIX ln command) between files that reside in @@ -495,11 +507,15 @@ ln -s command) between elements in two different AFS directories, or even between an element in AFS and one in a machine's local UNIX file system. Do not create a symbolic - link to a file whose name begins with either a number sign + link in AFS to a file whose name begins with either a number sign (#) or a percent sign (%), however. The Cache Manager interprets such links as a mount point to a regular or read/write volume, respectively. + + + + AFS Implements Save on Close fsync system call @@ -518,10 +534,6 @@ system call for files saved on AFS client - - - - AFS Implements Save on Close When an application issues the UNIX close system call on a file, the Cache @@ -542,8 +554,8 @@ file maintained by the File Server. The Cache Manager does sometimes write this type of modified data from the cache to the File Server without receiving the close or - fsync system call, for example if - it needs to free cache chunks for new data. However, it is not + fsync system call, such as when it + needs to free cache chunks for new data. However, it is not generally possible to predict when the Cache Manager transfers modified data to the File Server in this way. @@ -567,21 +579,36 @@ restrictions on - Set the UNIX setuid bit only for the local superuser root; this does not present an automatic - security risk: the local superuser has no special privilege in AFS, - but only in the local machine's UNIX file system and kernel. + The UNIX setuid bit is ignored by default for programs run + from AFS, but can be enabled by the system administrator on a client + machine. The fs setcell command + determines whether setuid programs that originate in a particular + cell can run on a given client machine. Running setuid binaries from + AFS poses a security risk due to weaknesses in the integrity checks + of the AFS protocol and should normally not be permitted. See Determining if a Client Can Run Setuid + Programs. + + Set the UNIX setuid bit only for files whose owner is UID 0 + (the local superuser root). This + does not present an automatic security risk: the local superuser has + no special privilege in AFS, but only in the local machine's UNIX + file system and kernel. Setting the UNIX setuid bit for files owned + with a different UID will have unpredictable resuilts, since that + UID will be interpreted as possibly different users on each AFS + client machine. Any file can be marked with the setuid bit, but only members of the system:administrators group can issue the chown system call or - the chown command. + the chown command, or issue the + chmod system call or the chmod command to set the setuid bit. + + - The fs setcell command - determines whether setuid programs that originate in a foreign cell - can run on a given client machine. See Determining if a Client Can Run Setuid - Programs. + + Choosing a Cell Name cell @@ -610,17 +637,12 @@ conventions for cell name - - - - - Choosing a Cell Name This section explains how to choose a cell name and explains why choosing an appropriate cell name is important. Your cell name must distinguish your cell from all others in the - AFS global namespace. By conventions, the cell name is the second + AFS global namespace. By convention, the cell name is the second element in any AFS pathname; therefore, a unique cell name guarantees that every AFS pathname uniquely identifies a file, even if cells use the same directory names at lower levels in their local AFS @@ -630,21 +652,23 @@ /afs/abc.com/usr/pat and /afs/stateu.edu/usr/pat. - By convention, cell names follow the ARPA Internet Domain System - conventions for site names. If you are already an Internet site, then - it is simplest to choose your Internet domain name as the - cellname. + By convention, cell names follow the Domain Name System (DNS) + conventions for domain names. If you are already an Internet site, + then it is simplest and strongly recommended to choose your Internet + domain name as the cell name. If you are not an Internet site, it is best to choose a unique - Internet-style name, particularly if you plan to connect to the - Internet in the future. There are a few constraints on AFS cell names: - + DNS-style name, particularly if you plan to connect to the Internet in + the future. There are a few constraints on AFS cell names: + It can contain as many as 64 characters, but shorter names are better because the cell name frequently is part of machine and file names. If your cell name is long, you can reduce - pathname length by creating a symbolic link to the complete cell - name, at the second level in your file tree. See CellAlias + configuration file on a client machine. See The Second (Cellname) Level. @@ -660,95 +684,32 @@ conventionally separated by periods (see the examples below). - - - It must end in a suffix that indicates the type of - institution it is, or the country in which it is situated. The - following are some of the standard suffixes: - - - .com - - - For businesses and other commercial - organizations. Example: abc.com for the ABC Corporation - cell. - - - - .edu - - - For educational institutions such as - universities. Example: stateu.edu for the State - University cell. - - - - .gov - - - For United States government institutions. - - - - - .mil - - - For United States military installations. - - - - - - + - - Internet - - Domain Registrar - - - - Domain Registrar - - - Other suffixes are available if none of these are - appropriate. Contact a domain registrar to purchase a domain name for - your cell. - - - setting - - cell name - - - - cell - - name - - setting - - - - server machine + + How to Set the Cell Name - setting home cell - + + setting + cell name + - - client machine + + cell + name + setting + - setting home cell - + + server machine + setting home cell + - - How to Set the Cell Name + + client machine + setting home cell + The cell name is recorded in two files on the local disk of each file server and client machine. Among other functions, these @@ -762,7 +723,7 @@ name are the /usr/afs/etc/ThisCell and /usr/afs/etc/CellServDB files. As described more explicitly in the OpenAFS Quick - Beginnings, you set the cell name in both by issuing the + Start Guide, you set the cell name in both by issuing the bos setcellname command on the first file server machine you install in your cell. It is not usually necessary to issue the command again. If you use the Update @@ -770,7 +731,7 @@ role="bold">ThisCell and CellServDB files to additional server machines that you install. If you do not use the Update Server, the - OpenAFS Quick Beginnings explains how to copy + OpenAFS Quick Start Guide explains how to copy the files manually. For client machines, the two files that record the cell name @@ -782,11 +743,12 @@ Server Machines for details. Change the cell name in these files only when you want to - transfer the machine to a different cell (it can only belong to one - cell at a time). If the machine is a file server, follow the - complete set of instructions in the OpenAFS Quick - Beginnings for configuring a new cell. If the machine is - a client, all you need to do is change the files appropriately and + transfer the machine to a different cell (client machines can only + have one default cell at a time and server machines can only belong + to one cell at a time). If the machine is a file server, follow the + complete set of instructions in the OpenAFS Quick Start + Guide for configuring a new cell. If the machine is a + client, all you need to do is change the files appropriately and reboot the machine. The next section explains further the negative consequences of changing the name of an existing cell. @@ -808,16 +770,15 @@ the cell in which the parent directory of the new mount point resides. + + + + Why Choosing the Appropriate Cell Name is Important ThisCell file (client) - how used by programs - - - - Why Choosing the Appropriate Cell Name is Important Take care to select a cell name that is suitable for long-term use. Changing a cell name later is complicated. An appropriate cell @@ -838,60 +799,53 @@ in each machine's ThisCell file affects the performance of many programs and processes running on the machine. For instance, AFS commands (fs, kas, - pts and vos commands) by default execute in the cell - of the machine on which they are issued. The command interpreters - check the ThisCell file on the - local disk and then contact the database server machines listed in - the CellServDB file for the - indicated cell (the bos commands + role="bold">fs, pts, and + vos commands, for example) by + default execute in the cell of the machine on which they are + issued. The command interpreters check the ThisCell file on the local disk and then + contact the database server machines listed in the CellServDB file or configured in DNS for the + indicated cell. (The bos commands work differently because the issuer always has to name of the - machine on which to run the command). The ThisCell file also determines the cell for - which a user receives an AFS token when he or she logs in to a - machine. This method of converting passwords into - encryption keys means that the same password results in different - keys in different cells. Even if a user uses the same password in - multiple cells, obtaining a user's token from one cell does not - enable unauthorized access to the user's account in another - cell. + machine on which to run the command.) + + The ThisCell file also + normally determines the cell for which a user receives an AFS token + when he or she logs in to a machine. If you change the cell name, you must change the ThisCell and CellServDB files on every server and client - machine. Failure to change them all can prevent login, because the - encryption keys produced by the login utility do not match the keys - stored in the Authentication Database. In addition, many commands - from the AFS suites do not work as expected. - - - participation - - in AFS global namespace - - - - AFS - - global namespace - - - - global namespace - + machine. Failure to change them all will cause many commands from + the AFS suites to not work as expected. Participating in the AFS Global Namespace + + participation + in AFS global namespace + + + + AFS + global namespace + + + + global namespace + + Participating in the AFS global namespace makes your cell's local file tree visible to AFS users in foreign cells and makes other cells' file trees visible to your local users. It makes file sharing across cells just as easy as sharing within a cell. This section outlines the procedures necessary for participating in the global - namespace. + namespace. + Participation in the global namespace is not mandatory. Some cells use AFS primarily to facilitate file @@ -916,8 +870,10 @@ You make your cell visible to others by advertising your - database server machines. See Making - Your Cell Visible to Others. + database server machines and allowing users at other sites to + access your database server and file server machines. See Making Your Cell Visible to + Others. @@ -927,45 +883,38 @@ another. See Making Other Cells Visible in Your Cell. - + - - conventions - - AFS pathnames - - - - AFS - - root directory (/afs) - - on client machine - - - - directories - - /afs - - - - directories + + What the Global Namespace Looks Like - /afs/cellname - + + conventions + AFS pathnames + - - cell + + AFS + root directory (/afs) + on client machine + - name + + directories + /afs + - at second level in file tree - + + directories + /afs/cellname + - - What the Global Namespace Looks Like + + cell + name + at second level in file tree + The AFS global namespace appears the same to all AFS cells that participate in it, because they all agree to follow a small set @@ -987,28 +936,25 @@ depends on how a cell has chosen to arrange its filespace. There are some suggested conventional directories at the third level; see The Third Level. + + + + Making Your Cell Visible to Others cell - making local visible to foreign local cell - making visible to foreign cells foreign cell - making local cell visible - - - - Making Your Cell Visible to Others You make your cell visible to others by advertising your cell name and database server machines. Just like client machines in the @@ -1016,9 +962,9 @@ information to reach your cell's Volume Location (VL) Servers when they need volume and file location information. For authenticated access, foreign clients must be configured with the necessary - Kerberos v5 domain-to-realm mappings and Key Distribution Center - location information for both the local and remote Kerberos v5 - realms. + Kerberos version 5 domain-to-realm mappings and Key Distribution + Center (KDC) location information for both the local and remote + Kerberos version 5 realms. There are two places you can make this information available: