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