Documentation/filesystems/nfs/rpc-cache.rst

   1 =========
   2 RPC Cache
   3 =========
   4
   5 This document gives a brief introduction to the caching
   6 mechanisms in the sunrpc layer that is used, in particular,
   7 for NFS authentication.
   8
   9 Caches
  10 ======
  11
  12 The caching replaces the old exports table and allows for
  13 a wide variety of values to be caches.
  14
  15 There are a number of caches that are similar in structure though
  16 quite possibly very different in content and use.  There is a corpus
  17 of common code for managing these caches.
  18
  19 Examples of caches that are likely to be needed are:
  20
  21   - mapping from IP address to client name
  22   - mapping from client name and filesystem to export options
  23   - mapping from UID to list of GIDs, to work around NFS's limitation
  24     of 16 gids.
  25   - mappings between local UID/GID and remote UID/GID for sites that
  26     do not have uniform uid assignment
  27   - mapping from network identify to public key for crypto authentication.
  28
  29 The common code handles such things as:
  30
  31    - general cache lookup with correct locking
  32    - supporting 'NEGATIVE' as well as positive entries
  33    - allowing an EXPIRED time on cache items, and removing
  34      items after they expire, and are no longer in-use.
  35    - making requests to user-space to fill in cache entries
  36    - allowing user-space to directly set entries in the cache
  37    - delaying RPC requests that depend on as-yet incomplete
  38      cache entries, and replaying those requests when the cache entry
  39      is complete.
  40    - clean out old entries as they expire.
  41
  42 Creating a Cache
  43 ----------------
  44
  45 -  A cache needs a datum to store.  This is in the form of a
  46    structure definition that must contain a struct cache_head
  47    as an element, usually the first.
  48    It will also contain a key and some content.
  49    Each cache element is reference counted and contains
  50    expiry and update times for use in cache management.
  51 -  A cache needs a "cache_detail" structure that
  52    describes the cache.  This stores the hash table, some
  53    parameters for cache management, and some operations detailing how
  54    to work with particular cache items.
  55
  56    The operations are:
  57
  58     struct cache_head \*alloc(void)
  59       This simply allocates appropriate memory and returns
  60       a pointer to the cache_detail embedded within the
  61       structure
  62
  63     void cache_put(struct kref \*)
  64       This is called when the last reference to an item is
  65       dropped.  The pointer passed is to the 'ref' field
  66       in the cache_head.  cache_put should release any
  67       references create by 'cache_init' and, if CACHE_VALID
  68       is set, any references created by cache_update.
  69       It should then release the memory allocated by
  70       'alloc'.
  71
  72     int match(struct cache_head \*orig, struct cache_head \*new)
  73       test if the keys in the two structures match.  Return
  74       1 if they do, 0 if they don't.
  75
  76     void init(struct cache_head \*orig, struct cache_head \*new)
  77       Set the 'key' fields in 'new' from 'orig'.  This may
  78       include taking references to shared objects.
  79
  80     void update(struct cache_head \*orig, struct cache_head \*new)
  81       Set the 'content' fileds in 'new' from 'orig'.
  82
  83     int cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h)
  84       Optional.  Used to provide a /proc file that lists the
  85       contents of a cache.  This should show one item,
  86       usually on just one line.
  87
  88     int cache_request(struct cache_detail \*cd, struct cache_head \*h, char \*\*bpp, int \*blen)
  89       Format a request to be send to user-space for an item
  90       to be instantiated.  \*bpp is a buffer of size \*blen.
  91       bpp should be moved forward over the encoded message,
  92       and  \*blen should be reduced to show how much free
  93       space remains.  Return 0 on success or <0 if not
  94       enough room or other problem.
  95
  96     int cache_parse(struct cache_detail \*cd, char \*buf, int len)
  97       A message from user space has arrived to fill out a
  98       cache entry.  It is in 'buf' of length 'len'.
  99       cache_parse should parse this, find the item in the
 100       cache with sunrpc_cache_lookup_rcu, and update the item
 101       with sunrpc_cache_update.
 102
 103
 104 -  A cache needs to be registered using cache_register().  This
 105    includes it on a list of caches that will be regularly
 106    cleaned to discard old data.
 107
 108 Using a cache
 109 -------------
 110
 111 To find a value in a cache, call sunrpc_cache_lookup_rcu passing a pointer
 112 to the cache_head in a sample item with the 'key' fields filled in.
 113 This will be passed to ->match to identify the target entry.  If no
 114 entry is found, a new entry will be create, added to the cache, and
 115 marked as not containing valid data.
 116
 117 The item returned is typically passed to cache_check which will check
 118 if the data is valid, and may initiate an up-call to get fresh data.
 119 cache_check will return -ENOENT in the entry is negative or if an up
 120 call is needed but not possible, -EAGAIN if an upcall is pending,
 121 or 0 if the data is valid;
 122
 123 cache_check can be passed a "struct cache_req\*".  This structure is
 124 typically embedded in the actual request and can be used to create a
 125 deferred copy of the request (struct cache_deferred_req).  This is
 126 done when the found cache item is not uptodate, but the is reason to
 127 believe that userspace might provide information soon.  When the cache
 128 item does become valid, the deferred copy of the request will be
 129 revisited (->revisit).  It is expected that this method will
 130 reschedule the request for processing.
 131
 132 The value returned by sunrpc_cache_lookup_rcu can also be passed to
 133 sunrpc_cache_update to set the content for the item.  A second item is
 134 passed which should hold the content.  If the item found by _lookup
 135 has valid data, then it is discarded and a new item is created.  This
 136 saves any user of an item from worrying about content changing while
 137 it is being inspected.  If the item found by _lookup does not contain
 138 valid data, then the content is copied across and CACHE_VALID is set.
 139
 140 Populating a cache
 141 ------------------
 142
 143 Each cache has a name, and when the cache is registered, a directory
 144 with that name is created in /proc/net/rpc
 145
 146 This directory contains a file called 'channel' which is a channel
 147 for communicating between kernel and user for populating the cache.
 148 This directory may later contain other files of interacting
 149 with the cache.
 150
 151 The 'channel' works a bit like a datagram socket. Each 'write' is
 152 passed as a whole to the cache for parsing and interpretation.
 153 Each cache can treat the write requests differently, but it is
 154 expected that a message written will contain:
 155
 156   - a key
 157   - an expiry time
 158   - a content.
 159
 160 with the intention that an item in the cache with the give key
 161 should be create or updated to have the given content, and the
 162 expiry time should be set on that item.
 163
 164 Reading from a channel is a bit more interesting.  When a cache
 165 lookup fails, or when it succeeds but finds an entry that may soon
 166 expire, a request is lodged for that cache item to be updated by
 167 user-space.  These requests appear in the channel file.
 168
 169 Successive reads will return successive requests.
 170 If there are no more requests to return, read will return EOF, but a
 171 select or poll for read will block waiting for another request to be
 172 added.
 173
 174 Thus a user-space helper is likely to::
 175
 176   open the channel.
 177     select for readable
 178     read a request
 179     write a response
 180   loop.
 181
 182 If it dies and needs to be restarted, any requests that have not been
 183 answered will still appear in the file and will be read by the new
 184 instance of the helper.
 185
 186 Each cache should define a "cache_parse" method which takes a message
 187 written from user-space and processes it.  It should return an error
 188 (which propagates back to the write syscall) or 0.
 189
 190 Each cache should also define a "cache_request" method which
 191 takes a cache item and encodes a request into the buffer
 192 provided.
 193
 194 .. note::
 195   If a cache has no active readers on the channel, and has had not
 196   active readers for more than 60 seconds, further requests will not be
 197   added to the channel but instead all lookups that do not find a valid
 198   entry will fail.  This is partly for backward compatibility: The
 199   previous nfs exports table was deemed to be authoritative and a
 200   failed lookup meant a definite 'no'.
 201
 202 request/response format
 203 -----------------------
 204
 205 While each cache is free to use its own format for requests
 206 and responses over channel, the following is recommended as
 207 appropriate and support routines are available to help:
 208 Each request or response record should be printable ASCII
 209 with precisely one newline character which should be at the end.
 210 Fields within the record should be separated by spaces, normally one.
 211 If spaces, newlines, or nul characters are needed in a field they
 212 much be quoted.  two mechanisms are available:
 213
 214 -  If a field begins '\x' then it must contain an even number of
 215    hex digits, and pairs of these digits provide the bytes in the
 216    field.
 217 -  otherwise a \ in the field must be followed by 3 octal digits
 218    which give the code for a byte.  Other characters are treated
 219    as them selves.  At the very least, space, newline, nul, and
 220    '\' must be quoted in this way.