doc/pwmd.1

   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  02111-1307  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH PWMD 1 "21 Sep 2007" "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>] [\-D] [\-b] [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 AES encrypted XML file.
  32
  33 .SH OPTIONS
  34 The following are the available command line options. Remaining arguments are
  35 files to add to the cache on startup.
  36 .TP
  37 .I "\-f rcfile"
  38 Specify an alternate configuration file. The default is \fI~/.pwmd/config\fR.
  39 .TP
  40 .I "\-I filename"
  41 Import an XML file prompting for a key to use for encryption. The encrypted
  42 data will be written to stdout.
  43 .TP
  44 .I "\-D"
  45 Disable the LIST and DUMP protocol commands.
  46 .TP
  47 .I "\-b"
  48 Run as a background process (daemonize).
  49 .TP
  50 .I "\-v"
  51 Version information.
  52 .TP
  53 .I "\-h"
  54 Help text.
  55
  56 .SH CONFIGURATION FILE
  57 Blank lines and lines beginning with '#' are ignored. Some options can be
  58 grouped together to have file specific settings. A file section is declared by
  59 surrounding the filename with braces (i.e., \fI[filename]\fP). Default options
  60 may be specified in a \fI[default]\fP section. If the first character of a
  61 string value is a tilde, it will be expanded to your home directory. First the
  62 global options:
  63 .TP
  64 .I "socket_path=<string>"
  65 Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.
  66 .TP
  67 .I "data_directory=<string>"
  68 Where
  69 .B pwmd
  70 should store and retrieve data files. The default is \fI~/.pwmd/data\fR.
  71 .TP
  72 .I "disable_mlockall=<boolean>"
  73 When set to \fBfalse\fP,
  74 .BR mlockall (2)
  75 will be called after the client connects. This will use alot more physical
  76 memory but may also be more secure. Most will probably find it overkill since
  77 the contents of all memory is cleared before being freed. Note that this
  78 doesn't affect the file cache which is always stored in RAM (if possible).
  79 .TP
  80 .I "cache_size=<integer>"
  81 Specfies the size of the file cache. Must be in multiples of your systems
  82 \fBPAGE_SIZE\fR. The default is one page.
  83 .TP
  84 .I "log_path=<string>"
  85 Logs informational messages to the specified file. The default is
  86 \fI~/.pwmd/log\fR.
  87 .TP
  88 .I "enable_logging=<boolean>"
  89 Enable or disable logging to \fIlog_path\fR. The default is \fIfalse\fR.
  90 .TP
  91 .I "cache_push=<list>"
  92 A list of filenames separated by commas that will be pushed into the file
  93 cache upon startup.
  94 .B pwmd
  95 will ask for the key for each file specified unless the key was specified with
  96 the \fBkey\fR or \fBkey_file\fR parameters in a matching file section. The
  97 default is none.
  98 .PP
  99 Below are options that can be in the \fI[default]\fP or \fI[filename]\fP
 100 section. If in both, then \fI[filename]\fP will have precedence.
 101 .TP
 102 .I "cache_timeout=<integer>"
 103 The number of seconds for the life of the cached file. If \fI-1\fP, the file
 104 is cached forever. If \fI0\fP, each time the file is opened or saved a key
 105 will be required.
 106 .TP
 107 .I "iterations=<integer>"
 108 The number of times to encrypt the data. A value of 10000 or more will make
 109 dictionary attacks very slow depending on the CPU. The default is \fI0\fP.
 110 .TP
 111 .I "iteration_progress=<integer>"
 112 After the specified number of iterations while encrypting or decrypting, a
 113 status message with the keyword \fBPROGRESS\fP will be sent to the client.
 114 Setting to \fI0\fP, the default, disables sending progress messages.
 115 .TP
 116 .I "key=<string>"
 117 The initial key to use for this file. If specified in the \fI[default]\fP
 118 section then "\fIdefault\fP" is treated as a filename and not a default for
 119 other files.
 120 .TP
 121 .I "key_file=<string>"
 122 Same as above but obtain the key from the specified filename with the key
 123 being on the first line of the file.
 124 .TP
 125 .I "compression_level=<integer>"
 126 The default compression level for data files from \fI1\fP to \fI9\fP, \fI1\fP
 127 being the fastest but least compression and \fI9\fP being the slowest but best
 128 compression. To disable compression entirely, set to \fI0\fP. The default is
 129 \fI6\fP.
 130 .TP
 131 .I "zlib_bufsize=<integer>"
 132 The input and output buffer size when compressing and decompressing. This
 133 affects how often the COMPRESS and DECOMPRESS status messages are sent and
 134 also affects compression quality. The default is \fB4096\fP. Set to a higher
 135 value for larger files.
 136 .TP
 137 .I "recursion_depth=<integer>"
 138 The maximum number of times to resolve a target attribute for a single element
 139 in an element path. An error is returned when this value is exceeded. The
 140 default is \fI20\fP but can be disabled by setting to \fI0\fP.
 141 .SH SIGNALS
 142 .TP
 143 .B SIGHUP
 144 Clears the entire file cache. If there are any clients connected, a key will
 145 be required for the next \fBOPEN\fP or \fBSAVE\fP command.
 146 .TP
 147 .B SIGUSR1
 148 Reloads the configuration file.
 149
 150 .SH FILES
 151 .TP
 152 .B ~/.pwmd/config
 153 Default configuration file.
 154 .TP
 155 .B ~/.pwmd/data
 156 Default data directory.
 157 .TP
 158 .B ~/.pwmd/socket
 159 Default listening socket.
 160 .TP
 161 .B ~/.pwmd/log
 162 Default log file when logging is enabled.
 163 .TP
 164 .B /dev/shm/pwmd.<uid>
 165 On Linux, and maybe other systems, where the file cache is stored for the
 166 duration of the daemon. If your
 167 .BR mmap (2)
 168 supports MAP_ANONYMOUS with MAP_SHARED then no file will need to be created.
 169
 170 .SH AUTHOR
 171 Ben Kibbey <bjk@luxsci.net>
 172 .br
 173 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 174
 175 .SH "SEE ALSO"
 176 .BR shm_open (2),
 177 .BR mlock (2),
 178 .BR mlockall (2),
 179 .BR libxml (3) ,
 180 .BR mmap (2)
 181
 182 Also see \fBCOMMANDS\fP included in the archive for protocol commands.