Skip to content

User Management

This tutorial demonstrates how to manage users in Edge Builder. It covers how to:

Initialise the Edge Builder server components and CLI

To initialize the Edge Builder server components and CLI, complete the following steps:

  1. Set up the environment as described in Tutorials Setup

  2. SSH into the master node:

    vagrant ssh master
    

  3. Start the Edge Builder server components using the following command:

    sudo edgebuilder-server up -a 192.168.56.10
    

Login as admin user

Edge Builder comes with a default user account, which has admin permissions. In this tutorial, we use this account to create new users and manage your team.

Login to the admin account using the following default credentials and the address of the controller:

edgebuilder-cli user login -u iotech -p EdgeBuilder123 -c "http://192.168.56.10:8085"
The following message displays:
INFO: User "iotech" logged in successfully

  • Confirm that you have a valid license in the Vagrant project directory (edgebuilder-vagrant)
  • Add the license using the following command:
    edgebuilder-cli license add -l DemoLicense -f /vagrant/EdgeBuilder_test_Evaluation.lic
    
    You should see the output similar to that shown below:
    INFO: License added successfully
    +-------------+--------------------------------------+---------------------------------+-----------+-----------+
    | NAME        | ID                                   | FILENAME                        | MAX NODES | EXPIRY    |
    +-------------+--------------------------------------+---------------------------------+-----------+-----------+
    | DemoLicense | b65c2ba0-c78b-4031-aaf4-cc030d3d763d | EdgeBuilder_test_Evaluation.lic | 100       | unlimited |
    +-------------+--------------------------------------+---------------------------------+-----------+-----------+
    INFO: Viewing 1 result(s)
    

Add a node

In this section, we add a node to Edge Builder. It is accessible on 192.168.56.11.

To add an edge node, complete the following steps:

  1. Confirm that the example node configuration file is available using the cat command:

    cat /vagrant/examples/single-node-config.json
    
    The output is similar to the following:
    {
      "NodeConfig": [
        {
          "name": "node1",
          "description": "virtual node 1",
          "nodeaddress": "192.168.56.11",
          "nodesshport": "22",
          "username" : "vagrant",
          "password" : "vagrant",
          "serveraddress": "192.168.56.10",
          "labels" : ["label1", "label2"]
        }
      ]
    }
    

  2. Add the node to Edge Builder using the following command:

     edgebuilder-cli node add -f /vagrant/examples/single-node-config.json
    
    The output is similar to the following:
    INFO: SSH Node(s) added successfully:
    +-------+--------------------------------------+----------------+
    | NODE  | ID                                   | LABELS         |
    +-------+--------------------------------------+----------------+
    | node1 | 4ce8c47a-46c4-40fb-b1ed-71351933ce0b | label1, label2 |
    +-------+--------------------------------------+----------------+
    INFO: Viewing 1 result(s)
    

  3. Confirm that the node has been added using the following command:

    edgebuilder-cli node view --all
    
    The output is similar to the following:
    INFO: Finding all nodes...
    INFO: *** Node View Results ***
    +-------+----------+------------+--------------+----------------+--------------------------------------+
    | NAME  |  STATUS  | DEBUG MODE | METRICS MODE | DESCRIPTION    | ID                                   |
    +-------+----------+------------+--------------+----------------+--------------------------------------+
    | node1 | Deploying| Off        | Local        | virtual node 1 | 4ce8c47a-46c4-40fb-b1ed-71351933ce0b |
    +-------+----------+------------+--------------+----------------+--------------------------------------+
    INFO: Viewing 1 result(s)
    

    Note

    • The status of the node is initially shown as Deploying. After a few minutes, you can re-issue the command and the status will have changed to Up
    • You can also use the watch command with the node view above to automatically track the status changes

Add a new user to Edge Builder

  1. Add a new user to Edge Builder using the user add command. The new username must be unique and contain only alphanumeric, space, _ and - characters (no spaces). The password must be at least 8 characters in length and contain non-space characters only. For example:
    edgebuilder-cli user add --username edge_user --password p@ssw*rd123!
    
    The following message displays (however the ID will be different):
    INFO: User created:
    +-----------+--------------------------------------+-------+
    | NAME      | ID                                   | ROLES |
    +-----------+--------------------------------------+-------+
    | edge_user | 936a63a8-8efd-4904-8dd7-3f718abc608c |       |
    +-----------+--------------------------------------+-------+
    INFO: Viewing 1 result(s)
    
  2. Verify the new user exists with the command:
    edgebuilder-cli user view -A
    
    Example output:
    INFO: Finding all users...
    INFO: *** User View Results ***
    +---------------------+--------------------------------------+---------------------+-----------------+
    | NAME                | ID                                   | ROLE(S)             | NO. PERMISSIONS |
    +---------------------+--------------------------------------+---------------------+-----------------+
    | eb_provisioner_user | 8cf6cd1c-e6c4-4652-b293-9ab6ea4a8c99 | eb_provisioner_role |               1 |
    | eb_salt_user        | 88e403ff-fad8-464b-8b73-53f2bdb1b598 | eb_salt_role        |               1 |
    | edge_user           | 936a63a8-8efd-4904-8dd7-3f718abc608c | <none>              |               0 |
    | iotech              | de1abbc4-8e77-4c08-b034-f1921458668f | eb_admin_role       |              88 |
    +---------------------+--------------------------------------+---------------------+-----------------+
    INFO: Viewing 4 result(s)
    
    You will see at least three users: iotech (the current user), eb_salt_user (used for internal processing only) and the new edge_user.

Note

edge_user has no roles or permissions yet, we will assign the user a role in the next section, so they can begin using Edge Builder.

Assign the user a role

  1. By default, new users have no permissions in EdgeBuilder. Assign edge_user the Edge Builder standard role to give grant read-only permissions:

    edgebuilder-cli user role -u edge_user -r eb_standard_role --add
    
    The response is similar to the following:
    INFO: added 1 role(s) to user "edge_user" (ID = 936a63a8-8efd-4904-8dd7-3f718abc608c)
    

  2. Verify the role assignment was successful with the user inspect command:

    edgebuilder-cli user inspect -u edge_user
    
    The response provides detailed information on the user, with any role(s) and associated permissions displayed within embedded fields. In the example below, the list of permissions has been shortened for readability:
    {
      "CreatedBy": "iotech",
      "ID": "936a63a8-8efd-4904-8dd7-3f718abc608c",
      "ModifiedBy": "iotech",
      "Roles": [
        {
          "CreatedBy": "EdgeBuilder",
          "Description": "EdgeBuilder standard role - read-only permissions (protected) ",
          "ID": "b12092cf-b63c-4a47-8708-c1e28d29e11a",
          "ModifiedBy": "EdgeBuilder",
          "Name": "eb_standard_role",
          "Permissions": [
            {
              "CreatedBy": "EdgeBuilder",
              "ID": "0021703c-9155-4756-8101-15903547e1fb",
              "Method": "GET",
              "Name": "AppConfigFileInspect",
              "Path": "/api/v1/app_configs/files/inspect/{id}",
              "TimestampCreate": 1646674176
            },
            .
            .
            .
            {
              "CreatedBy": "EdgeBuilder",
              "ID": "fbd1477b-5b6c-4d89-8da1-02add53d861a",
              "Method": "GET",
              "Name": "AppList",
              "Path": "/api/v1/apps",
              "TimestampCreate": 1646674176
            }
          ],
          "TimestampCreate": 1646674176,
          "TimestampModify": 1646730489
        }
      ],
      "TimestampCreate": 1646744341,
      "TimestampModify": 1646744472,
      "Username": "edge_user"
    }
    

Issue commands as new user

The user edge_user is now ready to begin using Edge Builder. Try issuing some commands from their account.

  1. Log-in using the relevant credentials and the same controller address as before:
    edgebuilder-cli user login -u edge_user -p p@ssw*rd123! -c "http://192.168.56.10:8085"
    
    Expected Output:
    INFO: User "edge_user" logged in successfully
    
  2. Try viewing nodes:

    edgebuilder-cli node view --all
    
    The request is successful because eb_standard_role includes the GET /api/v1/nodes permission. Example output:
    INFO: Finding all nodes...
    INFO: *** Node View Results ***
    +-------+--------------------------------------+---------+------------+--------------+------------------------------------------+----------------+
    | NAME  | ID                                   | STATUS  | DEBUG MODE | METRICS MODE | LABELS                                   | DESCRIPTION    |
    +-------+--------------------------------------+---------+------------+--------------+------------------------------------------+----------------+
    | node1 | 81b5b8fe-ebba-42bf-b301-df1aa872aba3 | Up      | Off        | Live         | CPUModel:11thGenIntel(R)Core(TM)i7-11800 | virtual node 1 |
    |       |                                      |         |            |              | H@2.30GHz, Language:en_US, label1, OSArc |                |
    |       |                                      |         |            |              | h:amd64, OSFinger:Ubuntu-20.04, CPUArch: |                |
    |       |                                      |         |            |              | x86_64, OSFamily:Debian, GroupName:root, |                |
    |       |                                      |         |            |              |  label2, Manufacturer:innotekGmbH, Virtu |                |
    |       |                                      |         |            |              | al:VirtualBox, Timezone:UTC, Kernel:Linu |                |
    |       |                                      |         |            |              | x, UserName:root, ProductName:VirtualBox |                |
    |       |                                      |         |            |              | , Hostname:node1                         |                |
    +-------+--------------------------------------+---------+------------+--------------+------------------------------------------+----------------+
    INFO: Viewing 1 result(s)
    

  3. To illustrate what happens when a user tries to execute a command without sufficient API permissions, try to add a new user:

    edgebuilder-cli user add --username edge_user2 --password p@ssw*rd123!
    
    The permission for adding users is not included in eb_standard_role so this error displays:
    ERROR: Exit Code (156): user create failed - unexpected StatusCode: "403 Forbidden" - {"err":"Insufficient Permissions Error - user 'edge_user' does not have POST /api/v1/users permissions"}
    

Add a new role

The default Edge Builder roles may not be sufficient to cover the unique requirements of your team. The sections cover how to create your own, customisable roles. As an example, you will create a role for managing App Definitions.

  1. Log-in as the admin user:
    edgebuilder-cli user login -u iotech -p EdgeBuilder123 -c "http://192.168.56.10:8085"
    
    Expected response:
    INFO: User "iotech" logged in successfully
    
  2. Create the role with a suitable name and description (both fields required), for example:
    edgebuilder-cli role add --role AppDefRole --description "Role for managing app defnitions"
    
    The response is similar to the following:
    INFO: Role(s) created:
    +------------+--------------------------------------+
    | NAME       | ID                                   |
    +------------+--------------------------------------+
    | AppDefRole | c32e4cc9-f863-4611-ad1e-11be624603e7 |
    +------------+--------------------------------------+
    INFO: Viewing 1 result(s)
    

Add permissions to role(s)

  1. To grant permissions to the new role, collect the permission IDs with the permission view command. You can view all permissions relating to app definitions using a wildcard in the argument of the --path flag:
    edgebuilder-cli permission view --path "/api/v1/app_definitions*"
    
    The permissions below define the actions of creating, deleting, inspecting and viewing app definitions in Edge Builder.

INFO: Finding permissions with path(s): ["/api/v1/app_definitions*"]
INFO: *** Permission View Results ***
+---------------+--------------------------------------+--------+--------------------------------------+
| NAME          | ID                                   | METHOD | PATH                                 |
+---------------+--------------------------------------+--------+--------------------------------------+
| AppDefInspect | 38893ff4-32ed-4678-8700-5ce94868539d | GET    | /api/v1/app_definitions/inspect/{id} |
| AppDefUpdate  | 541d47f9-4b8b-45df-af6b-170c895b9f8a | PATCH  | /api/v1/app_definitions/{id}         |
| AppDefDelete  | 9c043cfa-bdb4-409b-9039-d094ab500221 | DELETE | /api/v1/app_definitions              |
| AppDefCreate  | b1805e3b-c218-46b7-8228-3e6170b3a6f0 | POST   | /api/v1/app_definitions              |
| AppDefList    | df6d7cd2-d758-4c18-88bc-864925a52608 | GET    | /api/v1/app_definitions              |
+---------------+--------------------------------------+--------+--------------------------------------+
INFO: Viewing 5 result(s)
2. Add the permissions to the new role using the role permisison command with the --add flag. The command takes the role name and list of permission IDs or wildcards as arguments. For example:
edgebuilder-cli role permission -r AppDefRole -p AppDef* --add
The response is similar to the following:
INFO: added 5 permission(s) to role "AppDefRole"
This new role can then be assigned to users to give them AppDefinition permissions.

  1. Verify the permissions have been added to the role using the role inspect command:
    edgebuilder-cli role inspect --role AppDefRole
    
    The response is similar to the following showing all the 5 permissions:
    {
      "CreatedBy": "iotech",
      "Description": "Role for managing app defnitions",
      "ID": "c32e4cc9-f863-4611-ad1e-11be624603e7",
      "ModifiedBy": "iotech",
      "Name": "AppDefRole",
      "Permissions": [
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "0d79247d-832d-4c53-adc7-a2694b56c621",
          "Method": "POST",
          "Name": "AppDefCreate",
          "Path": "/api/v1/app_definitions",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "134c5e1b-be41-4e57-8caa-1d4af5563c2b",
          "Method": "GET",
          "Name": "AppDefInspect",
          "Path": "/api/v1/app_definitions/inspect/{id}",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "16aa9577-345f-460c-8c69-3395e2e00ac2",
          "Method": "GET",
          "Name": "AppDefList",
          "Path": "/api/v1/app_definitions",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "5441601a-90c3-4388-a423-9ce7da5081e5",
          "Method": "DELETE",
          "Name": "AppDefDelete",
          "Path": "/api/v1/app_definitions",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "5db90388-675b-4535-a6ed-7601a49ecb33",
          "Method": "PATCH",
          "Name": "AppDefUpdate",
          "Path": "/api/v1/app_definitions/{id}",
          "TimestampCreate": 1646674176
        }
      ],
      "TimestampCreate": 1646744945,
      "TimestampModify": 1646745387
    }
    

Remove permissions from role(s)

  • To remove permissions from roles, use the role permission command with the --remove flag. For example, to remove the DELETE /api/v1/app_definitions permission from AppDefRole, obtain the correct permission and issue the command:
    edgebuilder-cli role permission --role AppDefRole --permission AppDefDelete --remove
    
    Expected Output:
    INFO: removed 1 permission(s) from role "AppDefRole"
    
  • Confirm that the permission is removed from the AppDefRole using the following command:
    edgebuilder-cli role inspect --role AppDefRole
    
    The response is similar to the following showing the remaining 4 permissions:
    {
      "CreatedBy": "iotech",
      "Description": "Role for managing app defnitions",
      "ID": "c32e4cc9-f863-4611-ad1e-11be624603e7",
      "ModifiedBy": "iotech",
      "Name": "AppDefRole",
      "Permissions": [
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "0d79247d-832d-4c53-adc7-a2694b56c621",
          "Method": "POST",
          "Name": "AppDefCreate",
          "Path": "/api/v1/app_definitions",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "134c5e1b-be41-4e57-8caa-1d4af5563c2b",
          "Method": "GET",
          "Name": "AppDefInspect",
          "Path": "/api/v1/app_definitions/inspect/{id}",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "16aa9577-345f-460c-8c69-3395e2e00ac2",
          "Method": "GET",
          "Name": "AppDefList",
          "Path": "/api/v1/app_definitions",
          "TimestampCreate": 1646674176
        },
        {
          "CreatedBy": "EdgeBuilder",
          "ID": "5db90388-675b-4535-a6ed-7601a49ecb33",
          "Method": "PATCH",
          "Name": "AppDefUpdate",
          "Path": "/api/v1/app_definitions/{id}",
          "TimestampCreate": 1646674176
        }
      ],
      "TimestampCreate": 1646744945,
      "TimestampModify": 1646745606
    }
    

Remove the role(s)

  • To remove roles, use the role remove command as shown below:
    edgebuilder-cli role remove --role AppDefRole -y
    
    The response is similar to the following
    INFO: Processing roles: [AppDefRole]
    INFO: Attempting to remove 1 role(s)
    INFO: 1 role(s) removed successfully