How to use the groupadd Command in Linux

In this tutorial, we cover the basics of using the groupadd command on a Linux operating system.

The groupadd command is incredibly useful for creating new user groups on a Linux-based distribution. Groups are an effective tool for controlling permissions across a large set of users. You will likely have to manage groups if you administrate a multi-user system.

There are many other Linux commands that you can use for user administration. For example, you might also want to look at usermod, useradd, passwd, and userdel. They will all help with creating and modifying users.

This tutorial will take you through most of the basics of using the groupadd command. We touch on the syntax, options, and go through several examples of using the command to create new groups on a Linux distribution.

Table of Contents

• groupadd command Syntax
• groupadd command Options
• Using the groupadd Command
  • Create a Group
  • Create a Group using a GID
    • Using a Non-Unique GID
  • Create a System Group
  • Override the Default GID Ranges
• More Help
• Conclusion

groupadd Command Syntax

The syntax of the groupadd command is very straightforward. The command accepts two separate parameters, the first is options, and the second is the group name.

groupadd [OPTIONS] GROUP

• [OPTIONS] is where you will need to specify any additional options you want to be applied to the command. We touch on some of the options that you can use later in this tutorial.
• GROUP is the name of the group you wish to create

groupadd Command Options

There are a few different options that you can use with this command. It is unlikely that you will need to use most of them, but they may come in handy eventually.

• -f or --force will force the command to exit with success even when a group already exists. If you are using -g and the specified GID (group id) already exists, then the command will choose a unique GID instead.
• -g or --gid GID is the number value for the group. The number must be positive and unique. If used alongside the -o option, you can use a non-unique value.
• -o or --non-unique allows for a non-unique GID when used alongside the -g or --gid options.
• -K or --key KEY=VALUE allows you to override the /etc/login.defs defaults. You can use multiple -K options to cover different settings. You can override settings such as GID_MIN, GID_MAX, and MAX_MEMBERS_PER_GROUP.
• -p or --password PASSWORD will create an encrypted password returned by crypt. This option is not recommended as the password will be visible by users listing processes.
• -r or --system allows you to create a system group. The system group number is chosen within the range defined in the login.defs. (SYS_GID_MIN – SYS_GID_MAX)
• -R or --root applies the changes in the CHROOT_DIR directory and uses configuration files from within the same directory.
• -P or --prefix applies the changes in the PREFIX_DIR directory and uses configuration files from within the same directory. Does not support SELinux (Security-Enhanced Linux).

Command Exit Codes

The groupadd command has several exit codes that indicate either success or an issue. Below are the values that you might get when you run the command.

• 0 Success
• 2 Invalid command syntax
• 3 invalid argument to option
• 4 GID not unique
• 9 Group name not unique
• 10 Can’t update group file

Using the groupadd Command

This section will take you through a few examples of how you can use this command to create new groups. You will want to use the groupmod command to modify an existing group.

You must have sufficient user rights when you run the groupadd command; otherwise, you will see permission errors. So, you must have superuser rights (sudo) or be the root user.

Create a Group

In this example, we will create a group with the name testGroup. You will need to have super user privileges.

sudo groupadd testGroup

To confirm that the command was successful, we can use echo $?. This command will provide an exit code that we can cross-reference with the command’s exit codes.

dev@pimylifeup:~$ echo $?
0

Alternatively, you can search through the /etc/group file to see if groupadd created the group successfully. To search the file, we will use grep followed by our group name and the group file.

dev@pimylifeup:~$ grep "testGroup" /etc/group
testGroup:x:1003:

Create a Group using a GID

If you want your new group to have a specific GID (group id), you can specify this in the command by using the -g or --gid options.

The value you specify needs to be unique and not already used as a GID. It will also need to be a positive number as you cannot have a negative GID.

In the example below, we create a new group with the GID of 2022.

sudo groupadd -g 2022 gidTest

In the output below, we check the command exit code by using echo $? and search the /etc/group file. The last line shows that our group has the correct GID.

sudo groupadd -g 2022 gidTest
echo $?
0
grep "gidTest" /etc/group
gidTest:x:2022:

Using a Non-Unique GID

If you want to give the new group a GID already used by another group, you will need to use the -o or --non-unique options.

In the example below, we create a new group using the same id as the user we created above.

sudo groupadd -o -g 2022 gidNewTest

You can see in the output below we now have two groups that share the same GID.

dev@pimylifeup:~$ echo $?
0
dev@pimylifeup:~$ grep "2022" /etc/group
gidTest:x:2022:
gidNewTest:x:2022:

Create a System Group

There is no difference between a regular group and a system group other than for administration purposes.

A system group will be assigned a GID within a different range from a regular group. These ranges are within the login.defs file and can be overridden.

To create a new system group, simply use the -r or --system options with the groupadd command.

sudo groupadd --system sysUser

Our output shows that our system group was created successfully and has a different GID than what you would get if you were to create a regular group.

dev@pimylifeup:~$ echo $?
0
dev@pimylifeup:~$ grep "sysUser" /etc/group
sysUser:x:998:

Override the Default GID Ranges

If you want to temporally override the GID default ranges defined in the /etc/login.defs file, you can use the -K or --key options. You can use these options multiple times within the same command.

In the example below, we alter the range minimum GID range (GID_MIN) and maximum GID range (GID_MAX).

sudo groupadd -K GID_MIN=1050 -K GID_MAX=1060 exampleGroup

As you can see in our output below, the exit code is 0, which means success, and our new group is within the range we defined using the -K option.

dev@pimylifeup:~$ echo $?
0
dev@pimylifeup:~$ grep "exampleGroup" /etc/group
exampleGroup:x:1050:

More Help

You can get additional help for using this command in a couple of different ways. We will touch on the two easiest methods, which are built into most Linux operating systems.

The first method is to use the man command. The man tool will bring up the manual pages for the given command.

man groupadd

To exit the manual pages, simply press the q key.

The other method is to use the commands inbuilt help documentation. You can use the -h or --help option to load this information into the terminal.

groupadd --help

I hope either of the above methods has the information that you require.

Conclusion

I hope by now, you have a decent understanding of how to use the groupadd command to create new groups on a Linux operating system. In addition, we have touched on several different options that you can use to alter the command’s behavior.

If you are new to Linux and want to learn more, I recommend checking out the many other Linux command tutorials. For example, you might want to learn about the useradd command for adding new users or the usermod command for editing existing users.

Please let us know if you notice a mistake or an important topic is missing from this guide.

Weekly Updates Straight To Your Inbox

Receive our Raspberry Pi projects, coding tutorials, Linux guides and more!

Subscribe