man/groupadd.8

   1 '\" t
   2 .\"     Title: groupadd
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 02/16/2011
   6 .\"    Manual: System Management Commands
   7 .\"    Source: System Management Commands
   8 .\"  Language: English
   9 .\"
  10 .TH "GROUPADD" "8" "02/16/2011" "System Management Commands" "System Management Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 groupadd \- create a new group
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBgroupadd\fR\ 'u
  34 \fBgroupadd\fR [\fIoptions\fR] \fIgroup\fR
  35 .SH "DESCRIPTION"
  36 .PP
  37 The
  38 \fBgroupadd\fR
  39 command creates a new group account using the values specified on the command line plus the default values from the system\&. The new group will be entered into the system files as needed\&.
  40 .SH "OPTIONS"
  41 .PP
  42 The options which apply to the
  43 \fBgroupadd\fR
  44 command are:
  45 .PP
  46 \fB\-f\fR, \fB\-\-force\fR
  47 .RS 4
  48 This option causes the command to simply exit with success status if the specified group already exists\&. When used with
  49 \fB\-g\fR, and the specified GID already exists, another (unique) GID is chosen (i\&.e\&.
  50 \fB\-g\fR
  51 is turned off)\&.
  52 .RE
  53 .PP
  54 \fB\-g\fR, \fB\-\-gid\fR \fIGID\fR
  55 .RS 4
  56 The numerical value of the group\*(Aqs ID\&. This value must be unique, unless the
  57 \fB\-o\fR
  58 option is used\&. The value must be non\-negative\&. The default is to use the smallest ID value greater than 999 and greater than every other group\&. Values between 0 and 999 are typically reserved for system accounts\&.
  59 .RE
  60 .PP
  61 \fB\-h\fR, \fB\-\-help\fR
  62 .RS 4
  63 Display help message and exit\&.
  64 .RE
  65 .PP
  66 \fB\-K\fR, \fB\-\-key\fR \fIKEY\fR=\fIVALUE\fR
  67 .RS 4
  68 Overrides
  69 /etc/login\&.defs
  70 defaults (GID_MIN, GID_MAX and others)\&. Multiple
  71 \fB\-K\fR
  72 options can be specified\&.
  73 .sp
  74 Example:
  75 \fB\-K \fR\fIGID_MIN\fR=\fI100\fR
  76 \fB\-K \fR\fIGID_MAX\fR=\fI499\fR
  77 .sp
  78 Note:
  79 \fB\-K \fR
  80 \fIGID_MIN\fR=\fI10\fR,\fIGID_MAX\fR=\fI499\fR
  81 doesn\*(Aqt work yet\&.
  82 .RE
  83 .PP
  84 \fB\-o\fR, \fB\-\-non\-unique\fR
  85 .RS 4
  86 This option permits to add a group with a non\-unique GID\&.
  87 .RE
  88 .PP
  89 \fB\-p\fR, \fB\-\-password\fR \fIPASSWORD\fR
  90 .RS 4
  91 The encrypted password, as returned by
  92 \fBcrypt\fR(3)\&. The default is to disable the password\&.
  93 .sp
  94
  95 \fBNote:\fR
  96 This option is not recommended because the password (or encrypted password) will be visible by users listing the processes\&.
  97 .sp
  98 You should make sure the password respects the system\*(Aqs password policy\&.
  99 .RE
 100 .PP
 101 \fB\-r\fR, \fB\-\-system\fR
 102 .RS 4
 103 Create a system group\&.
 104 .sp
 105 The numeric identifiers of new system groups are choosen in the
 106 \fBSYS_GID_MIN\fR\-\fBSYS_GID_MAX\fR
 107 range, defined in
 108 login\&.defs, instead of
 109 \fBGID_MIN\fR\-\fBGID_MAX\fR\&.
 110 .RE
 111 .SH "CONFIGURATION"
 112 .PP
 113 The following configuration variables in
 114 /etc/login\&.defs
 115 change the behavior of this tool:
 116 .PP
 117 \fBGID_MAX\fR (number), \fBGID_MIN\fR (number)
 118 .RS 4
 119 Range of group IDs used for the creation of regular groups by
 120 \fBuseradd\fR,
 121 \fBgroupadd\fR, or
 122 \fBnewusers\fR\&.
 123 .RE
 124 .PP
 125 \fBMAX_MEMBERS_PER_GROUP\fR (number)
 126 .RS 4
 127 Maximum members per group entry\&. When the maximum is reached, a new group entry (line) is started in
 128 /etc/group
 129 (with the same name, same password, and same GID)\&.
 130 .sp
 131 The default value is 0, meaning that there are no limits in the number of members in a group\&.
 132 .sp
 133 This feature (split group) permits to limit the length of lines in the group file\&. This is useful to make sure that lines for NIS groups are not larger than 1024 characters\&.
 134 .sp
 135 If you need to enforce such limit, you can use 25\&.
 136 .sp
 137 Note: split groups may not be supported by all tools (even in the Shadow toolsuite)\&. You should not use this variable unless you really need it\&.
 138 .RE
 139 .PP
 140 \fBSYS_GID_MAX\fR (number), \fBSYS_GID_MIN\fR (number)
 141 .RS 4
 142 Range of group IDs used for the creation of system groups by
 143 \fBuseradd\fR,
 144 \fBgroupadd\fR, or
 145 \fBnewusers\fR\&.
 146 .RE
 147 .SH "FILES"
 148 .PP
 149 /etc/group
 150 .RS 4
 151 Group account information\&.
 152 .RE
 153 .PP
 154 /etc/gshadow
 155 .RS 4
 156 Secure group account information\&.
 157 .RE
 158 .PP
 159 /etc/login\&.defs
 160 .RS 4
 161 Shadow password suite configuration\&.
 162 .RE
 163 .SH "CAVEATS"
 164 .PP
 165 Groupnames must start with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes\&. They can end with a dollar sign\&. In regular expression terms: [a\-z_][a\-z0\-9_\-]*[$]?
 166 .PP
 167 Groupnames may only be up to characters long\&.
 168 .PP
 169 You may not add a NIS or LDAP group\&. This must be performed on the corresponding server\&.
 170 .PP
 171 If the groupname already exists in an external group database such as NIS or LDAP,
 172 \fBgroupadd\fR
 173 will deny the group creation request\&.
 174 .SH "EXIT VALUES"
 175 .PP
 176 The
 177 \fBgroupadd\fR
 178 command exits with the following values:
 179 .PP
 180 \fI0\fR
 181 .RS 4
 182 success
 183 .RE
 184 .PP
 185 \fI2\fR
 186 .RS 4
 187 invalid command syntax
 188 .RE
 189 .PP
 190 \fI3\fR
 191 .RS 4
 192 invalid argument to option
 193 .RE
 194 .PP
 195 \fI4\fR
 196 .RS 4
 197 GID not unique (when
 198 \fB\-o\fR
 199 not used)
 200 .RE
 201 .PP
 202 \fI9\fR
 203 .RS 4
 204 group name not unique
 205 .RE
 206 .PP
 207 \fI10\fR
 208 .RS 4
 209 can\*(Aqt update group file
 210 .RE
 211 .SH "SEE ALSO"
 212 .PP
 213 \fBchfn\fR(1),
 214 \fBchsh\fR(1),
 215 \fBpasswd\fR(1),
 216 \fBgpasswd\fR(8),
 217 \fBgroupdel\fR(8),
 218 \fBgroupmod\fR(8),
 219 \fBlogin.defs\fR(5),
 220 \fBuseradd\fR(8),
 221 \fBuserdel\fR(8),
 222 \fBusermod\fR(8)\&.