Setting up a new user
This page shows how to create non-privileged user accounts. i.e. those used for daily work, including desktop use and remote logins, and how to grant admin access to such accounts if needed. The inbuilt root account should be used only for local administrative purposes that require elevated access permissions. Diskless mode users may want to refer to the section Persistent Home directory.
User management
Creating regular or non-privileged user accounts provides users with their own $HOME directory and adding to appropriate groups allows root account to limit the access those user accounts have to the operating system configuration files. Using them increases security, because they limit possible actions and thus possible damage even from accidental errors. Refer to Groups for desktop usage section, if applicable.
setup-user
script provides a quick and simple way to setup regular and Admin user accounts in Alpine Linux.To create an user <username> issue the command:
# adduser [-g <Full Name>] <username>
By default, adduser
will:
- prompt you to set a password for the new user
- create a home directory in /home/<username>
- set the shell to the one used by the
root
account (ash by default) - assign user ID and group ID starting at 1000
- set the GECOS field to <username>, if -g <Full Name> is not specified
-g <Full Name>
can be very useful. Setting this string - at least equal to the username - makes the user distinguishable, e.g. when they are listed at the login screen of a Display manager.For complete options, issue adduser --help.
The new user gets listed at the last line:
Contents of /etc/passwd
Now you should be able to issue the command exit
to logout from a TTY and login to the newly created account.
To delete an user <username> from the system, issue the command:
# deluser [--remove-home] <username>
Using the option --remove-home
deletes home directory /home/<username>.
setup-user
To create a regular user account, use the setup-user script and follow the prompts for options:
# setup-user
Group management
To see what group(s) one belong to, command $ groups
can be used. To check what group(s) another user belongs to:
$ groups <username>
Adding an user to a group can be done in the following ways using the inbuilt tools:
- To add an user <username> to a group (for e.g seat), use the following command:
# addgroup <username> seat
- To add the currently logged in user to a group (for e.g seat) using doas, issue the command:
$ doas addgroup $USER seat
- Using a variation of adduser command, the same can be done as follows:
# adduser <username> seat (or) $ doas adduser $USER seat
Removing an user from a group can be done in the following ways using the inbuilt tools:
- To remove an user <username> from a group (for e.g seat), use the following command:
# delgroup <username> seat
- To remove the currently logged in user from a group (for e.g seat) Using doas, issue the command:
$ doas delgroup $USER seat
Groups for desktop usage
For desktop users not using elogind as Seat manager and need PipeWire to access a webcam, the user needs to be in video group. For users that want a X11 based desktop without a Seat manager, the user needs to be in both input and video groups to ensure proper keyboard, mouse, and display functionality.
As noted in #15409, adding users to the video has negative security concerns.
To add all newly created users to groups that may come in handy for desktop usage, you can run the below command as root:
# for u in $(ls /home); do for g in disk lp input audio cdrom dialout video netdev games users; do addgroup $u $g; done;done
Please pay attention to the groups in above command and proceed only if you want to add all the users in your system to above groups.
root account
The root account is the most privileged account on a Unix system. The "root" account has no security restrictions imposed upon it. When you are signed in as, or acting as "root", the shell prompt displays '#' as the last character. This is to serve as a warning to you of the absolute power of this account.
Wheel group
The wheel group provides a mechanism to grant users administrator-level i.e root privileges without them needing to log in as the root user directly. The doas utility must be installed and configured, so that admin users i.e members of the wheel group, can execute commands that require root privileges without needing to know the root password.
SSH root login
For security reasons, root account is provided with local log-in access only and SSH login is disabled by default. To change this, edit the file /etc/ssh/sshd_config and add PermitRootLogin yes. Restart the sshd service
for the change to take effect immediately.
Securing root account
Creating admin user is recommended to enable logging of administrative actions.
Admin user
A regular user can be considered as an Admin user, if the user belongs to wheel group. The setup-user script allows setup of new admin user accounts by adding the <username> to wheel group and also installs doas package, if not already installed:
# setup-user -a <username>
To provide admin user privileges to an existing user, add him to the wheel group as follows:
# adduser <username> wheel
doas
doas
is a simplified and lightweight utility that provides a way to execute commands as another user. Install the doas package:
# apk add doas
For more information about doas configuration details, check out the doas(1)
, doas.conf(5)
and doas.d(5)
manpages, which you can install with the doas-doc package.
Configuration in the default config file /etc/doas.conf may be overridden by /etc/doas.d/*.conf if files exist.
To allow the members of the wheel group to use root privileges with doas
command, a config file /etc/doas.d/20-wheel.conf can be created as follows:
Contents of /etc/doas.d/20-wheel.conf
sudo
Sudo (su “do”) allows a system administrator to delegate authority to give certain users (or groups of users) the ability to run some (or all) commands as root or another user while providing an audit trail of the commands and their arguments.
Sudo may be used as follows:
# apk add sudo # NEWUSER='yourUserName' # adduser -g "${NEWUSER}" $NEWUSER # echo "$NEWUSER ALL=(ALL) ALL" > /etc/sudoers.d/$NEWUSER && chmod 0440 /etc/sudoers.d/$NEWUSER
Here a custom user configuration file i.e /etc/sudoers.d/$NEWUSER is used to avoid having to deal with manually changing configuration files later during package upgrades.
Editing administrative files
It's recommended to not run complete applications, like editors, as root just to modify administrative files.
- If doas is used, use
doasedit
utility from the doasedit package available in the testing repository. It can be safely installed by following the guidelines. - If using sudo,
sudoedit
can be used.
These tools enables starting an editor with a temporary copy of a file, which overwrites the original file after the user modifies and saves it. For example, doasedit /etc/apk/lbu.conf
- Many desktop environments and file browsers support using
admin:///
in their address bars, to access files through a local gvfs-admin mount.
Locking the root account
Once an admin user is created with either doas or sudo properly configured and tested thoroughly, root account can be disabled by locking it.

To lock the root account you need to log into your root account and then lock it using the passwd
command:
# passwd -l root
Home directory permissions
`adduser` creates home directories with permissions `rwxr-sr-x`. This makes the directory readable by all other users on the system. If you prefer to not allow other users to read your home directory, the permissions can be changed:
$ chmod o-rx <path-to-directory>
If --ingroup isn't set, (default) the new user is assigned a new GID that matches the UID. If the GID corresponding to a provided UID already exists, adduser will fail.
This ensures new users default to having a "user's private group" (UPG) as primary group. These allow the system to use a permission umask (002), which creates new files automatically as group-writable, but only by the user's private group. In special set-group-id (collaboration) directories, new files can be automatically created writable by the directory's group.
Persistent home directory
If using a "diskless" or "data" disk mode installation, it's important to make the /home
directory persistent:
- Either the
/home
filesystem needs to be mounted from a writable partition, or - the /home directories have to be added to the lbu backup, and a new local backup needs to be committed after creating the user:
# lbu include /home # lbu commit
Common permission groups
The following groups are needed for certain operations on your system. The group names were taken from https://git.alpinelinux.org/alpine-baselayout/tree/group
adm Used for system monitoring tasks. disk Raw access to disks. Mostly equivalent to root access. lp Members of this group can enable and use printers. wheel Administrator group, members can use doas to run commands as root if enabled in the doas configuration. floppy Access to floppy drives and other removable (non-optical) drives (like USB flash drives). audio Direct access to sound hardware (the soundcard or a microphone). cdrom For access to disk writers and mounting DVD, BR or CD-ROM disk as normal user. dialout Full and direct access to serial ports. input Privileged access to input devices (not recommended on Wayland desktops). seat Access to input and output devices via seatd. tape Needed to give a set of users access to a tape drive. video Access to video capture devices (like a webcam) and privileged access to GPU devices. netdev For network connections management as normal user. kvm Needed to use the KVM acceleration of virtual machines. games Access to some game software. cdrw Needed to write RW-DVD, RW-BR or RW-CD disk on a disk writing device. usb Needed to access special USB devices, deprecated group. users Needed if you plan to used common files for all users, mandatory for desktop usage.
Refer Debian/wiki SystemGroups to understand about the security implications of all these groups.