Updated the FSF address in the copyright header.

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

pwmd \- local socket data server
.SH SYNOPSIS
.B pwmd
[\-hv] [\-f <rcfile>] [\-I <filename> [-i <iterations>]] [\-D] [\-n] [file] [...]

.SH DESCRIPTION
.B pwmd
is a daemon that listens for connections on a local socket. Clients connect to
the server and can retrieve or modify "account" data. The word "account" is
just a placeholder for the element describing and item. But what the data
actually is can be anything. The data is stored in an AES encrypted XML file.

.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"
Import an XML file prompting for a key to use for encryption. The encrypted
data will be written to stdout.
.TP
.I "\-i iterations
The number of encryption iterations when importing. When not specified, the
configuration file default will be used from the \fIglobal\fP section.
.TP
.I "\-D"
Disable the LIST and DUMP protocol commands.
.TP
.I "\-n"
Run as a foreground process.
.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 "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 a 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.

.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 mlock (2),
.BR mlockall (2),
.BR libxml (3) ,
.BR mmap (2),
.BR pinentry (1)

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