| 1 | =head1 NAME |
| 2 | |
| 3 | afsd, afsd.fuse - Initializes the Cache Manager and starts related daemons |
| 4 | |
| 5 | =head1 SYNOPSIS |
| 6 | |
| 7 | =for html |
| 8 | <div class="synopsis"> |
| 9 | |
| 10 | B<afsd> [B<-afsdb>] [B<-backuptree>] |
| 11 | S<<< [B<-biods> <I<number of bkg I/O daemons (aix vm)>>] >>> |
| 12 | S<<< [B<-blocks> <I<1024 byte blocks in cache>>] >>> |
| 13 | S<<< [B<-cachedir> <I<cache directory>>] >>> |
| 14 | S<<< [B<-chunksize> <I<log(2) of chunk size>>] >>> |
| 15 | S<<< [B<-confdir> <I<configuration directory>>] >>> |
| 16 | S<<< [B<-daemons> <I<number of daemons to use>>] >>> |
| 17 | S<<< [B<-dcache> <I<number of dcache entries>>] >>> [B<-debug>] |
| 18 | [B<-dynroot>] [B<-dynroot-sparse>] [B<-enable_peer_stats>] |
| 19 | [B<-enable_process_stats>] [B<-fakestat>] [B<-fakestat-all>] |
| 20 | S<<< [B<-files> <I<files in cache>>] >>> |
| 21 | S<<< [B<-files_per_subdir> <I<log(2) of files per dir>> ] >>> |
| 22 | [B<-help>] S<<< [B<-logfile> <I<Place to keep the CM log>>] >>> |
| 23 | S<<< [B<-inumcalc>] <I<method>> >>> |
| 24 | [B<-mem_alloc_sleep>] [B<-memcache>] |
| 25 | S<<< [B<-mountdir> <I<mount location>>] >>> [B<-nomount>] |
| 26 | [B<-nosettime>] |
| 27 | S<<< [B<-prealloc> <I<number of 'small' preallocated blocks>>] >>> |
| 28 | [B<-rmtsys>] S<<< [B<-rootvol> <I<name of AFS root volume>>] >>> |
| 29 | [B<-rxbind>] S<<< [B<-rxmaxmtu> value for maximum MTU ] >>> |
| 30 | S<<< [B<-rxpck> value for rx_extraPackets ] >>> |
| 31 | [B<-settime>] [B<-shutdown>] |
| 32 | S<<< [B<-splitcache> <I<RW/RO ratio>>] >>> |
| 33 | S<<< [B<-stat> <I<number of stat entries>>] >>> [B<-verbose>] |
| 34 | [B<-disable-dynamic-vcaches>] |
| 35 | S<<< [B<-volumes> <I<number of volume entries>>] >>> |
| 36 | [B<-waitclose>] [B<-rxmaxfrags> <I<max # of fragments>>] |
| 37 | S<<< [B<-volume-ttl> <I<vldb cache timeout>>] >>> |
| 38 | |
| 39 | =for html |
| 40 | </div> |
| 41 | |
| 42 | =head1 DESCRIPTION |
| 43 | |
| 44 | The B<afsd> command initializes the Cache Manager on an AFS client machine |
| 45 | by transferring AFS-related configuration information into kernel memory |
| 46 | and starting several daemons. B<afsd.fuse> is an experimental variant that |
| 47 | initializes a FUSE-based Cache Manager instead of one based on a kernel |
| 48 | module. |
| 49 | |
| 50 | The B<afsd> command performs the following actions: |
| 51 | |
| 52 | =over 4 |
| 53 | |
| 54 | =item * |
| 55 | |
| 56 | Sets a field in kernel memory that defines the machine's cell |
| 57 | membership. Some Cache Manager-internal operations and system calls |
| 58 | consult this field to learn which cell to execute in. (The AFS command |
| 59 | interpreters refer to the F</usr/vice/etc/ThisCell> file instead.) This |
| 60 | information is transferred into the kernel from the |
| 61 | F</usr/vice/etc/ThisCell> file and cannot be changed until the B<afsd> |
| 62 | program runs again. |
| 63 | |
| 64 | =item * |
| 65 | |
| 66 | Places in kernel memory the names and Internet addresses of the database |
| 67 | server machines in the local cell and (optionally) foreign cells. The |
| 68 | appearance of a cell's database server machines in this list enables the |
| 69 | Cache Manager to contact them and to access files in the cell. Omission of |
| 70 | a cell from this list, or incorrect information about its database server |
| 71 | machines, prevents the Cache Manager from accessing files in it. |
| 72 | |
| 73 | By default, the list of database server machines is transferred into the |
| 74 | kernel from the F</usr/vice/etc/CellServDB> file. Alternatively, when the |
| 75 | B<-afsdb> option is used, the list of database server machines is taken |
| 76 | from the DNS SRV or AFSDB records for each cell. After initialization, use the |
| 77 | B<fs newcell> command to change the kernel-resident list without having to |
| 78 | reboot. |
| 79 | |
| 80 | =item * |
| 81 | |
| 82 | Mounts the root of the AFS filespace on a directory on the machine's local |
| 83 | disk, according to either the first field in the |
| 84 | F</usr/vice/etc/cacheinfo> file (the default) or the B<afsd> command's |
| 85 | B<-mountdir> argument. The conventional value is F</afs>. |
| 86 | |
| 87 | =item * |
| 88 | |
| 89 | Determines which volume to mount at the root of the AFS file tree. The |
| 90 | default is the volume C<root.afs>; use the B<-rootvol> argument to |
| 91 | override it. Although the base (read/write) form of the volume name is the |
| 92 | appropriate value, the Cache Manager has a bias for accessing the |
| 93 | read-only version of the volume (by convention, C<root.afs.readonly>) if |
| 94 | it is available. |
| 95 | |
| 96 | =item * |
| 97 | |
| 98 | Configures the cache on disk (the default) or in machine memory if the |
| 99 | B<-memcache> argument is provided. In the latter case, the B<afsd> program |
| 100 | allocates space in machine memory for caching, and the Cache Manager uses |
| 101 | no disk space for caching even if the machine has a disk. |
| 102 | |
| 103 | =item * |
| 104 | |
| 105 | Defines the name of the local disk directory devoted to caching, when the |
| 106 | B<-memcache> argument is not used. If necessary, the B<afsd> program |
| 107 | creates the directory (its parent directory must already exist). It does |
| 108 | not remove the directory that formerly served this function, if one |
| 109 | exists. |
| 110 | |
| 111 | The second field in the F</usr/vice/etc/cacheinfo> file is the source for |
| 112 | this name. The standard value is F</usr/vice/cache>. Use the B<-cachedir> |
| 113 | argument to override the value in the B<cacheinfo> file. |
| 114 | |
| 115 | =item * |
| 116 | |
| 117 | Sets the size of the cache. The default source for the value is the third |
| 118 | field in the F</usr/vice/etc/cacheinfo> file, which specifies a number of |
| 119 | kilobytes. |
| 120 | |
| 121 | For a memory cache, the following arguments to the afsd command override |
| 122 | the value in the B<cacheinfo> file: |
| 123 | |
| 124 | =over 4 |
| 125 | |
| 126 | =item * |
| 127 | |
| 128 | The B<-blocks> argument, to specify a different number of kilobyte blocks. |
| 129 | |
| 130 | =item * |
| 131 | |
| 132 | The B<-dcache> and B<-chunksize> arguments together, to set both the |
| 133 | number of dcache entries and the chunk size (see below for definition of |
| 134 | these parameters). In this case, the B<afsd> program derives cache size by |
| 135 | multiplying the two values. Using this combination is not recommended, as |
| 136 | it requires the issuer to perform the calculation beforehand to determine |
| 137 | the resulting cache size. |
| 138 | |
| 139 | =item * |
| 140 | |
| 141 | The B<-dcache> argument by itself. In this case, the B<afsd> program |
| 142 | derives cache size by multiplying the value specified by the B<-dcache> |
| 143 | argument by the default memory cache chunk size of eight kilobytes. Using |
| 144 | this argument is not recommended, as it requires the issuer to perform the |
| 145 | calculation beforehand to determine the resulting cache size. |
| 146 | |
| 147 | =back |
| 148 | |
| 149 | For satisfactory memory cache performance, the specified value must leave |
| 150 | enough memory free to accommodate all other processes and commands that |
| 151 | can run on the machine. If the value exceeds the amount of memory |
| 152 | available, the B<afsd> program exits without initializing the Cache |
| 153 | Manager and produces the following message on the standard output stream: |
| 154 | |
| 155 | afsd: memCache allocation failure at <number> KB |
| 156 | |
| 157 | where <number> is how many kilobytes were allocated just before the |
| 158 | failure. |
| 159 | |
| 160 | For a disk cache, use the B<-blocks> argument to the B<afsd> command to |
| 161 | override the value in the B<cacheinfo> file. The value specified in either |
| 162 | way sets an absolute upper limit on cache size; values provided for other |
| 163 | arguments (such as B<-dcache> and B<-chunksize>) never result in a larger |
| 164 | cache. The B<afsd> program rejects any setting larger than 95% of the |
| 165 | partition size, and exits after generating an error message on the |
| 166 | standard output stream, because the cache implementation itself requires a |
| 167 | small amount of disk space and overfilling the partition can cause the |
| 168 | client machine to panic. |
| 169 | |
| 170 | To change the size of a disk cache after initialization without rebooting, |
| 171 | use the B<fs setcachesize> command; the setting persists until the B<afsd> |
| 172 | command runs again or the B<fs setcachesize> command is reissued. The B<fs |
| 173 | setcachesize> command does not work for memory caches. |
| 174 | |
| 175 | =item * |
| 176 | |
| 177 | Sets the size of each cache I<chunk>, and by implication the amount of |
| 178 | data that the Cache Manager requests at a time from the File Server (how |
| 179 | much data per fetch RPC, since AFS uses partial file transfer). |
| 180 | |
| 181 | For a disk cache, a chunk is a F<VI<n>> file and this parameter sets the |
| 182 | maximum size to which each one can expand. For a memory cache, each chunk |
| 183 | is a collection of contiguous memory blocks. The default for a disk cache |
| 184 | is between 256 KB and 1 MB depending on the size of the cache. The default |
| 185 | for a memory cache is 8 KB. |
| 186 | |
| 187 | To override the default chunk size for either type of cache, use the |
| 188 | B<-chunksize> argument to provide an integer to be used as an exponent of |
| 189 | two; see L</OPTIONS> for details. For a memory cache, if total cache size |
| 190 | divided by chunk size leaves a remainder, the B<afsd> program rounds down |
| 191 | the number of dcache entries, resulting in a slightly smaller cache. |
| 192 | |
| 193 | =item * |
| 194 | |
| 195 | Sets the number of chunks in the cache. For a memory cache, the number of |
| 196 | chunks is equal to the cache size divided by the chunk size. For a disk |
| 197 | cache, the number of chunks (F<VI<n>> files) is set to the largest |
| 198 | of the following unless the B<-files> argument is used to set the value |
| 199 | explicitly: |
| 200 | |
| 201 | =over 4 |
| 202 | |
| 203 | =item * |
| 204 | |
| 205 | 100 |
| 206 | |
| 207 | =item * |
| 208 | |
| 209 | 1.5 times the result of dividing cache size by chunk size |
| 210 | (I<cachesize>/I<chunksize> * 1.5) |
| 211 | |
| 212 | =item * |
| 213 | |
| 214 | The result of dividing cachesize by 10 KB (I<cachesize>/10240) |
| 215 | |
| 216 | =back |
| 217 | |
| 218 | =item * |
| 219 | |
| 220 | Sets the number of I<dcache entries> allocated in machine memory for |
| 221 | storing information about the chunks in the cache. |
| 222 | |
| 223 | For a disk cache, the F</usr/vice/cache/CacheItems> file contains one |
| 224 | entry for each F<VI<n>> file. By default, one half the number of |
| 225 | these entries (but not more that 2,000) are duplicated as dcache entries |
| 226 | in machine memory for quicker access. |
| 227 | |
| 228 | For a memory cache, there is no F<CacheItems> file so all information |
| 229 | about cache chunks must be in memory as dcache entries. Thus, there is no |
| 230 | default number of dcache entries for a memory cache; instead, the B<afsd> |
| 231 | program derives it by dividing the cache size by the chunk size. |
| 232 | |
| 233 | To set the number of dcache entries, use the B<-dcache> argument; the |
| 234 | specified value can exceed the default limit of 2,000. Using this argument |
| 235 | is not recommended for either type of cache. Increasing the number of |
| 236 | dcache entries for a disk cache sometimes improves performance (because |
| 237 | more entries are retrieved from memory rather than from disk), but only |
| 238 | marginally. Using this argument for a memory cache requires the issuer to |
| 239 | calculate the cache size by multiplying this value by the chunk size. |
| 240 | |
| 241 | =item * |
| 242 | |
| 243 | Sets the number of I<stat> entries available in machine memory for caching |
| 244 | status information about cached AFS files. The default is based on the |
| 245 | size of the cache. Use the B<-stat> argument to override the default. |
| 246 | |
| 247 | =back |
| 248 | |
| 249 | In addition to setting cache configuration parameters, the B<afsd> program |
| 250 | starts the following daemons. (On most system types, these daemons appear |
| 251 | as nameless entries in the output of the UNIX B<ps> command.) |
| 252 | |
| 253 | =over 4 |
| 254 | |
| 255 | =item * |
| 256 | |
| 257 | One I<callback> daemon, which handles callbacks. It also responds to the |
| 258 | File Server's periodic probes, which check that the client machine is |
| 259 | still alive. |
| 260 | |
| 261 | =item * |
| 262 | |
| 263 | One I<maintenance> daemon, which performs the following tasks: |
| 264 | |
| 265 | =over 4 |
| 266 | |
| 267 | =item * |
| 268 | |
| 269 | Garbage collects obsolete data (for example, expired tokens) from kernel |
| 270 | memory. |
| 271 | |
| 272 | =item * |
| 273 | |
| 274 | Synchronizes files. |
| 275 | |
| 276 | =item * |
| 277 | |
| 278 | Refreshes information from read-only volumes once per hour. |
| 279 | |
| 280 | =item * |
| 281 | |
| 282 | Does delayed writes for NFS clients if the machine is running the NFS/AFS |
| 283 | Translator. |
| 284 | |
| 285 | =back |
| 286 | |
| 287 | =item * |
| 288 | |
| 289 | One I<cache-truncation> daemon, which flushes the cache when free space is |
| 290 | required, by writing cached data and status information to the File |
| 291 | Server. |
| 292 | |
| 293 | =item * |
| 294 | |
| 295 | One I<server connection> daemon, which sends a probe to the File |
| 296 | Server every few minutes to check that it is still accessible. |
| 297 | |
| 298 | =item * |
| 299 | |
| 300 | One or more I<background> daemons that improve performance by pre-fetching |
| 301 | files and performing background (delayed) writes of saved data into AFS. |
| 302 | |
| 303 | The default number of background daemons is two, enough to service at |
| 304 | least five simultaneous users of the machine. To increase the number, use |
| 305 | the B<-daemons> argument. A value greater than six is not generally |
| 306 | necessary. |
| 307 | |
| 308 | =item * |
| 309 | |
| 310 | On some system types, one I<Rx listener> daemon, which listens for |
| 311 | incoming RPCs. |
| 312 | |
| 313 | =item * |
| 314 | |
| 315 | On some system types, one I<Rx event> daemon, which reviews the Rx |
| 316 | system's queue of tasks and performs them as appropriate. Most items in |
| 317 | the queue are retransmissions of failed packets. |
| 318 | |
| 319 | =item * |
| 320 | |
| 321 | On machines that run AIX with virtual memory (VM) integration, one or more |
| 322 | I<VM> daemons (sometimes called I<I/O> daemons, which transfer data |
| 323 | between disk and machine memory. The number of them depends on the setting |
| 324 | of the B<-biods> and B<-daemons> arguments: |
| 325 | |
| 326 | =over 4 |
| 327 | |
| 328 | =item * |
| 329 | |
| 330 | If the B<-biods> argument is used, it sets the number of VM daemons. |
| 331 | |
| 332 | =item * |
| 333 | |
| 334 | If only the B<-daemons> argument is used, the number of VM daemons is |
| 335 | twice the number of background daemons. |
| 336 | |
| 337 | =item * |
| 338 | |
| 339 | If neither argument is used, there are five VM daemons. |
| 340 | |
| 341 | =back |
| 342 | |
| 343 | =back |
| 344 | |
| 345 | B<afsd.fuse> is a variant of B<afsd> that, instead of initializing a Cache |
| 346 | Manager implemented as a kernel module, initializes a FUSE-based AFS |
| 347 | client. FUSE (Filesystem in USErspace) is a Linux-only mechanism for |
| 348 | providing a file system through a purely user-space daemon without a |
| 349 | kernel module component. B<afsd.fuse> takes all of the same options as |
| 350 | B<afsd>. |
| 351 | |
| 352 | This command does not use the syntax conventions of the AFS command |
| 353 | suites. Provide the command name and all option names in full. |
| 354 | |
| 355 | =head1 CAUTIONS |
| 356 | |
| 357 | Before using the B<-shutdown> parameter, use the standard UNIX B<umount> |
| 358 | command to unmount the AFS root directory (by convention, F</afs>). On |
| 359 | Linux, unloading the AFS kernel module and then loading it again before |
| 360 | restarting AFS after B<-shutdown> is recommended. |
| 361 | |
| 362 | AFS has for years had difficulties with being stopped and restarted |
| 363 | without an intervening reboot. While most of these issues have been |
| 364 | ironed out, stopping and restarting AFS is not recommended unless |
| 365 | necessary and rebooting before restarting AFS is still the safest course |
| 366 | of action. This does not apply to Linux; it should be safe to restart the |
| 367 | AFS client on Linux without rebooting. |
| 368 | |
| 369 | In contrast to many client-server applications, not all communication is |
| 370 | initiated by the client. When the AFS client opens a file, it registers a |
| 371 | callback with the AFS server. If the file changes, the server notifies the |
| 372 | client that the file has changed and that all cached copies should be |
| 373 | discarded. In order to enable full functionality on the AFS client, |
| 374 | including all command-line utilities, the following UDP ports must be open |
| 375 | on an firewalls between the client and the server: |
| 376 | |
| 377 | fileserver 7000/udp |
| 378 | cachemanager 7001/udp (OpenAFS client. Arla uses 4711/udp) |
| 379 | ptserver 7002/udp |
| 380 | vlserver 7003/udp |
| 381 | kaserver 7004/udp (not needed with Kerberos v5) |
| 382 | volserver 7005/udp |
| 383 | reserved 7006/udp (for future use) |
| 384 | bosserver 7007/udp |
| 385 | |
| 386 | Clients will also need to be able to contact your Kerberos KDC to |
| 387 | authenticate. If you are using B<kaserver> and B<klog>, you need to allow |
| 388 | inbound and outbound UDP on ports >1024 (probably 1024<port<2048 would |
| 389 | suffice depending on the number of simultaneous B<klog>s). |
| 390 | |
| 391 | Be sure to set the UDP timeouts on the firewall to be at least twenty |
| 392 | minutes for the best callback performance. |
| 393 | |
| 394 | B<afsd.fuse> was first introduced in OpenAFS 1.5.74. It is only available |
| 395 | if OpenAFS was built with the C<--enable-fuse-client> configure switch. |
| 396 | It should be considered experimental. |
| 397 | |
| 398 | =head1 OPTIONS |
| 399 | |
| 400 | =over 4 |
| 401 | |
| 402 | =item B<-afsdb> |
| 403 | |
| 404 | Enable afsdb support. This will use DNS to lookup the SRV or AFSDB records and |
| 405 | use that for the database servers for each cell instead of the values |
| 406 | in the F<CellServDB> file. This has the advantage of only needing to |
| 407 | update one set of DNS records to reconfigure the AFS clients for a new |
| 408 | database server as opposed to touching all of the clients, and also |
| 409 | allows one to access a cell without preconfiguring its database |
| 410 | servers in F<CellServDB>. The format of SRV records is defined in |
| 411 | RFC 5864, and the AFSDB record format is in RFC 1183. |
| 412 | |
| 413 | =item B<-backuptree> |
| 414 | |
| 415 | Prefer backup volumes for mountpoints in backup volumes. This option means |
| 416 | that the AFS client will prefer to resolve mount points to backup volumes |
| 417 | when a parent of the current volume is a backup volume. This is similar to |
| 418 | the standard behaviour of preferring read-only volumes over read-write |
| 419 | volumes when the parent volume is a read-only volume. |
| 420 | |
| 421 | =item B<-biods> <I<number of I/O daemons>> |
| 422 | |
| 423 | Sets the number of VM daemons dedicated to performing I/O operations on a |
| 424 | machine running a version of AIX with virtual memory (VM) integration. If |
| 425 | both this argument and the B<-daemons> argument are omitted, the default |
| 426 | is five. If this argument is omitted but the B<-daemons> argument is |
| 427 | provided, the number of VM daemons is set to twice the value of the |
| 428 | B<-daemons> argument. |
| 429 | |
| 430 | =item B<-blocks> <I<blocks in cache>> |
| 431 | |
| 432 | Specifies the number of kilobyte blocks to be made available for caching |
| 433 | in the machine's cache directory (for a disk cache) or memory (for a |
| 434 | memory cache), overriding the default defined in the third field of the |
| 435 | F</usr/vice/etc/cacheinfo> file. For a disk cache, the value cannot exceed |
| 436 | 95% of the space available in the cache partition. If using a memory |
| 437 | cache, do not combine this argument with the B<-dcache> argument, since |
| 438 | doing so can possibly result in a chunk size that is not an exponent of 2. |
| 439 | |
| 440 | =item B<-cachedir> <I<cache directory>> |
| 441 | |
| 442 | Names the local disk directory to be used as the cache. This value |
| 443 | overrides the default defined in the second field of the |
| 444 | F</usr/vice/etc/cacheinfo> file. |
| 445 | |
| 446 | =item B<-chunksize> <I<chunk size>> |
| 447 | |
| 448 | Sets the size of each cache chunk. The integer provided, which must be |
| 449 | from the range C<0> to C<30>, is used as an exponent on the number 2. If not |
| 450 | supplied, a default chunksize will be determined based on the cache type and |
| 451 | cache size, and will range from C<13> (8KB) for memory cache and C<18> to |
| 452 | C<20> (256 KB to 1MB) for disk cache. A value of C<0> or less, or greater than |
| 453 | C<30>, sets chunk size to the appropriate default. Values less than C<10> |
| 454 | (which sets chunk size to a 1 KB) are not recommended. Combining this |
| 455 | argument with the B<-dcache> argument is not recommended because it |
| 456 | requires that the issuer calculate the cache size that results. |
| 457 | |
| 458 | B<-chunksize> is an important option when tuning for performance. Setting |
| 459 | this option to larger values can increase performance when dealing with |
| 460 | large files. |
| 461 | |
| 462 | =item B<-confdir> <I<configuration directory>> |
| 463 | |
| 464 | Names a directory other than the F</usr/vice/etc> directory from which to |
| 465 | fetch the F<cacheinfo>, F<ThisCell>, and F<CellServDB> configuration |
| 466 | files. |
| 467 | |
| 468 | =item B<-daemons> <I<number of daemons to use>> |
| 469 | |
| 470 | Specifies the number of background daemons to run on the machine. These |
| 471 | daemons improve efficiency by doing prefetching and background writing of |
| 472 | saved data. This value overrides the default of C<2>, which is adequate |
| 473 | for a machine serving up to five users. Values greater than C<6> are not |
| 474 | generally more effective than C<6>. |
| 475 | |
| 476 | Note: On AIX machines with integrated virtual memory (VM), the number of |
| 477 | VM daemons is set to twice the value of this argument, if it is provided |
| 478 | and the B<-biods> argument is not. If both arguments are omitted, there |
| 479 | are five VM daemons. |
| 480 | |
| 481 | =item B<-dcache> <I<number of dcache entries>> |
| 482 | |
| 483 | Sets the number of dcache entries in memory, which are used to store |
| 484 | information about cache chunks. For a disk cache, this overrides the |
| 485 | default, which is 50% of the number of F<VI<n>> files (cache chunks). For |
| 486 | a memory cache, this argument effectively sets the number of cache chunks, |
| 487 | but its use is not recommended, because it requires the issuer to |
| 488 | calculate the resulting total cache size (derived by multiplying this |
| 489 | value by the chunk size). Do not combine this argument with the B<-blocks> |
| 490 | argument, since doing so can possibly result in a chunk size that is not |
| 491 | an exponent of 2. |
| 492 | |
| 493 | =item B<-debug> |
| 494 | |
| 495 | Generates a highly detailed trace of the B<afsd> program's actions on the |
| 496 | standard output stream. The information is useful mostly for debugging |
| 497 | purposes. |
| 498 | |
| 499 | =item B<-dynroot> |
| 500 | |
| 501 | The standard behaviour of the AFS client without the B<-dynroot> option is |
| 502 | to mount the root.afs volume from the default cell on the F</afs> path. The |
| 503 | F</afs> folder and root.afs volume traditionally shows the folders for |
| 504 | F<ThisCell> and other cells as configured by the AFS cell administrator. |
| 505 | |
| 506 | The B<-dynroot> option changes this. Using this option, the AFS client |
| 507 | does not mount the root.afs volume on F</afs>. Instead it uses the |
| 508 | contents of the F<CellServDB> file to populate the listing of cells in |
| 509 | F</afs>. This is known as a DYNamic ROOT. A cell is not contacted until |
| 510 | the path F</afs/I<cellname>> if accessed. This functions similarly to an |
| 511 | automounter. The main advantage of using B<-dynroot> is that the AFS |
| 512 | client will start properly even without network access, whereas the client |
| 513 | not using B<-dynroot> will freeze upon startup if cannot contact the |
| 514 | default cell specified in F<ThisCell> and mount the root.afs |
| 515 | volume. Dynamic root mode is also sometimes called travelling mode because |
| 516 | it works well for laptops which don't always have network connectivity. |
| 517 | |
| 518 | Two advantages of not using dynroot are that listing F</afs> will usually |
| 519 | be faster because the contents of F</afs> are limited to what the AFS |
| 520 | administrator decides and that symbolic links are traditionally created |
| 521 | by the AFS administrator to provide a short name for the cell (i.e. |
| 522 | cellname.domain.com is aliased to cellname). However, with dynroot, the |
| 523 | local system administrator can limit the default contents of F</afs> by |
| 524 | installing a stripped-down F<CellServDB> file, and if dynroot is in effect, |
| 525 | the F<CellAlias> file can be used to provide shortname for common AFS cells |
| 526 | which provides equivalent functionality to the most commonly used symbolic |
| 527 | links. |
| 528 | |
| 529 | When the dynamic root (B<-dynroot>, B<-dynroot-sparse>) and the fake stat |
| 530 | (B<-fakestat>, B<-fakestat-all>) modes are in effect, the cache manager |
| 531 | provides a special directory named F</afs/.:mount> which allows access to |
| 532 | volumes by volume name or ID. The F</afs/.:mount> directory appears to be |
| 533 | empty, but any name in the form of I<cell>:I<volume> will be resolved as a |
| 534 | read-write mount point to the specified volume. For example, the |
| 535 | I<user.jdoe> volume in the I<example.com> cell would be accessible at the |
| 536 | following path: F</afs/.:mount/example.com:user.jdoe>. This dynamic mount |
| 537 | feature is recommended only for temporary access to a volume. Linux-based |
| 538 | cache managers provide this dynamic mount feature even when dynamic root |
| 539 | (B<-dynroot>, B<-dynroot-sparse>) is not in effect. |
| 540 | |
| 541 | =item B<-dynroot-sparse> |
| 542 | |
| 543 | In addition to operating in the manner described for dynroot above, |
| 544 | cells other than the local cell are not shown by default until a lookup |
| 545 | occurs. Cell aliases as set in the CellAliases file are shown as normal, |
| 546 | although they may appear to be dangling links until traversed. |
| 547 | |
| 548 | =item B<-enable_peer_stats> |
| 549 | |
| 550 | Activates the collection of Rx statistics and allocates memory for their |
| 551 | storage. For each connection with a specific UDP port on another machine, |
| 552 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and |
| 553 | so on) sent or received. To display or otherwise access the records, use |
| 554 | the Rx Monitoring API. |
| 555 | |
| 556 | =item B<-enable_process_stats> |
| 557 | |
| 558 | Activates the collection of Rx statistics and allocates memory for their |
| 559 | storage. A separate record is kept for each type of RPC (FetchFile, |
| 560 | GetStatus, and so on) sent or received, aggregated over all connections to |
| 561 | other machines. To display or otherwise access the records, use the Rx |
| 562 | Monitoring API. |
| 563 | |
| 564 | =item B<-fakestat> |
| 565 | |
| 566 | Return fake values for stat calls on cross-cell mounts. This option makes |
| 567 | an C<ls -l> of F</afs> much faster since each cell isn't contacted, and |
| 568 | this and the B<-fakestat-all> options are useful on Mac OS X so that the |
| 569 | Finder program doesn't try to contact every AFS cell the system knows |
| 570 | about. |
| 571 | |
| 572 | Note that, for the purposes of B<-fakestat>, local cellular mounts count |
| 573 | as "cross-cell" mounts. That is, if the local cell is C<localcell>, a |
| 574 | mount for C<localcell:root.cell> will count as a "cross-cell" mount and |
| 575 | so stat calls for it will be faked with B<-fakestat>. In practice, local |
| 576 | cellular mounts are rare and generally discouraged, so this should not |
| 577 | generally make a difference. |
| 578 | |
| 579 | =item B<-fakestat-all> |
| 580 | |
| 581 | Return fake values for stat calls on all mounts, not just cross-cell |
| 582 | mounts. This and the B<-fakestat> options are useful on Mac OS X so that |
| 583 | the Finder program doesn't hang when browsing AFS directories. |
| 584 | |
| 585 | =item B<-files> <I<files in cache>> |
| 586 | |
| 587 | Specifies the number of F<VI<n>> files to create in the cache directory |
| 588 | for a disk cache, overriding the default that is calculated as described |
| 589 | in L</DESCRIPTION>. Each F<VI<n>> file accommodates a chunk of data, and |
| 590 | can grow to a maximum size of 64 KB by default. Do not combine this |
| 591 | argument with the B<-memcache> argument. |
| 592 | |
| 593 | =item B<-files_per_subdir> <I<files per cache subdirectory>> |
| 594 | |
| 595 | Limits the number of cache files in each subdirectory of the cache |
| 596 | directory. The value of the option should be the base-two log of the |
| 597 | number of cache files per cache subdirectory (so 10 for 1024 files, 14 for |
| 598 | 16384 files, and so forth). |
| 599 | |
| 600 | =item B<-help> |
| 601 | |
| 602 | Prints the online help for this command. All other valid options are |
| 603 | ignored. |
| 604 | |
| 605 | =item B<-logfile> <I<log file location>> |
| 606 | |
| 607 | This option is obsolete and no longer has any effect. |
| 608 | |
| 609 | =item B<-inumcalc> <I<method>> |
| 610 | |
| 611 | Specifies the method used by the Cache Manager to generate inode numbers for |
| 612 | files, directories, and symlinks in the AFS filesystem. Valid methods are |
| 613 | C<compat> and C<md5>. The default method is C<compat>. |
| 614 | |
| 615 | When the C<compat> method is in effect, the Cache Manager generates inode |
| 616 | numbers for a given inode by multiplying the AFS volume number by 65536, adding |
| 617 | the result to the AFS vnode number, and finally truncating the result to a |
| 618 | signed 32 bit integer. |
| 619 | |
| 620 | When the C<md5> method is in effect, the Cache Manager generates inode numbers |
| 621 | for a given inode by calculating the MD5 digest of a combination of the cell |
| 622 | number, volume number, and vnode number. The result is truncated to a signed 32 |
| 623 | bit integer. The C<md5> method is computationally more expensive but greatly |
| 624 | reduces the chance for inode number collisions, especially when volumes from |
| 625 | multiple cells are mounted within the AFS filesystem. |
| 626 | |
| 627 | =item B<-mem_alloc_sleep> |
| 628 | |
| 629 | This option is obsolete and no longer has any effect. |
| 630 | |
| 631 | =item B<-memcache> |
| 632 | |
| 633 | Initializes a memory cache rather than a disk cache. Do not combine this |
| 634 | flag with the B<-files> argument. |
| 635 | |
| 636 | =item B<-mountdir> <I<mount location>> |
| 637 | |
| 638 | Names the local disk directory on which to mount the root of the AFS |
| 639 | filespace. This value overrides the default defined in the first field of |
| 640 | the F</usr/vice/etc/cacheinfo> file. If a value other than the F</afs> |
| 641 | directory is used, the machine cannot access the filespace of cells that |
| 642 | do use that value. |
| 643 | |
| 644 | =item B<-nomount> |
| 645 | |
| 646 | Do not mount AFS on startup. The afs global mount must be mounted via |
| 647 | some other means. This is useful on Mac OS X where /afs is sometimes |
| 648 | mounted in /Network/afs like other network file systems. |
| 649 | |
| 650 | =item B<-nosettime> |
| 651 | |
| 652 | This option is obsolete and no longer has any effect. The operating system |
| 653 | provided time keeping daemons should be used to maintain the system time. |
| 654 | |
| 655 | =item B<-prealloc> <I<number of preallocated blocks>> |
| 656 | |
| 657 | Specifies the number of pieces of memory to preallocate for the Cache |
| 658 | Manager's internal use. The default initial value is C<400>, but the Cache |
| 659 | Manager dynamically allocates more memory as it needs it. |
| 660 | |
| 661 | =item B<-rmtsys> |
| 662 | |
| 663 | Initializes an additional daemon to execute AFS-specific system calls on |
| 664 | behalf of NFS client machines. Use this flag only if the machine is an |
| 665 | NFS/AFS translator machine serving users of NFS client machines who |
| 666 | execute AFS commands. |
| 667 | |
| 668 | =item B<-rootvol> <I<name of AFS root volume>> |
| 669 | |
| 670 | Names the read/write volume corresponding to the root directory for the |
| 671 | AFS file tree (which is usually the F</afs> directory). This value |
| 672 | overrides the default of the C<root.afs> volume. This option is ignored if |
| 673 | B<-dynroot> is given. |
| 674 | |
| 675 | =item B<-rxbind> |
| 676 | |
| 677 | Bind the Rx socket (one interface only). |
| 678 | |
| 679 | =item B<-rxmaxfrags> <I<max # of fragments>> |
| 680 | |
| 681 | Set a limit for the maximum number of UDP fragments Rx will send per Rx |
| 682 | packet, and the maximum number of fragments Rx thinks it can receive when |
| 683 | advertising its receive size to peers. Practically speaking, setting this |
| 684 | option means that you will not see Rx data packets that are broken into more |
| 685 | than N fragments, where N is the value specified for this option. Setting this |
| 686 | option to 1 effectively prevents fragmentation, and can be useful when dealing |
| 687 | with networking equipment that does not properly handle UDP fragments. |
| 688 | |
| 689 | Note that this option just specifies a maximum. The actual number of fragments |
| 690 | seen on the wire may be less than what is specified, depending on the |
| 691 | configuration of the peer. |
| 692 | |
| 693 | =item B<-rxmaxmtu> <I<value for maximum MTU>> |
| 694 | |
| 695 | Set a limit for the largest maximum transfer unit (network packet size) that |
| 696 | the AFS client on this machine will be willing to transmit. This switch can |
| 697 | be used where an artificial limit on the network precludes packets as large |
| 698 | as the discoverable MTU from being transmitted successfully. |
| 699 | |
| 700 | =item B<-rxpck> <I<value for rx_extraPackets>> |
| 701 | |
| 702 | Set rx_extraPackets to this value. This sets the number of extra Rx |
| 703 | packet structures that are available to handle Rx connections. This |
| 704 | value should be increased if the "rxdebug 127.0.0.1 -port 7001 |
| 705 | -rxstats" command shows no free Rx packets. Increasing this value may |
| 706 | improve OpenAFS client performance in some circumstances. |
| 707 | |
| 708 | =item B<-settime> |
| 709 | |
| 710 | This option is obsolete and no longer has any effect. The operating system |
| 711 | provided time keeping daemons should be used to maintain the system time. |
| 712 | |
| 713 | =item B<-shutdown> |
| 714 | |
| 715 | Shuts down the Cache Manager. Before calling B<afsd> with this option, |
| 716 | unmount the AFS file system with B<umount>. |
| 717 | |
| 718 | =item B<-splitcache> <I<RW/RO Ratio>> |
| 719 | |
| 720 | This allows the user to set a certain percentage of the AFS cache be |
| 721 | reserved for read/write content and the rest to be reserved for read-only |
| 722 | content. The ratio should be written as a fraction. For example, |
| 723 | C<-splitcache 75/25> devotes 75% of your cache space to read/write content |
| 724 | and 25% to read-only. |
| 725 | |
| 726 | =item B<-stat> <I<number of stat entries>> |
| 727 | |
| 728 | Specifies the number of entries to allocate in the machine's memory for |
| 729 | recording status information about the AFS files in the cache. If this value |
| 730 | is not specified, the number of stat entires will be autotuned based on the |
| 731 | size of the disk cache. |
| 732 | |
| 733 | =item B<-verbose> |
| 734 | |
| 735 | Generates a detailed trace of the B<afsd> program's actions on the |
| 736 | standard output stream. |
| 737 | |
| 738 | =item B<-volumes> <I<number of volume entries>> |
| 739 | |
| 740 | Specifies the number of memory structures to allocate for storing volume |
| 741 | location information. The default value is C<200>. |
| 742 | |
| 743 | =item B<-disable-dynamic-vcaches> |
| 744 | |
| 745 | By default, dynamic vcache overrides the B<-stat> option by using the value of |
| 746 | B<-stat> (or the default) as the initial size of the stat (or vcache) pool and |
| 747 | increases the pool dynamically as needed on supported platforms. This flag will |
| 748 | disable this new functionality and honor the '-stat' setting. |
| 749 | |
| 750 | =item B<-waitclose> |
| 751 | |
| 752 | Has no effect on the operation of the Cache Manager. The behavior it |
| 753 | affected in previous versions of the Cache Manager, to perform synchronous |
| 754 | writes to the File Server, is now the default behavior. To perform |
| 755 | asynchronous writes in certain cases, use the B<fs storebehind> command. |
| 756 | |
| 757 | =item B<-volume-ttl> |
| 758 | |
| 759 | Specifies the maximum amount of time the Cache Manager will cache volume |
| 760 | information retrieved from VL Servers. |
| 761 | |
| 762 | By default, the Cache Manager will cache read-only volume information as long |
| 763 | as a volume callback is held for that volume. The callback may be held as long |
| 764 | as files in the read-only volume are being accessed, with no upper limit. For |
| 765 | read/write volumes, by default the Cache Manager will cache volume information |
| 766 | forever, until a fileserver returns a volume-level error in response to |
| 767 | accessing files in that volume. |
| 768 | |
| 769 | Use the B<-volume-ttl> option to specify the maximum amount of time in seconds |
| 770 | that volume information will be cached, regardless of connectivity to the |
| 771 | fileservers. Lowering this value can make the Cache Manager recover more |
| 772 | quickly from certain volume/fileserver errors, but will increase the load on |
| 773 | the VL Servers for contacted cells. |
| 774 | |
| 775 | A typical value is 7200 seconds (2 hours), which is the same as the default |
| 776 | callback duration for read-only volumes. The minimum valid value is 600 seconds |
| 777 | (10 minutes). |
| 778 | |
| 779 | =back |
| 780 | |
| 781 | =head1 EXAMPLES |
| 782 | |
| 783 | The B<afsd> command is normally included in the machine's AFS |
| 784 | initialization file, rather than typed at the command shell prompt. For |
| 785 | most disk caches, the appropriate form is |
| 786 | |
| 787 | % /usr/vice/etc/afsd |
| 788 | |
| 789 | The following command is appropriate when enabling a machine to act as an |
| 790 | NFS/AFS Translator machine serving more than five users. |
| 791 | |
| 792 | % /usr/vice/etc/afsd -daemons 4 -rmtsys |
| 793 | |
| 794 | The following command initializes a memory cache and sets chunk size to 16 |
| 795 | KB (2^14). |
| 796 | |
| 797 | % /usr/vice/etc/afsd -memcache -chunksize 14 |
| 798 | |
| 799 | =head1 PRIVILEGE REQUIRED |
| 800 | |
| 801 | The issuer must be logged in as the local superuser root. |
| 802 | |
| 803 | =head1 SEE ALSO |
| 804 | |
| 805 | L<fs_newcell(1)>, |
| 806 | L<afs_cache(5)>, |
| 807 | L<CellServDB(5)>, |
| 808 | L<cacheinfo(5)> |
| 809 | |
| 810 | RFC 5864 L<http://www.ietf.org/rfc/rfc5864.txt> |
| 811 | RFC 1183 L<http://www.ietf.org/rfc/rfc1183.txt> |
| 812 | |
| 813 | =head1 COPYRIGHT |
| 814 | |
| 815 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. |
| 816 | |
| 817 | This documentation is covered by the IBM Public License Version 1.0. It |
| 818 | was converted from HTML to POD by software written by Chas Williams and |
| 819 | Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |