pwm — pwm(1) Manual Page

Description

The pwm utility is a password manager which stores passwords and associated metadata in an encrypted database protected by a master password. It offers both a text-based user interface for interactive use as well as a non-interactive mode. The database uses the PasswordSafe database version 3 file format and thus provides interoperabity with other password managers using the same format.

After opening an existing database or creating a new one, pwm provides commands to create, modify, delete, and display password database entries which may be organized in groups. The contents of a field of a given entry can also be piped to an external command such as the pwm-clip(1) utility in order to copy the content of the username or password field of an entry to the clipboard.

If specified, pwm will open or create database_file instead of the user's default database.

pwm must be run with a locale which uses the UTF-8 character encoding.

Output format

The show and info commands display fields by printing the field name followed by a colon, one or more space characters and the field's verbatim content to the standard output stream. Field content may contain newlines, non-printable and/or control characters.

If running in interactive mode, the list, show and info will display the results on a page-by-page basis using an internal pager.

The pipe prints the verbatim field content to the standard input stream of the given command.

Error messages are printed to the standard error stream.

Options

The following options are supported:

-P password_file: Read the master password from the first line of password_file.
-R: Treat the database as read-only and disallow any modifications and write operations.

Usage

Start-up

If stdin is connected to a terminal pwm will run in interactive mode and prompt the user for the master password unless password_file is specified via the -P option. After successfully opening the password database the user will be prompted for a command.

When running in non-interactive mode a file containing the master pasword must be specified via the -P option and after successfully opening the password database, pwm will execute commands read from stdin until either an error occurrs or end-of-file is reached.

pwm operates on a copy of the password database in memory, any changes must be explicitly written back to the database using the write command.

When starting up, before prompting the user for a master password or reading the master password from a specified file pwm will read the file ~/.pwm/pwmrc and execute any set and define commands specified therein.

Configuration Variables

pwm can be configured through configuration variables using the set command. The following configuration variables are supported:

filename: Specifies the password database file if no other file is given as a command line argument.
pipecommand: Specifies a default command which is invoked by the pipe command if not other command is explicitly specified as a argument.

IDs

Database entries are referred to by an ID value which is a positive integer value that is guaranteed to be unqiue during the run time of the pwm utility.

Fields

The following entry fields are supported:

Table 1. Fields and their identifiers

Field	Field Identifier
Group	group
Title	title
Username	username
Password	password
Notes	notes
URL	url
Creation Time	ctime
Modification Time	mtime

Other, existing fields specified by the PasswordSafe file format will be preserved but cannot be displayed or modified.

Commands

Each command must appear on a seperate line terminated by a newline character. The command and its arguments are seperated by whitespace, i.e. one or more space or tab characters. If an argument contains whitespace characters it must either be quoted by encosing it in single or double quote characters or each whitespace character must be preceded by a backslash character. Arguments quoted with a single or double quote character preserve the literal values of all characters with the exception of the backslash character which can be used to escape the respective quoting character. Two consecutive backslash characters yield a literal backslash within both quoted and unquoted arguments. A line must not end in a single backslash character, any other backslash characters are ignored.

If an error occurrs while parsing or executing a command, pwm will terminate when running in non-interactive mode. In interactive mode it will print an error message and prompt the user for the next command. The following commands are supported:

List entries

list [ field~regex ...]

ls [ field~regex ...]

List password database entries. If one or more filter expressions are specified, limit the displayed entries to those whose field content matches the extended regular expression regex.

Create entry

create [ field=value ...]

c [ field=value ...]

Create a new entry assigning each given field to the corresponsing value.

If no fields are specified in interactive mode, pwm will prompt the user for the content of each field.

Modify entry

modify id [ field=value ...]

m id [ field=value ...]

Modify an existing entry identified by id assigning each given field to the corresponsing value.

If no fields are specified and pwm is running in interactive mode, it will prompt the user for the content of each field, allowing him to edit any previous content.

Remove entry

remove id

rm id

Remove an existing entry identified by id.

Display entry fields

show id [ field ...]

s id [ field ...]

Display each field of the entry identified by id. If no field is specified, display all fields except the password field.

Pipe entry fields to an external command

pipe id field ... command

p id field ... command

Pipe the content of each given field of the entry identified by id to command which must be a single argument. The command is executed by invoking the sh utility with the [-c] option and command as its option argument, thus special care should be applied to quoting command. See the sh(1) manual page for details. The command argument is optional if the pipecommand configuration variable is set.

Create empty group

creategroup name

cg name

Create a new empty group named name.

In interactive-mode the name argument is optional, if it is not specified pwm will prompt the user for it.

Remove empty group

removegroup name

rg name

Remove the empty group named name.

Generate a random password

generatepassword [ id ] [ len=n ] [ chars=n:chars ...] [ charclass=n:class ...]

gp [ id ] [ len=n ] [ chars=n:chars ...] [ charclass=n:class ...]

Randomly generate a new password according to the specified constraints. The len argument sets the length of the generated password to n characters. The chars argument constrains the password to n from the set of characters chars. Similarly, the charclass argument to n characters from the extended regular expression character class class. Multiple char and charclass arguments may be specified, in which case the generated passwords match all of them.

Change the master password

changepassword

ch

Change the master password.

Define macro

define name=value

D name=value

Define the macro name to expand to value. A Macro is a shorthand term for a command and/or command arguments. Macros are tokenized when they are defined, thus if a macro contains other macros, these other macros are expanded once at the time the macro is defined and not each time a macro is expanded later. A macro can be used as like a command or as part of the command's argument by prefixing the macro name by a "$". It is expanded by substituting the previously tokenized contents before the command is evaluated.

Set configuration variable or display their values

set [ variable=value ]

S variable=value

If variable is specified, set the configuration variable variable to value. If no arguments are specified, display the current values of all configuration variables.

Display help text

help [ command ]

h [ command ]

Display a summary of all commands or usage information for the specified command.

Show metadata information

info

i

Display metadata information such as the user who last wrote to the database, the time when the database was last written to, and the host on which the password database was last written to.

Display status messages

status

t

Redisplay any error message from the previous command and whether there are unsaved changes.

Write database

write

w

Write all changes back to the password database.

Quit

quit

q

end-of-file

Quit pwm. If running in interactive mode and there are unsaved changes, pwm will not terminate but display a warning message. If the quit command is invoked twice consecutively, pwm will discard unsaved changes and terminate.

Quit and discard unsaved changes

Quit

Q

Quit pwm and discard any unsaved changes without a warning.

File Format

The canonical description of the file format is included with the distribution of the pwsafe(1) utility.

Environment Variables

LANG , LC_ALL: See locale(5)
LOGNAME: The name of the logged in user which is recorded when writing the password database

Exit Status

The following exit values are returned:

0: Command successfully executed.
1: An unspecified error has occured.
2: Invalid command line options were specified.

Asynchronous Events

SIGINT, SIGHUP, SIGTERM: If there are changes since the database was last written and pwm is running in interactive mode, it automatically writes a copy of the current database to the file ~/.pwm/autosave.psafe3 which may be used for recovery later.

Files

~/.pwm/pwmrc: configuration file
~/.pwm/pwm.psafe3: default password database
~/.pwm/autosave.psafe3: automatic copy of the password database after receiving a fatal signal in interactive mode

pwm(1) Manual Page

Name

Synopsis