src/man/afsd.1

   1 afsd                       AFS Commands                   afsd
   2
   3
   4 NAME
   5
   6    afsd  -- initialize   Cache   Manager   and  start  related
   7
   8                        daemons.
   9
  10
  11    afsd  [-blocks <number of cache blocks>] [-files <number of
  12    cache files>]
  13    [-stat <number of status cache entries>] [-rootvol <root
  14    volume>]
  15    [-cachedir <cache directory>]  [-mountdir <AFS mount
  16    directory>]
  17    [-verbose]  [-debug]  [-nosettime]
  18    [-daemons <number of background daemons>]  [-rmtsys]
  19    [-memcache]  [-dcache <# entries>]  [-chunksize <chunk
  20    exponent>]
  21
  22 ACCEPTABLE ABBREVIATIONS
  23
  24    This command does not use the syntax conventions of the  AFS
  25    command  suites.    Therefore,  "afsd"  and all switches and
  26    flags must be typed in full.
  27
  28 DESCRIPTION
  29
  30    Initializes the Cache Manager on an AFS  client  machine  by
  31    transferring   AFS-related  configuration  information  into
  32    kernel  memory  and  starting   several   daemons.      More
  33    specifically, afsd
  34
  35       - sets  a  field in kernel memory that defines which
  36         cell  the  machine  belongs  to.      Some   Cache
  37         Manager-internal   operations   and  system  calls
  38         consult this field to learn which cell to  execute
  39         in.    (The  AFS  command  interpreters  refer  to
  40         /usr/vice/etc/ThisCell instead.)
  41
  42         This information is transferred  into  the  kernel
  43         from the file /usr/vice/etc/ThisCell and cannot be
  44         changed until afsd runs again.
  45
  46       - places in kernel memory  the  names  and  Internet
  47         addresses  of  the database server machines in the
  48         local cell and (optionally) foreign  cells.    The
  49         appearance of a cell's database server machines in
  50         this list enables the  Cache  Manager  to  contact
  51         them and so to access files in the cell.  Omission
  52         of a cell from this list, or incorrect information
  53         about  its  database server machines, prevents the
  54         Cache Manager from accessing files in it.
  55
  56         This information is transferred  into  the  kernel
  57         from  the  file  /usr/vice/etc/CellServDB.   After
  58         initialization, use the  fs   newcell  command  to
  59         change  the kernel-resident list without having to
  60         reboot.
  61
  62       - determines whether the cache  is  on  disk  or  in
  63         machine  memory.    The  default  is to use a disk
  64         cache.  If the  -memcache  argument  is  provided,
  65
  66
  67
  68         space  is allocated in machine memory for caching,
  69         and disk space is not used even if the machine has
  70         a disk.
  71
  72       - defines  the  name  of  the  local  disk directory
  73         devoted to caching, when -memcache  is  not  used.
  74         If  necessary, afsd creates the directory (as long
  75         as its parent directory  exists).    It  does  not
  76         remove  from  the disk the directory that formerly
  77         served this function, if any.
  78
  79         The     second     field     in      the      file
  80         /usr/vice/etc/cacheinfo  is  the  source  for this
  81         name, and the standard value  is  /usr/vice/cache.
  82         Use  the  -cachedir argument to override the value
  83         from cacheinfo.
  84
  85       - sets the size of the  cache,  for  both  disk  and
  86         memory caches.
  87
  88         The  afsd  program consults the third field in the
  89         file /usr/vice/etc/cacheinfo to learn the  default
  90         cache  size  in kilobyte blocks.  The value should
  91         not exceed 90% to 95% of the disk space  available
  92         on  the  cache partition (with a disk cache) or of
  93         the machine's memory (with a memory cache).   This
  94         is   because   the   cache  implementation  itself
  95         requires a small amount of disk or machine memory.
  96
  97         For either a disk or memory cache, use the -blocks
  98         argument to override the value from cacheinfo.
  99
 100         For  a  memory cache, the issuer can also override
 101         the cacheinfo value by providing either
 102
 103            * both -dcache  and  -chunksize,  to  set  both
 104              number  of dcache entries and chunk size (see
 105              below for definition  of  these  parameters).
 106              In   this   case,  afsd  derives  cache  size
 107              (overriding   the   cacheinfo    value)    by
 108              multiplying  the  two  values.    Using  this
 109              combination  is  not   recommended,   as   it
 110              requires    the   issuer   to   perform   the
 111              calculation  beforehand  to   determine   the
 112              resulting cache size.
 113
 114            * -dcache by itself. In this case, afsd derives
 115              cache size (overriding the  cacheinfo  value)
 116              by  multiplying  -dcache by the default chunk
 117              size of 8 kilobytes.  Using this argument  is
 118              not recommended, as it requires the issuer to
 119              perform   the   calculation   beforehand   to
 120              determine the resulting cache size.
 121
 122         For  a  disk cache, the value defined in cacheinfo
 123         or with -blocks is  an  absolute  upper  limit  on
 124         cache  size;  values  provided for other arguments
 125         cannot result in a larger cache.
 126
 127         After  initialization,  use   fs setcachesize   to
 128         change  the size of a disk cache without having to
 129
 130
 131
 132         reboot;  the  value  set  with  that  command   is
 133         overridden   the   next   time  afsd  runs.    The
 134         fs setcachesize command does not work  for  memory
 135         caches.  Instead, the machine must be rebooted.
 136
 137       - sets  the  size  of  each  "chunk"  of data in the
 138         cache, and by implication the amount of data  that
 139         the Cache Manager requests at a time from the File
 140         Server (how much data per "fetch" RPC,  since  AFS
 141         uses partial file transfer).
 142
 143         For a disk cache, each chunk is called a "V file",
 144         so this parameter sets the maximum size of each  V
 145         file;  the default is 64 kilobytes.  See below for
 146         more on V files.
 147
 148         For a memory cache, each chunk is a collection  of
 149         memory blocks allocated together, so this sets the
 150         size  of  each  collection;  the  default   is   8
 151         kilobytes.
 152
 153         For  both  types  of  cache,  use  the  -chunksize
 154         argument to change the default  chunk  size.    To
 155         guarantee proper chunk sizes, the integer provided
 156         is used as an exponent on the number  2;  see  the
 157         ARGUMENTS  section  for  details.    For  a memory
 158         cache, if total cache size divided by  chunk  size
 159         leaves a remainder, afsd rounds down the number of
 160         dcache entries. resulting in  a  slightly  smaller
 161         cache (see below for more on dcache entries).
 162
 163       - sets  the number of empty "V files" created in the
 164         cache directory for a disk cache.  Each file is  a
 165         cache  chunk, and the Cache Manager caches data in
 166         them as needed.  By default,  each  "V"  file  can
 167         accommodate  up  to 64 kilobytes of data, since 64
 168         kilobytes is the default  size  of  a  disk  cache
 169         chunk.
 170
 171         A  memory cache cannot use V files because it does
 172         not use disk memory; instead the number of  chunks
 173         is  equivalent  to  the number of "dcache entries"
 174         (see below).
 175
 176         The default number of V files  is  1000;  use  the
 177         -files  argument to override it.  Since by default
 178         each V file can accommodate 64 kilobytes, the only
 179         reason  to increase from the default of 1000 is if
 180         the cache size is greater than about 64  megabytes
 181         (or  the  chunk  size  has  been  changed with the
 182         -chunksize argument discussed above).
 183
 184       - sets the number of "dcache entries"  allocated  in
 185         machine  memory  for storing information about the
 186         chunks in the cache.
 187
 188         With     a     disk      cache,      the      file
 189         /usr/vice/cache/CacheItems  on  disk  contains one
 190         entry for each V file.   Some  of  the  CacheItems
 191         entries,  by default 100, are duplicated as dcache
 192         entries in machine memory for quicker access.
 193
 194
 195
 196         With a memory cache, there is no CacheItems  file,
 197         so  all  information about cache chunks must be in
 198         memory as dcache  entries.    There  must  be  one
 199         dcache entry for each cache chunk, so for a memory
 200         cache number of dcache entries  equals  number  of
 201         cache  chunks.    There  is  no  default number of
 202         dcache entries for a memory cache;  instead,  afsd
 203         derives it by dividing cache size by chunk size.
 204
 205         Use  the  -dcache  argument  to  set the number of
 206         dcache entries.    This  is  not  recommended  for
 207         either  type  of  cache.  Increasing the number of
 208         dcache  entries  for  a  disk  cache  may  improve
 209         performance  marginally  because  more entries are
 210         retrieved from memory rather than from  disk,  but
 211         is  not  generally necessary.  Using this argument
 212         is not recommended for a memory cache  because  it
 213         requires the issuer to pre-calculate cache size by
 214         multiplying this value times  chunk  size  (either
 215         the   default   8   kilobytes   or  the  value  of
 216         -chunksize).
 217
 218       - sets the number of  "stat"  entries  available  in
 219         machine  memory  for  caching  status  information
 220         about cached AFS files.
 221
 222         The default is 300;  use  the  -stat  argument  to
 223         override the default.
 224
 225       - defines  the  directory in the machine's file name
 226         space at which the AFS file tree is mounted.
 227
 228         The     first     field      in      the      file
 229         /usr/vice/etc/cacheinfo  is  the  source  for  the
 230         default directory name.   The  standard  value  is
 231         /afs.   Use the -mountdir argument to override the
 232         value from cacheinfo.
 233
 234       - defines which volume corresponds to  the  root  of
 235         the AFS file tree.
 236
 237         The default is root.afs; use the -rootvol argument
 238         to override it.  Note  that  although  the  volume
 239         name  should  be  given  in the "base" (ReadWrite)
 240         form, the  Cache  Manager  retains  its  bias  for
 241         accessing  the  ReadOnly  version of the volumeMin
 242         the  default  case,  root.afs.readonlyMif  it   is
 243         available.
 244
 245       - randomly  selects  a  file  server  machine in the
 246         local cell as the source for the  "correct"  time.
 247         Every  five minutes thereafter, the local clock is
 248         adjusted (if necessary) to match the  file  server
 249         machine's clock.
 250
 251         Use  the  -nosettime  flag  to  prevent  afsd from
 252         selecting a time standard.   This  is  recommended
 253         only  on file server machines that are also acting
 254         as clients.  File  server  machines  maintain  the
 255         correct  time  using  the  Network  Time  Protocol
 256         Daemon instead.
 257
 258
 259
 260    In addition to setting cache configuration parameters,  afsd
 261    starts  up  the  following  three types of daemons.  On most
 262    system types, these daemons appear as  nameless  entries  in
 263    the output of the ps command:
 264
 265       - a  "callback"  daemon  that handles callbacks.  It
 266         also  responds  to  the  File  Server's   periodic
 267         probes,  which  check  that  the client machine is
 268         still alive.
 269
 270       - a  "maintenance"  daemon  that  performs   routine
 271         periodic maintenance tasks, including
 272
 273            * performing garbage collection
 274
 275            * synchronizing files
 276
 277            * probing the fileserver process on file server
 278              machines every few minutes
 279
 280            * refreshing information from ReadOnly  volumes
 281              once per hour
 282
 283            * doing  delayed  writes for NFS clients if the
 284              machine is running the NFS/AFS Translator
 285
 286            * keeping the machine's clock synchronized with
 287              the chosen file server machine's
 288
 289       - "background"  daemons  that improve performance by
 290         pre-fetching  files  and   performing   background
 291         (delayed) writes of saved data into AFS.
 292
 293         The  default  number  of  background daemons is 2,
 294         usually enough to  handle  up  to  5  simultaneous
 295         users  of  the machine.  Use the -daemons argument
 296         to increase the number of background  daemons,  if
 297         the  machine  serves  more  users.  No more than 6
 298         background daemons should ever be necessary.
 299
 300    The default number of daemons is four (one callback  daemon,
 301    one  maintenance  daemon,  and two background daemons).  The
 302    issuer can alter only the number of background daemons; afsd
 303    always  initializes  one callback daemon and one maintenance
 304    daemon.
 305
 306    AFS includes three configuration scripts that can be used to
 307    modify  some  Cache  Manager  parameters on a client machine
 308    that uses a disk cache.  Named  rc.afsd.small,  rc.afsd.med,
 309    and   rc.afsd.large,   the   configuration  scripts  specify
 310    suitable, predefined values for the  afsd  command's  -stat,
 311    -dcache,  -daemons,  and  -volumes  switches.    They define
 312    increasingly greater values for these switches according  to
 313    the  configuration  and usage patterns of the client machine
 314    on which the afsd command is run.  Refer to the  AFS  System
 315    Administrator's Guide for more information about the scripts
 316    and how to use them.
 317
 318 ARGUMENTS
 319
 320    -blocks   specifies the number of kilobyte blocks to be made
 321
 322
 323
 324              available  for  caching  in  the  machine's  cache
 325              directory (for a disk  cache)  or  memory  (for  a
 326              memory  cache),  overriding the default defined in
 327              the third field of  /usr/vice/etc/cacheinfo.    It
 328              should  not  exceed 90% to 95% of the actual space
 329              available.   If  using  a  memory  cache,  do  not
 330              combine this argument with -dcache, since doing so
 331              could result in a  chunk  size  that  was  not  an
 332              exponent of 2.
 333
 334    -files    specifies  the  number of V files to be created in
 335              the cache directory for a disk  cache,  overriding
 336              the  default of 1000.  Each V file can accommodate
 337              a "chunk" of data, which for a disk  cache  is  64
 338              kilobytes by default.  Thus the default of 1000 is
 339              adequate for any cache smaller than  64  megabytes
 340              (unless  chunk  size  is changed with -chunksize).
 341              Do not combine this argument with -memcache.
 342
 343    -stat     specifies the number of entries in  the  machine's
 344              memory  for recording status information about the
 345              AFS files in the cache.  This value overrides  the
 346              default of 300.
 347
 348    -rootvol  names  the  Read Write volume corresponding to the
 349              root directory for the AFS  file  tree  (which  is
 350              usually  /afs).   This value overrides the default
 351              of root.afs.
 352
 353    -cachedir names the local disk directory to be used  as  the
 354              cache.    This value overrides the default defined
 355              in the  second  field  of  /usr/vice/etc/cacheinfo
 356              (typically, /usr/vice/cache).
 357
 358    -mountdir names  the  local disk directory on which to mount
 359              the AFS file  tree.    This  value  overrides  the
 360              default    defined   in   the   first   field   of
 361              /usr/vice/etc/cacheinfo  (typically,  /afs).    If
 362              /afs  is  not  used, the machine cannot access the
 363              AFS global name space.
 364
 365    -daemons  specifies the number of  "background"  daemons  to
 366              run   on  the  machine.    These  daemons  improve
 367              efficiency by doing  pre-fetching  and  background
 368              writing  of  saved data.  This value overrides the
 369              default of 2, which  is  adequate  for  a  machine
 370              serving  up to five users.  It does not change the
 371              number of  "callback"  or  "maintenance"  daemons,
 372              which is always one each.
 373
 374    -verbose  causes  afsd  to  produce a more detailed trace of
 375              its activities than the default one.    The  trace
 376              displays  on  standard  out  (stdout) unless it is
 377              piped into a file.
 378
 379    -debug    causes afsd to produce a highly detailed trace  of
 380              its  activities, potentially useful to a developer
 381              for  debugging  purposes.    The  trace  goes   to
 382              standard output (stdout) by default.
 383
 384    -nosettime
 385
 386
 387
 388              prevents the machine from selecting  at  random  a
 389              local  file  server machine to act as a source for
 390              the "correct" time.  If this flag is omitted,  the
 391              machine  selects  a  file server machine as a time
 392              standard,  and  every  five   minutes   thereafter
 393              adjusts  its  clock  to  avoid  drifting  from the
 394              standard.
 395
 396    -rmtsys   initializes an additional  "remote-system"  daemon
 397              to  execute AFS-specific system calls on behalf of
 398              NFS client machines.  This flag is necessary  only
 399              if  the  machine is an NFS/AFS translator machine,
 400              and if users on its NFS clients  want  to  execute
 401              AFS commands.
 402
 403    -memcache causes  afsd  to  initialize a memory cache rather
 404              than a disk cache.  Do not combine this flag  with
 405              -files.
 406
 407    -dcache   sets  the  number  of  "dcache entries" in memory,
 408              which are used to store  information  about  cache
 409              chunks.    For  a  disk  cache, this overrides the
 410              default of 100.  For a memory cache, this argument
 411              effectively  sets the number of cache chunks.  Use
 412              of this argument is not recommended for  a  memory
 413              cache,   because   it   requires   the  issuer  to
 414              pre-calculate  the  resulting  total  cache   size
 415              (derived by multiplying this value by chunk size).
 416              Do not combine this argument with  -blocks,  since
 417              doing so could result in a chunk size that was not
 418              an exponent of 2.
 419
 420    -chunksize
 421              sets  the  size  of each cache chunk.  The integer
 422              provided, which should be between  0  and  20,  is
 423              used as an exponent on the number 2.  It overrides
 424                                                      16
 425              the default of 16 for a  disk  cache  (2    is  64
 426                                                         13
 427              kilobytes)  and  13  for  a memory cache (2   is 8
 428              kilobytes).  A value of 0 or less, or greater than
 429              20,  sets  chunk  size to the appropriate default.
 430              Values less than 10 (which sets chunk  size  to  a
 431                          10
 432              kilobyte,  2  )  are  not  recommended.  Combining
 433              this argument  with  -dcache  is  not  recommended
 434              because  it requires that the issuer pre-calculate
 435              the cache size that results.
 436
 437 EXAMPLE
 438
 439    This command is normally included in an initialization  file
 440    such  as  /etc/rc,  rather  than  typed at the command shell
 441    prompt.  For most disk caches, the appropriate form is
 442
 443    /usr/vice/etc/afsd
 444
 445    The following is appropriate when enabling a machine to  act
 446    as  an  NFS/AFS  Translator  machine  serving more than five
 447    users.
 448
 449    /usr/vice/etc/afsd -daemons 4 -rmtsys
 450
 451
 452
 453    The following initializes a memory cache and sets chunk size
 454                      14
 455    to 16 kilobytes (2  ).
 456
 457    /usr/vice/etc/afsd -memcache -chunksize 14
 458
 459 PRIVILEGE REQUIRED
 460
 461    Issuer must be logged into the machine's UNIX file system as
 462    "root."