xref: /freebsd/usr.sbin/pwd_mkdb/pwd_mkdb.8 (revision 3467ce29b4485b5318e7efac187cfb7ec0c91aea)
1dea673e9SRodney W. Grimes.\" Copyright (c) 1991, 1993
2dea673e9SRodney W. Grimes.\"	The Regents of the University of California.  All rights reserved.
3dea673e9SRodney W. Grimes.\"
4dea673e9SRodney W. Grimes.\" Redistribution and use in source and binary forms, with or without
5dea673e9SRodney W. Grimes.\" modification, are permitted provided that the following conditions
6dea673e9SRodney W. Grimes.\" are met:
7dea673e9SRodney W. Grimes.\" 1. Redistributions of source code must retain the above copyright
8dea673e9SRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer.
9dea673e9SRodney W. Grimes.\" 2. Redistributions in binary form must reproduce the above copyright
10dea673e9SRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer in the
11dea673e9SRodney W. Grimes.\"    documentation and/or other materials provided with the distribution.
12fbbd9655SWarner Losh.\" 3. Neither the name of the University nor the names of its contributors
13dea673e9SRodney W. Grimes.\"    may be used to endorse or promote products derived from this software
14dea673e9SRodney W. Grimes.\"    without specific prior written permission.
15dea673e9SRodney W. Grimes.\"
16dea673e9SRodney W. Grimes.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17dea673e9SRodney W. Grimes.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18dea673e9SRodney W. Grimes.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19dea673e9SRodney W. Grimes.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20dea673e9SRodney W. Grimes.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21dea673e9SRodney W. Grimes.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22dea673e9SRodney W. Grimes.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23dea673e9SRodney W. Grimes.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24dea673e9SRodney W. Grimes.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25dea673e9SRodney W. Grimes.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26dea673e9SRodney W. Grimes.\" SUCH DAMAGE.
27dea673e9SRodney W. Grimes.\"
28*3467ce29SJens Schweikhardt.Dd April 19, 2025
29dea673e9SRodney W. Grimes.Dt PWD_MKDB 8
30dea673e9SRodney W. Grimes.Os
31dea673e9SRodney W. Grimes.Sh NAME
32dea673e9SRodney W. Grimes.Nm pwd_mkdb
33dea673e9SRodney W. Grimes.Nd "generate the password databases"
34dea673e9SRodney W. Grimes.Sh SYNOPSIS
35e97407b4SRuslan Ermilov.Nm
368e1887faSEd Maste.Op Fl CiNp
37fb0e6accSGary Palmer.Op Fl d Ar directory
38e6bb224eSPoul-Henning Kamp.Op Fl s Ar cachesize
39dfacdfe9SMike Pritchard.Op Fl u Ar username
40dea673e9SRodney W. Grimes.Ar file
41dea673e9SRodney W. Grimes.Sh DESCRIPTION
42490d5836SPhilippe CharnierThe
43490d5836SPhilippe Charnier.Nm
44490d5836SPhilippe Charnierutility creates
45dea673e9SRodney W. Grimes.Xr db 3
46dea673e9SRodney W. Grimesstyle secure and insecure databases for the specified file.
47dea673e9SRodney W. GrimesThese databases are then installed into
488b76e1d7SPhilippe Charnier.Pa /etc/spwd.db
49dea673e9SRodney W. Grimesand
508b76e1d7SPhilippe Charnier.Pa /etc/pwd.db
51dea673e9SRodney W. Grimesrespectively.
52dea673e9SRodney W. GrimesThe file is installed into
538b76e1d7SPhilippe Charnier.Pa /etc/master.passwd .
54dea673e9SRodney W. GrimesThe file must be in the correct format (see
55dea673e9SRodney W. Grimes.Xr passwd 5 ) .
56dea673e9SRodney W. GrimesIt is important to note that the format used in this system is
57dea673e9SRodney W. Grimesdifferent from the historic Version 7 style format.
58dea673e9SRodney W. Grimes.Pp
59dea673e9SRodney W. GrimesThe options are as follows:
60dea673e9SRodney W. Grimes.Bl -tag -width flag
61d7f71209SWolfram Schneider.It Fl C
62f2e366a1SSheldon HearnCheck if the password file is in the correct format.
63f2e366a1SSheldon HearnDo not
64e2ab8bacSWolfram Schneiderchange, add, or remove any files.
65508aee96SDag-Erling Smørgrav.It Fl d Ar directory
66508aee96SDag-Erling SmørgravStore databases into specified destination directory instead of
67508aee96SDag-Erling Smørgrav.Pa /etc .
68508aee96SDag-Erling Smørgrav.It Fl i
69508aee96SDag-Erling SmørgravIgnore locking failure of the
70508aee96SDag-Erling Smørgrav.Pa master.passwd
71508aee96SDag-Erling Smørgravfile.
72508aee96SDag-Erling SmørgravThis option is intended to be used to build password files in
73508aee96SDag-Erling Smørgravthe release process over NFS where no contention can happen.
74508aee96SDag-Erling SmørgravA non-default directory must also be specified with the
75508aee96SDag-Erling Smørgrav.Fl d
76508aee96SDag-Erling Smørgravoption for locking to be ignored.
77508aee96SDag-Erling SmørgravOther use of this option is strongly discouraged.
78be648216SMatthew Dillon.It Fl N
79be648216SMatthew DillonTell
8008a92bd8SDima Dorfman.Nm
8107bfccd7SRuslan Ermilovto exit with an error if it cannot obtain a lock on the file.
8207bfccd7SRuslan ErmilovBy default,
8307bfccd7SRuslan Ermilovwe block waiting for a lock on the source file.
8407bfccd7SRuslan ErmilovThe lock is held through
85be648216SMatthew Dillonthe rebuilding of the database.
86dea673e9SRodney W. Grimes.It Fl p
87dea673e9SRodney W. GrimesCreate a Version 7 style password file and install it into
888b76e1d7SPhilippe Charnier.Pa /etc/passwd .
89e6bb224eSPoul-Henning Kamp.It Fl s Ar cachesize
90e6bb224eSPoul-Henning KampSpecify in megabytes the size of the memory cache used by the
9107bfccd7SRuslan Ermilovhashing library.
9207bfccd7SRuslan ErmilovOn systems with a large user base, a small cache
93e6bb224eSPoul-Henning Kampsize can lead to prohibitively long database file rebuild times.
94e6bb224eSPoul-Henning KampAs a rough guide, the memory usage of
95e97407b4SRuslan Ermilov.Nm
96e6bb224eSPoul-Henning Kampin megabytes will be a little bit more than twice the figure
9707bfccd7SRuslan Ermilovspecified here.
9807bfccd7SRuslan ErmilovThe default is 2 megabytes.
99508aee96SDag-Erling Smørgrav.It Fl u Ar username
100508aee96SDag-Erling SmørgravOnly update the record for the specified user.
101508aee96SDag-Erling SmørgravUtilities that
102508aee96SDag-Erling Smørgravoperate on a single user can use this option to avoid the
103508aee96SDag-Erling Smørgravoverhead of rebuilding the entire database.
104dea673e9SRodney W. Grimes.El
105dea673e9SRodney W. Grimes.Pp
106dea673e9SRodney W. GrimesThe two databases differ in that the secure version contains the user's
107dea673e9SRodney W. Grimesencrypted password and the insecure version has an asterisk (``*'')
108dea673e9SRodney W. Grimes.Pp
109dea673e9SRodney W. GrimesThe databases are used by the C library password routines (see
110dea673e9SRodney W. Grimes.Xr getpwent 3 ) .
111dea673e9SRodney W. Grimes.Pp
112490d5836SPhilippe CharnierThe
113490d5836SPhilippe Charnier.Nm
114490d5836SPhilippe Charnierutility exits zero on success, non-zero on failure.
1159a602accSSheldon Hearn.Sh ENVIRONMENT
1169a602accSSheldon HearnIf the
1179a602accSSheldon Hearn.Ev PW_SCAN_BIG_IDS
1189a602accSSheldon Hearnenvironment variable is set,
1199a602accSSheldon Hearn.Nm
1209a602accSSheldon Hearnwill suppress the warning messages that are
1219a602accSSheldon Hearnnormally generated for large user and group IDs.
1229a602accSSheldon HearnSuch IDs can cause serious problems with software
1239a602accSSheldon Hearnthat makes assumptions about the values of IDs.
124dea673e9SRodney W. Grimes.Sh FILES
125dea673e9SRodney W. Grimes.Bl -tag -width Pa -compact
126fb0e6accSGary Palmer.It Pa /etc/pwd.db
127dea673e9SRodney W. GrimesThe insecure password database file.
128fb0e6accSGary Palmer.It Pa /etc/pwd.db.tmp
129dea673e9SRodney W. GrimesA temporary file.
130fb0e6accSGary Palmer.It Pa /etc/spwd.db
131dea673e9SRodney W. GrimesThe secure password database file.
132fb0e6accSGary Palmer.It Pa /etc/spwd.db.tmp
133dea673e9SRodney W. GrimesA temporary file.
134dea673e9SRodney W. Grimes.It Pa /etc/master.passwd
135dea673e9SRodney W. GrimesThe current password file.
136dea673e9SRodney W. Grimes.It Pa /etc/passwd
137dea673e9SRodney W. GrimesA Version 7 format password file.
138dea673e9SRodney W. Grimes.El
139b81e945bSDag-Erling Smørgrav.Sh EXAMPLES
140b81e945bSDag-Erling SmørgravRegenerate the password database after manually editing or replacing
141b81e945bSDag-Erling Smørgravthe password file:
142c013ca2cSGraham Percival.Bd -literal -offset indent
143b7e6051aSDag-Erling Smørgrav/usr/sbin/pwd_mkdb -p /etc/master.passwd
144b81e945bSDag-Erling Smørgrav.Ed
14559a3c79dSRuslan Ermilov.Sh COMPATIBILITY
14659a3c79dSRuslan ErmilovPrevious versions of the system had a program similar to
14759a3c79dSRuslan Ermilov.Nm ,
148*3467ce29SJens Schweikhardtmkpasswd, which built
14959a3c79dSRuslan Ermilov.Xr dbm 3
15059a3c79dSRuslan Ermilovstyle databases for the password file but depended on the calling programs
15159a3c79dSRuslan Ermilovto install them.
15259a3c79dSRuslan ErmilovThe program was renamed in order that previous users of the program
15359a3c79dSRuslan Ermilovnot be surprised by the changes in functionality.
15459a3c79dSRuslan Ermilov.Sh SEE ALSO
15559a3c79dSRuslan Ermilov.Xr chpass 1 ,
15659a3c79dSRuslan Ermilov.Xr passwd 1 ,
15759a3c79dSRuslan Ermilov.Xr db 3 ,
15859a3c79dSRuslan Ermilov.Xr getpwent 3 ,
15959a3c79dSRuslan Ermilov.Xr passwd 5 ,
16059a3c79dSRuslan Ermilov.Xr vipw 8
161dea673e9SRodney W. Grimes.Sh BUGS
162dea673e9SRodney W. GrimesBecause of the necessity for atomic update of the password files,
1638b76e1d7SPhilippe Charnier.Nm
164dea673e9SRodney W. Grimesuses
165dea673e9SRodney W. Grimes.Xr rename 2
166dea673e9SRodney W. Grimesto install them.
167dea673e9SRodney W. GrimesThis, however, requires that the file specified on the command line live
168dea673e9SRodney W. Grimeson the same file system as the
1698b76e1d7SPhilippe Charnier.Pa /etc
170dea673e9SRodney W. Grimesdirectory.
171dea673e9SRodney W. Grimes.Pp
172dea673e9SRodney W. GrimesThere are the obvious races with multiple people running
1738b76e1d7SPhilippe Charnier.Nm
174dea673e9SRodney W. Grimeson different password files at the same time.
175dea673e9SRodney W. GrimesThe front-ends to
176e97407b4SRuslan Ermilov.Nm ,
177dea673e9SRodney W. Grimes.Xr chpass 1 ,
178dea673e9SRodney W. Grimes.Xr passwd 1
179dea673e9SRodney W. Grimesand
180dea673e9SRodney W. Grimes.Xr vipw 8 ,
181dea673e9SRodney W. Grimeshandle the locking necessary to avoid this problem.
182