Linux is a multi-user operating system where:

  • root is the administrator who can perform privileged operations such as configuring the system, accessing to all interfaces, installing or removing software, etc.

  • all other users are unprivileged and cannot do administrator-level operations.

Digi recommends you set a secure root password and create regular users for your applications.

Create users and groups

Digi recommends you create regular users to help protect the security of your system.

Digi Embedded Yocto creates the following specific groups:

  • digiapix: Digi APIX group to grant access to the interfaces managed by the APIs.

  • ggc_group: AWS Greengrass group (only applicable if Greengrass Core is installed in the root filesystem).

Manage accounts in a running system

Create a new user

  1. Open your device shell and log in as root. Create a new user with default options and his own group with useradd.

    ~# useradd <user_name>

    For example, to add user called digi, execute:

    ~# useradd digi

  2. Add a password to the new user with passwd.

    ~# passwd <user_name>

    For example, to set digipassword as password for digi account, issue passwd and type the password when prompted:

    ~# passwd digi
Changing password for digi
Enter the new password (minimum of 5 characters)
Please use a combination of upper and lower case letters and numbers.
New password:
Re-enter new password:
passwd: password changed.

  3. Once the new password is set, log out or reboot to log in as the new user.

Create a new group

Use the groupadd command to create a new group

~# groupadd <group_name>

Add a user to a group

Issue usermod command to modify an existing user account and add it to an existing group.

~# usermod -a -G <group_name> <user_name>

Where <user_name> is the user login name to add to the group specified in <group_name>.

Use groups to print group memberships for a specific user name.

~# groups <user_name>

For example, to add user digi to the digiapix group:

~# usermod -a -G digiapix digi
~# groups digi
digiapix digi

Remove existing users and groups

You can remove an existing user with userdel.

~# userdel -r <user_name>

For example, to remove digi user:

~# userdel -r digi

Use groupdel to remove existing groups.

~# groupdel <group_name>

Create users and groups at build time

The standard way for a recipe to add or modify system users or groups is with the useradd class:

inherit useradd

This class uses the following variables:

  • USERADD_PACKAGES specifies the output packages which include custom users/groups. For the main package, use the following:

    USERADD_PACKAGES = "${PN}"

  • USERADD_PARAM specifies the command line arguments for the Linux useradd command, to add new users to the system. You can create multiple users by separating the commands with a semicolon.

  • GROUPADD_PARAM defines the command line arguments for the Linux groupadd command, to add new groups to the system. You can create multiple groups by separating the commands with a semicolon.

  • GROUPMEMS_PARAM contains the arguments for the Linux groupmems command, which administers members of the user’s primary group.

The recipe useradd-example.bb is an example of using features from useradd class.

Example snippet of a recipe using the useradd class
inherit useradd

PASSWORD ?= "miDBHDo2hJSAA"
USERADD_PACKAGES = "${PN}"
USERADD_PARAM_${PN} = "--system --create-home \
                       --groups tty,digiapix \
                       --password ${PASSWORD} \
                       --user-group ${PN}"

You can generate the password on your host machine using the mkpasswd Linux command-line utility.

Storing a password hash instead of plain text protects critical information in case of unauthorized system access. To generate the hash of your desired password, execute the following command in your development PC and copy the output:

Development PC
~$ echo -n <password> | mkpasswd -5 -s | sed -e 's,\$,\\$,g'

For Debian-like distributions such as Ubuntu, the mkpasswd command is part of the whois package.

Development PC
~$ sudo apt-get install whois

Change root password

You can establish the root user password in one of two ways:

Set the root password on a running system

In pre-built Digi images, root user does not require a password to login to any image built with debug-tweaks. To build images with root password, see Set the root password at build time.

To create a new password for the running user:

  1. Execute the passwd command in your device shell and enter a new password.

    Device
    ~# passwd
Changing password for root
Enter the new password (minimum of 5 characters)
Please use a combination of upper and lower case letters and numbers.
New password:

  2. Once the new password is set, log out or reboot the system. The next time you login to the system, you must enter the username and established password.

    This configuration will be persistent after reboots or power cycles.

Set the root password at build time

To establish the root user password at build time, follow these steps:

  1. Generate the new password hash.

    Storing a password hash instead of plain text protects critical information in case of unauthorized system access. To generate the hash of your desired password, execute the following command in your development PC and copy the output:

    Development PC
    ~$ echo -n <password> | mkpasswd -5 -s | sed -e 's,\$,\\$,g'

    For Debian-like distributions such as Ubuntu, the mkpasswd command is part of the whois package.

    Development PC
    ~$ sudo apt-get install whois

  2. Edit the local.conf file of your project to add the following lines:

    local.conf
    # Change the root password: (specify its MD5)
MD5_ROOT_PASSWD = "<password_hash_output>"

  3. Remove the debug-tweaks feature in your local.conf by commenting the following line:

    local.conf
    # We default to enabling the debugging tweaks.
#EXTRA_IMAGE_FEATURES ?= "debug-tweaks"

  4. Rebuild your project and upload the new root file system to the target.

  5. The next time you log in to the system, you must enter the username and established root password.

Managing network privileges

Managing network connections is typically something only a user with administrator privileges can do. However, you can also enable a regular user or group to manage network connections:

NetworkManager privileges

Most network interfaces are handled by the NetworkManager daemon. NetworkManager uses polkit, a toolkit for defining and handling authorizations, to manage how users and groups access the network interfaces. Polkit uses a set of rules to determine who has access to different resources and actions.

For example, the meta-openembedded layer contains a recipe polkit-group-rule-network.bb that:

  1. Creates a group called network.

  2. Adds a polkit rules file to give users of this group the permission to mofify NetworkManager settings.

    50-org.freedesktop.NetworkManager.rules
    /* give group 'network' rights to change settings */
/* taken from https://wiki.archlinux.org/index.php/NetworkManager#Set_up_PolicyKit_permissions */

polkit.addRule(function(action, subject) {
  if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {
    return polkit.Result.YES;
  }
});

You can add this recipe to your root file system or define your specific users, groups, and privileges using a similar approach. See the polkit documentation for additional information on this tool.

Bluetooth privileges

Bluetooth security policies are handled via the configuration file /etc/dbus-1/system.d/bluetooth.conf.

For example, to allow users of a group called bluetooth to do certain actions on the Bluetooth, add the following to the configuration file:

/etc/dbus-1/system.d/bluetooth.conf
  <policy group="bluetooth">
    <allow own="org.bluez"/>
    <allow send_destination="org.bluez"/>
    <allow send_interface="org.bluez.GattCharacteristic1"/>
    <allow send_interface="org.bluez.GattDescriptor1"/>
    <allow send_interface="org.bluez.LEAdvertisement1"/>
    <allow send_interface="org.freedesktop.DBus.ObjectManager"/>
    <allow send_interface="org.freedesktop.DBus.Properties"/>
  </policy>

This is just an example. See BlueZ documentation for additional BlueZ D-Bus API interfaces.