Operator DHCPMessageParser

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.teracloud.streams.network/op$com.teracloud.streams.network.parse$DHCPMessageParser.svg

DHCPMessageParser is an operator for the Streams product that parses individual fields of DHCP messages received in input tuples, and emits tuples containing message data. The operator may be configured with one or more output ports, and each port may be configured to emit different tuples, as specified by output filters. The tuples contain individual fields from the input message, as specified by output attribute assignments.

The DHCPMessageParser operator expects only DHCP messages in its input tuples, without any of the headers that precede them in network packets. The PacketLiveSource and PacketFileSource operators can produce tuples that contain DHCP messages with the PAYLOAD_DATA() output attribute assignment function.

The DHCPMessageParser operator consumes input tuples containing DHCP messages, parses individual fields in the messages, selects messages to emit as output tuples with output filter expressions, and assigns values to them with output attribute assignment expressions.

Output filters and attribute assignments are SPL expressions. They may use any of the built-in SPL functions, and any of these functions, which are specific to the DHCPMessageParser operator:

The DHCPMessageParser operator emits a tuple on each output port for each input tuple, optionally filtered by the outputFilters parameter. Specified fields from the DHCP message in the input tuple are assigned to output attributes with the DHCP parser result functions. All attributes of all output ports must be assigned values, either with explicit assignment expressions, or implicitly by copy from input tuples.

Threads

The DHCPMessageParser runs on the thread of the upstream operator that sends input tuples to it. It does not start any threads of its own.

Exceptions

The DHCPMessageParser operator will throw an exception and terminate in these situations:

  • No output ports are specified.

  • The outputFilters parameter is specified, and the number of expressions specified does not match the number of output ports specified.

Example 


use com.teracloud.streams.network.parse::*;
use com.teracloud.streams.network.source::*;
composite Main {
    type
      PacketType =
          uint64 packetNumber,            // sequence number of packet, as emitted by operator
          uint32 captureTime,             // time that packet was captured, in seconds since Unix epoch
          rstring ipSourceAddress,        // IP source address
          rstring ipDestinationAddress,   // IP destination address
          blob dhcpMessage;               // the DHCP message from a packet, excluding all network headers

      DHCPMessageType =
          uint64 packetNumber,            // sequence number of packet, as emitted by operator
          rstring captureTime,            // time that packet was captured, in seconds since Unix epoch
          rstring ipSourceAddress,        // IP source address
          rstring ipDestinationAddress,   // IP destination address
          uint64 messagesProcessed,
          rstring dhcpMessageType,        // option 53: type of this DHCP message
          rstring dhcpServer,             // header: address of DHCP server, as an IPv4 address
          rstring dhcpServerError,        // option 56: error message from server, if request failed
          rstring clientMACAddress,       // header: client hardware address
          rstring clientIPAddress,        // header: address of client requesting renewal of lease, as an IPv4 address
          rstring leaseDuration,          // option 51: address lease time, in seconds
          rstring leasedAddress,          // header: address leased to client by server, as an IPv4 address
          rstring leasedAddressSubnetMask,// option 1: the subnet mask of the client, as an IPv4 address
          list<rstring> subnetRouters,    // option 3: list of routers on client's subnet, as IPv4 addresses
          list<rstring> staticRoutes,     // option 33: list of address pairs for routing table, as IPv4 addresses
          list<rstring> dnsServers,       // option 6: list of DNS servers, as IPv4 addresses
          rstring hostname,               // option 12: hostname of the client
          rstring domainName,             // option 15: domain name client should use with DNS
          uint32 requestIdentifier,       // header: request correlator, chosen by client, returned by server
          rstring requestedAddress,       // option 50: client's requested address, as an IPv4 address
          list<uint8> requestedParameters,// option 55: list of requested DHCP parameters, specified as option codes
          rstring parseError;

      // error output from DHCPMessageParser operator
      DHCPErrorType =
          uint64 packetNumber,            // sequence number of packet, as emitted by operator
          rstring captureTime,            // time that packet was captured, in seconds since Unix epoch
          rstring ipSourceAddress,        // binary representation of IP source address
          rstring ipDestinationAddress,   // IP destination address
          rstring parserError,
          rstring dhcpError,              // option 56: error message from server, if request failed
          rstring dhcpMessage;

  graph
    stream<PacketType> PacketStream as Out = PacketFileSource() {
        param
            pcapFilename: getSubmissionTimeValue("pcapFilename", "data/sample_dns+dhcp.pcap" );
            inputFilter: "udp port 67 or udp port 68";
            metricsInterval: 0.0;
        output Out:
            packetNumber = packetsProcessed(),
            captureTime = CAPTURE_SECONDS(),
            ipSourceAddress = convertIPV4AddressNumericToString(IPV4_SRC_ADDRESS()),
            ipDestinationAddress = convertIPV4AddressNumericToString(IPV4_DST_ADDRESS()),
            dhcpMessage = PAYLOAD_DATA();
    }

    ( stream<DHCPMessageType> DHCPMessageStream as OutMessage ;
      stream<DHCPErrorType> DHCPErrorStream as OutError ) = DHCPMessageParser(PacketStream) {
      logic
        state: {
          map<uint8,rstring> dhcpTypes = { 1: "DHCPDISCOVER", 2: "DHCPOFFER", 3: "DHCPREQUEST", 4: "DHCPDECLINE", 5: "DHCPACK", 6: "DHCPNAK", 7: "DHCPRELEASE", 8: "DHCPINFORM" };
        }
      param
          messageAttribute: dhcpMessage;
          outputFilters: true, parseError();
      output OutMessage:
          captureTime = formatEpochDateTime(captureTime),
          messagesProcessed = messagesProcessed(),
          dhcpMessageType = DHCP_MESSAGE_TYPE() in dhcpTypes ? dhcpTypes[DHCP_MESSAGE_TYPE()] : (rstring)DHCP_MESSAGE_TYPE(),
          dhcpServer = convertIPV4AddressNumericToString(DHCP_SERVER_ADDRESS()),
          dhcpServerError = DHCP_ERROR_MESSAGE(),
          clientMACAddress = convertMACAddressNumericToString((list<uint8>[6])DHCP_CLIENT_HARDWARE_ADDRESS()),
          clientIPAddress = convertIPV4AddressNumericToString(DHCP_CLIENT_ADDRESS()),
          leaseDuration = formatElapsedTime(DHCP_ADDRESS_LEASE_TIME()),
          leasedAddress = convertIPV4AddressNumericToString(DHCP_YOUR_ADDRESS()),
          leasedAddressSubnetMask = convertIPV4AddressNumericToString(DHCP_SUBNET_MASK()),
          subnetRouters = convertIPV4AddressListToStringList(DHCP_ROUTERS()),
          staticRoutes = convertIPV4AddressListToStringList(DHCP_STATIC_ROUTES()),
          dnsServers = convertIPV4AddressListToStringList(DHCP_DNS_SERVERS()),
          hostname = DHCP_HOST_NAME(),
          domainName = DHCP_DOMAIN_NAME(),
          requestIdentifier = DHCP_TRANSACTION_IDENTIFIER(),
          requestedAddress = convertIPV4AddressNumericToString(DHCP_REQUESTED_ADDRESS()),
          requestedParameters = DHCP_PARAMETER_REQUESTS(),
          parseError = parseErrorDescription();
      OutError:
          captureTime = formatEpochDateTime(captureTime),
          parserError = parseErrorDescription(),
          dhcpError = DHCP_ERROR_MESSAGE(),
          dhcpMessage = substring((rstring)dhcpMessage, 0, 2*(int32)parseErrorOffset()) + "_" + substring((rstring)dhcpMessage, 2*(int32)parseErrorOffset(), 2*size(dhcpMessage)-2*(int32)parseErrorOffset());
    }

    // See the $STREAMS_INSTALL/samples/com.teracloud.streams.network directory for more examples
}

References

DHCP messages and the fields they contain are described here:

Summary

Ports
This operator has 1 input port and 0 or more output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 3 parameters.

Required: messageAttribute

Optional: outputFilters, processorAffinity

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

The DHCPMessageParser operator requires one input port. One input attribute must be of type blob and must contain a DHCP message, excluding the network headers that proceed them in network packets, as specified by the required parameter messageAttribute.

The PAYLOAD_DATA() output assignment function of the PacketLiveSource and PacketFileSource operators produces attributes that can be consumed by the DHCPMessageParser operator.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Ports (0...)

The DHCPMessageParser operator requires one or more output ports.

Each output port will produce one output tuple for each input tuple if the corresponding expression in the outputFilters parameter evaluates true, or if no outputFilters parameter is specified.

Output attributes can be assigned values with any SPL expression that evaluates to the proper type, and the expressions may include any of the DHCP result functions. Output attributes that match input attributes in name and type are copied automatically.

Properties

Parameters

Required: messageAttribute

Optional: outputFilters, processorAffinity

messageAttribute

This required parameter specifies an input attribute of type blob that contains a DHCP messages to be parsed by the operator.

Properties

outputFilters

This optional parameter takes a list of SPL expressions that specify which DHCP messages should be emitted by the corresponding output port. The number of expressions in the list must match the number of output ports, and each expression must evaluate to a boolean value. The output filter expressions may include any of the DHCP result functions.

The default value of the outputFilters parameter is an empty list, which causes all DHCP messages processed to be emitted by all output ports.

Properties

processorAffinity

This optional parameter takes one expression of type uint32 that specifies which processor core the operator's thread will run on. The maximum value is P-1, where P is the number of processors on the machine where the operator will run.

Where the operator runs on a thread of its own, this parameter applies to the operator's thread. This is the situation when the operator's input port is configured as a threaded input port, and when the operator has an @parallel annotation.

Where the operator runs on the thread of an upstream operator, this parameter affects the thread of the operator that sends tuples to it. This is the situation when the operator is fused with an upstream operator.

The default is to dispatch the operator's thread on any available processor.

Properties

Code Templates

DHCPMessageParser

stream<${outputSchema}> ${outputStream} = com.teracloud.streams.network.parse::DHCPMessageParser(${inputPacketStream}) {
  param
      messageAttribute: ${inputPacketStream-blob-attribute};
      ${parameter}: ${parameterExpression}
  output
      ${outputStream}: ${attributeAssignments}
}

Libraries

Include Path: ../../impl/include