BVE API Server Reference

14.1 Overview

The Business Visibility Engine (BVE) in NetVigil handles the distributed architecture transparently and provides a common interface for provisioning, data and report retrieval. Through the BVE, you can access the provisioning database and real-time statistics.

The BVE server is accessed via a text based protocol over a TCP socket. Protocol messages can be sent from programs written in C, Java, Perl or any other language.

An alternative to accessing the BVE Server directly is to use the NetVigil Perl API described in Chapter 17, "NetVigil Perl API".

14.1.1 Connecting to the Server

Communication with the BVE Server consists of two phases - a connection establishment phase and a command-execution phase. The connection establishment phase is where a remote client provides authentication information to the server in the form of a login id that is associated with a Department, and the corresponding password. Once the authentication information has been verified, all subsequent commands sent to the server will be executed with the permissions and privileges of the specified Department. It is possible to change the privilege level at any point in the command-reply phase by entering new authentication information.

Once the connection establishment phase has been completed, the client application may send one command at a time and wait to receive a reply (possibly consisting of multiple lines of output) from the server.

A client application establishes a connection to the BVE Server by opening a TCP/IP socket, using the hostname/ip of the server that is hosting the provisioning database, and a pre-defined port number specified in dge.xml (default port number is 7661). Upon establishment of the TCP session, the server will greet the client with a welcome message following the rules outlined below. The client may optionally send client-side information, e.g. client software version.

14.1.2 Disconnecting from the server

When the client application would like to disconnect from the NetVigil platform, it should issue a disconnect request instead of simply closing the socket connection. This will allow the server to perform proper cleanup before disconnecting the session.

Also if the BVE Server does not receive anything from the client for an extended period, the session will timeout and disconnect the client from the BVE Server. The default timeout is currently 15 minutes.

14.2 Command-reply formatting rules

The commands sent by a client and responses sent back by the server must adhere to the following formatting conventions:

Client Command Format

Each client command is composed of a single line of text terminated by a newline character. A carriage return followed by a newline (\r\n) is considered to be the same as a newline character (\n) alone.
Client commands may or may not require additional parameters. Each parameter consists of the option name and value, separated by equal sign (=) and enclosed in quotes. Multiple parameters should be separated by a comma (,) and space. Example "command1=value1", "command2=value2"... If a parameter supports multiple values, the values should be separated by a comma (,). Example: "command1=value1,value2,...".
No whitespace characters should appear in the argument name. No whitespace should occur between the argument name and the equal (=) delimiter. Whitespace that occurs after the equal (=) is considered to be part of the argument value.
Double-quotes are not permitted as part of the value.
For each client command, the server will respond with a response code indicating success or failure, and optionally some descriptive text indication actions taken.
If a client command produces a reply with more than one line of output, the server will respond with 203 response code (see below). Each set of output will be terminated with a newline (\n) and the end of the array will be indicated with a newline (\n) by itself.
Command and parameter names are NOT case sensitive.
Parameters for any command may appear in any order following the command.
Certain parameters indicate a value of <regexp>, which indicates that the parameter may point to a non-unique value. You can use an asterisk (*) as a wildcard in such case. For example, dev* would match device1 and Device B but not my device. However, *dev* would match all three
Parameters which indicate <value> require a value which is already present in the database, while <new_value> indicates a new value to be inserted into the database.
All date/time should be specified in YYYYMMDDhhmm format and in GMT.
For startTime, a blank value (or zero [0]) indicates 24 hours ago and for endTime, it indicates now.
timezone_value is specified in format listed at http://www.timezoneconverter.com/cgi-bin/zonehelp.tzc?cc=US
For Device, Test, and Container specific commands, a special parameter "userName=<value>" is available to admin users. When used, the object would be created/deleted/etc. as the specified user.

Server Response Format

The server will always respond (to client initiated commands/requests) with text of the following format:

<status code> <response code> [optional informative text]  

where status code is one of:

OK

which indicates the command/request was successful

ERR

which is indicative of failure to execute the request

and response code is a three digit numeric code which provides additional details about the status code.

Server response codes and their meanings

Response code	Meaning
200 level - informative messages
200	Server ready for initial handshake
201	Request accepted and processed, ready for next request
203	Request accepted, multi line response follows
298	Request accepted, server will halt
299	Session ended, server will close socket connection
300 level - debugging information (ignore)
301 - 399	Debug message. These messages will be printed before a 200, 400 or 500 level message
400 level - client side error (try again)
401	Authentication failure
402	Logged in user does not have permission to perform requested task
410	Unknown command - use 'help' for list of commands
411	Feature has not been implemented yet
412	Not enough parameters specified - use 'help command.name'
413	Invalid Parameter parameter specified - use 'help command.name'
420	One or more objects already exist
421	One or more of the objects requested does not exist
500 level - server side error
595	Communication failure with remote database, please try again later
596	Maintenance in progress, please try again later
597	Server too busy, please try again later
598	Backend failure, server will close socket connection
599	Server unavailable, server will close socket connection

14.2.1 Client Commands

Login

Provide authentication information to the server.

LOGIN <login_id>/<password>  

Logout | Quit

End a login session.

LOGOUT  

Department.create

Create new Department information. A user login of the same name as the newly created Department will also be created with the specified password.

Department.create "departmentName=<new_value>",
"groupName=<new_value>",
"password=<new_value>",
"passwordVerify=<new_value>",
"contactEmail=<new_value>",
"contactPhone=<new_value>"
[,"company=<new_value>"]
[,"address1=<new_value>"]
[,"address2=<new_value>"]
[,"city=<new_value>"]
[,"state=<new_value>"]
[,"zip=<new_value>"]
[,"country=<new_value>"]  

Department.update

Update information for an existing Department.

Department.update <"departmentName=<regexp>" | 
"departmentSerial=<value>">
[,"groupName=<new_value>"]
["company=<new_value>"]
[,"contactEmail=<new_value>"]
[,"contactPhone=<new_value>"]
[,"address1=<new_value>"]
[,"address2=<new_value>"]
[,"city=<new_value>"]
[,"state=<new_value>"]
[,"zip=<new_value>"]
[,"country=<new_value>"] 

Department.delete

Delete an existing Department. Any login IDs, devices and tests associated with this Department would automatically get deleted as well.

Department.delete <"departmentName=<regexp>" | 
"departmentSerial=<value>">  

Department.suspend

Suspend an existing Department. All login IDs associated with this Department would be locked out of the system and all devices/tests for the corresponding login IDs would also be suspended.

Department.suspend <"departmentName=<regexp>" | 
"departmentSerial=<value>"> ,"reason=<new_value>"  

Department.resume

Unsuspend a previously suspended Department. All login IDs associated with this Department would be able to log into the system once again and all devices/tests for the corresponding login IDs would start to be monitored again.

Department.resume <"departmentName=<regexp>" | 
"departmentSerial=<value>">  

Department.list

List Department information based on the search criteria.

Department.list <"departmentName=<regexp>" | 
"departmentSerial=<value>">
[,"groupName=<regexp>"]
[,"company=<regexp>"]
[,"contactEmail=<regexp>"]
[,"contactPhone=<regexp>"]
[,"address1=<regexp>"]
[,"address2=<regexp>"]
[,"city=<regexp>"]
[,"state=<regexp>"]
[,"zip=<regexp>"]
[,"country=<regexp>"] 

Action.create

Create a new action. Using '0' for n_tests on notifyAfter or repeat parameters will send an immediate notification and will not repeat the notification respectively. It is possible to get notifications on multiple states by specifying different state names separated by '|' symbol for notifyOn parameter. Assigning a method of 'none' will delete that action item. Up to five methods (method1 through method5) can be defined for a single action.

Action.create "actionName=<new_value>"
[,"method<1..5>=<none|email>"]
[,"notifyOn<1..5>=<ok|warning|critical|unknown>"]
[,"recipient<1..5>=<new_value>"]
[,"notifyAfter<1..5>=<n_tests>"]
[,"repeat<1..5>=<n_tests>"]
[,"description=<new_value>"]  

Action.update

Update configuration information of one of more existing actions. If actionSerial and actionName are both given, then the action matching the serial number given by actionSerial will be updated with the name given by actionName.

Action.update <"actionName=<regexp>" | "actionSerial=<value>">
[,"method<1..5>=<none|email>"]
[,"recipient<1..5>=<new_value>"] 
[,"notifyAfter<1..5>=<n_tests>"]
[,"repeat<1..5>=<n_tests>"
[,"description=<new_value>"]
[,"notifyOn<1..5>=<ok|warning|critical|unknown>"]  

Action.delete

Delete one or more existing actions.

Action.delete <"actionName=<regexp>", | "actionSerial=<value>">
[,"method=<regexp>"]
[,"recipient=<regexp>"]
[,"description=<regexp>"]  

Action.list

List actions based on search criteria.

Action.list <"actionName=<regexp>" | "actionSerial=<value>"> 

AdminClass.create

Create an administrative group. Administrative groups are assigned User Groups, and members of admin groups can access information on any device, that is part of a Department under a user group assigned to that particular admin group.

AdminClass.create "groupName=<new_value>" 
[,"comment=<new_value>"]
[,"userClasses=<new_value,...>"]  

AdminClass.update

Update user group assignments or name of an existing admin group. If AdminClassSerial and groupName are both given, then the admin group name will be updated.

AdminClass.update <"groupName=<regexp>" | 
"adminClassSerial=<value>">
[,"comment=<new_value>"]
[,"userClasses=<new_value,...>"]  

AdminClass.delete

Delete an existing admin group.

AdminClass.delete "groupName=<regexp>" | 
"adminClassSerial=<value>">  

AdminClass.list

List admin group information based on search criteria.

AdminClass.list "groupName=<regexp>" | 
"adminClassSerial=<value>">  

Device.create

Create a new device configuration in the database.

Device.create "deviceName=<new_value>",
"address=<new_value>",
"locationName=<new_value>",
"deviceType=<nt|unix|router|switch|firewall|slb|proxy|vpnc|prin
ter|wireless|other>"
[,"snmpCid=<new_value>"]
[,"comment=<new_value>"]
[,"parentNames=<new_value,...>"]
[,"clearOnOk=<true|false>"]
[,"smartNotify=<true|false>"]
[,"showOnSummary=<true|false>"]  

For example:

Device.create "deviceName=Cisco Router 01",
"address=206.33.183.211",
"locationName=Princeton Dev Lab",
"deviceType=router",
"snmpCid=public",
"clearOnOk=true",
"smartNotify=true",
"showOnSummary=true" 

Device.update

Update configuration information for one or more existing device(s). If deviceSerial and deviceName are both given, then the device name will be updated.

Device.update <"deviceName=<regexp>" | "deviceSerial=<value>">
[,"address=<regexp>"]
[,"snmpCid=<new_value>"]
[,"comment=<new_value>"]
[,"deviceType=<nt|unix|router|switch|firewall|slb|proxy|vpnc|pr
inter|wireless|other>"]
[,"parentNames=<new_value,new_value,..>"]
[,"clearOnOk=<true|false>"]
[,"smartNotify=<true|false>"]
[,"showOnSummary=<true|false>"]  

Device.delete

Delete configuration information for one or more device(s). All associated tests for the device(s) are automatically deleted as well.

Device.delete<"deviceName=<regexp>" | "deviceSerial=<value>">
[,"address=<regexp>"]
[,"locationName=<regexp>"]
[,"snmpCid=<regexp>"]
[,"deviceType=<regexp>"]  

Device.suspend

Suspend one or more existing devices and all corresponding tests.

Device.suspend <"deviceName=<regexp>" | "deviceSerial=<value>"> 

Device.resume

Resume one or more previously suspended devices and all corresponding tests.

Device.resume <"deviceName=<regexp>" | "deviceSerial=<value>"> 

Device.list

List device information based on the search criteria.

Device.list <"deviceName=<regexp>" | "deviceSerial=<value>"> 

Device.status

Displays summary of devices being monitored. Tests for each device are displayed in same three-column manner as the web application.

Device.status ["deviceName=<regexp>" | "deviceSerial=<value>"]  

DeviceDependency.create

Assign one or more existing device as the parent device for an existing device.

DeviceDependency.create <"deviceName=<value>",
"parentNames=<value,value,...>"  

DeviceDependency.delete

Delete a previously created device dependency for one or more existing devices.

DeviceDependency.delete <"deviceName=<value>", 
"parentNames=<value,value,...>"  

DeviceDependency.list

List device dependency for information based on search criteria.

DeviceDependency.list [ <"deviceName=<regexp>" | 
"deviceSerial=<value>"> ]  

DGE.create

Create a new Data Gathering Element (DGE) instance.

DGE.create "dgeName=<new_value>",
"host=<new_value>",
"locationName=<new_value>",
"softLimit=<new_value>",
"hardLimit=<new_value>"  

DGE.update

Update information for an existing DGE. If dgeSerial and dgeName are both given, the DGE name is updated.

DGE.update <"dgeName=<regexp>" | "dgeSerial=<value>">
[,"host=<new_value>"]
[,"locationName=<new_value>"]
[,"softLimit=<new_value>"]
[,"hardLimit=<new_value>"]  

DGE.delete

Delete configuration information for one or more existing DGE instance(s).

DGE.delete<"dgeName=<regexp>" | "dgeSerial=<value>">  

DGE.list

List DGE information based on the search criteria.

DGE.list <"dgeName=<regexp>" | "dgeSerial=<value>"> 

Event.list

List events for one or more devices and one or more tests configured on those devices for a certain time-frame. By specifying a certain type of event in eventType parameter, it is possible to display only events where the previous or current state was of that type. Output will be in the format:

device_name | device_serial_number | test_name | 
test_serial_number | test_type | test_sub_type | time_stamp | 
event_duration | previous_state | new_state  
Event.list "deviceName=<regexp>",
["testName=<regexp>" | "testSerial=<value>"]
[,"startTime=<YYYYMMDDhhmm>"]
[,"endTime=<YYYYMMDDhhmm>"]
[,"eventType=<ok|warning|critical|unreachable|unknown>"]
[,"testType=<regexp>"]
[,"subType=<regexp>"]  

Location.create

Create a new location where one or more DGEs will be operating.

Location.create "locationName=<new_value>",
"streetAddress=<new_value>",
"city=<new_value>",
"state=<new_value>",
"comments=<new_value>"  

Location.update

Update information on an existing location. If both locationName and locationSerial are given, the location name is updated.

Location.update <"locationName=<regexp>" | 
"locationSerial=<value>">
[,"streetAddress=<new_value>"]
[,"city=<new_value>"]
[,"state=<new_value>"]
[,"comments=<new_value>"]  

Location.delete

Delete an existing location. All DGEs at that location and all associated devices/tests on those DGEs are deleted automatically.

Location.delete <"locationName=<value>" | 
"locationSerial=<value>">  

Location.list

List location information based on the search criteria.

Location.list <"locationName=<regexp>" | 
"locationSerial=<value>"> 

Message.list

List messages for a specific device for a certain time-frame. By specifying a certain type of message in severity parameter, it is possible to display only messages of that severity. Output will be in the format:

device_name | device_addr | test_name | test_serial | date_time 
| severity | message  
Message.list "deviceName=<value>",
["testName=<regexp>" | "testSerial=<value>"]
[,"startTime=<YYYYMMDDhhmm>"]
[,"endTime=<YYYYMMDDhhmm>"]
[,"severity=<info|warning|error|critical>"]  

Result.list

List test results for one or more devices and one or more tests configured for those devices for a certain time-frame. Output is in the format:

device_name | device_serial_number | test_name | 
test_serial_number | test_type | test_sub_type | time_stamp | 
num_samples | avg_value | min_value | max_value | current_state 
| warning_threshold | critial_threshold  
Result.list <"deviceName=<regexp>" | "deviceSerial=<value>">,
["testName=<regexp>" | "testSerial=<value>"]
[,"startTime=<YYYYMMDDhhmm>"]
[,"endTime=<YYYYMMDDhhmm>"]
[,"testType=<regexp>"]
[,"subType=<regexp>"]  

Report.create

This command is similar to Result.list, but the output is pre-processed based on the type of report requested.

Report.create "deviceName=<value>",
"testName=<new_value>"
[,"testSerial=<value>"]
[,"startTime=<YYYYMMDDhhmm>"]
[,"endTime=<YYYYMMDDhhmm>"]
"reportType=<stats|summary|billing>" 

Container.status

Displays summary of Containers that have been created. The aggregate severity of each Container is provided.

Container.status ["containerSerial=<value>" | 
"containerName=<regexp>"]  

Test.create

Create new tests for an existing device.

To create a ping test:

Test.create "deviceName=<new_value>",
"testType=ping",
"subType=<pl|rtt>",
"testName=<new_value>"
[,"interval=<new_value>"]
[,"warningThreshold=<new_value>"]
[,"criticalThreshold=<new_value>"]
[,"actionName=<new_value>"]  

For example:

Test.create "deviceName=Cisco Router 01",
"testType=ping",
"subType=rtt",
"testName=Cisco-Router-01-ping-rtt",
"warningThreshold=250",
"criticalThreshold=1500",
"actionName=email-NOC" 

To create an SNMP test:

Test.create "deviceName=<new_value>",
"testType=snmp",
"subType=<new_value>",
"testName=<new_value>"
[,"interval=<new_value>"]
[,"warningThreshold=<new_value>"]
[,"criticalThreshold=<new_value>"]
"snmpOId=<new_value>",
"resultMultiplier=<new_value>",
"resultProcessDirective=<new_value>",
"maxValue=<new_value>",
[,"actionName=<new_value>"]  

To create a port test:

Test.create "deviceName=<new_value>",
"testType=port",
"subType=<http|https|smtp|pop3|pop3s|imap|imaps|nntp|ftp>", 
"testName=<new_value>"
[,"interval=<new_value>"]
[,"warningThreshold=<new_value>"]
[,"criticalThreshold=<new_value>"]
[,"port=<new_value>"]
[,"url=<new_value>"]
[,"loginName=<new_value>"]
[,"password=<new_value>"]
[,"actionName=<new_value>"]
[,"sendString=<new_value>"]
[,"expectString=<new_value>"]  

To create an external test:

Test.create "deviceName=<new_value>",
"testType=external",
"testName=<new_value>",
"interval=<new_value>",
"warningThreshold=<new_value>",
"criticalThreshold=<new_value>"
[,"actionName=<new_value>"]  

Test.update

Update configuration information for one or more existing test(s).

Test.update <"testName=<regexp>",
"deviceName=<regexp>",
"testType=<value>" 
[,"subType=<regexp>"]
[,"interval=<new_value>"] 
[,"warningThreshold=<new_value>"]
[,"criticalThreshold=<new_value>"]
[,"actionName=<new_value>"]
[,"maxValue=<new_value>"]
[,"units=<new_value>"] 

Test.delete

Delete configuration information for one or more existing test(s). If a test name is given, then a device name is required.

Test.delete "deviceName=<regexp>",
<"testName=<regexp>" | "testSerial=<value>">
[,"testType=<regexp>"]
[,"subType=<regexp>"] 

Test.suspend

Suspend testing of one or more existing tests.

Test.suspend
<"deviceName=<regexp>",
<"testName=<regexp>" | "testSerial=<value>">
[,"testType=<regexp>"]
[,"subType=<regexp>"]  

Test.resume

Resume regular testing for previously suspended test(s)

Test.resume
<"deviceName=<regexp>" | "deviceSerial=<value>">,
<"testName=<regexp>" | "testSerial=<value>">
[,"testType=<regexp>"]
[,"subType=<regexp>"]  

Test.suppress

Suppress the test result of one or more tests. When suppressed, the severity/state of the test will not affect the status displayed for the device/Department. When test severity changes (e.g. from Warning to Critical or from Unknown to Unreachable), the suppression is reset automatically.

Test.suppress
<"deviceName=<regexp>",
<"testName=<regexp>" | "testSerial=<value>">
[,"testType=<regexp>"]
[,"subType=<regexp>"]  

Test.list

List test information based on the search criteria.

Test.list "deviceName=<regexp>",
<"testName=<regexp>" | "testSerial=<value>">
[,"testType=<regexp>"]
[,"subType=<regexp>"] 

User.create

Create a new user (login id) in a specific Department.

User.create "role=<read-only | read-write>",
"loginName=<new_value>",
"firstName=<new_value>",
"lastName=<new_value>",
"emailAddress=<new_value>",
"departmentName=<new_value>",
"password=<new_value>",
"passwordVerify=<new_value>"
[,"passwordHint=<new_value>"]
[,"passwordHintAnswer=<new_value>"],
"phoneDay=<new_value>"
[,"phoneEvening=<new_value>"]
[,"phoneMobile=<new_value>"]
[,"pager=<new_value>"]
[,"timeZone=<timezone_value>"] 

For example,

User.create "role=read-only",
"loginName=jsmith",
"firstName=John",
"lastName=Smith",
"emailAddress=jsmith@acme.com",
"departmentName=roUsers",
"password=h4ckth1s!",
"passwordVerify=h4ckth1s!",
"phoneDay=609-555-1212" 

User.update

Update information for an existing user/login id. User login names cannot be updated, so if both loginSerial and loginName are given, the loginName is ignored.

User.update <"loginName=<regexp>" | "loginSerial=<value>">
[,"role=<read-only | read-write>"]
[,"firstName=<new_value>"]
[,"lastName=<new_value>"]
[,"emailAddress=<new_value>"]
[,"departmentName=<new_value>"]
[,"password=<new_value>"]
[,"passwordVerify=<new_value>"]
[,"passwordHint=<new_value>"]
[,"passwordHintAnswer=<new_value>"]
[,"phoneDay=<new_value>"]
[,"phoneEvening=<new_value>"]
[,"phoneMobile=<new_value>"]
[,"pager=<new_value>"]
[,"timeZone=<new_value>"]  

User.delete

Delete a user/login id from a specific Department.

User.delete <"loginName=<regexp>" | "loginSerial=<value>">  

User.list

List user information based on the search criteria.

User.list <"loginName=<regexp>" | "loginSerial=<value>">
[,"departmentName=<regexp>"]
[,"firstName=<regexp>"]
[,"lastName=<regexp>"] 

User.represent

Masquerade as a specific user (only available to admin users). Once executed, the permissions and privileges of the specified user will be inherited and any new Department, device and tests created will be created on behalf of the said user.

User.represent "loginName=<value>"  

UserClass.create

Create a user group.

UserClass.create "groupName=<new_value>"
[,"comment=<new_value>"]  

UserClass.update

Update user group information. If both groupName and userClassSerial are given, then the user group name will be updated with groupName.

UserClass.update <"groupName=<regexp>" | 
"userClassSerial=<value>">
[,"comment=<new_value>"]  

UserClass.delete

Delete an existing user group.

UserClass.delete "groupName=<regexp>" | 
"userClassSerial=<value>">  

UserClass.list

List user group information based on search criteria.

UserClass.list "groupName=<regexp>" | 
"userClassSerial=<value>">  

14.3 Example

The following is an example of a telnet session where a new device and a test are created by directly connecting to the BVE Server on the TCP port 7661.

% telnet bve_host 7661 
Trying 127.0.0.1... 
Connected to localhost. 
Escape character is '^]'. 
OK 200 NetVigil BVE TCP Server v3.5 ready 
LOGIN localuser/localpassword 
OK 201 request accepted and processed, ready for next request 
DEVICE.CREATE "devicename=my_device", "address=192.168.123.25", 
"devicetype=unix", "snmpcid=public", "comment=my workstation", 
"locationName=Denver Office" 
OK 201 request accepted and processed, ready for next request 
TEST.CREATE "devicename=my_device", "testname=my_test", 
"testtype=external", "subtype=external", "interval=15m", 
"units=xyz", "warningThreshold=55", "criticalThreshold=85", 
"maxvalue=100", "resultProcessDirective=0", 
"resultMultiplier=1" 
OK 201 request accepted and processed, ready for next request 

[[ if you wanted to check the newly created test ]]

TEST.LIST "testname=my_test", "devicename=my_device" 
OK 203 request accepted, records returned: 1 
"serialNumber=470003", "deviceName=my_device", 
"testName=my_test", "testType=external", "subType=external", 
"interval=900", "warningThreshold=55", "criticalThreshold=85", 
"actionName=None", "suppressed=false", "isSuspended=false", 
"resultProcessDirective=0", 
"resultMultiplier=1.0","maxValue=100" 
QUIT 
OK 299 Logging out.