Add adding_user.8 to SEE ALSO, note that usernames may contain any character

[pw-darwin.git] / adduser / adduser.8

diff --git a/adduser/adduser.8 b/adduser/adduser.8
index 3ae61b4fe4aee8c9115b0336c9f662ade07045e5..018c164b4b4913b74c1f889f0c2ab3cc00103675 100644 (file)
--- a/adduser/adduser.8
+++ b/adduser/adduser.8
@@ -1,6 +1,6 @@
 .\" Copyright (c) 1995-1996 Wolfram Schneider <wosch@FreeBSD.org>. Berlin.
 .\" All rights reserved.
-.\" Copyright (c) 2002 Michael Telahun Makonnen <makonnen@pacbell.net>
+.\" Copyright (c) 2002-2004 Michael Telahun Makonnen <mtm@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 14, 2002
+.Dd June 7, 2006
 .Dt ADDUSER 8
 .Os
 .Sh NAME
@@ -34,11 +34,12 @@
 .Nd command for adding new users
 .Sh SYNOPSIS
 .Nm
-.Op Fl CENhq
+.Op Fl CDENShq
 .Op Fl G Ar groups
 .Op Fl L Ar login_class
 .Op Fl d Ar partition
 .Op Fl f Ar file
+.Op Fl g Ar login_group
 .Op Fl k Ar dotdir
 .Op Fl m Ar message_file
 .Op Fl s Ar shell
@@ -65,7 +66,9 @@ The user name is restricted to whatever
 .Xr pw 8
 will accept.
 Generally this means it
-may contain only lowercase characters or digits.
+may contain only lowercase characters or digits but cannot begin with
+.Sq Fl
+character.
 Maximum length
 is 16 characters.
 The reasons for this limit are historical.
@@ -76,11 +79,11 @@ such a basic fundamental parameter in
 You can change
 .Dv UT_NAMESIZE
 in
-.Pa /usr/include/utmp.h
+.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-character
-name limit and NIS.
+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
@@ -97,11 +100,13 @@ The
 .Ql \&:
 character is not allowed.
 .It shell
-Only valid shells from the shell database
+Unless the
+.Fl S
+argument is supplied 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.
+In addition,
+either the base name or the full path of the shell may be supplied.
 .It UID
 Automatically generated or your choice.
 It must be less than 32000.
@@ -118,8 +123,8 @@ 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
-safely run with a umask of 002 instead of the usual 022
+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.
 .Pp
@@ -163,6 +168,16 @@ option.
 Home partition.
 Default partition, under which all user directories
 will be located.
+The
+.Pa /nonexistent
+partition is considered special.
+The
+.Nm
+script will not create and populate a home directory by that name.
+Otherwise,
+by default it attempts to create a home directory.
+.It Fl D
+Do not attempt to create the home directory.
 .It Fl E
 Disable the account.
 This option will lock the account by prepending the string
@@ -189,10 +204,17 @@ 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 login_group
+Normaly,
+if no login group is specified,
+it is assumed to be the same as the username.
+This option makes
+.Ar login_group
+the default.
 .It Fl G Ar groups
 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.
+The user is a member of these groups in addition to their login group.
 .It Fl h
 Print a summary of options and exit.
 .It Fl k Ar directory
@@ -227,12 +249,16 @@ standard output.
 Default shell for new users.
 The
 .Ar shell
-argument must be the base name of the shell,
-.Em not
-the full path.
-It must exist in
+argument may be the base name of the shell or the full path.
+Unless the
+.Fl S
+argument is supplied the shell must exist in
 .Pa /etc/shells
+or be the special shell
+.Em nologin
 to be considered a valid shell.
+.It Fl S
+The existence or validity of the specified shell will not be checked.
 .It Fl u Ar uid
 Use UIDs from
 .Ar uid
@@ -343,9 +369,15 @@ Full name and other extra information about the user.
 Home directory.
 If this field is left empty, it will be automatically
 created by appending the username to the home partition.
+The
+.Pa /nonexistent
+home directory is considered special and
+is understood to mean that no home directory is to be
+created for the user.
 .It Ar shell
 Login shell.
-This field should contain the full path to a valid login shell.
+This field should contain either the base name or
+the full path to a valid login shell.
 .It Ar password
 User password.
 This field should contain a plaintext string, which will
@@ -395,11 +427,13 @@ logfile for
 .Sh SEE ALSO
 .Xr chpass 1 ,
 .Xr passwd 1 ,
+.Xr adduser.conf 5 ,
 .Xr aliases 5 ,
 .Xr group 5 ,
 .Xr login.conf 5 ,
 .Xr passwd 5 ,
 .Xr shells 5 ,
+.Xr adding_user 8 ,
 .Xr pw 8 ,
 .Xr pwd_mkdb 8 ,
 .Xr rmuser 8 ,
@@ -437,5 +471,6 @@ 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.
+only in batch mode or when specified in
+.Pa /etc/adduser.conf .
 The user should be able to set them in interactive mode as well.