SVIP - The Simple Vital Information Protocol (version 1.0)

Author: Johannes Findeisen - 2005-05-25
Author: Thilo Bangert - 2005-06-12
Last modified: Johannes Findeisen - 2006-05-11

This document describes the idea of a network protocol designed to get vital information from hosts while leaving the smallest possible memory and cpu footprint on the monitored machine.

1. Introduction

Purpose

SVIP is a network protocol designed for getting vital information from hosts. It aims to be a simple replacement for SNMP and it is implemented as lightweight and secure as possible. You could write a server monitoring solution to visualize the health status of your hosts with help of the SVIP protocol.

What is vital information?

I define vital information as follows. Your heartbeat is a vital function and it has a frequency. This frequency is vital information. So what is vital information on a host? This is easy: The process count, the system load, available space of memory and so on. All this is vital information and you could define other vital information by yourself depending on your needs. So if you want to know how much mail is in the current mail spool because your system will run unstable if there is a huge amount of mail in it (this should never happen though), the current mail count is a vital information!

Why i have choosen to implement a new protocol since ksysguardd from the kde-base package is exactly providing the same?

I had to read the sourcecode of ksysguardd to get information about the protocol. There is no place in the web where this protocol is defined. Then after reading the sourcode i was impressed. ksysguardd is providing a lot of features which i also are planning to implement but i do not like the concept behind the protocol.

From the Porting-HOWTO delivered with ksysguardd:

ksysguard sends commands and ksysguardd answers to them. Each answer ends with the string "\nksysguardd> ". Error messages are enclosed in ESC '\033' characters. Therefor regular messages may never contain ESC. The set of commands that each ksysguardd implementation supports can be very different. There are only a very few mandatory command and a few recommended commands.

I think this is a very ugly implementation of a protocol. First of all: Why is there a damn ksysguard> at the end of each answer? Why not implement are much more generic protocol? Another thing are the error messages. Why are error messages send in a different format then vital information data. The data produced by ksysguardd is not parseable with genric parsers and this should be much more easy!

I think there are more flexible ways how things could be implemented!

How should your admin write a plugin for this system guard daemon without the knowledge of C++? And what about compilation? ksysguardd is available as standalone package for some distributions but you have to compile kde-base to get a new or maybe patched version of ksysguardd. Okay there is a way around this but, hello??? Thats too much work!

This implementation provides a serverside interface for plugins as described below. These plugins could be written in nearly every programming language or scripting language. This makes it easy for nearly everybody with some Unix expierience to write some plugins and makes the software a lot more flexible then ksysguardd.

Anyway, thanks to the developers of ksysguard for providing this piece of software. Maybe we could define a common protocol at some time...?

Requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."

2. Connect

The connection is done by a TCP/IP connection to port 1100 of the monitored machine. After a succesfull connection the server MUST response with an error code and a welcome message following with the supported SVIP version added to the end.

Example:

[hanez@phantom svipd]\$ ./svipc 192.168.0.10 -p svip
Connecting to svip://192.168.0.10:svip.
200 SVIP/1.0

The first part of the connect response MUST be the status code. After a whitespace the protocol name and version MUST follow in the following format: SVIP/1.0.

SVIP MUST support persistent connections and requests MUST be pipelined like described in the HTTP RFC.

3. Request

The definition:

GET PLUGIN

Where PLUGIN is build of "/class/datataype_id-script_name"

Where "class" is a class of all vital information such as hardiscs. Memory information is another class. Process information is another class and so on. The class is optional e.g: PLUGIN = datataype_id-script_name and it can contain subclasses e.g: PLUGIN = /class/subclass/datataype_id-script_name.

Where "datatype_id" is one of:

The datatype_id is not optional because it identifies the requested datatype and handling is much more easy.

The "script_name" is the real name of the script residing in the plugins directory with the "datatype_id" as prefix like shown above.

THIS SHOULD BE DEFINED WITH THE BACKUS-NAUR FORM! (See the weblinks at the bottom of the site!)

Note: dots (.) are not allowed in PLUGIN.

Example:

GET mail/num-queuecount

Session disconnect is done by:

QUIT

4. Response

The response body is build similiar to a HTTP response. All response codes are nearly the same as in HTTP but with modified name and little bit different signification.

Example:

GET plugin
200 OK
DATA

DATA MUST be encapsulated in a netstring, since netstrings defined by Dan Bernstein seems to be a good way for transporting data over a network.

Example

GET hdd/tab-df
200 OK - Data following...
252:Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/sda2             19840924   6165240  12651544  33% /
/dev/shm                257788         0    257788   0% /dev/shm
/dev/sda5             56765020   8447608  45433748  16% /home
,

From Dan Bernstein's site about netstrings:

Any string of 8-bit bytes may be encoded as [len]":"[string]",". Here [string] is the string and [len] is a nonempty sequence of ASCII digits giving the length of [string] in decimal.

5. Status codes

The status codes are the same then defined in the HTTP protocol. Since the SVIP protocol has not the same features then HTTP servers, it does not need all status codes but some of them. They all have the same code number in SVIP for a similiar status in HTTP.

2XX Family

200 SVIP/0.1 - If everything is okay.

201 Created - If a request was successfull and data is following.

204 No Content - If a plugin does not return data.

4XX Family

400 Bad Request - If the request was not accepted.

403 Permission Denied - If access to plugin is not allowed.

404 Resource Not Found - For non existing plugins.

405 Method Not Allowed - For non supported request methods.

408 Request Timeout - If a plugin reaches its maximum execution time.

5XX Family

500 Internal Server Error - If the server has an internal error.

503 Service Unavailable - If the server is not able to answer requests.

505 Server Error - If an internal server occurs.

510 Too Many Illegal Commands - If an internal server occurs.

6. Security

ksysguardd allows the kill of applications and that is not very secure! If some evil person could get access to the server daemon, the person could kill arbitrary processes.

In the implentation described in this document there will not be features for killing server side processes. The SVIP protocol is only for getting information and not for execution of serverside commands. If someone wants to use this protocol for such things, do it, but beware of the risk! It will be very easy to write plugins to restart or stop daemons running on the watched machines but with the same risk as in ksysguardd! I will not do that in my envoirenments. I know how to use ssh and this is enough for remote adminstration!

SVIP should generally fully support SSL/TLS!

7. Familiar protocols

A very familiar protocol - and maybe the one and only - is the "Simple Network Management Protocol" (SNMP). SNMP is "far from simple."! The SVIP protocol is designed to be as simple and lightweight as possible. The SNMP protocol is implemented with features to manage your remote hosts and do administration tasks. This is insecure and will overload the software to a state where it maybe will make more problems then the production software running on these hosts. This is not acceptable!

There are existing some commercial tools for providing vital information from host to host but there is no generic protocol public available which nearly makes it impossible to design own "visualisation clients" and these tools are very expensive.

  1. The SNMP protocol
  2. The Simple Mail Transfer Protocol (SMTP)
  3. Netstrings
  4. The Backus-Naur form
  5. The HTTP protocol
  6. HTTP/1.1 Status Code Definitions
  7. Networking Protocols

Copyright (C) 2005, 2006, 2007, 2008 - Thilo Bangert and Johannes Findeisen. All Rights Reserved.

Comments

Please enter your comment here:




Security check, please solve:

BSH         L        
  J    T    T S   58I
  N   T2T   NH9      
  O    W      4   6UP
  T           P

$Date: 2008-02-29 18:55:35 +0100 (Fri, 29 Feb 2008) $