Date: Mon, 9 Feb 1998 18:15:40 -0600 (CST) From: dannyman <dannyman@arh0300.urh.uiuc.edu> To: FreeBSD-gnats-submit@FreeBSD.ORG Subject: docs/5692: context diff for pw(8) man page revision Message-ID: <199802100015.SAA24428@arh0300.urh.uiuc.edu>
next in thread | raw e-mail | index | archive | help
>Number: 5692
>Category: docs
>Synopsis: context diff for pw(8) man page revision
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-bugs
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Feb 9 16:20:00 PST 1998
>Last-Modified:
>Originator: dannyman
>Organization:
>Release: FreeBSD 3.0-CURRENT i386
>Environment:
>Description:
This is a minor revision of the pw(8) man page addresing some typoes,
akward phrasing, and some minor technical faults.
>How-To-Repeat:
>Fix:
please advise if there is a better way to attach context diff. :)
Context diff follows;
*** /usr/src/usr.sbin/pw/pw.8 Fri Oct 10 01:23:33 1997
--- pw.8 Mon Feb 9 16:46:44 1998
***************
*** 165,171 ****
modifying and removing users and groups.
Note that
.Nm
! only operates on the local user and group files; NIS users and groups must be
maintained on the NIS server.
.Nm Pw
handles updating the
--- 165,171 ----
modifying and removing users and groups.
Note that
.Nm
! only operates on the local user and group files - NIS users and groups must be
maintained on the NIS server.
.Nm Pw
handles updating the
***************
*** 175,199 ****
and the secure and insecure
password database files, and must be run as root.
.Pp
! The first one or two keywords provided on
! .Xr pw 8 's
! command line provide the context for the remainder of the arguments.
! One of the keywords
.Ar user
and
.Ar group
! may be combined or provided separately with
.Ar add ,
.Ar del ,
.Ar mod ,
.Ar show ,
or
! .Ar next ,
! and may be specified in either order (ie. showuser, usershow, show user and user show
! are all considered to be the same thing).
! This flexibility is useful for interactive scripts which call
.Nm
! for the actual user and group database manipulation.
Following these keywords, you may optionally specify the user or group name or numeric
id as an alternative to using the
.Fl n Ar name ,
--- 175,203 ----
and the secure and insecure
password database files, and must be run as root.
.Pp
! The first one or two keywords provided to
! .Nm
! on the command line provide the context for the remainder of the arguments.
! The keywords
.Ar user
and
.Ar group
! may be combined with
.Ar add ,
.Ar del ,
.Ar mod ,
.Ar show ,
or
! .Ar next
! in any order. (For example,
! .Ar showuser ,
! .Ar usershow ,
! .Ar show user , and
! .Ar user show
! all mean the same thing.)
! This flexibility is useful for interactive scripts calling
.Nm
! for user and group database manipulation.
Following these keywords, you may optionally specify the user or group name or numeric
id as an alternative to using the
.Fl n Ar name ,
***************
*** 201,207 ****
.Fl g Ar gid
options.
.Pp
! The following flags are common to all or most modes of operation:
.Pp
.Bl -tag -width "-G grouplist"
.It Fl C Ar config
--- 205,211 ----
.Fl g Ar gid
options.
.Pp
! The following flags are common to most modes of operation;
.Pp
.Bl -tag -width "-G grouplist"
.It Fl C Ar config
***************
*** 209,221 ****
.Nm
reads the file
.Pa /etc/pw.conf
! to obtain policy information on how new user accounts and groups are to be created,
! and the
.Fl C
option specifies a different configuration file.
! Most of the contents in the configuration file may be overridden via command line
! options, but it may be more useful to set up standard information for addition of
! new accounts in the configuration file.
.It Fl q
Use of this option causes
.Nm
--- 213,225 ----
.Nm
reads the file
.Pa /etc/pw.conf
! to obtain policy information on how new user accounts and groups are to be created.
! The
.Fl C
option specifies a different configuration file.
! While most of the contents of the configuration file may be overridden via
! command-line options, it may be more convenient to keep standard information in a
! configuration file.
.It Fl q
Use of this option causes
.Nm
***************
*** 224,233 ****
.Nm
rather than messing up a carefully formatted display.
.It Fl N
! This option is available in add and modify operations, and causes
.Nm
! to skip updating the user/group databases and instead print the result
! of the operation without actually performing it.
You may use the
.Fl P
option to switch between standard passwd and readable formats.
--- 228,241 ----
.Nm
rather than messing up a carefully formatted display.
.It Fl N
! This option is available in
! .Ar add
! and
! .Ar modify
! operations, and tells
.Nm
! to output the result of the operation without updating the user or group
! databases.
You may use the
.Fl P
option to switch between standard passwd and readable formats.
***************
*** 238,257 ****
.Xr make 1
after changing to the directory
.Pa /var/yp .
! This is intended to allow automatic updating of the NIS database files.
If separate passwd and group files are being used by NIS, then use the
.Fl y Ar path
! option to specify the location of the NIS passwd database so that pw
! will automatically update it concurrently with the system password
databases.
.El
.Pp
.Sh USER OPTIONS
The following options apply to the
! .Ar useradd ,
and
! .Ar usermod ,
! commands:
.Pp
.Bl -tag -width "-G grouplist"
.It Fl n Ar name
--- 246,266 ----
.Xr make 1
after changing to the directory
.Pa /var/yp .
! This is intended to allow automatic updating of NIS database files.
If separate passwd and group files are being used by NIS, then use the
.Fl y Ar path
! option to specify the location of the NIS passwd database so that
! .Nm
! will concurrently update it with the system password
databases.
.El
.Pp
.Sh USER OPTIONS
The following options apply to the
! .Ar useradd
and
! .Ar usermod
! commands;
.Pp
.Bl -tag -width "-G grouplist"
.It Fl n Ar name
***************
*** 259,301 ****
.It Fl u Ar uid
Specify the user/account numeric id.
.Pp
! Usually, you need only to provide one or the other of these options, as the account
! name will imply the uid, and vice versa.
! Also, you may provide either the account or userid immediately after the
! .Ar useradd ,
! .Ar userdel ,
! .Ar usermod
! or
! .Ar usershow
! keyword on the command line without the need to use
! .Ql Fl n
! or
! .Ql Fl u .
! There are times, however, were you need to provide both.
For example, when changing the uid of an existing user with
.Ar usermod ,
or overriding the default uid when creating a new account.
If you wish
.Nm
! to automatically allocate the uid to a new user on
.Ar useradd ,
then you should
.Em not
use the
.Ql Fl u
option.
.El
.Pp
- Options available with both
- .Ar useradd
- and
- .Ar usermod
- are:
.Bl -tag -width "-G grouplist"
.It Fl c Ar comment
This field sets the contents of the passwd GECOS field, which normally contains up
to four comma-separated fields containing the user's full name, office or location,
! work and home phone numbers.
These sub-fields are used by convention only, however, and are optional.
If this field is to contain spaces, you need to quote the comment itself with double
quotes
--- 268,306 ----
.It Fl u Ar uid
Specify the user/account numeric id.
.Pp
! Usually, you only need to provide one or the other of these options, as the account
! name will imply the uid, or vice versa.
! However, there are times when you need to provide both.
For example, when changing the uid of an existing user with
.Ar usermod ,
or overriding the default uid when creating a new account.
If you wish
.Nm
! to automatically allocate the uid to a new user with
.Ar useradd ,
then you should
.Em not
use the
.Ql Fl u
option.
+ You may also provide either the account or userid immediately after the
+ .Ar useradd ,
+ .Ar userdel ,
+ .Ar usermod
+ or
+ .Ar usershow
+ keywords on the command line without using the
+ .Ql Fl n
+ or
+ .Ql Fl u
+ options.
.El
.Pp
.Bl -tag -width "-G grouplist"
.It Fl c Ar comment
This field sets the contents of the passwd GECOS field, which normally contains up
to four comma-separated fields containing the user's full name, office or location,
! and work and home phone numbers.
These sub-fields are used by convention only, however, and are optional.
If this field is to contain spaces, you need to quote the comment itself with double
quotes
***************
*** 303,320 ****
Avoid using commas in this field as these are used as sub-field separators, and the
colon
.Ql \&:
! character also cannot be used as this is the field separator in the passwd file.
.It Fl d Ar dir
This option sets the account's home directory.
Normally, you will only use this if the home directory is to be different from the
! default (which is determined from pw.conf, which specifies the base home directory
- normally
.Pa /home
! - with the account name as a subdirectory).
.It Fl e Ar date
Set the account's expiration date.
Format of the date is either a UNIX time in decimal, or a date in
! .Ql \& dd-mmm-yy[yy]
format, where dd is the day, mmm is the month, either in numeric or alphabetic format
('Jan', 'Feb', etc) and year is either a two or four digit year.
This option also accepts a relative date in the form
--- 308,327 ----
Avoid using commas in this field as these are used as sub-field separators, and the
colon
.Ql \&:
! character also cannot be used as this is the field separator for the passwd
! file itself.
.It Fl d Ar dir
This option sets the account's home directory.
Normally, you will only use this if the home directory is to be different from the
! default determined from
! .Pa /etc/pw.conf
- normally
.Pa /home
! with the account name as a subdirectory.
.It Fl e Ar date
Set the account's expiration date.
Format of the date is either a UNIX time in decimal, or a date in
! .Ql dd-mmm-yy[yy]
format, where dd is the day, mmm is the month, either in numeric or alphabetic format
('Jan', 'Feb', etc) and year is either a two or four digit year.
This option also accepts a relative date in the form
***************
*** 323,356 ****
.Ql \&n
is a decimal, octal (leading 0) or hexadecimal (leading 0x) digit followed by the
number of Minutes, Hours, Days, Weeks, Months or Years from the current date at
! which the expiry date is to be set.
.It Fl p Ar date
Set the account's password expiration date.
! This field is identical to the account expiration date option, except that it
applies to forced password changes.
! The same formats are accepted as with the account expiration option.
.It Fl g Ar group
Set the account's primary group to the given group.
.Ar group
! may be either the group name or its corresponding group id number.
.It Fl G Ar grouplist
! Sets the additional groups to which an account belongs.
.Ar grouplist
! is a comma-separated list or group names or group ids.
! When adding a user, the user's name is added to the group lists in
.Pa /etc/group ,
! and when editing a user, the user's name is also added to the group lists, and
removed from any groups not specified in
.Ar grouplist .
! Note: a user should not be added to their primary group in
! .Pa /etc/group .
! Also, group membership changes do not take effect immediately for current logins,
! only logins subsequent to the change.
.It Fl L Ar class
This option sets the login class for the user being created.
See
.Xr login.conf 5
! for more information on user classes.
.It Fl m
This option instructs
.Nm
--- 330,365 ----
.Ql \&n
is a decimal, octal (leading 0) or hexadecimal (leading 0x) digit followed by the
number of Minutes, Hours, Days, Weeks, Months or Years from the current date at
! which the expiration date is to be set.
.It Fl p Ar date
Set the account's password expiration date.
! This field is similar to the account expiration date option, except that it
applies to forced password changes.
! This is set in the same manner as the
! .Ql Fl e
! option.
.It Fl g Ar group
Set the account's primary group to the given group.
.Ar group
! may be defined by either its name or group number.
.It Fl G Ar grouplist
! Sets additional group memberships for an account.
.Ar grouplist
! is a comma-separated list of group names or group numbers.
! The user's name is added to the group lists in
.Pa /etc/group ,
! and
removed from any groups not specified in
.Ar grouplist .
! Note: a user should not be added to their primary group with
! .Ar grouplist .
! Also, group membership changes do take effect for current user login
! sessions, requiring the user to reconnect to be affected by the changes.
.It Fl L Ar class
This option sets the login class for the user being created.
See
.Xr login.conf 5
! for more information on user login classes.
.It Fl m
This option instructs
.Nm
***************
*** 367,393 ****
.Ql Fl m
is used on an account with
.Ar usermod ,
! any existing configuration files in the user's home directory are
.Em not
! overwritten with the prototype files.
.Pp
! When a user's home directory is created, it will be default be as a subdirectory of the
.Ar basehome
! directory specified with the
! .Ql Fl b Ar dir
! option (see below), and will be named the same as the account.
! This may be overridden with the
! .Ql Fl d Ar dir
option on the command line, if desired.
.It Fl k Ar dir
Set the
.Ar skeleton
! subdirectory, from which the basic startup and configuration files are copied when
the user's home directory is created.
! This option only has meaning when used with
! .Ql Fl D
! (see below) or
! .Ql Fl m .
.It Fl s Ar shell
Set or changes the user's login shell to
.Ar shell .
--- 376,403 ----
.Ql Fl m
is used on an account with
.Ar usermod ,
! existing configuration files in the user's home directory are
.Em not
! overwritten from the skeleton files.
.Pp
! When a user's home directory is created, it will by default be a subdirectory of the
.Ar basehome
! directory as specified by the
! .Ql Fl b
! option (see below), bearing the name of the new account.
! This can be overridden by the
! .Ql Fl d
option on the command line, if desired.
.It Fl k Ar dir
Set the
.Ar skeleton
! directory, from which basic startup and configuration files are copied when
the user's home directory is created.
! This option only has meaning when used with the
! .Ql Fl d
! or
! .Ql Fl m
! flags.
.It Fl s Ar shell
Set or changes the user's login shell to
.Ar shell .
***************
*** 410,425 ****
Set the
.Em class
field in the user's passwd record.
! This field is not currently used, but will be in the future used to specify a
.Em termcap
! entry like tag (see
.Xr passwd 5
! for details).
.It Fl h Ar fd
This option provides a special interface by which interactive scripts can
set an account password using
.Nm pw .
! Because the command line and environment are fundamental insecure mechanisms
by which programs can accept information,
.Nm
will only allow setting of account and group passwords via a file descriptor
--- 420,435 ----
Set the
.Em class
field in the user's passwd record.
! This field is not currently used, but will be used in the future to specify a
.Em termcap
! entry like tag. See
.Xr passwd 5
! for details.
.It Fl h Ar fd
This option provides a special interface by which interactive scripts can
set an account password using
.Nm pw .
! Because the command line and environment are fundamentally insecure mechanisms
by which programs can accept information,
.Nm
will only allow setting of account and group passwords via a file descriptor
***************
*** 429,435 ****
.Ar ksh
and
.Ar perl
! all posses mechanisms by which this can be done.
Alternatively,
.Nm pw
will prompt for the user's password if
--- 439,445 ----
.Ar ksh
and
.Ar perl
! all possess mechanisms by which this can be done.
Alternatively,
.Nm pw
will prompt for the user's password if
***************
*** 438,447 ****
.Em stdin
as the file descriptor on which to read the password.
Note that this password will be read once and once only and is intended
! for use by a script or similar rather than interactive use.
If you wish to have new password confirmation along the lines of
.Xr passwd 1 ,
! this must be implemented as part of the interactive script that calls
.Nm pw .
.Pp
If a value of
--- 448,457 ----
.Em stdin
as the file descriptor on which to read the password.
Note that this password will be read once and once only and is intended
! for use by a script rather than for interactive use.
If you wish to have new password confirmation along the lines of
.Xr passwd 1 ,
! this must be implemented as part of an interactive script that calls
.Nm pw .
.Pp
If a value of
***************
*** 450,456 ****
.Ar fd ,
then the password will be set to
.Ql \&* ,
! rendering the account inaccessible via passworded login.
.El
.Pp
It is possible to use
--- 460,466 ----
.Ar fd ,
then the password will be set to
.Ql \&* ,
! rendering the account inaccessible via password-based login.
.El
.Pp
It is possible to use
***************
*** 486,492 ****
changes the meaning of several command line switches in the
.Ar useradd
command.
! These are:
.Bl -tag -width "-G grouplist"
.It Fl D
Set default values in
--- 496,502 ----
changes the meaning of several command line switches in the
.Ar useradd
command.
! These are;
.Bl -tag -width "-G grouplist"
.It Fl D
Set default values in
***************
*** 512,529 ****
Set the default group for new users.
If a blank group is specified using
.Ql Fl g Ar \&"" ,
! then new users will be allocated their own private primary group (a new group created
! with the same name as their login name).
If a group is supplied, either its name or uid may be given as an argument.
.It Fl G Ar grouplist
! Set the default groups in which new users are made members.
This is a separate set of groups from the primary group, and you should avoid
! nominating the same group as both the primary and in extra groups.
In other words, these extra groups determine membership in groups
.Em other than
the primary group.
.Ar grouplist
! is a comma-separated list of group names or ids, or a mixture of both, and are always
stored in
.Pa /etc/pw.conf
by their symbolic names.
--- 522,539 ----
Set the default group for new users.
If a blank group is specified using
.Ql Fl g Ar \&"" ,
! then new users will be allocated their own private primary group
! with the same name as their login name
If a group is supplied, either its name or uid may be given as an argument.
.It Fl G Ar grouplist
! Set the default groups in which new users are granted membership.
This is a separate set of groups from the primary group, and you should avoid
! nominating the same group as both primary and extra groups.
In other words, these extra groups determine membership in groups
.Em other than
the primary group.
.Ar grouplist
! is a comma-separated list of group names or ids, and are always
stored in
.Pa /etc/pw.conf
by their symbolic names.
***************
*** 585,591 ****
the information from
.Pa /etc/master.passwd
directly with NIS.
! You should only set this option on NIS servers.
.El
.Pp
The
--- 595,601 ----
the information from
.Pa /etc/master.passwd
directly with NIS.
! You should only set this option for NIS servers.
.El
.Pp
The
***************
*** 618,625 ****
are unconditionally attached to the user name.
Jobs queued for processing by
.Ar at
! are also removed if the user's uid is unique (not also used by another account on the
! system).
.Pp
The
.Ar usershow
--- 628,635 ----
are unconditionally attached to the user name.
Jobs queued for processing by
.Ar at
! are also removed if the user's uid is unique and not also used by another account on the
! system.
.Pp
The
.Ar usershow
***************
*** 646,657 ****
.Pp
.Sh GROUP OPTIONS
The
! .Ql Fl C Ar config
and
.Ql Fl q
options (explained at the start of the previous section) are available
with the group manipulation commands.
! Other common options to all group-related commands are:
.Bl -tag -width "-m newmembers"
.It Fl n Ar name
Specify the group name.
--- 656,667 ----
.Pp
.Sh GROUP OPTIONS
The
! .Ql Fl C
and
.Ql Fl q
options (explained at the start of the previous section) are available
with the group manipulation commands.
! Other common options to all group-related commands are;
.Bl -tag -width "-m newmembers"
.It Fl n Ar name
Specify the group name.
***************
*** 663,669 ****
versa.
You will only need to use both when setting a specific group id
against a new group or when changing the uid of an existing group.
! .It Fl M Ar memberlist
This option provides an alternative way to add existing users to a
new group (in groupadd) or replace an existing membership list (in
groupmod).
--- 673,679 ----
versa.
You will only need to use both when setting a specific group id
against a new group or when changing the uid of an existing group.
! .Ql Fl M Ar memberlist
This option provides an alternative way to add existing users to a
new group (in groupadd) or replace an existing membership list (in
groupmod).
***************
*** 671,696 ****
is a comma separated list of valid and existing user names or uids.
.It Fl m Ar newmembers
Similar to
! .Op M ,
this option allows the
.Em addition
! of existing users to a group without first replacing the existing list of
members.
! Login names or user ids may be used, and duplicated users are automatically
! and silently eliminated.
.El
.Pp
.Ar groupadd
also has a
.Ql Fl o
! option that allows allocation of an existing group id to new group.
The default action is to reject an attempt to add a group, and this option overrides
the check for duplicate group ids.
There is rarely any need to duplicate a group id.
.Pp
The
.Ar groupmod
! command adds one additonal option:
.Pp
.Bl -tag -width "-m newmembers"
.It Fl l Ar name
--- 681,706 ----
is a comma separated list of valid and existing user names or uids.
.It Fl m Ar newmembers
Similar to
! .Ql Fl M ,
this option allows the
.Em addition
! of existing users to a group without replacing the existing list of
members.
! Login names or user ids may be used, and duplicate users are
! silently eliminated.
.El
.Pp
.Ar groupadd
also has a
.Ql Fl o
! option that allows allocation of an existing group id to a new group.
The default action is to reject an attempt to add a group, and this option overrides
the check for duplicate group ids.
There is rarely any need to duplicate a group id.
.Pp
The
.Ar groupmod
! command adds one additional option:
.Pp
.Bl -tag -width "-m newmembers"
.It Fl l Ar name
***************
*** 715,721 ****
returns the next available group id on standard output.
.Sh DIAGNOSTICS
.Nm Pw
! returns EXIT_SUCCESS on successful operation, otherwise one of the
following exit codes defined by
.Xr sysexits 3
as follows:
--- 725,733 ----
returns the next available group id on standard output.
.Sh DIAGNOSTICS
.Nm Pw
! returns EXIT_SUCCESS on successful operation, otherwise
! .Nm
! returns one of the
following exit codes defined by
.Xr sysexits 3
as follows:
***************
*** 741,747 ****
.Bl -bullet -compact
.It
Bad or invalid data provided or missing on the command line or
! via the password flie descriptor.
.It
Attempted to remove, rename root account or change its uid.
.El
--- 753,759 ----
.Bl -bullet -compact
.It
Bad or invalid data provided or missing on the command line or
! via the password file descriptor.
.It
Attempted to remove, rename root account or change its uid.
.El
***************
*** 752,765 ****
.It
Base home directory is invalid or does not exist.
.It
! Invalid or non-existant shell specified.
.El
.It EX_NOUSER
.Bl -bullet -compact
.It
User, user id, group or group id specified does not exist.
.It
! User or group recorded added or modified unexpectedly disappeared.
.El
.It EX_SOFTWARE
.Bl -bullet -compact
--- 764,777 ----
.It
Base home directory is invalid or does not exist.
.It
! Invalid or non-existent shell specified.
.El
.It EX_NOUSER
.Bl -bullet -compact
.It
User, user id, group or group id specified does not exist.
.It
! User or group recorded, added or modified unexpectedly disappeared.
.El
.It EX_SOFTWARE
.Bl -bullet -compact
***************
*** 790,812 ****
lists all available options for the useradd operation.
.Pp
.Nm Pw
! allows 8-bit characters in the passwd gecos field (user's full name,
office, work and home phone number subfields), but disallows them in
user login and group names.
! Use 8-bit characters with caution, as connection to the internet will
require that your mail transport program supports 8BITMIME, and will
convert headers containing 8-bit characters to 7-bit quoted-printable
format.
.Xr sendmail 8
does support this.
! Use of 8-bit characters in the gecos field should be used in
conjunction with the user's default locale and character set
and should not be implemented without their use.
Using 8-bit characters may also affect other
! programs that transmit the contents of the gecos field over the
! internet, such as
.Xr fingerd 8 ,
! and a small number of tcpip clients, such as irc, where fullnames
specified in the passwd file may be used by default.
.Sh FILES
.Bl -tag -width /etc/master.passwd.new -compact
--- 802,824 ----
lists all available options for the useradd operation.
.Pp
.Nm Pw
! allows 8-bit characters in the passwd GECOS field (user's full name,
office, work and home phone number subfields), but disallows them in
user login and group names.
! Use 8-bit characters with caution, as connection to the Internet will
require that your mail transport program supports 8BITMIME, and will
convert headers containing 8-bit characters to 7-bit quoted-printable
format.
.Xr sendmail 8
does support this.
! Use of 8-bit characters in the GECOS field should be used in
conjunction with the user's default locale and character set
and should not be implemented without their use.
Using 8-bit characters may also affect other
! programs that transmit the contents of the GECOS field over the
! Internet, such as
.Xr fingerd 8 ,
! and a small number of TCP/IP clients, such as IRC, where full names
specified in the passwd file may be used by default.
.Sh FILES
.Bl -tag -width /etc/master.passwd.new -compact
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-bugs" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199802100015.SAA24428>