SIOS TECHNOLOGY CORP.

LifeKeeper API for Monitoring

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.

{
	"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"
		}
	]
}

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>

Using 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.

Name
Explanation
Value
Comments
show Specify the target information status, log, log-err show=status is the default
format Specify data format json, html, plain format=json is the default. If the format is json an error will be displayed if show=log or show=log-err is set.

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 colored character.) plus a restart of the lighttpd module. See figure 7 for how to configure lightttp.conf.

After modification execute the command ”/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd” and reboot lighttpd to restart lighttpd using the new configuration.

/opt/LifeKeeper/etc/lighttpd/lighttpd.conf

server.modules              = (
	:
	%(color-red)"mod_auth",% # uncommenting

/opt/LifeKeeper/lib64/steeleye-lighttpd/include_server_bind.pl

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/;

Step 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 in the following figure. After modification execute the command ”/opt/LifeKeeper/sbin/sv restart steeleye-lighttpd” and reboot lighttpd to restart lighttpd with the new configuration.

/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/ ssl.use-sslv2 = “disable”\n/; print qq/ ssl.use-sslv3 = “disable”\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/etc/lighttpd/lighttpd.conf


server.modules              = (
	:
	"mod_auth", # uncommenting




/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/    ssl.use-sslv2 = “disable”\n/;
	print qq/    ssl.use-sslv3 = “disable”\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/;

}





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.
            
              
              

      
      

      
              

                      
                                
                    

        

      
              

                      
Feedback

          
                      

              
              
              
              
              
              
              
              
              
              

                

                  
Was this helpful?

                

                

                   Yes
                   No
                

              

              

              	
You indicated this topic was not helpful to you ...

              	
Could you please leave a comment telling us why? Thank you!

              

            

          
          

          

             Thanks for your feedback.          

          
                      

              

                Post your comment on this topic.
              

  
              

                
                
                
                
                
                
                
                
                
                

                  

                    
                    

                      
                    

                  

          
                  

                    
                    

                      
                    

                  

                

                
                

                  
                  

                    
                  

                

    
                                
                Post Comment