Configuration directives explained

Configuration directives and their related command-line switches are listed below.

Syntax

A configuration consists of key/value pairs, separated by the ':' char. Starting a line with the '!' symbol, makes the whole line to be ignored by the interpreter, making it a comment.

! A sample config file.
daemonize:true
aggregate[inbound]: dst_host
aggregate[outbound]: src_host
aggregate_filter[inbound]: dst net 192.168.0.0/16
aggregate_filter[outbound]: src net 192.168.0.0/16
plugins: memory[inbound], memory[outbound]

Please take a look to the examples available online for further readings.

Legend

List Of Directives

Each directive is followed in parenthesis by it's equivalent command line switch, if any.


debug (-d)

Values

[true|false]

Desc

enables debug

(default: false).


daemonize (-D) [GLOBAL]

Values

[true|false]

Desc

daemonizes the process

(default: false).


aggregate (-c)

Values

[src_mac, dst_mac, vlan, cos, etype, src_host, dst_host, src_net, dst_net, src_mask, dst_mask, src_as, dst_as, src_port, dst_port, tos, proto, none, sum_mac, sum_host, sum_net, sum_as, sum_port, flows, tag, tag2, class, tcpflags, in_iface, out_iface, std_comm, ext_comm, as_path, peer_src_ip, peer_dst_ip, peer_src_as, peer_dst_as, local_pref, med, src_as_path, src_std_comm, src_ext_comm, src_local_pref, src_med, mpls_vpn_rd] FOREWORDS: individual IP packets are uniquely identified by their header fields values (a rather large set of primitives!). Same applies to uni-directional IP flows, as they have at least enough information to discriminate where packets are coming from and going to. Aggregates are instead used for the sole purpose of IP accounting and hence can be identified by a custom and stripped down set of primitives. The procedure to create an aggregate starting from IP packets or flow is: (a) select only the primitives of interest (generic aggregation), (b) optionally cast certain primitive values into broader logical entities, ie. IP addresses into network prefixes or Autonomous System Numbers (spatial aggregation) and (c) sum bytes/flows/packets counters whenever a new constituent IP packet or flow is captured (temporal aggregation).

Desc

aggregate captured traffic data by selecting the specified set of primitives. sum_<primitive> are compound primitives which join together both inbound and outbound traffic into a single aggregate. The 'none' primitive allows to make an unique aggregate which accounts for the grand total of traffic flowing through a specific interface. 'tag' and 'tag2' enable generation of tags when tagging engines (pre_tag_map, post_tag) are in use. 'class' enables reception of L7 traffic classes when Packet/Flow Classification engine (classifiers) is in use. (default: src_host).

NOTES: * Some primitives (ie. tag2, src_as_path, src_std_comm, src_ext_comm, src_med and src_local_pref primitives) are not part of any default SQL table schema shipped with pmacct. Always check out documentation related to the RDBMS in use (ie. 'sql/README.mysql') which will point you to extra primitive-related documentation, if required.


aggregate_filter [NO_GLOBAL]

Desc

Per-plugin filtering applied against the original packet or flow. Aggregation is performed slightly afterwards, upon successful match of this filter. By binding a filter, in tcpdump syntax, to an active plugin, this directive allows to select which data has to be delivered to the plugin and aggregated as specified by the plugin 'aggregate' directive. See the following example:

...
aggregate[inbound]: dst_host
aggregate[outbound]: src_host
aggregate_filter[inbound]: dst net 192.168.0.0/16
aggregate_filter[outbound]: src net 192.168.0.0/16
plugins: memory[inbound], memory[outbound]
...

This directive can be used in conjunction with 'pre_tag_filter' (which, in turn, allows to filter tags). You will also need to force fragmentation handling in the specific case in which a) none of the 'aggregate' directives is including L4 primitives (ie. src_port, dst_port) but b) an 'aggregate_filter' runs a filter which requires dealing with L4 primitives. For further information, refer to the 'pmacctd_force_frag_handling' directive.


pcap_filter (like tcpdump syntax) [GLOBAL, NO_NFACCTD]

Desc

this filter is global and applied to all incoming packets. It's passed to libpcap and, indeed, expects libpcap/tcpdump filter syntax. Being global it doesn't offer a great flexibility but it's the fastest way to drop unwanted traffic. It applies only to pmacctd.


snaplen (-L) [GLOBAL, NO_NFACCTD]

Desc

specifies the maximum number of bytes to capture for each packet. This directive has key importance when enabling both classification and connection tracking engines. In fact, some protocols (mostly text-based eg.: RTSP, SIP, etc.) benefit of extra bytes because they give more chances to successfully track data streams spawned by control channel. But it must be also noted that capturing larger packet portion require more resources. The right value need to be traded-off. In case classification is enabled, values under 200 bytes are often meaningless. 500-750 bytes are enough even for text based protocols. Default snaplen values are ok if classification is disabled. For uacctd daemon, this option doesn't apply to packet snapshot length but rather to the Netlink socket read buffer size. This should be reasonably large - at least 4KB, which is the default value. For large uacctd_nl_size values snaplen could be further increased.


plugins (-P)

Values

[ memory | print | mysql | pgsql | sqlite3 | nfprobe | sfprobe | tee ]

Desc

plugins to be enabled. SQL plugins are available only if configured and compiled. 'memory' enables the use of a memory table as backend; then, a client tool, 'pmacct', can fetch its content; mysql, pgsql and sqlite3 enable the use of respectively MySQL, PostgreSQL and SQLite 3.x (or BerkeleyDB 5.x with the SQLite API compiled-in) tables to store data. 'print' prints aggregates to flat-files or stdout in CSV or formatted. 'nfprobe' acts as a NetFlow/IPFIX agent and exports collected data via NetFlow v1/v5/ v9 and IPFIX datagrams to a remote collector. 'sfprobe' acts as a sFlow agent and exports collected data via sFlow v5 datagrams to a remote collector. Both 'nfprobe' and 'sfprobe' apply only to 'pmacctd' and 'uacctd' daemons. 'tee' acts as a replicator for NetFlow/IPFIX/ sFlow data (also transparent); it applies to 'nfacctd' and 'sfacctd' daemons only. Plugins can be either anonymous or named; configuration directives can be either global or bound to a specific named plugin. An anonymous plugin is declared as 'plugins: mysql' whereas a named plugin is declared as 'plugins: mysql[name]'. Then, directives can be bound to such named plugin as: 'directive[name]: value'.

(default: memory)


plugin_pipe_size

Desc

Core process and active plugins are encapsulated into different OS processes. To exchange data, they set up a communication channel structured as a circular queue (referred as pipe). This directive sets the total size, in bytes, of such queue. Its default size is set depending on the Operating System. Whenever facing heavy traffic loads, this size can be adjusted to store more data. Read INTERNALS, 'Communications between core process and plugin' section for further details. A value of 10240000 (10MB) is usually ok.


plugin_buffer_size

Desc

by defining the transfer buffer size, in bytes, this directive enables bufferization of data transfers between core process and active plugins. It is disabled by default which gives best feelings while testing lab environments. The value has to be <= the size defined by 'plugin_pipe_size' and keeping a ratio of 1:1000 between the two is generally a good idea. Hence, the queue will be partitioned in plugin_buffer_size/plugin_pipe_size slots. Once a slot is filled, it is delivered to the plugin while the circular queue moves to the next buffer element. For further details, read INTERNALS, 'Communications between core process and plugin' section. A value of 10240 (10KB) is usually ok.

(default: 0)


plugin_pipe_backlog

Values

[0 <= value < 100]

Desc

Expects the value to be a percentage. It creates a backlog of buffers on the pipe before actually releasing them to the plugin. The strategy helps optimizing inter process communications where plugins are quicker handling data than the Core process. By default backlog is disabled; as with buffering in general, this feature should be enabled with caution in lab and low-traffic environments.

(default: 0)


files_umask

Desc

Defines the mask for newly created files (log, pid, etc.). A mask less than "002" is currently not accepted due to security reasons.

(default: 077)


files_uid

Desc

Defines the system user id (UID) for files opened for writing (log, pid, etc.); this is indeed possible only when running the daemon as super-user; by default this is left untouched.


files_gid

Desc

Defines the system group id (GID) for files opened for writing (log, pid, etc.); this is indeed possible only when running the daemon as super-user; by default this is left untouched.


interface (-i) [GLOBAL, NO_NFACCTD]

Desc

interface on which 'pmacctd' listens. If such directive isn't supplied, a libpcap function is used to select a valid device. [ns]facctd can catch similar behaviour by employing the [ns]facctd_ip directives; also, note that this directive is mutually exclusive with 'pcap_savefile' (-I).


pcap_savefile (-I) [GLOBAL, NO_NFACCTD]

Desc

file in libpcap savefile format from which read data (this is in alternative to binding to an intervace). The file has to be correctly finalized in order to be read. As soon as 'pmacctd' is finished with the file, it exits (unless the 'savefile_wait' option is in place). The directive doesn't apply to [ns]facctd; to replay original NetFlow/sFlow streams, a tool like TCPreplay can be used instead. The directive is mutually exclusive with 'interface' (-i).


interface_wait (-w) [GLOBAL, NO_NFACCTD]

Values

[true|false]

Desc

if set to true, this option causes 'pmacctd' to wait for the listening device to become available; it will try to open successfully the device each few seconds. Whenever set to false, 'pmacctd' will exit as soon as any error (related to the listening interface) is detected.

(default: false)


savefile_wait (-W) [GLOBAL, NO_NFACCTD]

Values

[true|false]

Desc

if set to true, this option will cause 'pmacctd' to wait indefinitely for a signal (ie. CTRL-C when not daemonized or 'killall -9 pmacctd' if it is) after being finished with the supplied libpcap savefile (pcap_savefile). It's particularly useful when inserting fixed amounts of data into memory tables by keeping the daemon alive.

(default: false)


promisc (-N) [GLOBAL, NO_NFACCTD]

Values

[true|false]

Desc

if set to true, puts the listening interface in promiscuous mode. It's mostly useful when running 'pmacctd' in a box which is not a router, for example, when listening for traffic on a mirroring port.

(default: true)


imt_path (-p)

Desc

specifies the full pathname where the memory plugin has to listen for client queries. When multiple memory plugins are active, each one has to use its own file to communicate with the client tool. Note that placing these files into a carefully protected directory (rather than /tmp) is the proper way to control who can access the memory backend.

(default: /tmp/collect.pipe)


imt_buckets (-b)

Desc

defines the number of buckets of the memory table which is organized as a chained hash table. A prime number is highly recommended. Read INTERNALS 'Memory table plugin' chapter for further details.


imt_mem_pools_number (-m)

Desc

defines the number of memory pools the memory table is able to allocate; the size of each pool is defined by the 'imt_mem_pools_size' directive. Here, a value of 0 instructs the memory plugin to allocate new memory chunks as they are needed, potentially allowing the memory structure to grow undefinitely. A value > 0 instructs the plugin to not try to allocate more than the specified number of memory pools, thus placing an upper boundary to the table size.

(default: 16)


imt_mem_pools_size (-s)

Desc

defines the size of each memory pool. For further details read INTERNALS 'Memory table plugin'. The number of memory pools is defined by the 'imt_mem_pools_number' directive.

(default: 8192).


syslog (-S)

Values

[auth | mail | daemon | kern | user | local[0-7] ]

Desc

enables syslog logging, using the specified facility.

(default: none, console logging)


logfile

Desc

enables logging to a file (bypassing syslog); expected value is a pathname

(default: none, console logging)


pidfile (-F) [GLOBAL]

Desc

writes PID of Core process to the specified file. PIDs of the active plugins are written aswell by employing the following syntax: 'path/to/pidfile-<plugin_type>-<plugin_name>'. This gets particularly useful to recognize which process is which on architectures where pmacct does not support the setproctitle() function.

(default: none)


networks_file (-n)

Desc

full pathname to a file containing a list of (known/local/meaningful) networks/ASNs (one for each line, read more on the file syntax into examples/ tree). The directive is twofold: a) it allows to rewrite as zero IP addresses not included in any defined network range (ie. to avoid IP addresses external to the local domain to be accounted for); b) it is vital for network (src_net, dst_net) and ASN (src_as, dst_as) aggregations.


networks_mask

Desc

specifies the network mask - in bits - to apply to IP address values in L3 header. The mask is applied sistematically and before evaluating the 'networks_file' content (if any is specified).


networks_cache_entries

Desc

Networks Lookup Table (which is the memory structure where the 'networks_file' data is loaded) is preeceded by a Network Lookup Cache where lookup results are saved to speed up later searches. NLC is structured as an hash table, hence, this directive is aimed to set the number of buckets for the hash table. The default value should be suitable for most common scenarios, however when facing with large-scale network definitions, it is quite adviceable to tune this parameter to improve performances. A prime number is highly recommended.


ports_file

Desc

full pathname to a file containing a list of (known/interesting/meaningful) ports (one for each line, read more about the file syntax into examples/ tree). The directive allows to rewrite as zero port numbers not matching any port defined in the list. Indeed, this makes sense only if aggregating on either 'src_port' or 'dst_port' primitives.


sql_db

Desc

defines the SQL database to use. Remember that when using the SQLite3 plugin, this directive refers to the full path to the database file

(default: 'pmacct', SQLite 3.x default: '/tmp/pmacct.db').


[ sql_table | print_output_file ]

Desc

In SQL plugins this defines the SQL table to use (sql_table); in print plugin it defines the file to write to (print_output_file). Dynamic names are supported through the use of variables, which are computed at the moment when data is purged to the backend. The list of supported variables follows: %d The day of the month as a decimal number (range 01 to 31). %H The hour as a decimal number using a 24 hour clock (range 00 to 23). %m The month as a decimal number (range 01 to 12). %M The minute as a decimal number (range 00 to 59). %s The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC. %w The day of the week as a decimal, range 0 to 6, Sunday being 0. %W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. %Y The year as a decimal number including the century. SQL plugins notes: Time-related variables require 'sql_history' to be specified in order to work correctly (see 'sql_history' entry in this in this document for further information) and that the 'sql_refresh_time' setting is aligned with the 'sql_history', ie.:

sql_history: 5m
sql_refresh_time: 300

Furthermore, if the 'sql_table_schema' directive is not specified, tables are expected to be already in place. This is an example on how to split accounted data among multiple tables basing on the day of the week:

sql_history: 1h
sql_history_roundoff: h
sql_table: acct_v4_%w

The above directives will account data on a hourly basis (1h). Also the above sql_table definition will make: Sunday data be inserted into the 'acct_v4_0' table, Monday into the 'acct_v4_1' table, and so on. The switch between the tables will happen each day at midnight: this behaviour is ensured by the use of the 'sql_history_roundoff' directive. Ideally sql_refresh_time and sql_history values should be aligned for the dynamic tables to work; sql_refresh_time with a value smaller than sql_history is also supported; whereas the feature does not support values of sql_refresh_time greater than sql_history. Print plugin notes: If a non-dynamic filename is selected, content is overwritten to the existing one. Common notes: The maximum table name length is 64 characters. The maximum number of variables it may contain is 8.


sql_table_schema

Desc

full pathname to a file containing a SQL table schema. It allows to create the SQL table if it does not exist; this directive makes sense only if a dynamic 'sql_table' is in use. A configuration example where this directive could be useful follows:

sql_history: 5m
sql_history_roundoff: h
sql_table: acct_v4_%Y%m%d_%H%M 
sql_table_schema: /usr/local/pmacct/acct_v4.schema

In this configuration, the content of the file pointed by 'sql_table_schema' should be:

CREATE TABLE acct_v4_%Y%m%d_%H%M (
[ ... PostgreSQL/MySQL specific schema ... ]
);

This setup, along with this directive, are mostly useful when the dynamic tables are not closed in a 'ring' fashion (e.g., the days of the week) but 'open' (e.g., current date).


sql_table_version (-v)

VALUES [ 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ]

Desc

defines the version of the SQL table. SQL table versioning was introduced to achieve two goals: a) make tables work out-of-the-box for the SQL beginners, smaller installations and quick try-outs; and in this context b) to allow introduction of new features over time without breaking backward compatibility. For the SQL experts, the alternative to versioning is 'sql_optimize_clauses' which allows custom mix-and-match of primitives: in such a case you have to build yourself custom SQL schemas and indexes. Check in the 'sql/' sub-tree the SQL table profiles which are supported by the pmacct version you are currently using

(default: 1)


sql_table_type

VALUES [ bgp ]

Desc

optionally combined with "sql_table_version", defines one of the supported SQL table profiles. Currently this directive has to be defined to select one of the default BGP table profiles.


sql_data

Values

[ typed | unified ]

Desc

this switch makes sense only when using PostgreSQL plugin; each of the pgsql scripts in the sql/ tree will create one 'unified' table and multiple 'typed' tables. The 'unified' table has IP and MAC addresses specified as standard CHAR strings, slower and not space savy but flexible; 'typed' tables sport PostgreSQL own types (inet, mac, etc.), resulting in a faster but more rigid structure. Since v6 unified mode is being discontinued leading to efficiency and simplification.

(default: 'typed').


sql_host

Desc

defines the SQL server IP/hostname

(default: localhost).


sql_user

Desc

defines the username to use when connecting to the SQL server

(default: pmacct).


sql_passwd

Desc

defines the password to use when connecting to the SQL server

(default: arealsmartpwd).


[ sql_refresh_time | print_refresh_time ] (-r)

Desc

time interval between consecutive executions of the SQL cache scanner. The scanner purges data from the cache into the RDBMS. The value is expressed in seconds.


sql_startup_delay

Desc

defines the time, in seconds, the first SQL cache scan event has to be delayed. This delay is, in turn, propagated to the subsequent scans. It comes useful in two scenarios: a) so that multiple plugins can use the same 'sql_refresh_time' value, allowing them to spread the writes among the length of the time-bin; b) with NetFlow, to keep original flow start time (nfacctd_time_new: false) while enabling the sql_dont_try_update feature (for RDBMS efficiency purposes); in such a context, sql_startup_delay value should be greater (better >= 2x the value) of the NetFlow active flow timeout.

(default: 0)


sql_optimize_clauses

Values

[true|false]

Desc

enables the optimization of the statements sent to the RDBMS essentially allowing to a) run stripped-down variants of the default SQL tables or b) totally customized SQL tables by a free mix-and-match of the available primitives. Either case, you will need to build the custom SQL table schema and indexes. As a rule of thumb when NOT using this directive always remember to specify which default SQL table version you intend to stick to by using the 'sql_table_version' directive.

(default: false)


sql_history

Values

#[m|h|d|w|M]

Desc

enables historical accounting by dividing accounted data into configurable time-bins. It will use the 'stamp_inserted' (base time of the time-bin) and 'stamp_updated' (last time the time-bin was touched) fields. The supplied value defines the time slot length during which counters are accumulated. For a nice effect, it's adviceable to pair this directive with 'sql_history_roundoff'. Note that this value is fully disjoint from the 'sql_refresh_time' directive which sets the time intervals at which data has to be written to the RDBMS instead. The final effect is close to time slots in a RRD file. Examples of valid values are: '5m' - five minutes, '1h' - one hour, '4h' - four hours, '1d' - one day, '1w' - one week, '1M' - one month).


[ sql_history_roundoff | print_time_roundoff ]

VALUES [m,h,d,w,M]

Desc

enables alignment of minutes (m), hours (h), days of month (d), weeks (w) and months (M) in print (to print_refresh_time) and SQL plugins (to sql_history and sql_refresh_time). Suppose you go with 'sql_history: 1h', 'sql_history_roundoff: m' and it's 6:34pm. Rounding off minutes gives you an hourly timeslot (1h) starting at 6:00pm; so, subsequent ones will start at 7:00pm, 8:00pm, etc. Now, you go with 'sql_history: 5m', 'sql_history_roundoff: m' and it's 6:37pm. Rounding off minutes will result in a first slot starting at 6:35pm; next slot will start at 6:40pm, and then every 5 minutes (6:45pm ... 7:00pm, etc.). 'w' and 'd' are mutually exclusive, that is: you can either reset the date to last Monday or reset the date to the first day of the month.


sql_history_since_epoch

VALUES [true|false]

Desc

enables the use of timestamps (stamp_inserted, stamp_updated) in the standard seconds since the Epoch format. This directive requires changes to the default types for timestamp fields in the SQL schema.

(default: false)

MySQL:          DATETIME ==> INT(8) UNSIGNED
PostgreSQL:     timestamp without time zone ==> bigint
SQLite3:        DATETIME ==> INT(8)


sql_recovery_logfile

Desc

enables recovery mode; recovery mechanism kicks in if the DB fails. It works by checking for the successful result of each SQL query. By default it is disabled. By using this key aggregates are recovered to the specified logfile. Data may be played later by either 'pmmyplay' or 'pmpgplay' tools. Each time pmacct package is updated it's good rule not continue writing old files but start a new ones. Each plugin instance has to write to a different logfile in order to avoid inconsistencies over data. And, finally, the maximum size for a logfile is set to 2Gb: if the logfile reaches such size, it's automatically rotated (in a way similar to logrotate: old file is renamed, appending a little sequential integer to it, and a new file is started). See INTERNALS 'Recovery modes' section for details about this topic. SQLite 3.x note: because the database is file-based it's quite useless to have a logfile, thus this feature is not supported. However, note that the 'sql_recovery_backup_host' directive allows to specify an alternate SQLite 3.x database file.


sql_recovery_backup_host

Desc

enables recovery mode; recovery mechanism kicks in if DB fails. It works by checking for the successful result of each SQL query. By default it is disabled. By using this key aggregates are recovered to a secondary DB. See INTERNALS 'Recovery modes' section for details about this topic. SQLite 3.x note: the plugin uses this directive to specify a the full path to an alternate database file (e.g., because you have multiple file system on a box) to use in the case the primary backend fails.


sql_max_writers

Desc

sets the maximum number of concurrent writer processes the SQL plugin is allowed to fire. This setting allows pmacct to degrade gracefully during major database outages. The value is splitted as follows: up to N-1 concurrent processes will have full functionalities; Nth process will go for a recovery mechanism (sql_recovery_logfile, sql_recovery_backup_host), if any is configured; all processes beyond Nth will stop managing data (so, data will be lost at this stage) and an error message is printed out. Triggers (sql_trigger_exec) will continue working in any case.

(default: 10)


[ sql_cache_entries | print_cache_entries ]

Desc

SQL and print plugins sport a Plugin Memory Cache (PMC) meant to accumulate bytes/packets counters until next purging event (for further insights take a look to 'sql_refresh_time'). This directive sets the number of PMC buckets. Default value is suitable for most common scenarios, however when facing large-scale networks, it's higly recommended to carefully tune this parameter to improve performances. Use a prime number of buckets.

(default: sql_cache_entries: 32771, print_cache_entries: 16411)


sql_dont_try_update

Values

[true|false]

Desc

by default pmacct uses an UPDATE-then-INSERT mechanism to write data to the RDBMS; this directive instructs pmacct to use a more efficient INSERT-only mechanism. This directive is useful for gaining performances by avoiding UPDATE queries. Using this directive puts some timing constraints, specifically sql_history == sql_refresh_time, otherwise it may lead to duplicate entries and, potentially, loss of data. When used in nfacctd it also requires nfacctd_time_new to be enabled.

(default: false)


sql_use_copy

Values

[true|false]

Desc

instructs the plugin to build non-UPDATE SQL queries using COPY (in place of INSERT). While providing same functionalities of INSERT, COPY is also more efficient. To have effect, this directive requires 'sql_dont_try_update' to be set to true. It applies to PostgreSQL plugin only.

(default: false)


sql_delimiter

Desc

If sql_use_copy is true, uses the supplied character as delimiter. This is thought in cases where the default delimiter is part of any of the supplied strings to be inserted into the database.

(default: ',')


sql_multi_values

Desc

enables the use of multi-values INSERT statements. The value of the directive is intended to be the size (in bytes) of the multi-values buffer. The directive applies only to MySQL and SQLite 3.x plugins. Inserting many rows at the same time is much faster (many times faster in some cases) than using separate single-row INSERT statements. It's adviceable to check the size of this pmacct buffer against the size of the corresponding MySQL buffer (max_allowed_packet).

(default: none)


[ sql_trigger_exec | print_trigger_exec ]

Desc

defines the executable to be launched at fixed time intervals to post-process aggregates; in SQL plugins, intervals are specified by the 'sql_trigger_time' directive; if no interval is supplied 'sql_refresh_time' value is used instead: this will result in a trigger being fired each purging event. A number of environment variables are set in order to allow the trigger to take actions; take a look to docs/TRIGGER_VARS to check them out. In the print plugin a simpler implementation is made: triggers can be fired at each 'print_refresh_time' only and no environment variables are passed over to the executable.


sql_trigger_time

Values

#[m|h|d|w|M]

Desc

specifies time interval at which the executable specified by 'sql_trigger_exec' has to be launched; if no executables are specified, this key is simply ignored. Values need to be in the 'sql_history' directive syntax (for example, valid values are '5m', '1h', '4h', '1d', '1w', '1M'; eg. if '1h' is selected, the executable will be fired each hour).


sql_preprocess

Desc

allows to process aggregates (via a comma-separated list of conditionals and checks) while purging data to the RDBMS thus resulting in a powerful selection tier; aggregates filtered out may be just discarded or saved through the recovery mechanism (if enabled). The set of available preprocessing directives follows:


qnum

Desc

conditional. Subsequent checks will be evaluated only if the number of queries to be created during the current cache-to-DB purging event is '>=' qnum value.


minp

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of packets is '>=' minp value.


minf

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of flows is '>=' minf value.


minb

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the bytes counter is '>=' minb value. An interesting idea is to set its value to a fraction of the link capacity. Remember that you have also a timeframe reference: the 'sql_refresh_time' seconds. For example, given the following parameters: Link Capacity = 8Mbit/s, THreshold = 0.1%, TImeframe = 60s minb = ((LC / 8) * TI) * TH -> ((8Mbit/s / 8) * 60s) * 0.1% = 60000 bytes. Given a 8Mbit link, all aggregates which have accounted for at least 60Kb of traffic in the last 60 seconds, will be written to the DB.


maxp

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of packets is '<' maxp value.


maxf

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of flows is '<' maxf value.


maxb

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the bytes counter is '<' maxb value.


maxbpp

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of bytes per packet is '<' maxbpp value.


maxppf

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of packets per flow is '<' maxppf value.


minbpp

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of bytes per packet is '>=' minbpp value.


minppf

Desc

check. Aggregates on the queue are evaluated one-by-one; each object is marked valid only if the number of packets per flow is '>=' minppf value.


fss

Desc

check. Enforces flow (aggregate) size dependent sampling, computed against the bytes counter and returns renormalized results. Aggregates which have collected more than the supplied 'fss' threshold in the last time window (specified by the 'sql_refresh_time' configuration key) are sampled. Those under the threshold are sampled with probability p(bytes). The method allows to get much more accurate samples compared to classic 1/N sampling approaches, providing an unbiased estimate of the real bytes counter. It would be also adviceable to hold the the equality 'sql_refresh_time' = 'sql_history'. For further references: http://www.research.att.com/projects/flowsamp/ and specifically to the papers: N.G. Duffield, C. Lund, M. Thorup, "Charging from sampled network usage", http://www.research.att.com/~duffield/pubs/DLT01-usage.pdf and N.G. Duffield and C. Lund, "Predicting Resource Usage and Estimation Accuracy in an IP Flow Measurement Collection Infrastructure", http://www.research.att.com/~duffield/pubs/p313-duffield-lund.pdf


fsrc

Desc

check. Enforces flow (aggregate) sampling under hard resource constraints, computed against the bytes counter and returns renormalized results. The method selects only 'fsrc' flows from the set of the flows collected during the last time window ('sql_refresh_time'), providing an unbiasied estimate of the real bytes counter. It would be also adviceable to hold the equality 'sql_refresh_time' = 'sql_history'. For further references: http://www.research.att.com/projects/flowsamp/ and specifically to the paper: N.G. Duffield, C. Lund, M. Thorup, "Flow Sampling Under Hard Resource Constraints", http://www.research.att.com/~duffield/pubs/DLT03-constrained.pdf


usrf

Desc

action. Applies the renormalization factor 'usrf' to counters of each aggregate. Its use is suitable for use in conjunction with uniform sampling methods (for example simple random - e.g. sFlow, 'sampling_rate' directive or simple systematic - e.g. sampled NetFlow by Cisco and Juniper). The factor is applied to recovered aggregates also. It would be also adviceable to hold the equality 'sql_refresh_time' = 'sql_history'. Before using this action to renormalize counters generated by sFlow, take also a read of the 'sfacctd_renormalize' key.


adjb

Desc

action. Adds (or subtracts) 'adjb' bytes to the bytes counter multiplied by the number of packet in each aggregate. This is a particularly useful action when - for example - fixed lower (link, llc, etc.) layer sizes need to be included into the bytes counter (as explained by Q7 in FAQS document).


recover

Desc

action. If previously evaluated checks have marked the aggregate as invalid, a positive 'recover' value makes the packet to be handled through the recovery mechanism (if enabled).


sql_preprocess_type

Values

[any|all]

Desc

When more checks are to be evaluated, this directive tells whether aggregates on the queue are valid if they just match one of the checks (any) or all of them (all)

(default: any).


Values

[true|false]

Desc

Enables the use of START/END markers each time data is written to 'stdout'. Start marker returns additional information about current time-bin and configured refresh time

(default: false).


Values

[ formatted | csv ]

Desc

Defines the print plugin output format. 'formatted' enables tabular output; 'csv' is to enable comma-separated values format, suitable for injection into 3rd party tools.

(default: formatted)


[ print_num_protos | sql_num_protos ]

Values

[true|false]

Desc

Defines whether IP protocols (ie. tcp, udp) should be looked up and presented in string format or left numerical. The default is to look protocol names up.

(default: false)


sql_num_hosts

Values

[true|false]

Desc

Defines whether IP addresses should be left numerical (in network bytes ordering) or converted into human-readable strings. Applies to MySQL and SQLite plugins only and assumes the INET_NTOA() function is defined in the RDBMS (which for MySQL is always the case, while for SQLite it is not by default). Since INET_NTOA() is used, unless redefined to some custom-made variant, this feature works for IPv4 addresses only. Default setting is to convert IP addresses into strings.

(default: false)


[ nfacctd_port | sfacctd_port ] (-l) [GLOBAL, NO_PMACCTD]

Desc

defines the UDP port where to bind nfacctd (nfacctd_port) and sfacctd (sfacctd_port) daemons

(default: nfacctd_port: 2100, sfacctd_port: 6343).


[ nfacctd_ip | sfacctd_ip ] (-L) [GLOBAL, NO_PMACCTD]

Desc

defines the IPv4/IPv6 address where to bind the nfacctd (nfacctd_ip) and sfacctd (sfacctd_ip) daemons

(default: all interfaces).


[ nfacctd_allow_file | sfacctd_allow_file ] [GLOBAL, NO_PMACCTD]

Desc

full pathname to a file containing the list of IPv4/IPv6 addresses (one for each line) allowed to send packets to the daemon. Current syntax does not implement network masks but individual IP addresses only. The Allow List is intended to be small; firewall rules should be preferred to long ACLs.

(default: allow all)


nfacctd_time_secs [GLOBAL, NO_PMACCTD]

Values

[true|false]

Desc

makes 'nfacctd' expect times included in NetFlow header to be in seconds rather than msecs. This knob makes sense for NetFlow up to v8 - as in NetFlow v9 and IPFIX different fields are reserved for secs and msecs timestamps, increasing collector awareness.

(default: false)


nfacctd_time_new [GLOBAL, NO_PMACCTD]

Values

[true|false]

Desc

makes 'nfacctd' to ignore timestamps included in NetFlow header and build new ones. This gets particularly useful to assign flows to time-bins based on the flow arrival time at the collector rather than the flow start time. An application for it is when historical accounting is enabled ('sql_history') and an INSERT-only mechanism is in use ('sql_dont_try_update', 'sql_use_copy').

(default: false)


[ nfacctd_as_new | sfacctd_as_new | pmacctd_as | uacctd_as ] [GLOBAL]

Values

[ false | (true|file) | bgp | fallback ]

Desc

When 'false', it instructs nfacctd and sfacctd to populate 'src_as', 'dst_as', 'peer_src_as' and 'peer_dst_as' primitives from NetFlow and sFlow datagram respectively; when 'true' ('file' being an alias of 'true') it instructs nfacctd and sfacctd to generate 'src_as' and 'dst_as' (only! ie. no peer-AS) by looking up source and destination IP addresses against a networks_file. When 'bgp' is specified, ASNs are looked up against the BGP RIB of the peer from which the NetFlow datagram was received (see also bgp_agent_map directive). When 'fallback' is specified, lookup is done against the winning longest match lookup method (sFlow/NetFlow <= BGP), which can be different for source and destination IP prefix. Intuitively if 'fallback' is specified, IS-IS/IGP daemon is enabled and IGP is the winning method then no BGP information will be attached to the prefixes. In pmacctd and uacctd 'false' (maintained for backward compatibility), 'true' and 'file' expect a 'networks_file' to be defined; 'bgp' just works as described previously for nfacctd and sfacctd; 'fallback' is mapped to 'bgp' since no export protocol lookup method is available.

(default: false)


[ nfacctd_net | sfacctd_net | pmacctd_net | uacctd_net ]

Values

[ netflow | sflow | mask | file | igp | bgp | fallback ]

Desc

Determines the method for performing IP prefix aggregation - hence directly influencing 'src_net', 'dst_net', 'src_mask', 'dst_mask' and 'peer_dst_ip' primitives. 'netflow' and 'sflow' get values from NetFlow and sFlow protocols respectively; these keywords are only valid in nfacctd, sfacctd. 'mask' applies a defined networks_mask; 'file' selects a defined networks_file; 'igp' and 'bgp' source values from IGP/IS-IS daemon and BGP daemon respectively. Default behaviour under pmacctd and uacctd is for backward compatibility: 'mask' and 'file' are turned on if a networks_mask and a networks_file are respectively specified by configuration. If they both are defined, the outcome will be the intersection of their definitions. 'fallback' behaves in a longest-match-wins fashion: in nfacctd and sfacctd lookup is done against sFlow/NetFlow protocol, IGP and BGP (sFlow/NetFlow < IGP <= BGP) whereas in pmacctd and uacctd lookup is done against IGP and BGP only (IGP <= BGP).

(default: nfacctd: 'netflow'; sfacctd: 'sflow'; pmacctd and uacctd: 'mask', 'file')


[ nfacctd_mcast_groups | sfacctd_mcast_groups ] [GLOBAL, NO_PMACCTD]

Desc

defines one or more IPv4/IPv6 multicast groups to be joined by the daemon. If more groups are supplied, they are expected comma separated. A maximum of 20 multicast groups may be joined by a single daemon instance. Some OS (noticeably Solaris -- seems) may also require an interface to bind to which - in turn - can be supplied declaring an IP address ('nfacctd_ip' key).


[ nfacctd_disable_checks | sfacctd_disable_checks ] [GLOBAL, NO_PMACCTD]

Values

[true|false]

Desc

both nfacctd and sfacctd check health of incoming NetFlow/sFlow datagrams - actually this is limited to just verifying sequence numbers progression. You may want to disable such feature because of non-standard implementations. By default checks are enabled

(default: false)


nfacctd_sql_log [NO_PMACCTD]

Values

[true|false]

Desc

under the NetFlow accounting daemon (nfacctd), it makes the SQL plugin to use a) NetFlow's First Switched timestamp as "stamp_inserted" value and b) NetFlow's Last Switched timestamp as "stamp_updated" value. By not encapsulating traffic into fixed timeslots, this directive is meant to be employed in scenarios in which it's required to log each micro-flow in the SQL database. It's not compatible with nfacctd_time_new and sql_recovery_logfile directives. It can be applied in conjunction with sql_history_since_epoch directive.

(default: false)


pre_tag_map [GLOBAL]

Desc

full pathname to a file containing tag mappings. Enables the use of Pre-Tagging. When used in nfacctd and sfacctd this map allows (a) to translate some NetFlow/sFlow packet fields (for example 'ip': agent IP address, 'in': Input interface, 'out': Output interface) and (b) to match filter expressions (tcpdump syntax) into an ID (in the range 1-4294967295). In pmacctd it allows just the (b). Take a look to the examples/ sub-tree for all supported keys and detailed examples. Pre-Tagging is enforced in the Core Process shortly after packet/flow/sample collection.


pre_tag_map_entries [GLOBAL]

Desc

defines the maximum number of entries the Pre-Tagging map can contain. The default value is suitable for most scenarios, though tuning it could be required either to save on memory or to allow for more entries. Refer to the specific map directives documentation in this file to see which are affected by this setting.

(default: 384)


refresh_maps [GLOBAL]

Values

[true|false]

Desc

when enabled, this directive allows to reload map files without restarting the daemon instance. For example, it may result particularly useful to reload Pre-Tagging entries or Networks map in order to reflect some change in the network. After having modified the map files, a SIGUSR2 has to be sent (e.g.: in the simplest case "killall -USR2 pmacctd") to the daemon to notify the change. If such signal is sent to the daemon and this directive is not enabled, the signal is silently discarded. The Core Process is in charge of processing the Pre-Tagging map; plugins are devoted to Networks and Ports maps instead. Then, because signals can be sent either to the whole daemon (killall) or to just a specific process (kill), this mechanism also offers the advantage to elicit local reloads.

(default: true)


pre_tag_filter, pre_tag2_filter [NO_GLOBAL]

Values

[0-4294967295]

Desc

it expects one or more tags (when multiple tags are supplied, they need to be comma separated and a logical OR is used in the evaluation phase) as value and allows to filter aggregates basing upon their Pre Tag ID: in case of a match, the aggregate is delivered to the plugin. This directive has to be bound to a plugin (that is, it cannot be global) and is suitable to split tagged data among the active plugins. While the IDs need to be in the range 1-4294967295, this directive also allows to specify an ID '0' - which intercepts non-tagged aggregates - thus allowing to split tagged traffic from untagged one. It also allows negations by pre-pending a minus sign to the tag value (ie. '-6' would send everything but traffic tagged as '6') and ranges (ie. '10-20' would send over traffic tagged in the range 10..20) and combination of these. This directive makes sense if coupled with 'pre_tag_map'; it could be used in conjunction with 'aggregate_filter'.


post_tag

Values

[1-4294967295]

Desc

it expects an ID as its value. Enables the use of Post-Tagging. Once the aggregate has passed all filters and is on the final way to the plugin, this directive allows to statically tag it using the specified value. The tag is sticked to the 'tag' aggregate field.


sampling_rate

Values

[>= 1]

Desc

enables packet sampling. It expects a number which is the mean ratio of packets to be sampled (1 out of N). The currently implemented sampling algorithm is a simple randomic one. If using any SQL plugin, look also to the powerful 'sql_preprocess' layer and the more advanced sampling choices it offers: they will allow to deal with advanced sampling scenarios (e.g. probabilistic methods). Finally, note that this 'sampling_rate' directive can be renormalized by using the 'usrf' action of the 'sql_preprocess' layer.

(default: no sampling)


sampling_map [GLOBAL, NO_PMACCTD, NO_UACCTD]

Desc

full pathname to a file containing traffic sampling mappings. It is mainly meant to be used in conjunction with nfacctd and sfacctd for the purpose of fine-grained reporting of sampling rates circumventing bugs and issues in router operating systems. Renormalization must be enabled (nfacctd_renormalize or sfacctd_renormalize set to true) in order for the feature to work. If a specific router is not defined in the map, the sampling rate advertised by the router itself is applied. Take a look to the examples/ sub-tree 'sampling.map.example' for all supported keys and detailed examples.


[ pmacctd_force_frag_handling | uacctd_force_frag_handling ] [GLOBAL, NO_NFACCTD]

Values

[true|false]

Desc

forces 'pmacctd' to join together IPv4/IPv6 fragments: 'pmacctd' does this only whether any of the port primitives are selected (src_port, dst_port, sum_port); in fact, when not dealing with any upper layer primitive, fragments are just handled as normal packets. However, available filtering rules ('aggregate_filter', Pre-Tag filter rules) will need such functionality enabled whether they need to match TCP/UDP ports. So, this directive aims to support such scenarios.

(default: false)


[ pmacctd_frag_buffer_size | uacctd_frag_buffer_size ] [GLOBAL, NO_NFACCTD]

Desc

defines the maximum size of the fragment buffer. The value is expeced in bytes

(default: 4 Mb).


[ pmacctd_flow_buffer_size | uacctd_flow_buffer_size ] [GLOBAL, NO_NFACCTD]

Desc

defines the maximum size of the flow buffer. This is an upper limit to avoid unlimited growth of the memory structure. This value has to scale accordingly to the link traffic rate. It is expected in bytes

(default: 16 Mb).


[ pmacctd_flow_buffer_buckets | uacctd_flow_buffer_buckets ] [GLOBAL, NO_NFACCTD]

Desc

defines the number of buckets of the flow buffer - which is organized as a chained hash table. To exploit better performances, the table should be reasonably flat. This value has to scale to higher power of 2 accordingly to the link traffic rate. For example, it has been reported that a value of 65536 works just fine under full 100Mbit load

(default: 256).


[ pmacctd_conntrack_buffer_size | uacctd_conntrack_buffer_size ] [GLOBAL, NO_NFACCTD]

Desc

defines the maximum size of the connection tracking buffer. The value is expected in bytes

(default: 8 Mb).


[ pmacctd_flow_lifetime | uacctd_flow_lifetime ] [GLOBAL, NO_NFACCTD]

Desc

defines how long a flow could remain inactive (ie. no packets belonging to such flow are received) before considering it expired. The value is expected in seconds.

(default: 60 secs)


[ pmacctd_ext_sampling_rate | uacctd_ext_sampling_rate | nfacctd_ext_sampling_rate |

sfacctd_ext_sampling_rate ] [GLOBAL] flags pmacctd that captured traffic is being sampled at the specified rate. Such rate can then be renormalized by using 'pmacctd_renormalize' or otherwise is propagated by the NetFlow/sFlow probe plugins, if any of them is activated. External sampling might be performed by capturing frameworks the daemon is linked against (ie. PF_RING, ULOG) or appliances (ie. sampled packet mirroring). In nfacctd and sfacctd daemons this directive can be used to tackle corner cases, ie. sampling rate reported by the NetFlow/sFlow agent is missing or not correct.

(default: no sampling)


[ sfacctd_renormalize | nfacctd_renormalize | pmacctd_renormalize | uacctd_renormalize ] (-R)

Values

[true|false]

Desc

automatically renormalizes byte/packet counters value basing on information acquired from either the NetFlow data unit or sFlow packet. In particular, it allows to deal with scenarios in which multiple interfaces have been configured at different sampling rates. The feature also calculates an effective sampling rate (sFlow only) which could differ from the configured one - expecially at high rates - because of various losses. Such estimated rate is then used for renormalization purposes.

(default: false)


classifiers [GLOBAL, NO_NFACCTD, NO_SFACCTD]

Desc

full path to a spool directory containing the packet classification patterns (expected as .pat or .so files; files with different extensions and subdirectories will be just ignored). This feature enables packet/flow classification against application layer data (that is, the packet payload) and based either over regular expression (RE) patterns (.pat) or external/pluggable C modules (.so). Patterns are loaded in filename alphabetic order and will be evaluated in the same order while classifying packets. Supported RE patterns are those from the great L7-filter project, which is a new packet classifier for Linux kernel, and are avilable for download at: http://sourceforge.net/projects/l7-filter/ (then point to the Protocol definitions archive). Existing SO patterns are available at: http://www.pmacct.net/classification/ . This configuration directive should be specified whenever the 'class' aggregation method is in use (ie. 'aggregate: class'). It's supported only by pmacctd.


sql_aggressive_classification

Values

[true|false]

Desc

usually 5 to 10 packets are required to classify a stream by the 'classifiers' feature. Until the flow is not classified, such packets join the 'unknown' class. As soon as classification engine is successful identifying the stream, the packets are moved to their correct class if they are still cached by the SQL plugin. This directive delays 'unknown' streams - but only those which would have still chances to be correctly classified - from being purged to the DB but only for a small number of consecutive sql_refresh_time slots. It is incompatible with sql_dont_try_update and sql_use_copy directives

(default: false)


sql_locking_style

Desc

defines the locking style for the SQL table. Supported values are: "table", the plugin will lock the entire table when writing data to the DB. It serializes access to the table whenever multiple plugins need to access it simultaneously. Slower but light and safe, ie. no risk for deadlocks and transaction-friendly; "row", the plugin will lock only the rows it needs to UPDATE/DELETE. It results in better overral performances but has some noticeable drawbacks in dealing with transactions and making the UPDATE-then-INSERT mechanism work smoothly. The user need to take cares on his own; a simple and safe enough protection can be tagging uniquely data coming from each plugin (see pre_tag_map, post_tag). In MySQL the use of an InnoDB table is mandatory. This config directive currently applies only to PostgreSQL and MySQL plugins.

(default: table)


classifier_tentatives [GLOBAL, NO_NFACCTD, NO_SFACCTD]

Desc

number of tentatives to classify a stream. Usually 5 "full" (ie. carrying payload) packets are sufficient to classify an uni-directional flow. This is the default value. However classifiers not basing on the payload content may require a different (maybe larger) number of tentatives.

(default: 5)


classifier_table_num [GLOBAL, NO_NFACCTD, NO_SFACCTD]

Desc

the maximum number of classifiers (SO + RE) that could be loaded runtime. The default number is usually ok, but some "dirty" uses of classifiers might require more entries.

(default: 256)


nfprobe_timeouts

Desc

allows to tune a set of timeouts to be applied over collected packets. The value is expected in the following form: 'name=value:name=value:...'. The set of supported timeouts and their default values are listed below: tcp (generic tcp flow life) 3600 tcp.rst (TCP RST flow life) 120 tcp.fin (TCP FIN flow life) 300 udp (UDP flow life) 300 icmp (ICMP flow life) 300 general (generic flow life) 3600 maxlife (maximum flow life) 604800 expint (expiry interval) 60


nfprobe_hoplimit

Values

[1-255]

Desc

value of TTL for the newly generated NetFlow datagrams.

(default: 0, leave default OS settings)


nfprobe_maxflows

Desc

maximum number of flows that can be tracked simultaneously.

(default: 8192)


nfprobe_receiver

Desc

defines the remote IP address/hostname and port to which NetFlow dagagrams are to be exported. The value is expected to be in the usual form 'address:port'.

(default: 127.0.0.1:2100)


nfprobe_source_ip

Desc

defines the local IP address from which NetFlow dagagrams are to be exported. Only a numerical IPv4/IPv6 address is expected. The supplied IP address is required to be already configured on one of the interfaces. This parameter is also required for graceful encoding of NetFlow v9 and IPFIX option scoping.

(default: IP address is selected by the OS)


nfprobe_version

Values

[5,9,10]

Desc

version of outgoing NetFlow datagrams. NetFlow v5/v9 and IPFIX (v10) are supported. NetFlow v5 features a fixed record structure and if not specifying an 'aggregate' directive it gets populated as much as possible; NetFlow v9 and IPFIX feature a dynamic template-based structure instead and by default it is populated as: 'src_host, dst_host, src_port, dst_Port, proto, tos'.

(default: 5)


nfprobe_engine

Desc

allows to define Engine ID and Engine Type fields. It applies only to NetFlow v5/v9 and IPFIX. In NetFlow v9/IPFIX, the supplied value fills last two bytes of SourceID field. Expects two non-negative numbers, up to 255 each and separated by the ":" symbol. It also allows a collector to distinguish between distinct probe instances running on the same box; this is also important for letting NetFlow v9/IPFIX templates to work correctly: in fact, template IDs get automatically selected only inside single daemon instances.

(default: 0:0)


[ nfprobe_peer_as | sfprobe_peer_as ]

Values

[true|false]

Desc

includes peer-AS rather than origin-AS as part of the NetFlow/sFlow export. Requirements to enable this feature are: a) one of the nfacctd_as_new/sfacctd_as_new/pmacctd_as/uacctd_as set to 'bgp' and b) a fully functional BGP daemon (bgp_daemon).

(default: false)


[ nfprobe_ipprec | sfprobe_ipprec ]

Desc

marks self-originated NetFlow (nfprobe) and sFlow (sfprobe) messages with the supplied IP precedence value.

(default: 0)


[ nfprobe_direction | sfprobe_direction ]

Values

[in,out,tag,tag2]

Desc

defines traffic direction. Can be statically defined via 'in' and 'out' keywords. It can also be dynamically determined via lookup to either 'tag' or 'tag2' values. Tag value of 1 will be mapped to 'in' direction, whereas tag value of 2 will be mapped to 'out'. The idea underlying tag lookups is that pre_tag_map supports, among the other features, 'filter' matching against a supplied tcpdump-like filter expression; doing so against L2 primitives (ie. source or destination MAC addresses) allows to dynamically determine traffic direction (see example at 'examples/pretag.map.example')

(default: none)


[ nfprobe_ifindex | sfprobe_ifindex ]

Values

[tag,tag2,<1-4294967295>]

Desc

associates an interface index (ifIndex) to a given nfprobe or sfprobe plugin. This is meant as an add-on to [ns]probe_direction directive, ie. when multiplexing mirrored traffic from different sources on the same interface (ie. split by VLAN). Can be statically defined via a 32-bit integer or semi-dynamically determined via lookup to either 'tag' or 'tag2' values (read full elaboration on [ns]probe_direction directive). This definition will be also always overridden whenever the ifIndex can be determined dynamically (ie. via ULOG framework).


sfprobe_receiver

Desc

defines the remote IP address/hostname and port to which sFlow dagagrams are to be exported. The value is expected to be in the usual form 'address:port'.

(default: 127.0.0.1:6343)


sfprobe_agentip

Desc

sets the value of agentIp field inside the sFlow datagram header.


sfprobe_agentsubid

Desc

sets the value of agentSubId field inside the sFlow datagram header.


sfprobe_ifspeed

Desc

statically associates an interface speed to a given sfprobe plugin.

(default: 100000000)


bgp_daemon

Values

[true|false]

Desc

enables the skinny BGP daemon thread. This feature requires the package to be supporting multi- threading (--enable-threads). Neighbors are not defined explicitely via a piece of configuration (see bgp_daemon_max_peers directive); also, for security purposes, the daemon doesn't implement outbound BGP UPDATE messages and acts passively (ie. it never establishes a connection to a remote peer but waits for incoming connections); upon receipt of a BGP OPEN message, the local daemon presents itself as belonging to the same AS number and supporting same BGP capabilities (ie. MP-BGP, 4-bytes ASNs) as the remote peer. Per-peer RIBs are maintained basing on the IP address of the peer (and for clarity not its BGP Router-ID).

(default: false)


bgp_daemon_ip

Desc

binds the BGP daemon to a specific interface. Expects as value an IPv4 address. The same is used as BGP Router-ID to its peers - otherwise a dumb "1.2.3.4" value is presented. Setting this directive is highly adviced.

(default: 0.0.0.0)


bgp_daemon_port

Desc

binds the BGP daemon to a port different from the standard BGP port: 179/tcp.

(default: 179)


bgp_daemon_ipprec

Desc

marks self-originated BGP messages with the supplied IP precedence value.

(default: 0)


bgp_daemon_max_peers

Desc

sets the maximum number of neighbors the BGP daemon can peer to. Upon reaching of the limit, no more BGP sessions can be established. Differently from routers BGP neighbors don't need to be defined explicitely one-by-one rather an upper boundary to the number of neighbors applies. pmacctd, uacctd daemons are limited to only two BGP peers (in a primary/backup fashion, see bgp_agent_map); such hardcoded limit is imposed as the only scenarios supported in conjunction with the BGP daemon are as NetFlow/sFlow probes on-board software routers and firewalls.

(default: 10)


bgp_daemon_msglog

Values

[true|false]

Desc

enables BGP messages logging: as this can get easily verbose, it is intended for debug and troubleshooting purposes only.

(default: false)


bgp_aspath_radius

Desc

cuts down AS-PATHs to the specified number of ASN hops. If the same ASN is repeated multiple times (ie. as effect of prepending), each of them is regarded as one hop. By default AS-PATHs are left intact unless reaching the maximum length of the buffer (128 chars).


[ bgp_stdcomm_pattern | bgp_extcomm_pattern ]

Desc

filters BGP standard/extended communities against the supplied pattern. The underlying idea is that many communities can be attached to a prefix; some of these can be of little or no interest for the accounting task; this feature allows to select only the relevant ones. By default the list of communities is left intact until reaching maximum length of the buffer (96 chars). The filter does substring matching, ie. 12345:64 will match communities in the ranges 64-64, 640-649, 6400-6499 and 64000-64999. The '.' symbol can be used to wildcard a pre-defined number of characters, ie. 12345:64... will match community values in the range 64000-64999 only.


[ bgp_stdcomm_pattern_to_asn ]

Desc

filters BGP standard communities against the supplied pattern. The algorithm employed is the same as for the bgp_stdcomm_pattern directive: read implementation details there. The first matching community is taken and split using the ':' symbol as delimiter. The first part is mapped onto the peer AS field while the second is mapped onto the origin AS field. The aim of this directive is to deal with IP prefixes on the own address space, ie. statics or connected redistributed in BGP. Example: BGP standard community XXXXX:YYYYY is mapped as: Peer-AS=XXXXX, Origin-AS=YYYYY.


bgp_peer_as_skip_subas

Values

[true|false]

Desc

When determining the peer AS (source and destination), skip potential confederated sub-AS and report the first ASN external to the routing domain. When enabled if no external ASNs are found on the AS-PATH except the confederated sub-ASes, the first sub-AS is reported.

(default: false)


bgp_peer_src_as_type

Values

[ netflow | sflow | map | bgp ]

Desc

Defines the method to use to map incoming traffic to a source peer ASN. "map" selects a map, reloadable at runtime, specified by the bgp_peer_src_as_map directive (refer to it for further information); "bgp" implements naive BGP RIB lookups. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.

(default: netflow, sflow)


bgp_peer_src_as_map

Desc

full pathname to a file containing source peer AS mappings. The AS can be mapped to one or a combination of: ifIndex, source MAC address and BGP next-hop (query against the BGP RIB to look up the source IP prefix). This is sufficient to model popular tecniques for both public and private BGP peerings. Number of map entries (by default 384) can be modified via pre_tag_map_entries. Sample map in 'examples/peers.map.example'.


bgp_src_std_comm_type

Values

[ bgp ]

Desc

Defines the method to use to map incoming traffic to a set of standard communities. Only naive BGP RIB lookups are currenntly supported. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.


bgp_src_ext_comm_type

Values

[ bgp ]

Desc

Defines the method to use to map incoming traffic to a set of extended communities. Only naive BGP RIB lookups are currenntly supported. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.


bgp_src_as_path_type

Values

[ bgp ]

Desc

Defines the method to use to map incoming traffic to an AS-PATH. Only naive BGP RIB lookups are currenntly supported. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.


bgp_src_local_pref_type

Values

[ map | bgp ]

Desc

Defines the method to use to map incoming traffic to a local preference. Only naive BGP RIB lookups are currenntly supported. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.


bgp_src_local_pref_map

Desc

full pathname to a file containing source local preference mappings. The LP value can be mapped to one or a combination of: ifIndex, source MAC address and BGP next-hop (query against the BGP RIB to look up the source IP prefix). Number of map entries (by default 384) can be modified via pre_tag_map_entries. Sample map in 'examples/lpref.map.example'.


bgp_src_med_type

Values

[ map | bgp ]

Desc

Defines the method to use to map incoming traffic to a MED value. Only naive BGP RIB lookups are currenntly supported. BGP lookups assume traffic is symmtric, which is often not the case, affecting their accuracy.


bgp_src_med_map

Desc

full pathname to a file containing source MED (Multi Exit Discriminator) mappings. The MED value can be mapped to one or a combination of: ifIndex, source MAC address and BGP next-hop (query against the BGP RIB to look up the source IP prefix). Number of map entries (by default 384) can be modified via pre_tag_map_entries. Sample map in 'examples/med.map.example'.


bgp_agent_map

Desc

full pathname to a file to map source IP address of NetFlow agents and AgentID of sFlow agents to source IP address or Router ID of BGP peers. This is particularly aimed as a resource-savy alternative to have N agents but only a restricted number of BGP peers (ie. a BGP RR), in case of simpler topologies (ie. hub-and- spoke) or scenarios (ie. single- homed). It can also be viewed as a temporary workaround to certain situations. pmacctd, uacctd daemons are required to use a bgp_agent_map with up to two "catch-all" entries - working in a primary/backup fashion (see agent_to_peer.map in the examples section): this is because these daemons do not have a NetFlow/sFlow source address to match to. Number of map entries (by default 384) can be modified via pre_tag_map_entries.


bgp_iface_rd_map

Desc

full pathname to a file to map PE routers ifIndexes (input interfaces typically) to a BGP/MPLS Virtual Private Network (VPN) Route Distinguisher (RD), based upon rfc4659. See iface_to_rd.map file in the examples section for further information. Number of map entries (by default 384) can be modified via pre_tag_map_entries.


bgp_follow_default

Desc

expects positive number value which instructs how many times a default route, if any, can be followed in order to successfully resolve source and destination IP prefixes. This is aimed at scenarios where neighbors peering with pmacct have a default-only or partial BGP view. At each recursion (default route follow-up) the value gets decremented; the process stops when one of these conditions is met: * both source and destination IP prefixes are resolved * there is no available default route * the default gateway is not BGP peering with pmacct * the the recusion value reaches zero As soon as an IP prefix is matched, it is not looked up anymore in case more recursions are required (ie. the closer the router is, the most specific the route is assumed to be). pmacctd, uacctd daemons are internally limited to only two BGP peers hence this feature can't properly work.

(default: 0)


bgp_follow_nexthop

Desc

expects one or more IP prefix(es), ie. 192.168.0.0/16, comma separated. A maximum of 32 IP prefixes is supported. It follows the BGP next-hop up (using each next-hop as BGP source-address for the next BGP RIB lookup), returning the last next-hop part of the supplied IP prefix as value for the 'peer_ip_dst' primitive. bgp_agent_map is supported at each recursion. This feature is aimed at networks not running MPLS or being based on BGP confederations; underlying goal being to see the routing-domain "exit-point" (which is what is easily seen with MPLS LSPs in conjunction with BGP). The feature is internally protected against routing loops with an hardcoded limit of 20 lookups; pmacctd, uacctd daemons are internally limited to only two BGP peers hence this feature can't properly work.

(default: none)


bgp_neighbors_file

Desc

writes a list of the BGP neighbors in the established state to the specified file, one per line. This gets particularly useful for automation purposes (ie. auto-discovery of devices to poll via SNMP).

(default: none)


bgp_daemon_allow_file [GLOBAL]

Desc

full pathname to a file containing the list of IP addresses (one for each line) allowed to establish a BGP session packets to the BGP thread. Current syntax does not implement network masks but only individual IP addresses.

(default: allow all)


bgp_daemon_md5_file [GLOBAL]

Desc

full pathname to a file containing the BGP peers (IP address only, one for each line) and their corresponding MD5 passwords in CSV format (ie. 10.15.0.1, arealsmartpwd). BGP peers not making use of a MD5 password should not be listed. The maximum number of peers supported is 8192. For a sample map look in: 'examples/bgp_md5.lst.example' The feature was tested working against a 2.6.32 Linux kernel.

(default: no password)


bgp_table_peer_buckets [GLOBAL]

Values

[ 1-1000 ]

Desc

From version 0.12.4, a shared BGP RIB is worked out from announcements sent by all BGP peers. Routing information related to BGP prefixes is kept per-peer in order to simulate a multi-RIB environment and is internally structured as an hash with conflict chains. This parameter sets the number of buckets of such hash structure; the value is directly related to the number of expected BGP peers, should never exceed such amount and is best set to 1/10 of the expected number of peers. The default value proved to work fine up to aprox 100 BGP peers in lab. More buckets means better CPU usage but also increased memory footprint - and vice-versa.

(default: 13)


isis_daemon

Values

[true|false]

Desc

Enables the skinny IS-IS daemon thread. This feature requires the package to be supporting multi-threading (--enable-threads). It implements P2P Hellos, CSNP and PSNP - and does not send any LSP information out. It currently supports a single L2 P2P neighborship. Testing has been done over a GRE tunnel.

(default: false)


isis_daemon_ip

Desc

Sets the sub-TLV of the Extended IS Reachability TLV that contains an IPv4 address for the local end of a link. No default value is set and a non-zero value is mandatory. It should be set to the IPv4 address configured on the interface pointed by isis_daemon_iface.


isis_daemon_net

Desc

Defines the Network entity title (NET) of the IS-IS daemon. In turn a NET defines the area addresses for the IS-IS area and the system ID of the router. No default value is set and a non-zero value is mandatory. Extensive IS-IS and ISO literature cover the topic, example of the NET value format can be found as part of the "Quickstart guide to setup the IS-IS daemon" in the EXAMPLES document.


isis_daemon_iface

Desc

Defines the network interface (ie. gre1) where to bind the IS-IS daemon. No default value is set and a non-zero value is mandatory.


isis_daemon_mtu

Desc

Defines the available MTU for the IS-IS daemon. P2P HELLOs will be padded to such length. When the daemon is configured to set a neighborship with a Cisco router running IOS, this value should match the value of the "clns mtu" IOS directive.

(default: 1476) KEY isis_daemon_msglog ===

Values

[true|false]

Desc

enables IS-IS messages logging: as this can get easily verbose, it is intended for debug and troubleshooting purposes only.

(default: false)


uacctd_group

Desc

Sets the Linux Netlink ULOG multicast group to be joined.

(default: 1)


uacctd_nl_size

Desc

Sets ULOG Netlink internal buffer size (specified in bytes). It is 4KB by default, but to safely record bursts of high-speed traffic, it could be further increased. For high loads, values as large as 2MB are recommended. When modifying this value, it is also recommended to reflect the change to the 'snaplen' option.

(default: 4096)


tunnel_0 [GLOBAL, NO_NFACCTD]

Desc

Defines tunnel inspection, disabled by default. The daemon will then account on tunnelled data rather than on the envelope. The implementation approach is stateless, ie. control messages are not handled. Up to 4 tunnel layers are supported (ie. <tun proto>, <options>; <tun proto>, <options>; ...). Up to 8 tunnel stacks will be supported (ie. configuration directives tunnel_0 .. tunnel_8), to be used in a strictly sequential order. First stack matched at the first layering, wins. Below tunnel protocols supported and related options: GTP, GPRS tunnelling protocol. Expects as option the UDP port identifying the protocol. tunnel_0: gtp, <UDP port>


tee_receiver

Desc

defines remote IP address and port to which NetFlow/sFlow dagagrams are to be replicated to. The value is expected to be in the usual form 'address:port'. This key is mandatory for a 'tee' plugin instance and no default value is set in order to prevent loops.


tee_source_ip

Desc

defines the local IP address from which NetFlow/sFlow dagagrams are to be replicate from. Only a numerical IPv4/IPv6 address is expected. The supplied IP address is required to be already configured on one of the interfaces. Value is ignored when transparent replication is enabled.

(default: IP address is selected by the OS)


tee_transparent

Values

[true|false]

Desc

Enables transparent replication mode. It essentially spoofs the source IP address to the original sender of the datagram. It requires super-user permissions.

(default: false)


xlate_src

Values

[true|false]

Desc

Copies NAT L3/L4 field values in place of the original ones (ie. src_host, src_port, src_net) when available; alternatively it falls back to original values. At time of writing only IPFIX and Cisco ASA NetFlow v9 (NSEL) have support for this

(default: false)


xlate_dst

Values

[true|false]

Desc

Copies NAT L3/L4 field values in place of the original ones (ie. dst_host, dst_port, dst_net) when available; alternatively it falls back to original values. At time of writing only IPFIX and Cisco ASA NetFlow v9 (NSEL) have support for this

(default: false)


pmacct Wiki: OfficialConfigKeys (last edited 2012-04-12 15:13:48 by paolo)