---
updatedAt: 2026-07-30T22:11:49.000Z
---

# EPM-UL role-based policies | EPM-UL

> ℹ️
>
> Role-based policy management is disabled on hosts configured to use script-based policy.

An Endpoint Privilege Management for Unix and Linux (EPM-UL) role-based policy defines which users can use commands and when they can perform these actions on hosts. These role entities are then associated to a role. A **User**, **Host**, **Command**, and **Schedule** entity can be used in multiple roles, allowing the user to create a single definition and share it. The role-based policy editor is divided into sections allowing for the management of roles and each of the role entities.

Choose the EPM-UL role-based policy option and an appropriate policy server from the selection lists to load the **Role Based Policy** menu.

> ℹ️
>
> Fields may be disabled during policy configuration when the options are not available for the installed version of EPM-UL.

## Entitlement reporting

EPM-UL hosts running 10.1 and later in **Role Based Policy Mode** can take advantage of Entitlement reporting to discover who is able to do what, where, and when.

Entitlement reporting can be enabled per policy or to all role-based policies.

A default value for reporting can be configured in **Settings**; if enabled, all new role-based policies defaults to entitlement reporting enabled, or vice versa if set to **false**. Additionally, this setting can be locked so the default value is both set and unchangeable per policy. This is for new policies only; disabling entitlement reporting does not change the values for existing policies.

## Role-based policy roles

A list of available roles shows the existing entities. This list is searchable and can be filtered by **Enabled**, **Disabled**, or all options. Selecting the **Add Role** option creates a role.

* To edit an existing role, select an entry from the **Roles** list and click **Edit**.
* To delete an existing role, select an entry from the **Roles** list and click **Delete**.

### Role ordering

The order in which role-based policies are applied can be set by ordering the roles in the list of available roles. Click and drag a role entry up or down in the **Roles** list to establish the priority order. Changes to role order is saved automatically.

### General details

The following options are available:

* **Role name:** This should be unique on the policy server.
* **Tag:** Add a tag to the role. Once added, tags function as a filter and can be used to sort through policy roles.
* **Description:** A brief description to identify the role.
* **Comment:** The admin can add a comment here. These are only visible to the admin.
* **Role Risk Level:** The perceived risk level of the policy.
* **Request Type:** Allows the administrator to specify which request types this policy will apply to. For example, a policy might apply to commands issued only by **pbrun** invocations. Use the dropdown to select the appropriate request type, or select **Any**. The default value is to allow any request type.
* **Policy Enabled:** Whether or not the role is active (default **Enabled**).
* **Action:** Whether this should trigger an accept or reject action (default **Accept**).
* **Entitlement Reporting:** Whether or not Entitlement Reporting is enabled (default **Disabled**).

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

Click **Save**.

### Assignments

Assign allowed users, hosts, commands, and schedule to a role. Each role can have zero to many relationships with each entity type. This is managed using the lists matching the appropriate entity. The following configuration sections are available:

* **Who:** Defines which users the policy applies to. This item is divided into two user types:

  * **Submit Users**
  * **Run Users**

  These lists contain the user entities.

  Select **Use Default Group and Working Directory** to automatically populate the run users in a script block on the **Script Policy** page. Changing the block properties is not recommended.
* **What:** Defines which commands the policy applies to. This list contains the command entities.
* **Where:** Defines which hosts the policy applies to. This item is divided into two host types:

  * **Submit Hosts**
  * **Run Hosts**

  These lists contain the host entities.
* **When:** Defines which schedule the policy applies to. This list contains the schedule entities.

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

Click **Save**.

### Reauthentication

If configured, this feature requires users to reauthenticate themselves when this policy is invoked. Only one reauthentication method can be configured per policy. Most reauthentication options allow for customization of messages and prompts to be displayed to the user as well as logs. Reauthentication can be enabled in a number of configurations:

* **None:** Reauthentication is not required.
* **Shared Secret:** Create a shared secret value. The user must provide it to reauthenticate.
* **Privilege Access Management (PAM):** A number of PAM modules can be selected, or a custom one can be provided. Additionally, most options allow the user to configure where the authentication will occur.

To configure the **Shared Secret** option:

1. From the **Type** dropdown, select **Shared Secret**.
2. Enter the **Shared Secret** and confirm it.
3. Enter a **Reauthentication Prompt** message, or use the default.
4. Enter the **Number of attempts** (retries) before reauthentication locks up.
5. Enter the **Failure Message** the user sees if reauthentication fails, or use the default.
6. Enter the **Log Message** that is recorded in the log when reauthentication fails, or use the default.

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

7. Click **Save**.

To configure the **PAM** option:

1. From the **Type** dropdown, select **PAM**.
2. Select the **PAM Service** to use for authentication.
3. Select the **Location** to use, where the authentication happens. If you select the **Run Host** option, you only need to complete steps 4 and 5, and then click **Save**.
4. Select the **User Type**, whether you are providing authentication for the user requesting the elevation, the user running the command, or some other user. If you select **Custom**, enter a custom user name.
5. Enter a **Reauthentication Prompt** message, or use the default.
6. Enter the **Number of attempts** (retries) before reauthentication locks up. That depends entirely on the policies imposed by the authentication services that EPM-UL accesses through PAM.
7. Enter the **Valid** time length, in seconds, or use the default. This is how long the reauthentication is cached for, before a login is required again.
8. Enter the **Failure Message** the user sees if reauthentication fails, or use the default.
9. Enter the **Log Message** that is recorded in the log when reauthentication fails, or use the default.
10. In the **Change requested by \[loggedInUserName]** field, enter a reason for the assignment or change.

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

11. Click **Save**.

### Messages

Enables the administrator to output a message to the user when this policy is processed. This field can interpolate variables to provide a custom, context specific message using the EPM-UL template syntax of **%\<variable>%**. A few options are available using buttons to quickly insert the most popular options. Values can also be entered freely.

Click **Save**.

### Session replay

Generate a file location for session replay logs and configure **Path Options**.The **Session Replay Location** field allows for the use of variables in the file name. BIUL provides a template builder to assist with creating the path; select the build option, provide a path to save the file, and select the desired variable options. Values can also be entered freely.

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

Click **Save**.

### Script policy

A configuration area to include a custom script. Script policy can be entered into the code editor to set the script content.

> ℹ️
>
> If Change Management is enabled, an additional **Change requested by \[loggedInUserName]** field is visible and requires you to enter a reason for the change.

Click **Save**.

## Users and user groups

Users and user groups determine *who* the role will be applied to.

> ℹ️
>
> Role-based policy management is disabled on hosts configured to use script-based policy.

### User and user group types

There are three types of users and user groups:

* **Secure:** A user or group not associated with any system. The name and credential are added to the policy.
* **System:** The users and groups are retrieved from the selected host. System roles are only available with Endpoint Privilege Management for Unix and Linux versions 9.4.4 or later.
* **Directory Service:** The users and groups are retrieved from Directory Service. Create a connection to Directory Service on the **Settings > Integration** page.

> ℹ️
>
> If a wildcard character (\*) is in the username, the user is treated as a group.

### Add a secure user

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Click **Add User / Group** and select **Secure User**.
6. Enter **Username**, **Description**, and choose to enable or disable the entry.
7. Click **Save Changes**.

### Add a secure group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Click **Add User / Group** and select **Secure Group**.
6. Enter **Group name**, **Description**, and choose to make the group active or inactive.
7. In the **Group members** section, enter existing secure users in the **Username** field to add them to the group.
8. Click **Save Changes**.

### Delete a secure user or group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Select a secure user or group entry from the **Users** list.
6. On the **Users and Groups** pane, click **Delete User** or **Delete Group** to delete the entry.

### Add a system user or group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Click **Add User / Group** and select **System User** or **System Group**. A list of available entries is displayed on the **Users and Groups** pane.
6. On the **Users and Groups** pane, check the box to import users or user groups. The imported users or user groups are displayed in the **Users** list.

### Remove a system user or group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Select a system user or group entry from the **Users** list.
6. On the **Users and Groups** pane, click **Remove User** or **Remove User Group** to remove the entry.

### Add a directory service user or group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Click **Add User / Group** and select **Directory Service Users and Groups**.
6. On the **Users and Groups** pane, select the **Search Type** to **Find Users** or **Find Groups**.
7. Enter the **Forest** and **Domain**.
8. Click **Browse** to filter by organizational unit (OU) and enter criteria in the **Search for** field.
9. Click **Search Directory Service**.
10. Check the box to import Directory Service users or user groups. The imported users or user groups are displayed in the **Users** list.

### Remove a directory service user or group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Who**.
5. Select a Directory Service user or group entry from the **Users** list.
6. On the **Users and Groups** pane, click **Remove User** or **Remove Group** to remove the entry.

## Command groups

Command Groups determine *which commands* will be allowed or rejected.

> ℹ️
>
> Role-based policy management is disabled on hosts configured to use script-based policy.

### Add a command group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **What**.
5. Click **Add Command Group**.
6. Enter **Command Group Name**, **Command Group Description**, and choose whether the Command Group is enabled or disabled.
7. Enter **Commands**. When adding a command to the list, you must enter **Command**, which is the command an Endpoint Privilege Management for Unix and Linux user types. Optionally, you can enter **Executed**, which is executed in place of the **Command**.
8. Click **Save**.

### Delete a command group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **What**.
5. Select an existing entry from the **Command Groups** list.
6. Click **Delete**.

## Host groups

Host Groups determine *where* the roles are applied.

> ℹ️
>
> Role-based policy management is disabled on hosts configured to use script-based policy.

### Add a host group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Where**.
5. Click **Add Host Group**.
6. Enter **Host Group Name**, **Host Group Description**, and choose whether the Host Group is enabled or disabled.
7. Enter **Matching Hosts**.
8. Click **Save**.

### Delete a host group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **Where**.
5. Select an existing entry from the **Host Groups** list.
6. Click **Delete**.

## Schedule groups

Schedule Groups determine *when* roles are applied. When adding a schedule, there are two types of dates you can create in your schedule:

* **Fixed Schedule:** Choose a specific date range. If the end date is not specified, the range defaults to continuous. If the start date is not specified, the default starts immediately.
* **Recurring Schedule:** Choose active blocks of time per day. Choose a range of 15 minute blocks per each day for a full calendar week.

### Add a schedule group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **When**.
5. Click **Add Schedule Group**.
6. Enter **Schedule Group Name**, **Schedule Group Description**, and choose whether the Schedule Group is enabled or disabled.
7. Configure schedules using **Recurring Schedule** and **Fixed Schedule** options.
8. Click **Save**.

### Delete a schedule group

1. Go to the **Policy Management** page.
2. In the **Hostname** list, select a server entry, and then at the far right, click ![Actions menu](https://files.readme.io/7e786057c4cd2715b1c16394e9f6577cbdb2bdba8d3b97783ee040203f8af3c1-icon-actions.png) and select **Server Details**.
3. Click **Policy**.
4. Click **When**.
5. Select an existing entry from the **Schedule Groups** list.
6. Click **Delete**.

## Backup and restore

Role-based policy data can be managed in this section.

* **Backup Role Based Policy**: Download a copy of the policy database on the selected policy server.
* **Restore Role Based Policy**: Upload and set the current policy to the provided backup.
* **Version Control**: Restore the database to a particular version by selecting a version from the **Version** list and clicking **Restore Version**.