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.
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.
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
15 \\$2 \(laURL: \\$1 \(ra\\$3
17 .if \n[.g] .mso www.tmac
18 .TH PWMD 1 "15 Nov 2008" "Password Manager Daemon" "Password Manager Daemon"
21 pwmd \- a universal data server
24 [\-hvDnP] [\-f <rcfile>] [\-I <filename> [\-i <iterations>] [\-k <keyfile>]
25 \-o <filename>] [\-C <filename> \-o <filename>] [file] [...]
29 is a daemon/server that serves clients data which is stored in a, optionally
30 encrypted and compressed, XML data file. Clients connect and send commands
31 that either retrieve or store data.
34 The following are the available command line options. Remaining arguments are
35 files to add to the cache on startup.
38 Specify an alternate configuration file. The default is \fI~/.pwmd/config\fR.
40 .I "\-I filename \-o 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 \fIiterations\fP configuration
44 parameter or the \fI\-i\fP command line switch), you will be prompted for a
45 passphrase to encrypt with. The output is written to the filename specified
46 with the \fI\-o\fP command line switch which should then be placed in the
47 configured \fIdata_directory\fP.
50 The number of encryption iterations to use when importing. When not specified,
51 the \fIiterations\fP configuration option from the \fIglobal\fP section will
55 When importing, obtain the key from the specified filename. Only the first
56 line is read from this file. Be sure to set \fIkey_file\fP in your
59 .I "\-C filename \-o filename"
60 Converts a \fBpwmd\fP version 1 data file to a version 2 data file. If
61 encrypted, you will be prompted for a passphrase to use for decryption. The
62 converted data file will be saved to the filename specified with the \fI-o\fP
63 command line switch and with the same passphrase and iterations as the
67 Disable the LIST and DUMP protocol commands.
70 Run as a foreground process.
75 support. Overrides and configuration setting.
83 .SH CONFIGURATION FILE
84 Blank lines and lines beginning with '#' are ignored. Some options can be
85 grouped together to have file specific settings. A file section is declared by
86 surrounding the filename with braces (i.e., \fI[filename]\fP). Global options
87 may be specified in a \fI[global]\fP section and are the defaults for other
88 file sections. If the first character of a string value is a tilde, it will be
89 expanded to your home directory. First the global options:
91 .I "socket_path=<string>"
92 Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.
94 .I "socket_perms=<integer>"
95 Permissions to set after creating the socket. This will override any
99 .I "enable_tcp=<boolean>"
100 Whether to enable TCP server support. The default is \fIdisabled\fP. See
101 \fBTCP SUPPORT\fP below.
103 .I "tcp_port=<integer>"
104 The port to listen on when \fIenable_tcp\fP is \fItrue\fP. The default is
107 .I "tcp_interface=<string>"
108 Only useful when run as root.
110 .I "tcp_access=[!]<string>"
111 A comma separated list of client x509 certificate fingerprints in MD5 format
112 that will be allowed to open a file. If prefixed with \fB!\fP, access is
113 denied for the specified certificate. The access control is used in the OPEN
114 command for the specified filename. This option can be in either the
115 \fBglobal\fP section or a defined \fBfilename\fP section. If not found in
116 either then access will be granted. If defined but empty then access will be
119 .I "tcp_require_key=<boolean>"
120 Require the client to provide the key to open a file even if the file is
121 cached. The default is \fIfalse\fP.
123 .I "tcp_wait=<integer>"
124 The time in tenths of a second to wait for a new connection. The default is
125 \fB3\fP. Setting to \fB0\fP will disable waiting.
127 .I "data_directory=<string>"
130 should store and retrieve data files. The default is \fI~/.pwmd/data\fR.
132 .I "disable_mlockall=<boolean>"
133 When set to \fBfalse\fP,
135 will be called after the client connects. This will use alot more physical
136 memory but may also be more secure. Most will probably find it overkill since
137 the contents of all memory is cleared before being freed. Note that this
138 doesn't affect the file cache which is always stored in RAM (if possible).
140 .I "cache_size=<integer>"
141 Specfies the size of the file cache. Must be in multiples of your systems
142 \fBPAGE_SIZE\fR. The default is one page.
144 .I "log_path=<string>"
145 Logs informational messages to the specified file. The default is
148 .I "enable_logging=<boolean>"
149 Enable or disable logging to \fIlog_path\fR. The default is \fIfalse\fR.
151 .I "syslog=<boolean>"
154 with facility LOG_DAEMON and priority LOG_INFO. The default is \fIfalse\fR.
156 .I "cache_push=<list>"
157 A list of filenames separated by commas that will be pushed into the file
160 will ask for the key for each file specified unless the key was specified with
161 the \fBkey\fR or \fBkey_file\fR parameters in a matching file section. The
164 .I "priority=<integer>"
165 The priority, or niceness, of the server. The default is inherited from the
168 Below are options that can be in the \fI[global]\fP or \fI[filename]\fP
169 section. If in both then \fI[filename]\fP will have precedence.
171 .I "backup=<boolean>"
172 Whether a backup of the data file should be kept when saving. The default is
173 \fItrue\fP. The backup filename has the .backup extension appended to the
176 .I "cache_timeout=<integer>"
177 The number of seconds for the life of the cached file. If \fI-1\fP, the file
178 is cached forever. If \fI0\fP, each time the file is opened or saved a key
181 .I "enable_pinentry=<boolean>"
182 If \fIfalse\fP, disable the use of
184 The default is \fItrue\fP. Also see \fBPINENTRY\fP below.
186 .I "pinentry_timeout=<integer>"
187 The number of seconds before the pinentry dialog will terminate while waiting
188 for a password. Set to \fI0\fP to wait forever.
190 .I "iterations=<integer>"
191 The number of times to encrypt the data. A value of 10000 or more will make
192 dictionary attacks very slow depending on the CPU. The default is \fI0\fP
193 which is really 1 iteration (data file compatibility bug). Setting to \fI-1\fP
194 will disable encryption.
196 .I "iteration_progress=<integer>"
197 After the specified number of iterations while encrypting or decrypting, a
198 status message with the keyword \fBPROGRESS\fP will be sent to the client.
199 Setting to \fI0\fP, the default, disables sending progress messages.
202 The initial key to use for this file. If specified in the \fI[global]\fP
203 section then "\fIglobal\fP" is treated as a filename and not a default for
204 other files. Note that if a client changes the key this value is not modified
205 and will need to be updated by hand.
207 .I "key_file=<string>"
208 Same as above but obtain the key from the specified filename with the key
209 being on the first line of the file. Note that if you change the key when
210 connected this value is not modified and will need to be updated by hand.
212 .I "compression_level=<integer>"
213 The default compression level for data files from \fI1\fP to \fI9\fP, \fI1\fP
214 being the fastest but least compression and \fI9\fP being the slowest but best
215 compression. To disable compression entirely, set to \fI0\fP. The default is
218 .I "zlib_bufsize=<integer>"
219 The input and output buffer size when compressing and decompressing. This
220 affects how often the COMPRESS and DECOMPRESS status messages are sent and
221 also affects compression quality. The default is \fB65536\fP. Set to a higher
222 value for larger files.
224 .I "recursion_depth=<integer>"
225 The maximum number of times to resolve a target attribute for a single element
226 in an element path. An error is returned when this value is exceeded. The
227 default is \fI20\fP but can be disabled by setting to \fI0\fP.
229 .I "keepalive=<integer>"
230 Sends keep alive status messages to the client every N seconds. Set to \fI0\fP
231 to disable. The default is \fI5\fP.
235 When \fIenable_pinentry\fP is \fBtrue\fP, commands that require a key that
236 isn't cached or specified with the command, will use
238 to retrieve the passphrase. Since \fBpwmd\fP is a daemon process, it isn't
239 attached to any terminal. So \fBpinentry\fP needs to know where to put it's
240 dialog box by using command line options when executed. These can be set by
241 either using protocol commands (see COMMANDS included in the archive) or by
242 creating a file \fI~/.pwmd/pinentry.conf\fP. When using the file, each line should
243 contain NAME=VALUE pairs where NAME is one of:
246 The full path of the tty device.
249 The terminal type (i.e., vt100).
252 If using an X11 pinentry.
255 The full path to the pinentry binary. The default is \fI@pinentry@\fP.
257 The file is read only once after each client first connects. Note that if your
258 not using a \fBDISPLAY\fP, then both \fBTTYNAME\fP and \fBTTYTYPE\fP should be
259 set otherwise you'll get a segfault from ncurses.
262 When compiled with TCP support and \fIenable_tcp\fP is \fItrue\fP, \fBpwmd\fP
263 can accept connections from remote hosts. Authentication is done with X509
264 certificates. The server certificate should be signed by a certificate
265 authority (CA), which will probably be a locally generated one (see the
267 documentation for how to do this). When a client connects, \fBpwmd\fP
268 will require the client to send a certificate that was signed by the same
269 certificate authority that was used to sign the \fBpwmd\fP server certificate
270 (\fB~/.pwmd/ca-cert.pem\fP). After the client certificate is validated,
271 \fBpwmd\fP will accept commands from the client.
276 Clears the entire file cache. If there are any clients connected, a key will
277 be required for the next \fBOPEN\fP or \fBSAVE\fP command.
280 Reloads the configuration file.
282 .B SIGTERM and SIGINT
283 Disallows new connections and waits for all clients to disconnect before
289 Default configuration file.
292 Default data directory.
295 Default listening socket.
298 Default log file when logging is enabled.
301 Default location of the pinentry binary.
303 .B ~/.pwmd/pinentry.conf
304 Default pinentry settings for new clients.
306 .B ~/.pwmd/ca-cert.pem
307 The certificate authority (CA) than was used to sign the server (and client)
310 .B ~/.pwmd/server-cert.pem
311 The pwmd server certificate. This is sent to the client. Clients should check
312 the validity of it to ensure that the \fBpwmd\fP server hasn't been hijacked.
314 .B ~/.pwmd/server-key.pem
315 The key that was used to sign the server certificate.
318 Ben Kibbey <bjk@luxsci.net>
320 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
330 Also see \fBCOMMANDS\fP included in the archive for protocol commands and