Fix commit 87429946 to not overwrite errno.

[pwmd.git] / doc / pwmd.texi

>\input texinfo @c -*-texinfo-*- 
@c %**start of header 
@setfilename pwmd.info 
@settitle PWMD Manual

@macro manpage {a}
@end macro
@macro mansect {a}
@end macro
@macro manpause
@end macro
@macro mancont
@end macro
@c %**end of header

@dircategory Miscellaneous
@direntry
* pwmd: (pwmd).         Password Manager Daemon
@end direntry

@titlepage 
@title PWMD Manual
@subtitle Commands and syntax
@author by Ben Kibbey
@end titlepage

@c    Node, Next, Previous, Up 
@node Top ,     ,         , (dir) 
 
@ifinfo 
This manual documents @command{pwmd} version 3.0 protocol commands and
their syntax.
@end ifinfo 
 
@menu 
* Introduction::          Overview of pwmd.
* Access Control::        ACL of a single XML element.
* Invoking::              Command line options.
* Configuration::         Configuration file options.
* Commands::              Protocol commands.
* Status Messages::       Status lines and their meaning.
* Target Attribute::      A kind of symbolic link.
* Signals::               Signals known to pwmd.
* Concept Index::         Index of concepts.
@end menu

@c    Node,     Next,    Previous, Up 
@node Introduction, Access Control,        , Top 
@chapter Overview of @command{pwmd} 

@manpage pwmd.1
@ifset manverb
.B pwmd
\- a univeral data server
@end ifset

@mansect synopsis
@ifset manverb
.B pwmd
[options] [file1] [...]
@end ifset

@mansect description
@command{pwmd} or @dfn{Password Manager Daemon} is a server that
applications connect to and send commands to store and retrieve data
that is saved in an encrypted @abbr{XML} document.

The server uses the Assuan protocol (@inforef{Implementation,,assuan}) which
is the same used by @command{gpg-agent}, @command{pinentry} and
@command{scdaemon}. It also uses @cite{libgpg-error} for error reporting with
the error source set as @var{GPG_ERR_SOURCE_USER_1}.
@ifset isman
.P
It is recommended to read the texinfo documentation of @command{pwmd}
since it contains protocol commands and syntax and other details not
found here.
@end ifset
@manpause

The @abbr{XML} document uses the following @abbr{DTD}:

@example
    <?xml version="1.0"?>
    <!DOCTYPE pwmd [
    <!ELEMENT pwmd (element*)>
    <!ATTLIST element _name CDATA #REQUIRED>
    ]>
@end example

The @code{pwmd} element is the document root node while all other elements
of the document have the name @code{element} with an attribute @code{_name}
whose value uniquely identifies the element at the current element tree depth.
It is done this way to avoid @abbr{XML} parsing errors for commonly used
characters.  A @abbr{URL} for example would be an invalid @abbr{XML} element
since the @abbr{URI} contains a @samp{:} which is also the @abbr{XML}
namespace separator.

As mentioned, an element name must be unique for the current element tree
depth. You cannot have two elements containing the same @code{_name} attribute
value. @command{pwmd} will stop searching for an element of an @emph{element
path} at the first match then continue searching for the next element of the
element path beginning at the child node of the matched element.

An @emph{element path} is a @key{TAB} delimited character string where each
@key{TAB} separates each element in the path.  For example, the element path
@code{a@key{TAB}b@key{TAB}c} has the following @abbr{XML} document structure:

@example
        <pwmd>
            <element _name="a">
                <element _name="b">
                    <element _name="c">
                        [... element value or content ...]
                    </element>
                </element>
            </element>
        </pwmd>
@end example

The only restriction of an element name is that it contain no whitespace
characters. It also cannot begin with a @samp{!} since this character is
reserved for the @code{target} attribute. @xref{Target Attribute}.

@c    Node,     Next,    Previous, Up 
@node Access Control, Invoking, Introduction, Top 
@chapter Access Control

Like a filesystem has an @abbr{ACL} to grant or limit access to directories or
files for a specific user or group, @command{pwmd} can limit a local user,
group or a TLS connection to a specific element path. This is done by storing
an ACL in the element attribute @var{_acl}. Its syntax is similar to the
@var{allowed} configuration parameter (@pxref{Configuration}) with the
exception that a TLS fingerprint hash is prefixed with a @key{#}.

Access is denied for all users that are not in the @abbr{ACL} of an element
with the exception of the invoking user (see the @var{invoking_user} and
@var{invoking_tls} configuration parameters (@pxref{Configuration})). The
connected client must be in the @abbr{ACL} for each element in an element path
otherwise an error is returned.  As an example:

@example
<element _name="test" _acl="username,-@@wheel,root,#ABCDEF">
        <element _name="child"/>
</element>
@end example

The user @code{username} would be allowed access to the @code{test} element
but not if it is a member of the @code{wheel} group although the @code{root}
user, who may be a member of the @code{wheel} group, is allowed. The SHA-256
TLS fingerprint hash @code{#ABCDEF} is also allowed.  No users other than the
@var{invoking_user} are allowed access to the @code{child} element.

The first user listed in the @abbr{ACL} is considered the owner of the
element. This determines which clients may modify an @var{_acl} attribute and
store content for an element. The @var{invoking_user} may always modify an 
@abbr{ACL}.

@c    Node,     Next,    Previous, Up 
@node Invoking, Configuration, Access Control, Top 
@chapter Invoking @command{pwmd} 

@mancont
@mansect options
When @command{pwmd} is started with the @option{--use-agent} command
line option then @command{pwmd} will use @command{gpg-agent} for key
generation, decryption, signing and caching of passphrases as the
default rather than symmetrically encrypted data files.
@command{gpg-agent} must be running prior to @command{pwmd} startup when
this option is enabled.

It is recommended to pass the @option{--allow-preset-passphrase}
command line option to @command{gpg-agent}. Doing so allows @command{pwmd}
cache pushing on startup. It is also recommended to pass the
@option{--allow-loopback-pinentry} to @command{gpg-agent}. This option allows
a passphrase to be inquired from @command{pwmd} when a @command{pinentry} is
unavailable to the client.

@cindex Running @command{pwmd} 
@command{pwmd} is executed as follows: 
 
@example 
pwmd @var{options} [ file1 ] [ @dots{} ]
@end example

Non-option arguments are data files to cache on startup. When the data file
requires a passphrase for decryption a @command{pinentry} will prompt either
on the current @abbr{TTY} or from an X11 window when the @env{DISPLAY}
environment variable is set.

@cindex Options 
@cindex Arguments 
The following command line options are supported:

@cindex Getting help 
@table @samp 
@item --homedir directory
The root directory where pwmd will store its data and temporary files.  The
default is @file{~/.pwmd}.

@item --rcfile, -f rcfile
Specify an alternate configuration file. The default is
@file{~/.pwmd/config}.

@item --kill
Terminate an existing instance of pwmd. The process to terminate is determined
from the @option{--homedir} and @option{--rcfile} options.

@item --use-agent [integer]
Enable the use of @command{gpg-agent} and add support for data files
encrypted with a keypair. Files previously handled by
@command{gpg-agent} when this option is not specified will no longer be
able to be opened and new data files are symmetrically or conventionally
encrypted and without a public and private key. If specified, both data file
types are supported. The optional argument overrides any configuration file
value specified with the @option{--rcfile} option.

@item --import, -I filename
Imports an @abbr{XML} file. The @abbr{XML} file should be in conformance to
the @command{pwmd} @abbr{DTD} (@pxref{Introduction}). You
will be prompted for a passphrase to encrypt with.  The output is written to
the filename specified with @option{--outfile}. To make use of the imported
data, place the output file in @file{~/.pwmd/data}.

@item --keyparam S-expression
The key parameters to use when generating a new key pair while importing an
@abbr{XML} file or when converting a @emph{version 2} data file. The argument
must be a valid S-expression (@inforef{S-expressions,, gcrypt}).

@item --keygrip hexstring
Specifies the hexadecimal encoded public key-grip to use for encryption when
importing or converting. When not specified a new key-pair will be created.

@item --sign-keygrip hexstring
Specifies the hexadecimal encoded public key-grip to use for signing of the
data file when importing or converting. When not specified the generated
public key or the key specified with the @option{--keygrip} option will be
used.

@item --passphrase-file, -k filename"
Obtain the passphrase from the specified filename.

@item --s2k-count iterations
The number of times to hash the passphrase when importing or converting.  The
default is the gpg-agent calibrated value of the machine. When less than
@samp{65536} the default will be used.

@item --cipher-iterations iterations
The number of symmetric encryption iterations. The value is actually N+1. The
default is 0+1.

@item --cipher algo
When importing, the cipher to use for data encryption.  See the @var{cipher}
configuration parameter (@pxref{Configuration}) for available ciphers. The
default is @samp{aes256}.

@item --convert, -C filename
Converts a @command{pwmd} @emph{version 2} data file to a @emph{version 3}
data file. If encrypted, you will be prompted for a passphrase to use for
decryption unless @option{--passphrase-file} was specified. The converted data
file will be saved to the filename specified with @option{--outfile}. All
@option{--import} related options may also be used when converting.

@item --disable-dump, -D
Disable the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and @code{DUMP}
protocol commands (@pxref{Commands}). This overrides any
@var{disable_list_and_dump} configuration parameter (@pxref{Configuration}).

@item --no-fork, -n
Run as a foreground process and do not fork into the background.

@item --ignore, --force
Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
if an error occurred do to an invalid passphrase or other error.

@item --debug-level keyword,keyword,...
Output libassuan @inforef{Top,,assuan} protocol IO with the comma
separated list of output keywords.  Valid keywords are: @code{init},
@code{ctx}, @code{engine}, @code{data}, @code{sysio} and @code{control}.

@item --version
Show the version, copyright and compile time features and exit.

@item --help 
Print a summary of options.
@end table
@manpause

@c    Node,     Next,    Previous, Up 
@node Configuration, TLS, Invoking, Top 
@chapter @command{pwmd} configuration file options
@mancont
@mansect configuration file
If no configuration file is specified with the @command{pwmd} @option{-f}
command line option, @command{pwmd} will read @file{~/.pwmd/config} if it
exists, and if not, will use defaults.  Blank lines and lines beginning with
@samp{#} are ignored. Some parameters may have data file specific settings by
placing them in a file section. A file section is declared by surrounding the
filename with braces (i.e., @samp{[filename]}).  Global options may be
specified in a @samp{[global]} section and are the default options for new or
unspecified files.

A tilde @key{~} will be expanded to the home directory of the invoking user
when contained in a parameter whose value is a filename.

@cindex Reloading the configuration file
The configuration file can be reloaded by sending the @emph{SIGHUP} signal to
a @command{pwmd} process.

@cindex Global configuration options
The following options are only for use in the @samp{global} section:

@table @samp 
@item socket_path = /path/to/socket
Listen on the specified socket. The default is @file{~/.pwmd/socket}.

@item socket_perms = octal_mode
Permissions to set after creating the socket. This will override any
@cite{umask(2)} setting.

@item invoking_user = username
This parameter is not to be confused with setuid or setguid upon startup. It
is the local username that may use the @command{XPATH}, @command{XPATHATTR}
and @command{DUMP} commands (except when disabled with the
@code{disable_list_and_dump} option) and who may modify elements that have no
@code{_acl} attribute or is not listed in an @code{_acl}. It is similar to
the system administrator root account but for a data file
(@pxref{Access Control}). The default is the user the executes @command{pwmd}.

@item invoking_tls = SHA-256
Like @code{invoking_user} but is a hash of an @abbr{TLS} certificate
fingerprint for a remote client. The hash should be prefixed with a @key{#}
character.

@item allowed = [-!]user,[-!]@@group,[+,][-!]#SHA-256,...
A comma separated list of local user names, group names or @abbr{TLS}
fingerprint @abbr{SHA}-256 hashes (in the case of a remote client) who are
allowed to connect.  Groups should be prefixed with a @samp{@@}. When not
specified only the invoking user may connect. A username, group name or hash
may also be prefixed with a @key{-} or @key{!} to prevent access to a specific
user or group in the list. The order of the list is important since a user may
be of multiple groups.

This parameter may also be specified in a filename section to allow or deny a
client to @code{OPEN} (@pxref{OPEN}) a data file. It also affects the cache
commands @code{CLEARCACHE} (@pxref{CLEARCACHE}) and @code{CACHETIMEOUT}
(@pxref{CACHETIMEOUT}). When not specified in a file section any user that can
connect may also open the filename.

The following example would deny all users in group @code{primary} but
allow @code{username} who may be a member of @code{primary}. It will also
allow any TLS client except for the client with @abbr{TLS} fingerprint hash
@code{#ABCDEF}:

@example
allowed=-@@primary,username,+,!#ABCDEF
@end example

@item allowed_file = filename
A file containing one entry per line. An entry has the same syntax as the
@code{allowed} parameter. When both this parameter and the @code{allowed}
parameter are specified then the @code{allowed_file} entries will be appended
to the @code{allowed} parameter value.

@item disable_mlockall = boolean
When set to @code{false}, @cite{mlockall(2)} will be called on startup.  This
will use more physical memory but may also be more secure since no swapping to
disk will occur. The default is @var{true}.

@item log_path = /path/to/logfile
Logs informational messages to the specified file. The default is
@file{~/.pwmd/log}.

@item enable_logging = boolean
Enable or disable logging to @var{log_path}. The default is @code{false}.

@item log_keepopen = boolean
When set to @code{false}, the log file specified with @var{log_path} will be
closed after writing each line. The default is @code{true}.

@item syslog = boolean
Enable logging to @cite{syslog(8)} with facility @emph{LOG_DAEMON} and priority
@emph{LOG_INFO}. The default is @code{false}.

@item log_level = level
When @code{0}, only connections and errors are logged. When @code{1}, client
commands are also logged. When @code{2}, the command arguments are also logged.
The default is @code{0}.

@item use_agent = boolean
When true, enable @command{gpg-agent} support (@pxref{Invoking}).

@item gpg_agent_socket = /path/to/filename
The location of the @command{gpg-agent} socket. The default is
@code{~/.gnupg/S.gpg-agent}.

@item kill_scd = boolean
Kill @command{scdaemon} after each @code{OPEN} (@pxref{OPEN}) or @code{SAVE}
(@pxref{SAVE}) command.

@item require_save_key = boolean
Require the passphrase needed to open a data file before writing changes
of the documment to disk reguardless of the key cache status.

@item disable_list_and_dump = boolean
When @code{true}, the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and
@code{DUMP} protocol commands (@pxref{Commands}) will be disabled.

@item cache_push = file1,file2
A comma separated list of filenames that will be pushed into the file cache
upon startup. @command{pwmd} will prompt for the passphrase for each file unless
specified with the @var{passphrase} or @var{passphrase_file} parameters in a
matching file section.

@item priority = integer
The priority, or niceness, of the server. The default is inherited from the
parent process.

@item cipher = algorithm
The default cipher to use for data encryption when saving (@pxref{SAVE}) a new
file. The algorithm must be one of: @code{aes128}, @code{aes192},
@code{aes256}, @code{serpent128}, @code{serpent192}, @code{serpent256},
@code{camellia128}, @code{camellia192}, @code{camellia256}, @code{3des},
@code{cast5}, @code{blowfish}, @code{twofish128} or @code{twofish256}. The
default is @code{aes256}.

@item cipher_iterations = integer
The number of times to encrypt the XML data. This differs from the
@var{s2k_count} parameter which specifies the number of times to hash the
passphrase used to encrypt the data. The default is 0 although at least 1
iteration is always done.

@item cipher_progress = integer
Send a progress message to the client after the specified amount of encryption
or decryption iterations have been done. The default is 2000.

@item keyparam = s-expression
The default key parameters to use when generating a new key-pair. The default
is @code{RSA} with @code{2048} bits. Note that only the @abbr{RSA} and
@abbr{ELG} algorithms as the encryption algorithm are supported at the moment.
Both @abbr{RSA} and @abbr{DSA} keys may be used for signing.

@item pinentry_path = /path/to/pinentry
The location of the @command{pinentry} binary. This program is used to
prompt for a passphrase when not using @command{gpg-agent}. The default
is specified at compile time.

@item pinentry_timeout = seconds
The number of seconds to wait for a pinentry before giving up and
returning an error. This timeout value is used for both waiting for
another pinentry to complete and for the pinentry waiting for user input.

@item lock_timeout = integer
The default timeout in tenths of a second before giving up waiting for a file
lock and returning an error. The default is @code{50}.

@item send_state = integer
Whether to send client state changes of the current client to all connected
clients. When @code{0} no client state changes will be sent although a client
state may be obtained with the @code{GETINFO} command (@pxref{GETINFO}). When
@code{1} a status message will be sent to all connected clients.  When
@code{2} the status message will be sent only to the @code{invoking_user}
(@pxref{Configuration}). The default is @code{2}.  Disabling this option can
significantly increase the performance of @command{pwmd} when there are many
connected clients.
@end table

@ifset manverb
.P
@end ifset
@cindex Data file configuration options
The following options are defaults for new files when specified in the
@samp{global} section. When placed in a data file section they are options
specific to that data file only.

@table @samp 
@item backup = boolean
Whether to create a backup of the data file when saving. The backup filename
has the @file{.backup} extension appended to the opened file. The default is
@code{true}. 

@item cache_timeout = seconds
The number of seconds to keep the cache entry for this file. If @code{-1}, the
cache entry is kept forever. If @code{0}, each time an encrypted file is
@code{OPEN}ed (@pxref{OPEN}) a passphrase will be required. The default
is @code{600} or 10 minutes.

@item xfer_progress = bytes
Commands that send data lines to the client will also send the @code{XFER}
status message (@pxref{Status Messages}) after the specified number of bytes
have been sent. The number of bytes is rounded to @var{ASSUAN_LINELENGTH} or
@code{1002} bytes. The default is @code{8196}.

@item passphrase = string
The passphrase to use for this file. If specified in the @samp{global} section
then @samp{global} is treated as a data filename and not a default for other
files. Note that if a client changes the passphrase for this data file then
this value is not modified and will need to be updated.

@item passphrase_file = /path/to/file
Same as the @var{passphrase} parameter above but obtains the passphrase from
the specified filename.

@item recursion_depth = integer
The maximum number of times to resolve a @code{target} attribute for an
element in an element path (@pxref{Target Attribute}). An error is returned
when this value is exceeded.  The default is @code{100} but can be disabled by
setting to @code{0} (@emph{not recommended}).

@item allowed = [-]user,[-]@@group,...
Same parameter value as the @code{allowed} parameter mentioned above in
the @samp{global} section but grants or denies a local user from opening
a specific data file. The default is the same as the @samp{global} section.
@end table

@menu
* TLS::                   Remote connections over TLS.
* Pinentry::              Configuration file and defaults.
@end menu

@node TLS, Pinentry, Configuration, Configuration
@chapter Configuring remote connections over TLS.
@mansect TLS Configuration
Connections can also be made to @command{pwmd} over @abbr{TLS}.
Authentication is done by using X.509 client certificates which are signed
with the same Certificate Authority (@abbr{CA}) as the server certificate.

The @abbr{CA} certificate is expected to be found in
@file{~/.pwmd/ca-cert.pem} while the @command{pwmd} server certificate and key
file should be put in @file{~/.pwmd/server-cert.pem} and
@file{~/.pwmd/server-key.pem}, respectively.

See the documentation of @command{certtool} or @command{openssl} for details
on creating self-signed certificates.

The following TLS configuration options are available:

@table @samp 
@item enable_tcp = boolean
Whether to enable TCP/TLS server support. If enabled, both TCP and the local
unix domain socket will listen for connections. The default is
@code{false}.

@item tcp_port = integer
The TCP port to listen on when @var{enable_tcp} is @code{true}. The default is
@code{6466}.

@item tcp_bind = string
The internet protocol to listen with. Must be one of @code{ipv4}, @code{ipv6}
or @code{any} to listen for both IPv4 and IPv6 connections.

@item tcp_interface = string
Only useful if running as root.

@item tls_timeout = seconds
The number of seconds to wait for a read() or write() call on a
@abbr{TLS} client file descriptor to complete before returning an
error. The default is @var{300}.

Note that the @code{SAVE} command (@pxref{SAVE}) may take a longer time
to complete than other commands since key generation may need to be done
or do to a large @option{--cipher-iterations} setting.

@item keepalive_interval = seconds
Send a keepalive status message to an idle remote client.  An idle
client is one who is not in a command. The purpose of this status
message is to disconnect a hung remote client and release any file mutex
locks so another client may open the same data file. The default is @code{60}.

@item tcp_require_key = boolean
When @code{true}, require the remote client to provide the key or passphrase
to open a data file even if the file is cached. Note that the cache entry is
cleared during the @pxref{OPEN} command and the passphrase will be retrieved
from the client via a server @emph{INQUIRE}. This option is a default
for all files when specified in the @samp{global} section. The default
is @code{false}.

@item tcp_wait = integer
The time in tenths of a second to wait between TCP connections.  Setting to 0
will disable waiting. The default is @code{3}.

@item tls_cipher_suite = string
The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
information about the format of this string. The default is @code{SECURE256}.
@end table

@node Pinentry, Commands, TLS, Configuration
@chapter Pinentry configuration
@mansect Pinentry
The @command{pinentry} program is used to prompt the user for passphrase
input or as a confirmation dialog; it needs to know where to prompt for
the input, beit from a terminal or an X11 display.

It is the responsibility of the client to tell @command{pinentry} about
the terminal or X11 display before requiring the input. This is done by
using the @command{pwmd} @code{OPTION} (@pxref{OPTION}) protocol command. It
need be done only once per client connection. To avoid the use of
@command{pinentry} entirely, use the @code{OPTION} (@pxref{OPTION})
@option{--disable-pinentry} protocol command.

@ifclear isman
@c    Node,     Next,    Previous, Up
@node Commands, Status Messages, Pinentry, Top
@chapter Protocol commands and their syntax
@include menu.texi
@include commands.texi

@c    Node,     Next,    Previous, Up 
@node Status Messages, Target Attribute, Commands, Top 
@chapter Status messages and their meanings
Some commands send status messages to inform the client about certain
operations or as a progress indicator.  Status messages begin with a
@code{KEYWORD} followed by a status description for status messages that
require it. What status messages are sent, when, and how often may depend on
configuration settings (@pxref{Configuration}). A status message sent from
@command{gpg-agent} (@inforef{Invoking GPG-AGENT,,gnupg}) is also forwarded to
the client.

@multitable @columnfractions .20 .25 .55
@headitem Message @tab Parameters @tab Description
@item CACHE
@cindex CACHE
@tab @code{<integer>}
@tab The number of cached documents. Sent to each client after connecting
(@pxref{GETINFO}) and after every cache modification.

@item CLIENTS
@cindex CLIENTS
@tab @code{<integer>}
@tab The number of connected clients (@pxref{GETINFO}). Sent to each client
when another client either connects or disconnects.

@item DECRYPT
@cindex DECRYPT
@tab @code{<current>} @code{<total>}
@tab Sent to the current client during a decrypt operation. How often this
status message is sent is determined by the @code{cipher_progress}
(@pxref{Configuration}) setting.

@item ENCRYPT
@cindex ENCRYPT
@tab @code{<current>} @code{<total>}
@tab Sent to the current client during an  encrypt operation. How often this
status message is sent is determined by the @code{cipher_progress}
(@pxref{Configuration}) setting.

@item GENKEY
@cindex GENKEY
@tab
@tab Sent once to the current client just before generating a new key-pair.

@item INQUIRE_MAXLEN
@cindex INQUIRE_MAXLEN
@tab @code{<bytes>}
@tab Sent to the client from @command{gpg-agent} when inquiring data. This
specifies the maximum number of bytes allowed for the client to send and
should not be exceeded.

@item KEEPALIVE
@cindex KEEPALIVE
@tab
@tab Sent to each idle client every @var{keepalive_interval}
(@pxref{Configuration}) seconds.

@item LOCKED
@cindex LOCKED
@tab
@tab Sent to the current client when another client is holding the lock for
the mutex associated with a file.

@item NEWFILE
@cindex NEWFILE
@tab
@tab Sent to the current client when the opened (@pxref{OPEN}) file does not
exist on the file-system.

@item XFER
@cindex XFER
@tab @code{<sent> <total>}
@tab Sent to the current client when transferring data. It has two space
delimited arguments. The first being the current amount of bytes transferred
and the other being the total bytes to be transferred.

@item STATE
@cindex STATE
@tab @code{<client_id> <state>}
@tab Sent to all connected clients to indicate that @var{client_id} has
changed to @var{state} (@pxref{GETINFO} to describe the available client
states).
@end multitable

@c    Node,     Next,    Previous, Up 
@node Target Attribute, Signals, Status Messages, Top 
@chapter The @code{target} attribute
@cindex target attribute
A @emph{case sensitive} attribute named @code{target} is treated specially
when found in each element of an element path. This attribute, like other
element attributes, is created or modified with the @code{ATTR} command
(@pxref{ATTR}). The value of this attribute is an existing element path
somewhere in the document.  If you are familiar with @abbr{XML} entities or
maybe the @abbr{HTML} @code{id} or @code{target} attributes or a symbolic link
in a file-system, you may find this attribute behaves similar to any of those.

To create a @code{target} attribute use the following syntax:

@example
ATTR SET target [!]element[@key{TAB}[!]child[..]] [!]element[@key{TAB}[!]child[..]]
@end example

Note the single space between the two element paths. The first element path is
where the @code{target} attribute will be created. If the element path does
not exist then it will be created.  This is the only time the @code{ATTR}
(@pxref{ATTR}) command will create elements. The attribute is created in the
final element of the first element path.

The second element path is the destination of where you want the first element
path to resolve to. When an element path is passed as an argument to a
protocol command @command{pwmd} looks for a @code{target} attribute when
resolving each element and, if found, "jumps" to the attribute value and
continues resolving any remaining elements.  When you want to avoid the
@code{target} attribute for any element of an element path then prefix the
element with the literal element character @samp{!}.

When an element of a element path is removed that a @code{target} attribute
resolves to then an error will occur when trying to access that element. You
may need to either update the @code{target} attribute value with a new element
path or remove the attribute entirely. Remember that since the element
contains the @code{target} attribute it will need to be prefixed with the
literal element character @samp{!} when specifying the element path to prevent
@command{pwmd} from trying to resolve the @code{target} attribute. For
example, to remove a @code{target} attribute for an element containing it:

@example
ATTR DELETE target path@key{TAB}to@key{TAB}!element
@end example

Clients should be careful of creating @code{target} loops, or targets that
resolve to themselves. See the @var{recursion_depth} (@pxref{Configuration})
configuration parameter for details.

The @code{REALPATH} command (@pxref{REALPATH}) can be used to show the element
path after resolving all @code{target} attributes.


@c    Node,     Next,    Previous, Up 
@node Signals, Concept Index, Target Attribute, Top
@chapter Recognized signals
@end ifclear
@mansect signals
Sending the @emph{SIGHUP} signal to a @command{pwmd} process will reload the
configuration file and sending @emph{SIGUSR1} will clear the entire file
cache.

@mansect see also
@ifset manverb
.BR gpg-agent (1),
.BR pinentry (1)
@end ifset

@ifclear isman
@c    Node,     Next,    Previous, Up 
@node Concept Index, , Signals, Top 
@unnumbered Concept Index


@c @printindex cp
@shortcontents 
@contents 
@end ifclear
@bye