doc/man-pages/pod8/fileserver.pod

   1 =head1 NAME
   2
   3 fileserver - Initializes the File Server component of the fs process
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fileserver> S<<< [B<-d> <I<debug level>>] >>> S<<< [B<-p> <I<number of processes>>] >>>
  11     S<<< [B<-spare> <I<number of spare blocks>>] >>>
  12     S<<< [B<-pctspare> <I<percentage spare>>] >>> S<<< [B<-b> <I<buffers>>] >>>
  13     S<<< [B<-l> <I<large vnodes>>] >>> S<<< [B<-s> <I<small nodes>>] >>>
  14     S<<< [B<-vc> <I<volume cachesize>>] >>> S<<< [B<-w> <I<call back wait interval>>] >>>
  15     S<<< [B<-cb> <I<number of call backs>>] >>> [B<-banner>] [B<-novbc>]
  16     S<<< [B<-implicit> <I<admin mode bits: rlidwka>>] >>>
  17     S<<< [B<-hr> <I<number of hours between refreshing the host cps>>] >>>
  18     [B<-busyat> <I<< redirect clients when queue > n >>>]
  19     S<<< [B<-rxpck> <I<number of rx extra packets>>] >>>
  20     [B<-rxdbg>] [B<-rxdbge>] S<<< [B<-m> <I<min percentage spare in partition>>] >>>
  21     [B<-lock>] [B<-L>] [B<-S>] S<<< [B<-k> <I<stack size>>] >>>
  22     S<<< [B<-realm> <I<Kerberos realm name>>] >>>
  23     S<<< [B<-udpsize> <I<size of socket buffer in bytes>>] >>>
  24     [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>]
  25
  26 =for html
  27 </div>
  28
  29 =head1 DESCRIPTION
  30
  31 The B<fileserver> command initializes the File Server component of the
  32 C<fs> process. In the conventional configuration, its binary file is
  33 located in the F</usr/afs/bin> directory on a file server machine.
  34
  35 The B<fileserver> command is not normally issued at the command shell
  36 prompt, but rather placed into a database server machine's
  37 F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is
  38 ever issued at the command shell prompt, the issuer must be logged onto a
  39 file server machine as the local superuser C<root>.
  40
  41 The File Server creates the F</usr/afs/logs/FileLog> log file as it
  42 initializes, if the file does not already exist. It does not write a
  43 detailed trace by default, but use the B<-d> option to increase the amount
  44 of detail. Use the B<bos getlog> command to display the contents of the
  45 log file.
  46
  47 The command's arguments enable the administrator to control many aspects
  48 of the File Server's performance, as detailed in L<OPTIONS>.  By default
  49 the B<fileserver> command sets values for many arguments that are suitable
  50 for a medium-sized file server machine. To set values suitable for a small
  51 or large file server machine, use the B<-S> or B<-L> flag
  52 respectively. The following list describes the parameters and
  53 corresponding argument for which the B<fileserver> command sets default
  54 values, and the table below summarizes the setting for each of the three
  55 machine sizes.
  56
  57 =over 4
  58
  59 =item *
  60
  61 The maximum number of lightweight processes (LWPs) the File Server uses to
  62 handle requests for data; corresponds to the B<-p> argument. The File
  63 Server always uses a minimum of 32 KB for these processes.
  64
  65 =item *
  66
  67 The maximum number of directory blocks the File Server caches in memory;
  68 corresponds to the B<-b> argument. Each cached directory block (buffer)
  69 consumes 2,092 bytes of memory.
  70
  71 =item *
  72
  73 The maximum number of large vnodes the File Server caches in memory for
  74 tracking directory elements; corresponds to the B<-l> argument. Each large
  75 vnode consumes 292 bytes of memory.
  76
  77 =item *
  78
  79 The maximum number of small vnodes the File Server caches in memory for
  80 tracking file elements; corresponds to the B<-s> argument.  Each small
  81 vnode consumes 100 bytes of memory.
  82
  83 =item *
  84
  85 The maximum volume cache size, which determines how many volumes the File
  86 Server can cache in memory before having to retrieve data from disk;
  87 corresponds to the B<-vc> argument.
  88
  89 =item *
  90
  91 The maximum number of callback structures the File Server caches in
  92 memory; corresponds to the B<-cb> argument. Each callback structure
  93 consumes 16 bytes of memory.
  94
  95 =item *
  96
  97 The maximum number of Rx packets the File Server uses; corresponds to the
  98 B<-rxpck> argument. Each packet consumes 1544 bytes of memory.
  99
 100 =back
 101
 102 The default values are:
 103
 104   Parameter (Argument)               Small (-S)     Medium   Large (-L)
 105   ---------------------------------------------------------------------
 106   Number of LWPs (-p)                        6           9           12
 107   Number of cached dir blocks (-b)          70          90          120
 108   Number of cached large vnodes (-l)       200         400          600
 109   Number of cached small vnodes (-s)       200         400          600
 110   Maximum volume cache size (-vc)          200         400          600
 111   Number of callbacks (-cb)             20,000      60,000       64,000
 112   Number of Rx packets (-rxpck)            100         150          200
 113
 114 To override any of the values, provide the indicated argument (which can
 115 be combined with the B<-S> or B<-L> flag).
 116
 117 The amount of memory required for the File Server varies. The approximate
 118 default memory usage is 751 KB when the B<-S> flag is used (small
 119 configuration), 1.1 MB when all defaults are used (medium configuration),
 120 and 1.4 MB when the B<-L> flag is used (large configuration). If
 121 additional memory is available, increasing the value of the B<-cb> and
 122 B<-vc> arguments can improve File Server performance most directly.
 123
 124 By default, the File Server allows a volume to exceed its quota by 1 MB
 125 when an application is writing data to an existing file in a volume that
 126 is full. The File Server still does not allow users to create new files in
 127 a full volume. To change the default, use one of the following arguments:
 128
 129 =over 4
 130
 131 =item *
 132
 133 Set the B<-spare> argument to the number of extra kilobytes that the File
 134 Server allows as overage. A value of C<0> allows no overage.
 135
 136 =item *
 137
 138 Set the B<-pctspare> argument to the percentage of the volume's quota the
 139 File Server allows as overage.
 140
 141 =back
 142
 143 By default, the File Server implicitly grants the C<a> (administer) and
 144 C<l> (lookup) permissions to system:administrators on the access control
 145 list (ACL) of every directory in the volumes stored on its file server
 146 machine. In other words, the group's members can exercise those two
 147 permissions even when an entry for the group does not appear on an ACL. To
 148 change the set of default permissions, use the B<-implicit> argument.
 149
 150 The File Server maintains a I<host current protection subgroup> (I<host
 151 CPS>) for each client machine from which it has received a data access
 152 request. Like the CPS for a user, a host CPS lists all of the Protection
 153 Database groups to which the machine belongs, and the File Server compares
 154 the host CPS to a directory's ACL to determine in what manner users on the
 155 machine are authorized to access the directory's contents. When the B<pts
 156 adduser> or B<pts removeuser> command is used to change the groups to
 157 which a machine belongs, the File Server must recompute the machine's host
 158 CPS in order to notice the change. By default, the File Server contacts
 159 the Protection Server every two hours to recompute host CPSs, implying
 160 that it can take that long for changed group memberships to become
 161 effective. To change this frequency, use the B<-hr> argument.
 162
 163 The File Server generates the following message when a partition is nearly
 164 full:
 165
 166    No space left on device
 167
 168 This command does not use the syntax conventions of the AFS command
 169 suites. Provide the command name and all option names in full.
 170
 171 =head1 CAUTIONS
 172
 173 Do not use the B<-k> and -w arguments, which are intended for use by the
 174 AFS Development group only. Changing them from their default values can
 175 result in unpredictable File Server behavior.  In any case, on many
 176 operating systems the File Server uses native threads rather than the LWP
 177 threads, so using the B<-k> argument to set the number of LWP threads has
 178 no effect.
 179
 180 Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so
 181 causes the File Server to exit, leaving an error message in the
 182 F</usr/afs/logs/FileLog> file.
 183
 184 Options that are available only on some system types, such as the B<-m>
 185 and B<-lock> options, appear in the output generated by the B<-help>
 186 option only on the relevant system type.
 187
 188 =head1 OPTIONS
 189
 190 =over 4
 191
 192 =item B<-d> <I<debug level>>
 193
 194 Sets the detail level for the debugging trace written to the
 195 F</usr/afs/logs/FileLog> file. Provide one of the following values, each
 196 of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>,
 197 and C<125>. The default value of C<0> produces only a few messages.
 198
 199 =item B<-p> <I<number of processes>>
 200
 201 Sets the number of threads to run. Provide a positive integer. The File
 202 Server creates and uses five threads for special purposes, in addition to
 203 the number specified (but if this argument specifies the maximum possible
 204 number, the File Server automatically uses five of the threads for its own
 205 purposes).
 206
 207 The maximum number of threads can differ in each release of AFS.  Consult
 208 the I<IBM AFS Release Notes> for the current release.
 209
 210 =item B<-spare> <I<number of spare blocks>>
 211
 212 Specifies the number of additional kilobytes an application can store in a
 213 volume after the quota is exceeded. Provide a positive integer; a value of
 214 C<0> prevents the volume from ever exceeding its quota. Do not combine
 215 this argument with the B<-pctspare> argument.
 216
 217 =item B<-pctspare> <I<percentage spare>>
 218
 219 Specifies the amount by which the File Server allows a volume to exceed
 220 its quota, as a percentage of the quota. Provide an integer between C<0>
 221 and C<99>. A value of C<0> prevents the volume from ever exceeding its
 222 quota. Do not combine this argument with the B<-spare> argument.
 223
 224 =item B<-b> <I<buffers>>
 225
 226 Sets the number of directory buffers. Provide a positive integer.
 227
 228 =item B<-l> <I<large vnodes>>
 229
 230 Sets the number of large vnodes available in memory for caching directory
 231 elements. Provide a positive integer.
 232
 233 =item B<-s> <I<small nodes>>
 234
 235 Sets the number of small vnodes available in memory for caching file
 236 elements. Provide a positive integer.
 237
 238 =item B<-vc> <I<volume cachesize>>
 239
 240 Sets the number of volumes the File Server can cache in memory.  Provide a
 241 positive integer.
 242
 243 =item B<-w> <I<call back wait interval>>
 244
 245 Sets the interval at which the daemon spawned by the File Server performs
 246 its maintenance tasks. Do not use this argument; changing the default
 247 value can cause unpredictable behavior.
 248
 249 =item B<-cb> <I<number of callbacks>>
 250
 251 Sets the number of callbacks the File Server can track. Provide a positive
 252 integer.
 253
 254 =item B<-banner>
 255
 256 Prints the following banner to F</dev/console> about every 10 minutes.
 257
 258    File Server is running at I<time>.
 259
 260 =item B<-novbc>
 261
 262 Prevents the File Server from breaking the callbacks that Cache Managers
 263 hold on a volume that the File Server is reattaching after the volume was
 264 offline (as a result of the B<vos restore> command, for example). Use of
 265 this flag is strongly discouraged.
 266
 267 =item B<-implicit> <I<admin mode bits>>
 268
 269 Defines the set of permissions granted by default to the
 270 system:administrators group on the ACL of every directory in a volume
 271 stored on the file server machine. Provide one or more of the standard
 272 permission letters (C<rlidwka>) and auxiliary permission letters
 273 (C<ABCDEFGH>), or one of the shorthand notations for groups of permissions
 274 (C<all>, C<none>, C<read>, and C<write>). To review the meaning of the
 275 permissions, see the B<fs setacl> reference page.
 276
 277 =item B<-hr> <I<number of hours between refreshing the host cps>>
 278
 279 Specifies how often the File Server refreshes its knowledge of the
 280 machines that belong to protection groups (refreshes the host CPSs for
 281 machines). The File Server must update this information to enable users
 282 from machines recently added to protection groups to access data for which
 283 those machines now have the necessary ACL permissions.
 284
 285 =item B<-busyat> <I<< redirect clients when queue > n >>>
 286
 287 Defines the number of incoming RPCs that can be waiting for a response
 288 from the File Server before the File Server returns the error code
 289 C<VBUSY> to the Cache Manager that sent the latest RPC. In response, the
 290 Cache Manager retransmits the RPC after a delay. This argument prevents
 291 the accumulation of so many waiting RPCs that the File Server can never
 292 process them all. Provide a positive integer.  The default value is
 293 C<600>.
 294
 295 =item B<-rxpck> <I<number of rx extra packets>>
 296
 297 Controls the number of Rx packets the File Server uses to store data for
 298 incoming RPCs that it is currently handling, that are waiting for a
 299 response, and for replies that are not yet complete. Provide a positive
 300 integer.
 301
 302 =item B<-rxdbg>
 303
 304 Writes a trace of the File Server's operations on Rx packets to the file
 305 F</usr/afs/logs/rx_dbg>.
 306
 307 =item F<-rxdbge>
 308
 309 Writes a trace of the File Server's operations on Rx events (such as
 310 retransmissions) to the file F</usr/afs/logs/rx_dbg>.
 311
 312 =item F<-m> <I<min percentage spare in partition>>
 313
 314 Specifies the percentage of each AFS server partition that the AIX version
 315 of the File Server creates as a reserve. Specify an integer value between
 316 C<0> and C<30>; the default is 8%. A value of C<0> means that the
 317 partition can become completely full, which can have serious negative
 318 consequences.
 319
 320 =item B<-lock>
 321
 322 Prevents any portion of the fileserver binary from being paged (swapped)
 323 out of memory on a file server machine running the IRIX operating system.
 324
 325 =item B<-L>
 326
 327 Sets values for many arguments in a manner suitable for a large file
 328 server machine. Combine this flag with any option except the B<-S> flag;
 329 omit both flags to set values suitable for a medium-sized file server
 330 machine.
 331
 332 =item B<-S>
 333
 334 Sets values for many arguments in a manner suitable for a small file
 335 server machine. Combine this flag with any option except the B<-L> flag;
 336 omit both flags to set values suitable for a medium-sized file server
 337 machine.
 338
 339 =item B<-k> <I<stack size>>
 340
 341 Sets the LWP stack size in units of 1 kilobyte. Do not use this argument,
 342 and in particular do not specify a value less than the default of C<24>.
 343
 344 =item B<-realm> <I<Kerberos realm name>>
 345
 346 Defines the Kerberos realm name for the File Server to use. If this
 347 argument is not provided, it uses the realm name corresponding to the cell
 348 listed in the local F</usr/afs/etc/ThisCell> file.
 349
 350 =item B<-udpsize> <I<size of socket buffer in bytes>>
 351
 352 Sets the size of the UDP buffer, which is 64 KB by default. Provide a
 353 positive integer, preferably larger than the default.
 354
 355 =item B<-enable_peer_stats>
 356
 357 Activates the collection of Rx statistics and allocates memory for their
 358 storage. For each connection with a specific UDP port on another machine,
 359 a separate record is kept for each type of RPC (FetchFile, GetStatus, and
 360 so on) sent or received. To display or otherwise access the records, use
 361 the Rx Monitoring API.
 362
 363 =item B<-enable_process_stats>
 364
 365 Activates the collection of Rx statistics and allocates memory for their
 366 storage. A separate record is kept for each type of RPC (FetchFile,
 367 GetStatus, and so on) sent or received, aggregated over all connections to
 368 other machines. To display or otherwise access the records, use the Rx
 369 Monitoring API.
 370
 371 =item B<-help>
 372
 373 Prints the online help for this command. All other valid options are
 374 ignored.
 375
 376 =back
 377
 378 =head1 EXAMPLES
 379
 380 The following B<bos create> command creates an fs process on the file
 381 server machine C<fs2.abc.com> that uses the large configuration size, and
 382 allows volumes to exceed their quota by 10%. Type the command on a single
 383 line:
 384
 385    % bos create -server fs2.abc.com -instance fs -type fs \
 386                 -cmd "/usr/afs/bin/fileserver -pctspare 10 \
 387                 -L" /usr/afs/bin/volserver /usr/afs/bin/salvager
 388
 389 =head1 PRIVILEGE REQUIRED
 390
 391 The issuer must be logged in as the superuser C<root> on a file server
 392 machine to issue the command at a command shell prompt. It is conventional
 393 instead to create and start the process by issuing the B<bos create>
 394 command.
 395
 396 =head1 SEE ALSO
 397
 398 L<BosConfig(5)>,
 399 L<FileLog(5)>,
 400 L<bos_create(8)>,
 401 L<bos_getlog(8)>,
 402 L<fs_setacl(1)>,
 403 L<salvager(8)>,
 404 L<volserver(8)>
 405
 406 =head1 COPYRIGHT
 407
 408 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 409
 410 This documentation is covered by the IBM Public License Version 1.0.  It was
 411 converted from HTML to POD by software written by Chas Williams and Russ
 412 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.