01ac948556ebce5b07754977720f3890c9263002
[openafs.git] / doc / man-pages / pod8 / bosserver.pod
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> [B<-noauth>] [B<-log>] [B<-enable_peer_stats>]
11     S<<< [B<-auditlog> <I<log path>>] >>> [B<-audit-interface> (file | sysvmq)]
12     [B<-enable_process_stats>] [B<-allow-dotted-principals>] [B<-help>]
13
14 =for html
15 </div>
16
17 =head1 DESCRIPTION
18
19 The bosserver command initializes the Basic OverSeer (BOS) Server
20 (B<bosserver> process). In the conventional configuration, the binary file
21 is located in the F</usr/afs/bin> directory on a file server machine.
22
23 The BOS Server must run on every file server machine and helps to automate
24 file server administration by performing the following tasks:
25
26 =over 4
27
28 =item *
29
30 Monitors the other AFS server processes on the local machine, to make sure
31 they are running correctly.
32
33 =item *
34
35 Automatically restarts failed processes, without contacting a human
36 operator. When restarting multiple server processes simultaneously, the
37 BOS Server takes interdependencies into account and initiates restarts in
38 the correct order.
39
40 =item *
41
42 Processes commands from the bos suite that administrators issue to verify
43 the status of server processes, install and start new processes, stop
44 processes either temporarily or permanently, and restart halted processes.
45
46 =item *
47
48 Manages system configuration information: the files that list the cell's
49 server encryption keys, database server machines, and users privileged to
50 issue commands from the B<bos> and B<vos> suites.
51
52 =back
53
54 The BOS Server logs a default set of important events in the file
55 F</usr/afs/logs/BosLog>. To record the name of any user who performs a
56 privileged B<bos> command (one that requires being listed in the
57 F</usr/afs/etc/UserList> file), add the B<-log> flag. To display the
58 contents of the B<BosLog> file, use the B<bos getlog> command.
59
60 The first time that the BOS Server initializes on a server machine, it
61 creates several files and subdirectories in the local F</usr/afs>
62 directory, and sets their mode bits to protect them from unauthorized
63 access. Each time it restarts, it checks that the mode bits still comply
64 with the settings listed in the following chart. A question mark indicates
65 that the BOS Server initially turns off the bit (sets it to the hyphen),
66 but does not check it at restart.
67
68    /usr/afs              drwxr?xr-x
69    /usr/afs/backup       drwx???---
70    /usr/afs/bin          drwxr?xr-x
71    /usr/afs/db           drwx???---
72    /usr/afs/etc          drwxr?xr-x
73    /usr/afs/etc/KeyFile  -rw????---
74    /usr/afs/etc/UserList -rw?????--
75    /usr/afs/local        drwx???---
76    /usr/afs/logs         drwxr?xr-x
77
78 If the mode bits do not comply, the BOS Server writes the following
79 warning to the F<BosLog> file:
80
81    Bosserver reports inappropriate access on server directories
82
83 However, the BOS Server does not reset the mode bits, so the administrator
84 can set them to alternate values if desired (with the understanding that
85 the warning message then appears at startup).
86
87 This command does not use the syntax conventions of the AFS command
88 suites. Provide the command name and all option names in full.
89
90 =head1 OPTIONS
91
92 =over 4
93
94 =item B<-noauth>
95
96 Assigns the unprivileged identity C<anonymous> to the issuer, which is
97 useful only when authorization checking is disabled on the server machine
98 (for instance, during the installation of a file server machine.)
99
100 =item B<-log>
101
102 Records in the F</usr/afs/logs/BosLog> file the names of all users who
103 successfully issue a privileged B<bos> command (one that requires being
104 listed in the F</usr/afs/etc/UserList> file).
105
106 =item B<-auditlog> <I<log path>>
107
108 Turns on audit logging, and sets the path for the audit log.  The audit
109 log records information about RPC calls, including the name of the RPC
110 call, the host that submitted the call, the authenticated entity (user)
111 that issued the call, the parameters for the call, and if the call
112 succeeded or failed.
113
114 =item B<-audit-interface> (file | sysvmq)
115
116 Specifies what audit interface to use. Defaults to C<file>. See
117 L<fileserver(8)> for an explanation of each interface.
118
119 =item B<-enable_peer_stats>
120
121 Activates the collection of Rx statistics and allocates memory for their
122 storage. For each connection with a specific UDP port on another machine,
123 a separate record is kept for each type of RPC (FetchFile, GetStatus, and
124 so on) sent or received. To display or otherwise access the records, use
125 the Rx Monitoring API.
126
127 =item B<-enable_process_stats>
128
129 Activates the collection of Rx statistics and allocates memory for their
130 storage. A separate record is kept for each type of RPC (FetchFile,
131 GetStatus, and so on) sent or received, aggregated over all connections to
132 other machines. To display or otherwise access the records, use the Rx
133 Monitoring API.
134
135 =item B<-allow-dotted-principals>
136
137 By default, the RXKAD security layer will disallow access by Kerberos
138 principals with a dot in the first component of their name. This is to avoid
139 the confusion where principals user/admin and user.admin are both mapped to the
140 user.admin PTS entry. Sites whose Kerberos realms don't have these collisions 
141 between principal names may disable this check by starting the server
142 with this option.
143
144 =item B<-help>
145
146 Prints the online help for this command. All other valid options are
147 ignored.
148
149 =back
150
151 =head1 EXAMPLES
152
153 The following command initializes the BOS Server and logs the names of
154 users who issue privileged B<bos> commands.
155
156    % bosserver -log &
157
158 =head1 PRIVILEGE REQUIRED
159
160 The issuer most be logged onto a file server machine as the local
161 superuser C<root>.
162
163 =head1 SEE ALSO
164
165 L<BosConfig(5)>,
166 L<BosLog(5)>,
167 L<bos(8)>,
168 L<bos_create(8)>,
169 L<bos_exec(8)>,
170 L<bos_getlog(8)>,
171 L<bos_getrestart(8)>,
172 L<bos_restart(8)>,
173 L<bos_shutdown(8)>,
174 L<bos_start(8)>,
175 L<bos_startup(8)>,
176 L<bos_status(8)>,
177 L<bos_stop(8)>
178
179 =head1 COPYRIGHT
180
181 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
182
183 This documentation is covered by the IBM Public License Version 1.0.  It was
184 converted from HTML to POD by software written by Chas Williams and Russ
185 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.