doc/pwmd.1.in

   1 .\" This program is free software; you can redistribute it and/or modify
   2 .\" it under the terms of the GNU General Public License as published by
   3 .\" the Free Software Foundation; either version 2 of the License, or
   4 .\" (at your option) any later version.
   5 .\"
   6 .\" This program is distributed in the hope that it will be useful,
   7 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   8 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   9 .\" GNU General Public License for more details.
  10 .\"
  11 .\" You should have received a copy of the GNU General Public License
  12 .\" along with this program; if not, write to the Free Software
  13 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH PWMD 1 "27 Sep 2008" "Password Manager Daemon" "Password Manager Daemon"
  19 .SH NAME
  20
  21 pwmd \- local socket data server
  22 .SH SYNOPSIS
  23 .B pwmd
  24 [\-hv] [\-f <rcfile>] [\-I <filename> [-i <iterations>]] [\-D] [\-n] [file] [...]
  25
  26 .SH DESCRIPTION
  27 .B pwmd
  28 is a daemon that listens for connections on a local socket. Clients connect to
  29 the server and can retrieve or modify "account" data. The word "account" is
  30 just a placeholder for the element describing and item. But what the data
  31 actually is can be anything. The data is stored in an (optionally AES256
  32 encrypted) XML file.
  33
  34 .SH OPTIONS
  35 The following are the available command line options. Remaining arguments are
  36 files to add to the cache on startup.
  37 .TP
  38 .I "\-f rcfile"
  39 Specify an alternate configuration file. The default is \fI~/.pwmd/config\fR.
  40 .TP
  41 .I "\-I filename"
  42 Import an XML file prompting for a key to use for encryption. The encrypted
  43 data will be written to stdout. This output should be redirected to a file
  44 which is placed in the configured \fIdata_directory\fP.
  45 .TP
  46 .I "\-i iterations
  47 The number of encryption iterations when importing. When not specified, the
  48 configuration file default will be used from the \fIglobal\fP section.
  49 .TP
  50 .I "\-D"
  51 Disable the LIST and DUMP protocol commands.
  52 .TP
  53 .I "\-n"
  54 Run as a foreground process.
  55 .TP
  56 .I "\-v"
  57 Version information.
  58 .TP
  59 .I "\-h"
  60 Help text.
  61
  62 .SH CONFIGURATION FILE
  63 Blank lines and lines beginning with '#' are ignored. Some options can be
  64 grouped together to have file specific settings. A file section is declared by
  65 surrounding the filename with braces (i.e., \fI[filename]\fP). Global options
  66 may be specified in a \fI[global]\fP section and are the defaults for other
  67 file sections. If the first character of a string value is a tilde, it will be
  68 expanded to your home directory. First the global options:
  69 .TP
  70 .I "socket_path=<string>"
  71 Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.
  72 .TP
  73 .I "socket_perms=<integer>"
  74 Permissions to set after creating the socket. This will override any
  75 .BR umask (2)
  76 setting.
  77 .TP
  78 .I "data_directory=<string>"
  79 Where
  80 .B pwmd
  81 should store and retrieve data files. The default is \fI~/.pwmd/data\fR.
  82 .TP
  83 .I "disable_mlockall=<boolean>"
  84 When set to \fBfalse\fP,
  85 .BR mlockall (2)
  86 will be called after the client connects. This will use alot more physical
  87 memory but may also be more secure. Most will probably find it overkill since
  88 the contents of all memory is cleared before being freed. Note that this
  89 doesn't affect the file cache which is always stored in RAM (if possible).
  90 .TP
  91 .I "cache_size=<integer>"
  92 Specfies the size of the file cache. Must be in multiples of your systems
  93 \fBPAGE_SIZE\fR. The default is one page.
  94 .TP
  95 .I "log_path=<string>"
  96 Logs informational messages to the specified file. The default is
  97 \fI~/.pwmd/log\fR.
  98 .TP
  99 .I "enable_logging=<boolean>"
 100 Enable or disable logging to \fIlog_path\fR. The default is \fIfalse\fR.
 101 .TP
 102 .I "syslog=<boolean>"
 103 Enable logging to
 104 .BR syslog (8)
 105 with facility LOG_DAEMON and priority LOG_INFO. The default is \fIfalse\fR.
 106 .TP
 107 .I "cache_push=<list>"
 108 A list of filenames separated by commas that will be pushed into the file
 109 cache upon startup.
 110 .B pwmd
 111 will ask for the key for each file specified unless the key was specified with
 112 the \fBkey\fR or \fBkey_file\fR parameters in a matching file section. The
 113 default is none.
 114 .TP
 115 .I "priority=<integer>"
 116 The priority, or niceness, of the server. The default is inherited from the
 117 parent process.
 118 .PP
 119 Below are options that can be in the \fI[global]\fP or \fI[filename]\fP
 120 section. If in both then \fI[filename]\fP will have precedence.
 121 .TP
 122 .I "backup=<boolean>"
 123 Whether a backup of the data file should be kept when saving. The default is
 124 \fItrue\fP. The backup filename has the .backup extension appended to the
 125 opened file.
 126 .TP
 127 .I "cache_timeout=<integer>"
 128 The number of seconds for the life of the cached file. If \fI-1\fP, the file
 129 is cached forever. If \fI0\fP, each time the file is opened or saved a key
 130 will be required.
 131 .TP
 132 .I "enable_pinentry=<boolean>"
 133 If \fIfalse\fP, disable the use of
 134 .BR pinentry (1).
 135 The default is \fItrue\fP. Also see \fBPINENTRY\fP below.
 136 .TP
 137 .I "pinentry_timeout=<integer>"
 138 The number of seconds before the pinentry dialog will terminate while waiting
 139 for a password. Set to \fI0\fP to wait forever.
 140 .TP
 141 .I "iterations=<integer>"
 142 The number of times to encrypt the data. A value of 10000 or more will make
 143 dictionary attacks very slow depending on the CPU. The default is \fI0\fP
 144 which is really 1 iteration (data file compatibility bug). Setting to \fI-1\fP
 145 will disable encryption.
 146 .TP
 147 .I "iteration_progress=<integer>"
 148 After the specified number of iterations while encrypting or decrypting, a
 149 status message with the keyword \fBPROGRESS\fP will be sent to the client.
 150 Setting to \fI0\fP, the default, disables sending progress messages.
 151 .TP
 152 .I "key=<string>"
 153 The initial key to use for this file. If specified in the \fI[global]\fP
 154 section then "\fIglobal\fP" is treated as a filename and not a default for
 155 other files. Note that if a client changes the key this value is not modified
 156 and will need to be updated by hand.
 157 .TP
 158 .I "key_file=<string>"
 159 Same as above but obtain the key from the specified filename with the key
 160 being on the first line of the file. Note that if you change the key when
 161 connected this value is not modified and will need to be updated by hand.
 162 .TP
 163 .I "compression_level=<integer>"
 164 The default compression level for data files from \fI1\fP to \fI9\fP, \fI1\fP
 165 being the fastest but least compression and \fI9\fP being the slowest but best
 166 compression. To disable compression entirely, set to \fI0\fP. The default is
 167 \fI6\fP.
 168 .TP
 169 .I "zlib_bufsize=<integer>"
 170 The input and output buffer size when compressing and decompressing. This
 171 affects how often the COMPRESS and DECOMPRESS status messages are sent and
 172 also affects compression quality. The default is \fB65536\fP. Set to a higher
 173 value for larger files.
 174 .TP
 175 .I "recursion_depth=<integer>"
 176 The maximum number of times to resolve a target attribute for a single element
 177 in an element path. An error is returned when this value is exceeded. The
 178 default is \fI20\fP but can be disabled by setting to \fI0\fP.
 179 .TP
 180 .I "keepalive=<integer>"
 181 Sends keep alive status messages to the client every N seconds. Set to \fI0\fP
 182 to disable. The default is \fI5\fP.
 183
 184 .SH PINENTRY
 185 .P
 186 When \fIenable_pinentry\fP is \fBtrue\fP, commands that require a key that
 187 isn't cached or specified with the command, will use
 188 .BR pinentry (1)
 189 to retrieve the passphrase. Since \fBpwmd\fP is a daemon process, it isn't
 190 attached to any terminal. So \fBpinentry\fP needs to know where to put it's
 191 dialog box by using command line options when executed. These can be set by
 192 either using protocol commands (see COMMANDS included in the archive) or by
 193 creating a file \fI~/.pwmd/pinentry.conf\fP. When using the file, each line should
 194 contain NAME=VALUE pairs where NAME is one of:
 195 .TP
 196 .B TTYNAME
 197 The full path of the tty device.
 198 .TP
 199 .B TTYTYPE
 200 The terminal type (i.e., vt100).
 201 .TP
 202 .B DISPLAY
 203 If using an X11 pinentry.
 204 .TP
 205 .B PATH
 206 The full path to the pinentry binary. The default is \fI@pinentry@\fP.
 207 .P
 208 The file is read only once after each client first connects. Note that if your
 209 not using a \fBDISPLAY\fP, then both \fBTTYNAME\fP and \fBTTYTYPE\fP should be
 210 set otherwise you'll get a segfault from ncurses.
 211
 212 .SH SIGNALS
 213 .TP
 214 .B SIGUSR1
 215 Clears the entire file cache. If there are any clients connected, a key will
 216 be required for the next \fBOPEN\fP or \fBSAVE\fP command.
 217 .TP
 218 .B SIGHUP
 219 Reloads the configuration file.
 220 .TP
 221 .B SIGTERM and SIGINT
 222 Disallows new connections and waits for all clients to disconnect before
 223 terminating.
 224
 225 .SH FILES
 226 .TP
 227 .B ~/.pwmd/config
 228 Default configuration file.
 229 .TP
 230 .B ~/.pwmd/data
 231 Default data directory.
 232 .TP
 233 .B ~/.pwmd/socket
 234 Default listening socket.
 235 .TP
 236 .B ~/.pwmd/log
 237 Default log file when logging is enabled.
 238 .TP
 239 .B @pinentry@
 240 Default location of the pinentry binary.
 241 .TP
 242 .B ~/.pwmd/pinentry.conf
 243 Default pinentry settings for new clients.
 244
 245 .SH AUTHOR
 246 Ben Kibbey <bjk@luxsci.net>
 247 .br
 248 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 249
 250 .SH "SEE ALSO"
 251 .BR mlock (2),
 252 .BR mlockall (2),
 253 .BR libxml (3) ,
 254 .BR mmap (2),
 255 .BR pinentry (1)
 256
 257 Also see \fBCOMMANDS\fP included in the archive for protocol commands and
 258 syntax.