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