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 Jun 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 "log_level=<integer>"
 142 The logging level. When \fB0\fP, only connections and errors are logged. When
 143 \fB1\fP, client commands are also logged. When \fB2\fP, the command arguments
 144 are also logged. The default is \fB0\fP.
 145
 146 .TP
 147 .I "disable_list_and_dump=<boolean>"
 148 When \fBtrue\fP, the \fBXPATH\fP, \fBLIST\fP and \fBDUMP\fP protocol commands
 149 will be disabled and will return an error code.
 150
 151 .TP
 152 .I "cache_push=<list>"
 153 A list of filenames separated with commas that will be pushed into the file
 154 cache upon startup.
 155 .B pwmd
 156 will prompt for the key for each file specified unless the key was specified
 157 with the \fIkey\fR or \fIkey_file\fR parameters in a matching file section.
 158 The default is none.
 159
 160 .TP
 161 .I "priority=<integer>"
 162 The priority, or niceness, of the server. The default is inherited from the
 163 parent process.
 164
 165 .PP
 166 Below are options that can be specified in the \fB[global]\fP or
 167 \fB[filename]\fP section. If in both then \fB[filename]\fP will have
 168 precedence.
 169 .TP
 170 .I "backup=<boolean>"
 171 Whether to create a backup of the data file when saving. The default is
 172 \fBtrue\fP. The backup filename has the .backup extension appended to the
 173 opened file.
 174
 175 .TP
 176 .I "cache_timeout=<integer>"
 177 The number of seconds to keep the cache entry for this file. If \fB-1\fP, the
 178 cache entry is kept forever. If \fB0\fP, each time the file is opened (if
 179 encrypted) or saved a key will be required.
 180
 181 .TP
 182 .I "enable_pinentry=<boolean>"
 183 If \fBfalse\fP, disable the use of
 184 .BR pinentry (1).
 185 When disabled and a file requires a passphrase, the passphrase must be
 186 included in the command (see COMMANDS included in the archive). The default is
 187 \fBtrue\fP. Also see \fBPINENTRY\fP below.
 188
 189 .TP
 190 .I "pinentry_path=<string>"
 191 The full path of the pinentry binary. The default is specified at compile
 192 time.
 193
 194 .TP
 195 .I "pinentry_timeout=<integer>"
 196 The number of seconds before the pinentry dialog will terminate while waiting
 197 for a passphrase. The default is \fB20\fP. Set to \fB0\fP to wait forever.
 198
 199 .TP
 200 .I "iterations=<integer>"
 201 The number of times to encrypt the data. A value of 10000 or more will make
 202 dictionary attacks very slow depending on the CPU and size of the data file.
 203 The default is \fB1\fP iteration. Setting to \fB0\fP will disable encryption.
 204
 205 .TP
 206 .I "cipher=<string>"
 207 The default cipher to use when saving a data file. Valid values are:
 208 \fBaes128\fP, \fBaes192\fP, \fBaes256\fP, \fBserpent128\fP, \fBserpent192\fP,
 209 \fBserpent256\fP, \fBcamellia128\fP, \fBcamellia192\fP, \fBcamellia256\fP,
 210 \fB3des\fP, \fBcast5\fP, \fBblowfish\fP, \fBtwofish128\fP and
 211 \fBtwofish256\fP. The default is \fBaes256\fP.
 212
 213 .TP
 214 .I "iteration_progress=<integer>"
 215 After the specified number of iterations have been processed while encrypting
 216 or decrypting, a status message with the keyword \fBPROGRESS\fP will be sent
 217 to the client.  Setting to \fB0\fP, the default, disables sending these
 218 progress messages.
 219
 220 .TP
 221 .I "xfer_progress=<integer>"
 222 Commands that send data lines to the client can send the XFER status message
 223 after the specified number of bytes have been sent. The number of bytes is
 224 rounded to ASSUAN_LINELENGTH (1002).
 225
 226 .TP
 227 .I "key=<string>"
 228 The initial passphrase to use for this file. If specified in the
 229 \fBglobal\fP section then "\fBglobal\fP" is treated as a data filename and
 230 not a default for other files. Note that if a client changes the passphrase
 231 for this data file with the \fBSAVE\fP command, then this value is not
 232 modified and will need to be updated by hand.
 233
 234 .TP
 235 .I "key_file=<string>"
 236 Same as the \fBkey\fP option above but obtains the key from the specified
 237 filename with the key being on the first line of the file. Note that if the
 238 cache entry for this file gets removed then the only way to have it added
 239 again is to restart \fBpwmd\fP or to re-read the configuration file (i.e., you
 240 won't be prompted from pinentry).
 241
 242 .TP
 243 .I "compression_level=<integer>"
 244 The default compression level for data files from \fB1\fP to \fB9\fP, \fB1\fP
 245 being the fastest but least compression and \fB9\fP being the slowest but best
 246 compression. To disable compression entirely, set to \fB0\fP. The default is
 247 \fB6\fP.
 248
 249 .TP
 250 .I "zlib_bufsize=<integer>"
 251 The input and output buffer size when compressing and decompressing. This
 252 affects how often the COMPRESS and DECOMPRESS status messages are sent and
 253 also affects compression quality. The default is \fB65536\fP. Set to a higher
 254 value for larger files.
 255
 256 .TP
 257 .I "recursion_depth=<integer>"
 258 The maximum number of times to resolve a target attribute for a single element
 259 in an element path. An error is returned when this value is exceeded. The
 260 default is \fB20\fP but can be disabled by setting to \fB0\fP.
 261
 262 .TP
 263 .I "keepalive=<integer>"
 264 Sends keep alive status messages to the client every N seconds. Set to \fB0\fP
 265 to disable (not recommended). The default is \fB30\fP.
 266
 267 .SH PINENTRY
 268 .P
 269 When \fBenable_pinentry\fP is \fBtrue\fP, commands that require a key
 270 will use
 271 .BR pinentry (1)
 272 to retrieve the passphrase. Since \fBpwmd\fP is normally a daemon process, it
 273 isn't attached to any terminal. So \fBpinentry\fP needs to know where to put
 274 it's dialog box by using command line options when executed. These can be set
 275 by either using protocol commands (see COMMANDS included in the archive) or by
 276 creating a file \fI~/.pwmd/pinentry.conf\fP. When using this file, each line
 277 should contain NAME=VALUE pairs where NAME is one of:
 278 .TP
 279 .B TTYNAME
 280 The full path of the tty device.
 281
 282 .TP
 283 .B TTYTYPE
 284 The terminal type (i.e., vt100). Must be set when \fBTTYNAME\fP is set.
 285
 286 .TP
 287 .B DISPLAY
 288 If using an X11 pinentry.
 289
 290 .TP
 291 .B LC_CTYPE
 292 For internationalization.
 293
 294 .TP
 295 .B LC_MESSAGES
 296 For internationalization.
 297
 298 .TP
 299 .B PATH
 300 The full path to the pinentry binary. The default is \fI@pinentry@\fP.
 301
 302 .P
 303 The file is read only once after each client first connects. Note that if your
 304 not using a \fBDISPLAY\fP, then both \fBTTYNAME\fP and \fBTTYTYPE\fP should be
 305 set otherwise you'll get a segfault from ncurses.
 306
 307 .SH SIGNALS
 308 .TP
 309 .B SIGUSR1
 310 Clears the entire file cache. If there are any clients connected, a key will
 311 be required for the next \fBOPEN\fP or \fBSAVE\fP command.
 312 .TP
 313 .B SIGHUP
 314 Reloads the configuration file.
 315 .TP
 316 .B SIGTERM and SIGINT
 317 Disallows new connections and waits for all clients to disconnect before
 318 terminating.
 319
 320 .SH FILES
 321 .TP
 322 .B ~/.pwmd/config
 323 Default configuration file.
 324 .TP
 325 .B ~/.pwmd/data
 326 Default data directory.
 327 .TP
 328 .B ~/.pwmd/socket
 329 Default listening socket.
 330 .TP
 331 .B ~/.pwmd/log
 332 Default log file when logging is enabled.
 333 .TP
 334 .B @pinentry@
 335 Default location of the pinentry binary.
 336 .TP
 337 .B ~/.pwmd/pinentry.conf
 338 Default pinentry settings for new clients.
 339
 340 .SH AUTHOR
 341 Ben Kibbey <bjk@luxsci.net>
 342 .br
 343 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 344
 345 .SH "SEE ALSO"
 346 .BR pinentry (1)
 347
 348 Also see \fBCOMMANDS\fP included in the archive for protocol commands and
 349 syntax.