# groupadd

## NAME



           groupadd - create a new group
    


## SYNOPSIS



    
           **groupadd**[_OPTIONS_] _NEWGROUP_
    


## DESCRIPTION



           The **groupadd** 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.
    
           Groupnames may contain only lower and upper case letters, digits,
           underscores, or dashes. They can end with a dollar sign. Dashes
           are not allowed at the beginning of the groupname. Fully numeric
           groupnames and groupnames . or .. are also disallowed.
    
           Groupnames may only be up to 32 characters long.
    


## OPTIONS



           The options which apply to the **groupadd** command are:
    
           **-f** , **--force**
               This option causes the command to simply exit with success
               status if the specified group already exists. When used with
               **-g** , and the specified GID already exists, another (unique) GID
               is chosen (i.e.  **-g** is turned off).
    
           **-g** , **--gid** _GID_
               The numerical value of the group's ID.  _GID_ must be unique,
               unless the **-o** option is used. The value must be non-negative.
               The default is to use the smallest ID value greater than or
               equal to **GID_MIN** and greater than every other group.
    
               See also the **-r** option and the **GID_MAX** description.
    
           **-h** , **--help**
               Display help message and exit.
    
           **-K** , **--key** _KEY_ =_VALUE_
               Overrides /etc/login.defs defaults (GID_MIN, GID_MAX and
               others). Multiple **-K** options can be specified.
    
               Example: **-K** _GID_MIN_ =_100_  **-K** _GID_MAX_ =_499_
    
               Note: **-K** _GID_MIN_ =_10_ ,_GID_MAX_ =_499_ doesn't work yet.
    
           **-o** , **--non-unique**
               permits the creation of a group with an already used numerical
               ID. As a result, for this _GID_ , the mapping towards group
               _NEWGROUP_ may not be unique.
    
           **-p** , **--password** _PASSWORD_
               defines an initial password for the group account. PASSWORD is
               expected to be encrypted, as returned by **crypt**(3).
    
               Without this option, the group account will be locked and with
               no password defined, i.e. a single exclamation mark in the
               respective field of ths system account file /etc/group or
               /etc/gshadow.
    
               **Note:** This option is not recommended because the password (or
               encrypted password) will be visible by users listing the
               processes.
    
               You should make sure the password respects the system's
               password policy.
    
           **-r** , **--system**
               Create a system group.
    
               The numeric identifiers of new system groups are chosen in the
               **SYS_GID_MIN** -**SYS_GID_MAX** range, defined in login.defs, instead
               of **GID_MIN** -**GID_MAX**.
    
           **-R** , **--root** _CHROOT_DIR_
               Apply changes in the _CHROOT_DIR_ directory and use the
               configuration files from the _CHROOT_DIR_ directory. Only
               absolute paths are supported.
    
           **-P** , **--prefix** _PREFIX_DIR_
               Apply changes to configuration files under the root filesystem
               found under the directory _PREFIX_DIR_. This option does not
               chroot and is intended for preparing a cross-compilation
               target. Some limitations: NIS and LDAP users/groups are not
               verified. PAM authentication is using the host files. No
               SELINUX support.
    
           **-U** , **--users**
               A comma-separated list of usernames to add as members of the
               group.
    
               The default behavior (if the **-g** , **-N** , and **-U** options are not
               specified) is defined by the **USERGROUPS_ENAB** variable in
               /etc/login.defs.
    


## CONFIGURATION



           The following configuration variables in /etc/login.defs change
           the behavior of this tool:
    
           **GID_MAX**(number), **GID_MIN**(number)
               Range of group IDs used for the creation of regular groups by
               **useradd** , **groupadd** , or **newusers**.
    
               The default value for **GID_MIN**(resp.  **GID_MAX**) is 1000 (resp.
               60000).
    
           **MAX_MEMBERS_PER_GROUP**(number)
               Maximum members per group entry. When the maximum is reached,
               a new group entry (line) is started in /etc/group (with the
               same name, same password, and same GID).
    
               The default value is 0, meaning that there are no limits in
               the number of members in a group.
    
               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.
    
               If you need to enforce such limit, you can use 25.
    
               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.
    
           **SYS_GID_MAX**(number), **SYS_GID_MIN**(number)
               Range of group IDs used for the creation of system groups by
               **useradd** , **groupadd** , or **newusers**.
    
               The default value for **SYS_GID_MIN**(resp.  **SYS_GID_MAX**) is 101
               (resp.  **GID_MIN** -1).
    


## FILES



           /etc/group
               Group account information.
    
           /etc/gshadow
               Secure group account information.
    
           /etc/login.defs
               Shadow password suite configuration.
    


## CAVEATS



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


## EXIT VALUES



           The **groupadd** command exits with the following values:
    
           _0_
               success
    
           _2_
               invalid command syntax
    
           _3_
               invalid argument to option
    
           _4_
               GID is already used (when called without **-o**)
    
           _9_
               group name is already used
    
           _10_
               can't update group file
    


* * *