doc/pwmd.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6 <title>pwmd Manual</title>
   7
   8 <meta name="description" content="pwmd Manual">
   9 <meta name="keywords" content="pwmd Manual">
  10 <meta name="resource-type" content="document">
  11 <meta name="distribution" content="global">
  12 <meta name="Generator" content="makeinfo">
  13 <meta name="viewport" content="width=device-width,initial-scale=1">
  14
  15 <link href="#Top" rel="start" title="Top">
  16 <link href="#Index" rel="index" title="Index">
  17 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  18 <link href="dir.html#Top" rel="up" title="(dir)">
  19 <style type="text/css">
  20 <!--
  21 a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
  22 a.summary-letter {text-decoration: none}
  23 blockquote.indentedblock {margin-right: 0em}
  24 div.display {margin-left: 3.2em}
  25 div.example {margin-left: 3.2em}
  26 kbd {font-style: oblique}
  27 pre.display {font-family: inherit}
  28 pre.format {font-family: inherit}
  29 pre.menu-comment {font-family: serif}
  30 pre.menu-preformatted {font-family: serif}
  31 span.nolinebreak {white-space: nowrap}
  32 span.roman {font-family: initial; font-weight: normal}
  33 span.sansserif {font-family: sans-serif; font-weight: normal}
  34 span:hover a.copiable-anchor {visibility: visible}
  35 ul.no-bullet {list-style: none}
  36 -->
  37 </style>
  38
  39
  40 </head>
  41
  42 <body lang="en">
  43 <h1 class="settitle" align="center">pwmd Manual</h1>
  44
  45
  46
  47
  48 <div class="top" id="Top">
  49 <div class="header">
  50 <p>
  51 Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
  52 </div>
  53 <span id="SEC_Top"></span>
  54
  55
  56 <div class="Contents_element" id="SEC_Contents">
  57 <h2 class="contents-heading">Table of Contents</h2>
  58
  59 <div class="contents">
  60
  61 <ul class="no-bullet">
  62   <li><a id="toc-Overview-of-pwmd" href="#Introduction">1 Overview of <code>pwmd</code></a></li>
  63   <li><a id="toc-Access-Control-1" href="#Access-Control">2 Access Control</a></li>
  64   <li><a id="toc-Cache-Control-1" href="#Cache-Control">3 Cache Control</a></li>
  65   <li><a id="toc-Invoking-pwmd" href="#Invoking">4 Invoking <code>pwmd</code></a></li>
  66   <li><a id="toc-pwmd-configuration-file-options" href="#Configuration">5 <code>pwmd</code> configuration file options</a></li>
  67   <li><a id="toc-Configuring-remote-connections-over-TLS_002e" href="#TLS">6 Configuring remote connections over TLS.</a></li>
  68   <li><a id="toc-Pinentry-configuration" href="#Pinentry">7 Pinentry configuration</a></li>
  69   <li><a id="toc-Protocol-commands-and-their-syntax" href="#Commands">8 Protocol commands and their syntax</a>
  70   <ul class="no-bullet">
  71     <li><a id="toc-Modifying-element-attributes_002e" href="#ATTR">8.1 Modifying element attributes.</a></li>
  72     <li><a id="toc-Run-a-series-of-commands-in-sequence_002e" href="#BULK">8.2 Run a series of commands in sequence.</a></li>
  73     <li><a id="toc-Setting-the-cache-timeout_002e" href="#CACHETIMEOUT">8.3 Setting the cache timeout.</a></li>
  74     <li><a id="toc-Removing-a-cache-entry_002e" href="#CLEARCACHE">8.4 Removing a cache entry.</a></li>
  75     <li><a id="toc-Copying-an-element_002e" href="#COPY">8.5 Copying an element.</a></li>
  76     <li><a id="toc-Deleting-an-element_002e" href="#DELETE">8.6 Deleting an element.</a></li>
  77     <li><a id="toc-Deleting-a-key-from-the-key-ring_002e" href="#DELETEKEY">8.7 Deleting a key from the key ring.</a></li>
  78     <li><a id="toc-Showing-the-XML-document_002e" href="#DUMP">8.8 Showing the XML document.</a></li>
  79     <li><a id="toc-Generating-a-new-key_002e" href="#GENKEY">8.9 Generating a new key.</a></li>
  80     <li><a id="toc-Getting-the-content-of-an-element_002e" href="#GET">8.10 Getting the content of an element.</a></li>
  81     <li><a id="toc-Obtaining-a-configuration-value_002e" href="#GETCONFIG">8.11 Obtaining a configuration value.</a></li>
  82     <li><a id="toc-Obtaining-server-and-client-information_002e" href="#GETINFO">8.12 Obtaining server and client information.</a></li>
  83     <li><a id="toc-Showing-available-commands_002e" href="#HELP">8.13 Showing available commands.</a></li>
  84     <li><a id="toc-Creating-elements-from-XML_002e" href="#IMPORT">8.14 Creating elements from XML.</a></li>
  85     <li><a id="toc-Testing-cache-status_002e" href="#ISCACHED">8.15 Testing cache status.</a></li>
  86     <li><a id="toc-Showing-keys-used-for-the-current-data-file_002e" href="#KEYINFO">8.16 Showing keys used for the current data file.</a></li>
  87     <li><a id="toc-Terminating-another-client_002e" href="#KILL">8.17 Terminating another client.</a></li>
  88     <li><a id="toc-Showing-document-elements_002e" href="#LIST">8.18 Showing document elements.</a></li>
  89     <li><a id="toc-Listing-keys-in-the-key-ring_002e" href="#LISTKEYS">8.19 Listing keys in the key ring.</a></li>
  90     <li><a id="toc-Locking-the-current-data-file_002e" href="#LOCK">8.20 Locking the current data file.</a></li>
  91     <li><a id="toc-Showing-available-data-files_002e" href="#LS">8.21 Showing available data files.</a></li>
  92     <li><a id="toc-Moving-an-element_002e" href="#MOVE">8.22 Moving an element.</a></li>
  93     <li><a id="toc-Testing-the-connection_002e" href="#NOP">8.23 Testing the connection.</a></li>
  94     <li><a id="toc-Opening-a-data-file_002e" href="#OPEN">8.24 Opening a data file.</a></li>
  95     <li><a id="toc-Setting-various-client-parameters_002e" href="#OPTION">8.25 Setting various client parameters.</a></li>
  96     <li><a id="toc-Changing-the-passphrase-for-a-key_002e" href="#PASSWD">8.26 Changing the passphrase for a key.</a></li>
  97     <li><a id="toc-Resolving-an-element_002e" href="#REALPATH">8.27 Resolving an element.</a></li>
  98     <li><a id="toc-Renaming-an-element_002e" href="#RENAME">8.28 Renaming an element.</a></li>
  99     <li><a id="toc-Resetting-the-client-state_002e" href="#RESET">8.29 Resetting the client state.</a></li>
 100     <li><a id="toc-Saving-document-changes-to-disk_002e" href="#SAVE">8.30 Saving document changes to disk.</a></li>
 101     <li><a id="toc-Modifying-the-content-of-an-element_002e" href="#STORE">8.31 Modifying the content of an element.</a></li>
 102     <li><a id="toc-Removing-a-data-file-lock_002e" href="#UNLOCK">8.32 Removing a data file lock.</a></li>
 103     <li><a id="toc-Modifying-more-than-one-element_002e" href="#XPATH">8.33 Modifying more than one element.</a></li>
 104     <li><a id="toc-Modifying-more-than-one-element_0027s-attributes_002e" href="#XPATHATTR">8.34 Modifying more than one element&rsquo;s attributes.</a></li>
 105   </ul></li>
 106   <li><a id="toc-Running-multiple-commands-in-sequence" href="#Bulk-Commands">9 Running multiple commands in sequence</a></li>
 107   <li><a id="toc-Status-messages-and-their-meanings" href="#Status-Messages">10 Status messages and their meanings</a></li>
 108   <li><a id="toc-The-target-attribute" href="#Target-Attribute">11 The <code>target</code> attribute</a></li>
 109   <li><a id="toc-Other-special-attributes" href="#Other-Attributes">12 Other special attributes</a></li>
 110   <li><a id="toc-Key-Expiration-1" href="#Key-Expiration">13 Key Expiration</a></li>
 111   <li><a id="toc-Recognized-signals" href="#Signals">14 Recognized signals</a></li>
 112   <li><a id="toc-Index-1" href="#Index" rel="index">Index</a></li>
 113 </ul>
 114 </div>
 115 </div>
 116 <hr>
 117 <div class="chapter" id="Introduction">
 118 <div class="header">
 119 <p>
 120 Next: <a href="#Access-Control" accesskey="n" rel="next">Access Control</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 121 </div>
 122 <span id="Overview-of-pwmd"></span><h2 class="chapter">1 Overview of <code>pwmd</code></h2>
 123
 124
 125
 126
 127
 128
 129 <p><em>Password Manager Daemon</em> (or <code>pwmd</code>) is a server that
 130 applications connect to and send commands to put and get data that is stored
 131 in an OpenPGP encrypted <acronym>XML</acronym> document. It mimics a filesystem in a
 132 lot of ways including per element <acronym>ACL</acronym>&rsquo;s, but also has the advantage
 133 of remote connections over <acronym>TLS</acronym> and a document cache. The document cache is
 134 needed for a data file encrypted with secret keys stored on a smartcard.
 135 </p>
 136 <p>The server uses the Assuan protocol and is the same used by
 137 <code>gpg-agent</code>, <code>pinentry</code>, <code>gpgme</code> and
 138 <code>scdaemon</code>. It also uses <cite>libgpg-error</cite> for error reporting with
 139 <var>GPG_ERR_SOURCE_USER_1</var> being the error source.
 140 </p>
 141
 142 <p>The <acronym>XML</acronym> document uses the following <acronym>DTD</acronym>:
 143 </p>
 144 <div class="example">
 145 <pre class="example">    &lt;?xml version=&quot;1.0&quot;?&gt;
 146     &lt;!DOCTYPE pwmd [
 147     &lt;!ELEMENT pwmd (element*)&gt;
 148     &lt;!ATTLIST element _name CDATA #REQUIRED&gt;
 149     ]&gt;
 150 </pre></div>
 151
 152 <p>The <code>pwmd</code> element is the document root node while all other elements
 153 of the document have the name <code>element</code> with an attribute <code>_name</code>
 154 whose value uniquely identifies the element at the current element tree depth.
 155 It is done this way to avoid <acronym>XML</acronym> parsing errors for commonly used
 156 characters.  A <acronym>URL</acronym> for example would be an invalid <acronym>XML</acronym>
 157 element since the <acronym>URI</acronym> contains a &lsquo;<samp>:</samp>&rsquo; which is also the
 158 <acronym>XML</acronym> namespace separator.
 159 </p>
 160 <p>As mentioned, an element name must be unique for the current element tree
 161 depth. You cannot have two elements containing the same <code>_name</code> attribute
 162 value. <code>pwmd</code> will stop searching for an element of an <em>element
 163 path</em> at the first match then continue searching for the next element of the
 164 element path beginning at the child node of the matched element.
 165 </p>
 166 <p>An <em>element path</em> is a <code>TAB</code> delimited character string where each
 167 <code>TAB</code> separates each element in the path.  For example, the element path
 168 <code>a<code>TAB</code>b<code>TAB</code>c</code> has the following <acronym>XML</acronym> document
 169 structure:
 170 </p>
 171 <div class="example">
 172 <pre class="example">   &lt;pwmd&gt;
 173             &lt;element _name=&quot;a&quot;&gt;
 174                 &lt;element _name=&quot;b&quot;&gt;
 175                     &lt;element _name=&quot;c&quot;&gt;
 176                         [... element value or content ...]
 177                     &lt;/element&gt;
 178                 &lt;/element&gt;
 179             &lt;/element&gt;
 180         &lt;/pwmd&gt;
 181 </pre></div>
 182
 183 <p>The only restriction of an element name is that it contain no whitespace
 184 characters.
 185 </p>
 186 <hr>
 187 </div>
 188 <div class="chapter" id="Access-Control">
 189 <div class="header">
 190 <p>
 191 Next: <a href="#Cache-Control" accesskey="n" rel="next">Cache Control</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Overview of <code>pwmd</code></a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 192 </div>
 193 <span id="Access-Control-1"></span><h2 class="chapter">2 Access Control</h2>
 194
 195 <p>Like a filesystem has an <acronym>ACL</acronym> to grant or limit access to directories
 196 or files for a specific user or group, <code>pwmd</code> can limit a local user,
 197 group or a <acronym>TLS</acronym> connection to a specific element path. This is done
 198 by storing an <acronym>ACL</acronym> in the element attribute <var>_acl</var>. Its syntax is
 199 similar to the <var>allowed</var> configuration parameter (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>)
 200 with the exception that a <acronym>TLS</acronym> fingerprint hash is prefixed with a
 201 <code>#</code>.
 202 </p>
 203 <p>Access is denied for any user that is not in the <acronym>ACL</acronym> of an element
 204 with the exception of an invoking user (see the <var>invoking_user</var>). The
 205 connected client must be in the <acronym>ACL</acronym> for each element in an element
 206 path otherwise an error is returned.  As an example:
 207 </p>
 208 <div class="example">
 209 <pre class="example">&lt;element _name=&quot;test&quot; _acl=&quot;username,-@wheel,root,#ABCDEF&quot;&gt;
 210         &lt;element _name=&quot;child&quot;/&gt;
 211 &lt;/element&gt;
 212 </pre></div>
 213
 214 <p>The user <code>username</code> would be allowed access to the <code>test</code> element
 215 but not if it is a member of the <code>wheel</code> group although, the <code>root</code>
 216 user, who may be a member of the <code>wheel</code> group, is allowed. The SHA-256
 217 <acronym>TLS</acronym> fingerprint hash <code>#ABCDEF</code> is also allowed.  No users other than an
 218 <var>invoking_user</var> are allowed access to the <code>child</code> element.
 219 </p>
 220 <p>The first user listed in the <acronym>ACL</acronym> is considered the owner of the
 221 element. This determines which clients may modify an <var>_acl</var> attribute and
 222 store content for an element. An <var>invoking_user</var> may always modify an
 223 <acronym>ACL</acronym>.
 224 </p>
 225 <hr>
 226 </div>
 227 <div class="chapter" id="Cache-Control">
 228 <div class="header">
 229 <p>
 230 Next: <a href="#Invoking" accesskey="n" rel="next">Invoking <code>pwmd</code></a>, Previous: <a href="#Access-Control" accesskey="p" rel="prev">Access Control</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 231 </div>
 232 <span id="Cache-Control-1"></span><h2 class="chapter">3 Cache Control</h2>
 233
 234
 235
 236 <p>While <code>pwmd</code> has its own cache settings for an <acronym>XML</acronym> document,
 237 <code>gpg-agent</code> has cache settings for the keys used for crypto operations
 238 of a data file. Specifically the <samp>ignore-cache-for-signing</samp>,
 239 <samp>default-cache-ttl</samp> and <samp>max-cache-ttl</samp> options. These
 240 <code>gpg-agent</code> options may need to be adjusted depending on your usage
 241 needs. For example, the <code>OPEN</code> command may not require a passphrase to
 242 open a data file due to the gpg-agent having a cached key even though the
 243 <code>ISCACHED</code> command returns an error indicating the data file is not
 244 cached; which usually means a passphrase would be required. Keys for symmetric
 245 data files are never kept in the <code>gpg-agent</code> cache regardless of
 246 <code>gpg-agent</code> cache settings.
 247 </p>
 248 <p>A copy-on-write operation is done for commands that modify the document; the
 249 client that invoked the command will work on a copy of the in-memory document.
 250 The first client to <code>SAVE</code> the changes to disk will require other clients
 251 to reopen the data file due to the checksum being updated.
 252 </p>
 253 <hr>
 254 </div>
 255 <div class="chapter" id="Invoking">
 256 <div class="header">
 257 <p>
 258 Next: <a href="#Configuration" accesskey="n" rel="next"><code>pwmd</code> configuration file options</a>, Previous: <a href="#Cache-Control" accesskey="p" rel="prev">Cache Control</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 259 </div>
 260 <span id="Invoking-pwmd"></span><h2 class="chapter">4 Invoking <code>pwmd</code></h2>
 261
 262
 263 <p><code>pwmd</code> uses GpgME for encryption, decryption and signing of the
 264 OpenPGP data file. GpgME itself makes use of <code>gpg</code> for these
 265 operations so some configuration of <code>gpg</code> may be needed.  Pwmd spawns
 266 a separate <code>gpg-agent</code> process when <var>gpg_homedir</var>
 267 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) is not set to an instance of an already running
 268 gpg-agent. Any <code>gpg</code> configuration options that you need set should be
 269 put in <var>~/.pwmd/.gnupg/gpg.conf</var> or the <var>gpg.conf</var> file located in
 270 <var>gpg_homedir</var>. The same is true for the <var>gpg-agent.conf</var> file to set
 271 any required <code>gpg-agent</code> options.
 272 </p>
 273 <p>It is recommended to pass the <samp>--allow-preset-passphrase</samp>
 274 option to <code>gpg-agent</code>. Doing so allows <code>pwmd</code>
 275 cache pushing on startup. It is also recommended to pass the
 276 <samp>--allow-loopback-pinentry</samp> to <code>gpg-agent</code> (this is the default
 277 as of gnupg-2.1.15). This option allows a passphrase to be inquired from
 278 <code>pwmd</code> when a <code>pinentry</code> is unavailable to the client
 279 (see <a href="#TLS">Configuring remote connections over TLS.</a>).
 280 </p>
 281 <p>If you would like to use a keypair from your default gnupg keyring located in
 282 ~/.gnupg, but would still like to use a separate gpg-agent process (the
 283 default), you would need to first export the public key from the default
 284 keyring then import it into the keyring that pwmd uses. You can do this by
 285 first exporting the public key, then use the <samp>--homedir ~/.pwmd/.gnupg</samp>
 286 option of <code>gpg</code> to import it into the new keyring. For private keys,
 287 you would need to copy the private key associated with the exported public key
 288 to <var>~/.pwmd/.gnupg/private-keys-v1.d</var>. If the private key is stored on
 289 a smartcard you can also use the <code>KEYINFO --learn</code> command
 290 (see <a href="#KEYINFO">Showing keys used for the current data file.</a>).
 291 </p>
 292 <span id="index-Running-pwmd"></span>
 293 <p><code>pwmd</code> is executed as follows:
 294 </p>
 295 <div class="example">
 296 <pre class="example">pwmd <var>options</var> [ file1 ] [ &hellip; ]
 297 </pre></div>
 298
 299 <p>Non-option arguments are data files to cache upon startup. When the data file
 300 requires a passphrase for decryption a <code>pinentry</code> will prompt either
 301 on the current TTY or from an X11 window when the <code>DISPLAY</code>
 302 environment variable is set. See <a href="#Pinentry">Pinentry configuration</a>.
 303 </p>
 304 <span id="index-Options"></span>
 305 <span id="index-Arguments"></span>
 306 <p>The following command line options are supported:
 307 </p>
 308 <span id="index-Getting-help"></span>
 309 <dl compact="compact">
 310 <dt><span>&lsquo;<samp>--debug protocol:level[,protocol:level]</samp>&rsquo;</span></dt>
 311 <dd><p>Enable debugging output. This option can output sensitive information such as
 312 passphrases and secret keys so care should be taken where the output gets
 313 written to. The <var>protocol</var> is a single character representing the protocol
 314 to log. Use <code>a</code> for <code>libassuan</code> with <var>level</var> being one or more
 315 character flags: <code>i</code> for init, <code>x</code> for context, <code>e</code> for engine,
 316 <code>d</code> for data, <code>s</code> for system IO or <code>c</code> for control.  To debug
 317 <code>gpgme</code> use <code>g</code> as the <var>protocol</var> with <var>level</var> being an
 318 integer from <code>1</code> to <code>9</code>. To enable <acronym>TLS</acronym> debugging output
 319 use <code>t</code> as the <var>protocol</var> with <var>level</var> being an integer from
 320 <code>1</code> to <code>9</code>. A value over <code>10</code> will enable all <acronym>TLS</acronym>
 321 debugging output with <code>1</code> being the default.
 322 </p>
 323 </dd>
 324 <dt><span>&lsquo;<samp>--homedir directory</samp>&rsquo;</span></dt>
 325 <dd><p>The root directory where pwmd will store its data and temporary files.  The
 326 default is <samp>~/.pwmd</samp>.
 327 </p>
 328 </dd>
 329 <dt><span>&lsquo;<samp>--rcfile, -f rcfile</samp>&rsquo;</span></dt>
 330 <dd><p>Specify an alternate configuration file. The default is
 331 <samp>~/.pwmd/config</samp>.
 332 </p>
 333 </dd>
 334 <dt><span>&lsquo;<samp>--kill</samp>&rsquo;</span></dt>
 335 <dd><p>Terminate an existing instance of pwmd. The process to terminate is determined
 336 from the <samp>--homedir</samp> and <samp>--rcfile</samp> options.
 337 </p>
 338 </dd>
 339 <dt><span>&lsquo;<samp>--import, -I filename|-</samp>&rsquo;</span></dt>
 340 <dd><p>Imports the <acronym>XML</acronym> <var>filename</var>. When <var>filename</var> is <code>-</code> the
 341 <acronym>XML</acronym> is read from <code>stdin</code>. The <acronym>XML</acronym> file should be in conformance to
 342 the <code>pwmd</code> <acronym>DTD</acronym> (see <a href="#Introduction">Overview of <code>pwmd</code></a>). You will be prompted for
 343 a passphrase to encrypt with.  The output is written to the filename specified
 344 with <samp>--outfile</samp>. To make use of the imported data, place the output
 345 file in <samp>~/.pwmd/data</samp>.
 346 </p>
 347 </dd>
 348 <dt><span>&lsquo;<samp>--output, -o filename|-</samp>&rsquo;</span></dt>
 349 <dd><p>When importing, write the encrypted data file to <var>filename</var>. When
 350 <var>filename</var> is <code>-</code> output will be written to <code>stdout</code>.
 351 </p>
 352 </dd>
 353 <dt><span>&lsquo;<samp>--passphrase-file, -k filename&quot;</samp>&rsquo;</span></dt>
 354 <dd><p>Obtain the passphrase to use when importing from the specified <var>filename</var>.
 355 </p>
 356 </dd>
 357 <dt><span>&lsquo;<samp>--keyid fingerprint[,fingerprint,...]</samp>&rsquo;</span></dt>
 358 <dd><p>Specifies the fingerprint of the encryption key to use as a recipient when
 359 importing. When not specified a new key-pair will be created.
 360 </p>
 361 </dd>
 362 <dt><span>&lsquo;<samp>--sign-keyid fingerprint</samp>&rsquo;</span></dt>
 363 <dd><p>Specifies the fingerprint of the signing key to use for signing of the data
 364 file when importing.  When not specified the signing key of the generated
 365 key-pair or the signing key of the <samp>--keyid</samp> option will be used.
 366 </p>
 367 </dd>
 368 <dt><span>&lsquo;<samp>--symmetric, -s</samp>&rsquo;</span></dt>
 369 <dd><p>Use symmetric or conventional encryption rather than pubic key encryption when
 370 importing.  Signing is still possible by using the <samp>--sign-keyid</samp>
 371 option. By default no signing is done when specifying this option.
 372 </p>
 373 </dd>
 374 <dt><span>&lsquo;<samp>--userid string</samp>&rsquo;</span></dt>
 375 <dd><p>When importing, the user id used to identify the generated key. This should be
 376 in the form <code>First Last &lt;email&gt;</code>.
 377 </p>
 378 </dd>
 379 <dt><span>&lsquo;<samp>--algo string</samp>&rsquo;</span></dt>
 380 <dd><p>When importing, the algorithm to use when generating the new key pair. The
 381 default is determined by <code>gpg</code>.
 382 </p>
 383 </dd>
 384 <dt><span>&lsquo;<samp>--expire seconds</samp>&rsquo;</span></dt>
 385 <dd><p>When importing, the time, in seconds since epoch, when the generated key will
 386 expire. Specifying <code>0</code> will never expire the key. The default is three
 387 years.
 388 </p>
 389 </dd>
 390 <dt><span>&lsquo;<samp>--no-passphrase</samp>&rsquo;</span></dt>
 391 <dd><p>When importing, don&rsquo;t require a passphrase for the generated key.
 392 </p>
 393 </dd>
 394 <dt><span>&lsquo;<samp>--disable-dump</samp>&rsquo;</span></dt>
 395 <dd><p>Disable the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and <code>DUMP</code>
 396 protocol commands (see <a href="#Commands">Protocol commands and their syntax</a>). This overrides any
 397 <var>disable_list_and_dump</var> configuration parameter (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>).
 398 </p>
 399 </dd>
 400 <dt><span>&lsquo;<samp>--no-fork, -n</samp>&rsquo;</span></dt>
 401 <dd><p>Run as a foreground process and do not fork into the background.
 402 </p>
 403 </dd>
 404 <dt><span>&lsquo;<samp>--force</samp>&rsquo;</span></dt>
 405 <dd><p>Ignore cache pushing failures on startup. By default, <code>pwmd</code> will exit
 406 if an error occurred due to an invalid passphrase or other error.
 407 </p>
 408 </dd>
 409 <dt><span>&lsquo;<samp>--version</samp>&rsquo;</span></dt>
 410 <dd><p>Show the version, copyright and compile time features and exit.
 411 </p>
 412 </dd>
 413 <dt><span>&lsquo;<samp>--help</samp>&rsquo;</span></dt>
 414 <dd><p>Print a summary of options.
 415 </p></dd>
 416 </dl>
 417
 418
 419 <hr>
 420 </div>
 421 <div class="chapter" id="Configuration">
 422 <div class="header">
 423 <p>
 424 Next: <a href="#TLS" accesskey="n" rel="next">Configuring remote connections over TLS.</a>, Previous: <a href="#Invoking" accesskey="p" rel="prev">Invoking <code>pwmd</code></a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 425 </div>
 426 <span id="pwmd-configuration-file-options"></span><h2 class="chapter">5 <code>pwmd</code> configuration file options</h2>
 427
 428
 429 <p>If no configuration file is specified with the <code>pwmd</code> <samp>-f</samp>
 430 command line option, <code>pwmd</code> will read <samp>~/.pwmd/config</samp> if it
 431 exists, and if not, will use defaults.  Blank lines and lines beginning with
 432 &lsquo;<samp>#</samp>&rsquo; are ignored. Some parameters may have data file specific settings by
 433 placing them in a file section. A file section is declared by surrounding the
 434 filename with braces (i.e., &lsquo;<samp>[filename]</samp>&rsquo;).  Global options may be
 435 specified in the <code>global</code> section &lsquo;<samp>e.g., [global]</samp>&rsquo; and are the
 436 default options for new or unspecified file sections.
 437 </p>
 438 <p>A tilde <code>~</code> will be expanded to the home directory of the user starting
 439 <code>pwmd</code> when contained in a parameter whose value is a filename.
 440 </p>
 441 <span id="index-Reloading-the-configuration-file"></span>
 442 <p>The configuration file can be reloaded by sending the <em>SIGHUP</em> signal to
 443 a <code>pwmd</code> process. Some security sensitive settings may not be changed
 444 until <code>pwmd</code> is restarted.
 445 </p>
 446 <span id="index-Global-configuration-options"></span>
 447 <p>The following options are only for use in the <code>[global]</code> section:
 448 </p>
 449 <dl compact="compact">
 450 <dt><span>&lsquo;<samp>socket_path = /path/to/socket</samp>&rsquo;</span></dt>
 451 <dd><p>Listen on the specified socket. The default is <samp>~/.pwmd/socket</samp>.
 452 </p>
 453 </dd>
 454 <dt><span>&lsquo;<samp>socket_perms = octal_mode</samp>&rsquo;</span></dt>
 455 <dd><p>Permissions to set after creating the socket. This will override any
 456 <cite>umask(2)</cite> setting.
 457 </p>
 458 </dd>
 459 <dt><span>&lsquo;<samp>backlog = integer</samp>&rsquo;</span></dt>
 460 <dd><p>The number of connections to queue. When this limit is reached then new
 461 connections will be refused. The default is <code>128</code>.
 462 </p>
 463 </dd>
 464 <dt><span>&lsquo;<samp>invoking_user = [-!]user,[-!]@group,[-!]#SHA-256,...</samp>&rsquo;</span></dt>
 465 <dd><p>This parameter is not to be confused with setuid or setguid upon startup. It&rsquo;s
 466 syntax is the same as the <code>allowed</code> parameter except that it is a list of
 467 local usernames, group names and <acronym>TLS</acronym> fingerprint hashes that may use the
 468 <code>XPATH</code>, <code>XPATHATTR</code> and <code>DUMP</code> commands (except when
 469 disabled with the <code>disable_list_and_dump</code> option) and also who may modify
 470 elements that have no <code>_acl</code> attribute or is not listed in an
 471 <code>_acl</code>. It is similar to the system administrator root account but for a
 472 data file and element paths (see <a href="#Access-Control">Access Control</a>). The default is specified
 473 at compile-time and also by default is the user <code>nobody</code>.
 474 </p>
 475 </dd>
 476 <dt><span>&lsquo;<samp>invoking_file = filename</samp>&rsquo;</span></dt>
 477 <dd><p>A file containing one entry per line. An entry has the same syntax as the
 478 <code>invoking_user</code> parameter. When both this parameter and the
 479 <code>invoking_user</code> parameter are specified then the <code>invoking_user</code>
 480 parameter will behave as if the <code>invoking_file</code> entries have been
 481 appended to the <code>invoking_user</code> parameter value.
 482 </p>
 483 </dd>
 484 <dt><span>&lsquo;<samp>strict_open = boolean</samp>&rsquo;</span></dt>
 485 <dd><p>When <code>true</code>, disallow creation of a new data file when the current client
 486 is not an <code>invoking_user</code>. The default is <code>false</code>.
 487 </p>
 488 </dd>
 489 <dt><span>&lsquo;<samp>strict_kill = boolean</samp>&rsquo;</span></dt>
 490 <dd><p>When <code>false</code>, the <code>KILL</code> command (see <a href="#KILL">Terminating another client.</a>) will allow killing
 491 another client that is not of the same <code>UID</code> or <acronym>TLS</acronym> fingerprint of
 492 the current client and when not an <code>invoking_user</code>. The default us
 493 <code>false</code>.
 494 </p>
 495 </dd>
 496 <dt><span>&lsquo;<samp>allowed = [-!]user,[-!]@group,[-!]/path/to/exec,[+,][-!]#SHA-256,...</samp>&rsquo;</span></dt>
 497 <dd><p>A comma separated list of local user names, group names or <acronym>TLS</acronym>
 498 fingerprint SHA-256 hashes (in the case of a remote client) which are
 499 allowed to connect.  Groups should be prefixed with a &lsquo;<samp>@</samp>&rsquo;. When not
 500 specified only the user who started <code>pwmd</code> may connect. An entry in
 501 the list may be prefixed with a <code>-</code> or <code>!</code> to prevent access. The
 502 order of the list is important since a user may be a member of multiple
 503 groups, for example.
 504 </p>
 505 <p>Connections from local clients may also be limited by command name. A command
 506 name is the full path to the execuatble on the filesystem. The command check
 507 is done after all other user and group name checks. When no command is
 508 specified all commands are allowed. When the connecting client is not of the
 509 same <acronym>UID</acronym> as the user that invoked <code>pwmd</code> this feature is
 510 ignored.
 511 </p>
 512 <p>This parameter may also be specified in a filename section to allow or deny a
 513 client to <code>OPEN</code> (see <a href="#OPEN">Opening a data file.</a>) a data file. It also affects the cache
 514 commands <code>CLEARCACHE</code> (see <a href="#CLEARCACHE">Removing a cache entry.</a>) and <code>CACHETIMEOUT</code>
 515 (see <a href="#CACHETIMEOUT">Setting the cache timeout.</a>). When not specified in a file section, any client
 516 allowed to connect may also open any filename provided they can decrypt it.
 517 Note that when specified in a file section that any <var>allowed</var> parameter in
 518 the <code>global</code> seciton is not considered.
 519 </p>
 520 <p>The following example would deny all users in group <code>primary</code> but
 521 allow <code>username</code> who may be a member of <code>primary</code>. It will also
 522 allow any <acronym>TLS</acronym> client except for the client with <acronym>TLS</acronym>
 523 fingerprint hash <code>#ABCDEF</code>. For local connections, the connecting client
 524 must be using the /usr/bin/pwmc program:
 525 </p>
 526 <div class="example">
 527 <pre class="example">allowed=-@primary,username,+,!#ABCDEF,/usr/bin/pwmc
 528 </pre></div>
 529
 530 </dd>
 531 <dt><span>&lsquo;<samp>allowed_file = filename</samp>&rsquo;</span></dt>
 532 <dd><p>A file containing one entry per line. An entry has the same syntax as the
 533 <code>allowed</code> parameter except that a line beginning with a semicolon is
 534 ignored. When both this parameter and the <code>allowed</code> parameter are
 535 specified then the <code>allowed_file</code> entries will be appended to the
 536 <code>allowed</code> parameter value.
 537 </p>
 538 </dd>
 539 <dt><span>&lsquo;<samp>encrypt_to = boolean</samp>&rsquo;</span></dt>
 540 <dd><p>When <code>true</code> and <code>SAVE</code>&rsquo;ing a data file, allow <code>gpg</code> to
 541 append it&rsquo;s configured key to the list of recipients. The default is
 542 <code>false</code> meaning that only keys specified with <code>SAVE</code>
 543 <samp>--keyid</samp> are recipients.
 544 </p>
 545 </dd>
 546 <dt><span>&lsquo;<samp>always_trust = boolean</samp>&rsquo;</span></dt>
 547 <dd><p>When <code>true</code>, allow encrypting to untrusted recipients or public
 548 encryption keys. If you receive an error when <code>SAVE</code>&rsquo;ing stating that
 549 the public key is unusable, either enable this option or edit the keys&rsquo; trust
 550 value:
 551 </p><div class="example">
 552 <pre class="example">gpg --homedir ~/.pwmd/.gnupg --edit-key &lt;fingerprint&gt;
 553 </pre></div>
 554 <p>The default is <code>false</code>.
 555 </p>
 556 </dd>
 557 <dt><span>&lsquo;<samp>gpg_homedir = path</samp>&rsquo;</span></dt>
 558 <dd><p>The location where <code>gpg</code> will store its public and private keys and
 559 configuration. The default is <samp>HOMEDIR/.gnupg</samp> where <var>HOMEDIR</var> is the
 560 default (<samp>~/.pwmd</samp>) or the value specified on the command line with the
 561 <samp>--homedir</samp> command line option (see <a href="#Invoking">Invoking <code>pwmd</code></a>). If you want to use
 562 your standard <code>gpg</code> keyring then set this to <samp>~/.gnupg</samp>. Note
 563 that a new instance of <code>gpg-agent</code> will be started when <em>not</em>
 564 using the standard keyring and that any configuration options for
 565 <code>gpg-agent</code> will need to placed in
 566 <samp>HOMEDIR/.gnupg/gpg-agent.conf</samp>.
 567 </p>
 568 </dd>
 569 <dt><span>&lsquo;<samp>disable_mlockall = boolean</samp>&rsquo;</span></dt>
 570 <dd><p>When set to <code>false</code>, <cite>mlockall(2)</cite> will be called on startup.  This
 571 will use more physical memory but may also be more secure since no swapping to
 572 disk will occur. The default is <var>true</var>. If possible, use an encrypted swap
 573 file or partition and leave this set to <var>true</var>.
 574 </p>
 575 </dd>
 576 <dt><span>&lsquo;<samp>log_path = /path/to/logfile</samp>&rsquo;</span></dt>
 577 <dd><p>Logs informational messages to the specified file. The default is
 578 <samp>~/.pwmd/log</samp>.
 579 </p>
 580 </dd>
 581 <dt><span>&lsquo;<samp>enable_logging = boolean</samp>&rsquo;</span></dt>
 582 <dd><p>Enable or disable logging to <var>log_path</var>. The default is <code>false</code>.
 583 </p>
 584 </dd>
 585 <dt><span>&lsquo;<samp>log_keepopen = boolean</samp>&rsquo;</span></dt>
 586 <dd><p>When set to <code>false</code>, the log file specified with <var>log_path</var> will be
 587 closed after writing each line. The default is <code>true</code>.
 588 </p>
 589 </dd>
 590 <dt><span>&lsquo;<samp>syslog = boolean</samp>&rsquo;</span></dt>
 591 <dd><p>Enable logging to <cite>syslog(8)</cite> with facility <em>LOG_DAEMON</em> and priority
 592 <em>LOG_INFO</em>. The default is <code>false</code>.
 593 </p>
 594 </dd>
 595 <dt><span>&lsquo;<samp>log_level = level</samp>&rsquo;</span></dt>
 596 <dd><p>When <code>0</code>, only connections and errors are logged. When <code>1</code>, data
 597 file recipients and signers are logged during <code>OPEN</code> (see <a href="#OPEN">Opening a data file.</a>) and
 598 <code>SAVE</code> (see <a href="#SAVE">Saving document changes to disk.</a>). When <code>2</code>, client commands are also logged.
 599 The default is <code>0</code>.
 600 </p>
 601 </dd>
 602 <dt><span>&lsquo;<samp>kill_scd = boolean</samp>&rsquo;</span></dt>
 603 <dd><p>Attempt to kill <code>scdaemon</code> after a client disconnects.  The default is
 604 <code>false</code>.
 605 </p>
 606 </dd>
 607 <dt><span>&lsquo;<samp>disable_list_and_dump = boolean</samp>&rsquo;</span></dt>
 608 <dd><p>When <code>true</code> the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and
 609 <code>DUMP</code> protocol commands (see <a href="#Commands">Protocol commands and their syntax</a>) will be disabled.
 610 </p>
 611 </dd>
 612 <dt><span>&lsquo;<samp>cache_push = file1,file2</samp>&rsquo;</span></dt>
 613 <dd><p>A comma separated list of filenames to be cached upon startup. <code>pwmd</code>
 614 will prompt for the passphrase for each file unless specified with
 615 <var>passphrase_file</var> parameter in a matching file section.
 616 </p>
 617 </dd>
 618 <dt><span>&lsquo;<samp>priority = integer</samp>&rsquo;</span></dt>
 619 <dd><p>The priority or niceness of the server. The default is inherited from the
 620 parent process.
 621 </p>
 622 </dd>
 623 <dt><span>&lsquo;<samp>lock_timeout = integer</samp>&rsquo;</span></dt>
 624 <dd><p>The default timeout in tenths of a second before giving up while waiting for a
 625 file lock and returning an error. The default is <code>50</code>.
 626 </p>
 627 </dd>
 628 </dl>
 629
 630 <span id="index-Data-file-configuration-options"></span>
 631 <p>The following options are defaults for new files when specified in the
 632 &lsquo;<samp>global</samp>&rsquo; section. When placed in a data file section they are options
 633 specific to that data file only.
 634 </p>
 635 <dl compact="compact">
 636 <dt><span>&lsquo;<samp>require_save_key = boolean</samp>&rsquo;</span></dt>
 637 <dd><p>Require the passphrase needed for signing before writing changes of the
 638 document to disk regardless of the key cache status. The default is
 639 <code>true</code>. This option compliments <code>gpg-agent</code> option
 640 <samp>--ignore-cache-for-signing</samp> and is used as a fail-safe.
 641 </p>
 642 </dd>
 643 <dt><span>&lsquo;<samp>backup = boolean</samp>&rsquo;</span></dt>
 644 <dd><p>Whether to create a backup of the data file when saving. The backup filename
 645 has the <samp>.backup</samp> extension appended to the opened file. The default is
 646 <code>true</code>.
 647 </p>
 648 </dd>
 649 <dt><span>&lsquo;<samp>cache_timeout = seconds</samp>&rsquo;</span></dt>
 650 <dd><p>The number of seconds to keep the cache entry for this file. If <code>-1</code>, the
 651 cache entry is kept forever. If <code>0</code>, each time an encrypted file is
 652 <code>OPEN</code>ed (see <a href="#OPEN">Opening a data file.</a>) a passphrase will be required. The default
 653 is <code>600</code> or 10 minutes.
 654 </p>
 655 </dd>
 656 <dt><span>&lsquo;<samp>passphrase_file = /path/to/filename</samp>&rsquo;</span></dt>
 657 <dd><p>Obtain the passphrase to open the data file from <var>filename</var>. If specified
 658 in the &lsquo;<samp>global</samp>&rsquo; section then the <var>passphrase_file</var> is a default for
 659 all data files. Note that if a client changes the passphrase for this data
 660 file then the <var>passphrase_file</var> will need to be updated with the new
 661 passphrase.
 662 </p>
 663 </dd>
 664 <dt><span>&lsquo;<samp>recursion_depth = integer</samp>&rsquo;</span></dt>
 665 <dd><p>The maximum number of times to resolve a <code>_target</code> attribute for an
 666 element in an element path (see <a href="#Target-Attribute">The <code>target</code> attribute</a>). An error is returned
 667 when this value is exceeded.  The default is <code>100</code> but can be disabled by
 668 setting to <code>0</code> (<em>not recommended</em>).
 669 </p>
 670 </dd>
 671 <dt><span>&lsquo;<samp>allowed = [-]user,[-]@group,[!]#TLSFINGERPRINT,...</samp>&rsquo;</span></dt>
 672 <dd><p>Same parameter value as the <code>allowed</code> parameter mentioned above in
 673 the &lsquo;<samp>[global]</samp>&rsquo; section but grants or denies a client from opening a
 674 specific data file. The default is to allow any client that is allowed to
 675 connect.
 676 </p>
 677 </dd>
 678 </dl>
 679
 680 <hr>
 681 </div>
 682 <div class="chapter" id="TLS">
 683 <div class="header">
 684 <p>
 685 Next: <a href="#Pinentry" accesskey="n" rel="next">Pinentry configuration</a>, Previous: <a href="#Configuration" accesskey="p" rel="prev"><code>pwmd</code> configuration file options</a>, Up: <a href="#Configuration" accesskey="u" rel="up"><code>pwmd</code> configuration file options</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 686 </div>
 687 <span id="Configuring-remote-connections-over-TLS_002e"></span><h2 class="chapter">6 Configuring remote connections over TLS.</h2>
 688 <p>In addition to connecting to <code>pwmd</code> via a Unix Domain Socket, remote
 689 connections can also be made to <code>pwmd</code> over <acronym>TLS</acronym>.
 690 Authentication is done by using X.509 client certificates that are signed with
 691 the same Certificate Authority (CA) as the server certificate.
 692 </p>
 693 <p>The CA certificate is expected to be found in
 694 <samp>~/.pwmd/ca-cert.pem</samp> while the <code>pwmd</code> server certificate and key
 695 file should be put in <samp>~/.pwmd/server-cert.pem</samp> and
 696 <samp>~/.pwmd/server-key.pem</samp>, respectively.
 697 </p>
 698 <p>See the documentation of <code>certtool</code> or <code>openssl</code> for details
 699 about creating self-signed certificates.
 700 </p>
 701 <p>The following <acronym>TLS</acronym> configuration options are available:
 702 </p>
 703 <dl compact="compact">
 704 <dt><span>&lsquo;<samp>enable_tcp = boolean</samp>&rsquo;</span></dt>
 705 <dd><p>Whether to enable <acronym>TCP</acronym>/<acronym>TLS</acronym> server support. If enabled, both <acronym>TCP</acronym> and the local
 706 unix domain socket will listen for connections. The default is
 707 <code>false</code>.
 708 </p>
 709 </dd>
 710 <dt><span>&lsquo;<samp>tcp_port = integer</samp>&rsquo;</span></dt>
 711 <dd><p>The <acronym>TCP</acronym> port to listen on when <var>enable_tcp</var> is <code>true</code>. The default is
 712 <code>6466</code>.
 713 </p>
 714 </dd>
 715 <dt><span>&lsquo;<samp>tcp_bind = string</samp>&rsquo;</span></dt>
 716 <dd><p>The internet protocol to listen with. Must be one of <code>ipv4</code>, <code>ipv6</code>
 717 or <code>any</code> to listen for both IPv4 and IPv6 connections. The default is
 718 <code>any</code>.
 719 </p>
 720 </dd>
 721 <dt><span>&lsquo;<samp>tcp_interface = string</samp>&rsquo;</span></dt>
 722 <dd><p>Only useful if running as root.
 723 </p>
 724 </dd>
 725 <dt><span>&lsquo;<samp>tls_timeout = seconds</samp>&rsquo;</span></dt>
 726 <dd><p>The number of seconds to wait for a read() or write() call on a
 727 <acronym>TLS</acronym> client file descriptor to complete before returning an
 728 error. The default is <var>300</var>.
 729 </p>
 730 </dd>
 731 <dt><span>&lsquo;<samp>keepalive_interval = seconds</samp>&rsquo;</span></dt>
 732 <dd><p>Send a keepalive status message to an idle remote client.  An idle
 733 client is one that is not in a command. The purpose of this status
 734 message is to disconnect a hung remote client and release any file mutex
 735 locks so another client may open the same data file. The default is <code>60</code>.
 736 </p>
 737 </dd>
 738 <dt><span>&lsquo;<samp>tcp_require_key = boolean</samp>&rsquo;</span></dt>
 739 <dd><p>When <code>true</code>, require the remote client to provide the passphrase to open
 740 a data file even if the file is cached.  This option is a default for all
 741 files when specified in the &lsquo;<samp>[global]</samp>&rsquo; section. The default is
 742 <code>false</code>.
 743 </p>
 744 </dd>
 745 <dt><span>&lsquo;<samp>tls_cipher_suite = string</samp>&rsquo;</span></dt>
 746 <dd><p>The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
 747 information about the format of this string. The default is
 748 <code>SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1:-AES-128-CBC:-AES-256-CBC</code>.
 749 </p>
 750 </dd>
 751 <dt><span>&lsquo;<samp>tls_dh_params_file = filename</samp>&rsquo;</span></dt>
 752 <dd><p>The PEM encoded filename containing DH parameters. If not specified
 753 then DH algorithms will not be available to the client. See the
 754 <code>openssl dhparam</code> or <code>certtool</code> manual pages for details about
 755 generating this file.
 756 </p>
 757 <p>Note that SIGHUP will not reload this file once <acronym>TLS</acronym> support has been enabled.
 758 You will need to restart <code>pwmd</code> for changes to take effect.
 759 </p>
 760 </dd>
 761 <dt><span>&lsquo;<samp>tls_use_crl = boolean</samp>&rsquo;</span></dt>
 762 <dd><p>When <code>true</code>, enable the use of <samp>tls_crl_file</samp>. The default is
 763 <code>false</code>.
 764 </p>
 765 </dd>
 766 <dt><span>&lsquo;<samp>tls_crl_file = filename</samp>&rsquo;</span></dt>
 767 <dd><p>This file is an X.509 Certificate Revocation List (<acronym>CRL</acronym>) and can be
 768 used to deny clients by adding client certificates to it. <code>pwmd</code> will
 769 need to be restarted to recognize any changes to this file.  When not
 770 specified the default of <samp>~/.pwmd/crl.pem</samp> will be used when
 771 <samp>tls_use_crl</samp> is <code>true</code>.
 772 </p>
 773 </dd>
 774 <dt><span>&lsquo;<samp>tls_ca_file = filename</samp>&rsquo;</span></dt>
 775 <dd><p>The filename of the <acronym>CA</acronym> certificate to use. When not specified the
 776 default of <samp>~/.pwmd/ca-cert.pem</samp> will be used.
 777 </p>
 778 </dd>
 779 <dt><span>&lsquo;<samp>tls_server_cert_file = filename</samp>&rsquo;</span></dt>
 780 <dd><p>The filename of the server certificate to use. When not specified the default
 781 of <samp>~/.pwmd/server-cert.pem</samp> will be used.
 782 </p>
 783 </dd>
 784 <dt><span>&lsquo;<samp>tls_server_key_file = filename</samp>&rsquo;</span></dt>
 785 <dd><p>The key filename of the server certificate to use. When not specified the
 786 default of <samp>~/.pwmd/server-key.pem</samp> will be used.
 787 </p>
 788 </dd>
 789 </dl>
 790
 791 <hr>
 792 </div>
 793 <div class="chapter" id="Pinentry">
 794 <div class="header">
 795 <p>
 796 Next: <a href="#Commands" accesskey="n" rel="next">Protocol commands and their syntax</a>, Previous: <a href="#TLS" accesskey="p" rel="prev">Configuring remote connections over TLS.</a>, Up: <a href="#Configuration" accesskey="u" rel="up"><code>pwmd</code> configuration file options</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 797 </div>
 798 <span id="Pinentry-configuration"></span><h2 class="chapter">7 Pinentry configuration</h2>
 799
 800 <p>The <code>pinentry</code> program is used to prompt the user for passphrase
 801 input or as a confirmation dialog; it needs to know where to prompt for
 802 the input; from a terminal or an X11 display.
 803 </p>
 804 <p>It is the responsibility of the client to tell <code>pinentry</code> about the
 805 terminal or X11 display before requiring the input. This is done with the
 806 <code>OPTION</code> command (see <a href="#OPTION">Setting various client parameters.</a>) to either set or unset needed
 807 <code>pwmd</code> environment variables and by using the
 808 <code>gpg-connect-agent</code> program. Please read it&rsquo;s documentation about the
 809 <em>UPDATESTARTUPTTY</em> command.
 810 </p>
 811 <hr>
 812 </div>
 813 <div class="chapter" id="Commands">
 814 <div class="header">
 815 <p>
 816 Next: <a href="#Bulk-Commands" accesskey="n" rel="next">Running multiple commands in sequence</a>, Previous: <a href="#Pinentry" accesskey="p" rel="prev">Pinentry configuration</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 817 </div>
 818 <span id="Protocol-commands-and-their-syntax"></span><h2 class="chapter">8 Protocol commands and their syntax</h2>
 819 <ul class="section-toc">
 820 <li><a href="#ATTR" accesskey="1">Modifying element attributes.</a></li>
 821 <li><a href="#BULK" accesskey="2">Run a series of commands in sequence.</a></li>
 822 <li><a href="#CACHETIMEOUT" accesskey="3">Setting the cache timeout.</a></li>
 823 <li><a href="#CLEARCACHE" accesskey="4">Removing a cache entry.</a></li>
 824 <li><a href="#COPY" accesskey="5">Copying an element.</a></li>
 825 <li><a href="#DELETE" accesskey="6">Deleting an element.</a></li>
 826 <li><a href="#DELETEKEY" accesskey="7">Deleting a key from the key ring.</a></li>
 827 <li><a href="#DUMP" accesskey="8">Showing the XML document.</a></li>
 828 <li><a href="#GENKEY" accesskey="9">Generating a new key.</a></li>
 829 <li><a href="#GET">Getting the content of an element.</a></li>
 830 <li><a href="#GETCONFIG">Obtaining a configuration value.</a></li>
 831 <li><a href="#GETINFO">Obtaining server and client information.</a></li>
 832 <li><a href="#HELP">Showing available commands.</a></li>
 833 <li><a href="#IMPORT">Creating elements from XML.</a></li>
 834 <li><a href="#ISCACHED">Testing cache status.</a></li>
 835 <li><a href="#KEYINFO">Showing keys used for the current data file.</a></li>
 836 <li><a href="#KILL">Terminating another client.</a></li>
 837 <li><a href="#LIST">Showing document elements.</a></li>
 838 <li><a href="#LISTKEYS">Listing keys in the key ring.</a></li>
 839 <li><a href="#LOCK">Locking the current data file.</a></li>
 840 <li><a href="#LS">Showing available data files.</a></li>
 841 <li><a href="#MOVE">Moving an element.</a></li>
 842 <li><a href="#NOP">Testing the connection.</a></li>
 843 <li><a href="#OPEN">Opening a data file.</a></li>
 844 <li><a href="#OPTION">Setting various client parameters.</a></li>
 845 <li><a href="#PASSWD">Changing the passphrase for a key.</a></li>
 846 <li><a href="#REALPATH">Resolving an element.</a></li>
 847 <li><a href="#RENAME">Renaming an element.</a></li>
 848 <li><a href="#RESET">Resetting the client state.</a></li>
 849 <li><a href="#SAVE">Saving document changes to disk.</a></li>
 850 <li><a href="#STORE">Modifying the content of an element.</a></li>
 851 <li><a href="#UNLOCK">Removing a data file lock.</a></li>
 852 <li><a href="#XPATH">Modifying more than one element.</a></li>
 853 <li><a href="#XPATHATTR">Modifying more than one element&rsquo;s attributes.</a></li>
 854 </ul>
 855 <hr>
 856 <div class="section" id="ATTR">
 857 <div class="header">
 858 <p>
 859 Next: <a href="#BULK" accesskey="n" rel="next">Run a series of commands in sequence.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 860 </div>
 861 <span id="Modifying-element-attributes_002e"></span><h3 class="section">8.1 Modifying element attributes.</h3>
 862 <span id="index-ATTR-command"></span>
 863 <p>Syntax:
 864 </p><div class="example">
 865 <pre class="example">ATTR [--inquire] SET|GET|DELETE|LIST [&lt;attribute&gt;] element[&lt;TAB&gt;child[..]] ..
 866 </pre></div>
 867
 868 <dl compact="compact">
 869 <dt><span>ATTR SET attribute element[&lt;TAB&gt;child[..]] [value]</span></dt>
 870 <dd><p>Stores or updates an <var>attribute</var> name and optional <var>value</var> of an
 871 element. When no <var>value</var> is specified any existing value will be removed.
 872 <br><br>
 873 </p></dd>
 874 <dt><span>ATTR DELETE attribute element[&lt;TAB&gt;child[..]]</span></dt>
 875 <dd><p>Removes an attribute from an element. If <var>attribute</var> is <code>_name</code>
 876 or <code>target</code> an error is returned. Use the <code>DELETE</code> command
 877 (see <a href="#DELETE">Deleting an element.</a>) instead.
 878 <br><br>
 879 </p></dd>
 880 <dt><span>ATTR LIST element[&lt;TAB&gt;child[..]]</span></dt>
 881 <dd><p>Retrieves a newline separated list of attributes names and values
 882 from the specified element. Each attribute name and value is space delimited.
 883 <br><br>
 884 </p></dd>
 885 <dt><span>ATTR GET attribute element[&lt;TAB&gt;child[..]]</span></dt>
 886 <dd><p>Retrieves the value of an <var>attribute</var> from an element.
 887 </p></dd>
 888 </dl>
 889 <br><br>
 890 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
 891 arguments are retrieved via a server <em>INQUIRE</em>.
 892 <br><br>
 893 See <a href="#Target-Attribute">The <code>target</code> attribute</a>, for details about this special attribute and also
 894 see <a href="#Other-Attributes">Other special attributes</a> for other attributes that are handled specially
 895 by <code>pwmd</code>.
 896 </p>
 897
 898 <hr>
 899 </div>
 900 <div class="section" id="BULK">
 901 <div class="header">
 902 <p>
 903 Next: <a href="#CACHETIMEOUT" accesskey="n" rel="next">Setting the cache timeout.</a>, Previous: <a href="#ATTR" accesskey="p" rel="prev">Modifying element attributes.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 904 </div>
 905 <span id="Run-a-series-of-commands-in-sequence_002e"></span><h3 class="section">8.2 Run a series of commands in sequence.</h3>
 906 <span id="index-BULK-command"></span>
 907 <p>Syntax:
 908 </p><div class="example">
 909 <pre class="example">BULK [--inquire]
 910 </pre></div>
 911
 912 <p>Parses a semi-canonical s-expression representing a series of protocol
 913 commands to be run in sequence (see <a href="#Bulk-Commands">Running multiple commands in sequence</a>). Returns a canonical
 914 s-expression containing each commands id, return value and result data
 915 (if any).
 916 <br><br>
 917 When the <samp>--inquire</samp> option is passed then all remaining non-option
 918 arguments are retrieved via a server <em>INQUIRE</em>.
 919 </p>
 920
 921 <hr>
 922 </div>
 923 <div class="section" id="CACHETIMEOUT">
 924 <div class="header">
 925 <p>
 926 Next: <a href="#CLEARCACHE" accesskey="n" rel="next">Removing a cache entry.</a>, Previous: <a href="#BULK" accesskey="p" rel="prev">Run a series of commands in sequence.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 927 </div>
 928 <span id="Setting-the-cache-timeout_002e"></span><h3 class="section">8.3 Setting the cache timeout.</h3>
 929 <span id="index-CACHETIMEOUT-command"></span>
 930 <p>Syntax:
 931 </p><div class="example">
 932 <pre class="example">CACHETIMEOUT &lt;seconds&gt;
 933 </pre></div>
 934
 935 <p>The time in <var>seconds</var> until the currently opened data file will be
 936 removed from the cache. <code>-1</code> will keep the cache entry forever,
 937 <code>0</code> will require the passphrase for each <code>OPEN</code> command
 938 (see <a href="#OPEN">Opening a data file.</a>) or <code>SAVE</code> (see <a href="#SAVE">Saving document changes to disk.</a>) command. See <a href="#Configuration"><code>pwmd</code> configuration file options</a>,
 939 and the <code>cache_timeout</code> parameter.
 940 </p>
 941
 942 <hr>
 943 </div>
 944 <div class="section" id="CLEARCACHE">
 945 <div class="header">
 946 <p>
 947 Next: <a href="#COPY" accesskey="n" rel="next">Copying an element.</a>, Previous: <a href="#CACHETIMEOUT" accesskey="p" rel="prev">Setting the cache timeout.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 948 </div>
 949 <span id="Removing-a-cache-entry_002e"></span><h3 class="section">8.4 Removing a cache entry.</h3>
 950 <span id="index-CLEARCACHE-command"></span>
 951 <p>Syntax:
 952 </p><div class="example">
 953 <pre class="example">CLEARCACHE [&lt;filename&gt;]
 954 </pre></div>
 955
 956 <p>Clears a file cache entry for all or the specified <var>filename</var>. Note that
 957 this will also clear any <code>gpg-agent</code> cached keys which may cause
 958 problems if another data file shares the same keys as <var>filename</var>.
 959 <br><br>
 960 When clearing all cache entries a permissions test is done against the
 961 current client based on the <var>allowed</var> configuration parameter in a
 962 <var>filename</var> section. Both a cache entry may be cleared and an error
 963 returned depending on cached data files and client permissions.
 964 </p>
 965
 966 <hr>
 967 </div>
 968 <div class="section" id="COPY">
 969 <div class="header">
 970 <p>
 971 Next: <a href="#DELETE" accesskey="n" rel="next">Deleting an element.</a>, Previous: <a href="#CLEARCACHE" accesskey="p" rel="prev">Removing a cache entry.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 972 </div>
 973 <span id="Copying-an-element_002e"></span><h3 class="section">8.5 Copying an element.</h3>
 974 <span id="index-COPY-command"></span>
 975 <p>Syntax:
 976 </p><div class="example">
 977 <pre class="example">COPY [--inquire] source[&lt;TAB&gt;child[..]] dest[&lt;TAB&gt;child[..]]
 978 </pre></div>
 979
 980 <p>Copies the entire element tree starting from the child node of the source
 981 element, to the destination element path. If the destination element path
 982 does not exist then it will be created; otherwise it is overwritten.
 983 <br><br>
 984 Note that attributes from the source element are merged into the
 985 destination element when the destination element path exists. When an
 986 attribute of the same name exists in both the source and destination
 987 elements then the destination attribute will be updated to the source
 988 attribute value.
 989 <br><br>
 990 When the <samp>--inquire</samp> option is passed then all remaining non-option
 991 arguments are retrieved via a server <em>INQUIRE</em>.
 992 </p>
 993
 994 <hr>
 995 </div>
 996 <div class="section" id="DELETE">
 997 <div class="header">
 998 <p>
 999 Next: <a href="#DELETEKEY" accesskey="n" rel="next">Deleting a key from the key ring.</a>, Previous: <a href="#COPY" accesskey="p" rel="prev">Copying an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1000 </div>
1001 <span id="Deleting-an-element_002e"></span><h3 class="section">8.6 Deleting an element.</h3>
1002 <span id="index-DELETE-command"></span>
1003 <p>Syntax:
1004 </p><div class="example">
1005 <pre class="example">DELETE [--inquire] element[&lt;TAB&gt;child[..]]
1006 </pre></div>
1007
1008 <p>Removes the specified element path and all of its children. This may break
1009 an element with a <code>target</code> attribute (see <a href="#Target-Attribute">The <code>target</code> attribute</a>) that
1010 refers to this element or any of its children.
1011 <br><br>
1012 When the <samp>--inquire</samp> option is passed then all remaining non-option
1013 arguments are retrieved via a server <em>INQUIRE</em>.
1014 </p>
1015
1016 <hr>
1017 </div>
1018 <div class="section" id="DELETEKEY">
1019 <div class="header">
1020 <p>
1021 Next: <a href="#DUMP" accesskey="n" rel="next">Showing the XML document.</a>, Previous: <a href="#DELETE" accesskey="p" rel="prev">Deleting an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1022 </div>
1023 <span id="Deleting-a-key-from-the-key-ring_002e"></span><h3 class="section">8.7 Deleting a key from the key ring.</h3>
1024 <span id="index-DELETEKEY-command"></span>
1025 <p>Syntax:
1026 </p><div class="example">
1027 <pre class="example">DELETEKEY &lt;keyid&gt;
1028 </pre></div>
1029
1030 <p>Deletes the public and secret key associated with key <var>keyid</var> from the
1031 keyring. The <var>keyid</var> must be one associated with the currently opened
1032 data file.
1033 Note that no confirmation occurs. Also note that when the key is deleted,
1034 the current or other data files using this key will no longer be able to be
1035 opened.
1036 </p>
1037
1038 <hr>
1039 </div>
1040 <div class="section" id="DUMP">
1041 <div class="header">
1042 <p>
1043 Next: <a href="#GENKEY" accesskey="n" rel="next">Generating a new key.</a>, Previous: <a href="#DELETEKEY" accesskey="p" rel="prev">Deleting a key from the key ring.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1044 </div>
1045 <span id="Showing-the-XML-document_002e"></span><h3 class="section">8.8 Showing the XML document.</h3>
1046 <span id="index-DUMP-command"></span>
1047 <p>Syntax:
1048 </p><div class="example">
1049 <pre class="example">DUMP
1050 </pre></div>
1051
1052 <p>Shows the in memory <abbr>XML</abbr> document with indenting. See <a href="#XPATH">Modifying more than one element.</a>, for
1053 dumping a specific node.
1054 </p>
1055
1056 <hr>
1057 </div>
1058 <div class="section" id="GENKEY">
1059 <div class="header">
1060 <p>
1061 Next: <a href="#GET" accesskey="n" rel="next">Getting the content of an element.</a>, Previous: <a href="#DUMP" accesskey="p" rel="prev">Showing the XML document.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1062 </div>
1063 <span id="Generating-a-new-key_002e"></span><h3 class="section">8.9 Generating a new key.</h3>
1064 <span id="index-GENKEY-command"></span>
1065 <p>Syntax:
1066 </p><div class="example">
1067 <pre class="example">GENKEY --subkey-of=fpr | --userid=&quot;str&quot; [--no-expire | --expire=N] [--algo=&quot;str&quot;] [--no-passphrase] [--usage=&quot;default|sign|encrypt&quot;]
1068 </pre></div>
1069
1070 <p>Generates a new key based on option arguments. One of
1071 <samp>--subkey-of</samp> or <samp>--userid</samp> is
1072 required. The <samp>--subkey-of</samp> option will generate a subkey for the key
1073 of the specified fingerprint.
1074 </p>
1075
1076 <hr>
1077 </div>
1078 <div class="section" id="GET">
1079 <div class="header">
1080 <p>
1081 Next: <a href="#GETCONFIG" accesskey="n" rel="next">Obtaining a configuration value.</a>, Previous: <a href="#GENKEY" accesskey="p" rel="prev">Generating a new key.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1082 </div>
1083 <span id="Getting-the-content-of-an-element_002e"></span><h3 class="section">8.10 Getting the content of an element.</h3>
1084 <span id="index-GET-command"></span>
1085 <p>Syntax:
1086 </p><div class="example">
1087 <pre class="example">GET [--inquire] element[&lt;TAB&gt;child[..]]
1088 </pre></div>
1089
1090 <p>Retrieves the content of the specified element. The content is returned
1091 with a data response.
1092 <br><br>
1093 When the <samp>--inquire</samp> option is passed then all remaining non-option
1094 arguments are retrieved via a server <em>INQUIRE</em>.
1095 </p>
1096
1097 <hr>
1098 </div>
1099 <div class="section" id="GETCONFIG">
1100 <div class="header">
1101 <p>
1102 Next: <a href="#GETINFO" accesskey="n" rel="next">Obtaining server and client information.</a>, Previous: <a href="#GET" accesskey="p" rel="prev">Getting the content of an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1103 </div>
1104 <span id="Obtaining-a-configuration-value_002e"></span><h3 class="section">8.11 Obtaining a configuration value.</h3>
1105 <span id="index-GETCONFIG-command"></span>
1106 <p>Syntax:
1107 </p><div class="example">
1108 <pre class="example">GETCONFIG [filename] &lt;parameter&gt;
1109 </pre></div>
1110
1111 <p>Returns the value of a <code>pwmd</code> configuration <var>parameter</var> with a
1112 data response. If no file has been opened then the value for <var>filename</var>
1113 or the default from the <var>global</var> section will be returned. If a file
1114 has been opened and no <var>filename</var> is specified, the value previously
1115 set with the <code>OPTION</code> command (see <a href="#OPTION">Setting various client parameters.</a>) will be returned.
1116 </p>
1117
1118 <hr>
1119 </div>
1120 <div class="section" id="GETINFO">
1121 <div class="header">
1122 <p>
1123 Next: <a href="#HELP" accesskey="n" rel="next">Showing available commands.</a>, Previous: <a href="#GETCONFIG" accesskey="p" rel="prev">Obtaining a configuration value.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1124 </div>
1125 <span id="Obtaining-server-and-client-information_002e"></span><h3 class="section">8.12 Obtaining server and client information.</h3>
1126 <span id="index-GETINFO-command"></span>
1127 <p>Syntax:
1128 </p><div class="example">
1129 <pre class="example">GETINFO [--data] [--verbose] CACHE | CLIENTS | PID | USER | LAST_ERROR | VERSION
1130 </pre></div>
1131
1132 <p>Get server and other information. The information is returned via a status
1133 message (see <a href="#Status-Messages">Status messages and their meanings</a>) unless otherwise noted or <samp>--data</samp>
1134 is specified.
1135 <br><br>
1136 <var>CACHE</var> returns the number of cached documents.
1137 <br><br>
1138 <var>CLIENTS</var> returns the number of
1139 connected clients via a status message or a list of connected clients when
1140 the <samp>--verbose</samp> parameter is used (implies <samp>--data</samp>). A
1141 verbose line of a client list contains
1142 space delimited
1143 fields: the thread ID, client name, opened file (<code>/</code> if none opened),
1144 IP address if remote, file lock status, whether the current client is self
1145 or not, client state (see below),
1146 user ID or TLS fingerprint of the connected client, username if the
1147 client is a local one else <code>-</code>, and finally the time stamp of when the
1148 client connected.
1149 <br><br>
1150 Client state <code>0</code> is an unknown client state, state <code>1</code> indicates
1151 the client has connected but hasn&rsquo;t completed initializing, state <code>2</code>
1152 indicates that the client is idle, state <code>3</code> means the
1153 client is in a command and state <code>4</code> means the client is disconnecting.
1154 <br><br>
1155 <var>PID</var> returns the process ID number of the server via a data response.
1156 <br><br>
1157 <var>VERSION</var> returns the server version number and compile-time features
1158 via a data response with each being space delimited.
1159 <br><br>
1160 <var>LAST_ERROR</var> returns a detailed description of the last failed command
1161 via a data response, when available.
1162 <br><br>
1163 <var>USER</var> returns the username or <abbr>TLS</abbr> hash of the connected client
1164 via a data response.
1165 </p>
1166
1167 <hr>
1168 </div>
1169 <div class="section" id="HELP">
1170 <div class="header">
1171 <p>
1172 Next: <a href="#IMPORT" accesskey="n" rel="next">Creating elements from XML.</a>, Previous: <a href="#GETINFO" accesskey="p" rel="prev">Obtaining server and client information.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1173 </div>
1174 <span id="Showing-available-commands_002e"></span><h3 class="section">8.13 Showing available commands.</h3>
1175 <span id="index-HELP-command"></span>
1176 <p>Syntax:
1177 </p><div class="example">
1178 <pre class="example">HELP [--html] [&lt;COMMAND&gt;]
1179 </pre></div>
1180
1181 <p>Show available commands or command specific help text.
1182 <br><br>
1183 The <samp>--html</samp> option will output the help text in HTML format.
1184 </p>
1185
1186 <hr>
1187 </div>
1188 <div class="section" id="IMPORT">
1189 <div class="header">
1190 <p>
1191 Next: <a href="#ISCACHED" accesskey="n" rel="next">Testing cache status.</a>, Previous: <a href="#HELP" accesskey="p" rel="prev">Showing available commands.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1192 </div>
1193 <span id="Creating-elements-from-XML_002e"></span><h3 class="section">8.14 Creating elements from XML.</h3>
1194 <span id="index-IMPORT-command"></span>
1195 <p>Syntax:
1196 </p><div class="example">
1197 <pre class="example">IMPORT [--root=element[&lt;TAB&gt;child[..]]]
1198 </pre></div>
1199
1200 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
1201 <br><br>
1202 Like the <code>STORE</code> command (see <a href="#STORE">Modifying the content of an element.</a>), but the <var>content</var>
1203 argument is raw <abbr>XML</abbr> data. The content is created as a child of
1204 the element path specified with the <samp>--root</samp> option or at the
1205 document root when not specified. Existing elements of the same name will
1206 be overwritten.
1207 <br><br>
1208 The content must begin with an <abbr>XML</abbr> element node. See <a href="#Introduction">Overview of <code>pwmd</code></a>,
1209 for details.
1210 </p>
1211
1212 <hr>
1213 </div>
1214 <div class="section" id="ISCACHED">
1215 <div class="header">
1216 <p>
1217 Next: <a href="#KEYINFO" accesskey="n" rel="next">Showing keys used for the current data file.</a>, Previous: <a href="#IMPORT" accesskey="p" rel="prev">Creating elements from XML.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1218 </div>
1219 <span id="Testing-cache-status_002e"></span><h3 class="section">8.15 Testing cache status.</h3>
1220 <span id="index-ISCACHED-command"></span>
1221 <p>Syntax:
1222 </p><div class="example">
1223 <pre class="example">ISCACHED [--lock] [--agent [--sign]] &lt;filename&gt;
1224 </pre></div>
1225
1226 <p>Determines the file cache status of the specified <var>filename</var>.
1227 The default is to test whether the filename is cached in memory. Passing
1228 option <samp>--agent</samp> will test the <code>gpg-agent</code> cache for at most
1229 one cached key used for opening the data file (see <a href="#OPEN">Opening a data file.</a>). To test if
1230 a signing key is cached, pass <samp>--sign</samp> along with <samp>--agent</samp>.
1231 Both the <samp>--agent</samp> and <samp>--sign</samp> options require an opened data
1232 file.
1233 <br><br>
1234 An <em>OK</em> response is returned if the specified <var>filename</var> is found
1235 in the cache. If not found in the cache but exists on the filesystem
1236 then <code>GPG_ERR_NO_DATA</code> is returned. Otherwise a filesystem error is
1237 returned.
1238 <br><br>
1239 The <samp>--lock</samp> option will lock the file mutex of <var>filename</var> when
1240 the file exists; it does not need to be opened nor cached. The lock will be
1241 released when the client exits or sends the <code>UNLOCK</code> command
1242 (see <a href="#UNLOCK">Removing a data file lock.</a>). When this option is passed the current data file is closed.
1243 </p>
1244
1245 <hr>
1246 </div>
1247 <div class="section" id="KEYINFO">
1248 <div class="header">
1249 <p>
1250 Next: <a href="#KILL" accesskey="n" rel="next">Terminating another client.</a>, Previous: <a href="#ISCACHED" accesskey="p" rel="prev">Testing cache status.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1251 </div>
1252 <span id="Showing-keys-used-for-the-current-data-file_002e"></span><h3 class="section">8.16 Showing keys used for the current data file.</h3>
1253 <span id="index-KEYINFO-command"></span>
1254 <p>Syntax:
1255 </p><div class="example">
1256 <pre class="example">KEYINFO [--learn]
1257 </pre></div>
1258
1259 <p>Returns a new line separated list of key ID&rsquo;s that the currently opened
1260 data file has recipients and signers for. If the key is a signing key it
1261 will be prefixed with an <code>S</code>. If the file is a new one, or has no
1262 signers in the case of being symmetrically encrypted, the error code
1263 <code>GPG_ERR_NO_DATA</code> is returned.
1264 <br><br>
1265 When the <samp>--learn</samp> option is passed, keys on a smartcard will be
1266 imported.
1267 </p>
1268
1269 <hr>
1270 </div>
1271 <div class="section" id="KILL">
1272 <div class="header">
1273 <p>
1274 Next: <a href="#LIST" accesskey="n" rel="next">Showing document elements.</a>, Previous: <a href="#KEYINFO" accesskey="p" rel="prev">Showing keys used for the current data file.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1275 </div>
1276 <span id="Terminating-another-client_002e"></span><h3 class="section">8.17 Terminating another client.</h3>
1277 <span id="index-KILL-command"></span>
1278 <p>Syntax:
1279 </p><div class="example">
1280 <pre class="example">KILL &lt;thread_id&gt;
1281 </pre></div>
1282
1283 <p>Terminates the client identified by <var>thread_id</var> and releases any file
1284 lock or other resources it has held. See <code>GETINFO</code> (see <a href="#GETINFO">Obtaining server and client information.</a>)
1285 for details about listing connected clients. An <code>invoking_user</code>
1286 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) may kill any client while others may only kill
1287 clients of the same <code>UID</code> or <abbr>TLS</abbr> fingerprint.
1288 </p>
1289
1290 <hr>
1291 </div>
1292 <div class="section" id="LIST">
1293 <div class="header">
1294 <p>
1295 Next: <a href="#LISTKEYS" accesskey="n" rel="next">Listing keys in the key ring.</a>, Previous: <a href="#KILL" accesskey="p" rel="prev">Terminating another client.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1296 </div>
1297 <span id="Showing-document-elements_002e"></span><h3 class="section">8.18 Showing document elements.</h3>
1298 <span id="index-LIST-command"></span>
1299 <p>Syntax:
1300 </p><div class="example">
1301 <pre class="example">LIST [--inquire] [--recurse] [--sexp] [element[&lt;TAB&gt;child[..]]]
1302 </pre></div>
1303
1304 <p>If no element path is given then a newline separated list of root elements
1305 is returned with a data response. If given, then children of the specified
1306 element path are returned.
1307 <br><br>
1308 Each element path
1309 returned will have zero or more flags appened to it. These flags are
1310 delimited from the element path by a single space character. A flag itself
1311 is a single character. Flag <code>P</code> indicates that access to the element
1312 is denied. Flag <code>+</code> indicates that there are child nodes of
1313 the current element path. Flag <code>E</code> indicates that an element of the
1314 element path contained in a <var>target</var> attribute could not be found. Flag
1315 <code>O</code> indicates that a <var>target</var> attribute recursion limit was reached
1316 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>). Flag <code>T</code>, followed by a single space character,
1317 then an element path, is the element path of the <var>target</var> attribute
1318 contained in the current element.
1319 <br><br>
1320 When a specified element path contains an error either from the final
1321 element in the path or any previous element, the path is still shown but
1322 will contain the error flag for the element with the error. Determining
1323 the actual element which contains the error is up to the client. This can be
1324 done by traversing the final element up to parent elements that contain the
1325 same error flag.
1326 <br><br>
1327 The option <samp>--recurse</samp> may be used to list the entire element tree
1328 for a specified element path or the entire tree for all root elements.
1329 <br><br>
1330 The option <samp>--sexp</samp> outputs the list in an s-expression and also
1331 appends an elements&rsquo; attributes and attribute values. The syntax is:
1332 </p>
1333 <div class="example">
1334 <pre class="example">(11:list-result
1335   (4:path N:&lt;path&gt; 5:flags N:&lt;flags&gt;
1336     (5:attrs N:&lt;name&gt; N:&lt;value&gt; ...)
1337   )
1338   ...
1339 )
1340 </pre></div>
1341
1342 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1343 arguments are retrieved via a server <em>INQUIRE</em>.
1344 </p>
1345
1346 <hr>
1347 </div>
1348 <div class="section" id="LISTKEYS">
1349 <div class="header">
1350 <p>
1351 Next: <a href="#LOCK" accesskey="n" rel="next">Locking the current data file.</a>, Previous: <a href="#LIST" accesskey="p" rel="prev">Showing document elements.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1352 </div>
1353 <span id="Listing-keys-in-the-key-ring_002e"></span><h3 class="section">8.19 Listing keys in the key ring.</h3>
1354 <span id="index-LISTKEYS-command"></span>
1355 <p>Syntax:
1356 </p><div class="example">
1357 <pre class="example">LISTKEYS [--secret-only] [pattern[,&lt;pattern&gt;]]
1358 </pre></div>
1359
1360 <p>Returns a new line separated list of key information matching a comma
1361 separated list of <var>pattern</var>&rsquo;s. When option <samp>--secret-only</samp> is
1362 specified, only keys matching <var>pattern</var> that also have a secret key
1363 available will be returned.
1364 </p>
1365
1366 <hr>
1367 </div>
1368 <div class="section" id="LOCK">
1369 <div class="header">
1370 <p>
1371 Next: <a href="#LS" accesskey="n" rel="next">Showing available data files.</a>, Previous: <a href="#LISTKEYS" accesskey="p" rel="prev">Listing keys in the key ring.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1372 </div>
1373 <span id="Locking-the-current-data-file_002e"></span><h3 class="section">8.20 Locking the current data file.</h3>
1374 <span id="index-LOCK-command"></span>
1375 <p>Syntax:
1376 </p><div class="example">
1377 <pre class="example">LOCK
1378 </pre></div>
1379
1380 <p>Locks the mutex associated with the opened file. This prevents other clients
1381 from sending commands to the same opened file until the client
1382 that sent this command either disconnects or sends the <code>UNLOCK</code>
1383 command. See <a href="#UNLOCK">Removing a data file lock.</a>.
1384 </p>
1385
1386 <hr>
1387 </div>
1388 <div class="section" id="LS">
1389 <div class="header">
1390 <p>
1391 Next: <a href="#MOVE" accesskey="n" rel="next">Moving an element.</a>, Previous: <a href="#LOCK" accesskey="p" rel="prev">Locking the current data file.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1392 </div>
1393 <span id="Showing-available-data-files_002e"></span><h3 class="section">8.21 Showing available data files.</h3>
1394 <span id="index-LS-command"></span>
1395 <p>Syntax:
1396 </p><div class="example">
1397 <pre class="example">LS [--verbose]
1398 </pre></div>
1399
1400 <p>Returns a newline separated list of data files stored in the data directory
1401 <samp>HOMEDIR/data</samp> (see <a href="#Invoking">Invoking <code>pwmd</code></a>) with a data response. When the
1402 <var>&ndash;verbose</var> option is passed, the space-separated filesystem inode
1403 access, modification and change times are appended to the line.
1404 </p>
1405
1406 <hr>
1407 </div>
1408 <div class="section" id="MOVE">
1409 <div class="header">
1410 <p>
1411 Next: <a href="#NOP" accesskey="n" rel="next">Testing the connection.</a>, Previous: <a href="#LS" accesskey="p" rel="prev">Showing available data files.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1412 </div>
1413 <span id="Moving-an-element_002e"></span><h3 class="section">8.22 Moving an element.</h3>
1414 <span id="index-MOVE-command"></span>
1415 <p>Syntax:
1416 </p><div class="example">
1417 <pre class="example">MOVE [--inquire] source[&lt;TAB&gt;child[..]] [dest[&lt;TAB&gt;child[..]]]
1418 </pre></div>
1419
1420 <p>Moves the source element path to the destination element path. If the
1421 destination is not specified then it will be moved to the root node of the
1422 document. If the destination is specified and exists then it will be
1423 overwritten; otherwise non-existing elements of the destination element
1424 path will be created.
1425 <br><br>
1426 When the <samp>--inquire</samp> option is passed then all remaining non-option
1427 arguments are retrieved via a server <em>INQUIRE</em>.
1428 </p>
1429
1430 <hr>
1431 </div>
1432 <div class="section" id="NOP">
1433 <div class="header">
1434 <p>
1435 Next: <a href="#OPEN" accesskey="n" rel="next">Opening a data file.</a>, Previous: <a href="#MOVE" accesskey="p" rel="prev">Moving an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1436 </div>
1437 <span id="Testing-the-connection_002e"></span><h3 class="section">8.23 Testing the connection.</h3>
1438 <span id="index-NOP-command"></span>
1439 <p>Syntax:
1440 </p><div class="example">
1441 <pre class="example">NOP
1442 </pre></div>
1443
1444 <p>This command does nothing. It is useful for testing the connection for a
1445 timeout condition.
1446 </p>
1447
1448 <hr>
1449 </div>
1450 <div class="section" id="OPEN">
1451 <div class="header">
1452 <p>
1453 Next: <a href="#OPTION" accesskey="n" rel="next">Setting various client parameters.</a>, Previous: <a href="#NOP" accesskey="p" rel="prev">Testing the connection.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1454 </div>
1455 <span id="Opening-a-data-file_002e"></span><h3 class="section">8.24 Opening a data file.</h3>
1456 <span id="index-OPEN-command"></span>
1457 <p>Syntax:
1458 </p><div class="example">
1459 <pre class="example">OPEN [--lock] &lt;filename&gt;
1460 </pre></div>
1461
1462 <p>Opens <var>filename</var>. When the <var>filename</var> is not found on the
1463 file-system then a new in-memory document will be created. If the file is
1464 found, it is looked for in the file cache and when found no passphrase will
1465 be required to open it. When not cached, <cite>pinentry(1)</cite> will be used to
1466 retrieve the passphrase for decryption unless <samp>disable-pinentry</samp>
1467 (see <a href="#OPTION">Setting various client parameters.</a>) was specified in which case <code>pwmd</code> will
1468 <em>INQUIRE</em> the client for the passphrase. Note than when configuration
1469 option <samp>strict_open</samp> is enabled and the client is not an
1470 <samp>invoking_user</samp>, an error will be returned when the data file does
1471 not exist.
1472 <br><br>
1473 When the <samp>--lock</samp> option is passed then the file mutex will be
1474 locked as if the <code>LOCK</code> command (see <a href="#LOCK">Locking the current data file.</a>) had been sent after the
1475 file had been opened.
1476 </p>
1477
1478 <hr>
1479 </div>
1480 <div class="section" id="OPTION">
1481 <div class="header">
1482 <p>
1483 Next: <a href="#PASSWD" accesskey="n" rel="next">Changing the passphrase for a key.</a>, Previous: <a href="#OPEN" accesskey="p" rel="prev">Opening a data file.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1484 </div>
1485 <span id="Setting-various-client-parameters_002e"></span><h3 class="section">8.25 Setting various client parameters.</h3>
1486 <span id="index-OPTION-command"></span>
1487 <p>Syntax:
1488 </p><div class="example">
1489 <pre class="example">OPTION &lt;NAME&gt;=[&lt;VALUE&gt;]
1490 </pre></div>
1491
1492 <p>Sets a client option <var>name</var> to <var>value</var>. The value for an option is
1493 kept for the duration of the connection with the exception of the
1494 <code>pinentry</code> options which are defaults for all future connections
1495 (see <a href="#Pinentry">Pinentry configuration</a>). When <var>value</var> is empty the option is unset.
1496 <br><br>
1497 </p><dl compact="compact">
1498 <dt><span>DISABLE-PINENTRY</span></dt>
1499 <dd><p>Disable use of <code>pinentry</code> for passphrase retrieval. When <code>1</code>, a
1500 server inquire is sent to the client to obtain the passphrase. This option
1501 may be set as needed before the <code>OPEN</code> (see <a href="#OPEN">Opening a data file.</a>), <code>PASSWD</code>
1502 (see <a href="#PASSWD">Changing the passphrase for a key.</a>) and <code>SAVE</code> (see <a href="#SAVE">Saving document changes to disk.</a>) commands. Set to <code>0</code>
1503 to use a <code>pinentry</code>.
1504 <br><br>
1505 </p></dd>
1506 <dt><span>DISPLAY</span></dt>
1507 <dd><p>Set or unset the X11 display to use when prompting for a passphrase.
1508 <br><br>
1509 </p></dd>
1510 <dt><span>TTYNAME</span></dt>
1511 <dd><p>Set the terminal device path to use when prompting for a passphrase.
1512 <br><br>
1513 </p></dd>
1514 <dt><span>TTYTYPE</span></dt>
1515 <dd><p>Set the terminal type for use with <samp>TTYNAME</samp>.
1516 <br><br>
1517 </p></dd>
1518 <dt><span>NAME</span></dt>
1519 <dd><p>Associates the thread ID of the connection with the specified textual
1520 representation. Useful for debugging log messages. May not contain whitespace.
1521 <br><br>
1522 </p></dd>
1523 <dt><span>LOCK-TIMEOUT</span></dt>
1524 <dd><p>When not <code>0</code>, the duration in tenths of a second to wait for the file
1525 mutex which has been locked by another thread to be released before returning
1526 an error. When <code>-1</code> the error will be returned immediately.
1527 <br><br>
1528 </p></dd>
1529 <dt><span>CLIENT-STATE</span></dt>
1530 <dd><p>When set to <code>1</code> then client state status messages for other clients are
1531 sent to the current client. The default is <code>0</code>.
1532 </p></dd>
1533 </dl>
1534
1535
1536 <hr>
1537 </div>
1538 <div class="section" id="PASSWD">
1539 <div class="header">
1540 <p>
1541 Next: <a href="#REALPATH" accesskey="n" rel="next">Resolving an element.</a>, Previous: <a href="#OPTION" accesskey="p" rel="prev">Setting various client parameters.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1542 </div>
1543 <span id="Changing-the-passphrase-for-a-key_002e"></span><h3 class="section">8.26 Changing the passphrase for a key.</h3>
1544 <span id="index-PASSWD-command"></span>
1545 <p>Syntax:
1546 </p><div class="example">
1547 <pre class="example">PASSWD
1548 </pre></div>
1549
1550 <p>Changes the passphrase of the secret key required to open the current
1551 data file. If the data file is symmetrically encrypted the error
1552 <code>GPG_ERR_NOT_SUPPORTED</code> is returned. When symmetrically encrypted
1553 the <code>SAVE</code> command (see <a href="#SAVE">Saving document changes to disk.</a>) should be used instead to prevent
1554 this command saving any unwanted changes to the <abbr>XML</abbr> document.
1555 <br><br>
1556 Note that when the current data file has been either encrypted or signed
1557 with a key stored on a smartcard this command will return an error. In this
1558 case you should instead use <code>gpg --card-edit</code> to change the
1559 pin of the smartcard or <code>gpg --edit-key</code> to change the passphrase
1560 of the key used to sign or encrypt the data file.
1561 <br><br>
1562 This command is not available to non-invoking clients
1563 (see <a href="#Access-Control">Access Control</a>).
1564 </p>
1565
1566 <hr>
1567 </div>
1568 <div class="section" id="REALPATH">
1569 <div class="header">
1570 <p>
1571 Next: <a href="#RENAME" accesskey="n" rel="next">Renaming an element.</a>, Previous: <a href="#PASSWD" accesskey="p" rel="prev">Changing the passphrase for a key.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1572 </div>
1573 <span id="Resolving-an-element_002e"></span><h3 class="section">8.27 Resolving an element.</h3>
1574 <span id="index-REALPATH-command"></span>
1575 <p>Syntax:
1576 </p><div class="example">
1577 <pre class="example">REALPATH [--inquire] element[&lt;TAB&gt;child[..]]
1578 </pre></div>
1579
1580 <p>Resolves all <code>target</code> attributes of the specified element path and
1581 returns the result with a data response. See <a href="#Target-Attribute">The <code>target</code> attribute</a>, for details.
1582 <br><br>
1583 When the <samp>--inquire</samp> option is passed then all remaining non-option
1584 arguments are retrieved via a server <em>INQUIRE</em>.
1585 </p>
1586
1587 <hr>
1588 </div>
1589 <div class="section" id="RENAME">
1590 <div class="header">
1591 <p>
1592 Next: <a href="#RESET" accesskey="n" rel="next">Resetting the client state.</a>, Previous: <a href="#REALPATH" accesskey="p" rel="prev">Resolving an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1593 </div>
1594 <span id="Renaming-an-element_002e"></span><h3 class="section">8.28 Renaming an element.</h3>
1595 <span id="index-RENAME-command"></span>
1596 <p>Syntax:
1597 </p><div class="example">
1598 <pre class="example">RENAME [--inquire] element[&lt;TAB&gt;child[..]] &lt;value&gt;
1599 </pre></div>
1600
1601 <p>Renames the specified <var>element</var> to the new <var>value</var>. If an element of
1602 the same name as the <var>value</var> already exists it will be overwritten.
1603 <br><br>
1604 When the <samp>--inquire</samp> option is passed then all remaining non-option
1605 arguments are retrieved via a server <em>INQUIRE</em>.
1606 </p>
1607
1608 <hr>
1609 </div>
1610 <div class="section" id="RESET">
1611 <div class="header">
1612 <p>
1613 Next: <a href="#SAVE" accesskey="n" rel="next">Saving document changes to disk.</a>, Previous: <a href="#RENAME" accesskey="p" rel="prev">Renaming an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1614 </div>
1615 <span id="Resetting-the-client-state_002e"></span><h3 class="section">8.29 Resetting the client state.</h3>
1616 <span id="index-RESET-command"></span>
1617 <p>Syntax:
1618 </p><div class="example">
1619 <pre class="example">RESET
1620 </pre></div>
1621
1622 <p>Closes the currently opened file but keeps any previously set client options
1623 (see <a href="#OPTION">Setting various client parameters.</a>).
1624 </p>
1625
1626 <hr>
1627 </div>
1628 <div class="section" id="SAVE">
1629 <div class="header">
1630 <p>
1631 Next: <a href="#STORE" accesskey="n" rel="next">Modifying the content of an element.</a>, Previous: <a href="#RESET" accesskey="p" rel="prev">Resetting the client state.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1632 </div>
1633 <span id="Saving-document-changes-to-disk_002e"></span><h3 class="section">8.30 Saving document changes to disk.</h3>
1634 <span id="index-SAVE-command"></span>
1635 <p>Syntax:
1636 </p><div class="example">
1637 <pre class="example">SAVE [--sign-keyid=[&lt;fpr&gt;]] [--symmetric | --keyid=&lt;fpr&gt;[,..] | --inquire-keyid]
1638 </pre></div>
1639
1640 <p>Writes the in-memory <abbr>XML</abbr> document to disk. The file written to is the
1641 file that was opened when using the <code>OPEN</code> command (see <a href="#OPEN">Opening a data file.</a>).
1642 <br><br>
1643 If the file is a new one one of <samp>--symmetric</samp>, <samp>--keyid</samp> or
1644 <samp>--inquire-keyid</samp> is required. When not <samp>--symmetric</samp> the
1645 option <samp>--sign-keyid</samp> is also required but optional otherwise.
1646 <br><br>
1647 You can encrypt the data file to a recipient other than the one that it
1648 was originally encrypted with by passing the <samp>--keyid</samp> or
1649 <samp>--inquire-keyid</samp> option with a comma separated list of
1650 public encryption key fingerprints as its argument. Use the
1651 <code>LISTKEYS</code> command (see <a href="#LISTKEYS">Listing keys in the key ring.</a>) to show key information by
1652 pattern. The <samp>--sign-keyid</samp> option may also be used to sign the data
1653 file with an alternate key by specifying the fingerprint of a signing key.
1654 Only one signing key is supported unlike the <samp>--keyid</samp> option.
1655 A passphrase to decrypt the data file
1656 will be required when one or more of the original encryption keys or signing
1657 key are not found in either of these two options&rsquo; arguments or when the data
1658 file is symmetrically encrypted regardless of the <code>require_save_key</code>
1659 configuration parameter. The original encryption keys and signing key will be
1660 used when neither of these options are specified.
1661 <br><br>
1662 The <samp>--keyid</samp> and <samp>--sign-keyid</samp> options are not available
1663 to non-invoking clients
1664 (see <a href="#Access-Control">Access Control</a>) when the recipients or signer do not match those
1665 that were used when the file was <code>OPEN</code>&rsquo;ed.
1666 <br><br>
1667 The <samp>--symmetric</samp> option specifies that a new data file be
1668 conventionally encrypted. These types of data files do not use a recipient
1669 public key but may optionally be signed by using the <samp>--sign-keyid</samp>
1670 option. To remove the signing key from a symmtrically encrypted data file,
1671 leave the option value empty.
1672 <br><br>
1673 Note that you cannot change encryption schemes once a data file has been
1674 saved.
1675 </p>
1676
1677 <hr>
1678 </div>
1679 <div class="section" id="STORE">
1680 <div class="header">
1681 <p>
1682 Next: <a href="#UNLOCK" accesskey="n" rel="next">Removing a data file lock.</a>, Previous: <a href="#SAVE" accesskey="p" rel="prev">Saving document changes to disk.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1683 </div>
1684 <span id="Modifying-the-content-of-an-element_002e"></span><h3 class="section">8.31 Modifying the content of an element.</h3>
1685 <span id="index-STORE-command"></span>
1686 <p>Syntax:
1687 </p><div class="example">
1688 <pre class="example">STORE [--no-inherit-acl] element[&lt;TAB&gt;child[..]]&lt;TAB&gt;[content]
1689 </pre></div>
1690
1691 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
1692 <br><br>
1693 Creates a new element path or modifies the <var>content</var> of an existing
1694 element. If only a single element is specified then a new root element is
1695 created. Otherwise, elements are <tt class="key">TAB</tt> delimited and the content will be
1696 set to the final <tt class="key">TAB</tt> delimited element. If no <var>content</var> is
1697 specified after the final <tt class="key">TAB</tt>, then the content of the existing
1698 element will be removed; or will be empty if creating a new element.
1699 <br><br>
1700 The option <samp>--no-inherit-acl</samp> prevents a newly created element from
1701 inheriting the value of the parent element <code>_acl</code> attribute. In either
1702 case, the current user is made the owner of the newly created element(s).
1703 <br><br>
1704 The only restriction of an element name is that it not contain whitespace
1705 characters. There is no other whitespace between the <tt class="key">TAB</tt> delimited
1706 elements. It is recommended that the content of an element be base64 encoded
1707 when it contains control or <tt class="key">TAB</tt> characters to prevent <abbr>XML</abbr>
1708 parsing and <code>pwmd</code> syntax errors.
1709 </p>
1710
1711 <hr>
1712 </div>
1713 <div class="section" id="UNLOCK">
1714 <div class="header">
1715 <p>
1716 Next: <a href="#XPATH" accesskey="n" rel="next">Modifying more than one element.</a>, Previous: <a href="#STORE" accesskey="p" rel="prev">Modifying the content of an element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1717 </div>
1718 <span id="Removing-a-data-file-lock_002e"></span><h3 class="section">8.32 Removing a data file lock.</h3>
1719 <span id="index-UNLOCK-command"></span>
1720 <p>Syntax:
1721 </p><div class="example">
1722 <pre class="example">UNLOCK
1723 </pre></div>
1724
1725 <p>Unlocks the file mutex which was locked with the <code>LOCK</code> command or
1726 a commands&rsquo; <samp>--lock</samp> option (see <a href="#LOCK">Locking the current data file.</a>, see <a href="#OPEN">Opening a data file.</a>,
1727 see <a href="#ISCACHED">Testing cache status.</a>).
1728 </p>
1729
1730 <hr>
1731 </div>
1732 <div class="section" id="XPATH">
1733 <div class="header">
1734 <p>
1735 Next: <a href="#XPATHATTR" accesskey="n" rel="next">Modifying more than one element&rsquo;s attributes.</a>, Previous: <a href="#UNLOCK" accesskey="p" rel="prev">Removing a data file lock.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1736 </div>
1737 <span id="Modifying-more-than-one-element_002e"></span><h3 class="section">8.33 Modifying more than one element.</h3>
1738 <span id="index-XPATH-command"></span>
1739 <p>Syntax:
1740 </p><div class="example">
1741 <pre class="example">XPATH [--inquire] &lt;expression&gt;[&lt;TAB&gt;[value]]
1742 </pre></div>
1743
1744 <p>Evaluates an XPath <var>expression</var>. If no <var>value</var> argument is
1745 specified it is assumed the expression is a request to return a result.
1746 Otherwise, the result is set to the <var>value</var> argument and the document is
1747 updated. If there is no <var>value</var> after the <tt class="key">TAB</tt> character, the value
1748 is assumed to be empty and the document is updated. For example:
1749 </p><br>
1750 <div class="example">
1751 <pre class="example">XPATH //element[@_name='password']<span class="key">TAB</span>
1752 </pre></div>
1753 <br>
1754 <p>would clear the content of all <var>password</var> elements in the data file
1755 while leaving off the trailing <tt class="key">TAB</tt> would return all <var>password</var>
1756 elements in <abbr>XML</abbr> format.
1757 <br><br>
1758 When the <samp>--inquire</samp> option is passed then all remaining non-option
1759 arguments are retrieved via a server <em>INQUIRE</em>.
1760 <br><br>
1761 See <a href="https://www.w3schools.com/xml/xpath_intro.asp">https://www.w3schools.com/xml/xpath_intro.asp</a> for <abbr>XPATH</abbr>
1762 expression syntax.
1763 </p>
1764
1765 <hr>
1766 </div>
1767 <div class="section" id="XPATHATTR">
1768 <div class="header">
1769 <p>
1770 Previous: <a href="#XPATH" accesskey="p" rel="prev">Modifying more than one element.</a>, Up: <a href="#Commands" accesskey="u" rel="up">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1771 </div>
1772 <span id="Modifying-more-than-one-element_0027s-attributes_002e"></span><h3 class="section">8.34 Modifying more than one element&rsquo;s attributes.</h3>
1773 <span id="index-XPATHATTR-command"></span>
1774 <p>Syntax:
1775 </p><div class="example">
1776 <pre class="example">XPATHATTR [--inquire] SET|DELETE &lt;name&gt; &lt;expression&gt;[&lt;TAB&gt;[&lt;value&gt;]]
1777 </pre></div>
1778
1779 <p>Like the <code>XPATH</code> command (see <a href="#XPATH">Modifying more than one element.</a>) but operates on element
1780 attributes and does not return a result. For the <var>SET</var> operation the
1781 <var>value</var> is optional but the field is required. If not specified then
1782 the attribute value will be empty. For example:
1783 </p><br>
1784 <div class="example">
1785 <pre class="example">XPATHATTR SET password //element[@_name='password']<span class="key">TAB</span>
1786 </pre></div>
1787 <br>
1788 <p>would create a <var>password</var> attribute for each <var>password</var> element
1789 found in the document. The attribute value will be empty but still exist.
1790 <br><br>
1791 When the <samp>--inquire</samp> option is passed then all remaining non-option
1792 arguments are retrieved via a server <em>INQUIRE</em>.
1793 <br><br>
1794 See <a href="https://www.w3schools.com/xml/xpath_intro.asp">https://www.w3schools.com/xml/xpath_intro.asp</a> for <abbr>XPATH</abbr>
1795 expression syntax.
1796 </p>
1797
1798
1799 <hr>
1800 </div>
1801 </div>
1802 <div class="chapter" id="Bulk-Commands">
1803 <div class="header">
1804 <p>
1805 Next: <a href="#Status-Messages" accesskey="n" rel="next">Status messages and their meanings</a>, Previous: <a href="#Commands" accesskey="p" rel="prev">Protocol commands and their syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1806 </div>
1807 <span id="Running-multiple-commands-in-sequence"></span><h2 class="chapter">9 Running multiple commands in sequence</h2>
1808 <p>Multiple commands may be run in sequence by using the <code>BULK</code> command
1809 (see <a href="#BULK">Run a series of commands in sequence.</a>). Using this feature may speed up remote connections since less
1810 socket IO is needed. The <code>BULK</code> command uses an <em>INQUIRE</em> to obtain
1811 an canonical s-expression of commands to be run. The s-expression syntax is as
1812 follows:
1813 </p>
1814 <div class="example">
1815 <pre class="example">(2:id&lt;I&gt;:&lt;id&gt; &lt;P&gt;:&lt;prot&gt;&lt;D&gt;:[&lt;data&gt;] [2:rc&lt;R&gt;:&lt;code&gt;[|&lt;code&gt;...](2:id...) | 2:id...])
1816 </pre></div>
1817
1818 <p>Each token is prefixed with an unsigned integer that specifies the length of
1819 the token, followed by a colon &rsquo;<code>:</code>&rsquo;, followed by the token itself. Pwmd
1820 uses token pairs to create a <em>name=value</em> relationship. Whitespace is
1821 allowed between token pairs. For example, the following is valid:
1822 </p>
1823 <div class="example">
1824 <pre class="example">( 2:id 7:FirstID 4:LIST0: 2:rc 1:0 (2:id6:Second 7:GETINFO7:version))
1825 </pre></div>
1826
1827 <p>The <code>id</code> token begins a new command and requires an <var>&lt;id&gt;</var> token
1828 of length <var>&lt;I&gt;</var> to uniquely identify this command. The next token pair is
1829 the protocol command name, without any command arguments, of length <var>&lt;P&gt;</var>
1830 to run followed by a colon &rsquo;<code>:</code>&rsquo;, followed by the command <var>&lt;prot&gt;</var>
1831 itself, followed by the length <var>&lt;D&gt;</var> of both command arguments and data,
1832 followed by a colon &rsquo;<code>:</code>&rsquo; and finally the <var>&lt;data&gt;</var> itself.  If no
1833 arguments or data are needed for the command, set the length of the data
1834 <var>&lt;D&gt;</var> to <code>0</code> and append the required colon &rsquo;<code>:</code>&rsquo;.
1835 </p>
1836 <p>A new command enclosed in parentheses may be run when the previous command
1837 returns an error code that matches the <var>&lt;code&gt;</var> token of length <var>&lt;R&gt;</var>
1838 by appending <var>rc</var> tokens to the end of the previous commands <var>&lt;data&gt;</var>
1839 token. You may also test another return code for the previous command by
1840 placing the next <var>rc</var> token at the end of the closing parentheses of the
1841 previous return code command.
1842 </p>
1843 <p>Multiple <code>rc</code> <var>code</var>&rsquo;s may be specified for a single command by
1844 separating them with a pipe <code>|</code> character. This lets you specify an
1845 <em>if-this-and-that</em> expression for a commands return code.
1846 </p>
1847 <p>If another command is to be run after the previous and does not specify an
1848 <var>rc</var> token, the return value is ignored for the previous command and the
1849 next command is run.  There is no limit on the number of commands or
1850 sub-commands except for system memory.
1851 </p>
1852 <p>After inquiring the commands to be run, <code>BULK</code> will run each command with
1853 <var>&lt;data&gt;</var> as its argument and store the result code and data of the command
1854 in a <code>bulk-result</code> canonical s-expression of the syntax:
1855 </p>
1856 <div class="example">
1857 <pre class="example">(11:bulk-result2:id&lt;I&gt;:&lt;id&gt;2:rc&lt;R&gt;:&lt;code&gt;&lt;D&gt;:[&lt;data&gt;][2:id...])
1858 </pre></div>
1859
1860 <p>The <code>11:bulk-result</code> token begins the result of all commands. The
1861 <var>&lt;id&gt;</var> token of length <var>&lt;I&gt;</var> is the same that was associated with the
1862 command from the <em>INQUIRE</em>&rsquo;d syntax and is prefixed with <code>2:id</code>. The
1863 return code of the command is prefixed with <code>2:rc</code> followed by the length
1864 <var>&lt;R&gt;</var> of the unsigned integer <var>&lt;code&gt;</var> then the return <var>&lt;code&gt;</var>
1865 itself.  If the command returned any <var>&lt;data&gt;</var>, it is prefixed with a
1866 length <var>&lt;D&gt;</var> and immediately following the return <var>&lt;code&gt;</var>. Otherwise,
1867 <var>&lt;D&gt;</var> will be <code>0</code> and followed by a colon &rsquo;<code>:</code>&rsquo;.
1868 </p>
1869
1870 <hr>
1871 </div>
1872 <div class="chapter" id="Status-Messages">
1873 <div class="header">
1874 <p>
1875 Next: <a href="#Target-Attribute" accesskey="n" rel="next">The <code>target</code> attribute</a>, Previous: <a href="#Bulk-Commands" accesskey="p" rel="prev">Running multiple commands in sequence</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1876 </div>
1877 <span id="Status-messages-and-their-meanings"></span><h2 class="chapter">10 Status messages and their meanings</h2>
1878 <p>Some commands send status messages to inform the client about certain
1879 operations or as a progress indicator.  Status messages begin with a
1880 <code>KEYWORD</code> followed by a status description for status messages that
1881 require it. What status messages are sent, when, and how often may depend on
1882 configuration settings (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>).
1883 </p>
1884 <table>
1885 <thead><tr><th width="20%">Message</th><th width="25%">Parameters</th><th width="55%">Description</th></tr></thead>
1886 <tr><td width="20%">CACHE
1887 <span id="index-CACHE"></span></td><td width="25%"><code>&lt;integer&gt;</code></td><td width="55%">The number of cached documents. Sent to each client after connecting
1888 (see <a href="#GETINFO">Obtaining server and client information.</a>) and after every cache modification.</td></tr>
1889 <tr><td width="20%">CLIENTS
1890 <span id="index-CLIENTS"></span></td><td width="25%"><code>&lt;integer&gt;</code></td><td width="55%">The number of connected clients (see <a href="#GETINFO">Obtaining server and client information.</a>). Sent to each client
1891 when another client either connects or disconnects.</td></tr>
1892 <tr><td width="20%">DECRYPT
1893 <span id="index-DECRYPT"></span></td><td width="25%"></td><td width="55%">Sent to the current client during a decrypt operation. How often this
1894 status message is sent is determined by the <code>keepalive_interval</code>
1895 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) setting.</td></tr>
1896 <tr><td width="20%">ENCRYPT
1897 <span id="index-ENCRYPT"></span></td><td width="25%"></td><td width="55%">Sent to the current client during an encrypt operation. How often this
1898 status message is sent is determined by the <code>keepalive_interval</code>
1899 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) setting.</td></tr>
1900 <tr><td width="20%">GENKEY
1901 <span id="index-GENKEY"></span></td><td width="25%"><code>[&lt;sigkey_fpr&gt; &lt;pubkey_fpr&gt;]</code></td><td width="55%">Sent to the current client during key generation. How often this
1902 status message is sent is determined by the <code>keepalive_interval</code>
1903 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) setting. The <var>sigkey_fpr</var> and <var>pubkey_fpr</var>
1904 parameters are added when key generation has completed.</td></tr>
1905 <tr><td width="20%">INQUIRE_MAXLEN
1906 <span id="index-INQUIRE_005fMAXLEN"></span></td><td width="25%"><code>&lt;bytes&gt;</code></td><td width="55%">Sent to the client from <code>gpg-agent</code> when inquiring data. This
1907 specifies the maximum number of bytes allowed for the client to send and
1908 should not be exceeded.</td></tr>
1909 <tr><td width="20%">KEEPALIVE
1910 <span id="index-KEEPALIVE"></span></td><td width="25%"></td><td width="55%">Sent to each idle client every <var>keepalive_interval</var>
1911 (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) seconds.</td></tr>
1912 <tr><td width="20%">LOCKED
1913 <span id="index-LOCKED"></span></td><td width="25%"></td><td width="55%">Sent to the current client when another client is holding the lock for
1914 the mutex associated with a file. How often this status message is sent is
1915 determined by the <code>keepalive_interval</code> (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>) setting.</td></tr>
1916 <tr><td width="20%">NEWFILE
1917 <span id="index-NEWFILE"></span></td><td width="25%"></td><td width="55%">Sent to the current client when the opened (see <a href="#OPEN">Opening a data file.</a>) file does not
1918 exist on the file-system.</td></tr>
1919 <tr><td width="20%">MODIFIED
1920 <span id="index-MODIFIED"></span></td><td width="25%"><code>&lt;client_id&gt;</code></td><td width="55%">Sent to each client with the same opened data file as <var>client_id</var> to
1921 inform them of modifications that were written to disk using the
1922 <code>SAVE</code> command.</td></tr>
1923 <tr><td width="20%">XFER
1924 <span id="index-XFER"></span></td><td width="25%"><code>&lt;sent&gt; &lt;total&gt;</code></td><td width="55%">Sent to the current client when transferring data. It has two space
1925 delimited arguments. The first being the current amount of bytes transferred
1926 and the other being the total bytes to be transferred. Note that since version
1927 <code>3.1.1</code> of <code>pwmd</code> this status message is sent only once and
1928 before the transfer begins with the <var>total</var> argument set to the size of the
1929 data and the <var>sent</var> argument set to <code>0</code> leaving it to the client to
1930 determine the progress of the transfer as the data is received.</td></tr>
1931 <tr><td width="20%">STATE
1932 <span id="index-STATE"></span></td><td width="25%"><code>&lt;client_id&gt; &lt;state&gt;</code></td><td width="55%">Sent to each client to indicate that <var>client_id</var> has changed to
1933 <var>state</var> (see <a href="#GETINFO">Obtaining server and client information.</a> for client states). For a client to receive
1934 another clients state the option <var>CLIENT-STATE</var> must be set.
1935 See <a href="#OPTION">Setting various client parameters.</a> command.</td></tr>
1936 <tr><td width="20%">EXPIRE
1937 <span id="index-EXPIRE"></span></td><td width="25%"><code>&lt;epoch_seconds&gt; &lt;epoch_future&gt;|0</code></td><td width="55%">Sent to the current client when <code>GET</code> (see <a href="#GET">Getting the content of an element.</a>) encounters an
1938 <code>_expire</code> (see <a href="#Other-Attributes">Other special attributes</a>) attribute that is in the past or when
1939 <code>STORE</code> (see <a href="#STORE">Modifying the content of an element.</a>) updates the <code>_expire</code> attribute from the
1940 <code>_age</code> attribute value. The second field will be <code>0</code> when <code>GET</code>
1941 sends this status message.  Otherwise the second field is the time the next
1942 expiry will be.</td></tr>
1943 <tr><td width="20%">PASSPHRASE_HINT
1944 <span id="index-PASSPHRASE_005fHINT"></span></td><td width="25%">&lt;keyid&gt; &lt;userid&gt;</td><td width="55%">Forwarded from <code>GpgME</code>. Contains information that is useful in a
1945 <code>pinentry</code>. Only sent when pinentry is disabled (see <a href="#OPTION">Setting various client parameters.</a>).</td></tr>
1946 <tr><td width="20%">PASSPHRASE_INFO
1947 <span id="index-PASSPHRASE_005fINFO"></span></td><td width="25%">&lt;flags&gt; ...</td><td width="55%">Forwarded from <code>GpgME</code>. Contains information that is useful in a
1948 <code>pinentry</code>. Only sent when pinentry is disabled (see <a href="#OPTION">Setting various client parameters.</a>).</td></tr>
1949 <tr><td width="20%">REHANDSHAKE
1950 <span id="index-REHANDSHAKE"></span></td><td width="25%"></td><td width="55%">Sent to each <acronym>TLS</acronym> client just before performing a cipher renegotiation
1951 after a SIGHUP signal was received.</td></tr>
1952 <tr><td width="20%">BULK
1953 <span id="index-BULK"></span></td><td width="25%"><code>BEGIN|END &lt;command id&gt;</code></td><td width="55%">Sent to the current client before and after the <code>BULK</code> command
1954 (see <a href="#BULK">Run a series of commands in sequence.</a>) runs each command. The <var>&lt;command id&gt;</var> is the same that was
1955 associated with the command in the s-expression syntax.</td></tr>
1956 </table>
1957
1958 <hr>
1959 </div>
1960 <div class="chapter" id="Target-Attribute">
1961 <div class="header">
1962 <p>
1963 Next: <a href="#Other-Attributes" accesskey="n" rel="next">Other special attributes</a>, Previous: <a href="#Status-Messages" accesskey="p" rel="prev">Status messages and their meanings</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1964 </div>
1965 <span id="The-target-attribute"></span><h2 class="chapter">11 The <code>target</code> attribute</h2>
1966 <span id="index-target-attribute"></span>
1967 <p>A <em>case sensitive</em> attribute named <code>_target</code> is treated specially
1968 when found in each element of an element path. This attribute, like other
1969 element attributes, is created or modified with the <code>ATTR</code> command
1970 (see <a href="#ATTR">Modifying element attributes.</a>). The value of this attribute is an existing element path
1971 somewhere in the document.  If you are familiar with <acronym>XML</acronym> entities or
1972 maybe the HTML <code>id</code> or <code>_target</code> attributes or a symbolic link
1973 in a file-system, you may find this attribute behaves similar to any of those.
1974 </p>
1975 <p>To create a <code>_target</code> attribute use the following syntax:
1976 </p>
1977 <div class="example">
1978 <pre class="example">ATTR SET _target element[<code>TAB</code>child[..]] element[<code>TAB</code>child[..]]
1979 </pre></div>
1980
1981 <p>Note the single space between the two element paths. The first element path is
1982 where the <code>_target</code> attribute will be created. If the element path does
1983 not exist then it will be created.  This is the only time the <code>ATTR</code>
1984 (see <a href="#ATTR">Modifying element attributes.</a>) command will create elements. The attribute is created in the
1985 final element of the element path.
1986 </p>
1987 <p>The second element path is the destination of where you want the first element
1988 path to resolve to. When an element path is passed as an argument to a
1989 protocol command <code>pwmd</code> looks for a <code>_target</code> attribute when
1990 resolving each element and, if found, &quot;jumps&quot; to the attribute value and
1991 continues resolving any remaining elements a commands element path.
1992 </p>
1993 <p>When an element of a element path is removed that a <code>_target</code> attribute
1994 resolves to then an error will occur when trying to access that element. You
1995 may need to either update the <code>_target</code> attribute value with a new element
1996 path or remove the attribute entirely.
1997 </p>
1998 <p>Clients should be careful of creating <code>_target</code> loops, or targets that
1999 resolve to themselves. See the <var>recursion_depth</var> (see <a href="#Configuration"><code>pwmd</code> configuration file options</a>)
2000 configuration parameter for details.
2001 </p>
2002 <p>The <code>REALPATH</code> command (see <a href="#REALPATH">Resolving an element.</a>) can be used to show the element
2003 path after resolving all <code>_target</code> attributes.
2004 </p>
2005 <p><em>Note that when setting this attribute any children of the element will
2006 be removed.</em>
2007 </p>
2008
2009 <hr>
2010 </div>
2011 <div class="chapter" id="Other-Attributes">
2012 <div class="header">
2013 <p>
2014 Next: <a href="#Key-Expiration" accesskey="n" rel="next">Key Expiration</a>, Previous: <a href="#Target-Attribute" accesskey="p" rel="prev">The <code>target</code> attribute</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2015 </div>
2016 <span id="Other-special-attributes"></span><h2 class="chapter">12 Other special attributes</h2>
2017 <span id="index-special-attributes"></span>
2018 <p>In addition to the <code>_target</code> attribute (see <a href="#Target-Attribute">The <code>target</code> attribute</a>), there
2019 are a few other attributes that are specially handled by <code>pwmd</code>. The
2020 first is the <code>_ctime</code> attribute which is set to the current time when an
2021 element is created. Next is the <code>_mtime</code> attribute which is created when
2022 an element is created and also updated when an element is modified. Neither of
2023 these attributes may be modified by the client. The <code>_acl</code> attribute
2024 controls access to the element, beit modifying or accessing element content,
2025 or descending into child elements.  See <a href="#Access-Control">Access Control</a> for details. The
2026 <code>_name</code> attribute contains the name of an element.
2027 </p>
2028 <p>The above mentioned attributes are considered reserved attribute names.
2029 Reserved attributes are treated specially when a <code>_target</code> attribute is
2030 found for the current element. The <code>ATTR LIST</code> command will show these
2031 attribute values for the current element and not the attribute values for the
2032 resolved <code>_target</code> element. All other non-reserved attributes for the
2033 resolved <code>_target</code> are appended to the <code>ATTR LIST</code> command output.
2034 Other <code>ATTR</code> commands (see <a href="#ATTR">Modifying element attributes.</a>) behave as usual. You can, for
2035 example, <code>ATTR DELETE</code> a non-reserved attribute for an element that
2036 contains a <code>_target</code> attribute. The resolved target elements&rsquo; attribute
2037 will be removed rather than the element containing the <code>_target</code>
2038 attribute.
2039 </p>
2040 <p>Another specially handled attribute is the <code>_expire</code> attribute. This
2041 attribute value, like the <code>_ctime</code> and <code>_mtime</code> attributes, is a
2042 timestamp. But this timestamp is usually in the future and for use with the
2043 <code>GET</code> (see <a href="#GET">Getting the content of an element.</a>) and <code>STORE</code> (see <a href="#STORE">Modifying the content of an element.</a>) commands. When the
2044 <code>GET</code> command is issued, it checks for an <code>_expire</code> attribute an
2045 compares its&rsquo; value with the current time. If the <code>_expire</code> timestamp is
2046 in the past then a status message is sent (see <a href="#Status-Messages">Status messages and their meanings</a>) to inform
2047 the client that the element content should be updated.  When the content for
2048 an element containing an <code>_expire</code> attribute is set when using the
2049 <code>STORE</code> command, the value of the <code>_age</code> attribute is added to the
2050 current time and the <code>_expire</code> attribute value is updated.  When no
2051 <code>_age</code> attribute is found, no modification is done of the <code>_expire</code>
2052 attribute.
2053 </p>
2054
2055 <hr>
2056 </div>
2057 <div class="chapter" id="Key-Expiration">
2058 <div class="header">
2059 <p>
2060 Next: <a href="#Signals" accesskey="n" rel="next">Recognized signals</a>, Previous: <a href="#Other-Attributes" accesskey="p" rel="prev">Other special attributes</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2061 </div>
2062 <span id="Key-Expiration-1"></span><h2 class="chapter">13 Key Expiration</h2>
2063 <span id="index-key-expiration"></span>
2064 <p>When a key used for signing a data file has expired there is no indication
2065 until the next <code>SAVE</code> command is sent. The command will fail since one
2066 cannot sign the data file with an expired key. The client will need to either
2067 use a different key for signing by either specifying an existing non-expired
2068 key, generate a new key, or change the expire time of the existing key with
2069 <code>gpg</code>.
2070 </p>
2071 <p>To change the expiration of the currently used signing key with <code>gpg</code>,
2072 use the <code>KEYINFO</code> command (see <a href="#KEYINFO">Showing keys used for the current data file.</a>) to obtain the fingerprint of
2073 the signing key of the current data file, then change the expire time with
2074 <code>gpg</code>:
2075 </p>
2076 <div class="example">
2077 <pre class="example">gpg --homedir ~/.pwmd/.gnupg --edit-key &lt;fingerprint&gt;
2078 </pre></div>
2079
2080 <p>Then use the <code>expire</code> command to set the new key expire date. When
2081 finished, use the <code>save</code> command to save your changes.
2082 </p>
2083
2084 <hr>
2085 </div>
2086 <div class="chapter" id="Signals">
2087 <div class="header">
2088 <p>
2089 Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Key-Expiration" accesskey="p" rel="prev">Key Expiration</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2090 </div>
2091 <span id="Recognized-signals"></span><h2 class="chapter">14 Recognized signals</h2>
2092
2093 <p>Sending the <em>SIGHUP</em> signal to a <code>pwmd</code> process will reload the
2094 configuration file and sending <em>SIGUSR1</em> will clear the entire file
2095 cache.
2096 </p>
2097
2098
2099 <hr>
2100 </div>
2101 <div class="unnumbered" id="Index">
2102 <div class="header">
2103 <p>
2104 Previous: <a href="#Signals" accesskey="p" rel="prev">Recognized signals</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2105 </div>
2106 <span id="Index-1"></span><h2 class="unnumbered">Index</h2>
2107 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a>
2108  &nbsp;
2109 <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a>
2110  &nbsp;
2111 <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
2112  &nbsp;
2113 <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a>
2114  &nbsp;
2115 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
2116  &nbsp;
2117 <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a>
2118  &nbsp;
2119 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
2120  &nbsp;
2121 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
2122  &nbsp;
2123 <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a>
2124  &nbsp;
2125 <a class="summary-letter" href="#Index_cp_letter-L"><b>L</b></a>
2126  &nbsp;
2127 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
2128  &nbsp;
2129 <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a>
2130  &nbsp;
2131 <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a>
2132  &nbsp;
2133 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
2134  &nbsp;
2135 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
2136  &nbsp;
2137 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
2138  &nbsp;
2139 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
2140  &nbsp;
2141 <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a>
2142  &nbsp;
2143 <a class="summary-letter" href="#Index_cp_letter-X"><b>X</b></a>
2144  &nbsp;
2145 </td></tr></table>
2146 <table class="index-cp" border="0">
2147 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
2148 <tr><td colspan="4"> <hr></td></tr>
2149 <tr><th id="Index_cp_letter-A">A</th><td></td><td></td></tr>
2150 <tr><td></td><td valign="top"><a href="#index-Arguments">Arguments</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking">Invoking</a></td></tr>
2151 <tr><td></td><td valign="top"><a href="#index-ATTR-command">ATTR command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#ATTR">ATTR</a></td></tr>
2152 <tr><td colspan="4"> <hr></td></tr>
2153 <tr><th id="Index_cp_letter-B">B</th><td></td><td></td></tr>
2154 <tr><td></td><td valign="top"><a href="#index-BULK">BULK</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2155 <tr><td></td><td valign="top"><a href="#index-BULK-command">BULK command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#BULK">BULK</a></td></tr>
2156 <tr><td colspan="4"> <hr></td></tr>
2157 <tr><th id="Index_cp_letter-C">C</th><td></td><td></td></tr>
2158 <tr><td></td><td valign="top"><a href="#index-CACHE">CACHE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2159 <tr><td></td><td valign="top"><a href="#index-CACHETIMEOUT-command">CACHETIMEOUT command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CACHETIMEOUT">CACHETIMEOUT</a></td></tr>
2160 <tr><td></td><td valign="top"><a href="#index-CLEARCACHE-command">CLEARCACHE command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CLEARCACHE">CLEARCACHE</a></td></tr>
2161 <tr><td></td><td valign="top"><a href="#index-CLIENTS">CLIENTS</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2162 <tr><td></td><td valign="top"><a href="#index-COPY-command">COPY command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#COPY">COPY</a></td></tr>
2163 <tr><td colspan="4"> <hr></td></tr>
2164 <tr><th id="Index_cp_letter-D">D</th><td></td><td></td></tr>
2165 <tr><td></td><td valign="top"><a href="#index-Data-file-configuration-options">Data file configuration options</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Configuration">Configuration</a></td></tr>
2166 <tr><td></td><td valign="top"><a href="#index-DECRYPT">DECRYPT</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2167 <tr><td></td><td valign="top"><a href="#index-DELETE-command">DELETE command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#DELETE">DELETE</a></td></tr>
2168 <tr><td></td><td valign="top"><a href="#index-DELETEKEY-command">DELETEKEY command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#DELETEKEY">DELETEKEY</a></td></tr>
2169 <tr><td></td><td valign="top"><a href="#index-DUMP-command">DUMP command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#DUMP">DUMP</a></td></tr>
2170 <tr><td colspan="4"> <hr></td></tr>
2171 <tr><th id="Index_cp_letter-E">E</th><td></td><td></td></tr>
2172 <tr><td></td><td valign="top"><a href="#index-ENCRYPT">ENCRYPT</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2173 <tr><td></td><td valign="top"><a href="#index-EXPIRE">EXPIRE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2174 <tr><td colspan="4"> <hr></td></tr>
2175 <tr><th id="Index_cp_letter-G">G</th><td></td><td></td></tr>
2176 <tr><td></td><td valign="top"><a href="#index-GENKEY">GENKEY</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2177 <tr><td></td><td valign="top"><a href="#index-GENKEY-command">GENKEY command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GENKEY">GENKEY</a></td></tr>
2178 <tr><td></td><td valign="top"><a href="#index-GET-command">GET command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GET">GET</a></td></tr>
2179 <tr><td></td><td valign="top"><a href="#index-GETCONFIG-command">GETCONFIG command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GETCONFIG">GETCONFIG</a></td></tr>
2180 <tr><td></td><td valign="top"><a href="#index-GETINFO-command">GETINFO command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GETINFO">GETINFO</a></td></tr>
2181 <tr><td></td><td valign="top"><a href="#index-Getting-help">Getting help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking">Invoking</a></td></tr>
2182 <tr><td></td><td valign="top"><a href="#index-Global-configuration-options">Global configuration options</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Configuration">Configuration</a></td></tr>
2183 <tr><td colspan="4"> <hr></td></tr>
2184 <tr><th id="Index_cp_letter-H">H</th><td></td><td></td></tr>
2185 <tr><td></td><td valign="top"><a href="#index-HELP-command">HELP command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#HELP">HELP</a></td></tr>
2186 <tr><td colspan="4"> <hr></td></tr>
2187 <tr><th id="Index_cp_letter-I">I</th><td></td><td></td></tr>
2188 <tr><td></td><td valign="top"><a href="#index-IMPORT-command">IMPORT command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#IMPORT">IMPORT</a></td></tr>
2189 <tr><td></td><td valign="top"><a href="#index-INQUIRE_005fMAXLEN">INQUIRE_MAXLEN</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2190 <tr><td></td><td valign="top"><a href="#index-ISCACHED-command">ISCACHED command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#ISCACHED">ISCACHED</a></td></tr>
2191 <tr><td colspan="4"> <hr></td></tr>
2192 <tr><th id="Index_cp_letter-K">K</th><td></td><td></td></tr>
2193 <tr><td></td><td valign="top"><a href="#index-KEEPALIVE">KEEPALIVE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2194 <tr><td></td><td valign="top"><a href="#index-key-expiration">key expiration</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-Expiration">Key Expiration</a></td></tr>
2195 <tr><td></td><td valign="top"><a href="#index-KEYINFO-command">KEYINFO command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#KEYINFO">KEYINFO</a></td></tr>
2196 <tr><td></td><td valign="top"><a href="#index-KILL-command">KILL command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#KILL">KILL</a></td></tr>
2197 <tr><td colspan="4"> <hr></td></tr>
2198 <tr><th id="Index_cp_letter-L">L</th><td></td><td></td></tr>
2199 <tr><td></td><td valign="top"><a href="#index-LIST-command">LIST command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#LIST">LIST</a></td></tr>
2200 <tr><td></td><td valign="top"><a href="#index-LISTKEYS-command">LISTKEYS command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#LISTKEYS">LISTKEYS</a></td></tr>
2201 <tr><td></td><td valign="top"><a href="#index-LOCK-command">LOCK command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#LOCK">LOCK</a></td></tr>
2202 <tr><td></td><td valign="top"><a href="#index-LOCKED">LOCKED</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2203 <tr><td></td><td valign="top"><a href="#index-LS-command">LS command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#LS">LS</a></td></tr>
2204 <tr><td colspan="4"> <hr></td></tr>
2205 <tr><th id="Index_cp_letter-M">M</th><td></td><td></td></tr>
2206 <tr><td></td><td valign="top"><a href="#index-MODIFIED">MODIFIED</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2207 <tr><td></td><td valign="top"><a href="#index-MOVE-command">MOVE command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#MOVE">MOVE</a></td></tr>
2208 <tr><td colspan="4"> <hr></td></tr>
2209 <tr><th id="Index_cp_letter-N">N</th><td></td><td></td></tr>
2210 <tr><td></td><td valign="top"><a href="#index-NEWFILE">NEWFILE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2211 <tr><td></td><td valign="top"><a href="#index-NOP-command">NOP command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#NOP">NOP</a></td></tr>
2212 <tr><td colspan="4"> <hr></td></tr>
2213 <tr><th id="Index_cp_letter-O">O</th><td></td><td></td></tr>
2214 <tr><td></td><td valign="top"><a href="#index-OPEN-command">OPEN command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OPEN">OPEN</a></td></tr>
2215 <tr><td></td><td valign="top"><a href="#index-OPTION-command">OPTION command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OPTION">OPTION</a></td></tr>
2216 <tr><td></td><td valign="top"><a href="#index-Options">Options</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking">Invoking</a></td></tr>
2217 <tr><td colspan="4"> <hr></td></tr>
2218 <tr><th id="Index_cp_letter-P">P</th><td></td><td></td></tr>
2219 <tr><td></td><td valign="top"><a href="#index-PASSPHRASE_005fHINT">PASSPHRASE_HINT</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2220 <tr><td></td><td valign="top"><a href="#index-PASSPHRASE_005fINFO">PASSPHRASE_INFO</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2221 <tr><td></td><td valign="top"><a href="#index-PASSWD-command">PASSWD command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PASSWD">PASSWD</a></td></tr>
2222 <tr><td colspan="4"> <hr></td></tr>
2223 <tr><th id="Index_cp_letter-R">R</th><td></td><td></td></tr>
2224 <tr><td></td><td valign="top"><a href="#index-REALPATH-command">REALPATH command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#REALPATH">REALPATH</a></td></tr>
2225 <tr><td></td><td valign="top"><a href="#index-REHANDSHAKE">REHANDSHAKE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2226 <tr><td></td><td valign="top"><a href="#index-Reloading-the-configuration-file">Reloading the configuration file</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Configuration">Configuration</a></td></tr>
2227 <tr><td></td><td valign="top"><a href="#index-RENAME-command">RENAME command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#RENAME">RENAME</a></td></tr>
2228 <tr><td></td><td valign="top"><a href="#index-RESET-command">RESET command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#RESET">RESET</a></td></tr>
2229 <tr><td></td><td valign="top"><a href="#index-Running-pwmd">Running <code>pwmd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking">Invoking</a></td></tr>
2230 <tr><td colspan="4"> <hr></td></tr>
2231 <tr><th id="Index_cp_letter-S">S</th><td></td><td></td></tr>
2232 <tr><td></td><td valign="top"><a href="#index-SAVE-command">SAVE command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#SAVE">SAVE</a></td></tr>
2233 <tr><td></td><td valign="top"><a href="#index-special-attributes">special attributes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Other-Attributes">Other Attributes</a></td></tr>
2234 <tr><td></td><td valign="top"><a href="#index-STATE">STATE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2235 <tr><td></td><td valign="top"><a href="#index-STORE-command">STORE command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#STORE">STORE</a></td></tr>
2236 <tr><td colspan="4"> <hr></td></tr>
2237 <tr><th id="Index_cp_letter-T">T</th><td></td><td></td></tr>
2238 <tr><td></td><td valign="top"><a href="#index-target-attribute">target attribute</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Target-Attribute">Target Attribute</a></td></tr>
2239 <tr><td colspan="4"> <hr></td></tr>
2240 <tr><th id="Index_cp_letter-U">U</th><td></td><td></td></tr>
2241 <tr><td></td><td valign="top"><a href="#index-UNLOCK-command">UNLOCK command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#UNLOCK">UNLOCK</a></td></tr>
2242 <tr><td colspan="4"> <hr></td></tr>
2243 <tr><th id="Index_cp_letter-X">X</th><td></td><td></td></tr>
2244 <tr><td></td><td valign="top"><a href="#index-XFER">XFER</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status-Messages">Status Messages</a></td></tr>
2245 <tr><td></td><td valign="top"><a href="#index-XPATH-command">XPATH command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#XPATH">XPATH</a></td></tr>
2246 <tr><td></td><td valign="top"><a href="#index-XPATHATTR-command">XPATHATTR command</a>:</td><td>&nbsp;</td><td valign="top"><a href="#XPATHATTR">XPATHATTR</a></td></tr>
2247 <tr><td colspan="4"> <hr></td></tr>
2248 </table>
2249 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a>
2250  &nbsp;
2251 <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a>
2252  &nbsp;
2253 <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
2254  &nbsp;
2255 <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a>
2256  &nbsp;
2257 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
2258  &nbsp;
2259 <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a>
2260  &nbsp;
2261 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
2262  &nbsp;
2263 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
2264  &nbsp;
2265 <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a>
2266  &nbsp;
2267 <a class="summary-letter" href="#Index_cp_letter-L"><b>L</b></a>
2268  &nbsp;
2269 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
2270  &nbsp;
2271 <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a>
2272  &nbsp;
2273 <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a>
2274  &nbsp;
2275 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
2276  &nbsp;
2277 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
2278  &nbsp;
2279 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
2280  &nbsp;
2281 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
2282  &nbsp;
2283 <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a>
2284  &nbsp;
2285 <a class="summary-letter" href="#Index_cp_letter-X"><b>X</b></a>
2286  &nbsp;
2287 </td></tr></table>
2288
2289 </div>
2290 </div>
2291
2292
2293
2294 </body>
2295 </html>