Added configuration parameter "priority" to specify the niceness of
[pwmd.git] / COMMANDS
bloba5cf119da7df770e999dfe5395b16e8291f2477f
1 The server uses a protocol provided by libassuan to communicate with the
2 client. An OK response is returned when a command succeeds or ERR along with
3 an error code and description, if not. When a command requests data for
4 retrieval (e.g., GET) the output is prefixed with D then a single SPACE then
5 the actual data followed by a response. Read the libassuan docs for more info
6 about the protocol.
9 PROTOCOL COMMANDS
10 -----------------
11 OPEN <filename> [<key>]
12     Opens <filename> using <key>. If file is not found on the file-system, then
13     a new document will be created. If the file is found, it is looked for in
14     the file cache for an existing key. When found, the existing key will be
15     used for decryption. When not found, pinentry(1) will be used to retrieve
16     the key (see OPTIONS below). You can also open a different file using the
17     same connection. When using an empty key and you want to avoid the
18     pinentry dialog, set PINENTRY to 0 (see OPTIONS below).
21 SAVE [<key>]
22     Writes the XML document to disk. The file written to is the file that was
23     opened using the OPEN command. If <key> is not specified then the
24     currently cached key will be used. If the file is a new file or the file
25     isn't found in the file cache, <key> may be used. If <key> is not
26     specified then pinentry(1) will be used to retrieve the key (see OPTIONS
27     below). When using an empty key and you want to avoid the pinentry dialog,
28     set PINENTRY to 0 (see OPTIONS below).
30     When the SAVE command is sent and a key is found in the file cache, the
31     cached key will be used. To reset the key to a new value, send the
32     CLEARCACHE command followed by the filename, then send the SAVE command to
33     enter a new key.
36 ISCACHED <filename>
37     An OK response is returned if the specified file is in the file cache.
40 CLEARCACHE [<filename>]
41     Clears a file cache entry. This will forget the timeout and key for all or
42     the specified file.
45 CACHETIMEOUT <seconds> <filename>
46     Specify the number of seconds the specified file will be cached. -1 will
47     keep the cache entry forever, 0 will require the key each time the OPEN or
48     SAVE commands are used. Also see the "cache_timeout" configuration option.
51 LIST [[!]element[<TAB>[!]element[...]]]
52     If no element path is given then a list of root elements is returned with
53     the data response code. If given, then all reachable elements for the
54     specified element path are returned. Each element in the path is prefixed
55     with the literal '!' character when the element contains no "target"
56     attribute (See THE TARGET ATTRIBUTE below).
59 REALPATH [!]element[<TAB>[!]element[...]]
60     Resolves all "target" attributes of the specified element path and returns
61     the result with a data response.
64 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
65     Creates a new element tree or modifies the content of an existing element
66     path. If only a single element is specified, a new root element is
67     created. Otherwise, elements are TAB delimited and the content will be set
68     to the last TAB delimited argument. If no content is specified after the
69     last TAB then the content for the last specified element will be removed
70     or empty if creating a new element.
71     
72     The only restriction of element names is that they not begin with a
73     punctuation character (the literal '!' character is an exception) or digit
74     and not contain any whitespace. There is no whitespace between the TAB
75     delimited elements. It is recommended that the value be base 64 encoded to
76     prevent libXML and pwmd parsing errors.
77     
78     PWMD reads the element path from the client via the Assuan INQUIRE
79     protocol response. The STORE command is sent by itself without arguments,
80     then the server responds with INQUIRE. The client then sends the element
81     path prefixed with a "D " data response. When finished, the client sends
82     "END" on an empty line. This is needed so an element path and value can be
83     more than 1000 bytes long, the Assuan protocol line limit.
86 DELETE [!]element[<TAB>[!]element[...]]
87     Removes an element tree from the specified element path.
90 GET [!]element[<TAB>[!]element[...]]
91     Retrieves the text content of the specified element path. The data is
92     returned with a data response.
95 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
96     ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
97         Stores or updates an attribute value of an element path.
99     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
100         Removes an attribute from an element path.
102     ATTR LIST [!]element[<TAB>[!]element[...]]
103         Gets a list of attributes from an element path.
105     ATTR GET attribute [!]element[<TAB>[!]element[...]]
106         Gets the value of an attribute from an element path.
108     The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
109     if the element path is only a root element. Although it can be SET to
110     change the root element name.
112     Also see THE TARGET ATTRIBUTE below.
115 XPATH <expression>[<TAB>[value]]
116     Evaluates an XPath expression. If no value argument is specified, it is
117     assumed the expression is a request to return a result. Otherwise, the
118     result is set to the value argument and the document is updated. If there
119     is no value after the <TAB> character, the value is assumed to be empty
120     and the document is updated.
123 IMPORT [!]element[<TAB>[!]element[...]] <content>
124     Like the STORE command (an INQUIRE), but the content argument is raw XML
125     data. The content is created as a child of the specified element path. If
126     an element of the element path does not exist, it is created.
128     Note that the new content must begin with an element and not text. Also
129     note that an existing child node of the same element name as the root node
130     of the imported content will be overwritten.
133 DUMP
134     Shows the in memory XML document with indenting. To dump a specific
135     element tree, use the XPATH command.
138 LOCK
139     Locks the mutex associated with the opened file. This prevents other
140     clients from sending commands to the same opened file until the client
141     that sent this command sends the UNLOCK command.
144 UNLOCK
145     Unlocks the mutex which was locked with the LOCK command.
148 GETPID
149     Retrieves the process id of the server.
152 GETCONFIG [filename] <parameter>
153     Returns the value of a pwmd configuration variable with a data response.
154     If no file is open then the specified files value or the default will be
155     returned. The "key" and "key_file" variables are ignored.
158 OPTION <NAME>=<VALUE>
159     Sets an option NAME to VALUE. See OPTIONS below.
163     Closes the connection. Use the SAVE command before this command as any
164     changes will be lost.
167 If a command fails then the ERR response is returned followed by a protocol
168 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
169 error codes.
172 OPTIONS
173 -------
174 Commands that require a key that is neither cached nor specified will use
175 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
176 command followed by the option name and value. Below are the available
177 pinentry options:
179     NAME       VALUE      Description
180     ---------|----------|----------------------------------------------------
181     PINENTRY   0|1        When 0, disable use of pinentry. The default is 1.
182     TIMEOUT    <integer>  The number of seconds before the pinentry process
183                           will terminate while waiting for a password.
184     PATH       <string>   Full path to the pinentry binary. The default is
185                           specified at compile time (/usr/bin/pinentry).
186     TTYNAME    <string>   Same as the --ttyname option to pinentry(1).
187     TTYTYPE    <string>   Same as the --ttytype option to pinentry(1).
188     DISPLAY    <string>   Same as the --display option to pinentry(1).
189     TITLE      <string>   Sets the title string of the dialog.
190     PROMPT     <string>   Sets the prompt string of the dialog.
191     DESC       <string>   Sets the error or description string of the dialog.
192     ITERATIONS <integer>  The number of encryption iterations to do when the
193                           SAVE command is sent. When used, the configured
194                           value will be updated to this value for the opened
195                           file, or the "global" default if no file has been
196                           opened yet. The CONFIG status message is sent after
197                           receiving this command.
199 When pinentry is used with the SAVE command the key will be asked for
200 confirmation. If the confirmation fails, the process is started over again
201 until either the keys match or until Cancel is selected. The OPEN command will
202 only ask for the key once without retrying on failure. It is up to the client
203 to retry the OPEN command. Empty keys are allowed.
205 There is also a CLIENT option that contains other sub-options. The format is
206 OPTION CLIENT NAME=VALUE, where NAME is one of:
208     NAME       VALUE      Description
209     ---------|----------|----------------------------------------------------
210     NAME      <string>   Associates the thread ID of the connection with the
211                          specified textual representation. Useful for
212                          debugging log messages.
215 STATUS MESSAGES
216 ---------------
217 Some commands send a status message to the client when successful or as a
218 progress indicator. Status messages begin with a KEYWORD (see below) followed
219 by the status description. What messages are sent, and how often, depend on
220 configuration settings:
222     COMMAND             KEYWORD
223     --------------------------------
224     Non-cache commands  LOCKED
226     OPEN                DECRYPT
227                         DECOMPRESS
228                         CACHE
229                         LOCKED
231     SAVE                COMPRESS
232                         ENCRYPT
233                         CACHE
234                         LOCKED
236     CLEARCACHE          CACHE
237                         LOCKED
239     CACHETIMEOUT        CACHE
240                         LOCKED
242     ISCACHED            LOCKED
245     KEYWORD             OUTPUT FORMAT
246     ---------------------------------
247     CACHE               <slots used> <slots available>
248                         Sent to each client after a change.
249     ENCRYPT             <iterations so far> <total iterations>
250     DECRYPT             <iterations so far> <total iterations>
251     COMPRESS            <bytes so far> <total bytes>
252     DECOMPRESS          <bytes so far> <total bytes>
253     LOCKED              When another thread owns the file/key cache mutex
254                         lock, this is sent at some interval and the thread
255                         will block until the lock can be obtained.
256     KEEPALIVE           Sent to each client after every configured amount of
257                         seconds. This lets the client know that the connection
258                         is still active for commands that take a while to
259                         complete.
260     CONFIG              Sent to each client after the configuration file has
261                         been reloaded or has had a value changed.
262     CLIENTS             Sent to each client after a client connects or
263                         disconnects.
266 THE TARGET ATTRIBUTE
267 --------------------
268 There is a special attribute "target" (case sensitive) that can be set with
269 ATTR SET. The value of this attribute is an element path that is located
270 somewhere else in the XML document and are alot like how XPath treats
271 entities, but are needed do to how pwmd commands are implemented. The syntax
272 is as follows:
274 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
275                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
277 If the element path of the "target" attribute (arg1) doesn't exist, it is
278 created. This is the only time the ATTR command will create elements.
280 When a protocol command requests <arg1> as the element path, the remaining
281 elements after the element with the "target" attribute will be appended to
282 <arg2>. This is useful if you have elements that share the same data. If the
283 target is modified, the other elements "pointing" to the target will have the
284 same content. To get the real or literal element and ignore any "target"
285 attributes, prefix an element with a '!' character. Here's an example:
287     C> STORE
288     S> INQUIRE STORE
289     C> D host1<TAB>username<TAB>original username
290     C> END
291     S> OK
292     C> STORE
293     S> INQUIRE STORE
294     C> D host2<TAB>smtp<TAB>username<TAB>someuser
295     C> END
296     S> OK
297     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
298     S> OK
300 Now host1's "target" attribute will be used:
302     C> GET host1<TAB>username
303     S> D someuser
304     S> OK
306 If you want host1's username, prefix the element of the "target" attribute
307 with a '!':
309     C> GET host1<TAB>!username
310     S> D original username
311     S> OK
313 The target value (arg2) element can also have a "target" attribute:
315     C> ATTR SET target new_account host1
316     S> OK
317     C> GET new_account<TAB>username
318     S> D someuser
319     S> OK
321 The value of the "target" attribute may also be prefixed with a '!' to set the
322 target to the actual element path and not a target of the element path:
324     C> ATTR DELETE target !new_account
325     S> OK
326     C> ATTR SET target new_account<TAB>username host1<TAB>!username
327     S> OK
328     C> GET new_account<TAB>username
329     S> D original username
330     S> OK
332 The "target" attribute is considered for all commands that support an element
333 path. If the target element has been renamed or deleted afterwards, the
334 command will fail.
336 Clients should be careful of creating target loops. See the "recursion_depth"
337 configuration parameter for details.
340 XML DOCUMENT STRUCTURE
341 ----------------------
342 When importing an XML data file with the -I command line option, the document
343 should have the following DTD:
345     <?xml version="1.0"?>
346     <!DOCTYPE accounts [
347     <!ELEMENT accounts (account*)>
348     <!ATTLIST account name CDATA #REQUIRED>
349     ]>
351 "accounts" is the document root element while each root element mentioned in
352 the protocol commands use the "account" element. So if you have a root element
353 "isp" to be shown with the LIST command ("LIST isp"), the document structure
354 looks like this:
356     <accounts>
357         <account name="isp">
358         [...]
359         </account>
360     </accounts>
362 The DUMP command can be useful to show the current document structure.
365 DESIGN
366 ------
367 The key cache is protected with a mutex and is locked with each access. Each
368 cache entry also contains a mutex for the opened file and a reference count
369 which is adjusted each time a client connects or disconnects. This allows
370 client A to issue commands that aren't related to the file opened by client B.
371 The refcount is needed to prevent the mutex being overwritten when the entry
372 needs to be reset (CACHETIMEOUT for example) and there are any clients
373 connected.
375 The client_thread() uses an event to wait for the client FD to become ready
376 for reading. When ready, it uses the libassuan external IO loop functions to
377 prevent blocking letting other threads do their work.
379 When a key is required for the OPEN or SAVE commands, and OPTION PINENTRY=1,
380 pinentry(1) is used to retrieve the key. This is done by creating a pipe()
381 with the client_thread(), then pth_fork()'s the pinentry process which will
382 write the key or error to the pipe that client_thread() will read from. After
383 the read, the pinentry will have exited and client_thread() calls the
384 finalization function for the original command.
386 The KEEPALIVE status message is a PTH_EVENT_TIME event from server_loop(). It
387 uses a pth_msgport_t to write to other client threads. This is the same for
388 the CACHE and CONFIG status messages, except that pth_msgport_put() is called
389 from a client thread and sent to all other clients too. Each client thread
390 uses an PTH_EVENT_MSG event to wait for these messages.
392            -------------       ---------------
393            [server_loop]-_-_-_-[accept_thread]
394            -------------       ---------------
395        not joinable :                |
396     ---------------------     ---------------
397     [adjust_timer_thread]     [client_thread]<----------=====
398     ---------------------     --------------- |   |    |    =
399                                | |     ---------  |    |    =
400                    ------------------  [command]  |    |    =
401                    [command finalize]  ---------  |    |    = pipe()
402                    ------------------    |   |    |    |    =
403                                          |  ---------  |    =
404                                          |  [INQUIRE]  |    =
405                                          |  ---------  |    =
406                                          |    -----------   =
407                                          |----[OPEN/SAVE]   = 
408                                               -----------   =
409                                                    : fork() =
410                                                ----------   =
411                                                [pinentry]====
412                                                ----------
414 There is also a library libpwmd which makes it easy for applications to use
415 the server. It supports it's own key retrieval and asynchronous interaction
416 with pwmd.
418 The latest version of both pwmd and libpwmd can be obtained from
419 http://bjk.sourceforge.net/pwmd/. Feel free to send me any questions, bug
420 reports, patches or feature requests.
422 Ben Kibbey <bjk@luxsci.net>