1 <?xml version="1.0" encoding="UTF-8"?>
3 Copyright (c) 1991 , Julianne Frances Haugh
4 Copyright (c) 2007 - 2009, Nicolas François
7 Redistribution and use in source and binary forms, with or without
8 modification, are permitted provided that the following conditions
10 1. Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 2. Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in the
14 documentation and/or other materials provided with the distribution.
15 3. The name of the copyright holders or contributors may not be used to
16 endorse or promote products derived from this software without
17 specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
32 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
33 <!ENTITY GID_MAX SYSTEM "login.defs.d/GID_MAX.xml">
34 <!ENTITY MAX_MEMBERS_PER_GROUP SYSTEM "login.defs.d/MAX_MEMBERS_PER_GROUP.xml">
35 <!ENTITY SYS_GID_MAX SYSTEM "login.defs.d/SYS_GID_MAX.xml">
36 <!-- SHADOW-CONFIG-HERE -->
38 <refentry id='groupadd.8'>
39 <!-- $Id: groupadd.8.xml 2964 2009-05-21 12:02:12Z nekral-guest $ -->
41 <refentrytitle>groupadd</refentrytitle>
42 <manvolnum>8</manvolnum>
43 <refmiscinfo class="sectdesc">System Management Commands</refmiscinfo>
45 <refnamediv id='name'>
46 <refname>groupadd</refname>
47 <refpurpose>create a new group</refpurpose>
49 <!-- body begins here -->
50 <refsynopsisdiv id='synopsis'>
52 <command>groupadd</command>
54 <replaceable>options</replaceable>
57 <replaceable>group</replaceable>
62 <refsect1 id='description'>
63 <title>DESCRIPTION</title>
64 <para>The <command>groupadd</command> command creates a new group
65 account using the values specified on the command line plus the default
66 values from the system. The new group will be entered into the system
71 <refsect1 id='options'>
72 <title>OPTIONS</title>
74 The options which apply to the <command>groupadd</command> command
77 <variablelist remap='IP'>
80 <option>-f</option>, <option>--force</option>
84 This option causes the command to simply exit with success
85 status if the specified group already exists. When used with
86 <option>-g</option>, and the specified GID already exists,
87 another (unique) GID is chosen (i.e. <option>-g</option> is
94 <option>-g</option>, <option>--gid</option> <replaceable>GID</replaceable>
97 <para>The numerical value of the group's ID. This value must be
98 unique, unless the <option>-o</option> option is used. The value
99 must be non-negative. The default is to use the smallest ID
100 value greater than 999 and greater than every other group.
101 Values between 0 and 999 are typically reserved for system
107 <term><option>-h</option>, <option>--help</option></term>
109 <para>Display help message and exit.</para>
114 <option>-K</option>, <option>--key</option> <replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable>
118 Overrides <filename>/etc/login.defs</filename> defaults
119 (GID_MIN, GID_MAX and others). Multiple
120 <option>-K</option> options can be specified.
123 Example: <option>-K </option><replaceable>GID_MIN</replaceable>=<replaceable>100</replaceable>
124 <option>-K </option><replaceable>GID_MAX</replaceable>=<replaceable>499</replaceable>
127 Note: <option>-K </option>
128 <replaceable>GID_MIN</replaceable>=<replaceable>10</replaceable>,<replaceable>GID_MAX</replaceable>=<replaceable>499</replaceable>
135 <option>-o</option>, <option>--non-unique</option>
139 This option permits to add a group with a non-unique GID.
145 <option>-p</option>, <option>--password</option>
146 <replaceable>PASSWORD</replaceable>
150 The encrypted password, as returned by <citerefentry>
151 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
152 </citerefentry>. The default is to disable the password.
155 <emphasis role="bold">Note:</emphasis> This option is not
156 recommended because the password (or encrypted password) will
157 be visible by users listing the processes.
160 You should make sure the password respects the system's
167 <option>-r</option>, <option>--system</option>
171 Create a system group.
174 The numeric identifiers of new system groups are choosen in
175 the <option>SYS_GID_MIN</option>-<option>SYS_GID_MAX</option>
176 range, defined in <filename>login.defs</filename>, instead of
177 <option>GID_MIN</option>-<option>GID_MAX</option>.
184 <refsect1 id='configuration'>
185 <title>CONFIGURATION</title>
187 The following configuration variables in
188 <filename>/etc/login.defs</filename> change the behavior of this
192 &GID_MAX; <!-- documents also GID_MIN -->
193 &MAX_MEMBERS_PER_GROUP;
194 &SYS_GID_MAX; <!-- documents also SYS_GID_MIN -->
198 <refsect1 id='files'>
202 <term><filename>/etc/group</filename></term>
204 <para>Group account information.</para>
207 <varlistentry condition="gshadow">
208 <term><filename>/etc/gshadow</filename></term>
210 <para>Secure group account information.</para>
214 <term><filename>/etc/login.defs</filename></term>
216 <para>Shadow password suite configuration.</para>
222 <refsect1 id='caveats'>
223 <title>CAVEATS</title>
225 Groupnames must start with a lower case letter or an underscore,
226 followed by lower case letters, digits, underscores, or dashes.
227 They can end with a dollar sign.
228 In regular expression terms: [a-z_][a-z0-9_-]*[$]?
231 Groupnames may only be up to &GROUP_NAME_MAX_LENGTH; characters long.
234 You may not add a NIS or LDAP group. This must be performed on the
235 corresponding server.
238 If the groupname already exists in an external group database such
239 as NIS or LDAP, <command>groupadd</command> will deny the group
244 <refsect1 id='exit_values'>
245 <title>EXIT VALUES</title>
247 The <command>groupadd</command> command exits with the following values:
250 <term><replaceable>0</replaceable></term>
256 <term><replaceable>2</replaceable></term>
258 <para>invalid command syntax</para>
262 <term><replaceable>3</replaceable></term>
264 <para>invalid argument to option</para>
268 <term><replaceable>4</replaceable></term>
270 <para>GID not unique (when <option>-o</option> not used)</para>
274 <term><replaceable>9</replaceable></term>
276 <para>group name not unique</para>
280 <term><replaceable>10</replaceable></term>
282 <para>can't update group file</para>
289 <refsect1 id='see_also'>
290 <title>SEE ALSO</title>
292 <refentrytitle>chfn</refentrytitle><manvolnum>1</manvolnum>
295 <refentrytitle>chsh</refentrytitle><manvolnum>1</manvolnum>
298 <refentrytitle>passwd</refentrytitle><manvolnum>1</manvolnum>
301 <refentrytitle>gpasswd</refentrytitle><manvolnum>8</manvolnum>
304 <refentrytitle>groupdel</refentrytitle><manvolnum>8</manvolnum>
307 <refentrytitle>groupmod</refentrytitle><manvolnum>8</manvolnum>
310 <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
313 <refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum>
316 <refentrytitle>userdel</refentrytitle><manvolnum>8</manvolnum>
319 <refentrytitle>usermod</refentrytitle><manvolnum>8</manvolnum>