From 9f1986a7dea0f8acd1ba3ba415070f5ef6aadac9 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Wed, 9 Sep 2026 14:36:58 +0200 Subject: docs: Update Flow accounting page to VyOS 1.5 standards (#2236) * docs: Update Flow accounting page to VyOS 1.5 standards * Minor corrections * Minor corrections * Update flow-accounting.md * Apply batched suggestions from code review docs: Applied review suggestions to the Flow accounting page Co-authored-by: Daniil Baturin * Remove the passage about address family match requirements --------- Co-authored-by: Daniil Baturin --- docs/configuration/system/flow-accounting.md | 345 +++++++++++++++++---------- 1 file changed, 215 insertions(+), 130 deletions(-) (limited to 'docs') diff --git a/docs/configuration/system/flow-accounting.md b/docs/configuration/system/flow-accounting.md index c97d5473..bc1ecd57 100644 --- a/docs/configuration/system/flow-accounting.md +++ b/docs/configuration/system/flow-accounting.md @@ -1,209 +1,294 @@ +--- +myst: + html_meta: + description: | + VyOS can group IPv4 and IPv6 traffic into flows and export a record + of each flow to one or more external collectors, using the NetFlow or + IPFIX protocol. + keywords: flow-accounting, netflow, ipfix, exporter, collector +--- + (flow-accounting)= -# Flow Accounting +# Flow accounting -VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts -as a flow exporter, and you are free to use it with any compatible collector. +A flow is a stream of packets that share key header fields, such as source and +destination IP addresses, ports, and protocol. -Flows can be exported via protocol NetFlow (versions 5, 9 and -10/IPFIX). Additionally, you may save flows to an in-memory table -internally in a router. +Flow accounting groups IPv4 and IPv6 traffic into flows and records how many +packets and bytes each flow carries. These records are then exported to one or +more external collectors, using the {abbr}`NetFlow (Cisco NetFlow)` or +{abbr}`IPFIX (IP Flow Information Export)` protocol. -:::{warning} -You need to disable the in-memory table in production environments! -Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and -unstable flow-accounting behavior. -::: +Flow accounting is applied per interface. By default, only traffic entering an +interface (ingress) is accounted for. Traffic leaving an interface (egress) is +added with `enable-egress`. -## NetFlow / IPFIX +The router also supports sFlow, a separate monitoring protocol. Instead of +grouping packets into flows, sFlow sends packet samples taken at a configurable +rate to a collector (see {ref}`sflow`). -NetFlow is a feature that was introduced on Cisco routers around 1996 that -provides the ability to collect IP network traffic as it enters or exits an -interface. By analyzing the data provided by NetFlow, a network administrator -can determine things such as the source and destination of traffic, class of -service, and the causes of congestion. A typical flow monitoring setup (using -NetFlow) consists of three main components: +## Configuration -- **exporter**: aggregates packets into flows and exports flow records towards - one or more flow collectors -- **collector**: responsible for reception, storage and pre-processing of flow - data received from a flow exporter -- **application**: analyzes received flow data in the context of intrusion - detection or traffic profiling, for example +### Monitored interfaces -For connectionless protocols as like ICMP and UDP, a flow is considered -complete once no more packets for this flow appear after configurable timeout. +```{cfgcmd} set system flow-accounting netflow interface \ -NetFlow is usually enabled on a per-interface basis to limit load on the router -components involved in NetFlow, or to limit the amount of NetFlow records -exported. +**Enable flow accounting on the specified interface.** -## Configuration +Repeat the command to enable flow accounting on multiple interfaces. -:::{warning} -Using NetFlow on routers with high traffic levels may lead to -high CPU usage and may affect the router's performance. In such cases, -consider using sFlow instead. -::: +Enable flow accounting on at least one interface. Otherwise, the commit fails. +``` -In order for flow accounting information to be collected and displayed for an -interface, the interface must be configured for flow accounting. +Example: -```{cfgcmd} set system flow-accounting interface \ +```none +set system flow-accounting netflow interface eth0 +``` + +```{cfgcmd} set system flow-accounting enable-egress + +**Enable flow accounting for traffic leaving the monitored interfaces.** + +By default, only traffic entering the interfaces is accounted for. +``` -Configure and enable collection of flow information for the interface -identified by \. +Example: -You can configure multiple interfaces which would participate in flow -accounting. +```none +set system flow-accounting enable-egress ``` -:::{note} -Will be recorded only packets/flows on **incoming** direction in -configured interfaces by default. -::: +### Flow export + +```{cfgcmd} set system flow-accounting netflow server \ + +**Configure the address of a collector that receives the exported records.** -By default, recorded flows will be saved internally and can be listed with the -CLI command. You may disable using the local in-memory table with the command: +Accepts an IPv4 or IPv6 address. -```{cfgcmd} set system flow-accounting disable-imt +Repeat the command to export records to multiple collectors. -If you need to sample also egress traffic, you may want to -configure egress flow-accounting: +At least one collector must be configured. Otherwise, the commit fails. ``` -```{cfgcmd} set system flow-accounting enable-egress +Example: -Internally, in flow-accounting processes exist a buffer for data exchanging -between core process and plugins (each export target is a separated plugin). -If you have high traffic levels or noted some problems with missed records -or stopping exporting, you may try to increase a default buffer size (10 -MiB) with the next command: +```none +set system flow-accounting netflow server 192.0.2.10 +set system flow-accounting netflow server 2001:db8::10 ``` -```{cfgcmd} set system flow-accounting buffer-size \ +```{cfgcmd} set system flow-accounting netflow server \ port \<1025-65535\> -In case, if you need to catch some logs from flow-accounting daemon, you may -configure logging facility: +**Configure the destination port on the collector.** + +The default is 2055. ``` -```{cfgcmd} set system flow-accounting syslog-facility \ +Example: -Set the syslog facility for flow-accounting log messages. Supported values -include ``daemon``, ``local0`` through ``local7``, and other standard syslog -facilities. +```none +set system flow-accounting netflow server 192.0.2.10 port 4739 ``` +```{cfgcmd} set system flow-accounting netflow server \ source-address \ -### Flow Export +**Configure the source address the router uses to reach the collector.** -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. +The address must already be assigned to a local interface. If flow accounting +is bound to a VRF, the address must be assigned within that VRF. -#### NetFlow -```{cfgcmd} set system flow-accounting netflow version \ +Set either `source-address` or `source-interface` for a collector, not both. +Configuring both for the same collector fails the commit. +``` -There are multiple versions available for the NetFlow data. The \ -used in the exported flow data can be configured here. The following -versions are supported: -* **5** - Most common version, but restricted to IPv4 flows only -* **9** - NetFlow version 9 (default) -* **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917` +Example: + +```none +set system flow-accounting netflow server 192.0.2.10 source-address 192.0.2.1 ``` -```{cfgcmd} set system flow-accounting netflow server \ +```{cfgcmd} set system flow-accounting netflow server \ source-interface \ + +**Configure the interface the router uses to reach the collector.** + +When flow accounting is bound to a VRF, the interface must belong to that VRF. -Configure address of NetFlow collector. NetFlow server at \ can -be both listening on an IPv4 or IPv6 address. +Set either source-address or source-interface for a collector, not both. +Configuring both for the same collector fails the commit. ``` -```{cfgcmd} set system flow-accounting netflow source-ip \ +Example: -IPv4 or IPv6 source address of NetFlow packets +```none +set system flow-accounting netflow server 192.0.2.10 source-interface eth0 +``` + +```{cfgcmd} set system flow-accounting netflow version \<5 | 9 | 10\> + +**Configure the export protocol version.** + +Version 5 exports IPv4 flows only. Version 9 and version 10 (IPFIX) also +export IPv6 flows. + +The default is 9. +``` + +Example: + +```none +set system flow-accounting netflow version 10 ``` ```{cfgcmd} set system flow-accounting netflow engine-id \ -NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. +**Configure the identifier the router places in the exported records to +distinguish this exporter's flow streams.** + +For version 5, use two values in the form `<0-255>:<0-255>`. For versions 9 +and 10, use a single value from 0 to 4294967295. + +The value must be valid for the configured version. Otherwise, the commit +fails. +``` + +Example: + +```none +set system flow-accounting netflow engine-id 100 ``` -```{cfgcmd} set system flow-accounting netflow sampling-rate \ +```{cfgcmd} set system flow-accounting netflow sampling-rate \<0-4294967295\> + +**Export one flow in every N instead of every flow.** -Use this command to configure the sampling rate for flow accounting. The -system samples one in every \ packets, where \ is the value -configured for the sampling-rate option. The advantage of sampling every n -packets, where n > 1, allows you to decrease the amount of processing -resources required for flow accounting. The disadvantage of not sampling -every packet is that the statistics produced are estimates of actual data -flows. +Flows are selected at random. Each exported flow carries the full packet and +byte counts collected for it. Sampling reduces the number of flows sent to +collectors. The router reports `N` to collectors so they can estimate the +total. -Per default every packet is sampled (that is, the sampling rate is 1). +By default, no sampling is applied, and every flow is exported. ``` -```{cfgcmd} set system flow-accounting netflow timeout expiry-interval \ +Example: -Specifies the interval at which Netflow data will be sent to a collector. As -per default, Netflow data will be sent every 60 seconds. +```none +set system flow-accounting netflow sampling-rate 1000 +``` + +```{cfgcmd} set system flow-accounting netflow max-flows \<0-4294967295\> -You may also additionally configure timeouts for different types of -connections. +**Configure the maximum number of flows accounted for at the same time.** + +By default, no explicit maximum is set. ``` -```{cfgcmd} set system flow-accounting netflow max-flows \ +Example: -If you want to change the maximum number of flows, which are tracking -simultaneously, you may do this with this command (default 8192). +```none +set system flow-accounting netflow max-flows 2000000 ``` +```{cfgcmd} set system flow-accounting netflow inactive-timeout \<0-2147483647\> -### Example: +**Configure the number of seconds without new packets after which a flow is +considered finished and exported.** -NetFlow v5 example: +The default is 15. +``` + +Example: ```none -set system flow-accounting netflow engine-id 100 -set system flow-accounting netflow version 5 -set system flow-accounting netflow server 192.168.2.10 port 2055 +set system flow-accounting netflow inactive-timeout 15 +``` + +```{cfgcmd} set system flow-accounting netflow active-timeout \<0-2147483647\> + +**Configure the maximum number of seconds an active flow is accounted for +before it is exported.** + +A flow still receiving packets is exported once this time is reached. + +The default is 1800. +``` + +Example: + +```none +set system flow-accounting netflow active-timeout 1800 +``` + +```{cfgcmd} set system flow-accounting vrf \ + +**Export flow records within the specified +{abbr}`VRF (Virtual Routing and Forwarding)` instance.** + +The router reaches collectors through that VRF. + +A collector configured with `source-interface` is reached through that +interface, not through the VRF. + +The VRF must already be configured with `set vrf name `. ``` +Example: + +```none +set system flow-accounting vrf mgmt +``` ## Operation -Once flow accounting is configured on an interfaces it provides the ability to -display captured network traffic information for all configured interfaces. +```{opcmd} show flow-accounting + +Show all flows the router is currently accounting for. +``` ```{opcmd} show flow-accounting interface \ -Show flow accounting information for given \. +Show accounted flows on the specified interface. +``` +```{opcmd} show flow-accounting interface \ host \ -:::{code-block} none -vyos@vyos:~$ show flow-accounting interface eth0 -IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES ----------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- -eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 -eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 -eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 -eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 -::: +Show accounted flows on the specified interface whose source or destination +address is the given IPv4 or IPv6 address. ``` -```{opcmd} show flow-accounting interface \ host \ +```{opcmd} show flow-accounting interface \ port \<1-65535\> -Show flow accounting information for given \ for a specific host -only. +Show accounted flows on the specified interface whose source or destination +port is the given port. +``` +```{opcmd} show flow-accounting interface \ top \<1-100\> -:::{code-block} none -vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 -IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES ----------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 -eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 -::: -``` \ No newline at end of file +Show accounted flows on the specified interface, limited to the first N +entries. +``` + +```{opcmd} restart flow-accounting + +Restart flow accounting and reattach it to monitored interfaces. + +If flow accounting is not configured and running, the command reports this and +exits without starting it. +``` + +## Example + +The following example enables flow accounting on `eth0` and `eth1`, and exports +version 10 (IPFIX) records to the collector at `192.0.2.10` on port `4739`, +using `192.0.2.1` as the source address. + +```none +set system flow-accounting netflow interface eth0 +set system flow-accounting netflow interface eth1 +set system flow-accounting netflow version 10 +set system flow-accounting netflow server 192.0.2.10 port 4739 +set system flow-accounting netflow server 192.0.2.10 source-address 192.0.2.1 +``` -- cgit v1.2.3