Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

     adduser --	command	for adding new users

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

     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 di-
     rectory, 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 to get the
     list of new users from a file and operate in batch	mode without requiring
     any user interaction.

	     Login name.  The user name	is restricted to whatever pw(8)	will
	     accept.  Generally	this means it may contain only lowercase char-
	     acters or digits but cannot begin with the	`-' character.	Maxi-
	     mum length	is 16 characters.  The reasons for this	limit are his-
	     torical.  Given that people have traditionally wanted to break
	     this limit	for aesthetic reasons, it has never been of great im-
	     portance 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 precompiled programs, or source that assumes the 8-char-
	     acter 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	define 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 sepa-
	     rated list	of values such as office number	and work and home
	     phones.  If the name contains an ampersand	it will	be replaced by
	     the capitalized login name	when displayed by other	programs.  The
	     `:' character 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

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

	     You may choose an empty password, disable the password, use a
	     randomly generated	password or specify your own plaintext pass-
	     word, which will be encrypted before being	stored in the user

     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)

     The adduser utility reads its configuration information from
     /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 -C	command	line argument.	With this argument, adduser will start
     interactive 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

     -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
	     create a home directory.

     -D	     Do	not attempt to create the home directory.

     -E	     Disable the account.  This	option will lock the account by
	     prepending	the string "*LOCKED*" to the password field.  The ac-
	     count 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 speci-
	     fied, adduser will	operate	in batch mode and will not seek	any
	     user input.  If an	error is encountered while processing an ac-
	     count, it will write a message to standard	error and move to the
	     next account.  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; 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.

     -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
	     supplied 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

     -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 en-
		     ables the password.

	     none    Use an empty string as the	password.

	     yes     Use a user-supplied string	as the password.  In interac-
		     tive mode,	the user will be prompted for the password.
		     In	batch mode, the	last (10th) field in the line is as-
		     sumed 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.

     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
     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 `:' charac-
     ter as part of the	string.


     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 al-
	       phabetical 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 age-
	       ing.  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	auto-
	       matically created by appending the username to the home parti-
	       tion.  The /nonexistent home directory is considered special
	       and is understood to mean that no home directory	is to be cre-
	       ated 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 data-
	       base.  If the password type is yes and this field is empty, it
	       is assumed the account will have	an empty password.  If the
	       password	type is	random and this	field is not empty, its	con-
	       tents will be used as a password.  This field will be ignored
	       if the -p option	is used	with a no or none argument.  Be	care-
	       ful not to terminate this field with a closing `:' because it
	       will be treated as part of the password.

     /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

     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)

     The adduser command appeared in FreeBSD 2.1.

     This manual page and the original script, in Perl,	was written by Wolfram
     Schneider <>.  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 <>.

     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 eval-
     uate 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	addition, shell	special	characters and operators will have to be es-
     caped 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.

BSD			       October 19, 2007				   BSD


Want to link to this manual page? Use this URL:

home | help