Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | bosserver - Initializes the BOS Server | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<bosserver> | |
11 | S<<< [B<-noauth>] >>> | |
12 | S<<< [B<-log>] >>> | |
13 | S<<< [B<-enable_peer_stats>] >>> | |
14 | S<<< [B<-auditlog> <I<log path>>] >>> | |
15 | S<<< [B<-audit-interface> ( file | sysvmq )] >>> | |
16 | S<<< [B<-enable_process_stats>] >>> | |
17 | S<<< [B<-allow-dotted-principals>] >>> | |
18 | S<<< [B<-cores>[=none|<I<path>>]] >>> | |
19 | S<<< [B<-restricted>] >>> | |
20 | S<<< [B<-rxmaxmtu> <I<bytes>>] >>> | |
21 | S<<< [B<-rxbind>] >>> | |
22 | S<<< [B<-syslog>[=<I<facility>>]>] >>> | |
23 | S<<< [B<-transarc-logs>] >>> | |
24 | S<<< [B<-pidfiles>[=<I<path>>]] >>> | |
25 | S<<< [B<-nofork>] >>> | |
26 | S<<< [B<-help>] >>> | |
27 | ||
28 | =for html | |
29 | </div> | |
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
33 | The bosserver command initializes the Basic OverSeer (BOS) Server | |
34 | (B<bosserver> process). In the conventional configuration, the binary file | |
35 | is located in the F</usr/afs/bin> directory on a file server machine. | |
36 | ||
37 | The BOS Server must run on every file server machine and helps to automate | |
38 | file server administration by performing the following tasks: | |
39 | ||
40 | =over 4 | |
41 | ||
42 | =item * | |
43 | ||
44 | Monitors the other AFS server processes on the local machine, to make sure | |
45 | they are running correctly. | |
46 | ||
47 | =item * | |
48 | ||
49 | Automatically restarts failed processes, without contacting a human | |
50 | operator. When restarting multiple server processes simultaneously, the | |
51 | BOS Server takes interdependencies into account and initiates restarts in | |
52 | the correct order. | |
53 | ||
54 | =item * | |
55 | ||
56 | Processes commands from the bos suite that administrators issue to verify | |
57 | the status of server processes, install and start new processes, stop | |
58 | processes either temporarily or permanently, and restart halted processes. | |
59 | ||
60 | =item * | |
61 | ||
62 | Manages system configuration information: the files that list the cell's | |
63 | server encryption keys, database server machines, and users privileged to | |
64 | issue commands from the B<bos> and B<vos> suites. | |
65 | ||
66 | =back | |
67 | ||
68 | The BOS Server is configured via the F<BosConfig> configuration file. | |
69 | Normally, this file is managed via the B<bos> command suite rather than | |
70 | edited directly. See the L<BosConfig(5)> man page for the syntax of this | |
71 | file. | |
72 | ||
73 | The BOS Server will rewrite B<BosConfig> when shutting down, so changes | |
74 | made manually to it will be discarded. Instead, to change the BOS Server | |
75 | configuration only for the next restart of B<bosserver>, create a file | |
76 | named F</usr/afs/local/BosConfig.new>. If B<BosConfig.new> exists when | |
77 | B<bosserver> starts, it is renamed to F</usr/afs/local/BosConfig>, | |
78 | removing any existing file by that name, before B<bosserver> reads its | |
79 | configuration. | |
80 | ||
81 | The BOS Server logs a default set of important events in the file | |
82 | F</usr/afs/logs/BosLog>. To record the name of any user who performs a | |
83 | privileged B<bos> command (one that requires being listed in the | |
84 | F</usr/afs/etc/UserList> file), add the B<-log> flag. To display the | |
85 | contents of the B<BosLog> file, use the B<bos getlog> command. | |
86 | ||
87 | The first time that the BOS Server initializes on a server machine, it | |
88 | creates several files and subdirectories in the local F</usr/afs> | |
89 | directory, and sets their mode bits to protect them from unauthorized | |
90 | access. Each time it restarts, it checks that the mode bits still comply | |
91 | with the settings listed in the following chart. A question mark indicates | |
92 | that the BOS Server initially turns off the bit (sets it to the hyphen), | |
93 | but does not check it at restart. | |
94 | ||
95 | /usr/afs drwxr?xr-x | |
96 | /usr/afs/backup drwx???--- | |
97 | /usr/afs/bin drwxr?xr-x | |
98 | /usr/afs/db drwx???--- | |
99 | /usr/afs/etc drwxr?xr-x | |
100 | /usr/afs/etc/KeyFile -rw????--- | |
101 | /usr/afs/etc/UserList -rw?????-- | |
102 | /usr/afs/local drwx???--- | |
103 | /usr/afs/logs drwxr?xr-x | |
104 | ||
105 | If the mode bits do not comply, the BOS Server writes the following | |
106 | warning to the F<BosLog> file: | |
107 | ||
108 | Bosserver reports inappropriate access on server directories | |
109 | ||
110 | However, the BOS Server does not reset the mode bits, so the administrator | |
111 | can set them to alternate values if desired (with the understanding that | |
112 | the warning message then appears at startup). | |
113 | ||
114 | This command does not use the syntax conventions of the AFS command | |
115 | suites. Provide the command name and all option names in full. | |
116 | ||
117 | =head1 OPTIONS | |
118 | ||
119 | =over 4 | |
120 | ||
121 | =item B<-noauth> | |
122 | ||
123 | Turns off all authorization checks, and allows all connecting users to act as | |
124 | administrators, even unauthenticated users. The use of this option is | |
125 | inherently insecure, and should only be used in controlled environments for | |
126 | experimental or debug purposes. See L<NoAuth(5)>. | |
127 | ||
128 | =item B<-log> | |
129 | ||
130 | Records in the F</usr/afs/logs/BosLog> file the names of all users who | |
131 | successfully issue a privileged B<bos> command (one that requires being | |
132 | listed in the F</usr/afs/etc/UserList> file). | |
133 | ||
134 | =item B<-cores=>none|<I<path>> | |
135 | ||
136 | The argument none turns off core file generation. Otherwise, the | |
137 | argument is a path where core files will be stored. | |
138 | ||
139 | =item B<-auditlog> <I<log path>> | |
140 | ||
141 | Turns on audit logging, and sets the path for the audit log. The audit | |
142 | log records information about RPC calls, including the name of the RPC | |
143 | call, the host that submitted the call, the authenticated entity (user) | |
144 | that issued the call, the parameters for the call, and if the call | |
145 | succeeded or failed. | |
146 | ||
147 | =item B<-audit-interface> (file | sysvmq) | |
148 | ||
149 | Specifies what audit interface to use. Defaults to C<file>. See | |
150 | L<fileserver(8)> for an explanation of each interface. | |
151 | ||
152 | =item B<-enable_peer_stats> | |
153 | ||
154 | Activates the collection of Rx statistics and allocates memory for their | |
155 | storage. For each connection with a specific UDP port on another machine, | |
156 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and | |
157 | so on) sent or received. To display or otherwise access the records, use | |
158 | the Rx Monitoring API. | |
159 | ||
160 | =item B<-enable_process_stats> | |
161 | ||
162 | Activates the collection of Rx statistics and allocates memory for their | |
163 | storage. A separate record is kept for each type of RPC (FetchFile, | |
164 | GetStatus, and so on) sent or received, aggregated over all connections to | |
165 | other machines. To display or otherwise access the records, use the Rx | |
166 | Monitoring API. | |
167 | ||
168 | =item B<-allow-dotted-principals> | |
169 | ||
170 | By default, the RXKAD security layer will disallow access by Kerberos | |
171 | principals with a dot in the first component of their name. This is to avoid | |
172 | the confusion where principals user/admin and user.admin are both mapped to the | |
173 | user.admin PTS entry. Sites whose Kerberos realms don't have these collisions | |
174 | between principal names may disable this check by starting the server | |
175 | with this option. | |
176 | ||
177 | =item B<-restricted> | |
178 | ||
179 | In normal operation, the bos server allows a super user to run any command. | |
180 | When the bos server is running in restricted mode (either due to this | |
181 | command line flag, or when configured by L<bos_setrestricted(8)>) a number | |
182 | of commands are unavailable. Note that this flag persists across reboots. | |
183 | Once a server has been placed in restricted mode, it can only be opened up | |
184 | by sending the SIGFPE signal. | |
185 | ||
186 | =item B<-rxmaxmtu> <I<bytes>> | |
187 | ||
188 | Sets the maximum transmission unit for the RX protocol. | |
189 | ||
190 | =item B<-rxbind> | |
191 | ||
192 | Bind the Rx socket to the primary interface only. If not specified, the | |
193 | Rx socket will listen on all interfaces. | |
194 | ||
195 | =item B<-syslog>[=<I<facility>>]> | |
196 | ||
197 | Specifies that logging output should go to syslog instead of the normal | |
198 | log file. B<-syslog>=I<facility> can be used to specify to which facility | |
199 | the log message should be sent. | |
200 | ||
201 | =item B<-transarc-logs> | |
202 | ||
203 | Use Transarc style logging features. Rename the existing log file | |
204 | F</usr/afs/logs/BosLog> to F</usr/afs/logs/BosLog.old> when the bos server is | |
205 | restarted. This option is provided for compatibility with older versions. | |
206 | ||
207 | =item B<-pidfiles>[=<I<path>>] | |
208 | ||
209 | Create a one-line file containing the process id (pid) for each non-cron | |
210 | process started by the BOS Server. This file is removed by the BOS Server when | |
211 | the process exits. The optional <I<path>> argument specifies the path where | |
212 | the pid files are to be created. The default location is C</usr/afs/local>. | |
213 | ||
214 | The name of the pid files for C<simple> BOS Server process types are the BOS | |
215 | Server instance name followed by C<.pid>. | |
216 | ||
217 | The name of the pid files for C<fs> and C<dafs> BOS Server process types are | |
218 | the BOS Server type name, C<fs> or C<dafs>, followed by the BOS Server core | |
219 | name of the process, followed by C<.pid>. The pid file name for the | |
220 | C<fileserver> process is C<fs.file.pid>. The pid file name for the C<volserver> | |
221 | is C<fs.vol.pid>. | |
222 | ||
223 | BOS Server instance names are specfied using the B<bos create> command. See | |
224 | L<bos_create> for a description of the BOS Server process types and instance | |
225 | names. | |
226 | ||
227 | =item B<-nofork> | |
228 | ||
229 | Run the BOS Server in the foreground. By default, the BOS Server process will | |
230 | fork and detach the stdio, stderr, and stdin streams. | |
231 | ||
232 | =item B<-help> | |
233 | ||
234 | Prints the online help for this command. All other valid options are | |
235 | ignored. | |
236 | ||
237 | =back | |
238 | ||
239 | =head1 EXAMPLES | |
240 | ||
241 | The following command initializes the BOS Server and logs the names of | |
242 | users who issue privileged B<bos> commands. | |
243 | ||
244 | % bosserver -log | |
245 | ||
246 | =head1 PRIVILEGE REQUIRED | |
247 | ||
248 | The issuer most be logged onto a file server machine as the local | |
249 | superuser C<root>. | |
250 | ||
251 | =head1 SEE ALSO | |
252 | ||
253 | L<BosConfig(5)>, | |
254 | L<BosLog(5)>, | |
255 | L<bos(8)>, | |
256 | L<bos_create(8)>, | |
257 | L<bos_exec(8)>, | |
258 | L<bos_getlog(8)>, | |
259 | L<bos_getrestart(8)>, | |
260 | L<bos_restart(8)>, | |
261 | L<bos_setrestricted(8)>, | |
262 | L<bos_shutdown(8)>, | |
263 | L<bos_start(8)>, | |
264 | L<bos_startup(8)>, | |
265 | L<bos_status(8)>, | |
266 | L<bos_stop(8)> | |
267 | ||
268 | =head1 COPYRIGHT | |
269 | ||
270 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
271 | ||
272 | This documentation is covered by the IBM Public License Version 1.0. It was | |
273 | converted from HTML to POD by software written by Chas Williams and Russ | |
274 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |