share/man/man4/dtrace_ip.4

   1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 14, 2015
  28 .Dt DTRACE_IP 4
  29 .Os
  30 .Sh NAME
  31 .Nm dtrace_ip
  32 .Nd a DTrace provider for tracing events related to the IPv4 and IPv6 protocols
  33 .Sh SYNOPSIS
  34 .Fn ip:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \
  35     "ipv4info_t *" "ipv6info_t *"
  36 .Fn ip:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \
  37     "ipv4info_t *" "ipv6info_t *"
  38 .Sh DESCRIPTION
  39 The DTrace
  40 .Nm ip
  41 provider allows users to trace events in the
  42 .Xr ip 4
  43 and
  44 .Xr ip6 4
  45 protocol implementations.
  46 The
  47 .Fn ip:::send
  48 probe fires whenever the kernel prepares to transmit an IP packet, and the
  49 .Fn ip:::receive
  50 probe fires whenever the kernel receives an IP packet.
  51 The arguments to these probes can be used to obtain detailed information about
  52 the IP headers of the corresponding packet, as well as the network interface on
  53 which the packet was sent or received.
  54 Unlike the
  55 .Xr dtrace_tcp 4
  56 and
  57 .Xr dtrace_udp 4
  58 providers,
  59 .Nm ip
  60 provider probes are triggered by forwarded packets.
  61 That is, the probes will fire on packets that are not destined to the local
  62 host.
  63 .Sh ARGUMENTS
  64 The
  65 .Vt pktinfo_t
  66 argument is currently unimplemented and is included for compatibility with other
  67 implementations of this provider.
  68 Its fields are:
  69 .Bl -tag -width "uintptr_t pkt_addr" -offset indent
  70 .It Vt uintptr_t pkt_addr
  71 Always set to 0.
  72 .El
  73 .Pp
  74 The
  75 .Vt csinfo_t
  76 argument is currently unimplemented and is included for compatibility with other
  77 implementations of this provider.
  78 Its fields are:
  79 .Bl -tag -width "uintptr_t cs_addr" -offset indent
  80 .It Vt uintptr_t cs_addr
  81 Always set to 0.
  82 .It Vt uint64_t cs_cid
  83 A pointer to the
  84 .Vt struct inpcb
  85 for this packet, or
  86 .Dv NULL .
  87 .It Vt pid_t cs_pid
  88 Always set to 0.
  89 .El
  90 .Pp
  91 The
  92 .Vt ipinfo_t
  93 argument contains IP fields common to both IPv4 and IPv6 packets.
  94 Its fields are:
  95 .Bl -tag -width "uint32_t ip_plength" -offset indent
  96 .It Vt uint8_t ip_ver
  97 IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets.
  98 .It Vt uint32_t ip_plength
  99 IP payload size.
 100 This does not include the size of the IP header or IPv6 option headers.
 101 .It Vt string ip_saddr
 102 IP source address.
 103 .It Vt string ip_daddr
 104 IP destination address.
 105 .El
 106 .Pp
 107 The
 108 .Vt ifinfo_t
 109 argument describes the outgoing and incoming interfaces for the packet in the
 110 .Fn ip:::send
 111 and
 112 .Fn ip:::receive
 113 probes respectively.
 114 Its fields are:
 115 .Bl -tag -width "uintptr_t if_addr" -offset indent
 116 .It Vt string if_name
 117 The interface name.
 118 .It Vt int8_t if_local
 119 A boolean value indicating whether or not the interface is a loopback interface.
 120 .It Vt uintptr_t if_addr
 121 A pointer to the
 122 .Vt struct ifnet
 123 which describes the interface.
 124 See the
 125 .Xr ifnet 9
 126 manual page.
 127 .El
 128 .Pp
 129 The
 130 .Vt ipv4info_t
 131 argument contains the fields of the IP header for IPv4 packets.
 132 This argument is
 133 .Dv NULL
 134 for IPv6 packets.
 135 DTrace scripts should use the
 136 .Fn ip_ver
 137 field in the
 138 .Vt ipinfo_t
 139 argument to determine whether to use this argument.
 140 Its fields are:
 141 .Bl -tag -width "uint16_t ipv4_checksum" -offset indent
 142 .It Vt uint8_t ipv4_ver
 143 IP version.
 144 This will always be 4 for IPv4 packets.
 145 .It Vt uint8_t ipv4_ihl
 146 The IP header length, including options, in 32-bit words.
 147 .It Vt uint8_t ipv4_tos
 148 IP type of service field.
 149 .It Vt uint16_t ipv4_length
 150 The total packet length, including the header, in bytes.
 151 .It Vt uint16_t ipv4_ident
 152 Identification field.
 153 .It Vt uint8_t ipv4_flags
 154 The IP flags.
 155 .It Vt uint16_t ipv4_offset
 156 The fragment offset of the packet.
 157 .It Vt uint8_t ipv4_ttl
 158 Time to live field.
 159 .It Vt uint8_t ipv4_protocol
 160 Next-level protocol ID.
 161 .It Vt string ipv4_protostr
 162 A string containing the name of the encapsulated protocol.
 163 The protocol strings are defined in the
 164 .Va protocol
 165 array in
 166 .Pa /usr/lib/dtrace/ip.d
 167 .It Vt uint16_t ipv4_checksum
 168 The IP checksum.
 169 .It Vt ipaddr_t ipv4_src
 170 IPv4 source address.
 171 .It Vt ipaddr_t ipv4_dst
 172 IPv4 destination address.
 173 .It Vt string ipv4_saddr
 174 A string representation of the source address.
 175 .It Vt string ipv4_daddr
 176 A string representation of the destination address.
 177 .It Vt ipha_t *ipv4_hdr
 178 A pointer to the raw IPv4 header.
 179 .El
 180 .Pp
 181 The
 182 .Vt ipv6info_t
 183 argument contains the fields of the IP header for IPv6 packets.
 184 Its fields are not set for IPv4 packets; as with the
 185 .Vt ipv4info_t
 186 argument, the
 187 .Fn ip_ver
 188 field should be used to determine whether this argument is valid.
 189 Its fields are:
 190 .Bl -tag -width "uint16_t ipv4_checksum" -offset indent
 191 .It Vt uint8_t ipv6_ver
 192 IP version.
 193 This will always be 6 for IPv6 packets.
 194 .It Vt uint8_t ipv6_tclass
 195 The traffic class, used to set the differentiated services codepoint and
 196 extended congestion notification flags.
 197 .It Vt uint32_t ipv6_flow
 198 The flow label of the packet.
 199 .It Vt uint16_t ipv6_plen
 200 The IP payload size, including extension headers, in bytes.
 201 .It Vt uint8_t ipv6_nexthdr
 202 An identifier for the type of the next header.
 203 .It Vt string ipv6_nextstr
 204 A string representation of the type of the next header.
 205 .It Vt uint8_t ipv6_hlim
 206 The hop limit.
 207 .It Vt ip6_addr_t *ipv6_src
 208 IPv6 source address.
 209 .It Vt ip6_addr_t *ipv6_dst
 210 IPv6 destination address.
 211 .It Vt string ipv6_saddr
 212 A string representation of the source address.
 213 .It Vt string ipv6_daddr
 214 A string representation of the destination address.
 215 .It Vt struct ip6_hdr *ipv6_hdr
 216 A pointer to the raw IPv6 header.
 217 .El
 218 .Sh FILES
 219 .Bl -tag -width "/usr/lib/dtrace/ip.d" -compact
 220 .It Pa /usr/lib/dtrace/ip.d
 221 DTrace type and translator definitions for the
 222 .Nm ip
 223 provider.
 224 .El
 225 .Sh EXAMPLES
 226 The following script counts received packets by remote host address.
 227 .Bd -literal -offset indent
 228 ip:::receive
 229 {
 230         @num[args[2]->ip_saddr] = count();
 231 }
 232 .Ed
 233 .Pp
 234 This script will print some details of each IP packet as it is sent or received
 235 by the kernel:
 236 .Bd -literal -offset indent
 237 #pragma D option quiet
 238 #pragma D option switchrate=10Hz
 239
 240 dtrace:::BEGIN
 241 {
 242         printf(" %10s %30s    %-30s %8s %6s\\n", "DELTA(us)", "SOURCE",
 243             "DEST", "INT", "BYTES");
 244         last = timestamp;
 245 }
 246
 247 ip:::send
 248 {
 249         this->elapsed = (timestamp - last) / 1000;
 250         printf(" %10d %30s -> %-30s %8s %6d\\n", this->elapsed,
 251             args[2]->ip_saddr, args[2]->ip_daddr, args[3]->if_name,
 252             args[2]->ip_plength);
 253         last = timestamp;
 254 }
 255
 256 ip:::receive
 257 {
 258         this->elapsed = (timestamp - last) / 1000;
 259         printf(" %10d %30s <- %-30s %8s %6d\\n", this->elapsed,
 260             args[2]->ip_daddr, args[2]->ip_saddr, args[3]->if_name,
 261             args[2]->ip_plength);
 262         last = timestamp;
 263 }
 264 .Ed
 265 .Sh COMPATIBILITY
 266 This provider is compatible with the
 267 .Nm ip
 268 providers found in Solaris and Darwin.
 269 .Sh SEE ALSO
 270 .Xr dtrace 1 ,
 271 .Xr dtrace_tcp 4 ,
 272 .Xr dtrace_udp 4 ,
 273 .Xr ip 4 ,
 274 .Xr ip6 4 ,
 275 .Xr ifnet 9 ,
 276 .Xr SDT 9
 277 .Sh HISTORY
 278 The
 279 .Nm ip
 280 provider first appeared in
 281 .Fx
 282 10.0.
 283 .Sh AUTHORS
 284 This manual page was written by
 285 .An Mark Johnston Aq Mt markj@FreeBSD.org .