Merge pull request #460 from retis-org/at/release-v1.5

Release v1.5

Author: vlrpl

AUTHORS.md

@@ -10,4 +10,5 @@ In alphabetical order:
 - Hangbin Liu
 - Paolo Valerio
 - Sundaram Krishnan
+- Timothy Redaelli
 - Viktor Oreshkin

Cargo.lock

@@ -1,191 +1,130 @@
 # Retis
 
-Tracing packets in the [Linux](https://kernel.org) networking stack, using
-[eBPF](https://ebpf.io) and interfacing with control and data paths such as
-[OvS](https://www.openvswitch.org) or [Netfilter](https://netfilter.org).
+Tracing (filtered) packets in the [Linux](https://kernel.org) networking stack,
+using [eBPF](https://ebpf.io) probes and interfacing with control and data paths
+such as [OvS](https://www.openvswitch.org) or [Netfilter](https://netfilter.org).
 
 Visit the [online documentation](https://retis.readthedocs.io) for more
-details.
-
+details, or run `retis --help` and `retis <command> --help`.
 
 ![demo](demo.gif)
 
-## Quick start
-An overview and some examples can be found in the
-[Documentation](https://retis.readthedocs.io), but note the `--help` flag
-should document most of what Retis can do.
-
-```
-$ retis --help
-...
-$ retis <command> --help
-...
-```
+## Installation
 
-## Examples
+Retis can be used as a container image, installed on supported distributions or
+built from sources. All details on the [official
+documentation](https://retis.readthedocs.io/en/stable/install/).
 
-### Drop monitoring
-Listing packets being dropped by the kernel with an associated stack trace and drop reason
-```
-$ retis -p dropmon collect
-4 probe(s) loaded
-
-3392678938917 [nc] 2311 [tp] skb:kfree_skb drop (NO_SOCKET)
-    bpf_prog_3a0ef5414c2f6fca_sd_devices+0xa0ad
-    bpf_prog_3a0ef5414c2f6fca_sd_devices+0xa0ad
-    bpf_trace_run3+0x52
-    kfree_skb_reason+0x8f
-    tcp_v6_rcv+0x77
-    ip6_protocol_deliver_rcu+0x6b
-    ip6_input_finish+0x43
-    __netif_receive_skb_one_core+0x62
-    process_backlog+0x85
-    __napi_poll+0x28
-    net_rx_action+0x2a4
-    __do_softirq+0xd1
-    do_softirq.part.0+0x5f
-    __local_bh_enable_ip+0x68
-    __dev_queue_xmit+0x293
-    ip6_finish_output2+0x2a3
-    ip6_finish_output+0x160
-    ip6_xmit+0x2c0
-    inet6_csk_xmit+0xe9
-    __tcp_transmit_skb+0x534
-    tcp_connect+0xaf6
-    tcp_v6_connect+0x515
-    __inet_stream_connect+0x103
-    inet_stream_connect+0x3a
-    __sys_connect+0xa8
-    __x64_sys_connect+0x18
-    do_syscall_64+0x5d
-    entry_SYSCALL_64_after_hwframe+0x72
-  if 1 (lo) rxif 1 ::1.60634 > ::1.80 ttl 64 label 0x9c404 len 40 proto TCP (6) flags [S] seq 3918324244 win 65476
-...
-```
+## Use cases
 
-### Monitoring packets dropped by netfilter
-The exact nft rule can be retrieved using `nft -a list table ...`.
+Retis aims at providing better visibility on complex single-host topologies and
+linking useful context. It it designed to be modular in terms of what kind of
+data is retrieved and where it is retrieved from. Retis can be used for
+debugging networking issues, exploring the Linux networking stack or for testing
+features (eg. in a CI script).
 
-```
-$ retis -p nft-dropmon collect --allow-system-changes
-4 probe(s) loaded
-
-3443313082998 [swapper/0] 0 [k] __nft_trace_packet
-    __nft_trace_packet+0x1
-    nft_do_chain+0x3ef
-    nft_do_chain_inet+0x54
-    nf_hook_slow+0x42
-    ip_local_deliver+0xd0
-    ip_sublist_rcv_finish+0x7e
-    ip_sublist_rcv+0x186
-    ip_list_rcv+0x13d
-    __netif_receive_skb_list_core+0x29d
-    netif_receive_skb_list_internal+0x1d1
-    napi_complete_done+0x72
-    virtnet_poll+0x3ce
-    __napi_poll+0x28
-    net_rx_action+0x2a4
-    __do_softirq+0xd1
-    __irq_exit_rcu+0xbe
-    common_interrupt+0x86
-    asm_common_interrupt+0x26
-    pv_native_safe_halt+0xf
-    default_idle+0x9
-    default_idle_call+0x2c
-    do_idle+0x226
-    cpu_startup_entry+0x1d
-    __pfx_kernel_init+0x0
-    arch_call_rest_init+0xe
-    start_kernel+0x71e
-    x86_64_start_reservations+0x18
-    x86_64_start_kernel+0x96
-    __pfx_verify_cpu+0x0
-  if 2 (eth0) rxif 2 172.16.42.1.52294 > 172.16.42.2.8080 ttl 64 tos 0x0 id 37968 off 0 [DF] len 60 proto TCP (6) flags [S] seq 1971640626 win 64240
-  table firewalld (1) chain filter_IN_FedoraServer (202) handle 215 drop
-...
-$ nft -a list table inet firewalld
-...
-	chain filter_IN_FedoraServer { # handle 202
-...
-		jump filter_INPUT_POLICIES_post # handle 214
-		meta l4proto { icmp, ipv6-icmp } accept # handle 273
-		reject with icmpx admin-prohibited # handle 215         <- This one
-	}
-...
-```
+A few key points:
 
-## Installation
+- Operates on "skb-enabled" functions and tracepoints.
+- Offers filtering and tracking (the same packet can be seen multiple times,
+  modified, etc) capabilities.
+- Can retrieve more than the packet itself: additional metadata and contextual
+  information.
+- Does not require compilation on the target.
+- Has post-processing abilities (eg. reconstructing a packet journey).
+- Tries to have sane defaults.
 
-Retis can be installed from [COPR](https://copr.fedorainfracloud.org/coprs/g/retis/retis/)
-for rpm-compatible distributions, from a container image or from sources.
+Collecting packet events going in and out network devices (similarly to
+well-known `AF_PACKET` existing utilities) can be as simple as:
 
-### COPR
+```
+$ retis collect -p net:netif_receive_skb -p net:net_dev_start_xmit
+Collector(s) started: nft, skb, ct, skb-tracking, skb-drop
+7 probe(s) loaded
 
-RPM packages for Fedora (currently supported releases including Rawhide), RHEL (>=
-8) and EPEL (>= 8) are available.
+6034438235097 (9) [ping] 22026 [tp] net:net_dev_start_xmit #57d008c23d9ffff93bc8e6a6580 (skb ffff93bc8fe2f700)
+  if 4 (wlp82s0) [redacted] > 2606:4700:4700::1111 ttl 64 label 0x87f1c len 64 proto ICMPv6 (58) type 128 code 0
 
-```
-$ dnf -y copr enable @retis/retis
-$ dnf -y install retis
-$ retis --help
+6034449727598 (5) [irq/185-iwlwifi] 1359 [tp] net:netif_receive_skb #57d013b806effff93bc8b645180 (skb ffff93bc81f0d300)
+  if 4 (wlp82s0) 2606:4700:4700::1111 > [redacted] ttl 54 label 0x9f52e len 64 proto ICMPv6 (58) type 129 code 0
 ```
 
-Or on older distributions,
+The output is described in the [official
+documentation](https://retis.readthedocs.io/en/stable/). The above example is
+similar to running the [ifdump](https://retis.readthedocs.io/en/stable/profiles/#ifdump)
+profile (`retis -p ifdump c`).
+
+More advanced collections can be performed by providing more probes and by
+adding filtering rules. For example one can use the [generic
+profile](retis/profiles/generic.yaml) which defines a bigger set of probes.
 
 ```
-$ yum -y copr enable @retis/retis
-$ yum -y install retis
-$ retis --help
-```
+$ retis -p generic collect -f 'udp port 53 and host 2606:4700:4700::1111'
+L2+L3 packet filter(s) loaded
+29 probe(s) loaded
 
-### Container image
+6464781565852 (10) [isc-net-0000] 22818/22819 [k] ip6_output #5e133023f9cffff93bc85f28a00 (skb ffff93bc8148b000)
+  [redacted].60578 > 2606:4700:4700::1111.53 ttl 64 label 0x116de len 59 proto UDP (17) len 51
 
-The preferred method to run Retis in a container is by using the provided
-[retis_in_container.sh](tools/retis_in_container.sh) script,
+6464781577262 (10) [isc-net-0000] 22818/22819 [tp] net:net_dev_queue #5e133023f9cffff93bc85f28a00 (skb ffff93bc8148b000)
+  if 4 (wlp82s0) [redacted].60578 > 2606:4700:4700::1111.53 ttl 64 label 0x116de len 59 proto UDP (17) len 51
 
-```
-$ curl -O https://raw.githubusercontent.com/retis-org/retis/main/tools/retis_in_container.sh
-$ chmod +x retis_in_container.sh
-$ ./retis_in_container.sh --help
-```
+6464781579859 (10) [isc-net-0000] 22818/22819 [tp] net:net_dev_start_xmit #5e133023f9cffff93bc85f28a00 (skb ffff93bc8148b000)
+  if 4 (wlp82s0) [redacted].60578 > 2606:4700:4700::1111.53 ttl 64 label 0x116de len 59 proto UDP (17) len 51
 
-### From sources
-For details on how to build retis, visit the
-[documentation](https://retis.readthedocs.io/en/stable/install/).
+6464794631087 (11) [irq/191-iwlwifi] 1365 [tp] net:napi_gro_receive_entry #5e133c99bafffff93bc89dd4000 (skb ffff93bfd77f9f00)
+  if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].60578 ttl 54 label 0xfacb2 len 79 proto UDP (17) len 71
 
-## Limitations
+6464794636532 (11) [irq/191-iwlwifi] 1365 [k] udp6_gro_receive #5e133c99bafffff93bc89dd4000 (skb ffff93bfd77f9f00)
+  if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].60578 ttl 54 label 0xfacb2 len 79 proto UDP (17) len 71
 
-Known and current limitations:
+6464794638402 (11) [irq/191-iwlwifi] 1365 [k] udp_gro_receive #5e133c99bafffff93bc89dd4000 (skb ffff93bfd77f9f00)
+  if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].60578 ttl 54 label 0xfacb2 len 79 proto UDP (17) len 71
 
-- By default Retis does not modify the system (e.g. load kernel modules, change
-  the configuration, add a firewalling rule). This is done on purpose but might
-  mean some prerequisites will be missing if not added manually. The only
-  example for now is the `nft` module that requires a specific nft rule to be
-  inserted. If that rule is not there, no nft event will be reported. To allow
-  Retis to modify the system, use the `--allow-system-changes` option when
-  running the `collect` command. See `retis collect --help` for further details
-  about changes applied to the system.
+6464794640624 (11) [irq/191-iwlwifi] 1365 [tp] net:netif_receive_skb #5e133c99bafffff93bc89dd4000 (skb ffff93bfd77f9f00)
+  if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].60578 ttl 54 label 0xfacb2 len 79 proto UDP (17) len 71
 
-- Retis operates mainly on `struct sk_buff` objects meaning a good part of
-  locally generated traffic can't be traced at the moment. E.g. locally
-  generated traffic from a container can be traced when it exits the container.
+6464794657429 (11) [irq/191-iwlwifi] 1365 [k] udpv6_rcv #5e133c99bafffff93bc89dd4000 (skb ffff93bfd77f9f00)
+  if 4 (wlp82s0) rxif 4 2606:4700:4700::1111.53 > [redacted].60578 ttl 54 label 0xfacb2 len 79 proto UDP (17) len 71
+```
 
-- Profiles combination might fail if flags are used multiple times or if some
-  arguments are incompatible. Use with care.
+When storing events for later post-processing, the packets' journeys can be
+reconstructed:
 
-Additional notes (not strictly limitations):
+```
+$ retis -p generic collect -f 'udp port 53 and host 2606:4700:4700::1111' -o \
+      --cmd 'dig redhat.com @2606:4700:4700::1111'
+$ retis sort
+6946866196800 (11) [isc-net-0000] 23898/23899 [k] ip6_output #651717df140ffff93bc89dd7c00 (skb ffff93bc8c491500) n 0
+  [redacted].54205 > 2606:4700:4700::1111.53 ttl 64 label 0x86973 len 59 proto UDP (17) len 51
+  ↳ 6946866208851 (11) [isc-net-0000] 23898/23899 [tp] net:net_dev_queue #651717df140ffff93bc89dd7c00 (skb ffff93bc8c491500) n 1
+      if 4 (wlp82s0) [redacted].54205 > 2606:4700:4700::1111.53 ttl 64 label 0x86973 len 59 proto UDP (17) len 51
+  ↳ 6946866211760 (11) [isc-net-0000] 23898/23899 [tp] net:net_dev_start_xmit #651717df140ffff93bc89dd7c00 (skb ffff93bc8c491500) n 2
+      if 4 (wlp82s0) [redacted].54205 > 2606:4700:4700::1111.53 ttl 64 label 0x86973 len 59 proto UDP (17) len 51
+
+6946876837639 (7) [irq/187-iwlwifi] 1361 [tp] net:napi_gro_receive_entry #65172204f07ffff93bc93bf6580 (skb ffff93c01ebd8f00) n 0
+  if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].54205 ttl 54 label 0x7ff08 len 79 proto UDP (17) len 71
+  ↳ 6946876842090 (7) [irq/187-iwlwifi] 1361 [k] udp6_gro_receive #65172204f07ffff93bc93bf6580 (skb ffff93c01ebd8f00) n 1
+      if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].54205 ttl 54 label 0x7ff08 len 79 proto UDP (17) len 71
+  ↳ 6946876843587 (7) [irq/187-iwlwifi] 1361 [k] udp_gro_receive #65172204f07ffff93bc93bf6580 (skb ffff93c01ebd8f00) n 2
+      if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].54205 ttl 54 label 0x7ff08 len 79 proto UDP (17) len 71
+  ↳ 6946876845210 (7) [irq/187-iwlwifi] 1361 [tp] net:netif_receive_skb #65172204f07ffff93bc93bf6580 (skb ffff93c01ebd8f00) n 3
+      if 4 (wlp82s0) 2606:4700:4700::1111.53 > [redacted].54205 ttl 54 label 0x7ff08 len 79 proto UDP (17) len 71
+  ↳ 6946876855603 (7) [irq/187-iwlwifi] 1361 [k] udpv6_rcv #65172204f07ffff93bc93bf6580 (skb ffff93c01ebd8f00) n 4
+      if 4 (wlp82s0) rxif 4 2606:4700:4700::1111.53 > [redacted].54205 ttl 54 label 0x7ff08 len 79 proto UDP (17) len 71
+```
 
-- Filtering & tracking packets being modified can only work if the packet is at
-  least seen once in a form where it can be matched against the filter. E.g.
-  tracking SNATed packets only in `skb:consume_skb` with a filter on the
-  original address won't generate any event.
+Retis offers many more features including retrieving [conntrack
+information](https://retis.readthedocs.io/en/stable/modules/ct/), [advanced
+filtering](https://retis.readthedocs.io/en/stable/filtering/), [monitoring
+dropped packets](https://retis.readthedocs.io/en/stable/profiles/#dropmon) and
+[dropped packets from Netfilter](https://retis.readthedocs.io/en/stable/profiles/#nft-dropmon),
+generating `pcap` files from the collected packets, allowing [writing
+post-processing scripts in Python](https://retis.readthedocs.io/en/stable/python/)
+and more.
 
-- As explained in the [filtering section](https://retis.readthedocs.io/en/stable/#filtering)
-  filters are eventually translated to eBPF instructions. Currently, the maximum
-  size of an eBPF filter is 4096 instructions.
+## Contributing
 
-- Some fields present in the packet might not be reported when probes are early
-  in the stack, while being shown in later ones. This is because Retis probes
-  rely on the networking stack knowledge of the packet and if some parts weren't
-  processed yet they can't be reported. E.g. TCP ports won't be reported from
-  `kprobe:ip_rcv`.
+Retis is under [GPL v2](retis/LICENSE) and welcomes contributions. See our
+[contributing guide](https://retis.readthedocs.io/en/stable/CONTRIBUTING/) for
+more details.

README.md

@@ -5,8 +5,9 @@
    1. Make sure the README is up-to-date (collectors, build instructions, etc).
    1. Add new authors to the authors file if needed, by running
       `./tools/authors.sh` and committing the changes.
-   1. Update the version in `Cargo.toml`, retis-events/Cargo.toml and
-      retis-derive/Cargo.toml.
+   1. Update the version in `retis/Cargo.toml`, `retis-events/Cargo.toml` and
+      `retis-derive/Cargo.toml`.
+   1. Update the release name in `retis/Cargo.toml`.
    1. Open a PR and get it merged. This must have runtime tests enabled!
    1. Tag the right commit in the `vx.y.z` form and push it.
 1. Release binaries.

RELEASE.md

@@ -1,20 +1,8 @@
-# Event sections
+# Core events
 
-When an event is printed the exact form can vary depending on what data was
-retrieved and collected. This depends on the data itself (which kind of packet
-or metadata was retrieved) but also on the collection configuration (which
-collectors are enabled, which options are set).
-
-An event is always composed of a common section (containing a timestamp) and a
-set of optional other sections. Those sections data can come from the eBPF
-probes or from Retis directly. Sections are grouped in an event if they share a
-common property (eg. they are all linked to a given packet + probe).
-
-```none
-<common> <kernel or userspace> <tracking> <drop> <stack trace> <...>
-```
-
-The `collector` sections are described in the collector specific pages.
+Some data is collected or generated directly by the core logic in Retis and not
+by optional collectors. Those sections are quite generic and can't be enabled
+nor disabled.
 
 ## Common section
 

demo.gif

@@ -0,0 +1,29 @@
+# Collectors
+
+Collectors are optional data retrievers and event section producers used in the
+collection mode (the `collect` sub-command). They are responsible of handling
+specific data (eg. `skb`) or logical parts of the stack (eg. `ct`).
+
+They can be enabled explicitly using the `--collectors` argument or
+automatically started when that argument is not given. When started
+automatically collectors check for prerequisites and can opt-out of the
+collection (eg. the `ovs` collector won't run if OpenvSwitch is not used on the
+target machine).
+
+# Event sections
+
+When an event is printed the exact form can vary depending on what data was
+retrieved and collected. This depends on the data itself (which kind of packet
+or metadata was retrieved) but also on the collection configuration (which
+collectors are enabled, which options are set).
+
+An event is always composed of a common section (containing a timestamp) and a
+set of optional other sections. Those sections data can come from the eBPF
+probes or from Retis directly. Sections are grouped in an event if they share a
+common property (eg. they are all linked to a given packet + probe).
+
+```none
+<common> <kernel or userspace> <tracking> <drop> <stack trace> <...>
+```
+
+Each collector has a documentation page describing it and its event section.