Version 1.4

Syntax conventions: Boldtype are literal string commands. Italics are strings to be specified by the caller. Commas within specified values must be escaped with a backslash ‘\’. Commands are case insensitive, but specified values are case sensitive. There are no spaces between comma delimited parameters. The [a|b] style syntax is “either a or b” syntax where the underlined value is the default value. The […] style syntax is optional syntax. All commands, as well as responses from the server, are terminated with a CR/LF pair.

The Protocol

A client first connects to the Fairmount SSH Server on a specified port (which defaults to 22 unless configured differently at the server), and then authenticates with either a password or a public key. The specific usernames, passwords, and public keys allowed by the server are beyond the scope of this document. After successfully authenticating with the server, the client is logged in, and a “hello” string is returned in the format:

Where x.x.x is the product version number and 1.3 is the protocol version number. It is assumed that the protocol major version numbers must match between client and server. If the protocol major version numbers do not match, the client should disconnect. If the protocol minor version numbers do not match, the client or server may choose to support a lower minor version number for backward compatibility. Starting with 1.3, clients can issue a query to determine which commands are supported by the server, reducing reliance on this protocol version number.

Commands are initiated at the client, their format is as documented below, and they are always terminated with a CR/LF pair. Commands may be chained together when appropriate in order to avoid making several round-trips to the server.

Replies from the server are also terminated by a CR/LF pair. All replies, as required by the SSH protocol, may be split up into several messages that must be concatenated together back at the client. The client should continue to read for more data until a CR/LF pair is received.

All commands have the general format:

The optional ReqID is an unsigned 32-bit decimal integer that will be returned by the returned data. If the ReqID parameter is omitted, a session-unique number will be generated by the server.

Data returned will follow the general syntax:

Synchronous data replies always will have a request ID returned. Asynchronous data replies only will return a request ID if the reply is associated with an asynchronous request. Errors will be returned as:

The error code is a 32-bit unsigned integer formatted as a hexadecimal string. Synchronous error replies always will have a request ID returned. Asynchronous error replies only will return a request ID if the reply is associated with an asynchronous request. Optionally, all commands immediately return an acknowledgment reply. If the Acks option is turned on, the client receives an immediate reply "@ReqID;OK;" followed by the command that was recognized.

The API Sets

There are four API sets available in the Fairmount SSH Server: the Fairmount Network Data Access (FANDA) APIs, the Design Pad APIs, the Configuration APIs, and the internal use APIs.

Access to API sets may be limited based on authentication credentials. The GetCaps command provides a mechanism to determine the capabilities of the current connection.

The FANDA APIs

GetNDL

This command requests a download of the NDL string. Returns “@ReqID;NDL=xml string” or “@ReqID;Error=code;error message”. The format of xml string is documented elsewhere.

GetMulticastKey

This command requests a download of the multicast encryption key(s). If a particular Multicast ID is not specified, all multicast keys are reported. Returns “@ReqID;MulticastKey=MulticastID,KeyGen,Base64KeyData,Base64NextKeyData” or “@ReqID;Error=code;error message”. If all multicast keys are requested, each key will be reported with a MulticastKey= response. KeyGen specifies the current key generation number in use, Base64KeyData is the current encryption key in use, and Base64NextKeyData is the next encryption key to be used after rekeying. The format of Base64KeyData and Base64NextKeyData is little-endian binary encryption key encoded as a Base64 string. The key cipher and length are described in the NDL.

GetVar

Get the value of the variable VariableName and return it in the format specified by the SetDataFormat option. If VariableName contains embedded whitespace or periods, it must be enclosed in double quotes. At this point, VariableName must be defined in Design Pad as a global variable with network access enabled. The second form of the command may be used for structure type variables. In that case, the requested structure member is returned. If the SetDataFormat option is Base64 (the default) or String, the format of the returned data is:

The format of Base64Value is a little-endian binary value encoded as a Base64 string. The format of StringValue is a human-readable decimal value (i.e. formatted using the C-language sprintf function). If the SetDataFormat option is XML, the format of the returned data is:

where XMLString is an XML representation of the data. See Design Pad Structures for details on the XML format returned for structure data and underlying simple type data.

SetVar

Sets the value of the variable VariableName to Base64Value. Base64Value is a little-endian binary value encoded as a Base64 string. At this point, VariableName must be defined in Design Pad as a global variable with network access enabled. The second form of the command may be used for structure type variables. In that case, the requested structure member value is set. Returns "@ReqID;SetVar=Success” or “@ReqID;Error=code;error message”.

The Design Pad APIs

FairNET

Sends the bytes specified by Base64Value to the device's FANDA FairNET channel. The data is interpreted per the FairNET specification, as if the data had been received over the IR interface. The FANDA client acts as the FairNET master.

There is no reply to this command. Returned FairNET data arrives via asynchronous FairNET messages:

Returns the bytes specified by Base64Value from the device's FANDA FairNET channel. The data is interpreted per the FairNET specification, as if the data had been received by the client from the IR interface. The FANDA client is the FairNET master, so this message will only occur in response to an earlier FairNET message sent from the client.

A single FairNET incoming packet may be split into multiple FANDA FairNET messagess, and a single FANDA FairNET message may contain data from multiple FairNET packets.

ShowFile

Returns the contents of file aliased by Moniker and return it as one or more Base64 encoded strings of the format:

After the entire file contents are returned, either "@ReqID;ShowFile=Success” is returned if the file was returned successfully, or “@ReqID;Error=code;error message” if an error was encountered while reading the file. The only file moniker currently supported is Messages and refers to Linux and LynxOS syslog messages.

Update

The UpdateSubcommand command set allows uploading and executing a self-extracting update program, which may include a control code update or a kernel update. There are several sub-commands, which are typically issued in the order shown below.

UpdateStart

Start an update. The server will ensure that sufficient space is available to store an image of the specified size before proceeding. If sufficient space is available, the server will respond with:

otherwise, the server will return an error and cancel the update:

UpdateData

Transfers a chunk of the update program. CurrentOffset indicates the offset within the updater program at which Base64Data should be written. If the data is written out successfully the response is:

otherwise, an error response is returned and the client may retry the failed chunk:

UpdateApply

Verify the message digest of the transferred data and apply the update. If no digest is provided or the provided digest is not supported, the total amount of data transferred in successful UpdateData commands is compared to the size given in the UpdateStart command. If a digest or length mismatch is detected, an error response is returned and the update is canceled:

If validation succeeds, the UpdateApply=Success message is returned, followed by an EOF:

at which point no more FANDA data is passed over the connection. The SSH connection is connected to the update program's stdin, stdout, and stderr. Messages from the update program should be displayed to the user to confirm progress. When the update completes (successfully or otherwise) the SSH connection will be closed.

Each UpdateArg is passed as as a command-line argument to the update program. If no UpdateArg parameters are passed, the default is -- -n (preserve node configuration) to maintain network parameters. To run the updater with no arguments, pass Arg= (empty string).

If the update process proceeds to stop or restart the control code, any other connected clients will receive:

Currently supported DigestType values are MD5 and SHA1. The DigestValue is Base64 encoded. Multiple digests types may be included in a single command, in any order.

The SC1 supports all digest types. The NIM2 does not support message digests and performs length validation only. Any digest provided is ignored.

UpdateCancel

Cancel an in-progress update, typically in response to a user action. Any data already transferred is discarded. The response is:

Lock

Acquire the lock(s) specified by the LockID parameters. Return an error if the lock can not be acquired after AcquireTimeout seconds (may be zero or omitted, in which case the command returns a result immediately). If the locked capability is not used for HoldTimeout seconds the lock is automatically released. All held locks are released when a FANDA session ends. If HoldTimeout is zero or omitted, the lock is held until the session ends.

If more than one lock is specified, they are all acquired atomically or, if one or more cannot be acquired, then none are acquired.

Repeated Lock commands may be used to verify that the caller is still holding the lock. This will also reset the HoldTimeout to the value specified in the most recent Lock command. This is not a nested lock, only one Unlock call is needed to release the lock, regardless of the number of Lock commands that were executed.

The currently defined locks are:

The response is either

for success or

if an error occurs.

LockIDs are C-style numeric values (parsed with scanf "%d" modifier or strtol with base 0).

Unlock

Unlock the lock(s) with the IDs specified in the LockID parameters. If no error occurs, the response is:

with a comma-separated list of all locks that were released (locks that were abandoned due to timeout will not appear in the list). If an error occurs the response is

If LockID is the string "all", all locks currently held by the caller are released, and the response is:

with a comma-separated list of all locks that were released. If no locks were held the ID list is empty.

LockIDs are C-style numeric values (parsed with scanf "%d" modifier or strtol with base 0), or the string "all".

Configuration APIs

These meta-commands affect the FANDA connection itself.

Echo

The Echo command turns on or off echoing of all characters received by the server back to the client before processing. This is useful during debugging when using a command shell SSH client to talk to the server directly. No reply is given to this command.

Acks

Specifies whether acknowledgements are returned. If the client wishes to operate asynchronously, this option may be turned on. This will cause the server to immediately respond to all commands with an “<tt>@ReqID;OK;Command</tt>” string where Command is the recognized command (which may differ in case from the transmitted command). No reply is given to this command.

EOF

The EOF command signifies that the client is about to disconnect. (Future version: If the client does not send the EOF command before disconnecting, the server will maintain workspace information about the session until the session times out. This feature allows the client to reconnect after an unintended disconnect using the same logon credentials as the previous connection.) No reply is given to this command.

SetTimeout

Specifies the length of time the client may stay connected without sending a request before the server automatically disconnects. The default timeout interval is 300 seconds.
Returns “@ReqID;SetTimeout=Success” or “@ReqID;Error=code;error message”.

Keepalive

This command resets the timeout timer. The client may use this command at any time to reset the timeout timer. No reply is given to this command..

SetDataFormat

Specifies the reply format of data returned by the GetVar command.

GetCaps

This command requests a bit field indicating the capabilities of the current connection. The contents may depend on the device type, software version, and rights of the current FANDA user. Additional bits may be defined as new commands and capabilities are added in the future without requiring a change to the protocol version. Clients should simply ignore unsupported bits.

The response is:

HexByteList is a comma-separated list of capability bytes, starting with Byte 0. The client should ignore unknown bytes in the response, and should treat any missing bytes as zero. The currently defined capability flags are (Mask is in the format used by GetCaps and SetCaps):

The current max-capability response is

Asynchronous Messages

The following messages may be sent from the server to the client at any time.

EOF

The EOF asynchronous message that the server is ending the FANDA session. If present, Reason provides additional information on the reason the session is being ended.

EOF;Timeout

If a client session does not send any requests to the server within the configured timeout period, the server will send an “EOF;Timeout” string to the client and then immediately disconnect. The client may use this information to differentiate between disconnects due to timeouts and unexpected disconnects for other reasons. (Future version: Client sessions that are unexpectedly disconnected may be reconnected in the future up until the timeout period elapses by using the same logon credentials.)

EOF;Update

If a client starts an update, the server sends this message to indicate the end of the FANDA session. Any additional data transferred over the session after this message is to/from the stdin/stdout/stderr streams of the update program.

EOF;Shutdown

If a client is connected when the server is shut down, the server will send this message then immediately disconnect.

NDL

This message will be sent after the initial connection to inform the client of the current NDL in use. The format of xml string is documented elsewhere.

This message will be sent whenever there is a program change causing the NDL format to change. When the schema program is erased, an empty NDL is sent (xml string is blank). When a new schema program is loaded, the new NDL string is sent.

Internal Use APIs 

These APIs are for internal use only, and are not intended to be called by client software.

GetCapsAsync

It has no synchronous response, and causes the current caps to be sent as an asynchronous message.

SetCaps

The response is the same as the GetCaps command.

The bytes in HexByteList have the same format as a GetCaps response. The connection's current capabilities are masked with the capabilities given in this command. After this command completes, the connection's capabilities are reduced to the intersection of the two sets.

SetCapsAsync

This is an asynchronous version of SetCaps. The format and effect is the same as the SetCaps command, but there is no response.

GetNDLAsync

There is no synchronous response this command, but it will cause the NDL to be returned as an asynchronous message.

GetMulticastKeyAsync

There is no synchronous response this command, but it will cause the multicast encryption keys to be returned as an asynchronous message.

Change History

• Changes in Protocol Version 1.4:
  • Add GetMulticastKey command.
  • Add MulticastKey async message.
• Changes in Protocol Version 1.3:
  • Add Device ID to hello message.
  • Add GetCaps command.
  • Add Fairnet command.
  • Add Update command.
  • Add Lock and Unlock commands.
  • This update to the protocol is backwards-compatible with the 1.2 protocol. Existing 1.2 clients may use a 1.3 server.
• Changes in Protocol Version 1.2:
  • Initial published version?