diff --git a/index.rst b/index.rst index 1735dbc..c29caff 100644 --- a/index.rst +++ b/index.rst @@ -113,6 +113,7 @@ NethSecurity administrator manual ddns smtp snmp + softflowd custom_openvpn_tunnel logs speedtest diff --git a/softflowd.rst b/softflowd.rst new file mode 100644 index 0000000..8696773 --- /dev/null +++ b/softflowd.rst @@ -0,0 +1,212 @@ +.. _softflowd-section: + +========= +Softflowd +========= + +`softflowd `_ is a software implementation of a flow-based +network traffic monitor. It listens promiscuously on a network interface, tracks active traffic +flows (communication between two IP address/port tuples), and exports them as NetFlow or IPFIX +datagrams to a remote collector. + +Common use cases include: + +- **Network traffic analysis**: identify top talkers, protocols, and bandwidth consumers. +- **Bandwidth monitoring**: feed flow data into collectors like ntopng, nfsen, or Grafana. +- **Security auditing**: detect anomalous traffic patterns and potential intrusions. +- **Capacity planning**: understand long-term traffic trends across your network. + +softflowd supports NetFlow versions 1, 5, and 9, as well as IPFIX (version 10), and is fully +IPv6 capable when using NetFlow v9 or IPFIX. + +.. note:: + + softflowd is **not installed by default** on NethSecurity. You must install it manually + before configuring it. + +Installation +------------ + +Connect to your firewall via SSH and install the package: + +.. code-block:: bash + + opkg update + opkg install softflowd + +Configuration +------------- + +The configuration is stored in ``/etc/config/softflowd``. All settings are managed via UCI. + +1. **Enable softflowd** and set the network **interface** to monitor (replace ``br-lan`` with + the interface relevant to your setup — use ``ip link show`` to list available interfaces): + +.. code-block:: bash + + uci set softflowd.@softflowd[0].enabled='1' + uci set softflowd.@softflowd[0].interface='br-lan' + +2. **Set the collector destination** using ``host:port`` format. This is the address and UDP + port of your NetFlow/IPFIX collector: + +.. code-block:: bash + + uci set softflowd.@softflowd[0].host_port='192.168.1.100:2055' + +3. **Choose the export protocol version**. The default is ``5`` (NetFlow v5). Use ``9`` + (NetFlow v9) or ``10`` (IPFIX) if you need IPv6 flow export or bidirectional mode: + +.. code-block:: bash + + uci set softflowd.@softflowd[0].export_version='9' + +4. **Set the tracking level** to control the granularity of flow records: + +.. code-block:: bash + + uci set softflowd.@softflowd[0].tracking_level='full' + +5. **Optional**: enable IPv6 flow tracking (only effective with NetFlow v9 or IPFIX): + +.. code-block:: bash + + uci set softflowd.@softflowd[0].track_ipv6='1' + +6. **Commit and start the service**: + +.. code-block:: bash + + uci commit softflowd + reload_config + /etc/init.d/softflowd enable + /etc/init.d/softflowd start + +**Complete example** — exporting NetFlow v9 data to a collector at ``192.168.1.100:2055``, +monitoring the LAN bridge interface with full flow detail and IPv6 support: + +.. code-block:: bash + + uci set softflowd.@softflowd[0].enabled='1' + uci set softflowd.@softflowd[0].interface='br-lan' + uci set softflowd.@softflowd[0].host_port='192.168.1.100:2055' + uci set softflowd.@softflowd[0].export_version='9' + uci set softflowd.@softflowd[0].tracking_level='full' + uci set softflowd.@softflowd[0].track_ipv6='1' + uci set softflowd.@softflowd[0].max_flows='8192' + uci set softflowd.@softflowd[0].sampling_rate='100' + uci commit softflowd + reload_config + /etc/init.d/softflowd enable + /etc/init.d/softflowd start + +Configuration options +--------------------- + +The following table describes all available UCI options for softflowd. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Option + - Type + - Default + - Description + * - ``enabled`` + - boolean + - ``0`` + - Enable (``1``) or disable (``0``) the softflowd service. + * - ``interface`` + - string + - ``br-lan`` + - Network interface to listen on (e.g. ``br-lan``, ``eth0``, ``pppoe-wan``). + * - ``host_port`` + - string + - *(empty)* + - Destination for flow export in ``host:port`` format (e.g. ``192.168.1.100:2055``). + Multiple destinations can be specified using commas. + If empty, softflowd runs in statistics-only mode without exporting data. + * - ``export_version`` + - integer + - ``5`` + - NetFlow export protocol version. Supported values: ``1``, ``5``, ``9``, ``10`` (IPFIX). + Use ``9`` or ``10`` for IPv6 support and more detailed records. + * - ``tracking_level`` + - string + - ``full`` + - Flow element granularity. Options: ``full`` (src/dst address, port and protocol), + ``proto`` (src/dst address and protocol), ``ip`` (src/dst address only), + ``vlan`` (full + VLAN ID), ``ether`` (full + VLAN ID and MAC addresses). + * - ``max_flows`` + - integer + - ``8192`` + - Maximum number of flows to track concurrently. When exceeded, the oldest inactive + flows are forcibly expired and exported. + * - ``sampling_rate`` + - integer + - ``100`` + - Periodical sampling rate denominator. A value of ``100`` means 1 in 100 packets + is sampled. Set to ``1`` for no sampling (capture every packet). + * - ``track_ipv6`` + - boolean + - ``0`` + - Force tracking of IPv6 flows. Only meaningful with ``export_version`` set to ``9`` + or ``10``. + * - ``bidirectional`` + - boolean + - ``0`` + - Enable bidirectional flow mode. Only works with IPFIX (``export_version='10'``). + * - ``timeout`` + - string + - *(empty)* + - Override flow expiry timeouts. Format: ``name=time`` (e.g. ``udp=1m30s``). + Valid timeout names: ``general``, ``tcp``, ``tcp.rst``, ``tcp.fin``, ``udp``, + ``maxlife``, ``expint``. + * - ``filter`` + - string + - *(empty)* + - BPF filter expression to exclude specific traffic from tracking + (e.g. ``not port 22`` to ignore SSH traffic). + * - ``hoplimit`` + - integer + - *(empty)* + - IPv4 TTL or IPv6 hop limit for exported datagrams. Useful when exporting to + multicast groups. + * - ``pid_file`` + - string + - ``/var/run/softflowd.pid`` + - Path to the PID file used when running in daemon mode. + * - ``control_socket`` + - string + - ``/var/run/softflowd.ctl`` + - Path to the control socket used by ``softflowctl``. + * - ``pcap_file`` + - string + - *(empty)* + - Path to a pcap file to read traffic from instead of a live interface. + Useful for offline analysis. + +Runtime control +--------------- + +``softflowctl`` is the companion tool for interacting with a running softflowd instance. +It communicates via the control socket (``/var/run/softflowd.ctl`` by default). + +View current flow statistics and expiry information: + +.. code-block:: bash + + softflowctl statistics + +Dump the full current flow table: + +.. code-block:: bash + + softflowctl dump-flows + +Force immediate expiry and export of all tracked flows: + +.. code-block:: bash + + softflowctl expire-all