home | help
ADDUSER(8)		     System Manager's Manual		      ADDUSER(8)

NAME
     adduser -- command for adding new users

SYNOPSIS
     adduser [-CDENShq] [-G groups] [-L login_class] [-M mode] [-d partition]
	     [-f file] [-g login_group] [-k dotdir] [-m message_file] [-s shell]
	     [-u uid_start] [-w type]

DESCRIPTION
     The  adduser  utility  is a shell script, implemented around the pw(8) com-
     mand, for adding new users.  It creates passwd/group entries, a home direc-
     tory, copies dotfiles and sends the new user a welcome  message.	It  sup-
     ports  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.

RESTRICTIONS
     username
	     Login name.  The user name is restricted to whatever pw(8) will ac-
	     cept.  Generally this means it may contain only  lowercase  charac-
	     ters  or  digits  but cannot begin with the `-' character.  Maximum
	     length is 16 characters.  The reasons for this limit  are	histori-
	     cal.   Given  that  people  have traditionally wanted to break this
	     limit for aesthetic reasons, it has never been of great  importance
	     to  break	such  a  basic	fundamental  parameter in Unix.  You can
	     change UT_NAMESIZE in <utmp.h> and recompile the world; people have
	     done this and it works, but you will have problems with any precom-
	     piled programs, or source that assumes the 8-character name  limit,
	     such  as  NIS.   The NIS protocol mandates an 8-character username.
	     If you need a longer login name for e-mail addresses, you	can  de-
	     fine an alias in /etc/mail/aliases.

     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  name contains an ampersand it will be replaced by the capital-
	     ized login name when displayed by other programs.	The `:'  charac-
	     ter is not allowed.

     shell   Unless the -S argument is supplied only valid shells from the shell
	     database  (/etc/shells)  are allowed.  In addition, either the base
	     name or the full path of the shell may be supplied.

     UID     Automatically generated or your  choice.	It  must  be  less  than
	     32000.

     GID/login group
	     Automatically  generated  or  your  choice.   It  must be less than
	     32000.

     password
	     You may choose an empty password, disable the password, use a  ran-
	     domly  generated  password  or specify your own plaintext password,
	     which will be encrypted before being stored in the user database.

UNIQUE GROUPS
     Perhaps you are missing what can be done with this scheme that falls  apart
     with  most  other	schemes.   With  each  user in their own group, they 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.

     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.

     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.

     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)

CONFIGURATION
     The    adduser   utility	reads	its   configuration   information   from
     /etc/adduser.conf.  If this file does not exist, it will use predefined de-
     faults.  While this file may be edited by hand, the safer option is to  use
     the  -C  command line argument.  With this argument, adduser will start in-
     teractive input, save the answers to its prompts in /etc/adduser.conf,  and
     promptly  exit  without  modifying the user database.  Options specified on
     the command line will take precedence over any values saved in this file.

OPTIONS
     -C      Create new configuration file and exit.  This  option  is	mutually
	     exclusive with the -f option.

     -d partition
	     Home  partition.	Default partition, under which all user directo-
	     ries will be located.  The  /nonexistent  partition  is  considered
	     special.	The  adduser  script will not create and populate a home
	     directory by that name.  Otherwise, by default it attempts to  cre-
	     ate a home directory.

     -D      Do not attempt to create the home directory.

     -E      Disable the account.  This option will lock the account by prepend-
	     ing  the  string "*LOCKED*" to the password field.  The account may
	     be unlocked by the super-user with the pw(8) command:

		   pw unlock [name | uid]

     -f file
	     Get the list of accounts to create from file.  If file is "-", then
	     get the list from standard input.	If  this  option  is  specified,
	     adduser  will  operate in batch mode and will not seek any user in-
	     put.  If an error is encountered while processing	an  account,  it
	     will  write  a  message  to standard error and move to the next ac-
	     count.  The format of the input file is described below.

     -g login_group
	     Normally, if no login group is specified, it is assumed to  be  the
	     same as the username.  This option makes login_group the default.

     -G groups
	     Space-separated  list of additional groups.  This option allows the
	     user to specify additional groups to add users to.  The user  is  a
	     member of these groups in addition to their login group.

     -h      Print a summary of options and exit.

     -k directory
	     Copy  files  from	directory  into the home directory of new users;
	     dot.foo will be renamed to .foo.

     -L login_class
	     Set default login class.

     -m file
	     Send new users a welcome message from file.  Specifying a value  of
	     no for file causes no message to be sent to new users.  Please note
	     that  the	message file can reference the internal variables of the
	     adduser script.

     -M mode
	     Create the home directory with permissions set to mode.

     -N      Do not read the default configuration file.

     -q      Minimal user feedback.  In particular, the random password will not
	     be echoed to standard output.

     -s shell
	     Default shell for new users.  The shell argument may  be  the  base
	     name of the shell or the full path.  Unless the -S argument is sup-
	     plied  the  shell must exist in /etc/shells or be the special shell
	     nologin to be considered a valid shell.

     -S      The existence or validity	of  the  specified  shell  will  not  be
	     checked.

     -u uid  Use UIDs from uid on up.

     -w type
	     Password type.  The adduser utility allows the user to specify what
	     type  of password to create.  The type argument may have one of the
	     following values:

	     no      Disable the password.  Instead of an encrypted string,  the
		     password  field  will  contain a single `*' character.  The
		     user may not log in until the super-user  manually  enables
		     the password.

	     none    Use an empty string as the password.

	     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.

	     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 randompass variable.

FORMAT
     When  the	-f  option  is used, the account information must be stored in a
     specific format.  All empty lines or lines beginning with a `#' will be ig-
     nored.  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 `:' character as part
     of the string.

	   name:uid:gid:class:change:expire:gecos:home_dir:shell:password

     name      Login name.  This field may not be empty.

     uid       Numeric login user ID.  If this field is left empty, it	will  be
	       automatically generated.

     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.

     class     Login class.  This field may be left empty.

     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 -p argument to 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.  This field may be left empty to turn it off.

     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.

     gecos     Full name and other extra information about the user.

     home_dir  Home directory.	If this field is left empty, it will be automat-
	       ically  created	by appending the username to the home partition.
	       The /nonexistent home directory is considered special and is  un-
	       derstood  to mean that no home directory is to be created for the
	       user.

     shell     Login shell.  This field should contain either the base	name  or
	       the full path to a valid login shell.

     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  as-
	       sumed  the  account will have an 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 -w option
	       is used with a no or none argument.  Be careful not to  terminate
	       this  field with a closing `:' because it will be treated as part
	       of the password.

FILES
     /etc/master.passwd    user database
     /etc/group 	   group database
     /etc/shells	   shell database
     /etc/login.conf	   login classes database
     /etc/adduser.conf	   configuration file for adduser
     /etc/adduser.message  message file for adduser
     /usr/share/skel	   skeletal login directory
     /var/log/adduser	   logfile for adduser

SEE ALSO
     chpass(1), passwd(1), adduser.conf(5), aliases(5), group(5), login.conf(5),
     passwd(5),  shells(5),  adding_user(8),  pw(8),   pwd_mkdb(8),   rmuser(8),
     vipw(8), yp(8)

HISTORY
     The adduser command appeared in FreeBSD 2.1.

AUTHORS
     This  manual  page and the original script, in Perl, was written by Wolfram
     Schneider <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 Mike Makonnen <mtm@identd.net>.

BUGS
     In  order	for  adduser to correctly expand variables such as $username and
     $randompass in the message sent to new users, it must let the shell  evalu-
     ate each line of the message file.  This means that shell commands can also
     be  embedded in the message file.	The adduser utility attempts to mitigate
     the possibility of an attacker using this feature by refusing  to	evaluate
     the  file	if it is not owned and writable only by the root user.	In addi-
     tion, shell special characters and operators will have to be  escaped  when
     used in the message file.

     Also,  password ageing and account expiry times are currently settable only
     in batch mode or when specified in /etc/adduser.conf.  The user  should  be
     able to set them in interactive mode as well.

FreeBSD 7.1			 March 16, 2008 		      ADDUSER(8)

home | help