projects/pwm

view pwm.1.xml @ 26:5bdea77d0c1d

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