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:

"registrynameservice yes" Required in every host that utilizes Registry Name Service.
submitmasters, acceptmasters, logservers To lookup servers in the Registry Name Service a single asterisk is used. Each of these settings can be set and migrated individually and can be used with hostnames or IP addresses appended if hard-coded failover servers are desired.
servicedb This is required on Primary and Secondary Name Servers to specify the path to the Registry Name Service database.
svccachedb This is required on all hosts to specify the path to the Registry Name Service Cache database.
dbsyncdb This is required on all primary hosts to specify the path to the Database Synchronization database.

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.

registrynameservice	yes
registrynameservice	no

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.

rnsoptions UseAllIPs

No default value

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 (/).

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

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 (/).

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

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. Smaller values allow clients to retrieve changes in configuration in the Registry Name Service more quickly, but produce more network and load on the Registry Name Servers.

svccacherefresh 120
svccacherefresh 110

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.

warnusersvccache yes
warnusersvccache no

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 Further 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 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" }'

Add the New Host as a Primary Server

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

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