Controller Packet Specifications

The version date of this specification is 2024/07/02.

The controller program communicates use the FSS-000F (Packet).

This specification declares how the Payload Block, which is in FSS-000E (Payload) format, is required to be used.

Only a single header is allowed.

Only a single payload is allowed.

Packet Structure:

Packet is grouped into the following blocks:
- control: A single 1-byte block representing control codes.
- size: A single 4-byte block representing the size of the entire packet, including the control block.

The header Object contains the following FSS-0001 (Extended Object) (depending on type):

action: A valid action type: freeze, kexec, kill, pause, reboot, reload, rerun, restart, resume, shutdown, start, stop, or thaw.
length: A positive whole number inclusively between 0 and 4294965248 representing the length of the payload (may be in binary, octal, decimal, duodecimal, or hexidecimal).
status: The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
type: The packet type that is one of controller, error, or init.

When there are multiple Objects of the same name inside the header:

action: The order represents the order in which the actions are performed..
length: There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal).
status: A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
type: The first represent the type and all others represents a sub-type.

There are different headers and payload properties based on the type.

The controller type:

Supports the following headers: action, length, status, and type.
Only a single action may be provided and must exist for request and response packets.
Only a single status may be provided and must exist for response packets.
The payload is dependent on the action.

The error type:

Supports the following headers: length, status, and type.
Only a single status may be provided and must exist for request and response packets.
The payload is a NULL terminated string whose length is defined by the length header Content.

There are different headers and payload properties based on the type.

The init type:

Supports the following headers: action, length, status, and type.
Only a single action may be provided and must exist for request and response packets.
Only a single status may be provided and must exist for response packets.
The payload is dependent on the action.

Packet Documentation

Describes how a packet is designed and intended to be used.

The packet is the general category in which multiple types of packets belong. This describes the different packets based on their type.

Each packet begins with a control block and a size block followed by a payload block.

The control block:

The leading bit (starting from the left) designates the the format of the payload, which is 0 for string and 1 for binary.
The second bit (starting from the left) designates the the byte order for the rest of the packet, which 0 is for little endian and 1 is for big endian.
The remaining 6-bits are reserved for future use.
The size block:
- The size block represents the size of the entire packet (the control block, the size blocks, and the payload block).
- This number is a single 32-bit unsigned integer.

Example packet structure:

[ Control Block ] [ Size Block                                  ] [ Payload Block         ]
[ 0b10000000    ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 - 5) ]

The payload block:

This block is represented by the FSS-000E payload specification and its structure ad use is described in the next sections.

The following types of payload are received or sent:
1. controller payload.
2. error payload.
3. init payload.

The controller payload:

Commands being sent to the controller and their respective responses utilize a controller payload.
These are pre-defined commands to rules or the controller program itself.
Commands such as starting or stopping some rule, for example.
A controller payload is also sent in response to a controller payload request to represent a success.
- The now condition designates that the kexec, reboot, or shutdown is to begin immediately.
- The at condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock.
- The in condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started.

For these time conditions, different units of time should be supported, such as seconds, days, years as standard time, Time, or UNIX Time (Epoch Time).

The normal controller payload commands are any valid Rule Action that performs some action. This does not include Actions that provide some setting or configuration (such as with_pid). Some of the supported commands are: freeze, kill, pause, reload, rerun, restart, resume, start, stop, or thaw. Multiple commands may be sent multiple action headers. The action headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes.

Multiple status headers may exist in the response so long as they each match an action in the request.

The payload is expected to be empty and have a length of 0 for a request. The payload may have an FSS-0000 (Basic) format containing a single Object message to represent a message associated with an action. Multiple message may exist in the response so long as they each match an action in the request.

The error payload:

The error payload is intended to communicate some sort of failure.
The error payload is only sent in response to some request (and not in response to another response).
The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely.
The status from the header designates the status code as either a status code name string or a status code number (where a number may have error and warning bits).
The payload will contain a NULL terminated string representing the message used to describe the error.

The init payload:

The init payload is intended exclusively for the init operation mode and is expected to only be available when running as init.
This is used to provide special actions, namely kexec, reboot, and shutdown.
The kexec is for booting into another kernel, which may effectively be the same as a reboot (kexec is currently neither supported nor implemented).
The reboot is for rebooting the machine (currently not implemented).
The shutdown is for shutting down the machine (currently not implemented).
These three commands are configurable to fire off based on conditions.