Impcap: network traffic capture — rsyslog 8.2102.0 documentation

# Impcap: network traffic capture

Module Name: | impcap
Author: | Theo Bertin <theo.bertin@advens.fr>

## Purpose

Impcap is an input module based upon tcpdump’s libpcap library for network traffic capture.

Its goal is to capture network traffic with efficiency, parse network packets metadata AND data, and allow users/modules to make full use of it.

## Configuration Parameters

Note

Parameter names are case-insensitive

### Module Parameter

#### metadata_container

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | !impcap | no | none

Defines the container to place all the parsed metadata of the network packet.

Warning

if overwritten, this parameter should always begin with ‘!’ to define the JSON object accompanying messages. No checks are done to ensure that and not complying with this rule will prevent impcap/rsyslog from running, or will result in unexpected behaviours.

#### data_container

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | !data | no | none

Defines the container to place all the data of the network packet. ‘data’ here defines everything above transport layer in the OSI model, and is a string representation of the hexadecimal values of the stream.

Warning

if overwritten, this parameter should always begin with ‘!’ to define the JSON object accompanying messages. No checks are done to ensure that and not complying with this rule will prevent impcap/rsyslog from running, or will result in unexpected behaviours.

#### snap_length

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
number | 65535 | no | none

Defines the maximum size of captured packets. If captured packets are longer than the defined value, they will be capped. Default value allows any type of packet to be captured entirely but can be much shorter if only metadata capture is desired (500 to 2000 should still be safe, depending on network protocols). Be warry though, as impcap won’t be able to parse metadata correctly if the value is not high enough.

### Input Parameters

#### interface

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | no | none

This parameter specifies the network interface to listen to. If ‘interface’ is not specified, ‘file’ must be in order for the module to run.

Note

The name must be a valid network interface on the system (such as ‘lo’). see Supported interface types for an exhaustive list of all supported interface link-layer types.

#### file

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | no | none

This parameter specifies a pcap file to read. The file must respect the pcap file format specification. If ‘file’ is not specified, ‘interface’ must be in order for the module to run.

Warning

This functionality is not intended for production environnments, it is designed for development/tests.

#### promiscuous

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
boolean | off | no | none

When a valid interface is provided, sets the capture to promiscuous for this interface.

Warning

Setting your network interface to promiscuous can come against your local laws and regulations, maintainers cannot be held responsible for improper use of the module.

#### filter

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
string | none | no | none

Set a filter for the capture. Filter semantics are defined on pcap manpages.

#### tag

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | no | none

Set a tag to messages coming from this input.

#### ruleset

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | no | none

Assign messages from thi simput to a specific Rsyslog ruleset.

#### no_buffer

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
boolean | off | no | none

Disable buffering during capture. By default, impcap asks the system to bufferize packets (see parameters buffer_size, buffer_timeout and packet_count), this parameter disables buffering completely. This means packets will be handled as soon as they arrive, but impcap will make more system calls to get them and might miss some depending on the incoming rate and system performances.

#### buffer_size

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
number (octets) | 15740640 | no | none

Set a buffer size in bytes to the capture handle. This parameter is only relevant when no_buffer is not active, and should be set depending on input packet rates, buffer_timeout and packet_count values.

#### buffer_timeout

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
number (ms) | 10 | no | none

Set a timeout in milliseconds between two system calls to get bufferized packets. This parameter prevents low input rate interfaces to keep packets in buffers for too long, but does not guarantee fetch every X seconds (see pcap manpage for more details).

#### packet_count

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
number | 5 | no | none

Set a maximum number of packets to process at a time. This parameter allows to limit batch calls to a maximum of X packets at a time.

## Supported interface types

Impcap currently supports IEEE 802.3 Ethernet link-layer type interfaces. Please contact the maintainer if you need a different interface type !

See also

Help with configuring/using `Rsyslog`:

- Mailing list - best route for general questions
- GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with `Rsyslog`
- Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.
- Documentation: rsyslog-doc project README

Copyright 2008-2020 Rainer Gerhards (Großrinderfeld), and Others.