VSM Sensor Integration Example - Integrating ICPAM Access Control

[cchoobin]

This example shows ICPAM integration to VSM 7.12

Principal of operation:

1. SENSOR_CONNECTOR will connect to ICPAM & register the callback endpoint. Currently SENSOR_CONNECTOR is registering endpoint for all types of events available in ICPAM.
2. Whenever an event occurs, ICPAM will send event notification to SENSOR_CONNECTOR via registered callback endpoint.
3. Once SENSOR_CONNECTOR receives an event notification from ICPAM, It will propagate same event to VSOM for further processing.

Steps for integration:

In this example, the VSOM server IP address is 192.168.0.60 with hostname vsom4cpam. For ICPAM, the server IP address is 192.168.0.50. Use the hostname and IP address assigned in your deployment.

1. Setup ICPAM to accept connection from VSOM
   1. Get VSOM certificate to store in ICPAM
      This is one method to get the certificate from a PC with Chrome browser
      1. Browse to VSOM in Chrome browser
         
      2. From Details Tab click on Copy to File
         
         

• Certificate Export Wizard – click Next
  

1. Select DER encoded binary X.509 (.CER) – default
   
2. Assign name for certificate, press Next
   
   
3. Click Finish
   
   

1. ICPAM – Add VSOM certificate and VSOM host name as client for web services
   1. SSH into ICPAM server and copy the VSOM certificate on PC to the default destination on ICPAM, /home/cpamadmin
      
   2. Edit /etc/hosts file (on ICPAM) to include VSOM hostname
      

• Execute this command
  <JRE_PATH>/keytool -import -alias <VSOM_IP_HOSTNAME> -keystore /opt/cisco/cpam/keystores/keystore.jks -file <VSOM_CERT_PATH> -storepass changeit
  (replace vsom4cpam and vsom4cpam-certificate.cer with your deployment’s hostname and certificate file name):
  /usr/java/jdk1.6.0_20/jre/bin/keytool -import -alias vsom4cpam -keystore /opt/cisco/cpam/keystores/truststore.jks -file /home/cpamadmin/vsom4cpam-certificate.cer -storepass changeit
  1. Answer yes to Trust this certificate

1. Execute this command (replace vsom4cpam with your deployment’s hostname):
   /usr/java/jdk1.6.0_20/jre/bin/keytool -list -keystore /opt/cisco/cpam/keystores/truststore.jks -alias vsom4cpam -storepass changeit
   
   Screenshot from last command results
   
2. Edit acws.properties in ICPAM and add VSOM hostname to that file, located at:
   /opt/cisco/cpam/properties/acws.properties
   Edit (using vi or other editor) the acws.properties file
   Change from:
   acws.client.hostname=””
   to:
   acws.client.hostname=VSOM_HOSTNAME
   
   Sample screenshot showing hostname of vsom4cpam added to the file:
   
   

2. Configure VSOM Sensor Connector from the CLI
   192. Add ICPAM login properties to the sensor property file.
        SSH into VSOM server and run the following commands
        
        sudo su -
        
        /usr/BWhttpd/vsom_be/sensor/config_sensor_manager.sh –i <icpam ip address> –u <ICPAM login name> –p <ICPAM password> -v <VSOM virtual IP>
        
        Note: <VSOM virtual IP> is optional and only applies if VSOM has HA configuration
        
        Example, for a test ICPAM server (192.168.0.50) and its credentials:
        /usr/BWhttpd/vsom_be/sensor/config_sensor_manager.sh –i 192.168.0.50 –u cpamadmin  –p Cisco123!
        
        Session output from running the sensor manager configuration script
        
        
        Configuration is saved in /usr/BWhttpd/vsom_be/sensor_manager_properties
        
        Screenshot of sensor properties file – Note password is encrypted
        
   193. Enable the Sensor Connect, execute this command:
        /usr/BWhttpd/bin/init_sensor enable
        
        init_sensor command line options: [enable] [disable] [start] [stop] [restart] [status]
        
        Screenshot from session:
        
3. Validate communication between VSOM and ICPAM
   With SSH sessions running in both systems, monitor the following log files:
   
   On ICPAM:
   tail -f /opt/cisco/cpam/logs/webapp.log
   
   On VSOM:

tail -f /usr/BWhttpd/logs/vsom_be/sensor_be.log

Here is a screenshot of VSOM and ICPAM illustrating an incoming ICPAM trigger that was from a GRANT ACCESS command to a door and that door was not opened, resulting in the log code GW.EV_DOOR_NOT_USED. That log code is highlighted on both sides.
 

With communications established, the rest of the configuration is from VSOM.

Identifying ICPAM Sensor ID and Sensor States to use in VSOM

After establishing sensor connectivity between VSOM and ICPAM comes the step to identify sensor types and states that you wish to represent and integrate into VSOM.

Sensor integration in VSOM requires two parameters, a Sensor Unique ID and one or more Sensor States.

In integrating access control sensors into VSOM, like those managed by an application like ICPAM, one useful integration is monitoring a DOOR (Sensor) and tracking door ALARMS (Sensor States), e.g. Door Forced Open, Door Held Open.

Using the ICPAM PC client, in ICPAM REPORTS section, you can export both types of information to use for Sensor Unique ID and Sensor States in VSOM.

For Door’s unique Identifier (UNID) that will be used as the Sensor Unique ID, use the vx_dev report (under More Cisco Templates) under Reports.

Screen shot of VXDEV selection

Run the report which you can export in a variety of formats for reference. Here is a screenshot with the Door UNID (highlighted) that can be used as a Sensor Unique ID in VSOM.

VXDEV report, highlighting the Door1 UNID, “e149D70dSKOePQ+9HaijRg==”

To get a full report of LOG CODES used in ICPAM, use the vx_logcode_cat_member report (under More Cisco Templates)

Screenshot of VXLOGCODE

This will produce a long report (over 1000 lines). Exporting this report out to a CSV format is more useful as a reference. The log codes appear in the column with the heading “elt” in the report. The log codes beginning with GW.EV include the type of codes that ICPAM will report to VSOM as the state change occurs. Other log codes (not beginning with GW.EV) are not reported externally from ICPAM.

Screenshot

Note: Not all event log codes shown in the Report are used or even reported in ICPAM Events! Most, but not all, of GW.EV log codes reported via ICPAM Events will be reported externally, sometimes requiring double-checking on VSOM sensor log files to see what is transmitted as an event. However, to monitor what is actually logged in the Events window in the ICPAM application, you can add a LOG CODES column to the EVENTS windows (under Events & Alarms > Monitoring > Events).

Screenshot of Events with added “Log Code” column

In the screenshot above, log codes such as GW.EV_DOOR_MODE_CHANGED_BY_CMD, GW.EV_DOOR_FORCED_OPEN, and GW.EV_DOOR_FORCED_OPEN_CLEAR, and will be reported outbound from ICPAM for the door action – others will not.

Some useful log codes for DOOR state monitoring from ICPAM include:

Door forced Open: GW.EV_DOOR_FORCED_OPEN

Door Held Open: GW.EV_DOOR_HELD_OPEN

These door states are alarm conditions that would be useful to track in VSOM and to have a camera(s) and recordings associated with the events.

Configuring Sensor information in VSOM – ICPAM example

So far we introduced the baseline preparation for sensor event communication between ICPAM and VSOM and discussed methods for compiling the Sensor Unique ID and the relevant Sensor States from ICPAM to track in VSOM. Now comes the VSOM sensor setup steps.

The sequence of Sensor configuration in VSOM requires three steps:

1. Sensor Types setup: For a particular Sensor Type, define the state identifier/trigger and assign an icon for representation on the map
2.  

The DOOR STATES communicated in ICPAM are identified by LOG CODES. You can see LOG CODES by adding a COLUMN to the EVENTS windows (under Events & Alarms > Monitoring > Events).

Default Events Panel

Adding a column – add a check box to Log Code

Events displaying log codes

In ICPAM access control application, typically the DOOR is the entity that you need to monitor. The door state of interest here would be the Door Forced Open or GW.EV_DOOR_FORCED_OPEN which is the state in VSOM that is going to be tracked. Earlier we had shown how to get the unique door ID.