Added configuration option "tcp_wait". Sets the time to wait for a new

[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 "15 Nov 2008" "Password Manager Daemon" "Password Manager Daemon"
.SH NAME

pwmd \- a universal data server
.SH SYNOPSIS
.B pwmd
[\-hvDnP] [\-f <rcfile>] [\-I <filename> [\-i <iterations>] [\-k <keyfile>]
\-o <filename>] [\-C <filename> \-o <filename>] [file] [...]

.SH DESCRIPTION
.B pwmd
is a daemon/server that serves clients data which is stored in a, 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 "\-f rcfile"
Specify an alternate configuration file. The default is \fI~/.pwmd/config\fR.
.TP
.I "\-I filename \-o 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 \fIiterations\fP configuration
parameter or the \fI\-i\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\-o\fP command line switch which should then be placed in the
configured \fIdata_directory\fP.
.TP
.I "\-i iterations
The number of encryption iterations to use when importing. When not specified,
the \fIiterations\fP configuration option from the \fIglobal\fP section will
be used.
.TP
.I "\-k keyfile"
When importing, obtain the key from the specified filename. Only the first
line is read from this file. Be sure to set \fIkey_file\fP in your
configuration.
.TP
.I "\-C filename \-o 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. The
converted data file will be saved to the filename specified with the \fI-o\fP
command line switch and with the same passphrase and iterations as the
version 1 data file.
.TP
.I "\-D"
Disable the LIST and DUMP protocol commands.
.TP
.I "\-n"
Run as a foreground process.
.TP
.I "\-P"
Disable
.BR pinentry (1)
support. Overrides and configuration setting.
.TP
.I "\-v"
Version information.
.TP
.I "\-h"
Help text.

.SH CONFIGURATION FILE
Blank lines and lines beginning with '#' are ignored. Some options can be
grouped together to have file specific settings. 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 defaults for other
file sections. 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 "enable_tcp=<boolean>"
Whether to enable TCP server support. The default is \fIdisabled\fP. See
\fBTCP SUPPORT\fP below.
.TP
.I "tcp_port=<integer>"
The port to listen on when \fIenable_tcp\fP is \fItrue\fP. The default is
\fI6466\fP.
.TP
.I "tcp_interface=<string>"
Only useful when run as root.
.TP
.I "tcp_access=[!]<string>"
A comma separated list of client x509 certificate fingerprints in MD5 format
that will be allowed to open a file. If prefixed with \fB!\fP, access is
denied for the specified certificate. The access control is used in the OPEN
command for the specified filename.  This option can be in either the
\fBglobal\fP section or a defined \fBfilename\fP section. If not found in
either then access will be granted. If defined but empty then access will be
denied.
.TP
.I "tcp_require_key=<boolean>"
Require the client to provide the key to open a file even if the file is
cached. The default is \fIfalse\fP.
.TP
.I "tcp_wait=<integer>"
The time in tenths of a second to wait for a new connection. The default is
\fB3\fP. Setting to \fB0\fP will disable waiting.
.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 alot more physical
memory but may also be more secure. Most will probably find it overkill since
the contents of all 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 "cache_size=<integer>"
Specfies the size of the file cache. Must be in multiples of your systems
\fBPAGE_SIZE\fR. The default is one page.
.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 \fIfalse\fR.
.TP
.I "syslog=<boolean>"
Enable logging to
.BR syslog (8)
with facility LOG_DAEMON and priority LOG_INFO. The default is \fIfalse\fR.
.TP
.I "cache_push=<list>"
A list of filenames separated by commas that will be pushed into the file
cache upon startup.
.B pwmd
will ask for the key for each file specified unless the key was specified with
the \fBkey\fR or \fBkey_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 in the \fI[global]\fP or \fI[filename]\fP
section. If in both then \fI[filename]\fP will have precedence.
.TP
.I "backup=<boolean>"
Whether a backup of the data file should be kept when saving. The default is
\fItrue\fP. The backup filename has the .backup extension appended to the
opened file.
.TP
.I "cache_timeout=<integer>"
The number of seconds for the life of the cached file. If \fI-1\fP, the file
is cached forever. If \fI0\fP, each time the file is opened or saved a key
will be required.
.TP
.I "enable_pinentry=<boolean>"
If \fIfalse\fP, disable the use of
.BR pinentry (1).
The default is \fItrue\fP. Also see \fBPINENTRY\fP below.
.TP
.I "pinentry_timeout=<integer>"
The number of seconds before the pinentry dialog will terminate while waiting
for a password. Set to \fI0\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. The default is \fI0\fP
which is really 1 iteration (data file compatibility bug). Setting to \fI-1\fP
will disable encryption.
.TP
.I "iteration_progress=<integer>"
After the specified number of iterations while encrypting or decrypting, a
status message with the keyword \fBPROGRESS\fP will be sent to the client.
Setting to \fI0\fP, the default, disables sending progress messages.
.TP
.I "key=<string>"
The initial key to use for this file. If specified in the \fI[global]\fP
section then "\fIglobal\fP" is treated as a filename and not a default for
other files. Note that if a client changes the key this value is not modified
and will need to be updated by hand.
.TP
.I "key_file=<string>"
Same as above but obtain the key from the specified filename with the key
being on the first line of the file. Note that if you change the key when
connected this value is not modified and will need to be updated by hand.
.TP
.I "compression_level=<integer>"
The default compression level for data files from \fI1\fP to \fI9\fP, \fI1\fP
being the fastest but least compression and \fI9\fP being the slowest but best
compression. To disable compression entirely, set to \fI0\fP. The default is
\fI6\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 \fI20\fP but can be disabled by setting to \fI0\fP.
.TP
.I "keepalive=<integer>"
Sends keep alive status messages to the client every N seconds. Set to \fI0\fP
to disable. The default is \fI5\fP.

.SH PINENTRY
.P
When \fIenable_pinentry\fP is \fBtrue\fP, commands that require a key that
isn't cached or specified with the command, will use
.BR pinentry (1)
to retrieve the passphrase. Since \fBpwmd\fP is 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 the 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).
.TP
.B DISPLAY
If using an X11 pinentry.
.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 TCP SUPPORT
When compiled with TCP support and \fIenable_tcp\fP is \fItrue\fP, \fBpwmd\fP
can accept connections from remote hosts. Authentication is done with X509
certificates. The server certificate should be signed by a certificate
authority (CA), which will probably be a locally generated one (see the
.BR certtool (1)
documentation for how to do this). When a client connects, \fBpwmd\fP
will require the client to send a certificate that was signed by the same
certificate authority that was used to sign the \fBpwmd\fP server certificate
(\fB~/.pwmd/ca-cert.pem\fP). After the client certificate is validated,
\fBpwmd\fP will accept commands from the client.

.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.
.TP
.B ~/.pwmd/ca-cert.pem
The certificate authority (CA) than was used to sign the server (and client)
certificate.
.TP
.B ~/.pwmd/server-cert.pem
The pwmd server certificate. This is sent to the client. Clients should check
the validity of it to ensure that the \fBpwmd\fP server hasn't been hijacked.
.TP
.B ~/.pwmd/server-key.pem
The key that was used to sign the server certificate.

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

.SH "SEE ALSO"
.BR certtool (1),
.BR pinentry (1),
.BR mlock (2),
.BR mlockall (2),
.BR libxml (3) ,
.BR mmap (2)

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