Introduction
The LifeKeeper API for Monitoring can obtain the operational status of LifeKeeper nodes and their protected resources by making status inquiries to the available nodes in the LifeKeeper cluster.
Summary
This document describes the LifeKeeper API for Monitoring (hereinafter referred to as the API) and is targeted for developers who manage the resource protected by LifeKeeper. By using the API, the information supplied by the lcdstatus command is obtained through CGI script and the lighttpd module. By using this API, users can determine the current status of the LifeKeeper nodes and resources without logging-in to LifeKeeper servers. The API can supply the following information.
• LifeKeeper node status is the node alive and processing or down
• Communication path status between nodes in the cluster, are communication path(s) up or down
• Status of protected resources
To get the detailed status of any abnormal condition requires logging-in to LifeKeeper GUI or checking the LifeKeeper log as necessary.
Information to be supplied with this API
The following information is supplied through this API when the user makes an inquiry to an active LifeKeeper node. The information supplied is about the specific LifeKeeper server to which the inquiry was directed even if the cluster consists of multiple servers.
• Status
º Operating status of each server
• Node name
• Operational status (ALIVE/DEAD)
º Operational status of communication path(s)
• Node name
• Operational status (ALIVE/DEAD)
• Address / device name
º Status of protected resources
• Node Name
• Tag
• Status (ISP, OSU, OSF, …)
• Dependency setting
• Mirror information for Data Replication resources (available only if status is ISP)
• Tag
• Mirror status (Sync, Paused, …)
• Replication status (75%, 100%, …)
• Log
º /var/log/lifekeeper.log *Not supported if log file path is changed
• Up to 1000 lines (when data output format is HTML)
▪ All (when data output format is plain text)
º /var/log/lifekeeper.err *Not supported if log file path is changed
▪ Up to 1000 lines (when data output format is HTML)
▪ All (when data output format is plain text)
Communication Format
The API uses HTTP to obtain the requested information. To obtain information, the user sends a HTTP GET request to the CGI scripts via lighttpd on the specific server.
Data Format
The following 3 data formats are available.
▪ JSON
º To be used by an external tool to analyze the status information returned
º Status checking is possible
º Log output is not available
▪ HTML
º To be used to visually check via a browser
º Status checking is possible
º Log information is available up to 1000 lines
▪ plain text
º Used for regular log checking
º For logging purpose only and not for checking the status
º All contents of /var/log/lifekeeper.log and /var/log/lifekeeper.err are available
Available JSON format and HTML format from the status in the following figure.
Figure 2. Example of active LifeKeeper configuration
{ “resource”: [ { “replication”: {}, “child”: [ { “tag”: “datarep-data” } ], “server”: { “status”: “ISP”, “name”: “lk01” }, “tag”: “/data” }, { “replication”: { “percent”: “100%”, “mirror”: “Fully Operational” }, “child”: [], “server”: { “status”: “ISP”, “name”: “lk01” }, “tag”: “datarep-data” }, { “replication”: {}, “child”: [], “server”: { “status”: “ISP”, “name”: “lk01” }, “tag”: “ip-10.125.139.118” } ], “compath”: [ { “status”: “ALIVE”, “server”: [ { “name”: “lk01”, “term”: “192.168.139.18” }, { “name”: “lk02”, “term”: “192.168.139.19” } ] }, { “status”: “ALIVE”, “server”: [ { “name”: “lk01”, “term”: “172.20.139.18” }, { “name”: “lk02”, “term”: “172.20.139.19” } ] } ], “server”: [ { “status”: “ALIVE”, “name”: “lk01” }, { “status”: “ALIVE”, “name”: “lk02” } ]
}
Figure 3. Status output example using the JSON data format
Figure 4. Status output using the HTML format
How to use
Activate the API
The API is disabled by default. To activate, requires modification of /etc/default/LifeKeeper set the LKAPI_MONITORING configuration parameter to true. Setting of the configuration parameter only activates the API on that node and therefore must be set on each node on which the API will be used. Setting of this configuration parameter does not require a restart of LifeKeeper..
LKAPI_MONITORING=true
Port number
The API uses port 779 by default. To change the port number, the user needs to set the following in /etc/default/LifeKeeper.
LKAPI_WEB_PORT=<port number>
Usage examples
To obtain information a request is made to a server with an active LifeKeeper API configuration. Basic example using curl.
curl http://<IPADDR>:779/Monitoring.cgi
If no arguments are given, the current status is obtained using the JSON data format.
Request for log information using HTML data format.
curl http://<IPADDR>:779/Monitoring.cgi?format=html&show=log
The list of available arguments can be found in the table below.
List 1. Arguments
Security
All the users requesting information via the API must be authorized to get LifeKeeper status information.
For this reason, user security settings can limit the users who can get the status by, configuring SSL, and encrypting the information.
Basic Authentication
To obtain the information via the API, Basic Authentication is required. To setup the authentication requires modification to the lighttpd configuration file (modify the part in red) plus a restart of the lighttpd module.
After modification execute the command ”/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd” and reboot lighttpd to restart lighttpd using the new configuration.
server.modules = (
...
"mod_auth", # uncommenting
/opt/LifeKeeper/lib64/steeleye-lighttpd/include_server_bind.pl
print qq/\$SERVER["socket"] == "$addr:$port" {\n/;
print qq/ server.document-root = "\/opt\/LifeKeeper\/api"\n/;
print qq/ auth.backend = "htpasswd"\n/;
print qq/ auth.backend.htpasswd.userfile = "\/opt\/LifeKeeper\/etc\/lighttpd\/lighttpd.user.htpasswd"\n/;
print qq/ auth.require = ( "\/" =>\n/;
print qq/ (\n/;
print qq/ "method" => "basic",\n/;
print qq/ "realm" => "LifeKeeperAPI",\n/;
print qq/ "require" => "valid-user"\n/;
print qq/ )\n/;
print qq/ )\n/;
print qq/ }\n/;
To create htpasswd file:
htpasswd -c /opt/LifeKeeper/etc/lighttpd/lighttpd.user.htpasswd <USERNAME>
SSL/TLS set up
SSL/TLS is available for the communication via this API. The lighttpd modifications for SSL/TLS is shown in the example below. After modification execute the command ”/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd” and reboot lighttpd to restart lighttpd with the new configuration.
In addition, if it is no longer necessary to set the default port used by this API due to this support, disable it by referring to the following “Disable port 779”.
/opt/LifeKeeper/etc/lighttpd/include_ssl_port.pl
configAPI("0.0.0.0", 443);
if(socket($sock, AF_INET6, SOCK_STREAM, 0)) {
configAPI("[::]", 443);
}
sub configAPI {
my $addr = shift;
my $port = shift;
print qq/\$SERVER["socket"] == "$addr:$port" {\n/;
print qq/ server.document-root = "\/opt\/LifeKeeper\/api"\n/;
print qq/ ssl.engine = "enable"\n/;
print qq/ ssl.pemfile = "\/opt\/LifeKeeper\/etc\/certs\/LK4LinuxValidNode.pem"\n/;
print qq/ }\n/;
}Modification to support SSL/TLS + Basic authentication
Using SSL/TLS, modification example to set up Basic authentication is below. After modification, execute the command “/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd“ and restart lighttpd to reflect the modified set up.
/opt/LifeKeeper/lib64/steeleye-lighttpd/include_server_bind.pl
#lkapi_config("0.0.0.0", $lkapi_port);
#if(socket($sock, AF_INET6, SOCK_STREAM, 0)) {
# lkapi_config("[::]", $lkapi_port);
#}
IP address access limitation
The lightppd configuration can also be setup to limit IP addresses that can be used to access data via the API. The lighttpd configuration to limit access is shown in Figure 9. The example will reject the connections from IP address other than 192.168.10.1. After modification execute the command ”/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd” to restart lighttpd with the new configuration.
/opt/LifeKeeper/etc/lighttpd/conf.d/lkapi_user.conf
$HTTP["remoteip"] != "192.168.10.1" {
url.access-deny = ( "" )
}
Error
Errors can occur during the usage of this API when enabled. Should this occur, the summary of the error is output. Error example when JSON format is shown below.
HTTP status code returned by lighttpd is not described here.
{
"error" : {
id : -1,
message : "Failed to get LCD status"
}
}
Similar message is output in the case the output format is HTML.
Post your comment on this topic.