ct Collector

The ct collector reports information from socket buffers (struct sk_buff) about their connection tracking (conntrack) status.

Overview

The ct collector provides visibility into the Linux connection tracking subsystem, which is fundamental to stateful firewalls, NAT, and network connection management. It extracts conntrack information from packets as they flow through the networking stack.

What Data is Retrieved

The ct collector retrieves:

Connection state: ESTABLISHED, NEW, RELATED, REPLY, etc.
Connection status: Status flags from conntrack
Protocol information: TCP, UDP, ICMP with protocol-specific data
Direction: Original and reply tuple information
Zones: Conntrack zones if used
Marks and labels: Conntrack mark and label values
Parent connection: For RELATED connections (e.g., FTP data connections)

Probe Installation

The ct collector does not install any probes. It only retrieves data when a struct sk_buff * is available in probe arguments.

The collector reads the _nfct field from the socket buffer to access conntrack information.

Prerequisites

Kernel Configuration

The ct collector requires connection tracking support in the kernel:

CONFIG_NF_CONNTRACK

kernel config

required

Must be enabled (y) or available as a module (m).If built as a module, the nf_conntrack module must be loaded.

Check if conntrack is available:

# Check kernel config
grep CONFIG_NF_CONNTRACK /boot/config-$(uname -r)

# Check if module is loaded
lsmod | grep nf_conntrack

# Load module if needed
modprobe nf_conntrack

Command-Line Options

The ct collector has no specific command-line options.

Event Sections Produced

The ct collector produces the ct event section. See ct event documentation for detailed format.

Event Format

The event format includes several parts:

State Information

ct_state {state}

Where state is one of:

ESTABLISHED: Connection is established
RELATED: Related to an existing connection
NEW: New connection
REPLY: Reply direction
RELATED_REPLY: Reply to a related connection
UNTRACKED: Not tracked by conntrack

Status Information

status {status_hex}

Status flags in hexadecimal. See enum ip_conntrack_status in kernel uapi headers.

Connection Information

For TCP and UDP:

{protocol} ({TCP_state}) orig [{src_ip}.{src_port} > {dst_ip}.{dst_port}]
    reply [{src_ip}.{src_port} > {dst_ip}.{dst_port}] mark {mark} labels {labels}

For ICMP:

icmp orig [{src_ip} > {dst_ip} type {type} code {code} id {id}]
    reply [{src_ip} > {dst_ip} type {type} code {code} id {id}]

Then zone information:

orig-zone {zone_id}    # Zone in original direction
reply-zone {zone_id}   # Zone in reply direction  
zone {zone_id}         # Same zone in both directions

Finally:

mark {mark} labels {labels}

Supported Protocols

The collector supports protocol-specific data for:

IPv4/IPv6: Address information
TCP: Port numbers and TCP state (ESTABLISHED, SYN_SENT, etc.)
UDP: Port numbers
ICMP: Type, code, and identifier

Usage Examples

Basic Conntrack Monitoring

Monitor connection tracking state:

retis collect -c skb,ct

Filter by Connection State

Monitor specific connections:

# TCP traffic
retis collect -c skb,ct -f 'tcp'

# Specific host
retis collect -c skb,ct -f 'host 10.0.0.1'

# Port 443
retis collect -c skb,ct -f 'tcp port 443'

Track Connection Lifecycle

Follow a connection from start to finish:

retis collect -c skb,skb-tracking,ct -f 'tcp port 80' -o events.json
retis sort events.json

Debug NAT Issues

See how NAT affects connections:

retis collect -c skb,ct --skb-sections meta -f 'tcp'

The original and reply tuples show the NAT translation.

With Netfilter

Combine with firewall analysis:

retis collect -c skb,ct,nft --allow-system-changes -f 'tcp port 22'

Example Output

Established TCP Connection

202389123456789 [curl] 12345 [tp] net:netif_receive_skb
  if 2 (eth0) 203.0.113.10.443 > 192.168.1.100.54321 ttl 64 tos 0x0 id 12345 off 0 len 1500 proto TCP (6) flags [.]
  ct_state ESTABLISHED
  tcp (ESTABLISHED) orig [192.168.1.100.54321 > 203.0.113.10.443]
      reply [203.0.113.10.443 > 192.168.1.100.54321] zone 0 mark 0x0

This shows:

Connection is in ESTABLISHED state
TCP connection state is also ESTABLISHED
Original direction: client to server
Reply direction: server to client
No zone, mark is 0

New Connection

202389123456789 [curl] 12345 [tp] net:net_dev_start_xmit
  if 2 (eth0) 192.168.1.100.54321 > 203.0.113.10.443 ttl 64 tos 0x0 id 12345 off 0 [DF] len 60 proto TCP (6) flags [S]
  ct_state NEW
  tcp (SYN_SENT) orig [192.168.1.100.54321 > 203.0.113.10.443]
      reply [203.0.113.10.443 > 192.168.1.100.54321] zone 0 mark 0x0

This is a new connection (SYN packet).

NAT Example

202389123456789 [curl] 12345 [tp] net:net_dev_start_xmit
  if 2 (eth0) 203.0.113.50.54321 > 203.0.113.10.443 ttl 64 tos 0x0 id 12345 off 0 len 60 proto TCP (6) flags [S]
  ct_state NEW
  tcp (SYN_SENT) orig [192.168.1.100.54321 > 203.0.113.10.443]
      reply [203.0.113.10.443 > 192.168.1.100.54321] zone 0 mark 0x0

Notice:

Packet shows source IP 203.0.113.50 (after SNAT)
Conntrack original shows 192.168.1.100 (before NAT)
Reply tuple shows what the return traffic will look like

202389123456789 [ftpd] 6789 [tp] net:netif_receive_skb
  if 2 (eth0) 192.168.1.100.54322 > 203.0.113.10.20 ttl 64 tos 0x0 id 12346 off 0 len 60 proto TCP (6) flags [S]
  ct_state RELATED
  tcp (SYN_SENT) orig [192.168.1.100.54322 > 203.0.113.10.20]
      reply [203.0.113.10.20 > 192.168.1.100.54322] zone 0 mark 0x0
  \ parent [tcp (ESTABLISHED) orig [192.168.1.100.54321 > 203.0.113.10.21]
      reply [203.0.113.10.21 > 192.168.1.100.54321] zone 0 mark 0x0]

This shows an FTP data connection that’s RELATED to the control connection (parent).

Integration with Other Collectors

skb

Essential for seeing packet content:

retis collect -c skb,ct --skb-sections all

skb-tracking

Track packets through NAT:

retis collect -c skb,skb-tracking,ct -o events.json
retis sort events.json

Tracking persists across NAT transformations.

skb-drop

Debug connection tracking issues:

retis collect -c skb,ct,skb-drop

See if packets are dropped due to conntrack state.

nft (Netfilter)

See firewall and conntrack together:

retis collect -c skb,ct,nft --allow-system-changes

Shows how firewall rules interact with conntrack state.

dev

Include device information:

retis collect -c skb,ct,dev

See which interfaces connections traverse.

ns

Namespace and conntrack:

retis collect -c skb,ct,ns

Debug conntrack in containerized environments.

Use Cases

NAT Troubleshooting

retis collect -c skb,ct,skb-tracking -f 'tcp port 80' -o events.json
retis sort events.json

See original and translated addresses for connections.

Firewall State Debugging

retis collect -c skb,ct,nft --allow-system-changes

Understand how conntrack state affects firewall decisions.

Connection Tracking Issues

retis collect -c skb,ct,skb-drop

Find if packets are dropped due to invalid conntrack state.

retis collect -c skb,ct -f 'tcp'

See parent connections for RELATED traffic (like FTP data connections).

Mark-Based Routing

retis collect -c skb,ct -m 'sk_buff._nfct:0x7 == 0x2'

Filter by conntrack mark for policy routing debugging.

Understanding Conntrack Fields

Connection States

NEW: First packet of a new connection
ESTABLISHED: Connection has seen packets in both directions
RELATED: Related to an existing connection (e.g., FTP data, ICMP errors)
REPLY: Packet in the reply direction
UNTRACKED: Explicitly not tracked (raw table NOTRACK)

TCP States

Reported in parentheses for TCP:

NONE: No state yet
SYN_SENT: SYN sent
SYN_RECV: SYN received
ESTABLISHED: Connection established
FIN_WAIT: Closing
CLOSE_WAIT: Remote closed
LAST_ACK: Final ACK
TIME_WAIT: Waiting for final timeout
CLOSE: Connection closed

Zones

Zones isolate conntrack tables:

Used in virtualized environments
Same connection can exist in different zones
Zone 0 is the default

Marks

Marks are 32-bit values:

Set by firewall rules
Used for policy routing
Can be matched in filters

Labels

Labels are bit flags:

128-bit bitfield
Set by firewall rules
Shown in hexadecimal if set

Technical Details

Kernel Types

The ct collector activates when these types appear in probe arguments:

struct sk_buff *

Data Extraction

The collector:

Reads the _nfct field from struct sk_buff
Extracts the connection tracking entry
Reads protocol-specific information
Formats output based on protocol

Source Code References

Collector: retis/src/collect/collector/ct/ct.rs
eBPF hook: retis/src/collect/collector/ct/bpf/ct_hook.bpf.c
Event factory: retis/src/collect/collector/ct/bpf.rs

Best Practices

Combine with skb: See packet content and conntrack state together
Use tracking for NAT: Track packets through address translation
Filter appropriately: Focus on relevant protocols/hosts
Check prerequisites: Ensure nf_conntrack is loaded
Understand state flow: Know the connection lifecycle

Performance Considerations

No probe overhead: Doesn’t install probes
Minimal extraction: Only reads when skb has conntrack entry
Efficient parsing: Protocol-specific parsers are optimized
Works with any probe: Activates automatically when skb is available

Troubleshooting

No Conntrack Information

If conntrack information is missing:

Verify nf_conntrack is loaded: lsmod | grep nf_conntrack
Check if traffic is tracked: conntrack -L
Ensure traffic isn’t marked NOTRACK
Verify ct collector is enabled

Module Not Loaded

If Retis reports module error:

# Load the module
modprobe nf_conntrack

# Make it persistent
echo "nf_conntrack" >> /etc/modules-load.d/conntrack.conf

Incomplete Information

If some fields are missing:

Some fields are protocol-specific
UNTRACKED connections have minimal information
Check if connection is fully established

Get Started

Core Concepts

Commands

Collectors

Profiles

Advanced

Resources

​Overview

​What Data is Retrieved

​Probe Installation

​Prerequisites

​Kernel Configuration

​Command-Line Options

​Event Sections Produced

​Event Format

​State Information

​Status Information

​Connection Information

​Supported Protocols

​Usage Examples

​Basic Conntrack Monitoring

​Filter by Connection State

​Track Connection Lifecycle

​Debug NAT Issues

​With Netfilter

​Example Output

​Established TCP Connection

​New Connection

​NAT Example

​Related Connection

​Integration with Other Collectors

​skb

​skb-tracking

​skb-drop

​nft (Netfilter)

​dev

​ns

​Use Cases

​NAT Troubleshooting

​Firewall State Debugging

​Connection Tracking Issues

​Related Connection Analysis

​Mark-Based Routing

​Understanding Conntrack Fields

​Connection States

​TCP States

​Zones

​Marks

​Labels

​Technical Details

​Kernel Types

​Data Extraction

​Source Code References

​Best Practices

​Performance Considerations

​Troubleshooting

​No Conntrack Information

​Module Not Loaded

​Incomplete Information

​See Also

Build docs developers (and LLMs) love

Overview

What Data is Retrieved

Probe Installation

Prerequisites

Kernel Configuration

Command-Line Options

Event Sections Produced

Event Format

State Information

Status Information

Connection Information

Supported Protocols

Usage Examples

Basic Conntrack Monitoring

Filter by Connection State

Track Connection Lifecycle

Debug NAT Issues

With Netfilter

Example Output

Established TCP Connection

New Connection

NAT Example

Related Connection

Integration with Other Collectors

skb

skb-tracking

skb-drop

nft (Netfilter)

dev

ns

Use Cases

NAT Troubleshooting

Firewall State Debugging

Connection Tracking Issues

Related Connection Analysis

Mark-Based Routing

Understanding Conntrack Fields

Connection States

TCP States

Zones

Marks

Labels

Technical Details

Kernel Types

Data Extraction

Source Code References

Best Practices

Performance Considerations

Troubleshooting

No Conntrack Information

Module Not Loaded

Incomplete Information

See Also