...

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 are three 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.

...

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. If multicasts are not encrypted, KeyGen will be 0 and no key data follows.

GetVar

...

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";SetVar=Success” or “@ReqID;Error=code;error message”.

Configuration APIs

These meta-commands affect the FANDA connection itself.

...

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.

...

The current max-capability response is

...