1GROUPADD(8)               System Management Commands               GROUPADD(8)
2
3
4

NAME

6       groupadd - create a new group
7

SYNOPSIS

9       groupadd [OPTIONS] NEWGROUP
10

DESCRIPTION

12       The groupadd command creates a new group account using the values
13       specified on the command line plus the default values from the system.
14       The new group will be entered into the system files as needed.
15
16       Groupnames may contain only lower and upper case letters, digits,
17       underscores, or dashes. They can end with a dollar sign. Dashes are not
18       allowed at the beginning of the groupname. Fully numeric groupnames and
19       groupnames . or .. are also disallowed.
20
21       Groupnames may only be up to 32 characters long.
22

OPTIONS

24       The options which apply to the groupadd command are:
25
26       -f, --force
27           This option causes the command to simply exit with success status
28           if the specified group already exists. When used with -g, and the
29           specified GID already exists, another (unique) GID is chosen (i.e.
30           -g is turned off).
31
32       -g, --gid GID
33           The numerical value of the group's ID.  GID must be unique, unless
34           the -o option is used. The value must be non-negative. The default
35           is to use the smallest ID value greater than or equal to GID_MIN
36           and greater than every other group.
37
38           See also the -r option and the GID_MAX description.
39
40       -h, --help
41           Display help message and exit.
42
43       -K, --key KEY=VALUE
44           Overrides /etc/login.defs defaults (GID_MIN, GID_MAX and others).
45           Multiple -K options can be specified.
46
47           Example: -K GID_MIN=100  -K GID_MAX=499
48
49           Note: -K GID_MIN=10,GID_MAX=499 doesn't work yet.
50
51       -o, --non-unique
52           permits the creation of a group with an already used numerical ID.
53           As a result, for this GID, the mapping towards group NEWGROUP may
54           not be unique.
55
56       -p, --password PASSWORD
57           defines an initial password for the group account. PASSWORD is
58           expected to be encrypted, as returned by crypt (3).
59
60           Without this option, the group account will be locked and with no
61           password defined, i.e. a single exclamation mark in the respective
62           field of ths system account file /etc/group or /etc/gshadow.
63
64           Note: This option is not recommended because the password (or
65           encrypted password) will be visible by users listing the processes.
66
67           You should make sure the password respects the system's password
68           policy.
69
70       -r, --system
71           Create a system group.
72
73           The numeric identifiers of new system groups are chosen in the
74           SYS_GID_MIN-SYS_GID_MAX range, defined in login.defs, instead of
75           GID_MIN-GID_MAX.
76
77       -R, --root CHROOT_DIR
78           Apply changes in the CHROOT_DIR directory and use the configuration
79           files from the CHROOT_DIR directory. Only absolute paths are
80           supported.
81
82       -P, --prefix PREFIX_DIR
83           Apply changes to configuration files under the root filesystem
84           found under the directory PREFIX_DIR. This option does not chroot
85           and is intended for preparing a cross-compilation target. Some
86           limitations: NIS and LDAP users/groups are not verified. PAM
87           authentication is using the host files. No SELINUX support.
88
89       -U, --users
90           A list of usernames to add as members of the group.
91
92           The default behavior (if the -g, -N, and -U options are not
93           specified) is defined by the USERGROUPS_ENAB variable in
94           /etc/login.defs.
95

CONFIGURATION

97       The following configuration variables in /etc/login.defs change the
98       behavior of this tool:
99
100       GID_MAX (number), GID_MIN (number)
101           Range of group IDs used for the creation of regular groups by
102           useradd, groupadd, or newusers.
103
104           The default value for GID_MIN (resp.  GID_MAX) is 1000 (resp.
105           60000).
106
107       MAX_MEMBERS_PER_GROUP (number)
108           Maximum members per group entry. When the maximum is reached, a new
109           group entry (line) is started in /etc/group (with the same name,
110           same password, and same GID).
111
112           The default value is 0, meaning that there are no limits in the
113           number of members in a group.
114
115           This feature (split group) permits to limit the length of lines in
116           the group file. This is useful to make sure that lines for NIS
117           groups are not larger than 1024 characters.
118
119           If you need to enforce such limit, you can use 25.
120
121           Note: split groups may not be supported by all tools (even in the
122           Shadow toolsuite). You should not use this variable unless you
123           really need it.
124
125       SYS_GID_MAX (number), SYS_GID_MIN (number)
126           Range of group IDs used for the creation of system groups by
127           useradd, groupadd, or newusers.
128
129           The default value for SYS_GID_MIN (resp.  SYS_GID_MAX) is 101
130           (resp.  GID_MIN-1).
131

FILES

133       /etc/group
134           Group account information.
135
136       /etc/gshadow
137           Secure group account information.
138
139       /etc/login.defs
140           Shadow password suite configuration.
141

CAVEATS

143       You may not add a NIS or LDAP group. This must be performed on the
144       corresponding server.
145
146       If the groupname already exists in an external group database such as
147       NIS or LDAP, groupadd will deny the group creation request.
148

EXIT VALUES

150       The groupadd command exits with the following values:
151
152       0
153           success
154
155       2
156           invalid command syntax
157
158       3
159           invalid argument to option
160
161       4
162           GID is already used (when called without -o)
163
164       9
165           group name is already used
166
167       10
168           can't update group file
169

SEE ALSO

171       chfn(1), chsh(1), passwd(1), gpasswd(8), groupdel(8), groupmod(8),
172       login.defs(5), useradd(8), userdel(8), usermod(8).
173
174
175
176shadow-utils 4.13                 03/06/2023                       GROUPADD(8)
Impressum