1GROUPADD(8) System Management Commands GROUPADD(8)
2
6 groupadd - create a new group
7
9 groupadd [OPTIONS] NEWGROUP
10
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 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 Groupnames may only be up to 32 characters long.
22
24 The options which apply to the groupadd command are:
25 -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 -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 See also the -r option and the GID_MAX description.
39 -h, --help
41 Display help message and exit.
42 -K, --key KEY=VALUE
44 Overrides /etc/login.defs defaults (GID_MIN, GID_MAX and others).
45 Multiple -K options can be specified.
46 Example: -K GID_MIN=100 -K GID_MAX=499
48 Note: -K GID_MIN=10,GID_MAX=499 doesn't work yet.
50 -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 -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 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 Note: This option is not recommended because the password (or
65 encrypted password) will be visible by users listing the processes.
66 You should make sure the password respects the system's password
68 policy.
69 -r, --system
71 Create a system group.
72 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 -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 -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 -U, --users
90 A list of usernames to add as members of the group.
91 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
97 The following configuration variables in /etc/login.defs change the
98 behavior of this tool:
99 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 The default value for GID_MIN (resp. GID_MAX) is 1000 (resp.
105 60000).
106 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 The default value is 0, meaning that there are no limits in the
113 number of members in a group.
114 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 If you need to enforce such limit, you can use 25.
120 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 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 The default value for SYS_GID_MIN (resp. SYS_GID_MAX) is 101
130 (resp. GID_MIN-1).
131
133 /etc/group
134 Group account information.
135 /etc/gshadow
137 Secure group account information.
138 /etc/login.defs
140 Shadow password suite configuration.
141
143 You may not add a NIS or LDAP group. This must be performed on the
144 corresponding server.
145 If the groupname already exists in an external group database such as
147 NIS or LDAP, groupadd will deny the group creation request.
148
150 The groupadd command exits with the following values:
151 0
153 success
154 2
156 invalid command syntax
157 3
159 invalid argument to option
160 4
162 GID is already used (when called without -o)
163 9
165 group name is already used
166 10
168 can't update group file
169
171 chfn(1), chsh(1), passwd(1), gpasswd(8), groupdel(8), groupmod(8),
172 login.defs(5), useradd(8), userdel(8), usermod(8).
173shadow-utils 4.12.3 11/29/2022 GROUPADD(8)