BEYONDINSIGHT FOR UNIX/LINUX INSTALLATION GUIDE

BIUL is a web-based tool that you can use to:

• Manage software for AD Bridge and EPM-UL.
• Remotely assess the suitability of a remote host's state by running a profile. After a profile is complete, installs, uninstalls, domain joins, and other actions can be performed on remote hosts.
• Manage EPM-UL licenses on policy servers.
• Manage EPM-UL script, File Integrity Monitoring (FIM), and role-based policies.
• Manage Sudo host groups and FIM policy host assignment.
• View, replay, and audit EPM-UL logs.

This guide provides system administrators and security administrators the information to install and configure BeyondInsight for Unix & Linux, on Linux or Windows operating systems.

BeyondTrust product name conventions

This guide uses the following naming conventions for BeyondTrust products:

Core features

These features are found in the menu, under tiles, and on the main pages for menu items.

Solr

ℹ️

Note

As of version 23.1, Solr is deprecated. EPM-UL no longer supports installing Solr, but features that use an existing Solr installation will continue to work.

Install BeyondInsight for Unix & Linux

You can install the console on Windows or Linux operating systems.

Requirements

You must have the system firewall configured to allow access on port 4443 (default).

Supported operating systems

BIUL supports the following operating systems:

• Windows 2012 or later
• Windows 2012 R2 or later
• RHEL/CentOS 5 or later
• Debian/Ubuntu 12.04 or later

Supported browsers

BIUL supports the following browsers:

• Safari 9 or later
• Chrome 52 or later
• FireFox 48 or later
• Edge

Supported database versions

The standard Microsoft SQL Server scenario is set up on a U-Series Appliance. The following database versions and platforms are compatible for the BIUL database:

• Microsoft SQL Server 2014, 2016, and 2019
• SQLite versions 3.7.17 to 3.37

ℹ️

Note

The only MS SQL Server configuration that has been tested and approved is with SQL Server running on the same machine as the BIUL installation, which is the standard UVM Appliance setup. Running MS SQL Server on a separate, dedicated database server is not supported.

Prepare for the BeyondInsight for Unix & Linux installation

• Run the install using an account with root or administrator privileges.
• Copy the installers for BeyondInsight for Unix & Linux, Endpoint Privilege Management for Unix and Linux, and AD Bridge to the server.
• If deploying to an HP-UX server, make sure gzip is in /usr/bin or /bin. If it is not, create a symbolic link.

  ln –s /usr/contrib/bin/gzip /usr/bin/gzip
  

Install BeyondInsight for Unix & Linux on Linux

To install BeyondInsight for Unix & Linux on a Linux operating system, use the following syntax.

RHEL and CentOS

# install, where {version} is the current version
rpm -i biul-{version}.rpm
# optional: verify software is running
service pbsmc status

# configure firewall using OS version appropriate command:
# RedHat Enterprise Linux/CentOS 7:
firewall-cmd --zone=public --add-port=4443/tcp --permanent 
firewall-cmd --reload

# or, RedHat Enterprise Linux/CentOS 6:
iptables -A INPUT -p tcp -m tcp --dport 4443 -j ACCEPT 
service iptables save

Debian and Ubuntu

# install, where {version} is the current version
dpkg -i biul-{version}.deb

# optional: verify software is running
service pbsmc status

# configure firewall using OS version appropriate command:
# for ubuntu 14+:
 ufw allow 4443

# or other versions:

iptables -A INPUT -p tcp -m tcp --dport 4443 -j ACCEPT 
service iptables save

Install BeyondInsight for Unix & Linux on Windows

To install BeyondInsight for Unix & Linux on a Windows operating system:

1. Run the msi package and follow the install wizard.
2. After you go through the wizard, configure the firewall.
3. Open Control Panel > System and Security > Windows Firewall.
4. Click Advanced Settings.
5. Click Inbound Rules.
6. In the Actions window, click New Rule.
7. Click Rule Type of Port, and then click Next.
8. On the Protocol and Ports page, click TCP.
9. Select Specific Local Ports and type a value of 4443. Click Next.
10. On the Action page, click Allow the connection, and then click Next.
11. On the Profile page, click the appropriate options for your environment and click Next.
12. On the Name page, enter a name for BeyondInsight for Unix & Linux.
13. Click Finish.

Prepare AD Bridge and Endpoint Privilege Management for Unix and Linux for installation

You can use BIUL to install AD Bridge and Endpoint Privilege Management for Unix and Linux software on a remote host. To do so, BIUL must have access to an installer for the software. You can supply the installer by copying ISO files to the console server, or by uploading the software from within BeyondInsight for Unix & Linux.

Copy ISO files to the console server

You must copy and extract the ISO files for the AD Bridge and Endpoint Privilege Management for Unix and Linux installers.

ℹ️

Note

The installer path folder structures must not be modified.

AD Bridge

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\pbis

Unix and Linux

/usr/local/bin/software/pbis/

Endpoint Privilege Management for Unix and Linux

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\pmul

Unix and Linux

/usr/local/bin/software/pmul/

Solr

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\Solr

Unix and Linux

/usr/local/bin/software/solr/

Upload software

Alternatively, you can upload software for AD Bridge and Endpoint Privilege Management for Unix and Linux installers on the Settings page.

ℹ️

Note

You cannot upload software on the BeyondTrust U-Series Appliance. Use BT Updater to update local packages.

To upload software:

1. Click Settings > Software, and then click the upload icon.

2. Drag the file to the upload area.

   Optionally, click anywhere in the upload area to navigate to the file. The AD Bridge ZIP files and Endpoint Privilege Management for Unix and Linux ISO files are large. The upload can take time. A progress bar shows the upload progress. You can resume an upload if an interruption occurs (for example, a session timeout occurs).

3. After the upload is complete, BeyondInsight for Unix & Linux unpacks the files, which can take a few minutes. The software is available after the unpacking is complete.

4. To update the status of available software, click the refresh icon.

Configure BeyondInsight for Unix & Linux

You can customize the console using the pbsmc.toml.default file located in:

• Linux: /etc/pbsmc
• Windows: %ProgramFiles%\PBSMC

First, you must create a copy of the file using the name pbsmc.toml. You can include only the settings that you want to customize.

The BIUL API uses a markup language called TOML that is hierarchical. The settings are divided into sections and keys. Be sure to include the section title in pbsmc.toml. For example, if you want to change the default port number, the text will look similar to the following:

[server]
port="4443"

ℹ️

Note

Apply proper security settings on the TOML file. The file owner requires Read and Write privileges.

You can configure the following settings.

Database

By default, the console creates a SQLite database in /etc/pbsmc/pbsmc.sqlite on Linux, or in %ProgramFiles%\pbsmc on Windows. This can be changed to another location.

[database]
dialect="sqlite3"
url="./pbsmc.db"

dialect

Default: sqlite3

The dialect key allows a user to specify what type of database BIUL will connect to.

url

Default: The default is OS specific, but maps to using an sqlite database file with the following config:

pbsmc.db?cache=shared&mode=rwc&_busy_timeout=9999999999999999

The url is a key that allows a user to provide connection information to our database driver.

✅

Example

MSSQL URLstyle

sqlserver://sa:Hello2018@pbsmc-sqlserver:1433?database=pbsmc

✅

Example

MSSQL ADO Style

server=pbsmc-sqlserver;user id=sa;password=Hello2018;port=1433;database=pbsmc

✅

Example

sqlite

etc/pbsmc/pbsmc.db?cache=shared&mode=rwc&_busy_timeout=9999999999999999

Server

By default, the console runs on port 4443. Before changing this value, stop the service.

[server]
disabled=false
port=":4443"
softwarepath="/usr/local/bin/software"
uploads="/tmp/pbsmcUploads"
passwordcost=14

By default, the BeyondInsight for Unix & Linux server runs as the root user. In a Linux environment, you can override this default behavior to run as a dedicated user with only access to the BIUL resources.

1. Create a Linux user and group you want to use for running BeyondInsight for Unix & Linux.

useradd biul
groupadd biul
usermod -a -G biul biul

2. Stop the BeyondInsight for Unix & Linux service using systemctl stop pbsmc.
3. Specify this user and group as a value in the BeyondInsight for Unix & Linux config file (pbsmc.toml), in the server section, via the key runprivs, separated by a colon (user:group).

runprivs = "biul:biul"

See also the sample config file included with the installation, /etc/pbsmc/pbsmc.toml.default.

port

Default: :4443

The port that BIUL listens for connections on.

disabled

Default: false

A setting to disable BIUL from attempting to initialize.

softwarepath

Default: ""

The path to where installers are stored on disk.

uploads

Default: An OS specific folder where uploads are temporarily stored until they can be moved to the softwarepath.

passwordcost

Default: 14

The bcrypt cost factor for hashing passwords. Values less than 12 use 12. Values greater than 20 use 20.

SSL

By default, the console supports encrypted HTTPS connections using automatically generated, self-signed certificates. The console serves only HTTPS traffic on the configured port, unless explicitly configured to fall back to insecure HTTPS in the pbsmc.toml configuration file. A custom certificate pair may also be provided and placed in the configuration file.

[ssl]
enabled=true
cert="/usr/local/bin/cert.pem"
key="/usr/local/bin/key.pem"

enabled

Default: true

Whether to use TLS 1.2+ to secure connections to BIUL or not.

cert

Default: unset

The location on disk to use as the public key/cert for encrypting communications.

If key and cert are provided, key pairs stored in the database are not used.

key

Default: unset

The location on disk to use as the private key for encrypting communications.

If key and cert are provided, key pairs stored in the database are not used.

Worker pool

Console tasks are run in a concurrent pool of processes. The default number of processes running at a time is 20. You can increase the pool size to allow jobs to complete faster. However, the server performance might lag, and decreasing the pool size has the opposite effect.

[pool]
size=20

size

Default: 20

The number of workers that are allowed to operate performing remote actions simultaneously.

Logging

The logging level configuration.

[logging]
loglevel="info"
maxage=365
maxsize=10

loglevel

Default: info

The level of logging to write to disk.

maxage

Default: 365

The maximum age of rotated log files. When a logfile is rotated it has the timestamp of when it was rotated added to the logfile's name. Any logfiles that are more than maxage days old when the next file is rotated are deleted.

If a logfile happens to be rotated every 10 days, then it is possible for a logfile to exist on disk for more than 365 days.

If set to zero (0), old logfiles are not deleted.

maxsize

Default: 10

The size of a logfile in number of megabytes before the log is rotated.

If set to zero (0), the logfile is not rotated.

Encryption keys

Encryption keys for BIUL use base64 encoded AES-256 encryption. The key secures sensitive data stored in the database. More than one key can be used at a time. The active key in the pbsmc.toml file is the key currently in use. If you start BeyondInsight for Unix & Linux without an encryption key, one is generated for you. You can review the comments in the pbsmc.toml.default file.

[keys]
active="abcdefg"
revoked= [
    "abcd",
    "efgh"
]
known = [
    "abcde",
    "fghij"

]

active

Default: unset

This is the key that is used to encrypt all secrets in the database. If not provided, it is created and the settings file mutated.

revoked

Default: dYFnQ8eNHRTnqRahhqwbpizzrEQVK7LK, 8vkb8JJgWRy5h1C421zy2q0sS7i2mdw2

This is a list of keys that are no longer active; any secrets that are encrypted with the keys should be re-encrypted with the active key.

known

Default: unset

This is a list of keys that BIUL uses to decrypt secrets. known is used as a step in the process of rolling a key. In the event of a cluster of BIUL servers, it is necessary to synchronize keys to all servers before the process of re-encrypting all secrets occurs.

This allows a key to be known by all servers, then you can update active to the new key, potentially moving an old key to revoked, and then begin the process of moving other servers to update their active key to the new key.

This allows all secrets to be readable by all servers.

⚠️

Important

You must restart the service to apply changes.

SSH cipher and key exchange configuration

[ssh]
ciphers=[
  "aes128-ctr",
  "aes128-gcm",
  "aes128-cbc"
]
key_exchanges=[
  "curve25519-sha256",
  "ecdh-sha2-nistp256",
  "ecdh-sha2-nistp384"
]

ciphers

Default: a list containing the values aes128-gcm, chacha20-poly1305, aes128-ctr, aes192-ctr, aes256-ctr

This is used to configure the list of allowed ciphers to be used while connecting to remote hosts.

Supported values:

• aes128-ctr
• aes192-ctr
• aes256-ctr
• aes128-gcm
• chacha20-poly1305
• arcfour256
• arcfour128
• arcfour
• aes128-cbc
• 3des-cbc

key exchanges

Default: a list containing the values curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384

This is used to configure the list of allowed key exchange algorithms used to secure the initial connection to remote hosts.

Supported values:

• curve25519-sha256
• ecdh-sha2-nistp256
• ecdh-sha2-nistp384
• ecdh-sha2-nistp521
• diffie-hellman-group14-sha1
• diffie-hellman-group1-sha1
• diffie-hellman-group-exchange-sha256
• diffie-hellman-group-exchange-sha1

Scrypt

Increasing the value of the parameters makes it more difficult for an attacker to crack a given password, but that increase in security slows down the login process for a legitimate user.

⚠️

Important

Unless you fully understand the implications of adjustments to the parameters below, we recommend using the default parameters. For help with this specific configuration, contact BeyondTrust Support.

[scrypt]
N-65536
r=8
p=1

N

Default: 65536

The CPU/Memory cost parameter. N is the most commonly adjusted parameter. N is the main factor governing how much memory the algorithm uses.

Value for N must be:

• Greater than 1
• A power of 2
• Less than 2^(128*r/8)

r

Default: 8

The block size parameter.

Value for r must be greater than 0.

p

Default: 1

The degree of parallelism parameter.

Value for p must be greater than 0.

Installation and configuration

You can install the console on Windows or Linux operating systems.

Requirements

You must have the system firewall configured to allow access on port 4443 (default).

Supported operating systems

BIUL supports the following operating systems:

• Windows 2012 or later
• Windows 2012 R2 or later
• RHEL/CentOS 5 or later
• Debian/Ubuntu 12.04 or later

Supported browsers

BIUL supports the following browsers:

• Safari 9 or later
• Chrome 52 or later
• FireFox 48 or later
• Edge

Supported database versions

The standard Microsoft SQL Server scenario is set up on a U-Series Appliance. The following database versions and platforms are compatible for the BIUL database:

• Microsoft SQL Server 2014, 2016, and 2019
• SQLite versions 3.7.17 to 3.37

ℹ️

Note

The only MS SQL Server configuration that has been tested and approved is with SQL Server running on the same machine as the BIUL installation, which is the standard UVM Appliance setup. Running MS SQL Server on a separate, dedicated database server is not supported.

Prepare for the installation

• Run the install using an account with root or administrator privileges.
• Copy the installers for BeyondInsight for Unix & Linux, Endpoint Privilege Management for Unix and Linux, and AD Bridge to the server.
• If deploying to an HP-UX server, make sure gzip is in /usr/bin or /bin. If it is not, create a symbolic link.

  ln –s /usr/contrib/bin/gzip /usr/bin/gzip
  

Linux install

To install BeyondInsight for Unix & Linux on a Linux operating system, use the following syntax.

RHEL and CentOS

# install, where {version} is the current version
rpm -i biul-{version}.rpm
# optional: verify software is running
service pbsmc status

# configure firewall using OS version appropriate command:
# RedHat Enterprise Linux/CentOS 7:
firewall-cmd --zone=public --add-port=4443/tcp --permanent 
firewall-cmd --reload

# or, RedHat Enterprise Linux/CentOS 6:
iptables -A INPUT -p tcp -m tcp --dport 4443 -j ACCEPT 
service iptables save

Debian and Ubuntu

# install, where {version} is the current version
dpkg -i biul-{version}.deb

# optional: verify software is running
service pbsmc status

# configure firewall using OS version appropriate command:
# for ubuntu 14+:
 ufw allow 4443

# or other versions:

iptables -A INPUT -p tcp -m tcp --dport 4443 -j ACCEPT 
service iptables save

Windows install

To install BeyondInsight for Unix & Linux on a Windows operating system:

1. Run the msi package and follow the install wizard.
2. After you go through the wizard, configure the firewall.
3. Open Control Panel > System and Security > Windows Firewall.
4. Click Advanced Settings.
5. Click Inbound Rules.
6. In the Actions window, click New Rule.
7. Click Rule Type of Port, and then click Next.
8. On the Protocol and Ports page, click TCP.
9. Select Specific Local Ports and type a value of 4443. Click Next.
10. On the Action page, click Allow the connection, and then click Next.
11. On the Profile page, click the appropriate options for your environment and click Next.
12. On the Name page, enter a name for BeyondInsight for Unix & Linux.
13. Click Finish.

Prepare AD Bridge and EPM-UL

You can use BIUL to install AD Bridge and Endpoint Privilege Management for Unix and Linux software on a remote host. To do so, BIUL must have access to an installer for the software. You can supply the installer by copying ISO files to the console server, or by uploading the software from within BeyondInsight for Unix & Linux.

Copy ISO files to the console server

You must copy and extract the ISO files for the AD Bridge and EPM-UL installers.

ℹ️

Note

The installer path folder structures must not be modified.

AD Bridge

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\pbis

Unix and Linux

/usr/local/bin/software/pbis/

Endpoint Privilege Management for Unix and Linux

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\pmul

Unix and Linux

/usr/local/bin/software/pmul/

Solr

Windows

C:\Program Files (x86)\BeyondTrust\PBSMC\software\Solr

Unix and Linux

/usr/local/bin/software/solr/

Upload software

Alternatively, you can upload software for AD Bridge and EPM-UL installers on the Settings page.

ℹ️

Note

You cannot upload software on the BeyondTrust U-Series Appliance. Use BT Updater to update local packages.

To upload software:

1. Click Settings > Software, and then click the upload icon.

2. Drag the file to the upload area.

   Optionally, click anywhere in the upload area to navigate to the file. The AD Bridge ZIP files and Endpoint Privilege Management for Unix and Linux ISO files are large. The upload can take time. A progress bar shows the upload progress. You can resume an upload if an interruption occurs (for example, a session timeout occurs).

3. After the upload is complete, BeyondInsight for Unix & Linux unpacks the files, which can take a few minutes. The software is available after the unpacking is complete.

4. To update the status of available software, click the refresh icon.

Configure BeyondInsight for Unix & Linux

You can customize the console using the pbsmc.toml.default file located in:

• Linux: /etc/pbsmc
• Windows: %ProgramFiles%\PBSMC

First, you must create a copy of the file using the name pbsmc.toml. You can include only the settings that you want to customize.

The BIUL API uses a markup language called TOML that is hierarchical. The settings are divided into sections and keys. Be sure to include the section title in pbsmc.toml. For example, if you want to change the default port number, the text will look similar to the following:

[server]
port="4443"

ℹ️

Note

Apply proper security settings on the TOML file. The file owner requires Read and Write privileges.

You can configure the following settings.

Database

By default, the console creates a SQLite database in /etc/pbsmc/pbsmc.sqlite on Linux, or in %ProgramFiles%\pbsmc on Windows. This can be changed to another location.

[database]
dialect="sqlite3"
url="./pbsmc.db"

Server

By default, the console runs on port 4443. Before changing this value, stop the service.

[server]
disabled=false
port=":4443"
softwarepath="/usr/local/bin/software"
uploads="/tmp/pbsmcUploads"
passwordcost=14

By default, the BeyondInsight for Unix & Linux server runs as the root user. In a Linux environment, you can override this default behavior to run as a dedicated user with only access to the BIUL resources.

1. Create a Linux user and group to use for running BeyondInsight for Unix & Linux.

useradd biul
groupadd biul
usermod -a -G biul biul

2. Stop the BeyondInsight for Unix & Linux service using systemctl stop pbsmc.
3. Specify this user and group as a value in the BeyondInsight for Unix & Linux config file (pbsmc.toml), in the server section, via the key runprivs, separated by a colon (user:group).

runprivs = "biul:biul"

See also the sample config file included with the installation, /etc/pbsmc/pbsmc.toml.default.

SSL

By default, the console supports encrypted HTTPS connections using automatically generated, self-signed certificates. The console serves only HTTPS traffic on the configured port, unless explicitly configured to fall back to insecure HTTPS in the pbsmc.toml configuration file. A custom certificate pair may also be provided and placed in the configuration file.

[ssl]
enabled=true
cert="/usr/local/bin/cert.pem"
key="/usr/local/bin/key.pem"

Worker pool

Console tasks are run in a concurrent pool of processes. The default number of processes running at a time is 20. You can increase the pool size to allow jobs to complete faster. However, the server performance might lag, and decreasing the pool size has the opposite effect.

[pool]
size=20

Logging

The logging level configuration.

[logging]
loglevel="info"
maxage=365
maxsize=10

Encryption keys

Encryption keys for BIUL use base64 encoded AES-256 encryption. The key secures sensitive data stored in the database. More than one key can be used at a time. The active key in the pbsmc.toml file is the key currently in use.

If you start BeyondInsight for Unix & Linux without an encryption key, one is generated for you. You can review the comments in the pbsmc.toml.default file.

[keys]
active="abcdefg"
revoked= [
    "abcd",
    "efgh"
]
known = [
    "abcde",
    "fghij"

]

⚠️

Important

You must restart the service to apply changes.

SSH cipher and key exchange configuration

[ssh]
ciphers=[
  "aes128-ctr",
  "aes128-gcm",
  "aes128-cbc"
]
key_exchanges=[
  "curve25519-sha256",
  "ecdh-sha2-nistp256",
  "ecdh-sha2-nistp384"
]

Scrypt

Increasing the value of the parameters makes it more difficult for an attacker to crack a given password, but that increase in security slows down the login process for a legitimate user.

⚠️

Important

Unless you fully understand the implications of adjustments to the parameters below, we recommend using the default parameters. For help with this specific configuration, contact BeyondTrust Support.

[scrypt]
N-65536
r=8
p=1

Upgrade BIUL

We recommend running the latest available version of BeyondInsight for Unix & Linux (BIUL) software. Update your systems as upgrades become available.

Prerequisites

Before upgrading any versions of BIUL software or existing settings, we recommend you test your deployment in a preproduction environment. This will help mitigate any unforeseen compatibility issues, and avoid disruption to the business. In addition, export your policies for backup purposes prior to an upgrade.

All BIUL installers automatically remove old versions of BIUL software.

BIUL guarantees backward compatibility with previous versions, but does not guarantee forward compatibility.

Upgrade with BT Updater

To upgrade BIUL, use the BT Updater tool.

Upgrade workflow

1. Get and review the Release Notes for this latest BIUL version.
2. Use BT Updater to download the latest BIUL version installer.
3. Run the installer for BIUL.

Upgrade BIUL using the manual option (standalone installation)

If you have a standalone installation, to upgrade BIUL without using BT Updater:

• Download BIUL packages from our Customer Portal.
• Use the native package upgrade command (for example: rpm -U [the_biul_rpm_file]) to upgrade.

Uninstall BeyondInsight for Unix & Linux

Use the instructions that follow to uninstall BIUL from your operating system.

RHEL and CentOS

In an escalated shell session, enter:

# remove
rpm -e pbsmc

# optional: remove config and db
rm -rf /etc/pbsmc
rm -rf /usr/share/pbsmc/

Debian and Ubuntu

In an escalated shell session, enter:

# remove
dpkg -r pbsmc

# optional: remove config and db
rm -rf /etc/pbsmc
rm -rf /usr/share/pbsmc

Windows

1. Open Control Panel.
2. Click the Add or Remove Software icon.
3. Remove BeyondInsight for Unix & Linux. Configuration and database files can be manually deleted in the %ProgramFiles%\PBSMC\ directory.

Run BeyondInsight for Unix & Linux after Installation

Log in to the console using a supported browser: https://localhost:4443. If this is your first time logging into the console, the First-run wizard starts.

⚠️

Important

If the wizard starts and this is not the first time the console has been run, do not go through the wizard again. All data in the system will be lost. Contact BeyondTrust Technical Support.

Set up the console using the first run wizard

If this is the first time you are logging on to the console, complete the wizard and configure the system settings.

Configure BIUL

The following sections match the layout of the First-run wizard in BeyondInsight for Unix & Linux (BIUL). Please follow along for assistance with BIUL's initial configuration and setup.

1. Welcome: Read the available information carefully to ensure a smooth configuration process.

ℹ️

Note

Proceeding will reset the database to its initial state. This is an unrecoverable action.

2. Users:
   • Create the administrative accounts that will be used to log into the console. On this step, you can add multiple accounts.
   • After entering each new account, click Save to confirm the account details and to populate a list of accounts under Configured Host Users.
   • To delete an account, click the Delete icon next to the account's name.
   • When you've added the desired number of accounts, click Next Step.
   • Credentials: Create credentials for remote hosts. The credentials are used to connect to the remote hosts.
3. Summary: Review the settings and save. You are now able to log in to the console using the administrator account you created in the wizard.

RNS deployment

What is the RNS deployment?

The Registry Name Service (RNS) deployment is a way to manage an Endpoint Privilege Management for Unix and Linux (EPM-UL) installation using RNS and Client Registration Profiles (CRP).

How is it useful?

Deploy an RNS network using CRP that uses synchronized role-based policies with policy and log server redundancy. All required keys are managed by the system and REST connectivity with BIUL is established automatically.

A minimum deployment of RNS can be a single host, but to better illustrate features and BIUL integration, this guide provides a more robust example.

ℹ️

Note

This guide assumes that BIUL has been deployed and that it has access to EPM-UL 10.3 or later.

Client Registration Profiles

Installation of Endpoint Privilege Management for Unix and Linux (EPM-UL) has historically required manual steps, such as editing settings files or copying keys and settings from machine to machine. Client Registration Profiles (CRP) simplify EPM-UL deployments by allowing the user to configure some environmental settings during an installation.

✅

Example

A profile can be used to copy encryption keys from machine to machine to enable communication. It can also copy a settings file or join Registry Name Service (RNS) groups immediately.

Without using CRP, administrators need to manually provision files, keys, etc., on every host. CRP provides a centralized, customizable definition of what an installation looks like and handles that provisioning.

ℹ️

Note

CRP can be used with or without RNS; however, in RNS environments, CRP is required.

Registry Name Service

Registry Name Service is an alternative installation mode for EPM-UL. Historically, there has been no formal way to provide an entire EPM-UL network topology (what clients are involved, what policies they are receiving, etc.) or synchronization of important elements.

RNS provides a host registry that allows the user to define service groups and to manage members of those groups.

✅

Example

The administrator may create a custom_policy group that is in the category policy. This group, which is responsible for managing and delivering policy, is assigned members of three possible roles:

• Primary: Responsible for handling policy writes and synchronization
• Secondaries: Maintain copies of policy and can be used for delivery
• Clients: Customers of this policy

RNS Registry Primary

The RNS Registry Primary server is the primary in the Registry group, of which there is only one per EPM-UL network. This server provides the Client Registration Profiles for subsequent installations and is the source of the network map for the deployment.

Prepare an action plan

Before deployment, you should make a few decisions and create an action plan. In this example, our objective is the following:

• Use a host (rns-primary.biul.qa) as the primary Registry Name Service (RNS) server.
  Use role-based policy.
• Use Client Registration Profiles (CRP) to onboard new machines to the RNS network.
• Use the default RNS log group, but create a custom policy group (custom_policy).

ℹ️

Note

The step above is not required. It is merely to illustrate the process.

• Use a host (services-primary.biul.qa) as the primary log and policy host.
• Use a second host (services-secondary.biul.qa) as the secondary for the previous.
• Use BIUL to deploy a client to this RNS network. It writes to the log server and gets policy from the policy server.

Create action plan steps

Based on the objectives above, you can now create action plan steps and follow through the logical order:

1. Discover hosts.
2. Manage credentials.
3. Profile hosts.
4. Deploy the RNS primary.
5. Create the custom policy group.
6. Configure Client Registration Profiles.
7. Deploy the group primaries.
8. Enable and configure role-based policy.
9. Deploy the group secondaries.
10. Deploy the client.
11. Execute policy.

Discover Hosts after authentication

You can discover and manage hosts from the Host Inventory page in BIUL.

• After authenticating into BIUL, click the Host Inventory tile on the home page.
• Next, click the Add Hosts dropdown menu grid item.
• Select Scan for Hosts. An additional card appears, with fields you can edit to add a new host.

Provide the IP addresses of the machines being used in this deployment. You can provide a file, an IP range, or a single IP. Enable Automatically accept SSH fingerprints for demo purposes.

Manage credentials

From the left navigation menu, select the Hosts page, and then select the Host Credentials tile.

On the far right of the Credentials grid, click Manage Credentials to open the dropdown menu. Next, select Create Credential. Create credentials for each of your hosts. For demo purposes, it may be useful to manage one set of credentials replicated on each machine.

ℹ️

Note

In real-world scenarios, you could use distinct credentials or Password Safe to manage secrets.

Profile hosts

BIUL must do an initial scan of the hosts to capture some basic information. Navigate to the Hosts Inventory tile from the Hosts page. The discovered hosts become visible in the grid.

1. At the right of the server hostname row, click the ellipsis menu icon, and then select Perform Host Actions.
2. Select Profile under Step 1: Primary Action. Click Next Step. Since the other steps are not needed here, they are skipped.
3. In Step 4: Credential Selection, choose the appropriate credential from the dropdown menu and select from the provided delegation tools.

ℹ️

Note

If your credentials are the same on each machine, you can select all hosts that they apply to in the grid, and instead choose Actions > Perform Host Actions from the Hosts Inventory page.

4. At Step 5: Summary, you can review the information you've provided before you continue. Click Finish to finalize your actions and run the profile.

Review on the task page

1. Review the Task page and verify the completed status of attempted actions under Task Summary.
2. To view more information about Task Status, click Task Details.

ℹ️

Note

Task information is always available via the Tasks navigation element.

Deploy the RNS Primary from Hosts Inventory

On the Hosts Inventory page, at the right of the server hostname row, click the vertical ellipsis icon in the Inventory grid to display a dropdown menu that displays the following menu items: View Host Details, Perform Host Actions, Profile Host with Default Credentials, Deploy SSH Key for Authentication, and Delete Host.

1. Click Perform Host Actions.
2. On the expanded Perform Action card, choose Endpoint Privilege Management for Unix and Linux from the list of software under Step 1: Primary Action. Click Next Step.
3. On the Step 2: Secondary Action card, set the secondary action to Install. Click Next Step.
4. On the Step 3: Action Requirements card, select Primary Registry Server and All Components from the Installation Template dropdown menu. Choosing this option assigns the host the Primary role in the Registry Name Service group.
5. After selecting the Primary Registry Server and All Components template, select Install Primary Registry Server from the Client Registration Server dropdown. Click Next Step.
6. In the Step 4: Credential Selection card, select the appropriate host connection credential in the Credential field along with the appropriate delegation tool from the available options. Click Next Step.
7. In the Step 5: Summary card, review all of the previous entries before finalizing your changes.
8. Click Finish to proceed to Step 6: Review Task Details which displays the Task page. Review the completed status of the performed actions under the displayed Task Summary. Click Task Details to view expanded details about the actions. Errors are displayed during these steps to assist with troubleshooting.

⚠️

Important

Each RNS deployment must have exactly one Primary Registry Server.

Create an RNS Custom Policy Group

As noted previously, this step is entirely optional and is included only to illustrate functionality. Rather than using the dflt_policy_service group, which is always available in the Registry Name Service (RNS), create a custom group and use it in the deployment.

From the Hosts landing page, select Registry Name Service.

Choose the primary that was just installed from the presented list in the grid. A new list of categories appears under Service Group Categories. Select the Policy category and choose Add Service Group. In the expanded Service Groups card, name the new group custom_policy_group and click Create.

Configure Client Registration Profiles

In a Registry Name Service (RNS) deployment, Client Registration Profiles (CRP) are always retrieved from the Primary Registry group. Because of this, create the profiles there.

Choose Client Registration Profiles to enter the editor.

Make three new Registration Profiles:

• rns_primaries: Assigned to Group Primaries
• rns_secondaries: Assigned to Group Secondaries
• rns_clients: Assigned to Clients

To do this, follow the same action three times by cloning the default profile for each new Registration Profile.

ℹ️

Note

Rather than starting a new profile from scratch, clone the default profile for all three profiles. This allows you to take advantage of its existing capabilities.

Clone each profile

To clone each profile:

1. Select the default profile and choose Clone. Give the profile a meaningful name, such as rns_primaries, rns_secondaries, or rns_clients.
2. With one of the three profiles selected, expand Role Registrations. You should see two registrations already configured using two of the default services groups.
3. Change the Role field for each of these to match the desired type. For example, primary for the rns_primaries group.
4. Change the group name of the policy service group from dflt_policy_service to the one defined in the previous step. In this case, it is custom_policy_group.

Deploy the RNS Group Primaries

The deployment of the Group Primaries is explained in this section. On the Hosts page, click Hosts Inventory, choose the desired host, and click on the vertical ellipsis icon to select Perform Host Actions.

On the expanded Perform Action card, choose Endpoint Privilege Management for Unix and Linux from the list of software under Step 1: Primary Action. Click Next Step.

On the Step 2: Secondary Action card, set the secondary action to Install. Click Next Step.

In the Step 3: Action Requirements card, choose an installation template. Select All Components from the Installation Template dropdown menu.

ℹ️

Note

Choosing All Components installs policy, log, and client components.

For the Client Registration Server, choose the RNS Primary that was configured previously. A Primary Registry Server label and an icon are provided to help identify it. Choosing this joins this sever to the Registry Name Service (RNS) network.

In the Client Registration Profile dropdown menu, choose the rns_primaries profile. After you choose the server and click Next Step, EPM-UL installs and uses the profile to perform some additional steps.

ℹ️

Note

EPM-UL copies the settings file and keys required for encrypted communications. It also automatically joins this host to the dflt_pbpolicy_service and dflt_log_service as the group primary.

When the installation is complete, verify the configuration by visiting the Hosts main page and selecting Registry Name Service. Choose your primary from the presented list. A new list of categories appears on a new page under Service Group Categories. Choose the Policy category, which lists all policy groups. Select dflt_policy_service. A list of all hosts and their roles are displayed; the host you just installed is registered here as the group primary.

ℹ️

Note

This interface can be used to create new groups, add or remove hosts to existing groups, and to promote hosts in the group.

Enable and configure role-based policy

Before continuing the deployment, you must first configure policy.

ℹ️

Note

This can be done after deployment is complete, but with it in place, this policy is immediately synced when the secondary is in place, rather than be re-synced later.

1. On the left side menu, click Policy.
2. Using the filtering options (or from the list), select a server (host).
3. At the right of the server hostname row, click the ellipsis menu icon, and then select Server Details.

ℹ️

Note

In the Registry Name Service (RNS) deployments, you only write changes to primaries. If you had chosen a secondary, the policy would not be available for editing.

Enable RBP

To enable RBP, click the Settings & Configuration tile.

On the Endpoint Privilege Management for Unix and Linux Policy Settings page, click Enable Role-Based Policy.

Configure RBP

After you swap modes, select Server Details at the top of the page to configure a policy. Click the Policy tile to access more options.

Add command group

Command groups are added when the user wishes to designate a list of commands that are allowed or rejected for a specific set of users.

To add a command group:

• From the available tiles, click the What tile to move to the Command Groups page.
• In the Command Groups grid, click Add Command Group to reveal the Command Groups card.
• With the Command Groups card revealed, type the desired command group name into the Command Group Name field, as well as any command group description you may want to add into the Command Group Description.
• In the Change requested by [loggedInUserName] field, enter a reason for the assignment or change.
• Click Save to confirm your changes.

Commands are added to a Command Group by entering each item under the Commands section.

• To delete an individual command, click the Delete icon beside the command.
• Otherwise, to delete an entire command group, click the Delete button that appears after a command group has been created.

✅

Example

For example, a user may wish to add a list of basic commands consisting of ls, date, whoami, and id. Create a command group called Basic Commands, and add each of the previous commands to the command group.

Create new users

Next, you must choose users and add a new secure user.

To create a new user:

• At the top of the page, select Role Based Policy to navigate back to the RBP grid, and then select the Who tile.
• In the Users grid, click Add User / Group to reveal the dropdown menu.
• There are multiple types of user-creation options available to choose from, but for this guide select the Secure User option.

With the Users and Groups card revealed, type the desired username into the field, as well as any description you want to add into the Description field, and click Save Changes.

• Names entered into the Username field are entered freely.
• The username is now visible in the Users grid.

ℹ️

Note

A username can be edited or deleted at any time by left-clicking the username in the Users grid.

Create new roles

Finally, create a new Role. Make sure to use root as the run user and the command group for your commands.

To create a new role:

• At the top of the page, select Role Based Policy to navigate back to the RBP grid, and then select the Roles tile.
• From the Roles grid, click Add Role to reveal the expanded Roles card.
• Create a new role-based policy role, and then click Create to finalize your changes.

Deploy and Manage RNS Secondaries

Deploying a secondary very closely mirrors the process outlined in the Deploy the RNS Group Primaries section.

The primary difference is that you should change the selected Client Registration Profile (CRP) to the rns_secondaries, in order to make this host the secondary, for both the policy and log services.

Deploy Single and Multiple Clients

Like deploying a secondary, deploying a client very closely mirrors the process outlined in the Deploy the RNS Group Primaries section.

The primary change here, is that you will need to change the selected Client Registration Profile to the rns_clients in order to make this host a client of both the policy and log services.

Deploy multiple clients

To deploy multiple clients, select all applicable hosts in the grid and use Actions > Perform Host Actions to deploy multiple clients simultaneously.

Execute policy

SSH into the client and run a command defined in your Role Based Policy (RBP) via pbrun.

✅

Example

Assuming the policy is configured to accept this command, you will see an accept message, or a reject message otherwise.