packet_events

- packet events overview

Description

The implementation of the ip(7P) protocol in Solaris supports a number of packet events that are made available through netinfo(9F). The packet events that are currently available to programmers and applications are listed below. Each packet event below includes a description of the event.

The hook function (h_func) supplied in the hook_t(9S) structure passed to net_hook_register(9F) is called once for each packet. Returning more than one packet by the hook function by changing b_next is not supported. Only one packet at a time is passed in. On return from the hook function, one packet can be returned.

When the hook function is called, it is passed a pointer to a hook_pkt_event_t structure via the info (hook_data_t) argument. See hook_pkt_event(9S) for more details about the fields in this structure and how they are used with respect to the events described herein.

IP Events

IP events are available individually for each of the IPv4 and IPv6 protocols. Thus a party that is interested in both protocols must register two hooks: one for each protocol family. Similarly, if only one of the two protocols is of interest then the event for that protocol family can be subscribed to with no need to worry about packets from the other being presented.

Forwarding Events

Packet Event: Forwarding
Macro: NH_FORWARDING
Name: forwarding

IP packets that are received by the host but are destined for another host where the host is doing routing across multiple network interfaces will be delivered to the forwarding packet event when the host has determined the next outgoing network interface. Packets are received by this event after they have been processed by the Internet Load Balancer (see ilbadm(1M)).

Packets that are routed using IPFilter's policy based routing features will not be seen by the forwarding hook as they do not pass through the kernel's routing and instead use net_inject(9F) to deliver packets directly to a network interface.

Loopback Events

Loopback packet events are generated to simulate the transmission and reception of IP packets inside the kernel when it is sending a packet to itself. Packets addressed to the loopback address (127.0.0.1) will can be seen at these events. Additionally, packets that originate from an IP address that is assigned to a network interface and that carry the IP address of a network interface on the same host in the destination field also fall into this category.

The loopback events are the only packet events for which a packet can be received on the loopback interface (for example, lo0) or any other network interface that has the loopback flag set.

Network traffic that “transits” between zones that are sharing an instance of IP networking will also trigger loopback packet events. A local zone that is sharing its network instance with the global zone will typically have network interfaces named such as e1000g0:1, and there will be no network interfaces that are not logical network interfaces.

If a firewall or other software package is only interested in packets that are being sent and received by the physical hardware and all networking activity local to the host is considered to be safe then it is not necessary to subscribe to the loopback events.

Any software that receives packets from the loopback events must be aware that the packets are optimized for handling within the kernel. Thus it is possible that checksums may be missing or just incorrect because the system has no need to guard against the packet being corrupted in transmission.

Packet Event: Loopback In
Macro: NH_LOOPBACK_IN
Name: LOOPBACK_IN

The “loopback in” event simulates the kernel receiving a packet from itself. For example, if a user where to run the command “ssh localhost”, a “loopback in” event would be generated for the initial connection establishment where the host “receives” a packet to port 22 from itself. In most cases, the “loopback in” event will be the second event for any packet that is local to the host; the first will be the “loopback out” event that corresponds to the application or kernel sending the packet to itself.

Packet Event: Loopback Out
Macro: NH_LOOPBACK_OUT
Name: LOOPBACK_OU

The “loopback out” event simulates the kernel sending a packet to itself.

Physical Events

The “Physical” packet events occur in IP to indicate the reception and transmission of packets by IP from an external source to IP. By way of example, all packets exchanged between network interfaces present in the mac(9F) layer and IP will pass through these events.

Each packet received will have the IP header aligned to a 32bit boundary. There will be no other references held to the packet, thus db_ref from datab(9S) will be 1.

Packet Event: Physical In
Macro: NH_PHYSICAL_IN
Name: PHYSICAL_IN

The “physical in” event occurs for packets that have been accepted by IP and for which a very basic set of tests is completed. This currently includes ensuring that a packet is not from a loopback address nor destined to a loopback address.

All packets presented by the “physical in” will have an IP version number that matches the family of the event. Thus a packet received from the callback attached to the “physical in” event for IPv6 will always have an IP version number of 6.

Packets with impossible addresses, such as those in the loopback network address space for IPv4, will not be seen at the “physical in” event as they are filtered out by IP itself. However, other checks (such as ensuring the checksum is correct) are not done until after the packet passes through this event.

Packet Event: Physical Out
Macro: NH_PHYSICAL_OUT
Name: PHYSICAL_OUT

The “physical out” event occurs for packets that are being transmitted by IP. There is one event per packet that is transmitted, thus packets that are internally generated and too big will be seen as fragments when this event occurs.

For network interfaces that support offloading of the checksum calculation from software into hardware for the IP suite of protocols, packets presented by this event may either have incorrect, missing (zero) or partial checksums. The function net_ispartialchecksum(9F) can be used to verify if the packet is expecting hardware to complete the checksum calculations.

kstats

Each of the packet events presented here has its own kstat entry when it is available. To access a particular packet event's kstats, the use of the packet event's name as the kstat name and the protocol as the kstat module is supported.

The following example lists all kstats that have the name “PHYSICAL_IN”. When present, there will be one for each protocol that is registered with netinfo: arp, inet and inet6.

# kstat -n PHYSICAL_IN

The following example displays the kstat information for the “PHYSICAL_OUT” event that is associated with the “inet” module (protocol).

# kstat -m inet -n PHYSICAL_OUT

See Also

ilbadm(1M), ip(7P), datab(9S), hook_pkt_event(9S), hook_t(9S), mac(9F), net_ispartialchecksum(9F), net_hook_register(9F), net_inject(9F), netinfo(9F)