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 "25 Apr 2009" "Password Manager Daemon" "Password Manager Daemon"
  19 .SH NAME
  20
  21 pwmd \- a universal data server
  22 .SH SYNOPSIS
  23 .B pwmd
  24 [options] [file1] [...]
  25
  26 .SH DESCRIPTION
  27 .B pwmd
  28 is a daemon/server that serves clients data which is stored in an, optionally
  29 encrypted and compressed, XML data file. Clients connect and send commands
  30 that either retrieve or store data.
  31
  32 .SH OPTIONS
  33 The following are the available command line options. Remaining arguments are
  34 files to add to the cache on startup.
  35 .TP
  36 .I "\-\-rcfile, \-f rcfile"
  37 Specify an alternate configuration file. The default is \fB~/.pwmd/config\fR.
  38
  39 .TP
  40 .I "\-\-import, \-I filename \-\-outfile filename"
  41 Imports an XML file. The XML file should be in conformance to the pwmd DTD.
  42 See COMMANDS contained in the distributed pwmd archive for details. If
  43 encryption is wanted (specified with the \fBiterations\fP configuration
  44 parameter or the \fI\-\-iterations\fP command line switch), you will be
  45 prompted for a passphrase to encrypt with. The output is written to the
  46 filename specified with the \fI\-\-outfile\fP command line switch which should
  47 then be placed in the configured \fBdata_directory\fP.
  48
  49 .TP
  50 .I "\-\-iterations, \-i iterations
  51 The number of encryption iterations to use when importing. When not specified,
  52 the \fBiterations\fP configuration option from the \fBglobal\fP section will
  53 be used.
  54
  55 .TP
  56 .I "\-\-key\-file, \-k keyfile"
  57 When importing (\fI\-\-import\fP) or converting (\fI\-\-convert\fP), obtain
  58 the key from the specified filename. Only the first line is read from this
  59 file. Be sure to set \fBkey_file\fP in your configuration.
  60
  61 .TP
  62 .I "\-\-convert, \-C filename \-\-outfile filename"
  63 Converts a \fBpwmd\fP version 1 data file to a version 2 data file. If
  64 encrypted, you will be prompted for a passphrase to use for decryption (unless
  65 using a \fI\-\-key-file\fP). The converted data file will be saved to the
  66 filename specified with the \fI\-\-outfile\fP command line switch and with the
  67 same passphrase and iterations as the version 1 data file.
  68
  69 .TP
  70 .I "\-\-disable\-dump, \-D"
  71 Disable the XPATH, LIST and DUMP protocol commands. This overrides any
  72 \fBdisable_list_and_dump\fP configuration parameter.
  73
  74 .TP
  75 .I "\-\-no\-fork, \-n"
  76 Run as a foreground process.
  77
  78 .TP
  79 .I "\-\-no\-pinentry, \-P"
  80 Disable
  81 .BR pinentry (1)
  82 use overriding any configuration setting.
  83
  84 .TP
  85 .I "\-\-version"
  86 Version information.
  87
  88 .TP
  89 .I "\-\-help"
  90 Help text.
  91
  92 .SH CONFIGURATION FILE
  93 Blank lines and lines beginning with '#' are ignored. Some options can have
  94 data file-specific settings by placing them in a file section. A file section
  95 is declared by surrounding the filename with braces (i.e., \fI[filename]\fP).
  96 Global options may be specified in a \fI[global]\fP section and are the
  97 default options for new or unspecified files. If the first character of a
  98 string value is a tilde, it will be expanded to your home directory. First the
  99 global options:
 100 .TP
 101 .I "socket_path=<string>"
 102 Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.
 103
 104 .TP
 105 .I "socket_perms=<integer>"
 106 Permissions to set after creating the socket. This will override any
 107 .BR umask (2)
 108 setting.
 109
 110 .TP
 111 .I "data_directory=<string>"
 112 Where
 113 .B pwmd
 114 should store and retrieve data files. The default is \fI~/.pwmd/data\fR.
 115
 116 .TP
 117 .I "disable_mlockall=<boolean>"
 118 When set to \fBfalse\fP,
 119 .BR mlockall (2)
 120 will be called after the client connects. This will use more physical memory
 121 but may also be more secure. Most will probably find it overkill since the
 122 contents of all allocated memory is cleared before being freed. Note that this
 123 doesn't affect the file cache which is always stored in RAM (if possible).
 124
 125 .TP
 126 .I "log_path=<string>"
 127 Logs informational messages to the specified file. The default is
 128 \fI~/.pwmd/log\fR.
 129
 130 .TP
 131 .I "enable_logging=<boolean>"
 132 Enable or disable logging to \fIlog_path\fR. The default is \fBfalse\fR.
 133
 134 .TP
 135 .I "syslog=<boolean>"
 136 Enable logging to
 137 .BR syslog (8)
 138 with facility LOG_DAEMON and priority LOG_INFO. The default is \fBfalse\fR.
 139
 140 .TP
 141 .I "disable_list_and_dump=<boolean>"
 142 When \fBtrue\fP, the \fBXPATH\fP, \fBLIST\fP and \fBDUMP\fP protocol commands
 143 will be disabled and will return an error code.
 144
 145 .TP
 146 .I "cache_push=<list>"
 147 A list of filenames separated with commas that will be pushed into the file
 148 cache upon startup.
 149 .B pwmd
 150 will prompt for the key for each file specified unless the key was specified
 151 with the \fIkey\fR or \fIkey_file\fR parameters in a matching file section.
 152 The default is none.
 153
 154 .TP
 155 .I "priority=<integer>"
 156 The priority, or niceness, of the server. The default is inherited from the
 157 parent process.
 158
 159 .PP
 160 Below are options that can be specified in the \fB[global]\fP or
 161 \fB[filename]\fP section. If in both then \fB[filename]\fP will have
 162 precedence.
 163 .TP
 164 .I "backup=<boolean>"
 165 Whether to create a backup of the data file when saving. The default is
 166 \fBtrue\fP. The backup filename has the .backup extension appended to the
 167 opened file.
 168
 169 .TP
 170 .I "cache_timeout=<integer>"
 171 The number of seconds to keep the cache entry for this file. If \fB-1\fP, the
 172 cache entry is kept forever. If \fB0\fP, each time the file is opened (if
 173 encrypted) or saved a key will be required.
 174
 175 .TP
 176 .I "enable_pinentry=<boolean>"
 177 If \fBfalse\fP, disable the use of
 178 .BR pinentry (1).
 179 When disabled and a file requires a passphrase, the passphrase must be
 180 included in the command (see COMMANDS included in the archive). The default is
 181 \fBtrue\fP. Also see \fBPINENTRY\fP below.
 182
 183 .TP
 184 .I "pinentry_path=<string>"
 185 The full path of the pinentry binary. The default is specified at compile
 186 time.
 187
 188 .TP
 189 .I "pinentry_timeout=<integer>"
 190 The number of seconds before the pinentry dialog will terminate while waiting
 191 for a passphrase. The default is \fB20\fP. Set to \fB0\fP to wait forever.
 192
 193 .TP
 194 .I "iterations=<integer>"
 195 The number of times to encrypt the data. A value of 10000 or more will make
 196 dictionary attacks very slow depending on the CPU and size of the data file.
 197 The default is \fB1\fP iteration. Setting to \fB0\fP will disable encryption.
 198
 199 .TP
 200 .I "iteration_progress=<integer>"
 201 After the specified number of iterations have been processed while encrypting
 202 or decrypting, a status message with the keyword \fBPROGRESS\fP will be sent
 203 to the client.  Setting to \fB0\fP, the default, disables sending these
 204 progress messages.
 205
 206 .TP
 207 .I "xfer_progress=<integer>"
 208 Commands that send data lines to the client can send the XFER status message
 209 after the specified number of bytes have been sent. The number of bytes is
 210 rounded to ASSUAN_LINELENGTH (1002).
 211
 212 .TP
 213 .I "key=<string>"
 214 The initial passphrase to use for this file. If specified in the
 215 \fB[global]\fP section then "\BIglobal\fP" is treated as a data filename and
 216 not a default for other files. Note that if a client changes the passphrase
 217 for this data file with the \fBSAVE\fP command, then this value is not
 218 modified and will need to be updated by hand.
 219
 220 .TP
 221 .I "key_file=<string>"
 222 Same as the \fBkey\fP option above but obtains the key from the specified
 223 filename with the key being on the first line of the file. Note that if the
 224 cache entry for this file gets removed then the only way to have it added
 225 again is to restart \fBpwmd\fP or to re-read the configuration file (i.e., you
 226 won't be prompted from pinentry).
 227
 228 .TP
 229 .I "compression_level=<integer>"
 230 The default compression level for data files from \fB1\fP to \fB9\fP, \fB1\fP
 231 being the fastest but least compression and \fB9\fP being the slowest but best
 232 compression. To disable compression entirely, set to \fB0\fP. The default is
 233 \fB6\fP.
 234
 235 .TP
 236 .I "zlib_bufsize=<integer>"
 237 The input and output buffer size when compressing and decompressing. This
 238 affects how often the COMPRESS and DECOMPRESS status messages are sent and
 239 also affects compression quality. The default is \fB65536\fP. Set to a higher
 240 value for larger files.
 241
 242 .TP
 243 .I "recursion_depth=<integer>"
 244 The maximum number of times to resolve a target attribute for a single element
 245 in an element path. An error is returned when this value is exceeded. The
 246 default is \fB20\fP but can be disabled by setting to \fB0\fP.
 247
 248 .TP
 249 .I "keepalive=<integer>"
 250 Sends keep alive status messages to the client every N seconds. Set to \fB0\fP
 251 to disable (not recommended). The default is \fB30\fP.
 252
 253 .SH PINENTRY
 254 .P
 255 When \fBenable_pinentry\fP is \fBtrue\fP, commands that require a key
 256 will use
 257 .BR pinentry (1)
 258 to retrieve the passphrase. Since \fBpwmd\fP is normally a daemon process, it
 259 isn't attached to any terminal. So \fBpinentry\fP needs to know where to put
 260 it's dialog box by using command line options when executed. These can be set
 261 by either using protocol commands (see COMMANDS included in the archive) or by
 262 creating a file \fI~/.pwmd/pinentry.conf\fP. When using this file, each line
 263 should contain NAME=VALUE pairs where NAME is one of:
 264 .TP
 265 .B TTYNAME
 266 The full path of the tty device.
 267
 268 .TP
 269 .B TTYTYPE
 270 The terminal type (i.e., vt100). Must be set when \fBTTYNAME\fP is set.
 271
 272 .TP
 273 .B DISPLAY
 274 If using an X11 pinentry.
 275
 276 .TP
 277 .B LC_CTYPE
 278 For internationalization.
 279
 280 .TP
 281 .B LC_MESSAGES
 282 For internationalization.
 283
 284 .TP
 285 .B PATH
 286 The full path to the pinentry binary. The default is \fI@pinentry@\fP.
 287
 288 .P
 289 The file is read only once after each client first connects. Note that if your
 290 not using a \fBDISPLAY\fP, then both \fBTTYNAME\fP and \fBTTYTYPE\fP should be
 291 set otherwise you'll get a segfault from ncurses.
 292
 293 .SH SIGNALS
 294 .TP
 295 .B SIGUSR1
 296 Clears the entire file cache. If there are any clients connected, a key will
 297 be required for the next \fBOPEN\fP or \fBSAVE\fP command.
 298 .TP
 299 .B SIGHUP
 300 Reloads the configuration file.
 301 .TP
 302 .B SIGTERM and SIGINT
 303 Disallows new connections and waits for all clients to disconnect before
 304 terminating.
 305
 306 .SH FILES
 307 .TP
 308 .B ~/.pwmd/config
 309 Default configuration file.
 310 .TP
 311 .B ~/.pwmd/data
 312 Default data directory.
 313 .TP
 314 .B ~/.pwmd/socket
 315 Default listening socket.
 316 .TP
 317 .B ~/.pwmd/log
 318 Default log file when logging is enabled.
 319 .TP
 320 .B @pinentry@
 321 Default location of the pinentry binary.
 322 .TP
 323 .B ~/.pwmd/pinentry.conf
 324 Default pinentry settings for new clients.
 325
 326 .SH AUTHOR
 327 Ben Kibbey <bjk@luxsci.net>
 328 .br
 329 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 330
 331 .SH "SEE ALSO"
 332 .BR pinentry (1)
 333
 334 Also see \fBCOMMANDS\fP included in the archive for protocol commands and
 335 syntax.