The sysinfo protocol is a private protocol implemented for use in a class exercise. Be carful when browsing, since there may be other protocols with similar names or functions.
The sysinfo protocol is a simple client-server protocol build atop TCP. A client connects and issues queries (or commands) to the server, then disconnects. A connection may include any number of queries and responses. Queries request certain information about the system, and commands request the server to perform certain action; presently, there is only one command defined.
All messages are single lines terminated by carriage return/newline (byte value 13 followed by 10). Each message begins with a one-character indicator giving the type of message. The indicator characters are:
|+||A non-error status message sent from server to the client|
|-||An error message sent from the server to the client indicating that some operation failed.|
|?||An information query sent from the client to the server|
|@||A (successful) response to a query message, it is sent by the server to the client|
|!||A command sent from the client to the server|
Each indicator is followed immediately (on that same line not separated by spaces) by the contents of the message. For the + and - indicators, the content is simply a string of printable ASCII characters suitable for human consumption. For the ?, it is the name of some status value the server will report. Likewise, for ! it is the name of a command the server understands. For @, it the name of the status value requested, a space, then the value itself. Presently, no values contain blanks, but later versions of this protocol are not required to maintain this restriction.
The following status values are defined. Later versions of the protocol may define additional ones.
|ncpu||Number of CPUs,||Integer|
|nuser||Number of shell users logged in.||Integer|
|nproc||Number of processes and threads. (Technically, “kernel scheduling entities”)||Integer|
|utime||Unix time (seconds since 1970). This is the server computer's system clock value.||Integer|
|up||How long the system has been up, in seconds.||Floating point|
|idle||The amount of that time during which the sytem was idle. This is actually an average of the idle times of each CPU.||Floating point|
|qsize||The 10-minute average run queue size. Generally, the CPUs are considered fully utilized when this equals the number of them.||Floating Point|
|mem||Total memory (kb).||Integer|
|free||Free memory (kb).||Integer|
|avail||Available memory (kb). This is the kernel's estimate of how much memory is being used as cache, and could be repurposed cheaply.||Integer|
There is presently one one command defined, bye, which asks the server to close the connection.
A session is initiated by the client connecting to server port 45490. After the server accepts the connetion, it will send a + greeting message. If the server is unable or unwilling to process requests, it will send a - message instead, then close the connection.
Once the client has received the initial + message, it may repeatedly send a line of text to the server and read the response, then terminate the session either by closing the connection, or sending a bye command asking the server to close it, then reading the response. The server will send a single one-line response to each line sent by the client. To a query, the server will respond either with a single @ message giving the value requested, or a - line indicating that some error occurred when fetching the needed information. For each command (all one of them) the server will respond with + if the command was successful, or - if not. For any line which the server cannot identify or parse, it will send a - message. After completing the interaction, the client should close the connection.
When the server receives a message it does not understand, it responds with a -. If the client receives a message it does not understand, there is no provision to notify the server, and the client must discard the unidentified line. Further action is up to the implementer, but disconnecting (and perhaps reconnecting) would seem indicated.
Except for a negative inital message, a negative response does not require either the client or server to close the connection, and the client may try addtional requests, or retry previous ones. However, some types of errors suggest a failing server or server machine, in which case retries are not likely to be successful.
This example shows an interaction with the server. The lines are marked C: and S: for client and server. The session starts by the client connecting to the server, then: