DTRACE_UDP(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 DTRACE_UDP(4) — the Kernel Interfaces Manual glow-up ✨

Okay so bestie, this is the DTRACE_UDP(4) page from the Kernel Interfaces Manual, and it's literally all about the DTrace provider for tracing UDP stuff. Buckle up, we're getting into packet vibes. 🦋

🎀 NAME 🎀

dtrace_udp — a DTrace provider for tracing events related to the UDP protocol. No cap, that's the whole name. 💖

✨ SYNOPSIS ✨

udp:::receive(pktinfo_t *, csinfo_t *, ipinfo_t *, udpsinfo_t *,
    udpinfo_t *);

udp:::send(pktinfo_t *, csinfo_t *, ipinfo_t *, udpsinfo_t *,
    udpinfo_t *);

Two probes, two moods: one for when packets come in, one for when they go out. Iconic. 👑

🌸 DESCRIPTION 🌸

The DTrace udp provider lets you trace events inside the udp(4) protocol implementation. Lowkey powerful.

  • The udp:::send() probe fires whenever the kernel is about to transmit a UDP packet. 🚀
  • The udp:::receive() probe fires whenever the kernel receives a UDP packet — unless the UDP header is incomplete, the destination port is 0, the length field is invalid, or the checksum is wrong. So if any of those things are off, no probe for you, bestie. 💀

The arguments to these probes can be used to get detailed info about the IP and UDP headers of the corresponding packet. It's giving forensic girly. 🔍

🧚 ARGUMENTS 🧚

pktinfo_t — the compatibility cutie 🫶

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

  • uintptr_t pkt_addr — always set to 0. Literally always. Don't expect more. 🙈

csinfo_t — also a compatibility moment 💅

This argument is currently unimplemented and is included 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. Periodt.

ipinfo_t — the IP tea ☕

This argument contains IP fields common to both IPv4 and IPv6 packets. Its fields are:

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

udpsinfo_t — the connection state check 🦋

This argument contains the state of the UDP connection associated with the packet. Its fields are:

  • uintptr_t udps_addr — pointer to the struct inpcb containing the IP state for the associated socket.
  • uint16_t udps_lport — local UDP port.
  • uint16_t udps_rport — remote UDP port.
  • string udps_laddr — local IPv4 or IPv6 address.
  • string udps_raddr — remote IPv4 or IPv6 address.

udpinfo_t — the raw header, host order realness 🌈

This argument is the raw UDP header of the packet, with all fields in host order. Its fields are:

  • uint16_t udp_sport — source UDP port.
  • uint16_t udp_dport — destination UDP port.
  • uint16_t udp_length — length of the UDP header and payload, in bytes.
  • uint16_t udp_checksum — a checksum of the UDP header and payload, or 0 if no checksum was calculated.
  • struct udphdr *udp_hdr — a pointer to the raw UDP header.

🍓 FILES 🍓

  • /usr/lib/dtrace/udp.d — DTrace type and translator definitions for the udp provider. The whole vibe lives here. ✨

🔥 EXAMPLES 🔥

The following script counts transmitted packets by destination port. Slay.

udp:::send
{
        @num[args[4]->udp_dport] = count();
}

This script will print some details of each UDP packet as it is sent or received by the kernel:

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

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

udp:::send
{
        this->elapsed = (timestamp - last) / 1000;
        self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"),
             lltostr(args[4]->udp_dport));
        printf(" %10d %30s:%-5d -> %-36s %6d\n", this->elapsed,
            args[2]->ip_saddr, args[4]->udp_sport,
            self->dest, args[4]->udp_length);
        last = timestamp;
}

udp:::receive
{
        this->elapsed = (timestamp - last) / 1000;
        self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"),
             lltostr(args[4]->udp_sport));
        printf(" %10d %30s:%-5d <- %-36s %6d\n", this->elapsed,
            args[2]->ip_daddr, args[4]->udp_dport,
            self->dest, args[4]->udp_length);
        last = timestamp;
}

No notes, it's perfect. 💖

💜 COMPATIBILITY 💜

This provider is compatible with the udp provider in Solaris. We love cross-platform solidarity. 🤝

⭐ SEE ALSO ⭐

Go read them, iykyk. 📚

👑 HISTORY 👑

The udp provider first appeared in FreeBSD 10.0. A classic. 🎀

🌈 AUTHORS 🌈

This manual page was written by Mark Johnston <markj@FreeBSD.org>. Give him his flowers. 💐

And that's the whole page, bestie — written for Debian, dated August 1, 2018, under the DTRACE_UDP(4) name. Stay packet-positive! 💅✨

📦 where this page comes from