Chapter 5. Managing Users and Roles

download PDF

A User defines a set of details for individuals using the system. Users can be associated with organizations and environments, so that when they create new entities, the default settings are automatically used. Users can also have one or more roles attached, which grants them rights to view and manage organizations and environments. See Section 5.1, “User Management” for more information on working with users.

You can manage permissions of several users at once by organizing them into user groups. User groups themselves can be further grouped to create a hierarchy of permissions. See Section 5.2, “Creating and Managing User Groups” for more information on creating user groups.

Roles define a set of permissions and access levels. Each role contains one on more permission filters that specify the actions allowed for the role. Actions are grouped according to the Resource type. Once a role has been created, users and user groups can be associated with that role. This way, you can assign the same set of permissions to large groups of users. Red Hat Satellite provides a set of predefined roles and also enables creating custom roles and permission filters as described in Section 5.3, “Creating and Managing Roles”.

5.1. User Management

As an administrator, you can create, modify and remove Satellite users. You can also configure access permissions for a user or a group of users by assigning them different roles.

5.1.1. Creating a User

Use this procedure to create a user.


To create a user, complete the following steps:

  1. Navigate to Administer > Users.
  2. Click Create User.
  3. In the Login field, enter a username for the user.
  4. In the Firstname and Lastname fields, enter the real first name and last name of the user.
  5. In the Mail field, enter the user’s email address.
  6. In the Description field, add a description of the new user.
  7. Select a specific language for the user from the Language list.
  8. Select a timezone for the user from the Timezone list.

    By default, Satellite Server uses the language and timezone settings of the user’s browser.

  9. Set a password for the user:

    1. From the Authorized by list, select the source by which the user is authenticated.

    2. Enter an initial password for the user in the Password field and the Verify field.
  10. Click Submit to create the user.

For CLI Users

To create a user, enter the following command:

# hammer user create \
--login user_name \
--password user_password \
--mail user_mail \
--auth-source-id 1 \
--organization-ids org_ID1,org_ID2...

The --auth-source-id 1 setting means that the user is authenticated internally, you can specify an external authentication source as an alternative. Add the --admin option to grant administrator privileges to the user. Specifying organization IDs is not required, you can modify the user details later using the update subcommand.

For more information about user related subcommands, enter hammer user --help.

5.1.2. Assigning Roles to a User

Use this procedure to assign roles to a user.


  1. Navigate to Administer > Users.
  2. Click the username of the user to be assigned one or more roles.


    If a user account is not listed, check that you are currently viewing the correct organization. To list all the users in Satellite, click Default Organization and then Any Organization.

  3. Click the Locations tab, and select a location if none is assigned.
  4. Click the Organizations tab, and check that an organization is assigned.
  5. Click the Roles tab to display the list of available roles.
  6. Select the roles to assign from the Roles list.

    To grant all the available permissions, select the Admin check box.

  7. Click Submit.

To view the roles assigned to a user, click the Roles tab; the assigned roles are listed under Selected items. To remove an assigned role, click the role name in Selected items.

For CLI Users

To assign roles to a user, enter the following command:

# hammer user add-role --id user_id --role role_name

5.1.3. SSH Keys

Adding SSH keys to a user allows deployment of SSH keys during provisioning.

For information on deploying SSH keys during provisioning, see Deploying SSH Keys during Provisioning in the Red Hat Satellite Provisioning Guide.

For information on SSH keys and SSH key creation, see Generating Key Pairs in the Red Hat Enterprise Linux 7 System Administrator’s Guide.

5.1.4. Managing SSH Keys for a User

Use this procedure to add or remove SSH keys for a user.


Make sure that you are logged in to the web UI as an Admin user of Red Hat Satellite or a user with the create_ssh_key permission enabled for adding SSH key and destroy_ssh_key permission for removing a key.


  1. Navigate to Administer > Users.
  2. From the Username column, click on the username of the required user.
  3. Click on the SSH Keys tab.

    • To Add SSH key

      1. Prepare the content of the public SSH key in a clipboard.
      2. Click Add SSH Key.
      3. In the Key field, paste the public SSH key content from the clipboard.
      4. In the Name field, enter a name for the SSH key.
      5. Click Submit.
    • To Remove SSH key

      1. Click Delete on the row of the SSH key to be deleted.
      2. Click OK in the confirmation prompt.

For CLI Users

To add an SSH key to a user, you must specify either the path to the public SSH key file, or the content of the public SSH key copied to the clipboard.

  • If you have the public SSH key file, enter the following command:

    # hammer user ssh-keys add \
    --user-id user_id \
    --name key_name \
    --key-file ~/.ssh/
  • If you have the content of the public SSH key, enter the following command:

    # hammer user ssh-keys add \
    --user-id user_id \
    --name key_name \
    --key ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNtYAAABBBHHS2KmNyIYa27Qaa7EHp+2l99ucGStx4P77e03ZvE3yVRJEFikpoP3MJtYYfIe8k 1/46MTIZo9CPTX4CYUHeN8= host@user

To delete an SSH key from a user, enter the following command:

# hammer user ssh-keys delete --id key_id --user-id user_id

To view an SSH key attached to a user, enter the following command:

# hammer user ssh-keys info --id key_id --user-id user_id

To list SSH keys attached to a user, enter the following command:

# hammer user ssh-keys list --user-id user_id

5.1.5. Email Notifications

Email notifications are created by Satellite Server periodically or after completion of certain events. The periodic notifications can be sent daily, weekly or monthly.

The events that trigger a notification are the following:

  • Host build
  • Content View promotion
  • Error reported by host
  • Repository sync

Users do not receive any email notifications by default. An administrator can configure users to receive notifications based on criteria such as the type of notification, and frequency.


If you want email notifications sent to a group’s email address, instead of an individual’s email address, create a user account with the group’s email address and minimal Satellite permissions, then subscribe the user account to the desired notification types.


Satellite Server does not enable outgoing emails by default, therefore you must review your email configuration. For more information, see Configuring Satellite Server for Outgoing Emails in Installing Satellite Server from a Connected Network.

5.1.6. Configuring Email Notifications

Configure email notifications for a user from the Satellite web UI.


  1. Navigate to Administer > Users.
  2. Click the Username of the user you want to edit.
  3. On the User tab, verify the value of the Mail field. Email notifications will be sent to the address in this field.
  4. On the Email Preferences tab, select Mail Enabled.
  5. Select the notifications you want the user to receive using the drop-down menus next to the notification types.


    The Audit Summary notification can be filtered by entering the required query in the Mail Query text box.

  6. Click Submit.

    The user will start receiving the notification emails.

5.1.7. Testing Email Delivery

To verify the delivery of emails, send a test email to a user. If the email gets delivered, the settings are correct.


  1. In the Satellite web UI, navigate to Administer > Users.
  2. Click on the username.
  3. On the Email Preferences tab, click Test email.

    A test email message is sent immediately to the user’s email address.

If the email is delivered, the verification is complete. Otherwise, you must perform the following diagnostic steps:

  1. Verify the user’s email address.
  2. Verify Satellite Server’s email configuration.
  3. Examine firewall and mail server logs.

5.1.8. Testing Email Notifications

To verify that users are correctly subscribed to notifications, trigger the notifications manually.


  • To trigger the notifications, execute the following command:

    # foreman-rake reports:<frequency>

    Replace frequency with one of the following:

    • daily
    • weekly
    • monthly

This triggers all notifications scheduled for the specified frequency for all the subscribed users. If every subscribed user receives the notifications, the verification succeeds.


Sending manually triggered notifications to individual users is currently not supported.

5.1.9. Notification Types

The following are the notifications created by Satellite:

  • Audit summary: A summary of all activity audited by the Satellite Server.
  • Host built: A notification sent when a host is built.
  • Host errata advisory: A summary of applicable and installable errata for hosts managed by the user.
  • OpenSCAP policy summary: A summary of OpenSCAP policy reports and their results.
  • Promote errata: A notification sent only after a Content View promotion. It contains a summary of errata applicable and installable to hosts registered to the promoted Content View. This allows a user to monitor what updates have been applied to which hosts.
  • Puppet error state: A notification sent after a host reports an error related to Puppet.
  • Puppet summary: A summary of Puppet reports.
  • Sync errata: A notification sent only after synchronizing a repository. It contains a summary of new errata introduced by the synchronization.

5.2. Creating and Managing User Groups

5.2.1. User Groups

With Red Hat Satellite, you can assign permissions to groups of users. You can also create user groups as collections of other user groups. If using an external authentication source, you can map Satellite user groups to external user groups as described in Section 13.4, “Configuring External User Groups”.

User groups are defined in an organizational context, meaning that you must select an organization before you can access user groups.

5.2.2. Creating a User Group

Use this procedure to create a user group.


  1. Navigate to Administer > User Groups.
  2. Click Create User group.
  3. On the User Group tab, specify the name of the new user group and select group members:

    • Select the previously created user groups from the User Groups list.
    • Select users from the Users list.
  4. On the Roles tab, select the roles you want to assign to the user group. Alternatively, select the Admin check box to assign all available permissions.
  5. Click Submit.

For CLI Users

To create a user group, enter the following command:

# hammer user-group create \
--name usergroup_name \
--user-ids user_ID1,user_ID2... \
--role-ids role_ID1,role_ID2...

5.2.3. Removing a User Group

Use the Satellite web UI to remove a user group.


  1. Navigate to Administer > User Groups.
  2. Click Delete to the right of the user group you want to delete.
  3. In the alert box that appears, click OK to delete a user group.

5.3. Creating and Managing Roles

Red Hat Satellite provides a set of predefined roles with permissions sufficient for standard tasks, as listed in Section 5.3.7, “Predefined Roles Available in Satellite”. It is also possible to configure custom roles, and assign one or more permission filters to them. Permission filters define the actions allowed for a certain resource type. Certain Satellite plug-ins create roles automatically.

5.3.1. Creating a Role

Use this procedure to create a role.


  1. Navigate to Administer > Roles.
  2. Click Create Role.
  3. Provide a Name for the role.
  4. Click Submit to save your new role.

For CLI Users

To create a role, enter the following command:

# hammer role create --name role_name

To serve its purpose, a role must contain permissions. After creating a role, proceed to Section 5.3.3, “Adding Permissions to a Role”.

5.3.2. Cloning a Role

Use the Satellite web UI to clone a role.


  1. Navigate to Administer > Roles and select Clone from the drop-down menu to the right of the required role.
  2. Provide a Name for the role.
  3. Click Submit to clone the role.
  4. Click the name of the cloned role and navigate to Filters.
  5. Edit the permissions as required.
  6. Click Submit to save your new role.

5.3.3. Adding Permissions to a Role

Use this procedure to add permissions to a role.


  1. Navigate to Administer > Roles.
  2. Select Add Filter from the drop-down list to the right of the required role.
  3. Select the Resource type from the drop-down list. The (Miscellaneous) group gathers permissions that are not associated with any resource group.
  4. Click the permissions you want to select from the Permission list.
  5. Depending on the Resource type selected, you can select or deselect the Unlimited and Override check box. The Unlimited checkbox is selected by default, which means that the permission is applied on all resources of the selected type. When you disable the Unlimited check box, the Search field activates. In this field you can specify further filtering with use of the Red Hat Satellite 6 search syntax. See Section 5.4, “Granular Permission Filtering” for details. When you enable the Override check box, you can add additional locations and organizations to allow the role to access the resource type in the additional locations and organizations; you can also remove an already associated location and organization from the resource type to restrict access.
  6. Click Next.
  7. Click Submit to save changes.

For CLI Users

To add permissions to a role, complete the following steps:

  1. List all available permissions:

    # hammer filter available-permissions
  2. Add permissions to a role:

    # hammer filter create \
    --role role_name \
    --permission-ids perm_ID1,perm_ID2...

For more information about roles and permissions parameters, enter the hammer role --help and hammer filter --help commands.

5.3.4. Viewing Permissions of a Role

Use the Satellite web UI to view the permissions of a role.


  1. Navigate to Administer > Roles.
  2. Click Filters to the right of the required role to get to the Filters page.

The Filters page contains a table of permissions assigned to a role grouped by the resource type. It is also possible to generate a complete table of permissions and actions that you can use on your Satellite system. See Section 5.3.5, “Creating a Complete Permission Table” for instructions.

5.3.5. Creating a Complete Permission Table

Use the Satellite CLI to create a permission table.


  1. Ensure that the required packages are installed. Execute the following command on the Satellite Server:

    # satellite-maintain packages install tfm-rubygem-foreman*
  2. Start the Satellite console with the following command:

    # foreman-rake console

    Insert the following code into the console:

    f ='/tmp/table.html', 'w')
    result = Foreman::AccessControl.permissions {|a,b| a.security_block <=> b.security_block}.collect do |p|
          actions = p.actions.collect { |a| "<li>#{a}</li>" }

    The above syntax creates a table of permissions and saves it to the /tmp/table.html file.

  3. Press Ctrl + D to exit the Satellite console. Insert the following text at the first line of /tmp/table.html:

    <table border="1"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>

    Append the following text at the end of /tmp/table.html:

  4. Open /tmp/table.html in a web browser to view the table.

5.3.6. Removing a Role

Use the Satellite web UI to remove a role.


  1. Navigate to Administer > Roles.
  2. Select Delete from the drop-down list to the right of the role to be deleted.
  3. In an alert box that appears, click OK to delete the role.

5.3.7. Predefined Roles Available in Satellite

RolePermissions Provided by Role [a]

Access Insights Admin

Add and edit Insights rules.

Access Insights Viewer

View Insight reports.

Ansible Roles Manager

Play roles on hosts and host groups. View, destroy, and import Ansible roles. View, edit, create, destroy, and import Ansible variables.

Ansible Tower Inventory Reader

View facts, hosts, and host groups

Bookmarks manager

Create, edit, and delete bookmarks.

Boot disk access

Download the boot disk.

Compliance manager

View, create, edit, and destroy SCAP content files, compliance policies, and tailoring files. View compliance reports.

Compliance viewer

View compliance reports.

Create ARF report

Create compliance reports.

Default role

The set of permissions that every user is granted, irrespective of any other roles.

Discovery Manager

View, provision, edit, and destroy discovered hosts and manage discovery rules.

Discovery Reader

View hosts and discovery rules.

Edit hosts

View, create, edit, destroy, and build hosts.

Edit partition tables

View, create, edit and destroy partition tables.


A role similar to administrator, but does not have permissions to edit global settings. In the Satellite web UI, global settings can be found under Administer > Settings.

Organization admin

An administrator role defined per organization. The role has no visibility into resources in other organizations.

Red Hat Access Logs

View the log viewer and the logs.

Remote Execution Manager

A role with full remote execution permissions, including modifying job templates.

Remote Execution User

Run remote execution jobs.

Site manager

A restrained version of the Manager role.

System admin

  • Edit global settings in Administer > Settings
  • View, create, edit and destroy users, user groups, and roles
  • View, create, edit, destroy, and assign organizations and locations but not view resources within them

Users with this role can create users and assign all roles to them. Therefore, ensure to give this role only to trusted users.

Tasks manager

View and edit Satellite tasks.

Tasks reader

A role that can only view Satellite tasks.


A passive role that provides the ability to view the configuration of every element of the Satellite structure, logs, reports, and statistics.

View hosts

A role that can only view hosts.

Virt-who Manager

A role with full virt-who permissions.

Virt-who Reporter

Upload reports generated by virt-who to Satellite. It can be used if you configure virt-who manually and require a user role that has limited virt-who permissions.

Virt-who Viewer

View virt-who configurations. Users with this role can deploy virt-who instances using existing virt-who configurations.

[a] The exact set of allowed actions associated with predefined roles can be viewed by the privileged user as described in Section 5.3.4, “Viewing Permissions of a Role”

5.4. Granular Permission Filtering

5.4.1. Granular Permission Filter

As mentioned in Section 5.3.3, “Adding Permissions to a Role”, Red Hat Satellite provides the ability to limit the configured user permissions to selected instances of a resource type. These granular filters are queries to the Satellite database and are supported by the majority of resource types.

5.4.2. Creating a Granular Permission Filter

Use this procedure to create a granular filter.

Satellite does not apply search conditions to create actions. For example, limiting the create_locations action with name = "Default Location" expression in the search field does not prevent the user from assigning a custom name to the newly created location.


Specify a query in the Search field on the Edit Filter page. Deselect the Unlimited check box for the field to be active. Queries have the following form:

field_name operator value
  • field_name marks the field to be queried. The range of available field names depends on the resource type. For example, the Partition Table resource type offers family, layout, and name as query parameters.
  • operator specifies the type of comparison between field_name and value. See Section 5.4.4, “Supported Operators for Granular Search” for an overview of applicable operators.
  • value is the value used for filtering. This can be for example a name of an organization. Two types of wildcard characters are supported: underscore (_) provides single character replacement, while percent sign (%) replaces zero or more characters.

For most resource types, the Search field provides a drop-down list suggesting the available parameters. This list appears after placing the cursor in the search field. For many resource types, you can combine queries using logical operators such as and, not and has operators.

For CLI Users

To create a granular filter, enter the hammer filter create command with the --search option to limit permission filters, for example:

# hammer filter create \
--permission-ids 91 \
--search "name ~ ccv*" \
--role qa-user

This command adds to the qa-user role a permission to view, create, edit, and destroy Content Views that only applies to Content Views with name starting with ccv.

5.4.3. Examples of Using Granular Permission Filters

As an administrator, you can allow selected users to make changes in a certain part of the environment path. The following filter allows you to work with content while it is in the development stage of the application life cycle, but the content becomes inaccessible once is pushed to production. Applying Permissions for the Host Resource Type

The following query applies any permissions specified for the Host resource type only to hosts in the group named host-editors.

hostgroup = host-editors

The following query returns records where the name matches XXXX, Yyyy, or zzzz example strings:

name ^ (XXXX, Yyyy, zzzz)

You can also limit permissions to a selected environment. To do so, specify the environment name in the Search field, for example:


You can limit user permissions to a certain organization or location with the use of the granular permission filter in the Search field. However, some resource types provide a GUI alternative, an Override check box that provides the Locations and Organizations tabs. On these tabs, you can select from the list of available organizations and locations. See Section, “Creating an Organization Specific Manager Role”. Creating an Organization Specific Manager Role

Use the Satellite UI to create an administrative role restricted to a single organization named org-1.


  1. Navigate to Administer > Roles.
  2. Clone the existing Organization admin role. Select Clone from the drop-down list next to the Filters button. You are then prompted to insert a name for the cloned role, for example org-1 admin.
  3. Click the desired locations and organizations to associate them with the role.
  4. Click Submit to create the role.
  5. Click org-1 admin, and click Filters to view all associated filters. The default filters work for most use cases. However, you can optionally click Edit to change the properties for each filter. For some filters, you can enable the Override option if you want the role to be able to access resources in additional locations and organizations. For example, by selecting the Domain resource type, the Override option, and then additional locations and organizations using the Locations and Organizations tabs, you allow this role to access domains in the additional locations and organizations that is not associated with this role. You can also click New filter to associate new filters with this role.

5.4.4. Supported Operators for Granular Search

Table 5.1. Logical Operators




Combines search criteria.


Negates an expression.


Object must have a specified property.

Table 5.2. Symbolic Operators




Is equal to. An equality comparison that is case-sensitive for text fields.


Is not equal to. An inversion of the = operator.


Like. A case-insensitive occurrence search for text fields.


Not like. An inversion of the ~ operator.


In. An equality comparison that is case-sensitive search for text fields. This generates a different SQL query to the Is equal to comparison, and is more efficient for multiple value comparison.


Not in. An inversion of the ^ operator.

>, >=

Greater than, greater than or equal to. Supported for numerical fields only.

<, ⇐

Less than, less than or equal to. Supported for numerical fields only.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.