Mercurial > projects > pwm

comparison pwm.1.xml @ 1:55281f14dc9b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add README file and manpage
author Guido Berhoerster <guido+pwm@berhoerster.name>
date Fri, 03 Feb 2017 16:11:58 +0100
parents
children 17fb30016e64
comparison
equal deleted inserted replaced
0:a7e41e1a79c8 1:55281f14dc9b
1 <?xml version="1.0"?>
2 <!--
3
4 Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
5
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:
13
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
16
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.
24
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>3 February, 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> command displays selected fields by
84 printing the field name followed by a colon, one or more space characters
85 and the field's verbatim content to the standard output stream. Field
86 values may contain newlines, non-printable and/or control
87 characters.</para>
88 <para>The <command>pipe</command> prints the verbatim field content to the
89 standard input stream of the given command.</para>
90 <para>Error messages are printed to the standard error stream.</para>
91 </refsect2>
92 </refsect1>
93 <refsect1>
94 <title>Options</title>
95 <para>The following options are supported:</para>
96 <variablelist>
97 <varlistentry>
98 <term>
99 <option>-P</option>
100 <replaceable>password_file</replaceable>
101 </term>
102 <listitem>
103 <para>Read the master password from the first line of
104 <replaceable>password_file</replaceable>.</para>
105 </listitem>
106 </varlistentry>
107 </variablelist>
108 </refsect1>
109 <refsect1>
110 <title>Usage</title>
111 <para>If stdin is connected to a terminal pwm will run in interactive mode
112 and prompt the user for the master password unless
113 <replaceable>password_file</replaceable> is specified via the
114 <option>-P</option> option. After successfully opening the password
115 database the user will be prompted for a command.</para>
116 <para>When running in non-interactive mode a file containing the master
117 pasword must be specified via the <option>-P</option> option and after
118 successfully opening the password database, pwm will execute commands read
119 from stdin until either an error occurrs or end-of-file is reached.</para>
120 <para><command>pwm</command> operates on a copy of the password database
121 in memory, any changes must be explicitly written back to the database
122 using the write command.</para>
123 <refsect2>
124 <title>IDs</title>
125 <para>Database entries are referred to by an ID value which is a
126 positive integer value that is guaranteed to be unqiue during the run
127 time of the pwm utility.</para>
128 </refsect2>
129 <refsect2>
130 <title>Fields</title>
131 <para>The following entry fields are supported:
132 <simplelist type="vert">
133 <member>group</member>
134 <member>title</member>
135 <member>username</member>
136 <member>password</member>
137 <member>notes</member>
138 <member>url</member>
139 </simplelist>
140 </para>
141 <para>Other, existing fields specified by the PasswordSafe file format
142 will be preserved but cannot be displayed or modified.</para>
143 </refsect2>
144 <refsect2>
145 <title>Commands</title>
146 <para>Each command must appear on a seperate line terminated by a newline
147 character. The command and its arguments are seperated by whitespace,
148 i.e. one or more space or tab characters. If an argument contains
149 whitespace characters it must either be quoted by encosing it in single
150 or double quote characters or each whitespace character must be preceded
151 by a backslash character. Arguments quoted with a single or double quote
152 character preserve the literal values of all characters with the
153 exception of the backslash character which can be used to escape the
154 respective quoting character. Two consecutive backslash characters yield
155 a literal backslash within both quoted and unquoted arguments. A line
156 must not end in a single backslash character, any other backslash
157 characters are ignored.</para>
158 <para>If an error occurrs while parsing or executing a command,
159 <command>pwm</command> will terminate when running in non-interactive
160 mode. In interactive mode it will print an error message and prompt the
161 user for the next command. The following commands are supported:</para>
162 <variablelist>
163 <varlistentry>
164 <term>List entries</term>
165 <listitem>
166 <cmdsynopsis>
167 <command>list</command>
168 </cmdsynopsis>
169 <cmdsynopsis>
170 <command>ls</command>
171 <sbr/>
172 </cmdsynopsis>
173 <para>List all password database entries.</para>
174 </listitem>
175 </varlistentry>
176 <varlistentry>
177 <term>Create entry</term>
178 <listitem>
179 <cmdsynopsis>
180 <command>create</command>
181 <arg choice="opt" rep="repeat">
182 <replaceable>field</replaceable>=<replaceable>value</replaceable>
183 </arg>
184 </cmdsynopsis>
185 <cmdsynopsis>
186 <command>c</command>
187 <arg choice="opt" rep="repeat">
188 <replaceable>field</replaceable>=<replaceable>value</replaceable>
189 </arg>
190 <sbr/>
191 </cmdsynopsis>
192 <para>Create a new entry assigning each given
193 <replaceable>field</replaceable> to the corresponsing
194 <replaceable>value</replaceable>.</para>
195 </listitem>
196 </varlistentry>
197 <varlistentry>
198 <term>Modify entry</term>
199 <listitem>
200 <cmdsynopsis>
201 <command>modify</command>
202 <arg choice="plain">
203 <replaceable>id</replaceable>
204 </arg>
205 <arg choice="opt" rep="repeat">
206 <replaceable>field</replaceable>=<replaceable>value</replaceable>
207 </arg>
208 </cmdsynopsis>
209 <cmdsynopsis>
210 <command>m</command>
211 <arg choice="plain">
212 <replaceable>id</replaceable>
213 </arg>
214 <arg choice="opt" rep="repeat">
215 <replaceable>field</replaceable>=<replaceable>value</replaceable>
216 </arg>
217 <sbr/>
218 </cmdsynopsis>
219 <para>Modify an existing entry identified by
220 <replaceable>id</replaceable> assigning each given
221 <replaceable>field</replaceable> to the corresponsing
222 <replaceable>value</replaceable>.</para>
223 </listitem>
224 </varlistentry>
225 <varlistentry>
226 <term>Remove entry</term>
227 <listitem>
228 <cmdsynopsis>
229 <command>remove</command>
230 <arg choice="plain">
231 <replaceable>id</replaceable>
232 </arg>
233 </cmdsynopsis>
234 <cmdsynopsis>
235 <command>rm</command>
236 <arg choice="plain">
237 <replaceable>id</replaceable>
238 </arg>
239 <sbr/>
240 </cmdsynopsis>
241 <para>Remove an existing entry identified by
242 <replaceable>id</replaceable>.</para>
243 </listitem>
244 </varlistentry>
245 <varlistentry>
246 <term>Display entry fields</term>
247 <listitem>
248 <cmdsynopsis>
249 <command>show</command>
250 <arg choice="plain">
251 <replaceable>id</replaceable>
252 </arg>
253 <arg choice="opt" rep="repeat">
254 <replaceable>field</replaceable>
255 </arg>
256 </cmdsynopsis>
257 <cmdsynopsis>
258 <command>s</command>
259 <arg choice="plain">
260 <replaceable>id</replaceable>
261 </arg>
262 <arg choice="opt" rep="repeat">
263 <replaceable>field</replaceable>
264 </arg>
265 <sbr/>
266 </cmdsynopsis>
267 <para>Display each <replaceable>field</replaceable> of the entry
268 identified by <replaceable>id</replaceable>.</para>
269 </listitem>
270 </varlistentry>
271 <varlistentry>
272 <term>Pipe entry fields to an external command</term>
273 <listitem>
274 <cmdsynopsis>
275 <command>pipe</command>
276 <arg choice="plain">
277 <replaceable>id</replaceable>
278 </arg>
279 <arg choice="plain" rep="repeat">
280 <replaceable>field</replaceable>
281 </arg>
282 <arg choice="plain">
283 <replaceable>command</replaceable>
284 </arg>
285 </cmdsynopsis>
286 <cmdsynopsis>
287 <command>p</command>
288 <arg choice="plain">
289 <replaceable>id</replaceable>
290 </arg>
291 <arg choice="plain" rep="repeat">
292 <replaceable>field</replaceable>
293 </arg>
294 <arg choice="plain">
295 <replaceable>command</replaceable>
296 </arg>
297 <sbr/>
298 </cmdsynopsis>
299 <para>Pipe the content of each given
300 <replaceable>field</replaceable> of the entry identified by id to
301 command which must be a single argument. The command is executed by
302 invoking the <command>sh</command> utility with the <arg>-c</arg>
303 option and <replaceable>command</replaceable> as its option
304 argument, thus special care should be applied to quoting command.
305 See the <citerefentry><refentrytitle>sh</refentrytitle>
306 <manvolnum>1</manvolnum></citerefentry> manual page for
307 details.</para>
308 </listitem>
309 </varlistentry>
310 <varlistentry>
311 <term>Create empty group</term>
312 <listitem>
313 <cmdsynopsis>
314 <command>creategroup</command>
315 <arg choice="plain">
316 <replaceable>name</replaceable>
317 </arg>
318 </cmdsynopsis>
319 <cmdsynopsis>
320 <command>cg</command>
321 <arg choice="plain">
322 <replaceable>name</replaceable>
323 </arg>
324 <sbr/>
325 </cmdsynopsis>
326 <para>Create a new empty group named
327 <replaceable>name</replaceable>.</para>
328 </listitem>
329 </varlistentry>
330 <varlistentry>
331 <term>Remove empty group</term>
332 <listitem>
333 <cmdsynopsis>
334 <command>removegroup</command>
335 <arg choice="plain">
336 <replaceable>name</replaceable>
337 </arg>
338 </cmdsynopsis>
339 <cmdsynopsis>
340 <command>rg</command>
341 <arg choice="plain">
342 <replaceable>name</replaceable>
343 </arg>
344 <sbr/>
345 </cmdsynopsis>
346 <para>Remove the empty group named
347 <replaceable>name</replaceable>.</para>
348 </listitem>
349 </varlistentry>
350 <varlistentry>
351 <term>Change the master password</term>
352 <listitem>
353 <cmdsynopsis>
354 <command>changepassword</command>
355 </cmdsynopsis>
356 <cmdsynopsis>
357 <command>ch</command>
358 <sbr/>
359 </cmdsynopsis>
360 <para>Change the master password.</para>
361 </listitem>
362 </varlistentry>
363 <varlistentry>
364 <term>Display help text</term>
365 <listitem>
366 <cmdsynopsis>
367 <command>help</command>
368 </cmdsynopsis>
369 <cmdsynopsis>
370 <command>h</command>
371 <sbr/>
372 </cmdsynopsis>
373 <para>Display a list of all commands and a short help text.</para>
374 </listitem>
375 </varlistentry>
376 <varlistentry>
377 <term>Write database</term>
378 <listitem>
379 <cmdsynopsis>
380 <command>write</command>
381 </cmdsynopsis>
382 <cmdsynopsis>
383 <command>w</command>
384 <sbr/>
385 </cmdsynopsis>
386 <para>Write all changes back to the password database.</para>
387 </listitem>
388 </varlistentry>
389 <varlistentry>
390 <term>Quit</term>
391 <listitem>
392 <cmdsynopsis>
393 <command>quit</command>
394 </cmdsynopsis>
395 <cmdsynopsis>
396 <command>q</command>
397 <sbr/>
398 </cmdsynopsis>
399 <para>Quit <command>pwm</command>.</para>
400 </listitem>
401 </varlistentry>
402 </variablelist>
403 </refsect2>
404 </refsect1>
405 <refsect1>
406 <title>File Format</title>
407 <para>The canonical description of the file format is included with the
408 distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
409 <manvolnum>1</manvolnum></citerefentry> utility.</para>
410 </refsect1>
411 <refsect1>
412 <title>Environment Variables</title>
413 <variablelist>
414 <varlistentry>
415 <term>
416 <literal>LANG</literal>
417 </term>
418 <term>
419 <literal>LC_ALL</literal>
420 </term>
421 <listitem>
422 <para>See <citerefentry><refentrytitle>locale</refentrytitle>
423 <manvolnum>5</manvolnum></citerefentry></para>
424 </listitem>
425 </varlistentry>
426 </variablelist>
427 </refsect1>
428 <refsect1>
429 <title>Exit Status</title>
430 <para>The following exit values are returned:</para>
431 <variablelist>
432 <varlistentry>
433 <term>0</term>
434 <listitem>
435 <para>Command successfully executed.</para>
436 </listitem>
437 </varlistentry>
438 <varlistentry>
439 <term>1</term>
440 <listitem>
441 <para>An unspecified error has occured.</para>
442 </listitem>
443 </varlistentry>
444 <varlistentry>
445 <term>2</term>
446 <listitem>
447 <para>Invalid command line options were specified.</para>
448 </listitem>
449 </varlistentry>
450 </variablelist>
451 </refsect1>
452 <refsect1>
453 <title>Files</title>
454 <variablelist>
455 <varlistentry>
456 <term><filename>~/.pwm/pwm.psafe3</filename></term>
457 <listitem>
458 <para>default password database</para>
459 </listitem>
460 </varlistentry>
461 </variablelist>
462 </refsect1>
463 <refsect1>
464 <title>See Also</title>
465 <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
466 <manvolnum>1</manvolnum></citerefentry>,
467 <citerefentry><refentrytitle>sh</refentrytitle>
468 <manvolnum>1</manvolnum></citerefentry>,
469 <citerefentry><refentrytitle>locale</refentrytitle>
470 <manvolnum>5</manvolnum></citerefentry>,
471 <link xlink:href="https://pwsafe.org/"/></para>
472 </refsect1>
473 </refentry>