Version 2.14.

[pwmd.git] / doc / pwmd.1.in

.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH PWMD 1 "8 Feb 2010" "Password Manager Daemon" "Password Manager Daemon"
.SH NAME

pwmd \- a universal data server
.SH SYNOPSIS
.B pwmd
[options] [file1] [...]

.SH DESCRIPTION
.B pwmd
is a daemon/server that serves clients data which is stored in an, optionally
encrypted and compressed, XML data file. Clients connect and send commands
that either retrieve or store data.

.SH OPTIONS
The following are the available command line options. Remaining arguments are
files to add to the cache on startup.
.TP
.I "\-\-rcfile, \-f rcfile"
Specify an alternate configuration file. The default is \fB~/.pwmd/config\fR.

.TP
.I "\-\-import, \-I filename \-\-outfile filename"
Imports an XML file. The XML file should be in conformance to the pwmd DTD.
See COMMANDS contained in the distributed pwmd archive for details. If
encryption is wanted (specified with the \fBiterations\fP configuration
parameter or the \fI\-\-iterations\fP command line switch), you will be
prompted for a passphrase to encrypt with. The output is written to the
filename specified with the \fI\-\-outfile\fP command line switch which should
then be placed in the configured \fBdata_directory\fP.

.TP
.I "\-\-iterations, \-i iterations
The number of encryption iterations to use when importing. When not specified,
the \fBiterations\fP configuration option from the \fBglobal\fP section will
be used.

.TP
.I "\-\-key\-file, \-k keyfile"
When importing (\fI\-\-import\fP) or converting (\fI\-\-convert\fP), obtain
the key from the specified filename. Be sure to set \fBkey_file\fP in your
configuration.

.TP
.I "\-\-convert, \-C filename \-\-outfile filename"
Converts a \fBpwmd\fP version 1 data file to a version 2 data file. If
encrypted, you will be prompted for a passphrase to use for decryption (unless
using a \fI\-\-key-file\fP). The converted data file will be saved to the
filename specified with the \fI\-\-outfile\fP command line switch and with the
same passphrase and iterations as the version 1 data file.

.TP
.I "\-\-disable\-dump, \-D"
Disable the XPATH, LIST and DUMP protocol commands. This overrides any
\fBdisable_list_and_dump\fP configuration parameter.

.TP
.I "\-\-no\-fork, \-n"
Run as a foreground process.

.TP
.I "\-\-no\-pinentry, \-P"
Disable
.BR pinentry (1)
use overriding any configuration setting.

.TP
.I "\-\-version"
Version information.

.TP
.I "\-\-help"
Help text.

.SH CONFIGURATION FILE
Blank lines and lines beginning with '#' are ignored. Some options can 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., \fI[filename]\fP).
Global options may be specified in a \fI[global]\fP section and are the
default options for new or unspecified files. If the first character of a
string value is a tilde, it will be expanded to your home directory. First the
global options:
.TP
.I "socket_path=<string>"
Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.

.TP
.I "socket_perms=<integer>"
Permissions to set after creating the socket. This will override any
.BR umask (2)
setting.

.TP
.I "allowed=<user,@group,...>"
A comma separated list of local usernames or group names allowed to connect to
the socket. Groups should be prefixed with a '@'. When not specified only the
invoking user may connect. The username is obtained via SO_PEERCRED.

.TP
.I "data_directory=<string>"
Where
.B pwmd
should store and retrieve data files. The default is \fI~/.pwmd/data\fR.

.TP
.I "disable_mlockall=<boolean>"
When set to \fBfalse\fP,
.BR mlockall (2)
will be called after the client connects. This will use more physical memory
but may also be more secure. Most will probably find it overkill since the
contents of all allocated memory is cleared before being freed. Note that this
doesn't affect the file cache which is always stored in RAM (if possible).

.TP
.I "log_path=<string>"
Logs informational messages to the specified file. The default is
\fI~/.pwmd/log\fR.

.TP
.I "enable_logging=<boolean>"
Enable or disable logging to \fIlog_path\fR. The default is \fBfalse\fR.

.TP
.I "syslog=<boolean>"
Enable logging to
.BR syslog (8)
with facility LOG_DAEMON and priority LOG_INFO. The default is \fBfalse\fR.

.TP
.I "log_level=<integer>"
The logging level. When \fB0\fP, only connections and errors are logged. When
\fB1\fP, client commands are also logged. When \fB2\fP, the command arguments
are also logged. The default is \fB0\fP.

.TP
.I "debug_file=<string>"
When set, enable protocol debugging to the specified file. Note that this
logs all protocol IO so it may also log sensitive data.

.TP
.I "disable_list_and_dump=<boolean>"
When \fBtrue\fP, the \fBXPATH\fP, \fBLIST\fP and \fBDUMP\fP protocol commands
will be disabled and will return an error code.

.TP
.I "cache_push=<list>"
A list of filenames separated with commas that will be pushed into the file
cache upon startup.
.B pwmd
will prompt for the key for each file specified unless the key was specified
with the \fIkey\fR or \fIkey_file\fR parameters in a matching file section.
The default is none.

.TP
.I "priority=<integer>"
The priority, or niceness, of the server. The default is inherited from the
parent process.

.PP
Below are options that can be specified in the \fB[global]\fP or
\fB[filename]\fP section. If in both then \fB[filename]\fP will have
precedence.
.TP
.I "backup=<boolean>"
Whether to create a backup of the data file when saving. The default is
\fBtrue\fP. The backup filename has the .backup extension appended to the
opened file.

.TP
.I "cache_timeout=<integer>"
The number of seconds to keep the cache entry for this file. If \fB-1\fP, the
cache entry is kept forever. If \fB0\fP, each time the file is opened (if
encrypted) or saved a key will be required.

.TP
.I "enable_pinentry=<boolean>"
If \fBfalse\fP, disable the use of
.BR pinentry (1).
When disabled and a file requires a passphrase, the passphrase must be
included in the command (see COMMANDS included in the archive). The default is
\fBtrue\fP. Also see \fBPINENTRY\fP below.

.TP
.I "pinentry_path=<string>"
The full path of the pinentry binary. The default is specified at compile
time.

.TP
.I "pinentry_timeout=<integer>"
The number of seconds before the pinentry dialog will terminate while waiting
for a passphrase. The default is \fB20\fP. Set to \fB0\fP to wait forever.

.TP
.I "iterations=<integer>"
The number of times to encrypt the data. A value of 10000 or more will make
dictionary attacks very slow depending on the CPU and size of the data file.
The default is \fB1\fP iteration. Setting to \fB0\fP will disable encryption.

.TP
.I "cipher=<string>"
The default cipher to use when saving a data file. Valid values are:
\fBaes128\fP, \fBaes192\fP, \fBaes256\fP, \fBserpent128\fP, \fBserpent192\fP,
\fBserpent256\fP, \fBcamellia128\fP, \fBcamellia192\fP, \fBcamellia256\fP,
\fB3des\fP, \fBcast5\fP, \fBblowfish\fP, \fBtwofish128\fP and
\fBtwofish256\fP. The default is \fBaes256\fP.

.TP
.I "iteration_progress=<integer>"
After the specified number of iterations have been processed while encrypting
or decrypting, a status message with the keyword \fBPROGRESS\fP will be sent
to the client.  Setting to \fB0\fP, the default, disables sending these
progress messages.

.TP
.I "xfer_progress=<integer>"
Commands that send data lines to the client can send the XFER status message
after the specified number of bytes have been sent. The number of bytes is
rounded to ASSUAN_LINELENGTH (1002).

.TP
.I "key=<string>"
The initial passphrase to use for this file. If specified in the
\fBglobal\fP section then "\fBglobal\fP" 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 with the \fBSAVE\fP command, then this value is not
modified and will need to be updated by hand.

.TP
.I "key_file=<string>"
Same as the \fBkey\fP option above but obtains the key from the specified
filename. Note that if the cache entry for this file gets removed then the
only way to add it again is to restart \fBpwmd\fP or to re-read the
configuration file (i.e., you won't be prompted from pinentry).

Starting with pwmd version 2.14 the entire file is treated as the passphrase
including null bytes and newlines. A log message will be displayed warning
of the byte position that the key file of previous versions will be truncated
to, if any. This message means that the byte position is really the length or
size of the key data which may not be the size of the key file. A fix for this
is to generate a new key file and \fBimport\fP your data that was exported via
the \fBDUMP\fP command with the new key file.

.TP
.I "compression_level=<integer>"
The default compression level for data files from \fB1\fP to \fB9\fP, \fB1\fP
being the fastest but least compression and \fB9\fP being the slowest but best
compression. To disable compression entirely, set to \fB0\fP. The default is
\fB6\fP.

.TP
.I "zlib_bufsize=<integer>"
The input and output buffer size when compressing and decompressing. This
affects how often the COMPRESS and DECOMPRESS status messages are sent and
also affects compression quality. The default is \fB65536\fP. Set to a higher
value for larger files.

.TP
.I "recursion_depth=<integer>"
The maximum number of times to resolve a target attribute for a single element
in an element path. An error is returned when this value is exceeded. The
default is \fB20\fP but can be disabled by setting to \fB0\fP.

.TP
.I "keepalive=<integer>"
Sends keep alive status messages to the client every N seconds. Set to \fB0\fP
to disable. The default is \fB0\fP.

.SH PINENTRY
.P
When \fBenable_pinentry\fP is \fBtrue\fP, commands that require a key
will use
.BR pinentry (1)
to retrieve the passphrase. Since \fBpwmd\fP is normally a daemon process, it
isn't attached to any terminal. So \fBpinentry\fP needs to know where to put
it's dialog box by using command line options when executed. These can be set
by either using protocol commands (see COMMANDS included in the archive) or by
creating a file \fI~/.pwmd/pinentry.conf\fP. When using this file, each line
should contain NAME=VALUE pairs where NAME is one of:
.TP
.B TTYNAME
The full path of the tty device.

.TP
.B TTYTYPE
The terminal type (i.e., vt100). Must be set when \fBTTYNAME\fP is set.

.TP
.B DISPLAY
If using an X11 pinentry.

.TP
.B LC_CTYPE
For internationalization.

.TP
.B LC_MESSAGES
For internationalization.

.TP
.B PATH
The full path to the pinentry binary. The default is \fI@pinentry@\fP.

.P
The file is read only once after each client first connects. Note that if your
not using a \fBDISPLAY\fP, then both \fBTTYNAME\fP and \fBTTYTYPE\fP should be
set otherwise you'll get a segfault from ncurses.

.SH SIGNALS
.TP
.B SIGUSR1
Clears the entire file cache. If there are any clients connected, a key will
be required for the next \fBOPEN\fP or \fBSAVE\fP command.
.TP
.B SIGHUP
Reloads the configuration file.
.TP
.B SIGTERM and SIGINT
Disallows new connections and waits for all clients to disconnect before
terminating.

.SH FILES
.TP
.B ~/.pwmd/config
Default configuration file.
.TP
.B ~/.pwmd/data
Default data directory.
.TP
.B ~/.pwmd/socket
Default listening socket.
.TP
.B ~/.pwmd/log
Default log file when logging is enabled.
.TP
.B @pinentry@
Default location of the pinentry binary.
.TP
.B ~/.pwmd/pinentry.conf
Default pinentry settings for new clients.

.SH AUTHOR
Ben Kibbey <bjk@luxsci.net>
.br
.URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .

.SH "SEE ALSO"
.BR pinentry (1)

Also see \fBCOMMANDS\fP included in the archive for protocol commands and
syntax.