# userdb

## Name

userdb -- manipulate /usr/local/etc/userdb

## Synopsis

userdb {addr} set {field=value...}

userdb {addr} unset {field...}

userdb {addr} del

userdb {path/addr} [set | unset | del] ...

userdb -f {file} {adr} [set | unset | del] ...

userdb -show {path}

userdb -show {path} {addr}

userdb -show -f {file}

userdb -show -f {file} {addr}

## DESCRIPTION

userdb is a convenient script to individually manipulate entries in `/usr/local/etc/userdb`. See makeuserdb(8) for a description of its contents. `/usr/local/etc/userdb` can always be edited using any text editor, but userdb is a convenient way to modify this file from another script.

`/usr/local/etc/userdb` can also be a subdirectory, instead of a file. Specify foo/bar/addr to manipulate addr in the file `/usr/local/etc/userdb/foo/bar`. You can also use the -f flag: -f /usr/local/etc/userdb/foo/bar is equivalent. Use whatever form makes the most sense to you.

`/usr/local/etc/userdb` must not have any group or world permissions. That's because its contents may include system passwords (depending upon the application which uses this virtual user account database).

Each line in `/usr/local/etc/userdb` takes following form:

> `addr<TAB>field=value|field=value...`

addr specifies a unique virtual address. It is followed by a single tab character, then a list of field=value pairs, separated by vertical slash characters. See makeuserdb(8) for field definitions.

A text editor can be used to add blank lines or comments in `/usr/local/etc/userdb`. Any blank lines or comments are ignored by the userdb script.

The names of the actual fields, and their contents, are defined entirely by applications that use the `/usr/local/etc/userdb` database, the userdb command just adds or removes arbitrary fields.

For example:

> userdb default/info set mail=/home/mail/info

This command accesses the address "info" in `/usr/local/etc/userdb/default`.

If the second argument to userdb is "`set`", the remaining arguments are taken as `field=value` pairs, which are added to the record for addr. If there is no record for addr, a new record will be appended to the file. If addr exists, any existing values of any specified fields are removed. If `=value` is missing, userdb stops and prompts for it. This is useful if you're setting a password field, where you do not want to specify the password on the command line, which can be seen by the ps(1) command. If userdb is being executed by a script, the value can be provided on standard input.

Use "`unset`" to delete fields from an existing record. Use "`del`" to delete all fields in the existing record, plus the record itself.

### DISPLAYING `/usr/local/etc/userdb`

If the first argument to userdb is `-show`, userdb displays the contents of `/usr/local/etc/userdb`. If `/usr/local/etc/userdb` is a subdirectory, `path` must refer to a specific file in `/usr/local/etc/userdb`. The `-f` option can be used instead of `path` in order to specify an arbitrary file.

If `addr` is not specified, userdb produces a list, on standard output, containing all addresses found in the file, on per line. If `addr` is specified, userdb produces a list, on standard output, of all the fields in `/usr/local/etc/userdb` for this `addr`.

### REBUILDING `/usr/local/etc/userdb.dat`

The actual virtual account/address database is `/usr/local/etc/userdb.dat`. This is a binary database file. /usr/local/etc/userdb is the plain text version. After running userdb, execute the makeuserdb(8) command to rebuild `/usr/local/etc/userdb.dat` for the changes to take effect.

## BUGS

`addr` must be unique. If `/usr/local/etc/userdb` is a subdirectory, it's possible to create the same `addr` in different files in the subdirectory. This is an error that is not currently detected by userdb, however the subsequent makeuserdb(8) command will fail with an error message.

## FILES

`/usr/local/etc/userdb` - plain text file, or directory of plain text files

`.lock.filename` - lock file for `filename`

`.tmp.filename` - temporary file used to create new contents of `filename`

## SEE ALSO

makeuserdb(8), userdbpw(8)