DEVEL15-man-page-cellservdb-extras-20090605
[openafs.git] / doc / man-pages / pod5 / CellServDB.pod
1 =head1 NAME
2
3 CellServDB - Lists the database server machines in AFS cells
4
5 =head1 DESCRIPTION
6
7 There are two versions of the F<CellServDB> file, both of which have the
8 same format.  One version is used by an AFS client and lists all of the
9 database server machines in the local cell and any foreign cell that is to
10 be accessible from the local client machine.  The other version is used on
11 servers and need list only the database servers in the local cell; in some
12 configurations it can be a link to the same file the client uses.
13
14 =head2 Client CellServDB
15
16 Along with AFSDB entries in DNS, the client version of the CellServDB file
17 lists the database server machines in the local cell and any foreign cell
18 that is to be accessible from the local client machine. Database server
19 machines run the Authentication Server (optional), Backup Server
20 (optional), Protection Server, and Volume Location (VL) Server (the
21 B<kaserver>, B<buserver>, B<ptserver>, and B<vlserver>) processes, which
22 maintain the cell's administrative AFS databases.
23
24 The Cache Manager and other processes running on a client machine use the
25 list of a cell's database server machines when performing several common
26 functions, including:
27
28 =over 4
29
30 =item *
31
32 Fetching files. The Cache Manager contacts the VL Server to learn
33 the location of the volume containing a requested file or directory.
34
35 =item *
36
37 Creating, viewing, and manipulating protection groups. The B<pts> command
38 interpreter contacts the Protection Server when users create protection
39 groups or request information from the Protection Database.
40
41 =item *
42
43 Populating the contents of the fake F<root.afs> volume mounted at F</afs>
44 (or the alternative mount point specified in F<cacheinfo>) when B<afsd> is
45 run in C<-dynroot> mode.  The default contents of this directory will
46 match the cells listed in the client F<CellServDB> file.
47
48 =item *
49
50 Authenticating users. Client-side authentication programs (such as an
51 AFS-modified login utility or the B<klog> command interpreter) contact the
52 Authentication Server to obtain a server ticket, which the AFS server
53 processes accept as proof that the user is authenticated. This only
54 applies to AFS cells using the deprecated Authentication Server instead of
55 Kerberos v5 and B<aklog>.
56
57 =back
58
59 The Cache Manager reads the CellServDB file into kernel memory as it
60 initializes, and not again until the machine next reboots or the client
61 service restarts. To enable users on the local machine to continue
62 accessing the cell correctly, update the file whenever a database server
63 machine is added to or removed from a cell. To update the kernel-resident
64 list of database server machines without rebooting, use the B<fs newcell>
65 command.
66
67 If the client attempts to access an AFS cell not listed in F<CellServDB>
68 and B<afsd> was started with the B<-afsdb> option, the Cache Manager will
69 attempt an AFSDB DNS record lookup and dynamically add the database server
70 locations for that cell based on the result of the DNS query.  If the
71 B<-afsdb> option was not used, all AFS cells that will be accessed by a
72 client machine must either be listed in F<CellServDB> or added with the
73 B<fs newcell> command.
74
75 The F<CellServDB> file is in ASCII format and must reside in the
76 F</usr/vice/etc> directory on each AFS client machine. Use a text editor
77 to create and maintain it.
78
79 The client version of the F<CellServDB> file is distinct from the server
80 version, which resides in the F</usr/afs/etc> directory on each AFS server
81 machine. The client version lists the database server machines in every
82 AFS cell that the cell administrator wants the machine's users to be able
83 to access, whereas the server version lists only the local cell's database
84 server machines.
85
86 =head2 Server CellServDB
87
88 The server version of the F<CellServDB> file lists the local cell's
89 database server machines. These machines run the Authentication Server
90 (optional), Backup Server (optional), Protection Server, and Volume
91 Location (VL) Server (the B<kaserver>, B<buserver>, B<ptserver>, and
92 B<vlserver>) processes, which maintain the cell's administrative AFS
93 databases. The initial version of the file is created with the B<bos
94 setcellname> command during the installation of the cell's server machine,
95 which is automatically recorded as the cell's first database server
96 machine. When adding or removing database server machines, be sure to
97 update this file appropriately. It must reside in the F</usr/afs/etc>
98 directory on each AFS server machine. The database server processes,
99 in addition to the usual configuration allowing each to be elected
100 synchronization site and coordinate updates, can be set up as readonly
101 database clone servers. Such servers can never be elected as the
102 synchronization site.
103
104 The database server processes consult the F<CellServDB> file to learn
105 about their peers, with which they must maintain constant connections in
106 order to coordinate replication of changes across the multiple copies of
107 each database. The other AFS server processes consult the file to learn
108 which machines to contact for information from the databases when they
109 need it.
110
111 Although the server F<CellServDB> file is in ASCII format, do not use a
112 text editor to alter it. Instead always use the appropriate commands from
113 the B<bos> command suite:
114
115 =over 4
116
117 =item *
118
119 The B<bos addhost> command to add a machine to the file.
120
121 =item *
122
123 The B<bos listhosts> command to display the list of machines from the
124 file.
125
126 =item *
127
128 The B<bos removehost> command to remove a machine from the file.
129
130 =back
131
132 In cells that use the Update Server to distribute the contents of the
133 F</usr/afs/etc> directory, it is customary to edit only the copy of the
134 file stored on the system control machine. Otherwise, edit the file on
135 each server machine individually. For instructions on adding and removing
136 database server machine, see the I<OpenAFS Quick Start> chapter on
137 installing additional server machines. Updates to the server F<CellServDB>
138 will trigger reloading the cell server configurations automatically in the
139 AFS server processes.
140
141 =head2 CellServDB Format
142
143 Both F<CellServDB> files have the same format:
144
145 =over 4
146
147 =item *
148
149 The first line begins at the left margin with the greater-than character
150 (C<< > >>), followed immediately by the cell's name without an intervening
151 space. Optionally, a comment can follow any number of spaces and a octothorpe
152 (C<#>), perhaps to identify the organization associated with the
153 cell. A variant of this allows the defintion of a linked cell: after the 
154 leading (C<< > >>) and cell name, a space and a second cell name may be
155 listed before the optional spaces, octothorpe and comment.
156
157 =item *
158
159 Each subsequent line in the entry identifies one of the cell's database
160 server machines, with the indicated information in order:
161
162 =over 4
163
164 =item *
165
166 The database server machine's IP address in dotted-decimal format, optionally
167 enclosed in square braces (C<< [ >>)(C<< ] >>) to define a non-voting clone.
168
169 =item *
170
171 One or more spaces.
172
173 =item *
174
175 An octothorpe (#), followed by the machine's fully qualified hostname
176 without an intervening space. This number sign does not indicate that the
177 hostname is a comment. It is a required field.
178
179 =back
180
181 =back
182
183 No extra blank lines or newline characters are allowed in the file, even
184 after the last entry. Their presence can prevent the Cache Manager from
185 reading the file into kernel memory, resulting in an error message.
186
187 grand.central.org maintains a list of the database server machines in all
188 cells that have registered themselves as receptive to access from foreign
189 cells. When a cell's administrators change its database server machines,
190 it is customary to register the change with grand.central.org for
191 inclusion in this file. The file conforms to the required F<CellServDB>
192 format, and so is a suitable basis for the F<CellServDB> file on a client
193 machine.  You can download this file from L<http://grand.central.org/>.
194
195 =head1 EXAMPLES
196
197 The following example shows entries for two cells in a client
198 F<CellServDB> file and illustrates the required format.
199
200    >abc.com        # ABC Corporation
201    192.12.105.2         #db1.abc.com
202    192.12.105.3         #db2.abc.com
203    [192.12.107.3]       #db3.abc.com
204    >test.abc.com abc.com   # ABC Corporation Test Cell
205    192.12.108.57        #testdb1.abc.com
206    192.12.108.55        #testdb2.abc.com
207
208 =head1 SEE ALSO
209
210 L<afsd(8)>,
211 L<bos_addhost(8)>,
212 L<bos_listhosts(8)>,
213 L<bos_removehost(8)>,
214 L<bos_setcellname(8)>,
215 L<buserver(8)>,
216 L<fs_newcell(1)>,
217 L<kaserver(8)>,
218 L<klog(1)>,
219 L<ptserver(8)>,
220 L<vlserver(8)>,
221 L<upclient(8)>,
222 L<upserver(8)>
223
224 I<OpenAFS Quick Start>
225
226 =head1 COPYRIGHT
227
228 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
229
230 This documentation is covered by the IBM Public License Version 1.0.  It was
231 converted from HTML to POD by software written by Chas Williams and Russ
232 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.