SysInfoTM Service Protocol (SSP)

MagniComp

Introduction

This document describes the SysInfoTM Service Protocol (SSP). SSP is a TCP stream protocol which can be used to retrieve system information, such as OS, hardware, and software information, from a remote host.

The SSP service is provided by the sysinfod server. which provides data in mcsysinforeport(5) format. An operational description of sysinfod is beyond the scope of this document.

Connection Initialization

  1. Connect to TCP port 11967
  2. Server responds
    * OK SSP banner
     where banner is optional information about the server.

Server Commands

Server Command notes:

Command Desciption Example
AUTH PASSWORD user password Send authentication information.

In the AUTH PASSWORD user password authentication scheme, the client sends a username of user and a plain text password of password. The user and password will be checked first against the server's private configuration database. If no matching user entry is found, the server's standard passwd(5) database will be checked. On most systems, this includes lookup in /etc/passwd, NIS, and NIS+ if those services are available.

The client must authenticate with the AUTH command for any of the following reasons:

  • Authentication is required if the Response Code AUTHREQ appears on any line of the initial banner displayed during the first connection. i.e. 
    
    *-OK SSP MagniComp SysInfo Server
    * AUTHREQ You need to authenticate
  • If any command responds with the Response Code AUTHREQ you must authenticate and then re-send the original command. 
AUTH PASSWORD fred fun4all0
* OK Authentication succeeded
BYE Shutdown the connection. 
BYE
* BYE Closing session
CLASSLIST List names of SysInfo classes which are supported.  Values are returned in a comma seperated list. 
CLASSLIST
* OK general,hardware,software,printer
LICENSE Show information about the SysInfo license. 
LICENSE
* START
TBD
* OK
MEMBERS List class member information. The information provided is the class name, member's key name, and description. 
MEMBERS
* START
general|member|kernver|Kernel Version
general|member|boottime|Boot Time
general|member|currenttime|Current Time
network|member|defgwip|Default Gateway IP
network|member|defgwname|Default Gateway Name
* OK
SEND classlist Send SysInfo data for each class in classlist. classlist is a comma seperated list of class names. Use the CLASSLIST command to retrieve a list of valid class names.  The class all specifies all supported classes. The data stream begins with the START response code and ends with OK.

Data is sent in mcsysinforeport(5) format. This format is of the form produced by the CLI: 

	sysinfo --repsep '|' --format report
See mcsysinforeport(5) for the detailed format specification. 
SEND general,device
* START
... raw data ...
* OK
SETOPTION option Set an option where option is one of the following:
  • licports=start-end,start-end,... - Set the range of license ports to scan to be start-end.
  • noserial - Do not check serial numbers for duplicate devices.
  • swfiles - Include information about files when displaying software class information.
 
SETOPTION licports=1000-2000
* OK
TYPES List supported types. The information provided is a type name and it's description. Typically these are used with HARDWARE class data. 
TYPES
* START
type|cpu|CPU
type|diskctlr|disk controller
type|msd|disk controller
type|diskdrive|disk drive
type|disk|disk drive
* OK
NOOP Do nothing but return OK status. This command can be used to verify the server is operational. 
NOOP
* OK
VERSION Server returns version information as follows:
* OK SSP=version SIE=version SERVER=version
where SSP is the protocol version, SIE is the SysInfo Engine, SERVER is the SSP Server, and version is the respective versions of each value.   The order and set of return values is not guarenteed and may be extended with other values in the future. 
VERSION
* OK SSP=1 SERVER=5.0.0-alpha0 SIE=5.0-alpha0

Server Responses

Response Format

Server responses are of the form:
*CRESCODE
where:

Single-Line Responses

When responding to a request, the server's response will start with *<SPACE> (asterick followed by a single space).   This sequence indicates the server's response to the requested command and that the server is ready to accept further commands.  i.e.
* OK You are connected to SSP on sun1.magnicomp.com

Multi-Line Responses

Multiple line responses are allowed with each line beginning with *- (asterick followed by a single dash/minus).  The final response must be *<SPACE> to indicate the last response. i.e.
*-OK You are connected to SSP on sun1.magnicomp.com
*-AUTH=login,ssl
* SSPVERSION=5

Response Codes

Response Code
 Description
OK info
 Indicates success.  info is optional descriptive information about the requested operation.
ERR info
 General error/failure.  info is optional descriptive information about the failure.
AUTHREQ info
 Authentication is required. info is optional descriptive information about the response.
BYE info
 The session is being shutdown.  info is optional descriptive information.
START
 Indicates the server will start sending the requested data on the next line.  The requested data will likely be on multiple lines and will terminate upon success with an OK response code.