| 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. |