tcpconnect for IPv4 and IPv6, and make tcpv4connect a trimmed example

README.md

@@ -59,6 +59,7 @@ Examples:
 - examples/[bitehist.py](examples/bitehist.py) examples/[bitehist.c](examples/bitehist.c): Block I/O size histogram. [Examples](examples/bitehist_example.txt).
 - examples/[disksnoop.py](examples/disksnoop.py) examples/[disksnoop.c](examples/disksnoop.c): Trace block device I/O latency. [Examples](examples/disksnoop_example.txt).
 - examples/[hello_world.py](examples/hello_world.py): Prints "Hello, World!" for new processes.
+- examples/[tcpv4connect](examples/tcpv4connect): Trace TCP IPv4 active connections. [Examples](examples/tcpv4connect_example.txt).
 - examples/[trace_fields.py](examples/trace_fields.py): Simple example of printing fields from traced events.
 - examples/[vfsreadlat.py](examples/vfsreadlat.py) examples/[vfsreadlat.c](examples/vfsreadlat.c): VFS read latency distribution. [Examples](examples/vfsreadlat_example.txt).
 
@@ -73,7 +74,7 @@ Tools:
 - tools/[pidpersec](tools/pidpersec): Count new processes (via fork). [Examples](tools/pidpersec_example.txt).
 - tools/[syncsnoop](tools/syncsnoop): Trace sync() syscall. [Examples](tools/syncsnoop_example.txt).
 - tools/[tcpaccept](tools/tcpaccept): Trace TCP passive connections (accept()). [Examples](tools/tcpaccept_example.txt).
-- tools/[tcpv4connect](tools/tcpv4connect): Trace TCP IPv4 active connections (connect()). [Examples](tools/tcpv4connect_example.txt).
+- tools/[tcpconnect](tools/tcpconnect): Trace TCP active connections (connect()). [Examples](tools/tcpconnect_example.txt).
 - tools/[vfscount](tools/vfscount) tools/[vfscount.c](tools/vfscount.c): Count VFS calls. [Examples](tools/vfscount_example.txt).
 - tools/[vfsstat](tools/vfsstat) tools/[vfsstat.c](tools/vfsstat.c): Count some VFS calls, with column output. [Examples](tools/vfsstat_example.txt).
 

tools/tcpv4connect → examples/tcpv4connect

@@ -5,31 +5,17 @@
 #
 # USAGE: tcpv4connect [-h] [-t] [-p PID]
 #
+# This is provided as a basic example of TCP connection & socket tracing.
+#
+# All IPv4 connection attempts are traced, even if they ultimately fail.
+#
 # Copyright (c) 2015 Brendan Gregg.
 # Licensed under the Apache License, Version 2.0 (the "License")
 #
-# 25-Sep-2015 Brendan Gregg Created this.
+# 15-Oct-2015 Brendan Gregg Created this.
 
 from __future__ import print_function
 from bcc import BPF
-import argparse
-
-# arguments
-examples = """examples:
- ./tcpv4connect # trace all TCP IPv4 connect()s
- ./tcpv4connect -t # include timestamps
- ./tcpv4connect -p 181 # only trace PID 181
-"""
-parser = argparse.ArgumentParser(
- description="Trace TCP IPv4 connects",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog=examples)
-parser.add_argument("-t", "--timestamp", action="store_true",
- help="include timestamp on output")
-parser.add_argument("-p", "--pid",
- help="trace this PID only")
-args = parser.parse_args()
-debug = 0
 
 # define BPF program
 bpf_text = """
@@ -42,7 +28,6 @@ BPF_HASH(currsock, u32, struct sock *);
 int kprobe__tcp_v4_connect(struct pt_regs *ctx, struct sock *sk)
 {
  u32 pid = bpf_get_current_pid_tgid();
- FILTER
 
  // stash the sock ptr for lookup on return
  currsock.update(&pid, &sk);
@@ -62,8 +47,8 @@ int kretprobe__tcp_v4_connect(struct pt_regs *ctx)
  }
 
  if (ret != 0) {
- // failed to send SYNC packet, socket __sk_common.{skc_rcv_saddr, ...}
- // may not be populated properly.
+ // failed to send SYNC packet, may not have populated
+ // socket __sk_common.{skc_rcv_saddr, ...}
  currsock.delete(&pid);
  return 0;
  }
@@ -85,26 +70,13 @@ int kretprobe__tcp_v4_connect(struct pt_regs *ctx)
 }
 """
 
-# code substitutions
-if args.pid:
- bpf_text = bpf_text.replace('FILTER',
- 'if (pid != %s) { return 0; }' % args.pid)
-else:
- bpf_text = bpf_text.replace('FILTER', '')
-if debug:
- print(bpf_text)
-
 # initialize BPF
 b = BPF(text=bpf_text)
 
 # header
-if args.timestamp:
- print("%-9s" % ("TIME(s)"), end="")
 print("%-6s %-12s %-16s %-16s %-4s" % ("PID", "COMM", "SADDR", "DADDR",
  "DPORT"))
 
-start_ts = 0
-
 def inet_ntoa(addr):
  dq = ''
  for i in range(0, 4):
@@ -119,10 +91,6 @@ while 1:
  (task, pid, cpu, flags, ts, msg) = b.trace_fields()
  (saddr_hs, daddr_hs, dport_s) = msg.split(" ")
 
- if args.timestamp:
- if start_ts == 0:
- start_ts = ts
- print("%-9.3f" % (ts - start_ts), end="")
  print("%-6d %-12.12s %-16s %-16s %-4s" % (pid, task,
  inet_ntoa(int(saddr_hs, 16)),
  inet_ntoa(int(daddr_hs, 16)),

examples/tcpv4connect_example.txt

@@ -0,0 +1,23 @@
+Demonstrations of tcpv4connect, the Linux eBPF/bcc version.
+
+
+This example traces the kernel function performing active TCP IPv4 connections
+(eg, via a connect() syscall; accept() are passive connections). Some example
+output (IP addresses changed to protect the innocent):
+
+# ./tcpv4connect 
+PID COMM SADDR DADDR DPORT
+1479 telnet 127.0.0.1 127.0.0.1 23 
+1469 curl 10.201.219.236 54.245.105.25 80 
+1469 curl 10.201.219.236 54.67.101.145 80 
+
+This output shows three connections, one from a "telnet" process and two from
+"curl". The output details shows the source address, destination address,
+and destination port. This traces attempted connections: these may have failed.
+
+The overhead of this tool should be negligible, since it is only tracing the
+kernel function performing a connect. It is not tracing every packet and then
+filtering.
+
+This is provided as a basic example of TCP tracing. See tools/tcpconnect for a
+more featured version of this example (a tool).

man/man8/tcpconnect.8

@@ -0,0 +1,87 @@
+.TH tcpconnect 8 "2015-08-25" "USER COMMANDS"
+.SH NAME
+tcpconnect \- Trace TCP active connections (connect()). Uses Linux eBPF/bcc.
+.SH SYNOPSIS
+.B tcpconnect [\-h] [\-t] [\-x] [\-p PID]
+.SH DESCRIPTION
+This tool traces active TCP connections (eg, via a connect() syscall;
+accept() are passive connections). This can be useful for general
+troubleshooting to see what connections are initiated by the local server.
+
+All connection attempts are traced, even if they ultimately fail.
+
+This works by tracing the kernel tcp_v4_connect() and tcp_v6_connect() functions
+using dynamic tracing, and will need updating to match any changes to these
+functions.
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF and bcc.
+.SH OPTIONS
+.TP
+\-h
+Print usage message.
+.TP
+\-t
+Include a timestamp column.
+.TP
+\-p PID
+Trace this process ID only (filtered in-kernel).
+.SH EXAMPLES
+.TP
+Trace all active TCP connections:
+#
+.B tcpconnect
+.TP
+Trace all TCP connects, and include timestamps:
+#
+.B tcpconnect \-t
+.TP
+Trace PID 181 only:
+#
+.B tcpconnect \-p 181
+.SH FIELDS
+.TP
+TIME(s)
+Time of the call, in seconds.
+.TP
+PID
+Process ID
+.TP
+COMM
+Process name
+.TP
+IP
+IP address family (4 or 6)
+.TP
+SADDR
+Source IP address. IPv4 as a dotted quad, IPv6 shows "..." then the last 4
+bytes (check for newer versions of this tool for the full address).
+.TP
+DADDR
+Destination IP address. IPv4 as a dotted quad, IPv6 shows "..." then the last 4
+bytes (check for newer versions of this tool for the full address).
+.TP
+DPORT
+Destination port
+.SH OVERHEAD
+This traces the kernel tcp_v[46]_connect functions and prints output for each
+event. As the rate of this is generally expected to be low (< 1000/s), the
+overhead is also expected to be negligible. If you have an application that
+is calling a high rate of connects()s, such as a proxy server, then test and
+understand this overhead before use.
+.SH SOURCE
+This is from bcc.
+.IP
+https://github.com/iovisor/bcc
+.PP
+Also look in the bcc distribution for a companion _examples.txt file containing
+example usage, output, and commentary for this tool.
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Brendan Gregg
+.SH SEE ALSO
+tcpaccept(8), funccount(8), tcpdump(8)