projects/pwm

view pwm.1.xml @ 20:efef93e54c5f

Automatically save the database when receiving a fatal signal
author Guido Berhoerster <guido+pwm@berhoerster.name>
date Wed Sep 06 13:56:11 2017 +0200 (2017-09-06)
parents a08ef0674d8e
children ee4d36c85287
line source
1 <?xml version="1.0"?>
2 <!--
4 Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook"
27 xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
28 <info>
29 <author>
30 <personname>
31 <firstname>Guido</firstname>
32 <surname>Berhoerster</surname>
33 </personname>
34 <email>guido+pwm@berhoerster.name</email>
35 <personblurb/>
36 </author>
37 <date>6 September, 2017</date>
38 </info>
39 <refmeta>
40 <refentrytitle>pwm</refentrytitle>
41 <manvolnum>1</manvolnum>
42 <refmiscinfo class="source"/>
43 <refmiscinfo class="version"/>
44 <refmiscinfo class="manual">User Commands</refmiscinfo>
45 </refmeta>
46 <refnamediv>
47 <refname>pwm</refname>
48 <refpurpose>password manager</refpurpose>
49 </refnamediv>
50 <refsynopsisdiv>
51 <cmdsynopsis>
52 <command>pwm</command>
53 <arg choice="opt">
54 <option>-P</option>
55 <replaceable>password_file</replaceable>
56 </arg>
57 <arg choice="opt">
58 <replaceable>database_file</replaceable>
59 </arg>
60 </cmdsynopsis>
61 </refsynopsisdiv>
62 <refsect1>
63 <title>Description</title>
64 <para>The <command>pwm</command> utility is a password manager which
65 stores passwords and associated metadata in an encrypted database protected
66 by a master password. It offers both a text-based user interface for
67 interactive use as well as a non-interactive mode. The database uses the
68 PasswordSafe database version 3 file format and thus provides
69 interoperabity with other password managers using the same format.</para>
70 <para>After opening an existing database or creating a new one,
71 <command>pwm</command> provides commands to create, modify, delete, and
72 display password database entries which may be organized in groups. The
73 contents of a field of a given entry can also be piped to an external
74 command, e.g. in order to copy the content of the username or password
75 field of an entry to the clipboard.</para>
76 <para>If specified, <command>pwm</command> will open or create
77 <replaceable>database_file</replaceable> instead of the user's default
78 database.</para>
79 <para><command>pwm</command> must be run with a locale which uses the UTF-8
80 character encoding.</para>
81 <refsect2>
82 <title>Output format</title>
83 <para>The <command>show</command> and <command>info</command> commands
84 display fields by printing the field name followed by a colon, one or
85 more space characters and the field's verbatim content to the standard
86 output stream. Field content may contain newlines, non-printable and/or
87 control characters.</para>
88 <para>If running in interactive mode, the <command>list</command>,
89 <command>show</command> and <command>info</command> will display
90 the results on a page-by-page basis using an internal pager.</para>
91 <para>The <command>pipe</command> prints the verbatim field content to the
92 standard input stream of the given command.</para>
93 <para>Error messages are printed to the standard error stream.</para>
94 </refsect2>
95 </refsect1>
96 <refsect1>
97 <title>Options</title>
98 <para>The following options are supported:</para>
99 <variablelist>
100 <varlistentry>
101 <term>
102 <option>-P</option>
103 <replaceable>password_file</replaceable>
104 </term>
105 <listitem>
106 <para>Read the master password from the first line of
107 <replaceable>password_file</replaceable>.</para>
108 </listitem>
109 </varlistentry>
110 </variablelist>
111 </refsect1>
112 <refsect1>
113 <title>Usage</title>
114 <para>If stdin is connected to a terminal pwm will run in interactive mode
115 and prompt the user for the master password unless
116 <replaceable>password_file</replaceable> is specified via the
117 <option>-P</option> option. After successfully opening the password
118 database the user will be prompted for a command.</para>
119 <para>When running in non-interactive mode a file containing the master
120 pasword must be specified via the <option>-P</option> option and after
121 successfully opening the password database, pwm will execute commands read
122 from stdin until either an error occurrs or end-of-file is reached.</para>
123 <para><command>pwm</command> operates on a copy of the password database
124 in memory, any changes must be explicitly written back to the database
125 using the write command.</para>
126 <refsect2>
127 <title>IDs</title>
128 <para>Database entries are referred to by an ID value which is a
129 positive integer value that is guaranteed to be unqiue during the run
130 time of the pwm utility.</para>
131 </refsect2>
132 <refsect2>
133 <title>Fields</title>
134 <para>The following entry fields are supported:</para>
135 <table xml:id="field-table">
136 <title>Fields and their identifiers</title>
137 <tgroup cols="2" align="left" colsep="1" rowsep="1">
138 <thead>
139 <row>
140 <entry>Field</entry>
141 <entry>Field Identifier</entry>
142 </row>
143 </thead>
144 <tbody>
145 <row>
146 <entry>Group</entry>
147 <entry>group</entry>
148 </row>
149 <row>
150 <entry>Title</entry>
151 <entry>title</entry>
152 </row>
153 <row>
154 <entry>Username</entry>
155 <entry>username</entry>
156 </row>
157 <row>
158 <entry>Password</entry>
159 <entry>password</entry>
160 </row>
161 <row>
162 <entry>Notes</entry>
163 <entry>notes</entry>
164 </row>
165 <row>
166 <entry>URL</entry>
167 <entry>url</entry>
168 </row>
169 <row>
170 <entry>Creation Time</entry>
171 <entry>ctime</entry>
172 </row>
173 <row>
174 <entry>Modification Time</entry>
175 <entry>mtime</entry>
176 </row>
177 </tbody>
178 </tgroup>
179 </table>
180 <para>Other, existing fields specified by the PasswordSafe file format
181 will be preserved but cannot be displayed or modified.</para>
182 </refsect2>
183 <refsect2>
184 <title>Commands</title>
185 <para>Each command must appear on a seperate line terminated by a newline
186 character. The command and its arguments are seperated by whitespace,
187 i.e. one or more space or tab characters. If an argument contains
188 whitespace characters it must either be quoted by encosing it in single
189 or double quote characters or each whitespace character must be preceded
190 by a backslash character. Arguments quoted with a single or double quote
191 character preserve the literal values of all characters with the
192 exception of the backslash character which can be used to escape the
193 respective quoting character. Two consecutive backslash characters yield
194 a literal backslash within both quoted and unquoted arguments. A line
195 must not end in a single backslash character, any other backslash
196 characters are ignored.</para>
197 <para>If an error occurrs while parsing or executing a command,
198 <command>pwm</command> will terminate when running in non-interactive
199 mode. In interactive mode it will print an error message and prompt the
200 user for the next command. The following commands are supported:</para>
201 <variablelist>
202 <varlistentry>
203 <term>List entries</term>
204 <listitem>
205 <cmdsynopsis>
206 <command>list</command>
207 <arg choice="opt" rep="repeat">
208 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
209 </arg>
210 </cmdsynopsis>
211 <cmdsynopsis>
212 <command>ls</command>
213 <arg choice="opt" rep="repeat">
214 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
215 </arg>
216 <sbr/>
217 </cmdsynopsis>
218 <para>List password database entries. If one or more filter
219 expressions are specified, limit the displayed entries to those
220 whose <replaceable>field</replaceable> content matches the extended
221 regular expression <replaceable>regex</replaceable>.</para>
222 </listitem>
223 </varlistentry>
224 <varlistentry>
225 <term>Create entry</term>
226 <listitem>
227 <cmdsynopsis>
228 <command>create</command>
229 <arg choice="opt" rep="repeat">
230 <replaceable>field</replaceable>=<replaceable>value</replaceable>
231 </arg>
232 </cmdsynopsis>
233 <cmdsynopsis>
234 <command>c</command>
235 <arg choice="opt" rep="repeat">
236 <replaceable>field</replaceable>=<replaceable>value</replaceable>
237 </arg>
238 <sbr/>
239 </cmdsynopsis>
240 <para>Create a new entry assigning each given
241 <replaceable>field</replaceable> to the corresponsing
242 <replaceable>value</replaceable>.</para>
243 </listitem>
244 </varlistentry>
245 <varlistentry>
246 <term>Modify entry</term>
247 <listitem>
248 <cmdsynopsis>
249 <command>modify</command>
250 <arg choice="plain">
251 <replaceable>id</replaceable>
252 </arg>
253 <arg choice="opt" rep="repeat">
254 <replaceable>field</replaceable>=<replaceable>value</replaceable>
255 </arg>
256 </cmdsynopsis>
257 <cmdsynopsis>
258 <command>m</command>
259 <arg choice="plain">
260 <replaceable>id</replaceable>
261 </arg>
262 <arg choice="opt" rep="repeat">
263 <replaceable>field</replaceable>=<replaceable>value</replaceable>
264 </arg>
265 <sbr/>
266 </cmdsynopsis>
267 <para>Modify an existing entry identified by
268 <replaceable>id</replaceable> assigning each given
269 <replaceable>field</replaceable> to the corresponsing
270 <replaceable>value</replaceable>.</para>
271 </listitem>
272 </varlistentry>
273 <varlistentry>
274 <term>Remove entry</term>
275 <listitem>
276 <cmdsynopsis>
277 <command>remove</command>
278 <arg choice="plain">
279 <replaceable>id</replaceable>
280 </arg>
281 </cmdsynopsis>
282 <cmdsynopsis>
283 <command>rm</command>
284 <arg choice="plain">
285 <replaceable>id</replaceable>
286 </arg>
287 <sbr/>
288 </cmdsynopsis>
289 <para>Remove an existing entry identified by
290 <replaceable>id</replaceable>.</para>
291 </listitem>
292 </varlistentry>
293 <varlistentry>
294 <term>Display entry fields</term>
295 <listitem>
296 <cmdsynopsis>
297 <command>show</command>
298 <arg choice="plain">
299 <replaceable>id</replaceable>
300 </arg>
301 <arg choice="opt" rep="repeat">
302 <replaceable>field</replaceable>
303 </arg>
304 </cmdsynopsis>
305 <cmdsynopsis>
306 <command>s</command>
307 <arg choice="plain">
308 <replaceable>id</replaceable>
309 </arg>
310 <arg choice="opt" rep="repeat">
311 <replaceable>field</replaceable>
312 </arg>
313 <sbr/>
314 </cmdsynopsis>
315 <para>Display each <replaceable>field</replaceable> of the entry
316 identified by <replaceable>id</replaceable>. If no field is
317 specified, display all fields except the password field.</para>
318 </listitem>
319 </varlistentry>
320 <varlistentry>
321 <term>Pipe entry fields to an external command</term>
322 <listitem>
323 <cmdsynopsis>
324 <command>pipe</command>
325 <arg choice="plain">
326 <replaceable>id</replaceable>
327 </arg>
328 <arg choice="plain" rep="repeat">
329 <replaceable>field</replaceable>
330 </arg>
331 <arg choice="plain">
332 <replaceable>command</replaceable>
333 </arg>
334 </cmdsynopsis>
335 <cmdsynopsis>
336 <command>p</command>
337 <arg choice="plain">
338 <replaceable>id</replaceable>
339 </arg>
340 <arg choice="plain" rep="repeat">
341 <replaceable>field</replaceable>
342 </arg>
343 <arg choice="plain">
344 <replaceable>command</replaceable>
345 </arg>
346 <sbr/>
347 </cmdsynopsis>
348 <para>Pipe the content of each given
349 <replaceable>field</replaceable> of the entry identified by id to
350 command which must be a single argument. The command is executed by
351 invoking the <command>sh</command> utility with the <arg>-c</arg>
352 option and <replaceable>command</replaceable> as its option
353 argument, thus special care should be applied to quoting command.
354 See the <citerefentry><refentrytitle>sh</refentrytitle>
355 <manvolnum>1</manvolnum></citerefentry> manual page for
356 details.</para>
357 </listitem>
358 </varlistentry>
359 <varlistentry>
360 <term>Create empty group</term>
361 <listitem>
362 <cmdsynopsis>
363 <command>creategroup</command>
364 <arg choice="plain">
365 <replaceable>name</replaceable>
366 </arg>
367 </cmdsynopsis>
368 <cmdsynopsis>
369 <command>cg</command>
370 <arg choice="plain">
371 <replaceable>name</replaceable>
372 </arg>
373 <sbr/>
374 </cmdsynopsis>
375 <para>Create a new empty group named
376 <replaceable>name</replaceable>.</para>
377 </listitem>
378 </varlistentry>
379 <varlistentry>
380 <term>Remove empty group</term>
381 <listitem>
382 <cmdsynopsis>
383 <command>removegroup</command>
384 <arg choice="plain">
385 <replaceable>name</replaceable>
386 </arg>
387 </cmdsynopsis>
388 <cmdsynopsis>
389 <command>rg</command>
390 <arg choice="plain">
391 <replaceable>name</replaceable>
392 </arg>
393 <sbr/>
394 </cmdsynopsis>
395 <para>Remove the empty group named
396 <replaceable>name</replaceable>.</para>
397 </listitem>
398 </varlistentry>
399 <varlistentry>
400 <term>Generate a random password</term>
401 <listitem>
402 <cmdsynopsis>
403 <command>generatepassword</command>
404 <arg choice="opt">
405 <replaceable>id</replaceable>
406 </arg>
407 <arg choice="opt">
408 len=<replaceable>n</replaceable>
409 </arg>
410 <arg choice="opt" rep="repeat">
411 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
412 </arg>
413 <arg choice="opt" rep="repeat">
414 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
415 </arg>
416 </cmdsynopsis>
417 <cmdsynopsis>
418 <command>gp</command>
419 <arg choice="opt">
420 <replaceable>id</replaceable>
421 </arg>
422 <arg choice="opt">
423 len=<replaceable>n</replaceable>
424 </arg>
425 <arg choice="opt" rep="repeat">
426 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
427 </arg>
428 <arg choice="opt" rep="repeat">
429 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
430 </arg>
431 <sbr/>
432 </cmdsynopsis>
433 <para>Randomly generate a new password according to the specified
434 constraints. The <literal>len</literal> argument sets the length of
435 the generated password to <replaceable>n</replaceable> characters.
436 The <literal>chars</literal> argument constrains the password to
437 <replaceable>n</replaceable> from the set of characters
438 <replaceable>chars</replaceable>. Similarly, the
439 <literal>charclass</literal> argument to
440 <replaceable>n</replaceable> characters from the extended regular
441 expression character class <replaceable>class</replaceable>.
442 Multiple <literal>char</literal> and <literal>charclass</literal>
443 arguments may be specified, in which case the generated passwords
444 match all of them.</para>
445 </listitem>
446 </varlistentry>
447 <varlistentry>
448 <term>Change the master password</term>
449 <listitem>
450 <cmdsynopsis>
451 <command>changepassword</command>
452 </cmdsynopsis>
453 <cmdsynopsis>
454 <command>ch</command>
455 <sbr/>
456 </cmdsynopsis>
457 <para>Change the master password.</para>
458 </listitem>
459 </varlistentry>
460 <varlistentry>
461 <term>Display help text</term>
462 <listitem>
463 <cmdsynopsis>
464 <command>help</command>
465 <arg choice="opt">
466 <replaceable>command</replaceable>
467 </arg>
468 </cmdsynopsis>
469 <cmdsynopsis>
470 <command>h</command>
471 <arg choice="opt">
472 <replaceable>command</replaceable>
473 </arg>
474 <sbr/>
475 </cmdsynopsis>
476 <para>Display a summary of all commands or usage information for
477 the specified <replaceable>command</replaceable>.</para>
478 </listitem>
479 </varlistentry>
480 <varlistentry>
481 <term>Show metadata information</term>
482 <listitem>
483 <cmdsynopsis>
484 <command>info</command>
485 </cmdsynopsis>
486 <cmdsynopsis>
487 <command>i</command>
488 <sbr/>
489 </cmdsynopsis>
490 <para>Display metadata information such as the user who last wrote
491 to the database, the time when the database was last written to,
492 and the host on which the password database was last written
493 to.</para>
494 </listitem>
495 </varlistentry>
496 <varlistentry>
497 <term>Display status messages</term>
498 <listitem>
499 <cmdsynopsis>
500 <command>status</command>
501 </cmdsynopsis>
502 <cmdsynopsis>
503 <command>t</command>
504 <sbr/>
505 </cmdsynopsis>
506 <para>Redisplay any error message from the previous command and
507 whether there are unsaved changes.</para>
508 </listitem>
509 </varlistentry>
510 <varlistentry>
511 <term>Write database</term>
512 <listitem>
513 <cmdsynopsis>
514 <command>write</command>
515 </cmdsynopsis>
516 <cmdsynopsis>
517 <command>w</command>
518 <sbr/>
519 </cmdsynopsis>
520 <para>Write all changes back to the password database.</para>
521 </listitem>
522 </varlistentry>
523 <varlistentry>
524 <term>Quit</term>
525 <listitem>
526 <cmdsynopsis>
527 <command>quit</command>
528 </cmdsynopsis>
529 <cmdsynopsis>
530 <command>q</command>
531 <sbr/>
532 </cmdsynopsis>
533 <para>Quit <command>pwm</command>. If running in interactive mode
534 and there are unsaved changes, <command>pwm</command> will not
535 terminate but display a warning message. If the quit command is
536 invoked twice consecutively, <command>pwm</command> will discard
537 unsaved changes and terminate.</para>
538 </listitem>
539 </varlistentry>
540 <varlistentry>
541 <term>Quit and discard unsaved changes</term>
542 <listitem>
543 <cmdsynopsis>
544 <command>Quit</command>
545 </cmdsynopsis>
546 <cmdsynopsis>
547 <command>Q</command>
548 <sbr/>
549 </cmdsynopsis>
550 <para>Quit <command>pwm</command> and discard any unsaved changes
551 without a warning.</para>
552 </listitem>
553 </varlistentry>
554 </variablelist>
555 </refsect2>
556 </refsect1>
557 <refsect1>
558 <title>File Format</title>
559 <para>The canonical description of the file format is included with the
560 distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
561 <manvolnum>1</manvolnum></citerefentry> utility.</para>
562 </refsect1>
563 <refsect1>
564 <title>Environment Variables</title>
565 <variablelist>
566 <varlistentry>
567 <term>
568 <literal>LANG</literal>
569 </term>
570 <term>
571 <literal>LC_ALL</literal>
572 </term>
573 <listitem>
574 <para>See <citerefentry><refentrytitle>locale</refentrytitle>
575 <manvolnum>5</manvolnum></citerefentry></para>
576 </listitem>
577 </varlistentry>
578 <varlistentry>
579 <term>
580 <literal>LOGNAME</literal>
581 </term>
582 <listitem>
583 <para>The name of the logged in user which is recorded when writing
584 the password database</para>
585 </listitem>
586 </varlistentry>
587 </variablelist>
588 </refsect1>
589 <refsect1>
590 <title>Exit Status</title>
591 <para>The following exit values are returned:</para>
592 <variablelist>
593 <varlistentry>
594 <term>0</term>
595 <listitem>
596 <para>Command successfully executed.</para>
597 </listitem>
598 </varlistentry>
599 <varlistentry>
600 <term>1</term>
601 <listitem>
602 <para>An unspecified error has occured.</para>
603 </listitem>
604 </varlistentry>
605 <varlistentry>
606 <term>2</term>
607 <listitem>
608 <para>Invalid command line options were specified.</para>
609 </listitem>
610 </varlistentry>
611 </variablelist>
612 </refsect1>
613 <refsect1>
614 <title>Asynchronous Events</title>
615 <variablelist>
616 <varlistentry>
617 <term><literal>SIGINT</literal></term>
618 <term><literal>SIGHUP</literal></term>
619 <term><literal>SIGTERM</literal></term>
620 <listitem>
621 <para>If there are changes since the database was last written and
622 <command>pwm</command> is running in interactive mode, it
623 automatically writes a copy of the current database to the file
624 <filename>~/.pwm/autosave.psafe3</filename> which may be used for
625 recovery later.</para>
626 </listitem>
627 </varlistentry>
628 </variablelist>
629 </refsect1>
630 <refsect1>
631 <title>Files</title>
632 <variablelist>
633 <varlistentry>
634 <term><filename>~/.pwm/pwm.psafe3</filename></term>
635 <listitem>
636 <para>default password database</para>
637 </listitem>
638 </varlistentry>
639 <varlistentry>
640 <term><filename>~/.pwm/autosave.psafe3</filename></term>
641 <listitem>
642 <para>automatic copy of the password database after receiving a fatal
643 signal in interactive mode</para>
644 </listitem>
645 </varlistentry>
646 </variablelist>
647 </refsect1>
648 <refsect1>
649 <title>See Also</title>
650 <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
651 <manvolnum>1</manvolnum></citerefentry>,
652 <citerefentry><refentrytitle>sh</refentrytitle>
653 <manvolnum>1</manvolnum></citerefentry>,
654 <citerefentry><refentrytitle>locale</refentrytitle>
655 <manvolnum>5</manvolnum></citerefentry>,
656 <citerefentry><refentrytitle>regex</refentrytitle>
657 <manvolnum>5</manvolnum></citerefentry>,
658 <link xlink:href="https://pwsafe.org/"/></para>
659 </refsect1>
660 </refentry>