Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | bos - Introduction to the bos command suite | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The commands in the B<bos> command suite are the administrative interface | |
8 | to the Basic OverSeer (BOS) Server, which runs on every file server | |
9 | machine to monitor the other server processes on it. If a process fails, | |
10 | the BOS Server can restart it automatically, taking into account | |
11 | interdependencies between it and other processes. The BOS Server frees | |
12 | system administrators from constantly monitoring the status of server | |
13 | machines and processes. | |
14 | ||
15 | There are several categories of commands in the B<bos> command suite: | |
16 | ||
17 | =over 4 | |
18 | ||
19 | =item * | |
20 | ||
21 | Commands to administer server process binary files: B<bos getdate>, B<bos | |
22 | install>, B<bos prune>, and B<bos uninstall>. | |
23 | ||
24 | =item * | |
25 | ||
26 | Commands to maintain system configuration files: B<bos addhost>, B<bos | |
27 | addkey>, B<bos adduser>, B<bos listhosts>, B<bos listkeys>, B<bos | |
28 | listusers>, B<bos removehost>, B<bos removekey>, B<bos removeuser>, and | |
29 | B<bos setcellname>. | |
30 | ||
31 | =item * | |
32 | ||
33 | Commands to start and stop processes: B<bos create>, B<bos delete>, B<bos | |
34 | restart>, B<bos shutdown>, B<bos start>, B<bos startup>, and B<bos stop>. | |
35 | ||
36 | =item * | |
37 | ||
38 | Commands to set and verify server process and server machine status: B<bos | |
39 | getlog>, B<bos getrestart>, B<bos getrestricted>, B<bos setauth>, | |
40 | B<bos setrestart>, B<bos setrestricted> and B<bos status>. | |
41 | ||
42 | =item * | |
43 | ||
44 | A command to restore file system consistency: B<bos salvage>. | |
45 | ||
46 | =item * | |
47 | ||
48 | Commands to obtain help: B<bos apropos> and B<bos help>. | |
49 | ||
50 | =item * | |
51 | ||
52 | A command to display the OpenAFS command suite version: B<bos version>. | |
53 | ||
54 | =back | |
55 | ||
56 | The BOS Server and the B<bos> commands use and maintain the following | |
57 | configuration and log files: | |
58 | ||
59 | =over 4 | |
60 | ||
61 | =item * | |
62 | ||
63 | The F</usr/afs/etc/CellServDB> file lists the local cell's database server | |
64 | machines. These machines run the Authentication, Backup, Protection and | |
65 | Volume Location (VL) Server processes, which maintain databases of | |
66 | administrative information. The database server processes consult the file | |
67 | to learn about their peers, whereas the other server processes consult it | |
68 | to learn where to access database information as needed. To administer the | |
69 | F<CellServDB> file, use the following commands: B<bos addhost>, B<bos | |
70 | listhosts>, B<bos removehost>, and B<bos setcellname>. | |
71 | ||
72 | =item * | |
73 | ||
74 | The F</usr/afs/etc/KeyFile> file lists the server encryption keys that the | |
75 | server processes use to decrypt tickets presented by client processes and | |
76 | one another. To administer the F<KeyFile> file, use the following | |
77 | commands: B<bos addkey>, B<bos listkeys>, and B<bos removekey>. | |
78 | ||
79 | =item * | |
80 | ||
81 | The F</usr/afs/etc/KeyFileExt> file lists additional server encryption | |
82 | keys that the server processes can use to decrypt tickets presented by | |
83 | client processes and one another. These keys are strong encryption | |
84 | keys used by the rxkad-k5 extension; use L<asetkey(8)> to manage the | |
85 | F<KeyFileExt>. | |
86 | ||
87 | =item * | |
88 | ||
89 | The F</usr/afs/etc/ThisCell> file defines the cell to which the server | |
90 | machine belongs for the purposes of server-to-server communication. | |
91 | Administer it with the B<bos setcellname> command. There is also a | |
92 | F</usr/vice/etc/ThisCell> file that defines the machine's cell membership | |
93 | with respect to the AFS command suites and Cache Manager access to AFS | |
94 | data. | |
95 | ||
96 | =item * | |
97 | ||
98 | The F</usr/afs/etc/UserList> file lists the user name of each | |
99 | administrator authorized to issue privileged B<bos> and B<vos> | |
100 | commands. To administer the F<UserList> file, use the following commands: | |
101 | B<bos adduser>, B<bos listusers>, and B<bos removeuser>. | |
102 | ||
103 | =item * | |
104 | ||
105 | The F</usr/afs/local/BosConfig> file defines which AFS server processes | |
106 | run on the server machine, and whether the BOS Server restarts them | |
107 | automatically if they fail. It also defines when all processes restart | |
108 | automatically (by default once per week), when the BOS Server restarts | |
109 | processes that have new binary files (by default once per day), and | |
110 | whether the BOS Server will start in restricted mode. To | |
111 | administer the F<BosConfig> file, use the following commands: B<bos | |
112 | create>, B<bos delete>, B<bos getrestart>, B<bos getrestricted>, B<bos | |
113 | setrestart>, B<bos setrestricted>, B<bos start>, and B<bos stop>. | |
114 | ||
115 | =item * | |
116 | ||
117 | The F</usr/afs/log/BosLog> file records important operations the BOS | |
118 | Server performs and error conditions it encounters. | |
119 | ||
120 | =back | |
121 | ||
122 | For more details, see the reference page for each file. | |
123 | ||
124 | =head1 OPTIONS | |
125 | ||
126 | The following arguments and flags are available on many commands in the | |
127 | B<bos> suite. The reference page for each command also lists them, but | |
128 | they are described here in greater detail. | |
129 | ||
130 | =over 4 | |
131 | ||
132 | =item B<-cell> <I<cell name>> | |
133 | ||
134 | Names the cell in which to run the command. It is acceptable to abbreviate | |
135 | the cell name to the shortest form that distinguishes it from the other | |
136 | entries in the F</usr/vice/etc/CellServDB> file on the local machine. If | |
137 | the B<-cell> argument is omitted, the command interpreter determines the | |
138 | name of the local cell by reading the following in order: | |
139 | ||
140 | =over 4 | |
141 | ||
142 | =item * | |
143 | ||
144 | The value of the AFSCELL environment variable. | |
145 | ||
146 | =item * | |
147 | ||
148 | The local F</usr/vice/etc/ThisCell> file. | |
149 | ||
150 | =back | |
151 | ||
152 | Do not combine the B<-cell> and B<-localauth> options. A command on which | |
153 | the B<-localauth> flag is included always runs in the local cell (as | |
154 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), | |
155 | whereas a command on which the B<-cell> argument is included runs in the | |
156 | specified foreign cell. | |
157 | ||
158 | =item B<-help> | |
159 | ||
160 | Prints a command's online help message on the standard output stream. Do | |
161 | not combine this flag with any of the command's other options; when it is | |
162 | provided, the command interpreter ignores all other options, and only | |
163 | prints the help message. | |
164 | ||
165 | =item B<-localauth> | |
166 | ||
167 | Constructs a server ticket using the server encryption key with the | |
168 | highest key version number in the local F</usr/afs/etc/KeyFile> or | |
169 | F</usr/afs/etc/KeyFileExt> file. The | |
170 | B<bos> command interpreter presents the ticket, which never expires, to | |
171 | the BOS Server during mutual authentication. | |
172 | ||
173 | Use this flag only when issuing a command on a server machine; client | |
174 | machines do not usually have a F</usr/afs/etc/KeyFile> or | |
175 | F</usr/afs/etc/KeyFileExt> file. The issuer | |
176 | of a command that includes this flag must be logged on to the server | |
177 | machine as the local superuser C<root>. The flag is useful for commands | |
178 | invoked by an unattended application program, such as a process controlled | |
179 | by the UNIX B<cron> utility or by a cron entry in the machine's | |
180 | F</usr/afs/local/BosConfig> file. It is also useful if an administrator is | |
181 | unable to authenticate to AFS but is logged in as the local superuser | |
182 | C<root>. | |
183 | ||
184 | Do not combine the B<-cell> and B<-localauth> options. A command on which | |
185 | the B<-localauth> flag is included always runs in the local cell (as | |
186 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), | |
187 | whereas a command on which the B<-cell> argument is included runs in the | |
188 | specified foreign cell. Also, do not combine the B<-localauth> and | |
189 | B<-noauth> flags. | |
190 | ||
191 | =item B<-noauth> | |
192 | ||
193 | Establishes an unauthenticated connection to the BOS Server, in which the | |
194 | BOS Server treats the issuer as the unprivileged user C<anonymous>. It is | |
195 | useful only when authorization checking is disabled on the server machine | |
196 | (during the installation of a file server machine or when the B<bos | |
197 | setauth> command has been used during other unusual circumstances). In | |
198 | normal circumstances, the BOS Server allows only privileged users to issue | |
199 | commands that change the status of a server or configuration file, and | |
200 | refuses to perform such an action even if the B<-noauth> flag is | |
201 | provided. Do not combine the B<-noauth> and B<-localauth> flags. | |
202 | ||
203 | =item B<-server> <I<machine name>> | |
204 | ||
205 | Indicates the AFS server machine on which to run the command. Identify | |
206 | the machine by its IP address in dotted decimal format, its | |
207 | fully-qualified host name (for example, C<fs1.example.com>), or by an | |
208 | abbreviated form of its host name that distinguishes it from other | |
209 | machines. Successful use of an abbreviated form depends on the | |
210 | availability of a name service (such as the Domain Name Service or a local | |
211 | host table) at the time the command is issued. | |
212 | ||
213 | For the commands that alter the administrative files shared by all server | |
214 | machines in the cell (the B<bos addhost>, B<bos addkey>, B<bos adduser>, | |
215 | B<bos removehost>, B<bos removekey>, and B<bos removeuser> commands), the | |
216 | appropriate machine depends on whether the cell uses the United States or | |
217 | international version of AFS: | |
218 | ||
219 | =over 4 | |
220 | ||
221 | =item * | |
222 | ||
223 | If the cell (as recommended) uses the Update Server to distribute the | |
224 | contents of the F</usr/afs/etc> directory, provide the name of the system | |
225 | control machine. After issuing the command, allow up to five minutes for | |
226 | the Update Server to distribute the changed file to the other AFS server | |
227 | machines in the cell. If the specified machine is not the system control | |
228 | machine but is running an B<upclient> process that refers to the system | |
229 | control machine, then the change will be overwritten when the process next | |
230 | brings over the relevant file from the system control machine. | |
231 | ||
232 | =item * | |
233 | ||
234 | Otherwise, repeatedly issue the command, naming each of the cell's server | |
235 | machines in turn. To avoid possible inconsistency problems, finish issuing | |
236 | the commands within a fairly short time. | |
237 | ||
238 | =back | |
239 | ||
240 | =back | |
241 | ||
242 | =head1 PRIVILEGE REQUIRED | |
243 | ||
244 | To issue any bos command that changes a configuration file or alters | |
245 | process status, the issuer must be listed in the F</usr/afs/etc/UserList> | |
246 | file on the server machine named by the B<-server> | |
247 | argument. Alternatively, if the B<-localauth> flag is included the issuer | |
248 | must be logged on as the local superuser C<root>. | |
249 | ||
250 | To issue a bos command that only displays information (other than the | |
251 | B<bos listkeys> command), no privilege is required. | |
252 | ||
253 | =head1 SEE ALSO | |
254 | ||
255 | L<BosConfig(5)>, | |
256 | L<CellServDB(5)>, | |
257 | L<KeyFile(5)>, | |
258 | L<KeyFileExt(5)>, | |
259 | L<ThisCell(5)>, | |
260 | L<UserList(5)>, | |
261 | L<bos_addhost(8)>, | |
262 | L<bos_addkey(8)>, | |
263 | L<bos_adduser(8)>, | |
264 | L<bos_apropos(8)>, | |
265 | L<bos_create(8)>, | |
266 | L<bos_delete(8)>, | |
267 | L<bos_exec(8)>, | |
268 | L<bos_getdate(8)>, | |
269 | L<bos_getlog(8)>, | |
270 | L<bos_getrestart(8)>, | |
271 | L<bos_getrestricted(8)>, | |
272 | L<bos_help(8)>, | |
273 | L<bos_install(8)>, | |
274 | L<bos_listhosts(8)>, | |
275 | L<bos_listkeys(8)>, | |
276 | L<bos_listusers(8)>, | |
277 | L<bos_prune(8)>, | |
278 | L<bos_removehost(8)>, | |
279 | L<bos_removekey(8)>, | |
280 | L<bos_removeuser(8)>, | |
281 | L<bos_restart(8)>, | |
282 | L<bos_salvage(8)>, | |
283 | L<bos_setauth(8)>, | |
284 | L<bos_setcellname(8)>, | |
285 | L<bos_setrestart(8)>, | |
286 | L<bos_setrestricted(8)>, | |
287 | L<bos_shutdown(8)>, | |
288 | L<bos_start(8)>, | |
289 | L<bos_startup(8)>, | |
290 | L<bos_status(8)>, | |
291 | L<bos_stop(8)>, | |
292 | L<bos_uninstall(8)> | |
293 | ||
294 | =head1 COPYRIGHT | |
295 | ||
296 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
297 | ||
298 | This documentation is covered by the IBM Public License Version 1.0. It was | |
299 | converted from HTML to POD by software written by Chas Williams and Russ | |
300 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |