Commit | Line | Data |
---|---|---|
805e021f CE |
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 and SRV entries in DNS, the client version of the CellServDB | |
17 | file 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 a DNS SRV or AFSDB record lookup and dynamically add the database | |
70 | server 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 definition 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 | For the client F<CellServDB>, it may be desirable to make the client aware | |
188 | of a cell (so that it's listed by default in F</afs> when the B<-dynroot> | |
189 | flag to B<afsd> is in use, for instance) without specifying the database | |
190 | server machines for that cell. This can be done by including only the | |
191 | cell line (starting with C<< > >>) and omitting any following database | |
192 | server machine lines. B<afsd> must be configured with the B<-afsdb> option | |
193 | to use DNS SRV or AFSDB record lookups to locate database server | |
194 | machines. If the cell has such records and the client is configured to | |
195 | use them, this configuration won't require updates to the client | |
196 | F<CellServDB> file when the IP addresses of the database server machines | |
197 | change. | |
198 | ||
199 | grand.central.org maintains a list of the database server machines in all | |
200 | cells that have registered themselves as receptive to access from foreign | |
201 | cells. When a cell's administrators change its database server machines, | |
202 | it is customary to register the change with grand.central.org for | |
203 | inclusion in this file. The file conforms to the required F<CellServDB> | |
204 | format, and so is a suitable basis for the F<CellServDB> file on a client | |
205 | machine. You can download this file from L<http://grand.central.org/>. | |
206 | ||
207 | =head1 EXAMPLES | |
208 | ||
209 | The following example shows entries for two cells in a client | |
210 | F<CellServDB> file and illustrates the required format. | |
211 | ||
212 | >example.com # Example Corporation | |
213 | 192.12.105.2 #db1.example.com | |
214 | 192.12.105.3 #db2.example.com | |
215 | [192.12.107.3] #db3.example.com | |
216 | >test.example.com example.com # Example Corporation Test Cell | |
217 | 192.12.108.57 #testdb1.example.com | |
218 | 192.12.108.55 #testdb2.example.com | |
219 | ||
220 | The following example shows entries for two linked cells in a client | |
221 | F<CellServDB> file. The a.example.com cell is linked to the b.example.com | |
222 | cell. | |
223 | ||
224 | >b.example.com # B cell | |
225 | 192.12.108.57 # db1.b.example.com | |
226 | >a.example.com b.example.com # A cell | |
227 | 192.12.105.2 # db1.a.example.com | |
228 | ||
229 | In such a setup, if a client is looking for a volume in cell a.example.com | |
230 | and that volume doesn't exist, the client will try to find that volume | |
231 | again in cell b.example.com. The order is important. You must list the | |
232 | cell being linked before the cell doing the linking. | |
233 | ||
234 | The Windows client supports linking in two directions. The UNIX client | |
235 | does not allow bidirectional linkage. | |
236 | ||
237 | =head1 SEE ALSO | |
238 | ||
239 | L<afsd(8)>, | |
240 | L<bos_addhost(8)>, | |
241 | L<bos_listhosts(8)>, | |
242 | L<bos_removehost(8)>, | |
243 | L<bos_setcellname(8)>, | |
244 | L<buserver(8)>, | |
245 | L<fs_newcell(1)>, | |
246 | L<kaserver(8)>, | |
247 | L<klog(1)>, | |
248 | L<ptserver(8)>, | |
249 | L<vlserver(8)>, | |
250 | L<upclient(8)>, | |
251 | L<upserver(8)> | |
252 | ||
253 | I<OpenAFS Quick Start> | |
254 | ||
255 | =head1 COPYRIGHT | |
256 | ||
257 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
258 | ||
259 | This documentation is covered by the IBM Public License Version 1.0. It was | |
260 | converted from HTML to POD by software written by Chas Williams and Russ | |
261 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |