From 47101b66db98c349dc0001db98e36c47a8d4b484 Mon Sep 17 00:00:00 2001 From: Ruslan Ermilov Date: Wed, 4 Dec 2002 14:44:20 +0000 Subject: mdoc(7) police: overhaul. Approved by: re --- adduser/adduser.8 | 362 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 221 insertions(+), 141 deletions(-) (limited to 'adduser/adduser.8') diff --git a/adduser/adduser.8 b/adduser/adduser.8 index 9a3eea4..4af1ef7 100644 --- a/adduser/adduser.8 +++ b/adduser/adduser.8 @@ -34,7 +34,6 @@ .Nd command for adding new users .Sh SYNOPSIS .Nm -.Bk -words .Op Fl CENhq .Op Fl G Ar groups .Op Fl L Ar login_class @@ -45,33 +44,35 @@ .Op Fl s Ar shell .Op Fl u Ar uid_start .Op Fl w Ar type -.Ek .Sh DESCRIPTION The -.Nm adduser -program is a shell script, implemented around the +.Nm +utility is a shell script, implemented around the .Xr pw 8 command, for adding new users. It creates passwd/group entries, a home directory, copies dotfiles and sends the new user a welcome message. -It supports two modes of operation. It may be used interactively -at the command line to add one user at a time or it may be directed +It supports two modes of operation. +It may be used interactively +at the command line to add one user at a time, or it may be directed to get the list of new users from a file and operate in batch mode without requiring any user interaction. .Sh RESTRICTIONS -.Bl -tag -width Ds -compact -.It Sy username +.Bl -tag -width indent +.It username Login name. The user name is restricted to whatever .Xr pw 8 -will accept. Generally this means it +will accept. +Generally this means it may contain only lowercase characters or digits. Maximum length is 16 characters. -The reasons for this limit are "Historical". +The reasons for this limit are historical. Given that people have traditionally wanted to break this -limit for aesthetic reasons, it's never been of great importance to break -such a basic fundamental parameter in UNIX. +limit for aesthetic reasons, it has never been of great importance to break +such a basic fundamental parameter in +.Ux . You can change .Dv UT_NAMESIZE in @@ -84,94 +85,113 @@ The NIS protocol mandates an 8-character username. If you need a longer login name for e-mail addresses, you can define an alias in .Pa /etc/mail/aliases . -.It Sy full name +.It "full name" This is typically known as the gecos field and usually contains -the user's full name. Additionally, it may contain a comma separated -list of values such as office number and work and home phones. If the +the user's full name. +Additionally, it may contain a comma separated +list of values such as office number and work and home phones. +If the name contains an amperstand it will be replaced by the capitalized login name when displayed by other programs. The -.Ql Pa \&: +.Ql \&: character is not allowed. -.It Sy shell -Only valid shells from the shell database (/etc/shells) are allowed. In +.It shell +Only valid shells from the shell database +.Pq Pa /etc/shells +are allowed. +In addition, only the base name of the shell is necessary, not the full path. -.It Sy uid -Automatically generated or your choice. It must be less than 32000. -.It Sy gid/login group -Automatically generated or your choice. It must be less than 32000. -.It Sy password +.It UID +Automatically generated or your choice. +It must be less than 32000. +.It "GID/login group" +Automatically generated or your choice. +It must be less than 32000. +.It password You may choose an empty password, disable the password, use a randomly generated password or specify your own plaintext password, which will be encrypted before being stored in the user database. .El .Sh UNIQUE GROUPS -Perhaps you're missing what +Perhaps you are missing what .Em can be done with this scheme that falls apart with most other schemes. -With each user in his/her own group the user can +With each user in his/her own group, the user can safely run with a umask of 002 instead of the usual 022 and create files in their home directory without worrying about others being able to change them. .Pp -For a shared area you create a separate uid/gid (like cvs or ncvs on freefall), +For a shared area you create a separate UID/GID (like cvs or ncvs on freefall), you place each person that should be able to access this area into that new group. .Pp -This model of uid/gid administration allows far greater flexibility than lumping +This model of UID/GID administration allows far greater flexibility than lumping users into groups and having to muck with the umask when working in a shared area. .Pp I have been using this model for almost 10 years and found that it works -for most situations, and has never gotten in the way. (Rod Grimes) +for most situations, and has never gotten in the way. +(Rod Grimes) .Sh CONFIGURATION The .Nm utility reads its configuration information from -.Ar /etc/adduser.conf . -If this file does not exist it will use predefined defaults. While -this file may be edited by hand the safer option is to use the -.Op Fl C -command line argument. With this argument +.Pa /etc/adduser.conf . +If this file does not exist, it will use predefined defaults. +While this file may be edited by hand, +the safer option is to use the +.Fl C +command line argument. +With this argument, .Nm will start interactive input, save the answers to its prompts in -.Ar /etc/adduser.conf , +.Pa /etc/adduser.conf , and promptly exit without modifying the user -database. Options specified on the command line will take precedence over +database. +Options specified on the command line will take precedence over any values saved in this file. .Sh OPTIONS -.Bl -tag -width Ds +.Bl -tag -width indent .It Fl C -Create new configuration file and exit. This option is mutually exclusive -with the -.Op Fl f +Create new configuration file and exit. +This option is mutually exclusive with the +.Fl f option. .It Fl d Ar partition -Home partition. Default partition, under which all user directories +Home partition. +Default partition, under which all user directories will be located. .It Fl E -Disable the account. This option will lock the account by prepending -the string *LOCKED* to the password field. The account may be unlocked +Disable the account. +This option will lock the account by prepending the string +.Dq Li *LOCKED* +to the password field. +The account may be unlocked by the super-user with the .Xr pw 8 command: .Pp -.Dl "pw unlock [name|uid]" +.D1 Nm pw Cm unlock Op Ar name | uid .It Fl f Ar file Get the list of accounts to create from .Ar file . If .Ar file -is '`-'', then get the list from standard input. If this option -is specified +is +.Dq Fl , +then get the list from standard input. +If this option is specified, .Nm -will operate in batch mode and will not seek any user input. If an -error is encountered while processing an account it will write a -message to standard error and move to the next account. The format +will operate in batch mode and will not seek any user input. +If an error is encountered while processing an account, it will write a +message to standard error and move to the next account. +The format of the input file is described below. .It Fl G Ar groups -Additional group(s). By default the user name is used as the login group. +Additional groups. +By default, the user name is used as the login group. This option allows the user to specify additional groups to add users to. .It Fl h Print a summary of options and exit. @@ -179,131 +199,179 @@ Print a summary of options and exit. Copy files from .Ar directory into the home -directory of new users, -.Ql Pa dot.foo +directory of new users; +.Pa dot.foo will be renamed to -.Ql Pa .foo . +.Pa .foo . .It Fl L Ar login_class Set default login class. .It Fl m Ar file Send new users a welcome message from .Ar file . Specifying a value of -.Ar no +.Cm no for .Ar file -causes no message to be sent to new users. Please note that the message +causes no message to be sent to new users. +Please note that the message file can reference the internal variables of the .Nm script. .It Fl N Do not read the default configuration file. .It Fl q -Minimal user feedback. In particular, the random password will not be echoed to +Minimal user feedback. +In particular, the random password will not be echoed to standard output. .It Fl s Ar shell -Default shell for new users. The +Default shell for new users. +The .Ar shell -argument must be the base name of the shell , NOT the full path. +argument must be the base name of the shell, +.Em not +the full path. It must exist in -.Ar /etc/shells +.Pa /etc/shells to be considered a valid shell. .It Fl u Ar uid -Use uid's from +Use UIDs from .Ar uid on up. .It Fl w Ar type -Password type. The +Password type. +The .Nm utility allows the user to specify what type of password to create. The .Ar type argument may have one of the following values: -.Bl -tag -width ".Dv random" -.It Dv no -Disable the password. Instead of an encrypted string the passowrd field -will contain a single '`*'' character. -The user may not login until the super-user +.Bl -tag -width ".Cm random" +.It Cm no +Disable the password. +Instead of an encrypted string, the passowrd field will contain a single +.Ql * +character. +The user may not log in until the super-user manually enables the password. -.It Dv none +.It Cm none Use an empty string as the password. -.It Dv yes -Use a user supplied string as the password. In interactive mode -the user will be prompted for the password. In batch mode, the +.It Cm yes +Use a user-supplied string as the password. +In interactive mode, +the user will be prompted for the password. +In batch mode, the last (10th) field in the line is assumed to be the password. -.It Dv random -Generate a random string and use it as a password. The password will -be echoed to standard output. In addition it will be available for -inclusion in the message file in the -.Ar randompass -environment variable. +.It Cm random +Generate a random string and use it as a password. +The password will be echoed to standard output. +In addition, it will be available for inclusion in the message file in the +.Va randompass +variable. +.El .El .Sh FORMAT -.Bl -tag -width Ds -compact When the -.Op Fl f -option is used the account information must be stored in a specific -format. All empty lines or lines beginning with a -.Ql Pa # -will be ignored. All other lines must contain ten colon (:) separated -fields as described below. Command line options do not take precedence -over values in the fields. Only the password field may contain a -.Ql Pa : +.Fl f +option is used, the account information must be stored in a specific +format. +All empty lines or lines beginning with a +.Ql # +will be ignored. +All other lines must contain ten colon +.Pq Ql \&: +separated fields as described below. +Command line options do not take precedence +over values in the fields. +Only the password field may contain a +.Ql \&: character as part of the string. .Pp -.Dl "name:uid:gid:class:change:expire:gecos:home_dir:shell:password" -.Bl -tag -width ".Dv password" -.It Dv name -Login name. This field may not be empty. -.It Dv uid -Numeric login user id. If this field is left empty it will be automatically -generated. -.It Dv gid -Numeric primary group id. If this field is left empty a group with the -same name as the user name will be created and its gid will be used +.Sm off +.D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password +.Sm on +.Bl -tag -width ".Ar password" +.It Ar name +Login name. +This field may not be empty. +.It Ar uid +Numeric login user ID. +If this field is left empty, it will be automatically generated. +.It Ar gid +Numeric primary group ID. +If this field is left empty, a group with the +same name as the user name will be created and its GID will be used instead. -.It Dv class -Login class. This field may be left empty. -.It Dv change +.It Ar class +Login class. +This field may be left empty. +.It Ar change Password ageing. -This field denotes the password change date for the account. The format of this -field is the same as the format of the -.Op Fl p +This field denotes the password change date for the account. +The format of this field is the same as the format of the +.Fl p argument to .Xr pw 8 . -It may be 'dd-mmm-yy[yy]', where 'dd' is for the day, 'mmm' is for the month -in numeric or alphabetical format: '10 or Oct', and 'yy[yy]' is the four or two digit year. -To denote a time relative to the current date the format -is: '+n[mhdwoy]', where 'n' denotes a number, followed by the Minutes, Hours, -Days, Weeks, Months or Years after which the password must be changed. +It may be +.Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy , +where +.Ar dd +is for the day, +.Ar mmm +is for the month in numeric or alphabetical format: +.Dq Li 10 +or +.Dq Li Oct , +and +.Ar yy Ns Op Ar yy +is the four or two digit year. +To denote a time relative to the current date the format is: +.No + Ns Ar n Ns Op Ar mhdwoy , +where +.Ar n +denotes a number, followed by the minutes, hours, days, weeks, +months or years after which the password must be changed. +This field may be left empty to turn it off. +.It Ar expire +Account expiration. +This field denotes the expiry date of the account. +The account may not be used after the specified date. +The format of this field is the same as that for password ageing. This field may be left empty to turn it off. -.It Dv expire -Account expiration. This field denotes the expiry date of the account. The account may -not be used after the specified date. The format of this field is the same as that -for password ageing. This field may be left empty to turn it off. -.It Dv gecos +.It Ar gecos Full name and other extra information about the user. -.It Dv home_dir -Home directory. If this field is left empty it will be automatically +.It Ar home_dir +Home directory. +If this field is left empty, it will be automatically created by appending the username to the home partition. -.It Dv shell -Login Shell. This field should contain the full path to a valid login shell. -.It Dv password -User password. This field should contain a plaintext string, which will -be encrypted before being placed in the user database. If the password type is 'yes' -and this field is empty it is assumed the account will have any empty password. If -the password type is 'random' and this field is NOT empty its contents will be used -as a password. This field will be ignored if the -.Op Fl p -flag is used with a -.Ar no +.It Ar shell +Login shell. +This field should contain the full path to a valid login shell. +.It Ar password +User password. +This field should contain a plaintext string, which will +be encrypted before being placed in the user database. +If the password type is +.Cm yes +and this field is empty, it is assumed the account will have an empty password. +If the password type is +.Cm random +and this field is +.Em not +empty, its contents will be used +as a password. +This field will be ignored if the +.Fl p +option is used with a +.Cm no or -.Ar none -argument. Be carefull not to terminate this field with a closing ':' because it will -be treated as part of the password. +.Cm none +argument. +Be carefull not to terminate this field with a closing +.Ql \&: +because it will be treated as part of the password. .El .Sh FILES -.Bl -tag -width /etc/master.passwdxx -compact +.Bl -tag -width ".Pa /etc/adduser.message" -compact .It Pa /etc/master.passwd user database .It Pa /etc/group @@ -313,13 +381,16 @@ shell database .It Pa /etc/login.conf login classes database .It Pa /etc/adduser.conf -configuration file for adduser +configuration file for +.Nm .It Pa /etc/adduser.message -message file for adduser +message file for +.Nm .It Pa /usr/share/skel skeletal login directory .It Pa /var/log/adduser -logfile for adduser +logfile for +.Nm .El .Sh SEE ALSO .Xr chpass 1 , @@ -340,22 +411,31 @@ The command appeared in .Fx 2.1 . .Sh AUTHORS -This manual page and the original script, in perl, was written by -.An Wolfram Schneider . The replacement script, written as a Bourne +.An -nosplit +This manual page and the original script, in Perl, was written by +.An Wolfram Schneider Aq wosch@FreeBSD.org . +The replacement script, written as a Bourne shell script with some enhancements, and the man page modification that came with it were done by -.An Mike Makonnen . +.An Mike Makonnen Aq mtm@identd.net . .Sh BUGS In order for .Nm -to correctly expand variables such as $username and $randompass in the message sent -to new users it must let the shell evaluate each line of the message file. This means -that shell commands can also be embedded in the message file. The +to correctly expand variables such as +.Va $username +and +.Va $randompass +in the message sent to new users, it must let the shell evaluate +each line of the message file. +This means that shell commands can also be embedded in the message file. +The .Nm -utility attemps to mitigate the possibility of an attacker using this feature by -refusing to evaluate the file if it is not owned and writeable only by the root user. -In addition, shell special characters and operators will have to be escaped when -used in the message file. +utility attemps to mitigate the possibility of an attacker using this +feature by refusing to evaluate the file if it is not owned and writeable +only by the root user. +In addition, shell special characters and operators will have to be +escaped when used in the message file. .Pp -Also, password ageing and account expiry times are currently setable only in batch mode. +Also, password ageing and account expiry times are currently setable +only in batch mode. The user should be able to set them in interactive mode as well. -- cgit v1.2.3-56-ge451