DTRACE_IP(4)

💅 DTRACE_IP 💅

okay so bestie, welcome to the dtrace_ip page — that's the DTrace provider for tracing all the stuff that goes down with the IPv4 and IPv6 protocols, no cap ✨

---

🌸 NAME 🌸

dtrace_ip — a DTrace provider for tracing events related to the IPv4 and IPv6 protocols. that's it, that's the whole vibe 🦋

---

✨ SYNOPSIS ✨

ip:::receive(pktinfo_t *, csinfo_t *, ipinfo_t *, ifinfo_t *,
    ipv4info_t *, ipv6info_t *);

ip:::send(pktinfo_t *, csinfo_t *, ipinfo_t *, ifinfo_t *, ipv4info_t *,
    ipv6info_t *);

---

🎀 DESCRIPTION 🎀

So the DTrace ip provider lets you trace events inside the ip(4) and ip6(4) protocol implementations. literally iconic.

• ip:::send() — this probe fires whenever the kernel gets ready to transmit an IP packet, slay 🔥
• ip:::receive() — this one fires whenever the kernel receives an IP packet 💖

The arguments to these probes give you detailed info about the IP headers of the packet in question, plus the network interface it was sent or received on. the way that's so useful 🫶

okay important caveat bestie: unlike the dtrace_tcp(4) and dtrace_udp(4) providers, ip provider probes are triggered by forwarded packets. that means the probes will fire on packets that are not destined to the local host. yes really. don't come for me, that's just how it is 💀

---

👑 ARGUMENTS 👑

🧚 pktinfo_t

This argument is currently unimplemented and is only included for compatibility with other implementations of this provider. its fields are:

• uintptr_t pkt_addr — always set to 0.

🌈 csinfo_t

Also currently unimplemented, also just there for compatibility with other implementations of this provider. its fields are:

• uintptr_t cs_addr — always set to 0.
• uint64_t cs_cid — a pointer to the struct inpcb for this packet, or NULL.
• pid_t cs_pid — always set to 0.

🦋 ipinfo_t

This one has the IP fields that are common to both IPv4 and IPv6 packets. its fields are:

• uint8_t ip_ver — IP version of the packet: 4 for IPv4 packets and 6 for IPv6 packets.
• uint32_t ip_plength — IP payload size. this does not include the size of the IP header or the IPv6 option headers.
• string ip_saddr — IP source address.
• string ip_daddr — IP destination address.

💖 ifinfo_t

Describes the outgoing and incoming interfaces for the packet in the ip:::send() and ip:::receive() probes respectively. its fields are:

• string if_name — the interface name.
• int8_t if_local — a boolean value indicating whether or not the interface is a loopback interface.
• uintptr_t if_addr — a pointer to the struct ifnet which describes the interface. see the ifnet(9) manual page, iykyk.

🍓 ipv4info_t

Contains the fields of the IP header for IPv4 packets. this argument is NULL for IPv6 packets, so heads up 🙈 — DTrace scripts should use the ip_ver() field in the ipinfo_t argument to figure out whether to use this argument. its fields are:

• uint8_t ipv4_ver — IP version. this will always be 4 for IPv4 packets.
• uint8_t ipv4_ihl — the IP header length, including options, in 32-bit words.
• uint8_t ipv4_tos — IP type of service field.
• uint16_t ipv4_length — the total packet length, including the header, in bytes.
• uint16_t ipv4_ident — identification field.
• uint8_t ipv4_flags — the IP flags.
• uint16_t ipv4_offset — the fragment offset of the packet.
• uint8_t ipv4_ttl — time to live field.
• uint8_t ipv4_protocol — next-level protocol ID.
• string ipv4_protostr — a string containing the name of the encapsulated protocol. the protocol strings are defined in the protocol array in /usr/lib/dtrace/ip.d ⭐
• uint16_t ipv4_checksum — the IP checksum.
• ipaddr_t ipv4_src — IPv4 source address.
• ipaddr_t ipv4_dst — IPv4 destination address.
• string ipv4_saddr — a string representation of the source address.
• string ipv4_daddr — a string representation of the destination address.
• ipha_t *ipv4_hdr — a pointer to the raw IPv4 header.

💜 ipv6info_t

Contains the fields of the IP header for IPv6 packets. its fields are not set for IPv4 packets — and same as with the ipv4info_t argument, use the ip_ver() field to determine whether this argument is valid. its fields are:

• uint8_t ipv6_ver — IP version. this will always be 6 for IPv6 packets.
• uint8_t ipv6_tclass — the traffic class, used to set the differentiated services codepoint and extended congestion notification flags.
• uint32_t ipv6_flow — the flow label of the packet.
• uint16_t ipv6_plen — the IP payload size, including extension headers, in bytes.
• uint8_t ipv6_nexthdr — an identifier for the type of the next header.
• string ipv6_nextstr — a string representation of the type of the next header.
• uint8_t ipv6_hlim — the hop limit.
• ip6_addr_t *ipv6_src — IPv6 source address.
• ip6_addr_t *ipv6_dst — IPv6 destination address.
• string ipv6_saddr — a string representation of the source address.
• string ipv6_daddr — a string representation of the destination address.
• struct ip6_hdr *ipv6_hdr — a pointer to the raw IPv6 header.

---

🎀 FILES 🎀

• /usr/lib/dtrace/ip.d — DTrace type and translator definitions for the ip provider. literally the moment 💅

---

🔥 EXAMPLES 🔥

okay so this first script counts received packets by remote host address. eat:

ip:::receive
{
        @num[args[2]->ip_saddr] = count();
}

and this script prints some details of each IP packet as it's sent or received by the kernel. main character script fr fr:

#pragma D option quiet
#pragma D option switchrate=10Hz

dtrace:::BEGIN
{
        printf(" %10s %30s    %-30s %8s %6s\n", "DELTA(us)", "SOURCE",
            "DEST", "INT", "BYTES");
        last = timestamp;
}

ip:::send
{
        this->elapsed = (timestamp - last) / 1000;
        printf(" %10d %30s -> %-30s %8s %6d\n", this->elapsed,
            args[2]->ip_saddr, args[2]->ip_daddr, args[3]->if_name,
            args[2]->ip_plength);
        last = timestamp;
}

ip:::receive
{
        this->elapsed = (timestamp - last) / 1000;
        printf(" %10d %30s <- %-30s %8s %6d\n", this->elapsed,
            args[2]->ip_daddr, args[2]->ip_saddr, args[3]->if_name,
            args[2]->ip_plength);
        last = timestamp;
}

---

🌈 COMPATIBILITY 🌈

This provider is compatible with the ip providers found in Solaris and Darwin. bestie behaviour honestly 🫶

---

⭐ SEE ALSO ⭐

dtrace(1), dtrace_tcp(4), dtrace_udp(4), ip(4), ip6(4), ifnet(9), SDT(9)

---

🌸 HISTORY 🌸

The ip provider first appeared in FreeBSD 10.0. a classic, an icon, a legend 👑

---

💖 AUTHORS 💖

This manual page was written by Mark Johnston <markj@FreeBSD.org>. thank you king 🫡

---

and that's the whole page bestie ✨ this one came from the Debian gang, dated September 14, 2015, and it's the DTRACE_IP(4) kernel interfaces manual — go forth and trace those packets 💅🎀🦋