afsd                       AFS Commands                   afsd


NAME

   afsd  -- initialize   Cache   Manager   and  start  related

                       daemons.


   afsd  [-blocks <number of cache blocks>] [-files <number of
   cache files>]
   [-stat <number of status cache entries>] [-rootvol <root
   volume>]
   [-cachedir <cache directory>]  [-mountdir <AFS mount
   directory>]
   [-verbose]  [-debug]  [-nosettime]
   [-daemons <number of background daemons>]  [-rmtsys]
   [-memcache]  [-dcache <# entries>]  [-chunksize <chunk
   exponent>]

ACCEPTABLE ABBREVIATIONS

   This command does not use the syntax conventions of the  AFS
   command  suites.    Therefore,  "afsd"  and all switches and
   flags must be typed in full.

DESCRIPTION

   Initializes the Cache Manager on an AFS  client  machine  by
   transferring   AFS-related  configuration  information  into
   kernel  memory  and  starting   several   daemons.      More
   specifically, afsd

      - sets  a  field in kernel memory that defines which
        cell  the  machine  belongs  to.      Some   Cache
        Manager-internal   operations   and  system  calls
        consult this field to learn which cell to  execute
        in.    (The  AFS  command  interpreters  refer  to
        /usr/vice/etc/ThisCell instead.)

        This information is transferred  into  the  kernel
        from the file /usr/vice/etc/ThisCell and cannot be
        changed until afsd runs again.

      - places in kernel memory  the  names  and  Internet
        addresses  of  the database server machines in the
        local cell and (optionally) foreign  cells.    The
        appearance of a cell's database server machines in
        this list enables the  Cache  Manager  to  contact
        them and so to access files in the cell.  Omission
        of a cell from this list, or incorrect information
        about  its  database server machines, prevents the
        Cache Manager from accessing files in it.

        This information is transferred  into  the  kernel
        from  the  file  /usr/vice/etc/CellServDB.   After
        initialization, use the  fs   newcell  command  to
        change  the kernel-resident list without having to
        reboot.

      - determines whether the cache  is  on  disk  or  in
        machine  memory.    The  default  is to use a disk
        cache.  If the  -memcache  argument  is  provided,



        space  is allocated in machine memory for caching,
        and disk space is not used even if the machine has
        a disk.

      - defines  the  name  of  the  local  disk directory
        devoted to caching, when -memcache  is  not  used.
        If  necessary, afsd creates the directory (as long
        as its parent directory  exists).    It  does  not
        remove  from  the disk the directory that formerly
        served this function, if any.

        The     second     field     in      the      file
        /usr/vice/etc/cacheinfo  is  the  source  for this
        name, and the standard value  is  /usr/vice/cache.
        Use  the  -cachedir argument to override the value
        from cacheinfo.

      - sets the size of the  cache,  for  both  disk  and
        memory caches.

        The  afsd  program consults the third field in the
        file /usr/vice/etc/cacheinfo to learn the  default
        cache  size  in kilobyte blocks.  The value should
        not exceed 90% to 95% of the disk space  available
        on  the  cache partition (with a disk cache) or of
        the machine's memory (with a memory cache).   This
        is   because   the   cache  implementation  itself
        requires a small amount of disk or machine memory.

        For either a disk or memory cache, use the -blocks
        argument to override the value from cacheinfo.

        For  a  memory cache, the issuer can also override
        the cacheinfo value by providing either

           * both -dcache  and  -chunksize,  to  set  both
             number  of dcache entries and chunk size (see
             below for definition  of  these  parameters).
             In   this   case,  afsd  derives  cache  size
             (overriding   the   cacheinfo    value)    by
             multiplying  the  two  values.    Using  this
             combination  is  not   recommended,   as   it
             requires    the   issuer   to   perform   the
             calculation  beforehand  to   determine   the
             resulting cache size.

           * -dcache by itself. In this case, afsd derives
             cache size (overriding the  cacheinfo  value)
             by  multiplying  -dcache by the default chunk
             size of 8 kilobytes.  Using this argument  is
             not recommended, as it requires the issuer to
             perform   the   calculation   beforehand   to
             determine the resulting cache size.

        For  a  disk cache, the value defined in cacheinfo
        or with -blocks is  an  absolute  upper  limit  on
        cache  size;  values  provided for other arguments
        cannot result in a larger cache.

        After  initialization,  use   fs setcachesize   to
        change  the size of a disk cache without having to



        reboot;  the  value  set  with  that  command   is
        overridden   the   next   time  afsd  runs.    The
        fs setcachesize command does not work  for  memory
        caches.  Instead, the machine must be rebooted.

      - sets  the  size  of  each  "chunk"  of data in the
        cache, and by implication the amount of data  that
        the Cache Manager requests at a time from the File
        Server (how much data per "fetch" RPC,  since  AFS
        uses partial file transfer).

        For a disk cache, each chunk is called a "V file",
        so this parameter sets the maximum size of each  V
        file;  the default is 64 kilobytes.  See below for
        more on V files.

        For a memory cache, each chunk is a collection  of
        memory blocks allocated together, so this sets the
        size  of  each  collection;  the  default   is   8
        kilobytes.

        For  both  types  of  cache,  use  the  -chunksize
        argument to change the default  chunk  size.    To
        guarantee proper chunk sizes, the integer provided
        is used as an exponent on the number  2;  see  the
        ARGUMENTS  section  for  details.    For  a memory
        cache, if total cache size divided by  chunk  size
        leaves a remainder, afsd rounds down the number of
        dcache entries. resulting in  a  slightly  smaller
        cache (see below for more on dcache entries).

      - sets  the number of empty "V files" created in the
        cache directory for a disk cache.  Each file is  a
        cache  chunk, and the Cache Manager caches data in
        them as needed.  By default,  each  "V"  file  can
        accommodate  up  to 64 kilobytes of data, since 64
        kilobytes is the default  size  of  a  disk  cache
        chunk.

        A  memory cache cannot use V files because it does
        not use disk memory; instead the number of  chunks
        is  equivalent  to  the number of "dcache entries"
        (see below).

        The default number of V files  is  1000;  use  the
        -files  argument to override it.  Since by default
        each V file can accommodate 64 kilobytes, the only
        reason  to increase from the default of 1000 is if
        the cache size is greater than about 64  megabytes
        (or  the  chunk  size  has  been  changed with the
        -chunksize argument discussed above).

      - sets the number of "dcache entries"  allocated  in
        machine  memory  for storing information about the
        chunks in the cache.

        With     a     disk      cache,      the      file
        /usr/vice/cache/CacheItems  on  disk  contains one
        entry for each V file.   Some  of  the  CacheItems
        entries,  by default 100, are duplicated as dcache
        entries in machine memory for quicker access.



        With a memory cache, there is no CacheItems  file,
        so  all  information about cache chunks must be in
        memory as dcache  entries.    There  must  be  one
        dcache entry for each cache chunk, so for a memory
        cache number of dcache entries  equals  number  of
        cache  chunks.    There  is  no  default number of
        dcache entries for a memory cache;  instead,  afsd
        derives it by dividing cache size by chunk size.

        Use  the  -dcache  argument  to  set the number of
        dcache entries.    This  is  not  recommended  for
        either  type  of  cache.  Increasing the number of
        dcache  entries  for  a  disk  cache  may  improve
        performance  marginally  because  more entries are
        retrieved from memory rather than from  disk,  but
        is  not  generally necessary.  Using this argument
        is not recommended for a memory cache  because  it
        requires the issuer to pre-calculate cache size by
        multiplying this value times  chunk  size  (either
        the   default   8   kilobytes   or  the  value  of
        -chunksize).

      - sets the number of  "stat"  entries  available  in
        machine  memory  for  caching  status  information
        about cached AFS files.

        The default is 300;  use  the  -stat  argument  to
        override the default.

      - defines  the  directory in the machine's file name
        space at which the AFS file tree is mounted.

        The     first     field      in      the      file
        /usr/vice/etc/cacheinfo  is  the  source  for  the
        default directory name.   The  standard  value  is
        /afs.   Use the -mountdir argument to override the
        value from cacheinfo.

      - defines which volume corresponds to  the  root  of
        the AFS file tree.

        The default is root.afs; use the -rootvol argument
        to override it.  Note  that  although  the  volume
        name  should  be  given  in the "base" (ReadWrite)
        form, the  Cache  Manager  retains  its  bias  for
        accessing  the  ReadOnly  version of the volumeMin
        the  default  case,  root.afs.readonlyMif  it   is
        available.

      - randomly  selects  a  file  server  machine in the
        local cell as the source for the  "correct"  time.
        Every  five minutes thereafter, the local clock is
        adjusted (if necessary) to match the  file  server
        machine's clock.

        Use  the  -nosettime  flag  to  prevent  afsd from
        selecting a time standard.   This  is  recommended
        only  on file server machines that are also acting
        as clients.  File  server  machines  maintain  the
        correct  time  using  the  Network  Time  Protocol
        Daemon instead.



   In addition to setting cache configuration parameters,  afsd
   starts  up  the  following  three types of daemons.  On most
   system types, these daemons appear as  nameless  entries  in
   the output of the ps command:

      - a  "callback"  daemon  that handles callbacks.  It
        also  responds  to  the  File  Server's   periodic
        probes,  which  check  that  the client machine is
        still alive.

      - a  "maintenance"  daemon  that  performs   routine
        periodic maintenance tasks, including

           * performing garbage collection

           * synchronizing files

           * probing the fileserver process on file server
             machines every few minutes

           * refreshing information from ReadOnly  volumes
             once per hour

           * doing  delayed  writes for NFS clients if the
             machine is running the NFS/AFS Translator

           * keeping the machine's clock synchronized with
             the chosen file server machine's

      - "background"  daemons  that improve performance by
        pre-fetching  files  and   performing   background
        (delayed) writes of saved data into AFS.

        The  default  number  of  background daemons is 2,
        usually enough to  handle  up  to  5  simultaneous
        users  of  the machine.  Use the -daemons argument
        to increase the number of background  daemons,  if
        the  machine  serves  more  users.  No more than 6
        background daemons should ever be necessary.

   The default number of daemons is four (one callback  daemon,
   one  maintenance  daemon,  and two background daemons).  The
   issuer can alter only the number of background daemons; afsd
   always  initializes  one callback daemon and one maintenance
   daemon.

   AFS includes three configuration scripts that can be used to
   modify  some  Cache  Manager  parameters on a client machine
   that uses a disk cache.  Named  rc.afsd.small,  rc.afsd.med,
   and   rc.afsd.large,   the   configuration  scripts  specify
   suitable, predefined values for the  afsd  command's  -stat,
   -dcache,  -daemons,  and  -volumes  switches.    They define
   increasingly greater values for these switches according  to
   the  configuration  and usage patterns of the client machine
   on which the afsd command is run.  Refer to the  AFS  System
   Administrator's Guide for more information about the scripts
   and how to use them.

ARGUMENTS

   -blocks   specifies the number of kilobyte blocks to be made



             available  for  caching  in  the  machine's  cache
             directory (for a disk  cache)  or  memory  (for  a
             memory  cache),  overriding the default defined in
             the third field of  /usr/vice/etc/cacheinfo.    It
             should  not  exceed 90% to 95% of the actual space
             available.   If  using  a  memory  cache,  do  not
             combine this argument with -dcache, since doing so
             could result in a  chunk  size  that  was  not  an
             exponent of 2.

   -files    specifies  the  number of V files to be created in
             the cache directory for a disk  cache,  overriding
             the  default of 1000.  Each V file can accommodate
             a "chunk" of data, which for a disk  cache  is  64
             kilobytes by default.  Thus the default of 1000 is
             adequate for any cache smaller than  64  megabytes
             (unless  chunk  size  is changed with -chunksize).
             Do not combine this argument with -memcache.

   -stat     specifies the number of entries in  the  machine's
             memory  for recording status information about the
             AFS files in the cache.  This value overrides  the
             default of 300.

   -rootvol  names  the  Read Write volume corresponding to the
             root directory for the AFS  file  tree  (which  is
             usually  /afs).   This value overrides the default
             of root.afs.

   -cachedir names the local disk directory to be used  as  the
             cache.    This value overrides the default defined
             in the  second  field  of  /usr/vice/etc/cacheinfo
             (typically, /usr/vice/cache).

   -mountdir names  the  local disk directory on which to mount
             the AFS file  tree.    This  value  overrides  the
             default    defined   in   the   first   field   of
             /usr/vice/etc/cacheinfo  (typically,  /afs).    If
             /afs  is  not  used, the machine cannot access the
             AFS global name space.

   -daemons  specifies the number of  "background"  daemons  to
             run   on  the  machine.    These  daemons  improve
             efficiency by doing  pre-fetching  and  background
             writing  of  saved data.  This value overrides the
             default of 2, which  is  adequate  for  a  machine
             serving  up to five users.  It does not change the
             number of  "callback"  or  "maintenance"  daemons,
             which is always one each.

   -verbose  causes  afsd  to  produce a more detailed trace of
             its activities than the default one.    The  trace
             displays  on  standard  out  (stdout) unless it is
             piped into a file.

   -debug    causes afsd to produce a highly detailed trace  of
             its  activities, potentially useful to a developer
             for  debugging  purposes.    The  trace  goes   to
             standard output (stdout) by default.

   -nosettime



             prevents the machine from selecting  at  random  a
             local  file  server machine to act as a source for
             the "correct" time.  If this flag is omitted,  the
             machine  selects  a  file server machine as a time
             standard,  and  every  five   minutes   thereafter
             adjusts  its  clock  to  avoid  drifting  from the
             standard.

   -rmtsys   initializes an additional  "remote-system"  daemon
             to  execute AFS-specific system calls on behalf of
             NFS client machines.  This flag is necessary  only
             if  the  machine is an NFS/AFS translator machine,
             and if users on its NFS clients  want  to  execute
             AFS commands.

   -memcache causes  afsd  to  initialize a memory cache rather
             than a disk cache.  Do not combine this flag  with
             -files.

   -dcache   sets  the  number  of  "dcache entries" in memory,
             which are used to store  information  about  cache
             chunks.    For  a  disk  cache, this overrides the
             default of 100.  For a memory cache, this argument
             effectively  sets the number of cache chunks.  Use
             of this argument is not recommended for  a  memory
             cache,   because   it   requires   the  issuer  to
             pre-calculate  the  resulting  total  cache   size
             (derived by multiplying this value by chunk size).
             Do not combine this argument with  -blocks,  since
             doing so could result in a chunk size that was not
             an exponent of 2.

   -chunksize
             sets  the  size  of each cache chunk.  The integer
             provided, which should be between  0  and  20,  is
             used as an exponent on the number 2.  It overrides
                                                     16
             the default of 16 for a  disk  cache  (2    is  64
                                                        13
             kilobytes)  and  13  for  a memory cache (2   is 8
             kilobytes).  A value of 0 or less, or greater than
             20,  sets  chunk  size to the appropriate default.
             Values less than 10 (which sets chunk  size  to  a
                         10
             kilobyte,  2  )  are  not  recommended.  Combining
             this argument  with  -dcache  is  not  recommended
             because  it requires that the issuer pre-calculate
             the cache size that results.

EXAMPLE

   This command is normally included in an initialization  file
   such  as  /etc/rc,  rather  than  typed at the command shell
   prompt.  For most disk caches, the appropriate form is

   /usr/vice/etc/afsd

   The following is appropriate when enabling a machine to  act
   as  an  NFS/AFS  Translator  machine  serving more than five
   users.

   /usr/vice/etc/afsd -daemons 4 -rmtsys



   The following initializes a memory cache and sets chunk size
                     14
   to 16 kilobytes (2  ).

   /usr/vice/etc/afsd -memcache -chunksize 14

PRIVILEGE REQUIRED

   Issuer must be logged into the machine's UNIX file system as
   "root."
