C H A P T E R 20
Control Plane and System Interaction
Control Plane Interaction
At a conceptual level, packetC capabilities can be categorized as data plane capabilities, which involve examining, changing, and routing packets and control plane capabilities, which involve displaying system-level values and messages. In some systems, the two planes may be on separate boards or on distant components in a far-flung system. In others, such as a PC-based emulation system, the two sets of capabilities might execute on the same hardware. Thus, packetC specifies control plane capabilities in a general way, while allowing considerable latitude in how they are implemented.
The defined control plane capabilities are:
- Alerts
- Information Logging
- Messages
The packetC language specification defines the above capabilities in terms of language features and constructs but does not proscribe additional control plane capabilities. Such capabilities will typically be implemented by using compiler pragmas associated with the control pragma category.
Alerts and Information Logging
packetC provides alert and log commands to facilitate passing messages to the control plane environment and to facilitate logging packet data. The alert command simply sends a message while the log command sends associated packet data. Each of these commands has an associated message group and identification number associated with the action. The values used are the current values within the sys data structure at the time of the command call.
Alert command examples are shown below:
sys.messageGroup = MSG_CRITICAL;
sys.messageId = TCP_OPTION_MSG;
alert;
sys.messageGroup = MSG_CRITICAL;
sys.messageId = MSG_BOX_OVERHEATING;
alert;
Log messages are used to send packet data to the control plane. Logging may include a portion of the current packet or the entire packet. Similar to the alert command, a message group and identification is associated with the operation.
Log command examples are shown below:
sys.messageGroup = MSG_CRITICAL;
sys.messageId = 2;
log pkt; // log the entire packet
sys.messageGroup = MSG_MAJOR;
sys.messageId = 21;
log pkt[ 0 : 63 ]; // log first 64 bytes of the packet
alert Statement
The packetC statements consist of alphanumeric keywords, rather than new operator symbols or overloaded operator symbols.
The alert statement sends a text string message to the Control Plane environment, where it may be displayed or otherwise processed (see the section on the Messages to the Control Plane in this chapter). Two system variables located in the global sys variable control the default behavior of alert.
sys.messageId is an index of the message to use and sys.messageGroup is an enumeration value that indicates the message group, both of which depend on the definitions from the cloudshield.ph include file shown below in the section on cloudshield.ph file in this chapter.
enum int t_msgGroup = {
MSG_CRITICAL = 1, // initial default
MSG_MAJOR,
MSG_MINOR,
MSG_WARNING,
MSG_INFO };
When an alert statement appears, default values set in the sys variable are used. The user can manipulate those defaults by setting the following values in the sys struct (see Chapter 18).
sys.messageId = 5;
sys.messageGroup = MSG_INFO;
Here are some examples of the alert statement being used.
const int TCP_OPTION_MESSAGE = 12;
…
sys.messageGroup = MSG_CRITICAL;
sys.messageId = TCP_OPTION_MESSAGE;
alert;
sys.messageGroup = MSG_CRITICAL;
sys.messageId = MSG_BOX_OVERHEATING;
alert;
log Statement
The log statement causes the entire packet or a portion of the packet to be stored in the control plane environment, where it may be later displayed or otherwise processed (see section on Messages to Control Plane in this chapter). Setting two system variables (structure fields located in the global sys variable) controls the default behavior of log:
- sys.messageId is an index of the message to use
- sys.messageGroup is an enumeration value that indicates the message group
Refer to detailed information on the $MSG_TYPE later in this chapter and in the packetC.ph include file provided with a packetC development environment.
Logging treats the packet as a byte array. When an array range is specified, only the portion of the packet that the range specifies is logged.
sys.messageGroup = MSG_CRITICAL;
sys.messageId = 2;
log pkt; // log the entire packet
// w/msgId = 2 and MSG_CRITICAL
sys.messageGroup = MSG_MAJOR;
sys.messageId = 21;
log pkt[ 0 : 63 ]; // log the first 64 bytes of the packet
// w/msgId = 21 and MSG_MAJOR
Messages to Control Plane ($MSG_TYPE)
In order to support the message capabilities of the alert and log statements, a packetC implementation shall provide the following definitions at the global scope level of a module, either by pre-definition or via an include file:
const int MAX_PACKETC_MSGS = <implementation-supplied number > 1> ;
const int MAX_PACKETC_MSG_LEN = <implementation-supplied number > 1> ;
typedef byte $MSG_TYPE[MAX_PACKETC_MSGS][MAX_PACKETC_MSG_LEN];
A packetC module that uses alert or log statements must include a global scope definition that declares a variable named “messages”, and initializes the message strings:
const $MSG_TYPE messages = { “string1”, “string2”, …};
Implementations have the option of making the type, $MSG_TYPE, constant or not.
The following code shows a simple example that sends an alert for every packet with the severity level set to remainder of taking the length of the packet and dividing it by 5.
packet module alertTest;
/* Globals */
int packetLength_;
%pragma control packetLength_ (export);
int lengthModulo5_;
%pragma control lengthModulo5_ (export);
$MSG_TYPE messages = {
"Test Message Critical",
"Test Message Major",
"Test Message Minor",
"Test Message Warning",
"Test Message Informational"
};
void main( $PACKET pkt, $PIB pib, $SYS sys )
{
int pktLength;
pktLength = pib.length;
packetLength_ = pktLength;
/* Get modulo 5 and set message severity accordingly */
int lenRemainder;
lenRemainder = pktLength % 5;
lengthModulo5_ = lenRemainder;
switch (lenRemainder) {
case 0:
sys.messageGroup = MSG_CRITICAL;
sys.messageId = 0;
alert;
break;
case 1:
sys.messageGroup = MSG_MAJOR;
sys.messageId = 1;
alert;
break;
case 2:
sys.messageGroup = MSG_MINOR;
sys.messageId = 2;
alert;
break;
case 3:
sys.messageGroup = MSG_WARNING;
sys.messageId = 3;
alert;
break;
case 4:
sys.messageGroup = MSG_INFO;
sys.messageId = 4;
alert;
break;
default:
}
}
Figure 20-1 below shows a syslog client capturing the messages out of the control plane as a result of the code shown above. The section along the far right showing 5:Test Message Informational in the first line is a result of the severity code being set by sys.messageGroup = MSG_INFO;
Figure 20-1. Screenshot of syslog server displaying messages from packetC
Messages Portion of cloudshield.ph
In packetC, the following declarations and types are provided for use with messages. The definitions are preloaded through the inclusion of include file cloudshield.ph at the start of each application.
//==============================================================================
// Message Group Levels
//
// The MessageGroup enumerated type is used to set a severity level for a log()
// message. This field can be set once in a context and all future events that
// are generated during the processing of the packet will utilize this value.
// The $SYS structure utilized MessageGroup with field messageGroup.
//
//==============================================================================
enum int MessageGroup
{
MSG_CRITICAL = 1,
MSG_MAJOR = 2,
MSG_MINOR = 3,
MSG_WARNING = 4,
MSG_INFO = 5
};
//==============================================================================
// Message Constants
//
// The following constants provide a maximum message number and length for a
// log() message generated by the packetC system. Use in conjunction with the
// messageId field in $SYS.
//
//==============================================================================
const int MAX_PACKETC_MSGS = 255;
const int MAX_PACKETC_MSG_LEN = 80;