Prime Cable Provisioning provides automated tools that you use to perform certain functions more efficiently. The following table lists the various tools that this Prime Cable Provisioning release supports.

The PKCert tool creates the KDC certificate and its corresponding private key. It also allows you to verify certificate chains and copy and rename a certificate chain to the names required by the KDC.

Note	This tool is available only when the KDC component is installed.

The KeyGen tool is used to generate PacketCable service keys. The service keys are symmetric triple data encryption standard (triple DES or 3DES) keys (shared secret) required for KDC communication. The KDC server requires service keys for each of the provisioning FQDNs of the DPE. Any changes made to the DPE provisioning FQDN from the DPE command-line interface (CLI) requires a corresponding change to the KDC service key filename. This change is necessary because the KDC service key uses the DPE provisioning FQDN as part of its filename.

The KeyGen tool, which resides in the BPR_HOME/kdc directory, uses command-line arguments for the DPE provisioning FQDN, realm name, and a password, and generates the service key files.

Note

When running this tool, remember to enter the same password that you used to generate the service key on the DPE (by using the service packetCable 1..1 registration kdc-service-key command from the DPE CLI). For information on setting this password, see the Cisco Prime Cable Provisioning 6.3 DPE CLI Reference Guide.

The KDC server reads the service keys on startup. Any modification to the service keys requires that you restart the KDC server.

Syntax Description

keygen options fqdn realm password

• options are:

  • -? —Displays this usage message and exits the command.

  • -v or -version —Displays the version of this tool and exits the command.

  • -q or -quiet —Implements a quiet mode whereby no output is created.

  • -c or -cms —Creates a service key for the CMS system.

• fqdn —Identifies the FQDN of the DPE and is a required entry.

• realm —Identifies the Kerberos realm and is a required entry.

• password —Specifies the password to be used. This is also a required field. The password must be from 6 to 20 characters.

Three service key files are written in the KDC keys directory using this filename syntax:

mtafqdnmap,fqdn@REALM

mtaprovsrvr,fqdn@REALM

krbtgt,REALM@REALM

• fqdn—Identifies the FQDN of the DPE.

• REALM—Identifies the Kerberos realm.

The service key file always contains a version field of 0x0000.

Examples

# keygen dpe.cisco.com CISCO.COM changeme

When this command is implemented, these KDC service keys are written to the BPR_HOME/kdc/<Operating System>/keys directory:

mtafqdnmap,dpe.cisco.com@CISCO.COM
mtaprovsrvr,dpe.cisco.com@CISCO.COM
krbtgt,CISCO.COM@CISCO.COM

Restart the KDC, so that the new keys are recognized. Use this Prime Cable Provisioning process watchdog command to restart the KDC:

# /etc/init.d/bprAgent restart kdc

This example illustrates the generation of a CMS service key:

# keygen -c cms-fqdn.com CMS-REALM-NAME changeme

When this command is implemented, this CMS service key is written to the BPR_HOME/kdc/<Operating System>/keys directory.

cms,cms-fqdn.com@CMS-REALM-NAME

Verifying the KDC Service Keys

Once you generate the service keys on the KDC and the DPE, verify if the service keys match on both components.

The KeyGen tool requires you to enter the same password that you used to generate the service key on the DPE using the service packetCable 1..1 registration kdc-service-key command. Once you set this password on the DPE, you can view the service key from the dpe.properties file, which resides in the BPR_HOME/dpe/conf directory. Look for the value against the /pktcbl/regsvr/KDCServiceKey= property.

For example:

# more dpe.properties
/pktcbl/regsvr/KDCServiceKey=2e:d5:ef:e9:5a:4e:d7:06:67:dc:65:ac:bb:89:e3:2c:bb:
71:5f:22:bf:94:cf:2c

Note	The output of this example has been trimmed for demonstration purposes.

To view the service key generated on the KDC, run the following command from the BPR_HOME/kdc/<Operating System>/keys directory:

od -Ax -tx1 mtaprovsrvr,fqdn@REALM

• fqdn—Identifies the FQDN of the DPE.

• REALM—Identifies the Kerberos realm.

The output that this command generates should match the value of the /pktcbl/regsvr/KDCServiceKey= property in the dpe.properties file.

For example:

# od -Ax -tx1 mtaprovsrvr,dpe.cisco.com@CISCO.COM
0000000 00 00 2e d5 ef e9 5a 4e d7 06 67 dc 65 ac bb 89
0000010 e3 2c bb 71 5f 22 bf 94 cf 2c
000001a

In the examples shown here, note that the service key generated at the KDC matches the service key on the DPE.

Monitoring available disk space is an important system administration task. You can use a number of custom written scripts or commercially available tools to do so.

The disk_monitor.sh command, which resides in the BPR_HOME/rdu/samples/tools directory, sets threshold values for one or more file systems. When these thresholds are surpassed, an alert is generated through the Solaris syslog facility, at 60-second intervals, until additional disk space is available.

Note	We recommend that, at a minimum, you use the disk_monitor.sh script to monitor the BPR_DATA and BPR_DBLOG directories.

Syntax Description

disk_monitor.sh filesystem-directory x [filesystem-directory* x*]

• filesystem-directory—Identifies any directory in a file system to monitor.

• x—Identifies the percentage threshold applied to the specified file system.

• filesystem-directory*—Identifies multiple file systems.

• x*—Specifies percentage thresholds to be applied to multiple file systems.

Example 1

This example specifies that a notification be sent out when the /var/CSCObac file system reaches 80 percent of its capacity.

# ./disk_monitor.sh /var/CSCObac 80

When the database logs disk space reaches 80-percent capacity, an alert similar to the following one is sent to the syslog file:

Dec 7 8:16:06 perf-u80-1 BPR: [ID 702911 local6.warning] File system /var/bpr usage is 81% (threshold is 80%)

Example 2

This example describes how you can run the disk_monitor.sh tool as a background process. Specifying an ampersand (&) at the end of the command immediately returns output while running the process in the background.

# ./disk_monitor.sh /var/CSCObac 80 &
1020

Syntax Description

To run the event monitor, enter:

Options are used to specify the RDU connection parameters and amount of output. You have the following options:

• -noverbose—Forces the event monitor to display only the types of events being fired, not their contents.
• -host host—Specifies the host where the RDU is located. Default is the localhost.
• -username username—Specifies username for RDU host.
• -password password— Specifies password of the RDU host.
• -port port—Specifies the port on which the RDU is listening. Default is 49187.
• -secure—Sets secure mode of communication with RDU.
• -stopOnDisconnect—Stops event monitoring process on disconnecting from the RDU.
• -help—Displays help for the tool.

If need help, please restart command with '?' parameter.
Verbose mode: true 
RDU host: localhost 
RDU port: 49187 
Connecting to RDU...ok 
Listening for events... 
ExternalFileEvent added filename=gold.cm 
		rev=1014671115124(Sun Jul 14 23:35:39 IST 2019)
		source=BPR Provisioning API:BPR Regional Distribution Unit:AddExternalFile command
DeviceEvent newProvDevice ID=1,6,01:02:03:04:05:06 
		rev=1014671179380(Sun Jul 14 23:35:39 IST 2019) 
		source=BPR Provisioning API:BPR Regional Distribution Unit:AddIPDevice command IP=null 
		FQDN=null group=null
timestamp=2019-07-14 23:35:40,566 IST

Caution

Do not modify the rdu.properties without consulting the Cisco support. Changes to this file might have an adverse impact on the RDU.

The rdu.properties file contains a variety of controls that specify the behavior of the RDU. You can open this file using any text editor, and change its content to perform the functions that you want.

You can configure the RDU by using the options available in the rdu.properties file. These options are controlled by Prime Cable Provisioning settings or defined in the rdu.properties file in the BPR_HOME/rdu/conf/ directory. The default configuration parameters are:

• /server/port—Specifies the listening port of the RDU in nonsecured mode. The default port number is 49187.

• /server/secure/port—Specifies the listening port of the RDU in secure mode using SSL. The default port number is 49188.

• /server/rdu/secure/enabled—Specifies that the communication between RDU and other Prime Cable Provisioning components is secure.

• /server/rdu/unsecure/enabled—Specifies that the communication between RDU and other Prime Cable Provisioning components is unsecure.

• /secure/keystore/password—Specifies the keystore password for the keystore file. This password must be between 6 and 30 characters.

• /secure/keystore/file—Specifies the location of the keystore file.

• /secure/rdu/certificateKeyPassword—Specifies the password used to encrypt the certificate keys added in the keystore.

• /rdu/sharedSecret—Specifies the password used to encrypt the communication between Prime Cable Provisioning components and the RDU.

• /auth/user/session/limit/enabled=true - Specifies that the User session is Enabled. User session limit is disabled by default and same has to be enabled.

  Note

  If the User session is Enabled, the number of RDU connections is restricted, then the maxSessions property should be set to : maxSessions >= (number of REST PWS servers under load balancer) * (maximum number of concurrent PWS sessions) * n Where, n represents the buffer connections required for the other API clients.

Note	When you manually change properties in the rdu.properties file, remember to restart the RDU. RDU restart required for property changes to take effect. Use the BPR_HOME/agent/bin/bprAgent restart rdu command.

Sample rdu.properties File

cat /opt/CSCObac/rdu/conf/rdu.properties
/server/port=49187
/server/secure/port=49188
/server/rdu/secure/enabled=true
/server/rdu/unsecure/enabled=true
/secure/keystore/password=f2c2060fdbca0e60ae1864adb73155b9
/secure/keystore/file=/opt/CSCObac/lib/security/.keystore
/secure/rdu/certificateKeyPassword=b46411a3f24f08cd090bddd6e55d8de3
/rdu/sharedSecret=fgL7egT9zcYHs

Before you use the Admin UI, examine the adminui.properties file. This file contains a variety of controls that specify the behavior of the interface.

You can open this file using any text editor, and change its content to perform the functions that you want. After you save the changes, restart the Admin UI so that the changes take effect.

To start the Admin UI, enter:

BPR_HOME/agent/bin/bprAgent start adminui

To stop the Admin UI, enter:

BPR_HOME/agent/bin/bprAgent stop adminui

To restart the Admin UI, enter:

BPR_HOME/agent/bin/bprAgent restart adminui

You can configure the Admin UI by using the options available in the adminui.properties file. These options are controlled by Prime Cable Provisioning settings or defined in the adminui.properties file in the BPR_HOME/rdu/conf directory. The configuration parameters are:

• /adminui/port—Specifies the listening port of the RDU. The default port number is 49187.

• /adminui/fqdn—Specifies the fully qualified domain name of the host on which the RDU is running. The default value is the FQDN of the host; for example, bac_test.EXAMPLE.COM.

• /adminui/maxReturned—Specifies the maximum number of search results. You can set this value to a maximum of 5000. The default value is 1000.

• /adminui/maxDetailsReturned —Specifies the maximum number of search results when search for detailed information is requested. You can set this value to a maximum of 1000 which is also the default value.

  Note	If the memory of the deployed server is having a smaller heap size, then the maxReturned and maxDetailsReturned will become half of its values. For example, if the value of maxReturned is set to 5000, it will retrieve only 2500.

• /adminui/pageSize—Specifies the number of search results displayed per page. You can set this number at 25, 50, or 75. The default value is 25.

• /adminui/refresh—Specifies if the refresh function is enabled or disabled. This option is, by default, disabled.

• /adminui/extensions—Specifies if the use of extensions in Prime Cable Provisioning is enabled or disabled. You use extensions to augment Prime Cable Provisioning behavior or add support for new device technologies. The use of extensions is, by default, enabled.

• /adminui/maxFileSize—Specifies the maximum size of a file uploaded to Prime Cable Provisioning. The default file size is 20 MB.

• /adminui/refreshRate—Specifies the duration (in seconds) after which a screen is refreshed. The default value is 90 seconds. Before setting a value for this option, ensure that the /adminui/refresh option is enabled.

• /adminui/file/extensions—Specifies the extensions of the files that the Admin UI supports. The supported extensions are by default .bin, .cm, and .jar.

• /adminui/timeout—Specifies the length of time after which an idle session times out. The default period is set as 10 minutes. In case of any value lesser than 10 minutes, the idle session time out still happens after 10 minutes.

• /adminui/noOfLines—Specifies the last number of lines from rdu.log or dpe.log that appear on the Admin UI. The default number of lines that appear is 250.

• /adminui/redirectToHttps—Specifies whether the Admin UI should be in HTTPS mode or not. The default is true.

• /adminui/enableDomainAdministration—Specifies whether Security Domain(RBAC) can be assigned to various entities. If set to true, the Instance Level Authorization check box is shown in the RDU Defaults page. The default value is false.

Sample adminui.properties File

/adminui/port=49187
/adminui/fqdn=doc.example.com
/adminui/maxReturned=5000
/adminui/pageSize=25
/adminui/refresh=disabled
/adminui/extensions=enabled
/adminui/maxFileSize=20000000
/adminui/refreshRate=90
/adminui/file/extensions=.bin,.cm,.jar
/adminui/timeout=10
/adminui/noOfLines=250
/adminui/redirectToHttps=false

Note	By default, Prime Cable Provisioning redirects all HTTP communications over HTTPS. If you want to bypass the HTTPS redirection, set the property adminui/redirectToHttps to false in the admin.properties file.

./passwordEncryption.sh -enable

Once you enable encryption, Prime Cable Provisioning will not be able to support the 4.0 and 4.0.x API clients.

./passwordEncryption.sh -status

You can use the changeSSLProperties.sh tool, which is found in the BPR_HOME/bin directory, to change key SSL configuration properties.

The following table lists the various options that you can use to change the SSL configuration.

./changeSSLProperties.sh
 -ssl rdu enable

./changeSSLProperties.sh
 -nssl rdu disable

./changeSSLProperties.sh
 -secret changeme

./changeSSLProperties.sh
 -csp rdu

./changeSSLProperties.sh 
-cnsp rdu

./changeSSLProperties.sh 
-list n

./changeSSLProperties.sh 
-ckl /opt/CSCObac/lib/
security/.keystore

./changeSSLProperties.sh
 -ckp

./changeSSLProperties.sh
 -utp

./changeSSLProperties.sh
 -cpkp

./changeSSLProperties.sh
 -gk

./changeSSLProperties.sh
 -exp

./changeSSLProperties.sh
 -imp

./changeSSLProperties.sh
 -help

You can use the ws-cli.sh tool, which is found in the BPR_HOME/pws/bin for SOAP and BPR_HOME/restpws/bin for RESTful directory, to carry out some of the PWS configuration functions.

The following table lists the various options that are part of the ws-cli tool.

#./ws-cli.sh -ardu  test1-host  49187  admin  changeme

./ws-cli.sh -rrdu bac-test-lnx

#./ws-cli.sh -srductest1 -host 49187 admin changeme

#./ws-cli.sh -lrdu test1-host

./ws-cli.sh -ll

./ws-cli.sh -lp

./ws-cli.sh -rcc

./ws-cli.sh -removeproperty /cache/timeout

./ws-cli.sh -reloadproperty /cache/timeout

./ws-cli.sh -rpd

./ws-cli.sh -sap

./ws-cli.sh -scc clustername

./ws-cli.sh -sl general=DEBUG

./ws-cli.sh -sp /cache/timeout=100

./ws-cli.sh -ssv 10

Following are scripts that you can run to configure properties of HA resources as well as troubleshoot RDU redundancy. These scripts are available only when RDU is installed in redundancy mode. All these scripts are located under BPR_HOME/agent/HA/bin.

The following table lists the scripts that you can use to configure, monitor, and troubleshoot RDU redundancy.

BPR_HOME/agent/HA/bin/
manage_ha_resources.sh stop res_IPaddr2_1

BPR_HOME/agent/HA/bin/
configure_vip.sh ipaddress 
10.105.202.46 

BPR_HOME/agent/HA/bin/
configure_failover_threshold
.sh timeout 60

BPR_HOME/agent/HA/bin/
configure_failover_threshold
.sh threshold 6

BPR_HOME/agent/HA/
bin/set_prefered_ha_location
.sh primary

BPR_HOME/agent/HA/
bin/set_prefered_ha_location
.sh none

BPR_HOME/agent/HA/
bin/ping_resource_ha.sh 
create

BPR_HOME/agent/HA/
bin/ping_resource_ha.sh 
update

BPR_HOME/agent/HA/
bin/ping_resource_ha.sh 
delete

BPR_HOME/agent/HA/bin/
monitor_ha_cluster.sh 
timing-details 

BPR_HOME/agent/HA/bin/
monitor_fs_sync_status.sh 

BPR_HOME/agent/HA/bin/
manage_ha_resources.sh 
res_Filesystem_1

BPR_HOME/agent/HA/bin/
standby_ha_switch.sh 
secondary off

BPR_HOME/agent/HA/bin/
resolve_sb_victim.sh 
bprData

BPR_HOME/agent/HA/bin/
resolve_sb_survivor.sh 
bprLog

The deviceReader tool (deviceReader.sh) is used to extract the device details from a RDU database. It reads the device objects along with the associated resources like, CoS, DHCP criteria and presents the device information in a default file. This tool can be used against the RDU database when the RDU server is down or against a backup snapshot of the database by specifying the location with -dbdir and -dblogdir options.

This deviceReader tool provides options to save the device details in a file and it provides customization options to process the device details.

The deviceReader.sh tool is present in the $BPR_HOME/rdu/internal/db/bin/ directory.

Syntax Description

deviceReader.sh [-file outputfile] [-dbdir dir] [-dblogdir dir]

• -file — Specifies the output file name and the path to save the device information. By default, the output file (deviceinfo.txt) is generated on the current working directory.

• -dbdir — Specifies the database directory path. By default, the RDU database location is used.

• -dblogdir — Specifies the database log directory path. By default, the directory specified with dbdir option or RDU database location is used.

• -help — Displays help for the tool.

Example

# ./deviceReader.sh -dbdir /opt/backup/rdu-backup-20170410-150614/ -file /opt/result/devicedump.txt

Where,

— /opt/backup/rdu-backup-20170410-150614/ is the database directory

— /opt/result/devicedump.txt is the output file and the path to save the file

Output Device File Format

In the output device file, the device properties are stored seperated by '|':

MAC/DUID | OwnerID| Hostname | Domain| ProvGroupName | CoS | DHCPCriteria | docsis_version| device_serial_number| custom_properties

For example:

#  cat /opt/result/devicedump.txt
000000000211|testowner1|testhost1|testdomain1|chennai|null|null|1.0|000000000211|
/snmp/writeCommunityString|write123|test2|22|test1|11|/snmp/readCommunityString|read123
000000000212|testowner2|testhost2|testdomain2|chennai|null|null|1.0|000000000212|
/snmp/writeCommunityString|write1234|test2|2234|test1|1123|/snmp/readCommunityString|read1234
000000000290|null|null|null|chennai|null|null|null|null
000000000291|null|null|null|chennai|null|null|null|null

Customizing Device Data Usage

By default, the deviceReader tool provides the device data in a file. This tool also allows you to customize the device data output as per your requirement, i.e., the data handling is customized to send the device properties to a remote server / another file in a required format.

Data Handler Customization

1. Write a custom DataPrinter implementaion in Java.

   Implement the interface, com.cisco.csrc.db.util.devicereader.DataPrinter.

   
   // Source code of the interface
   	package com.cisco.csrc.db.util.devicereader;
   	
   	import java.util.Map;
   	
   	/**
   	 * The interface to mandate the methods to be implemented by the custom printer
   	 * implementations
   	 */
   	public interface DataPrinter
   	{
   	
   	    /**
   	     * This method will be invoked while reading each device object from the
   	     * database.
   	     * @param properties the device properties
   	     */
   	    public void print(Map<String, Object> properties);
   	
   	    /**
   	     * This method will be called the the tool has completed reading all the
   	     * devices. This can be used to close any resources used by the custom
   	     * printer implementations
   	     */
   	    public void closeConnections();
   	}
   

   
   The print method
   		public void print(Map<String, Object> properties)		
   			This method exposes the device properties in a Map. 
   			This method will be invoked when each IP device object is read from database by the tool
   			The keys for accessing the device device properties are available in com.cisco.provisioning.cpe.constants.DeviceDetailsKeys.
   			The keys are same as that of a getDetails() API result
   			
   	Connection handling
   		public void closeConnections();
   			This method will be invoked when the tool has completed.
   			This can be used to close any resources opened by the custom data printer implementation
   			
   	// A sample data printer implementation
   	
   	package com.test;
   	
   	import java.util.Map;
   	
   	/**
   	 * No op printer used for testing
   	 */
   	public class MyCusomDataPrinter implements DataPrinter
   	{
   	
   	    public void print(Map<String, Object> properties)
   	    {
   	        // process the device properties here. 
   	        // Eg Write to console 
   	        //System.out.println(" CoS "+properties);
   	
   	    }
   	
   	    public void closeConnections()
   	    {
   	    
   	        // Optional - handle (if any) connection house keeping here
   	    }
   	}
   

2. Implement the interface, com.cisco.csrc.db.util.devicereader.DataPrinter, and attach it to the tool’s classpath.
3. The custom data reader can be configured in <BPR_HOME>/rdu/internal/db/bin/devicereader.conf. Configure the name of class file in this file, for example: device=com.test.MyCusomDataPrinter

The Live DB Compaction tool (configureDbCompaction .sh) is used to compress the RDU database without stopping the RDU.

Prior to Prime Cable Provisioning 6.1, offline DB compaction was supported as explained in the following link: https://supportforums.cisco.com/t5/network-infrastructure-documents/db-compression-tech-note-pdf/ta-p/3149689 .

For the offline compaction procedure to work, RDU server has to be shut down. Since this offline compaction necessitates a long downtime for the RDU server, the live compaction of RDU Berkeley DB which will avoid the downtime of the RDU server is supported in Prime Cable Provisioning 6.1.

The live DB compaction is disabled by default when the RDU server is started. The live DB compaction triggered using configureDbCompaction.sh results in increase in the fill factor of Berkeley DB (default fill factor for live compaction is 80%). $BPR_HOME/rdu/internal/db/native/runTool.sh can be used to check the fill factor of the database after the live compaction is run.

Note	It is recommended to invoke the runTool.sh against a backup snapshot of the Database or when the RDU server is down.

Running of live compaction on a regular basis will free up pages in the database which will be reused by Berkeley DB to write new data. It does not reclaim any disk space but significantly lessens any further increase in disk space. Thus it avoids steep increase of database disk size. When live compaction is carried out on a regular basis (for example, once a week) the total time taken will be less than a minute. Database checkpoint will be triggered soon after compaction to sync any uncommitted changes to the DB which may take a couple of minutes.

In order to reclaim disk space, another tool runCompactDB.sh under $BPR_HOME/rdu/bin/internal/db/bin is provided which can be used in offline mode. This tool is similar to the online DB compaction tool with the only difference that it supports an additional option -reclaimspace. When this tool is run with -reclaimspace option, it will recover disk space. The disk space reclaimed by this tool will vary depending upon the way the nonempty pages are allocated. Only pages at the end of a file can be returned to the file system in this tool. The compact algorithm makes a one-pass over the pages of the database, so nonempty pages at the end of the file will prevent free pages (that are placed on the free list) from being returned to the file system. That is the reason we recommend regular live DB compaction to avoid growing of DB disk size and this offline DB compaction can be used occasionally along with online DB compaction tool.

Even though the online DB compaction tool supports scheduling of live DB compaction at regular intervals, we recommend triggering one time execution of online DB Compaction after taking a Database Backup at periodic intervals (achievable using a cron job). Since data is paramount and database manipulation requires utmost care, this approach will allow the user to have a control over the DB and a valid backup to restore in case of any unforeseen failure during DB compaction.

The online or offline DB compaction tool is not a direct replacement to DBdump/dbload utility. If the user doesn't run online or offline DB compaction tool periodically then DBdump/dbload utility is best tool to reclaim disk space. In general, most of the data access should be serviced by the cache, so the file fragmentation or low fill factor should not have a noticeable performance impact.

TheconfigureDbCompaction .sh tool is present in the $BPR_HOME/rdu/bin/ directory. Once the compaction is run, the status of the compaction and the time taken will be available in $BPR_DATA/rdu/db/history.log.

Note

We recommend you to use the offline compaction once at the very beginning using (db_dump and db_load BDB utility) as mentioned in the above support forum link. This will reduce the DB disk size, so that the live compaction will make sure to stop the increase in disk space. It is recommended to take a backup of the database each time before running the live compaction.

Error Handling:

If compaction is run when database backup or DB log deletion is in progress, it will throw an error and exit.

Since the compaction process will lock portions of the DB tables when it performs commit, you may see write batches to the DB failing at that time. If write batches higher than10/seconds is sent when compaction is in progress, you are likely to see RDU_BUSY.

Syntax Description of Online Compaction Tool

configureDbCompaction.sh [-show] [-run option] [-interval value] [-fillfactor ff]

• -show — Displays the current values of the compaction parameters.

• -run — This parameter specifies whether the compaction process has to run once or scheduled or disabled. Valid values are 1, 2, and 3. The default value is 3.

  1 (Once) - Trigger compaction once.

  2 (Schedule) - Schedule compaction at regular intervals.

  3 (Disable) - Disable compaction.

• -interval — Specifies the interval at which the compaction process has to be scheduled. The interval is 'day of week:hour of day' where day of week is any day from monday-sunday and hour of day is any value from 00-23. The default value is ‘sunday:00’.

• - fillfactor — This parameter is to specify the page fill factor. Valid values 1-100. The default value is 80%.

• -help — Displays help for the tool.

Examples:

1. Run Compaction Once

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -run 1
   Please enter RDU username: admin
   Please enter RDU password:
   
   Live DB Compaction is enabled to run once.
   
   

   Note: For status on the DB Compaction, check the history.log present in the $BPR_DATA/rdu/db directory.

2. Schedule compaction

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -run 2
   Please enter RDU username: admin
   Please enter RDU password:
   
   Enter the compaction interval (sunday:0):
   monday:02
   Live DB Compaction is scheduled to run at regular intervals MONDAY at 02 hrs.
   
   

   Note: For status on the DB Compaction, check the history.log present in the $BPR_DATA/rdu/db directory.

3. Change compaction interval

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -interval Tuesday:20
   Please enter RDU username: admin
   Please enter RDU password:
   
   Live Compaction interval set to TUESDAY at 20 hrs.
   
   

4. Disable compaction

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -run 3
   Please enter RDU username: admin
   Please enter RDU password:
   
   Live DB Compaction is disabled.
   
   

5. Set page fill factor

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -fillfactor 70
   Please enter RDU username: admin
   Please enter RDU password:
   
   Fill Factor for Live Compaction set to 70
   
   

6. Using the -help option

   
   
   $BPR_HOME/rdu/bin/configureDbCompaction.sh -help
   This tool can be used to configure the DB Compaction parameters. The command line syntax for this tool is as follows:
   configureDbCompaction.sh [-show] [-run option] [-interval value] [-fillfactor ff]
   -show           Displays the current values of the compaction parameters
   -run            An optional parameter to specify whether the Compaction process is to be run once or scheduled or disabled. Valid values 1,2 and 3.
   1 Once          Enter 1 to trigger compaction once.
   2 Schedule      Enter 2 to schedule compaction at regular intervals.
   3 Disable       Enter 3 to disable compaction.
   -interval       An optional parameter to provide the interval in which the compaction process is to be scheduled.
                   The interval is value is'day of week:hour of day' where day of week is any day from monday-sunday and hour of day is any value from 00-23.
                   For example, to schedule compaction every sunday at 1am, it can be set to 'sunday:01'.
   -fillfactor     An optional parameter to provide the page fill factor. Valid values 1-100.
   
   
   

Syntax Description of Offline Compaction Tool

runCompactDB.sh [-cachesize mb] [-dbdir dir] [-dblogdir dir] [-fillfactor ff] [-reclaimspace]

• -cachesize — An optional parameter that specifies cache size in MB. The default cache size is 10MB.

• -dbdir — An optional parameter with database directory path. RDU database location is used by default.

• -dblogdir — An optional parameter with database directory path. Directory specified with -dbdir option or RDU database location is used by default.

• - fillfactor — An optional parameter to provide the page fill factor.

• -reclaimspace — An optional parameter to enable disk space reclaimation when compaction is run.

Example to Reclaim Disk Space:

$BPR_HOME//runCompactDB.sh -reclaimspace

------------------------------------
Starting DB Compaction
------------------------------------

Reclaim Disk Space option value: true

Running DB Compaction with a fill factor of 100%


Time Taken for DB Compaction: 286584

Running DB Compaction with a fill factor of 90%
Time Taken for DB Compaction: 164891


Disk Space Reclaimed after compaction in bytes: 24576

------------------------------------

Custom DPE Event Implementation

DPE event publisher allows the user to view the events that are being fired in the Prime Cable Provisioning DPE. The publisher framework allows to customize the DPE events publishing as per your requirement. To publish the DPE events, it provides options to plug-in your own producer implementation and, the DPE events can be,

- published to any messaging system based on the producer implementation (By default, the DPE offers Kafka based producer implementation).

- published to any remote server.

- logged in to a file in a required format.

For information on custom producer implementation, see the below Custom DPE Event Implementation section.

The sample implementation file SampleEventPublisherImpl.java is present in $BPR_HOME/dpe/samples/event/ directory.

DPE Event Schema

The publisher sends the events as per the below defined Avro schema:

{
 "namespace": "com.cisco.csrc.dpe.events.specific",
 "type": "record",
 "name": "DpeEvent",
 "fields": [
         {"name": "dpe_event_id", "type": "int"},
         {"name": "event_source", "type": "string"},
         {"name": "host_name", "type": "string"},
         {"name": "received_time", "type": "string"},
         {"name": "display_message_tag", "type": "string"},
         {"name": "display_message", "type": "string"},
         {"name": "event_data", "type": {"type": "map", "values": "string"}}
 ]
}

The dpe_event_schema.avsc schema file is present in the $BPR_HOME/dpe/samples/event/ directory.

For custom DPE event implementation:

1. Write a custom producer event implementation in java to publish event to any custom messaging system by implementing the interface com.cisco.csrc.dpe.events.ProduceEvent.

   // Source code of the interface
   package com.cisco.csrc.dpe.events;
   
   import java.util.concurrent.ArrayBlockingQueue;
   
   import org.apache.commons.io.output.ByteArrayOutputStream;
   
   import com.cisco.csrc.dpe.events.specific.DpeEvent;
   import com.cisco.csrc.logging.LogContext;
   import com.cisco.csrc.logging.LogLevel;
   import com.cisco.csrc.logging.LogManager;
   import com.cisco.csrc.util.PositiveIntegerProperty;
   import com.cisco.provisioning.cpe.internal.constants.DPEKeys;
   import com.cisco.csrc.displaymessage.DisplayMessageTags;
   
   /**
   * The interface to mandate the methods to be implemented by the custom produce event
   * implementations
   * @since 6.1.2
   */
   public interface ProduceEvent extends DpeEventConstants
   {
   	static final LogManager s_log = LogManager.getInstance();
   	static final LogContext s_logContext = LogContext.DPE;
   	public static final PositiveIntegerProperty s_capacityOfQueue =  new PositiveIntegerProperty(DPEKeys.SERVER_DPE_EVENT_QUEUE_SIZE, 1000);
   	ArrayBlockingQueue<DpeEvent> dpeEventQueue = new ArrayBlockingQueue<DpeEvent>(s_capacityOfQueue.intValue());
   	
       /**
       * This method will be invoked if DPE event enable to send event.
       * Handle this method with save and send event with seperate threads.
       * if it blocked DPE will not handle with ease.
       * @param topic event type represents in DpeEventConstants
       * @param event event data represents as avro standard ByteArrayOutputStream
       */
   	@Deprecated
       public void eventPublisher(int topic, ByteArrayOutputStream event);
       
       
       /**
        * This method will be invoked if topics are configured
        * Handle this method with save and send event with seperate threads.
        * if it blocked DPE will not handle with ease.
        * @param dpeEvent event data
        * 
        * @since 6.3
        */
       default void eventPublisher(DpeEvent dpeEvent) {
   
   		try {
   			boolean success = dpeEventQueue.offer(dpeEvent);
   
   			if (!success) {
   				s_log.log(LogLevel.NOTIFICATION, DisplayMessageTags.MESSAGING_ERROR_QUEUE_FULL, "custom-topics", " ",
   						s_logContext);
   			}
   
   		} catch (final IllegalStateException ioe) {
   			s_log.log(LogLevel.ERROR, DisplayMessageTags.MESSAGING_ERROR_NOT_SENT, "DPE Event Messaging system ",
   					ioe.getMessage(), s_logContext);
   		} catch (NullPointerException npe) {
   			s_log.log(LogLevel.ERROR, DisplayMessageTags.MESSAGING_ERROR_NOT_SENT, "DPE Event Messaging system ",
   					npe.getMessage(), s_logContext);
   		}
   
   	
       }
       
       /**
        * This method will be called the tool when DPE shutdown. 
        * This can be used to close any resources used by the custom
        * ProduceEvent implementations
        */
       public void closeConnections();
   }
   

   Note	The deprecated method mentioned in the above example is supported till PCP 6.3.

   public void eventPublisher(int topic, ByteArrayOutputStream event);

   This eventPublisher method exposes the DPE object data in Avro Standard ByteArrayOutputStream for event publishing. This method will be invoked for DPE operations when the topics are not manually configured using dpe kafka commands.

   default void eventPublisher(DpeEvent dpeEvent) {}

   This eventPublisher method exposes the DPE object data for event publishing. This method will be invoked for DPE operations when atleast one topic is manually configured using dpe kafka commands.

   DPE operations are referred to operations like File Operation, Configuration/Cache Operation, Log Operation, TFTP Operation, Device level request Operation, ToD request and SNMP reset Operation.

   Note	For information on CLI command, dpe event kafka, see the Cisco Prime Cable Provisioning 6.3 DPE CLI Reference Guide.

   The keys for accessing the events are available in dpe_event_schema.avsc schema file which is present in the $BPR_HOME/dpe/samples/event/ directory.

   The topic is used to differentiate the event type

       /** DPERequestEvent */
       final public static int DPE_REQUEST_EVENT = 1;
       /** FileEvent */
       final public static int FILE_EVENT = 2;
       /** ConfigurationEvent */
       final public static int CONFIGURATION_EVENT = 3;
       /** TftpEvent */
       final public static int TFTP_EVENT = 4;
       /** LogEvent */
       final public static int LOG_EVENT = 5;
   
   // A sample produce event implementation
   package com.cisco.test.dpeevent;
   
   import org.apache.commons.io.output.ByteArrayOutputStream;
   import com.cisco.csrc.dpe.events.ProduceEvent;
   
   public class MyCustomProducerEventImpl implements ProduceEvent
   {
   
       @Override
       public void eventPublisher(int topic, ByteArrayOutputStream event)
       {
   // process the event data here.
   // Eg Write to console
   //System.out.println(" Event Type “ + topic “ : "+ event);
   // Or Implement your custom code for any messaging system
      }
   
   //overide the default method
       @Override
       public void eventPublisher(DpeEvent dpeEvent)
       {
   // process the event data here.
      }
    }
   

   Note	To compile the custom implementation class, we need to include bpr.jar, bac-common.jar, bacbase.jar and commons-io.jar which are present in the $BPR_HOME/lib/ directory.

2. Compile the MyCustomProducerEventImpl.java and bundle as a jar file (for eg: dpeevent.jar). Add the bundled jar and its dependencies jar (i.e., any messaging system dependency jars) to the publisher`s classpath $BPR_HOME/lib/.

3. The custom event can be configured in $BPR_HOME/dpe/internal/bin/dpeeventmonitor.conf. You can also configure the name of the class file in this file, for example, /dpe/producer/class= com.cisco.test.dpeevent.MyCustomProducerEventImpl.

4. Add the path for custom jar and its dependent jar to BPR_CP variable in $BPR_HOME/bpr_definitions.sh before exporting BPR_CP

   BPR_JAVA=$BPR_HOME/jre/bin/java BPR_CP=$BPR_CP:$BPR_HOME/lib/dpeevent.jar:$BPR_HOME/lib/dependentJar1.jar:$BPR_HOME/lib/dependentJar2.jar:.

5. Restart the DPE.

6. Enable the DPE event monitor using CLI, see, Event System Management Commands chapter of Cisco Prime Cable Provisioning 6.3 DPE CLI Reference Guide.

7. Based on the enabled event types, DPE events are published to custom implementation messaging system.

DPE Event Monitor CLI Commands

Prime Cable Provisioning generates the event messages from DPE server and publishes it using the custom messaging system. The event messages fired by the DPE server are based on the event types that are enabled in the settings. Using the CLI commands, the event monitor and the event type can be enabled/disabled.

Event type and Description

The following table describes the types of events that you can view from the DPE event monitor:

1. Login the Telnet using the credentials.

2. Enable the DPE event monitor using CLI command: dpe event monitor.

3. To enable/disable the different event level, see, Event System Management Commands chapter of Cisco Prime Cable Provisioning 6.3 DPE CLI Reference Guide.

4. To configure the kafka bootstrap server and topics, see, Event System Management Commands chapter of Cisco Prime Cable Provisioning 6.3 DPE CLI Reference Guide.

   Note	For information related to kafka, see the Apache Kafka documentation.

Note	It is not necessary to restart the DPE service after the event enabling/disabling.

Sample DPE Events

To use the sample DPE events (Softwares required are, kafka and scala):

1. Start the kafka and zookeeper servers with default configurations as shown below:

   nohup ./zookeeper-server-start.sh ../config/zookeeper.properties > zoo.out &
   
   nohup ./kafka-server-start.sh ../config/server.properties > kafka.out &
   

2. To verify the status of the servers:

   ps -ef | grep zookeeper
   
   ps -ef | grep kafka
   

3. Enable the DPE event properties (monitor, file, log, config, request, tftp) by using the telnet commands.

4. The sample DPE event will send the events to localhost:2181 port with the topic dpeevent. To consume the published events:

   ./kafka-console-consumer.sh --zookeeper localhost:2181 --topic dpeevent --from-beginning
   

5. If the consumer is in a different server, to consume the published events:

   ./kafka-console-consumer.sh --zookeeper pcp-lnx-xx:2181 --topic dpeevent --from-beginning
   

Sample Output

Once the integration is done. You can view the published event on your custom messaging system.

Example sample output

{
  "dpe_event_id" : 1,
  "event_source" : "DPE_REQUEST_EVENT",
  "host_name" : "pcp-lnx-90",
  "received_time" : "2018-10-15 04:49:55,955 IST",
  "mnemonic_tag" : "0112",
  "display_message" : "Sending configuration for device [1,6,11:00:00:00:00:10] in provisioning group [default] to [10.78.109.52:55946]. Time since request received [2 ms]. Rate [0.017/s over 1 min].",
  "event_data" : {
    "device_id" : "1,6,11:00:00:00:00:10",
    "provisioning_group" : "default",
    "event_message" : "Protocol Version=13, Type=CONFIGURATION_REQUEST, Transaction ID=1533394698, Device ID=1,6,11:00:00:00:00:10, Prov Group=default",
    "inet_address" : "10.78.109.52:55946"
  }
}