icmp provider

Skip to end of metadata
Go to start of metadata

icmp Provider

The icmp provider provides probes for tracing the ICMP protocol.

This provider is under development and is not yet available

Top

Probes

The icmp probes are described in the table below.

icmp Probes
Probe Description
send Probe that fires whenever ICMP sends a message.
receive Probe that fires whenever ICMP receives a message.

The send and receive probes cover ICMP messages on IP interfaces, and cover both IPv4 and IPv6 ICMP traffic.
Top

Arguments

The argument types for the icmp probes are listed in the table below. The arguments are described in the following section.

icmp Probe Arguments
Probe args[0] args[1] args[2] args[3] args[4]
send pktinfo_t * csinfo_t * ipinfo_t * NULL icmpinfo_t *
receive pktinfo_t * csinfo_t * ipinfo_t * NULL icmpinfo_t *

Top

pktinfo_t structure

The pktinfo_t structure is where packet ID info can be made available for deeper analysis if packet IDs become supported by the kernel in the future.
The pkt_addr member is currently always NULL.

typedef struct pktinfo {
        uintptr_t pkt_addr;             /* currently always NULL */
} pktinfo_t;

Top

csinfo_t structure

The csinfo_t structure is where connection state info is made available. It contains a unique (system-wide) connection ID, and the process ID and zone ID associated with the connection. For ICMP, the connection information is only fully populated for ICMP errors received, as these are sent to a specific connection. Other ICMP data received (e.g. ICMP echo requests/replies) is not directed to a specific connection, so the connection ID is 0. For outbound ICMP data, the pid and zoneid are specified but the connection ID is 0.

typedef struct csinfo {
        uintptr_t cs_addr;
	uint64_t cs_cid;
	pid_t cs_pid;
	zoneid_t cs_zoneid;
 } csinfo_t;
csinfo_t Members
cs_addr Address of translated ip_xmit_attr_t *.
cs_cid Connection id. A unique per-connection identifier which identifies the connection during its lifetime.
cs_pid Process ID associated with the connection.
cs_zoneid Zone ID associated with the connection.

Top

ipinfo_t structure

The ipinfo_t structure contains common IP info for both IPv4 and IPv6.

typedef struct ipinfo {
        uint8_t ip_ver;                 /* IP version (4, 6) */
        uint16_t ip_plength;            /* payload length */
        string ip_saddr;                /* source address */
        string ip_daddr;                /* destination address */
} ipinfo_t;
ipinfo_t Members
ip_ver IP version number. Currently either 4 or 6.
ip_plength Payload length in bytes. This is the length of the packet at the time of tracing, excluding the IP header.
ip_saddr Source IP address, as a string. For IPv4 this is a dotted decimal quad, IPv6 follows RFC-1884 convention 2 with lower case hexadecimal digits.
ip_daddr Destination IP address, as a string. For IPv4 this is a dotted decimal quad, IPv6 follows RFC-1884 convention 2 with lower case hexadecimal digits.

Top

icmpinfo_t structure

The icmpinfo_t structure is a DTrace translated version of the information contained in the various forms of ICMP and ICMP6 header.

typedef struct icmpinfo {
        uint8_t icmp_version;
        uint8_t icmp_type;
        uint8_t icmp_code;
        uint16_t icmp_checksum;
        uint32_t icmp_address_mask;     
        uint16_t icmp_echo_id;
        uint16_t icmp_echo_seq;
        uint32_t icmp_param_problem_ptr;
        uint32_t icmp_pmtu_update;
        uint8_t icmp_radv_num_addrs;
        uint16_t icmp_radv_lifetime;
        uint32_t *icmp_radv_addrs;
        string icmp_redirect_gateway;
        uint32_t icmp_timestamp_otime;
        uint32_t icmp_timestamp_rtime;
        uint32_t icmp_timestamp_ttime;
        string icmp6_mld_addr;
        uint8_t icmp6_mld_v2_num_mars;
        uintptr_t icmp6_mld_v2_mars;
        string icmp6_nd_target;
        string icmp6_nd_redirect_destination;
        uint32_t icmp6_nd_radv_reachable;
        uint32_t icmp6_nd_radv_retransmit;
        uint8_t icmp6_rr_segnum;
        uint8_t icmp6_rr_flags;
        uint16_t icmp6_rr_maxdelay;
        /* Original data that triggered ICMP error - NULL/0 if not ICMP error */
        ipha_t *icmp_error_ip_hdr;    /* Orig. IP hdr for ICMP error */
        ip6_t *icmp_error_ip6_hdr;    /* Orig. IPv6 hdr for ICMP error */
        uint16_t icmp_error_sport;
        uint16_t icmp_error_dport;
        struct icmp *icmp_hdr;
        icmp6_t *icmp6_hdr;
} icmpinfo_t;
icmpinfo_t Members
icmp_type ICMP/ICMPv6 message type.
icmp_code ICMP/ICMPv6 message code.
icmp_checksum Checksum of ICMP header and payload.
icmp_hdr Pointer to raw ICMP header at time of tracing.
icmp6_hdr Pointer to raw ICMPv6 header at time of tracing.
icmp_address_mask ICMP address mask reply.
icmp_echo_id ICMP echo request/response ID.
icmp_echo_seq ICMP echo request/response sequence number.
icmp_param_problem_ptr Offset of parameter in original datagram that caused the ICMP/ICMPv6 parameter problem.
icmp_pmtu_update Path MTU update for ICMP "destination unreachable/needs fragmentation" and ICMPv6 "packet too big".
icmp_radv_num_addrs Number of ICMP router advertisements to follow.
icmp_radv_lifetime Lifetime of router advertisements.
icmp_radv_addrs Pointer to router advertisements
icmp_redirect_gateway Gateway for ICMP redirect.
icmp_timestamp_otime Originating time set in ICMP timestamp request - number of seconds since 0:00 UT.
icmp_timestamp_rtime Receive time of timestamp request set in IMCP timestamp response.
icmp_timestamp_ttime Transmit time of timestamp reply sent in response to ICMP timestamp request.
icmp6_mld_addr ICMP6 Multicast layer discovery address.
icmp6_mld_v2_num_mars Number of ICMPv6 Multicast Address Records.
icmp6_mld_v2_mars Pointer to first ICMPv6 Multicast Address Record.
icmp6_nd_target ICMPv6 neighbor discovery target.
icmp6_nd_redirect_destination ICMPv6 neighbor discovery redirect destination.
icmp6_nd_radv_reachable ICMPv6 neighbor discovery router advertisement reachable.
icmp6_nd_radv_retransmit ICMPv6 neighbor discovery router advertisement.
icmp6_rr_segnum ICMPv6 router renumbering segment number.
icmp6_rr_flags ICMPv6 router renumbering flags.
icmp6_rr_maxdelay ICMPv6 router renumbering maximum delay.
icmp_error_ip_hdr Original IP hdr for ICMP/ICMPv6 error.
icmp_error_ip6_hdr Original IPv6 hdr for ICMP/ICMPv6 error.
icmp_error_sport Original layer 4 source port for ICMP/ICMPv6 error.
icmp_error_dport Original layer 4 destination port for ICMP/ICMPv6 error.
icmp_hdr Pointer to original ICMP header, NULL for ICMP6.
icmp6_hdr Pointer to original ICMPv6 header, NULL for ICMP.

See RFCs 792, 1256, 2463 for a detailed explanation of the various ICMP/ICMPv6 message header formats.

Top

Examples

Some simple examples of icmp provider usage follow.

ICMP errors sent by remote host/port.

This DTrace one-liner monitors ICMP errors sent, aggregating by the originating host and target port:

# dtrace -n 'icmp:::send / args[4]->icmp_error_dport != 0 / { @[args[2]->ip_daddr, args[4]->icmp_error_dport] = count(); }'
dtrace: description 'icmp:::send ' matched 9 probes
^C

  10.8.57.20                                           517               21


#

The output above shows 21 ICMP errors sent in response to packets sent from this system to the local port 517. These were UDP packets generated by running the talk(1) program when it's associated inetd service has not been enabled. The ICMP errors are destination unreachable/port unreachable errors, and this script can be used to catch UDP service connection refusal.

ICMP Packets by process

This DTrace one-liner counts ICMP sent/received packets by process:

# dtrace -n 'icmp:::send,icmp:::receive { @[args[1]->cs_pid] = count(); }'
dtrace: description 'icmp:::send,icmp:::receive ' matched 20 probes
^C

   100961                1
   100965                1
   100968                1

These represent 3 ICMP messages received in response to "ping -U" requests.

Top

icmp Stability

The icmp provider uses DTrace's stability mechanism to describe its stabilities, as shown in the following table. For more information about the stability mechanism, see Chapter 39, Stability.

Element Name stability Data stability Dependency class
Provider Evolving Evolving ISA
Module Private Private Unknown
Function Private Private Unknown
Name Evolving Evolving ISA
Arguments Evolving Evolving ISA
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.