Registry name service and database synchronization

Registry name service and database synchronization

Endpoint Privilege Management for Unix and Linux has historically required manual or customer-developed processes to copy policy from one policy server to another to make sure that failover and load balancing were addressed. Endpoint Privilege Management for Unix and Linux has historically required manual or customer-developed processes to copy encryption key files from one host to another to ensure no interruption in communication between its components. Hostnames or IP addresses were hard-coded into the settings file on every client and server to detail which servers provided services for each client. Although the use of DNS could mitigate some of these issues, day-to-day maintenance of these settings and policy configuration across multiple hosts remains arduous and open to user error.

As a solution to these problems, a flexible and powerful Registry Name Service incorporating Database Synchronization has been developed and integrated into Endpoint Privilege Management to provide advanced failover and load balancing automatically, centralized role based management, and the ability to form groups of clients that share configuration or policy based on role or business organization.

Service groups and planning

The Registry Name Service provides the product with a method of addressing and locating other components of the BeyondInsight product within the enterprise. Each category of service, including Endpoint Privilege Management for Unix and Linux Policy Authorization, Logging Services, and the Registry Name Service itself, have distinct groups which are comprised of a single primary server and zero or more secondary servers.

The primary host accepts all the configuration changes within that specified Service Group and automatically synchronizes these changes to the secondary service hosts. Other functions, such as authorization or data retrieval, are available from any of the secondary hosts within the Service Group, providing effective load balancing for clients.

Each host that makes up the Service Group is defined in the Registry Name Service database, including primary and secondary servers and clients. This allows every host within the BeyondInsight enterprise to identify every machine that will make up its Service Group. This also allows a more fine-grained control of licenses within the product.

When upgrading or installing a new BeyondInsight enterprise and incorporating the Registry Name Service, the first server installed becomes the Primary Registry Name Server. This creates a repository with the default groups of registry_name_service, dflt_pbpolicy_service, dflt_log_service, dflt_sudopolicy_service, dflt_logarch_service, and dflt_fim_service.

Once the primary Registry Name Sever has been installed, the administrator is free to define more Service Groups to allow multiple areas of the enterprise to work and be administered autonomously. Then, for each Service Group, the administrator can start installing the primary servers, secondary servers, and finally the clients. As soon as a host is added to a Service Group and its role within the group is defined, it will be available to use. Secondary servers are provided with configuration from the primary, and clients are aware of service providers immediately.

ℹ️

Note

There can only be one Registry Name Service group.

Hosts are members of one instance of each type of Service Group that is available. For example, a typical BeyondInsight policy client is a member of a single BeyondInsight Policy Service Group and a single Endpoint Privilege Management Log Services Group. Within each of these groups the primary and secondary servers provide the load balancing and failover required by mission-critical environments.

Command line configuration

The configuration of the Registry Name Service is provided through the enhanced pbdbutil command line utility. New categories have been added.

--svc is used on the Primary Registry Name Server to configure the Registry Name Service Groups:

Usage pbdbutil --svc [<options>] [ <file> <file> ...]

--scache is used on all hosts that are subscribed to the Registry Name Service and enables the interrogation of the local host Registry Name Service cache:

Usage pbdbutil --scache [<options>] [ <file> <file> ...]

--dbsync provides information regarding the status of Database Synchronization on primary servers:

Usage pbdbutil --dbsync [<options>] [ <file> <file> ...]

Settings and configuration

Prerequisites

The BeyondInsight install process configures individual hosts appropriately to use the Registry Name Service from the outset. However, if BeyondInsight is upgraded or configured manually to use the Registry Name Service there are a number of settings and commands that need to be run to successfully utilize the service.

pb.settings:

We recommend that you apply these settings initially to the Primary Registry Name Server and then, as hosts are added, into the Registry Name Service.

registrynameservice

• Version 9.3.0 and earlier: registrynameservice setting not available.
• Version 9.4.0 and later: registrynameservice setting available.

The registrynameservice option provides a global switch on each host to turn Registry Name Services on or off. Once it is turned on, individual settings such as submitmaster, acceptmaster, and logservers must be configured with a single asterisk to enable each setting to look up information in the Registry Name Service.

Example

registrynameservice yes

Default

registrynameservice no

Used on

All hosts

rnsoptions

• Version 10.2.0 and earlier: rnsoptions setting not available.
• Version 10.3.0 and later: rnsoptions settings available.

rnsoptions [UseFQDN|UseAllIPs]

If set to UseFQDN, RNS uses only the first IP address in the RNS address list to contact a host.

When set to UseAllIPs, it uses all IP addresses held within RNS to contact a host.

These are mutually exclusive.

Example

rnsoptions UseAllIPs

Default

No default value

Used on

All RNS hosts

servicedb

• Version 9.3.0 and earlier: servicedb setting not available.
• Version 9.4.0 and later: servicedb setting available.

The servicedb option specifies the path to the Registry Name Service Database. This file is created in databasedir by default, unless the file name starts with a slash (/).

Example

servicedb /etc/pbsvc.db

Default

servicedb /opt/<prefix>pbul<suffix>/dbs/pbsvc.db

Used on

Registry Name Server

svccachedb

• Version 9.3.0 and earlier: svccachedb setting not available.
• Version 9.4.0 and later: svccachedb setting available.

The svccachedb option defines the path to the Service Cache Database. This file is created in databasedir by default, unless the file name starts with a slash (/).

Example

svccachedb /etc/svccache.db

Default

svccachedb /opt/<prefix>pbul<suffix>/dbs/pbsvccache.db

Used on

All hosts, when Registry Name Service is enabled.

svccacherefresh

• Version 9.3.0 and earlier: svccacherefresh setting not available.
• Version 9.4.0 and later: svccacherefresh setting available.

The svccacherefresh option defines how often the Registry Name Service Cache Database is checked against the Registry Name Server for updates using the scheduler service. Smaller values allow the scheduler to retrieve configuration changes in the Registry Name Service more frequently but produce more network and load on the Registry Name Servers.

Example

svccacherefresh 120

Default

svccacherefresh 110

Used on

All hosts, when Registry Name Service is enabled.

warnusersvccache

• Version 10.2.0 and earlier: warnusersvccache setting not available.
• Version 10.3.0 and later: warnusersvccache setting available.

The warnusersvccache option displays RNS Service Cache out of date message to pbrun user.

Example

warnusersvccache yes

Default

warnusersvccache no

Used on

All hosts, when Registry Name Service is enabled.

Primary registry name server configuration

To create and initialize the Registry Name Service on the Primary Registry Name Server, use:

# pbdbutil --svc -N --force

Several items are created:

• The database
• The default Service Groups
• A host record for the primary server, with:
  • The appropriate Common Name set to the local hostname
  • A Fully Qualified Domain Name
  • A role configured as Primary Registry Name Server in the Registry Name Service Group.

This can be checked using:

# pbdbutil -P --svc -l -l
    {
    "svcgid": 1,
    "svcgname": "registry_name_service",
    "svc": "registry",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false,
    "svcs": [
    {
    "svcgid": 1,
    "hostid": 1,
    "role": "primary",
    "sorder": 1,
    "created_usec": "2016-11-10 11:12:20",
    "updated_usec": "2016-11-10 11:12:20",
    "cn": "pbulprimrns",
    "uuid": "3d13a9eb-7340-4199-aa47-1570941bd50f",
    "fqdn": "pbulprimrns.org.com",
    "addrs": [
    {
    "family": 4,
    "port": 24351,
    "addr": "192.168.1.1"
    }
    ],
    "tnlzone": 0,
    "deleted": 0
    }
    ]
    }
    {
    "svcgid": 2,
    "svcgname": "dflt_pbpolicy_service",
    "svc": "pbpolicy",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 3,
    "svcgname": "dflt_log_service",
    "svc": "logsvr",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 4,
    "svcgname": "dflt_sudopolicy_service",
    "svc": "sudopolicy",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 5,
    "svcgname": "dflt_Solr_service",
    "svc": "Solr",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 6,
    "svcgname": "dflt_logarch_service",
    "svc": "logarchive",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 7,
    "svcgname": "dflt_beyondinsight_service",
    "svc": "beyondinsight",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
    }
    {
    "svcgid": 8,
    "svcgname": "dflt_fim_service",
    "svc": "fim",
    "updated_usec": "2016-11-10 11:12:20",
    "deleted": false
}

Please note the use of -P to print the output in a pretty format to make it easier to read.

Add hosts into the enterprise

Further hosts can be added to the Registry Name Service in two ways. New hosts can be added on installation by using the Client Registration option in pbinstall. If this is selected and a suitable Client Registration profile is used, detailing default Registry Name Service Groups, the host is automatically added to the default Service Groups as a client, depending upon the host function selected at install time.

However, if automatic registration is not used, the host can be manually added to the Registry Name Service.

First, the host's unique UUID is required. On the host run:

# pbdbutil --info --uuid 969ecab2-93d8-4322-a8cf-6314457053bf

Then use this to add the host on the Primary Registry Name Server:

# pbdbutil --svc -u '{"cn":"pbtest","fqdn":"pbtest.org.com","uuid":"969ecab2-93d8-4322-a8cf-6314457053bf" }'

The Fully Qualified Domain Name (FQDN) is used to look up the host's address in the local Name Service. If the FQDN is not supplied, the Common Name (CN) is used instead.

Once the host has been added, it can be added to the specified Service Group as a particular role:

# pbdbutil --svc -u '{ "svcgname" : "test_pbpolicy", "cn" : "pbtest", "role" : "client" }'

If the host is added as a secondary server to a Service Group that already has a primary server, it starts receiving configuration automatically from the database synchronization. The license database is synchronized on the server when the role changes from client to primary license server.

Routine configuration examples

A list of hosts contained with the Registry Name Service is retrieved using:

# pbdbutil -P --svc -L
{
    "hostid": 1,
    "cn": "pbulprimrns",
    "uuid": "3d13a9eb-7340-4199-aa47-1570941bd50f",
    "fqdn": "pbulprimrns.org.com",
    "addrs": [
        {
        "family": 4,
        "port": 24351,
        "addr": "192.168.1.1"    
        }
        ],
    "tnlzone": 0,
    "updated_usec": "2016-11-10 11:12:20",
"deleted": false
}

Add new service groups

# pbdbutil --svc -u '{ "svcgname" : "test_pbpolicy", "svc" : "pbpolicy" }'
# pbdbutil --svc -l
{"svcgid":1,"svcgname":"registry_name_service","svc":"registry","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":2,"svcgname":"dflt_pbpolicy_service","svc":"pbpolicy","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":3,"svcgname":"dflt_log_service","svc":"logsvr","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":4,"svcgname":"dflt_sudopolicy_service","svc":"sudopolicy","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":5,"svcgname":"dflt_Solr_service","svc":"Solr","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":6,"svcgname":"dflt_logarch_service","svc":"logarchive","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":7,"svcgname":"dflt_beyondinsight_service","svc":"beyondinsight","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":8,"svcgname":"dflt_fim_service","svc":"fim","updated_usec":"2016-11-10 11:12:20","deleted":false}
{"svcgid":100,"svcgname":"test_pbpolicy","svc":"pbpolicy","updated_usec":"2016-11-10 11:32:42","deleted":false}

The default groups have Service Group IDs less than 100 and cannot be removed.

Retrieve specified service group information

# pbdbutil --svc -g '{ "svcgname" : "test_pbpolicy" }'
{"svcgid":100,"svcgname":"test_pbpolicy","svc":"pbpolicy","updated_usec":"2016-11-10 11:32:42","deleted":false}

Retrieve specified host by common name

# pbdbutil --svc -g '{ "cn" : "pbulprimrns" }'
{"cn":"pbulprimrns","uuid":"3d13a9eb-7340-4199-aa47-1570941bd50f","fqdn":"pbulprimrns.org.com","addrs":[{"family":4,"addr":"192.168.1.1","port":24351}]}

Retrieve specified host UUID

# pbdbutil --svc -g '{ "uuid" : "3d13a9eb-7340-4199-aa47-1570941bd50f" }'
{"cn":"pbulprimrns","uuid":"3d13a9eb-7340-4199-aa47-1570941bd50f", "fqdn":"pbulprimrns.org.com","addrs":[{"family":4,"addr":"192.168.1.1","port":24351}]}

Retrieve the primary server for the specified service group

# pbdbutil --svc -g '{ "primary" : "registry_name_service" }'
{"svcgid":1,"svcgname":"registry_name_service","svc":"registry","updated_usec":"2016-11-10 11:12:20","deleted":false,"hostid":1,"role":"primary","sorder":1,"created_usec":"2016-11-10 11:12:20","cn":"pbulprimrns","uuid":"3d13a9eb-7340-4199-aa47-1570941bd50f","fqdn":"pbulprimrns.org.com","addrs":[{"family":4,"port":24351,"addr":"192.168.1.1"}],"tnlzone":0}

Retrieve the current hosts information from the registry name service cache

pbdbutil --scache -w
{"fqdn":"pbulprimrns.org.com","cn":"pbulprimrns","uuid":"969ecab2-93d8-4322-a8cf-6314457053bb","addrs":[{"addr":"192.168.16.138","family":4,"port":24351}]}

Retrieve the complete list of service groups and hosts

# pbdbutil -P --svc -l -l -l
    {
        "svcgid": 1,
        "svcgname": "registry_name_svc",
        "svc": "registry",
        "updated": "2016-06-14 10:43:14",
        "deleted": 0,
        "svcs": [
            {
            "svcgid": 1,
            "hostid": 1,
            "role": "primary",
            "created": "2016-06-14 10:43:14",
            "updated": "2016-06-14 09:43:14",
            "deleted": 0,
            "cn": "pbulprimrns",
            "uuid": "969ecab2-93d8-4322-a8cf-6314457053bb",
            "fqdn": "pbulprimrns.org.com",
            "addrs": [
            {
            "family": 4,
            "port": 24351,
            "addr": "192.168.1.1"
            }
            ],
            "tnlzone": 0
        }
        ]
        }
        .
        .
        .
        {
        "svcgid": 100,
        "svcgname": "test_pbpolicy",
        "svc": "pbpolicy",
        "updated": "2016-06-14 09:52:17",
        "deleted": 0,
        "svcs": [
            {
            "svcgid": 100,
            "hostid": 4,
            "role": "client",
            "created": "2016-06-14 11:06:46",
            "updated": "2016-06-14 10:05:03",
            "deleted": 0,
            "cn": "pbtest",
            "uuid": "969ecab2-93d8-4322-a8cf-6314457053bf",
            "fqdn": "pbtest",
            "addrs": [
            {
            "family": 4,
            "port": 24351,
            "addr": "192.168.1.5"
            }
            ],
            "tnlzone": 0
        }
        ]
}

Delete the host

# pbdbutil --svc -d '{ "cn" : "pbtest" }'

Delete the host completely from service database

# pbdbutil --svc -d '{ "cn" : "pbtest" }' --remove

Add the new host as a primary server

# pbdbutil --svc -u '{ "svcgname" : "test_pbpolicy", "cn" : "pbtest", "role" : "primary" }'

Update CN of the host

# pbdbutil --svc -u '{ "cn" : "pbtest.org.com", "uuid" : "969ecab2-93d8-4322-a8cf-6314457053bf" }' --bycn "pbtest"

Delete the host again

# pbdbutil --svc -d '{ "cn" : "pbtest" }'
6024 Host is a primary server - please reassign before deleting the host

Delete the service group

# pbdbutil -svc -d '{ "svcgname" : "test_pbpolicy" }' --force

Synchronize policy configuration and other configuration files

Although all configuration databases are automatically synchronized across the Service Group, other configuration such as Endpoint Privilege Management for Unix and Linux policy scripts and encryption keys are not. They must be manually configured to synchronize across the Service Group. Only files that are kept within the standard configuration database pb.db on a primary server can be synchronized, so they need to be imported, and then synchronization configured.

All configuration databases are automatically synchronized across the Service Group. Other files, such as policy scripts and encryption keys, are not similarly treated and must be manually set up for synchronization. Only files that are kept within the standard configuration database /etc/pb.db on a primary server can be synchronized, so they need to be imported, and then synchronization configured.

The pbdbutil utility has been enhanced to provide the new synchronization options:

Usage

pbdbutil --cfg [<options>] [ <file> <file> ...]

Force synchronize configuration files

Prior to EPM-UL version 22.3, not all versions of configuration files were synchronized to secondary servers and file tags and file permissions were not synchronized.

Follow the below steps to clean up secondary servers and force synchronize the configuration files including the file tags and permissions of all versions of configuration files.

1. On secondary servers, remove the existing pb.db and create a new one

mv /etc/pb.db /etc/pb.db.backup
pbdbutil --cfg --reinit

1. On primary servers, start a dbsync with --force option

pbdbutil --dbsync -R <service group> --force

Synchronize REST appkeys

EPM-UL REST appkeys are often required to authenticate users and services on remote servers, and are specific to each host. However, to provide role-based access to servers across a Service Group, REST appkeys can be marked as synchronized across the Service Group.

ℹ️

Note

The host must be the primary of the specified Service Group to synchronize the appkeys.

Usage

pbdbutil --rest [<options>] [ <file> <file> ...]

Database synchronization

dbsyncdb

• Version 9.3.0 and earlier: dbsyncdb setting not available.
• Version 9.4.0 and later: dbsyncdb setting available.

The dbsyncdb option specifies the full path to the Database Synchronization Summary Database. This file is created in databasedir by default, unless the file name starts with a slash (/).

Example

dbsyncdb /etc/pbdbsync.db

Default

dbsyncdb /opt/<prefix>pbul<suffix>/dbs/dbsync.db

Used on

All primary servers when Registry Name Server is enabled.

dbsyncrefresh

• Version 9.3.0 and earlier: dbsyncrefresh setting not available.
• Version 9.4.0 and later: dbsyncrefresh setting available.

The dbsyncrefresh option defines the interval in seconds between database synchronization tasks. Increasing this value lowers the load on primary servers, but increases the time before configuration changes are applied to secondary servers.

Example

dbsyncrefresh 360

Default

dbsyncrefresh 3600

Used on

All primary servers when Registry Name Server is enabled.

dbsyncloginterval

• Version 9.3.0 and earlier: dbsyncloginterval setting not available.
• Version 9.4.0 and later: dbsyncloginterval setting available.

The dbsyncloginterval option defines the interval in seconds between logging synchronization success and failure messages. Increasing this time makes the REST log smaller, but provides slower feedback on current status of the Database Synchronization on any given host.

Example

dbsyncloginterval 360

Default

dbsyncloginterval 720

Used on

All primary servers when Registry Name Server is enabled.