Documentation/rpc-cache.txt

   1 This document gives a brief introduction to the caching
   2 mechanisms in the sunrpc layer that is used, in particular,
   3 for NFS authentication.
   4
   5 CACHES
   6 ======
   7 The caching replaces the old exports table and allows for
   8 a wide variety of values to be caches.
   9
  10 There are a number of caches that are similar in structure though
  11 quite possibly very different in content and use.  There is a corpus
  12 of common code for managing these caches.
  13
  14 Examples of caches that are likely to be needed are:
  15   - mapping from IP address to client name
  16   - mapping from client name and filesystem to export options
  17   - mapping from UID to list of GIDs, to work around NFS's limitation
  18     of 16 gids.
  19   - mappings between local UID/GID and remote UID/GID for sites that
  20     do not have uniform uid assignment
  21   - mapping from network identify to public key for crypto authentication.
  22
  23 The common code handles such things as:
  24    - general cache lookup with correct locking
  25    - supporting 'NEGATIVE' as well as positive entries
  26    - allowing an EXPIRED time on cache items, and removing
  27      items after they expire, and are no longe in-use.
  28
  29    Future code extensions are expect to handle
  30    - making requests to user-space to fill in cache entries
  31    - allowing user-space to directly set entries in the cache
  32    - delaying RPC requests that depend on as-yet incomplete
  33      cache entries, and replaying those requests when the cache entry
  34      is complete.
  35    - maintaining last-access times on cache entries
  36    - clean out old entries when the caches become full
  37
  38 The code for performing a cache lookup is also common, but in the form
  39 of a template.  i.e. a #define.
  40 Each cache defines a lookup function by using the DefineCacheLookup
  41 macro, or the simpler DefineSimpleCacheLookup macro
  42
  43 Creating a Cache
  44 ----------------
  45
  46 1/ A cache needs a datum to cache.  This is in the form of a
  47    structure definition that must contain a
  48      struct cache_head
  49    as an element, usually the first.
  50    It will also contain a key and some content.
  51    Each cache element is reference counted and contains
  52    expiry and update times for use in cache management.
  53 2/ A cache needs a "cache_detail" structure that
  54    describes the cache.  This stores the hash table, and some
  55    parameters for cache management.
  56 3/ A cache needs a lookup function.  This is created using
  57    the DefineCacheLookup macro.  This lookup function is used both
  58    to find entries and to update entries.  The normal mode for
  59    updating an entry is to replace the old entry with a new
  60    entry.  However it is possible to allow update-in-place
  61    for those caches where it makes sense (no atomicity issues
  62    or indirect reference counting issue)
  63 4/ A cache needs to be registered using cache_register().  This
  64    includes in on a list of caches that will be regularly
  65    cleaned to discard old data.  For this to work, some
  66    thread must periodically call cache_clean
  67
  68 Using a cache
  69 -------------
  70
  71 To find a value in a cache, call the lookup function passing it a the
  72 datum which contains key, and possibly content, and a flag saying
  73 whether to update the cache with new data from the datum.   Depending
  74 on how the cache lookup function was defined, it may take an extra
  75 argument to identify the particular cache in question.
  76
  77 Except in cases of kmalloc failure, the lookup function
  78 will return a new datum which will store the key and
  79 may contain valid content, or may not.
  80 This datum is typically passed to cache_check which determines the
  81 validity of the datum and may later initiate an upcall to fill
  82 in the data.
  83
  84 cache_check can be passed a "struct cache_req *".  This structure is
  85 typically embedded in the actual request and can be used to create a
  86 deferred copy of the request (struct cache_deferred_req).  This is
  87 done when the found cache item is not uptodate, but the is reason to
  88 believe that userspace might provide information soon.  When the cache
  89 item does become valid, the deferred copy of the request will be
  90 revisited (->revisit).  It is expected that this method will
  91 reschedule the request for processing.
  92
  93
  94 Populating a cache
  95 ------------------
  96
  97 Each cache has a name, and when the cache is registered, a directory
  98 with that name is created in /proc/net/rpc
  99
 100 This directory contains a file called 'channel' which is a channel
 101 for communicating between kernel and user for populating the cache.
 102 This directory may later contain other files of interacting
 103 with the cache.
 104
 105 The 'channel' works a bit like a datagram socket. Each 'write' is
 106 passed as a whole to the cache for parsing and interpretation.
 107 Each cache can treat the write requests differently, but it is
 108 expected that a message written will contain:
 109   - a key
 110   - an expiry time
 111   - a content.
 112 with the intention that an item in the cache with the give key
 113 should be create or updated to have the given content, and the
 114 expiry time should be set on that item.
 115
 116 Reading from a channel is a bit more interesting.  When a cache
 117 lookup fail, or when it suceeds but finds an entry that may soon
 118 expiry, a request is lodged for that cache item to be updated by
 119 user-space.  These requests appear in the channel file.
 120
 121 Successive reads will return successive requests.
 122 If there are no more requests to return, read will return EOF, but a
 123 select or poll for read will block waiting for another request to be
 124 added.
 125
 126 Thus a user-space helper is likely to:
 127   open the channel.
 128     select for readable
 129     read a request
 130     write a response
 131   loop.
 132
 133 If it dies and needs to be restarted, any requests that have not be
 134 answered will still appear in the file and will be read by the new
 135 instance of the helper.
 136
 137 Each cache should define a "cache_parse" method which takes a message
 138 written from user-space and processes it.  It should return an error
 139 (which propagates back to the write syscall) or 0.
 140
 141 Each cache should also define a "cache_request" method which
 142 takes a cache item and encodes a request into the buffer
 143 provided.
 144
 145
 146 Note: If a cache has no active readers on the channel, and has had not
 147 active readers for more than 60 seconds, further requests will not be
 148 added to the channel but instead all looks that do not find a valid
 149 entry will fail.  This is partly for backward compatibility: The
 150 previous nfs exports table was deemed to be authoritative and a
 151 failed lookup meant a definite 'no'.
 152
 153 request/response format
 154 -----------------------
 155
 156 While each cache is free to use it's own format for requests
 157 and responses over channel, the following is recommended are
 158 appropriate and support routines are available to help:
 159 Each request or response record should be printable ASCII
 160 with precisely one newline character which should be at the end.
 161 Fields within the record should be separated by spaces, normally one.
 162 If spaces, newlines, or nul characters are needed in a field they
 163 much be quotes.  two mechanisms are available:
 164 1/ If a field begins '\x' then it must contain an even number of
 165    hex digits, and pairs of these digits provide the bytes in the
 166    field.
 167 2/ otherwise a \ in the field must be followed by 3 octal digits
 168    which give the code for a byte.  Other characters are treated
 169    as them selves.  At the very least, space, newlines nul, and
 170    '\' must be quoted in this way.
 171