You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

CONFIG-KEYS 141KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554
  1. SUPPORTED CONFIGURATION KEYS
  2. Both configuration directives and commandline switches are listed below.
  3. A configuration consists of key/value pairs, separated by the ':' char.
  4. Starting a line with the '!' symbol, makes the whole line to be ignored
  5. by the interpreter, making it a comment. Please also refer to QUICKSTART
  6. document and the 'examples/' sub-tree for some examples.
  7. Directives are sometimes grouped, like sql_table and print_output_file:
  8. this is to stress if multiple plugins are running as part of the same
  9. daemon instance, such directives must be casted to the plugin they refer
  10. to - in order to prevent undesired inheritance effects. In other words,
  11. grouped directives share the same field in the configuration structure.
  12. LEGEND of flags:
  13. GLOBAL Can't be configured on individual plugins
  14. NO_GLOBAL Can't be configured globally
  15. NO_PMACCTD Does not apply to 'pmacctd'
  16. NO_UACCTD Does not apply to 'uacctd'
  17. NO_NFACCTD Does not apply to 'nfacctd'
  18. NO_SFACCTD Does not apply to 'sfacctd'
  19. ONLY_PMACCTD Applies only to pmacctd
  20. ONLY_UACCTD Applies only to uacctd
  21. ONLY_NFACCTD Applies only to nfacctd
  22. ONLY_SFACCTD Applies only to sfacctd
  23. MAP Indicates the input file is a map
  24. LIST OF DIRECTIVES:
  25. KEY: debug (-d)
  26. VALUES: [ true | false ]
  27. DESC: Enables debug (default: false).
  28. KEY: debug_internal_msg
  29. VALUES: [ true | false ]
  30. DESC: Extra flag to enable debug of internal messaging between Core process
  31. and plugins. It has to be enabled on top of 'debug' (default: false).
  32. KEY: daemonize (-D) [GLOBAL]
  33. VALUES: [ true | false ]
  34. DESC: Daemonizes the process (default: false).
  35. KEY: aggregate (-c)
  36. VALUES: [ src_mac, dst_mac, vlan, cos, etype, src_host, dst_host, src_net, dst_net,
  37. src_mask, dst_mask, src_as, dst_as, src_port, dst_port, tos, proto, none,
  38. sum_mac, sum_host, sum_net, sum_as, sum_port, flows, tag, tag2, label,
  39. class, tcpflags, in_iface, out_iface, std_comm, ext_comm, lrg_comm,
  40. as_path, peer_src_ip, peer_dst_ip, peer_src_as, peer_dst_as, local_pref,
  41. med, src_std_comm, src_ext_comm, src_lrg_comm, src_as_path, src_local_pref,
  42. src_med, mpls_vpn_rd, mpls_label_top, mpls_label_bottom, mpls_stack_depth,
  43. sampling_rate, src_host_country, dst_host_country, src_host_pocode,
  44. dst_host_pocode, pkt_len_distrib, nat_event, fw_event, post_nat_src_host,
  45. post_nat_dst_host, post_nat_src_port, post_nat_dst_port, tunnel_src_host,
  46. tunnel_dst_host, tunnel_proto, tunnel_tos, timestamp_start, timestamp_end,
  47. timestamp_arrival, export_proto_seqno, export_proto_version ]
  48. FOREWORDS: Individual IP packets are uniquely identified by their header field values (a
  49. rather large set of primitives!). Same applies to uni-directional IP flows, as
  50. they have at least enough information to discriminate where packets are coming
  51. from and going to. Aggregates are instead used for the sole purpose of IP
  52. accounting and hence can be identified by an arbitrary set of primitives.
  53. The process to create an aggregate starting from IP packets or flows is: (a)
  54. select only the primitives of interest (generic aggregation), (b) optionally
  55. cast certain primitive values into broader logical entities, ie. IP addresses
  56. into network prefixes or Autonomous System Numbers (spatial aggregation) and
  57. (c) sum aggregate bytes/flows/packets counters when a new tributary IP packet
  58. or flow is captured (temporal aggregation).
  59. DESC: Aggregate captured traffic data by selecting the specified set of primitives.
  60. sum_<primitive> are compound primitives which sum ingress/egress traffic in a
  61. single aggregate; current limit of sum primitives: each sum primitive is mutual
  62. exclusive with any other, sum and non-sum, primitive. The 'none' primitive
  63. allows to make an unique aggregate which accounts for the grand total of
  64. traffic flowing through a specific interface. 'tag', 'tag2' and 'label' enable
  65. generation of tags when tagging engines (pre_tag_map, post_tag) are in use.
  66. 'class' enables L7 traffic classification.
  67. NOTES: * Some primitives (ie. tag2, timestamp_start, timestamp_end) are not part of
  68. any default SQL table schema shipped. Always check out documentation related
  69. to the RDBMS in use (ie. 'sql/README.mysql') which will point you to extra
  70. primitive-related documentation, if required.
  71. * List of the aggregation primitives available to each specific pmacct daemon
  72. is available via -a command-line option, ie. "pmacctd -a".
  73. * sampling_rate: if counters renormalization (ie. sfacctd_renormalize) is
  74. enabled this field will report a value of one (1); otherwise it will report
  75. the rate that is passed by the protocol or sampling_map. A value of zero (0)
  76. means 'unknown' and hence no rate is applied to original counter values.
  77. * src_std_comm, src_ext_comm, src_lrg_comm, src_as_path are based on reverse
  78. BGP lookups; peer_src_as, src_local_pref and src_med are by default based on
  79. reverse BGP lookups but can be alternatively based on other methods, for
  80. example maps (ie. bgp_peer_src_as_type). Internet traffic is by nature
  81. asymmetric hence reverse BGP lookups must be used with caution (ie. against
  82. own prefixes).
  83. * Communities (ie. std_comm, ext_comm, lrg_comm) and AS-PATHs (ie. as_path)
  84. are fixed size (96 and 128 chars respectively at time of writing). Directives
  85. like bgp_stdcomm_pattern and bgp_aspath_radius are aimed to keep length of
  86. these strings under control but sometimes this is not enough. While the longer
  87. term approach will be to define these primitives as varchar, the short-term
  88. approach is to re-define default size, ie. MAX_BGP_STD_COMMS MAX_BGP_ASPATH
  89. in network.h, to the desired size (blowing extra memory). This will require
  90. recompiling the binary.
  91. * timestamp_start, timestamp_end and timestamp_arrival should not be mixed
  92. with pmacct support for historical accounting, ie. breakdown of traffic in
  93. time-bins via the sql_history feature; these primitives have the effect of
  94. letting pmacct act as a logger up to the msec level (if reported by the
  95. capturing method). timestamp_start records NetFlow/IPFIX flow start time or
  96. observation; timestamp_end records NetFlow/IPFIX flow end time; finally,
  97. timestamp_arrival records libpcap packet timestamp and sFlow/NetFlow/IPFIX
  98. packet arrival time at the collector.
  99. * export_proto_seqno reports about export protocol (NetFlow, sFlow, IPFIX)
  100. sequence number; due to its potential de-aggregation effect, two main use-
  101. cases are seen as use of this primitive:
  102. 1) if using a log type (de-)aggregation method, ie. for security, forensics,
  103. etc., in addition to existing primitives;
  104. 2) if using a reporting type aggregation method, it is recommended to split
  105. this primitive in a separate plugin instance instead for sequencing
  106. analysis.
  107. DEFAULT: src_host
  108. KEY: aggregate_primitives [GLOBAL, MAP]
  109. DESC: Expects full pathname to a file containing custom-defined primitives. Once
  110. defined in this file, primitives can be used in 'aggregate' statements. The
  111. feature is currently available only in nfacctd, for NetFlow v9/IPFIX, pmacctd
  112. and uacctd. Examples are available in 'examples/primitives.lst.example'. This
  113. map does not support reloading at runtime.
  114. DEFAULT: none
  115. KEY: aggregate_filter [NO_GLOBAL]
  116. DESC: Per-plugin filtering applied against the original packet or flow. Aggregation
  117. is performed slightly afterwards, upon successful match of this filter.
  118. By binding a filter, in tcpdump syntax, to an active plugin, this directive
  119. allows to select which data has to be delivered to the plugin and aggregated
  120. as specified by the plugin 'aggregate' directive. See the following example:
  121. ...
  122. aggregate[inbound]: dst_host
  123. aggregate[outbound]: src_host
  124. aggregate_filter[inbound]: dst net 192.168.0.0/16
  125. aggregate_filter[outbound]: src net 192.168.0.0/16
  126. plugins: memory[inbound], memory[outbound]
  127. ...
  128. This directive can be used in conjunction with 'pre_tag_filter' (which, in
  129. turn, allows to filter tags). You will also need to force fragmentation handling
  130. in the specific case in which a) none of the 'aggregate' directives is including
  131. L4 primitives (ie. src_port, dst_port) but b) an 'aggregate_filter' runs a filter
  132. which requires dealing with L4 primitives. For further information, refer to the
  133. 'pmacctd_force_frag_handling' directive.
  134. DEFAULT: none
  135. KEY: pcap_filter [GLOBAL, PMACCTD_ONLY]
  136. DESC: This filter is global and applied to all incoming packets. It's passed to libpcap
  137. and expects libpcap/tcpdump filter syntax. Being global it doesn't offer a great
  138. flexibility but it's the fastest way to drop unwanted traffic. It applies only to
  139. pmacctd.
  140. DEFAULT: none
  141. KEY: pcap_protocol [GLOBAL, PMACCTD_ONLY]
  142. DESC: If set, specifies a specific packet socket protocol value to limit packet capture
  143. to (for example, 0x0800 = IPv4). This option is only supported if pmacct was built
  144. against a version of libpcap that supports pcap_set_protocol(), and it only applies
  145. to pmacctd.
  146. DEFAULT: none
  147. KEY: snaplen (-L) [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  148. DESC: Specifies the maximum number of bytes to capture for each packet. This directive has
  149. key importance to both classification and connection tracking engines. In fact, some
  150. protocols (mostly text-based eg.: RTSP, SIP, etc.) benefit of extra bytes because
  151. they give more chances to successfully track data streams spawned by control channel.
  152. But it must be also noted that capturing larger packet portion require more resources.
  153. The right value need to be traded-off. In case classification is enabled, values under
  154. 200 bytes are often meaningless. 500-750 bytes are enough even for text based
  155. protocols. Default snaplen values are ok if classification is disabled.
  156. DEFAULT: 128 bytes; 64 bytes if compiled with --disable-ipv6
  157. KEY: plugins (-P)
  158. VALUES: [ memory | print | mysql | pgsql | sqlite3 | nfprobe | sfprobe | tee | amqp | kafka ]
  159. DESC: Plugins to be enabled. memory, print, nfprobe, sfprobe and tee plugins are always
  160. included in pmacct executables as they do not contain dependencies on external
  161. libraries. Database (ie. RDBMS, noSQL) and messaging ones (ie. amqp, kafka) do have
  162. external dependencies and hence are available only if explicitely configured and
  163. compiled.
  164. memory plugin uses a memory table as backend; then, a client tool, 'pmacct', can fetch
  165. the memory table content; the memory plugin is good for prototype solutions and/or
  166. small environments. mysql, pgsql and sqlite3 plugins output respectively to MySQL,
  167. PostgreSQL and SQLite 3.x (or BerkeleyDB 5.x with the SQLite API compiled-in) tables
  168. to store data. print plugin prints output data to flat-files or stdout in JSON, CSV
  169. or tab-spaced formats, or encodes it using the Apache Avro serialization system. amqp
  170. and kafka plugins allow to output data to RabbitMQ and Kafka brokers respectively.
  171. All these plugins, SQL, no-SQL and messaging are good for production solutions and/or
  172. larger scenarios.
  173. nfprobe acts as a NetFlow/IPFIX agent and exports collected data via NetFlow v1/v5/
  174. v9 and IPFIX datagrams to a remote collector. sfprobe acts as a sFlow agent and
  175. exports collected data via sFlow v5 datagrams to a remote collector. Both nfprobe
  176. and sfprobe plugins apply only to pmacctd and uacctd daemons. tee acts as a replicator
  177. for NetFlow/IPFIX/sFlow data (also transparent); it applies to nfacctd and sfacctd
  178. daemons only. Plugins can be either anonymous or named; configuration directives can
  179. be either global or bound to a specific plugins, if named. An anonymous plugin is
  180. declared as 'plugins: mysql' in the config whereas a named plugin is declared as
  181. 'plugins: mysql[name]'. Then, directives can be bound specifically to such named
  182. plugin as: 'directive[name]: value'.
  183. DEFAULT: memory
  184. KEY: [ nfacctd_pipe_size | sfacctd_pipe_size | pmacctd_pipe_size | tee_pipe_size ]
  185. DESC: Defines the size of the kernel socket to read (ie. daemons) and write (ie. tee plugin)
  186. traffic data. The socket is highlighted below with "XXXX":
  187. XXXX
  188. [network] ----> [kernel] ----> [core process] ----> [plugin] ----> [backend]
  189. [__________pmacct___________]
  190. On Linux systems, if this configuration directive is not specified default socket size
  191. awarded is defined in /proc/sys/net/core/[rw]mem_default ; the maximum configurable
  192. socket size is defined in /proc/sys/net/core/[rw]mem_max instead. Still on Linux, the
  193. "drops" field of /proc/net/udp or /proc/net/udp6 can be checked to ensure its value
  194. is not increasing.
  195. DEFAULT: Operating System default
  196. KEY: [ bgp_daemon_pipe_size | bmp_daemon_pipe_size ] [GLOBAL]
  197. DESC: Defines the size of the kernel socket used for BGP and BMP messaging. The socket is
  198. highlighted below with "XXXX":
  199. XXXX
  200. [network] ----> [kernel] ----> [core process] ----> [plugin] ----> [backend]
  201. [__________pmacct___________]
  202. On Linux systems, if this configuration directive is not specified default socket size
  203. awarded is defined in /proc/sys/net/core/rmem_default ; the maximum configurable socket
  204. size (which can be changed via sysctl) is defined in /proc/sys/net/core/rmem_max
  205. instead.
  206. DEFAULT: Operating System default
  207. KEY: plugin_pipe_size
  208. DESC: Core Process and each of the plugin instances are run into different processes. To
  209. exchange data, they set up a circular queue (home-grown implementation, referred to
  210. as 'pipe') and highlighted below with "XXXX":
  211. XXXX
  212. [network] ----> [kernel] ----> [core process] ----> [plugin] ----> [backend]
  213. [__________pmacct___________]
  214. This directive sets the total size, in bytes, of such queue. Its default size is set
  215. to 4MB. Whenever facing heavy traffic loads, this size can be adjusted to hold more
  216. data. In the following example, the queue between the Core process and the plugin
  217. 'test' is set to 10MB:
  218. ...
  219. plugins: memory[test]
  220. plugin_pipe_size[test]: 10240000
  221. ...
  222. When enabling debug, log messages about obtained and target pipe sizes are printed.
  223. If obtained is less than target, it could mean the maximum socket size granted by
  224. the Operating System has to be increased. On Linux systems default socket size awarded
  225. is defined in /proc/sys/net/core/[rw]mem_default ; the maximum configurable socket
  226. size (which can be changed via sysctl) is defined in /proc/sys/net/core/[rw]mem_max
  227. instead.
  228. In case of data loss messages containing the "missing data detected" string will be
  229. logged - indicating the plugin affected and current settings.
  230. Alternatively see at plugin_pipe_zmq and plugin_pipe_zmq_profile.
  231. DEFAULT: 4MB
  232. KEY: plugin_buffer_size
  233. DESC: By defining the transfer buffer size, in bytes, this directive enables buffering of
  234. data transfers between core process and active plugins. Once a buffer is filled, it
  235. is delivered to the plugin. Setting a larger value may improve throughput (ie. amount
  236. of CPU cycles required to transfer data); setting a smaller value may improve latency,
  237. especially in scenarios with little data influx. It is disabled by default. If used
  238. with the home-grown circular queue implemetation, the value has to be minor/equal to
  239. the size defined by 'plugin_pipe_size' and keeping a ratio between 1:100 and 1:1000
  240. among the two is considered good practice; the circular queue of plugin_pipe_size size
  241. is partitioned in chunks of plugin_buffer_size.
  242. Alternatively see at plugin_pipe_zmq and plugin_pipe_zmq_profile.
  243. DEFAULT: Set to the size of the smallest element to buffer
  244. KEY: plugin_pipe_check_core_pid
  245. VALUES: [ true | false ]
  246. DESC: When enabled (default), validates the sender of data at the plugin side. The check
  247. consists in verifying that the sender PID matches the PID of the plugin parent
  248. process. The feature is not inteded to be a security one; instead its objective is
  249. to limit impact of such things like mis- configurations, daemons started twice with
  250. the same configuration, etc.
  251. DEFAULT: true
  252. KEY: plugin_pipe_zmq
  253. VALUES: [ true | false ]
  254. DESC: By defining this directive to 'true', a ZeroMQ queue is used for queueing and data
  255. exchange between the Core Process and the plugins. This is in alternative to the
  256. home-grown circular queue implementation (see plugin_pipe_size description). This
  257. directive, along with all other plugin_pipe_zmq_* directives, can be set globally
  258. or be applied on a per plugin basis (ie. it is a valid scenario, if multiple
  259. plugins are instantiated, that some make use of home-grown queueing, while others
  260. use ZeroMQ based queueing). For a quick comparison: while relying on a ZeroMQ queue
  261. introduces an external dependency, ie. libzmq, it reduces the bare minimum the need
  262. of settings of the home-grown circular queue implementation. See QUICKSTART for
  263. some examples.
  264. DEFAULT: false
  265. KEY: plugin_pipe_zmq_retry
  266. DESC: Defines the interval of time, in seconds, after which a connection to the ZeroMQ
  267. server (Core Process) should be retried by the client (Plugin) after a failure is
  268. detected.
  269. DEFAULT: 60
  270. KEY: plugin_pipe_zmq_profile
  271. VALUES: [ micro | small | medium | large | xlarge ]
  272. DESC: Allows to select some standard buffering profiles. Following are the recommended
  273. buckets in flows/samples/packets per second:
  274. micro : up to 1K
  275. small : from 1K to 10-15K
  276. medium : from 10-10K to 100-125K
  277. large : from 100-125K to 250K
  278. xlarge : from 250K
  279. A symptom the selected profile is undersized is missing data warnings appear in
  280. the logs; a symptom it is oversized instead is latency in data being purged out.
  281. The amount of flows/samples per second can be estimated as described in Q21 in
  282. the FAQS document. Should no profile fit the sizing, the buffering value can be
  283. customised using the plugin_buffer_size directive.
  284. DEFAULT: micro
  285. KEY: files_umask
  286. DESC: Defines the mask for newly created files (log, pid, etc.) and their related directory
  287. structure. A mask less than "002" is not accepted due to security reasons.
  288. DEFAULT: 077
  289. KEY: files_uid
  290. DESC: Defines the system user id (UID) for files opened for writing (log, pid, etc.); this
  291. is indeed possible only when running the daemon as super-user; by default this is left
  292. untouched. This is also applied to any intermediary directory structure which might be
  293. created.
  294. DEFAULT: Operating System default (current user UID)
  295. KEY: files_gid
  296. DESC: Defines the system group id (GID) for files opened for writing (log, pid, etc.); this
  297. is indeed possible only when running the daemon as super-user; by default this is left
  298. untouched. This is also applied to any intermediary directory structure which might be
  299. created.
  300. DEFAULT: Operating System default (current user GID)
  301. KEY: interface (-i) [GLOBAL, PMACCTD_ONLY]
  302. DESC: Interface on which 'pmacctd' listens. If such directive isn't supplied, a libpcap
  303. function is used to select a valid device. [ns]facctd can catch similar behaviour by
  304. employing the [ns]facctd_ip directives; also, note that this directive is mutually
  305. exclusive with 'pcap_savefile' (-I).
  306. DEFAULT: Interface is selected by by the Operating System
  307. KEY: interface_wait (-w) [GLOBAL, PMACCTD_ONLY]
  308. VALUES: [ true | false ]
  309. DESC: If set to true, this option causes 'pmacctd' to wait for the listening device to become
  310. available; it will try to open successfully the device each few seconds. Whenever set to
  311. false, 'pmacctd' will exit as soon as any error (related to the listening interface) is
  312. detected.
  313. DEFAULT: false
  314. KEY: pcap_savefile (-I) [GLOBAL, NO_UACCTD]
  315. DESC: File in libpcap savefile format to read data from (as an alternative to live data
  316. collection. The file has to be correctly finalized in order to be read. As soon as
  317. the daemon finished processing the file, it exits (unless the 'pcap_savefile_wait'
  318. config directive is specified). The directive is mutually exclusive with 'interface'
  319. (-i) for pmacctd and with [ns]facctd_ip (-L) and [ns]facctd_port (-l) for nfacctd
  320. and sfacctd respectively.
  321. DEFAULT: none
  322. KEY: pcap_savefile_wait (-W) [GLOBAL, NO_UACCTD]
  323. VALUES: [ true | false ]
  324. DESC: If set to true, this option will cause the daemon to wait indefinitely for a signal
  325. (ie. CTRL-C when not daemonized or 'killall -9 pmacctd' if it is) after being finished
  326. processing the supplied libpcap savefile (pcap_savefile). This is particularly useful
  327. when inserting fixed amounts of data into memory tables.
  328. DEFAULT: false
  329. KEY: promisc (-N) [GLOBAL, PMACCTD_ONLY]
  330. VALUES: [ true | false ]
  331. DESC: If set to true, puts the listening interface in promiscuous mode. It's mostly useful when
  332. running 'pmacctd' in a box which is not a router, for example, when listening for traffic
  333. on a mirroring port.
  334. DEFAULT: true
  335. KEY: imt_path (-p)
  336. DESC: Specifies the full pathname where the memory plugin has to listen for client queries.
  337. When multiple memory plugins are active, each one has to use its own file to communicate
  338. with the client tool. Note that placing these files into a carefully protected directory
  339. (rather than /tmp) is the proper way to control who can access the memory backend.
  340. DEFAULT: /tmp/collect.pipe
  341. KEY: imt_buckets (-b)
  342. DESC: Defines the number of buckets of the memory table which is organized as a chained hash
  343. table. A prime number is highly recommended. Read INTERNALS 'Memory table plugin' chapter
  344. for further details.
  345. DEFAULT: 32771
  346. KEY: imt_mem_pools_number (-m)
  347. DESC: Defines the number of memory pools the memory table is able to allocate; the size of each
  348. pool is defined by the 'imt_mem_pools_size' directive. Here, a value of 0 instructs the
  349. memory plugin to allocate new memory chunks as they are needed, potentially allowing the
  350. memory structure to grow undefinitely. A value > 0 instructs the plugin to not try to
  351. allocate more than the specified number of memory pools, thus placing an upper boundary
  352. to the table size.
  353. DEFAULT: 16
  354. KEY: imt_mem_pools_size (-s)
  355. DESC: Defines the size of each memory pool. For further details read INTERNALS 'Memory table
  356. plugin'. The number of memory pools is defined by the 'imt_mem_pools_number' directive.
  357. DEFAULT: 8192
  358. KEY: syslog (-S)
  359. VALUES: [ auth | mail | daemon | kern | user | local[0-7] ]
  360. DESC: Enables syslog logging, using the specified facility.
  361. DEFAULT: none (logging to stderr)
  362. KEY: logfile
  363. DESC: Enables logging to a file (bypassing syslog); expected value is a pathname. The target
  364. file can be re-opened by sending a SIGHUP to the daemon so that, for example, logs can
  365. be rotated.
  366. DEFAULT: none (logging to stderr)
  367. KEY: amqp_host
  368. DESC: Defines the AMQP/RabbitMQ broker IP. amqp_* directives refer to the broker used by an
  369. AMQP plugin to purge data out.
  370. DEFAULT: localhost
  371. KEY: [ bgp_daemon_msglog_amqp_host | bgp_table_dump_amqp_host | bmp_dump_amqp_host |
  372. bmp_daemon_msglog_amqp_host | sfacctd_counter_amqp_host |
  373. telemetry_daemon_msglog_amqp_host | telemetry_dump_amqp_host ] [GLOBAL]
  374. DESC: See amqp_host. bgp_daemon_msglog_amqp_* directives refer to the broker used by the BGP
  375. thread to stream data out; bgp_table_dump_amqp_* directives refer to the broker used
  376. by the BGP thread to dump data out at regular time intervals; bmp_daemon_msglog_amqp_*
  377. directives refer to the broker used by the BMP thread to stream data out; bmp_dump_amqp_*
  378. directives refer to the broker used by the BMP thread to dump data out at regular time
  379. intervals; sfacctd_counter_amqp_* directives refer to the broker used by sfacctd to
  380. stream sFlow counter data out; telemetry_daemon_msglog_amqp_* directives refer to the
  381. broker used by the Streaming Telemetry thread/daemon to stream data out;
  382. telemetry_dump_amqp_* directives refer to the broker used by the Streaming Telemetry
  383. thread/daemon to dump data out at regular time intervals.
  384. DEFAULT: See amqp_host
  385. KEY: amqp_vhost
  386. DESC: Defines the AMQP/RabbitMQ server virtual host; see also amqp_host.
  387. DEFAULT: "/"
  388. KEY: [ bgp_daemon_msglog_amqp_vhost | bgp_table_dump_amqp_vhost | bmp_dump_amqp_vhost |
  389. bmp_daemon_msglog_amqp_vhost | sfacctd_counter_amqp_vhost |
  390. telemetry_daemon_msglog_amqp_vhost | telemetry_dump_amqp_vhost ] [GLOBAL]
  391. DESC: See amqp_vhost; see also bgp_daemon_msglog_amqp_host.
  392. DEFAULT: See amqp_vhost
  393. KEY: amqp_user
  394. DESC: Defines the username to use when connecting to the AMQP/RabbitMQ server; see also
  395. amqp_host.
  396. DEFAULT: guest
  397. KEY: [ bgp_daemon_msglog_amqp_user | bgp_table_dump_amqp_user | bmp_dump_amqp_user |
  398. bmp_daemon_msglog_amqp_user | sfacctd_counter_amqp_user |
  399. telemetry_daemon_msglog_amqp_user | telemetry_dump_amqp_user ] [GLOBAL]
  400. DESC: See amqp_user; see also bgp_daemon_msglog_amqp_host.
  401. DEFAULT: See amqp_user
  402. KEY: amqp_passwd
  403. DESC: Defines the password to use when connecting to the server; see also amqp_host.
  404. DEFAULT: guest
  405. KEY: [ bgp_daemon_msglog_amqp_passwd | bgp_table_dump_amqp_passwd |
  406. bmp_dump_amqp_passwd | bmp_daemon_msglog_amqp_passwd |
  407. sfacctd_counter_amqp_passwd | telemetry_daemon_msglog_amqp_passwd |
  408. telemetry_dump_amqp_passwd ]
  409. [GLOBAL]
  410. DESC: See amqp_passwd; see also bgp_daemon_msglog_amqp_host.
  411. DEFAULT: See amqp_passwd
  412. KEY: amqp_routing_key
  413. DESC: Name of the AMQP routing key to attach to published data. Dynamic names are supported
  414. through the use of variables, which are computed at the moment when data is purged to
  415. the backend. The list of variables supported is:
  416. $peer_src_ip Value of the peer_src_ip primitive of the record being processed.
  417. $pre_tag Value of the tag primitive of the record being processed.
  418. $post_tag Configured value of post_tag.
  419. $post_tag2 Configured value of post_tag2.
  420. See also amqp_host.
  421. DEFAULT: 'acct'
  422. KEY: [ bgp_daemon_msglog_amqp_routing_key | bgp_table_dump_amqp_routing_key |
  423. bmp_daemon_msglog_amqp_routing_key | bmp_dump_amqp_routing_key |
  424. sfacctd_counter_amqp_routing_key | telemetry_daemon_msglog_amqp_routing_key |
  425. telemetry_dump_amqp_routing_key ] [GLOBAL]
  426. DESC: See amqp_routing_key; see also bgp_daemon_msglog_amqp_host. Variables supported by
  427. the configuration directives described in this section:
  428. $peer_src_ip Value of the peer_src_ip primitive of the record being processed.
  429. DEFAULT: none
  430. KEY: [ amqp_routing_key_rr | kafka_topic_rr ]
  431. DESC: Performs round-robin load-balancing over a set of AMQP routing keys or Kafka topics.
  432. The base name for the string is defined by amqp_routing_key or kafka_topic. This key
  433. accepts a positive int value. If, for example, amqp_routing_key is set to 'blabla'
  434. and amqp_routing_key_rr to 3 then the AMQP plugin will round robin as follows:
  435. message #1 -> blabla_0, message #2 -> blabla_1, message #3 -> blabla_2, message #4
  436. -> blabla_0 and so forth. This works in the same fashion for kafka_topic. By default
  437. the feature is disabled, meaning all messages are sent to the base AMQP routing key
  438. or Kafka topic (or the default one, if no amqp_routing_key or kafka_topic is being
  439. specified).
  440. For Kafka it is adviced to create topics in advance with a tool like kafka-topics.sh
  441. (ie. "kafka-topics.sh --zookeepeer <zookeeper URL> --topic <topic> --create") even
  442. if auto.create.topics.enable is set to true (default) on the broker. This is because
  443. topic creation, especially on distributed systems, may take time and lead to data
  444. loss.
  445. DEFAULT: 0
  446. KEY: [ bgp_daemon_msglog_amqp_routing_key_rr | bgp_table_dump_amqp_routing_key_rr |
  447. bmp_daemon_msglog_amqp_routing_key_rr | bmp_dump_amqp_routing_key_rr |
  448. telemetry_daemon_msglog_amqp_routing_key_rr | telemetry_dump_amqp_routing_key_rr ]
  449. [GLOBAL]
  450. DESC: See amqp_routing_key_rr; see also bgp_daemon_msglog_amqp_host.
  451. DEFAULT: See amqp_routing_key_rr
  452. KEY: amqp_exchange
  453. DESC: Name of the AMQP exchange to publish data; see also amqp_host.
  454. DEFAULT: pmacct
  455. KEY: [ bgp_daemon_msglog_amqp_exchange | bgp_table_dump_amqp_exchange |
  456. bmp_daemon_msglog_amqp_exchange | bmp_dump_amqp_exchange |
  457. sfacctd_counter_amqp_exchange | telemetry_daemon_msglog_amqp_exchange |
  458. telemetry_dump_amqp_exchange ] [GLOBAL]
  459. DESC: See amqp_exchange
  460. DEFAULT: See amqp_exchange; see also bgp_daemon_msglog_amqp_host.
  461. KEY: amqp_exchange_type
  462. DESC: Type of the AMQP exchange to publish data to. 'direct', 'fanout' and 'topic'
  463. types are supported; "rabbitmqctl list_exchanges" can be used to check the
  464. exchange type. Upon mismatch of exchange type, ie. exchange type is 'direct'
  465. but amqp_exchange_type is set to 'topic', an error will be returned.
  466. DEFAULT: direct
  467. KEY: [ bgp_daemon_msglog_amqp_exchange_type | bgp_table_dump_amqp_exchange_type |
  468. bmp_daemon_msglog_amqp_exchange_type | bmp_dump_amqp_exchange_type |
  469. sfactd_counter_amqp_exchange_type | telemetry_daemon_msglog_amqp_exchange_type |
  470. telemetry_dump_amqp_exchange_type ] [GLOBAL]
  471. DESC: See amqp_exchange_type; see also bgp_daemon_msglog_amqp_host.
  472. DEFAULT: See amqp_exchange_type
  473. KEY: amqp_persistent_msg
  474. VALUES: [ true | false ]
  475. DESC: Marks messages as persistent and sets Exchange as durable so to prevent data loss
  476. if a RabbitMQ server restarts (it will still be consumer responsibility to declare
  477. the queue durable). Note from RabbitMQ docs: "Marking messages as persistent does
  478. not fully guarantee that a message won't be lost. Although it tells RabbitMQ to
  479. save message to the disk, there is still a short time window when RabbitMQ has
  480. accepted a message and hasn't saved it yet. Also, RabbitMQ doesn't do fsync(2) for
  481. every message -- it may be just saved to cache and not really written to the disk.
  482. The persistence guarantees aren't strong, but it is more than enough for our simple
  483. task queue."; see also amqp_host.
  484. DEFAULT: false
  485. KEY: [ bgp_daemon_msglog_amqp_persistent_msg | bgp_table_dump_amqp_persistent_msg |
  486. bmp_daemon_msglog_amqp_persistent_msg | bmp_dump_amqp_persistent_msg |
  487. sfacctd_counter_persistent_msg | telemetry_daemon_msglog_amqp_persistent_msg |
  488. telemetry_dump_amqp_persistent_msg ] [GLOBAL]
  489. VALUES: See amqp_persistent_msg; see also bgp_daemon_msglog_amqp_host.
  490. DESC: See amqp_persistent_msg
  491. DEFAULT: See amqp_persistent_msg
  492. KEY: amqp_frame_max
  493. DESC: Defines the maximum size, in bytes, of an AMQP frame on the wire to request of the broker
  494. for the connection. 4096 is the minimum size, 2^31-1 is the maximum; see also amqp_host.
  495. DEFAULT: 131072
  496. KEY: [ bgp_daemon_msglog_amqp_frame_max | bgp_table_dump_amqp_frame_max |
  497. bmp_daemon_msglog_amqp_frame_max | bmp_dump_amqp_frame_max |
  498. sfacctd_counter_amqp_frame_max | telemetry_daemon_msglog_amqp_frame_max |
  499. telemetry_dump_amqp_frame_max ] [GLOBAL]
  500. DESC: See amqp_frame_max; see also bgp_daemon_msglog_amqp_host.
  501. DEFAULT: See amqp_frame_max
  502. KEY: amqp_heartbeat_interval
  503. DESC: Defines the heartbeat interval in order to detect general failures of the RabbitMQ server.
  504. The value is expected in seconds. By default the heartbeat mechanism is disabled with a
  505. value of zero. According to RabbitMQ C API, detection takes place only upon publishing a
  506. JSON message, ie. not at login or if idle. The maximum value supported is INT_MAX (or
  507. 2147483647); see also amqp_host.
  508. DEFAULT: 0
  509. KEY: [ bgp_daemon_msglog_amqp_heartbeat_interval | bgp_table_dump_amqp_heartbeat_interval |
  510. bmp_daemon_msglog_amqp_heartbeat_interval | bmp_dump_amqp_heartbeat_interval |
  511. sfacctd_counter_amqp_heartbeat_interval | telemetry_daemon_msglog_amqp_heartbeat_interval |
  512. telemetry_dump_amqp_heartbeat_interval ] [GLOBAL]
  513. DESC: See amqp_heartbeat_interval; see also bgp_daemon_msglog_amqp_host.
  514. DEFAULT: See amqp_heartbeat_interval
  515. KEY: [ bgp_daemon_msglog_amqp_retry | bmp_daemon_msglog_amqp_retry |
  516. sfacctd_counter_amqp_retry | telemetry_daemon_msglog_amqp_retry ] [GLOBAL]
  517. DESC: Defines the interval of time, in seconds, after which a connection to the RabbitMQ
  518. server should be retried after a failure is detected; see also amqp_host. See also
  519. bgp_daemon_msglog_amqp_host.
  520. DEFAULT: 60
  521. KEY: kafka_topic
  522. DESC: Name of the Kafka topic to attach to published data. Dynamic names are supported by
  523. kafka_topic through the use of variables, which are computed at the moment when data
  524. is purged to the backend. The list of variables supported by amqp_routing_key:
  525. $peer_src_ip Value of the peer_src_ip primitive of the record being processed.
  526. $pre_tag Value of the tag primitive of the record being processed.
  527. $post_tag Configured value of post_tag.
  528. $post_tag2 Configured value of post_tag2.
  529. It is adviced to create topics in advance with a tool like kafka-topics.sh (ie.
  530. "kafka-topics.sh --zookeepeer <zookeeper URL> --topic <topic> --create") even if
  531. auto.create.topics.enable is set to true (default) on the broker. This is because
  532. topic creation, especially on distributed systems, may take time and lead to data
  533. loss.
  534. DEFAULT: 'pmacct.acct'
  535. KEY: kafka_config_file
  536. DESC: Full pathname to a file containing directives to configure librdkafka. All knobs
  537. whose values are string, integer, boolean, CSV are supported. Pointer values, ie.
  538. for setting callbacks, are currently not supported through this infrastructure.
  539. The syntax of the file is CSV and expected in the format: <type, key, value> where
  540. 'type' is one of 'global' or 'topic' and 'key' and 'value' are set according to
  541. librdkafka doc https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md
  542. Both 'key' and 'value' are passed onto librdkafka without any validation being
  543. performed; the 'value' field can also contain commas no problem as it is also not
  544. parsed. Examples are:
  545. topic, compression.codec, snappy
  546. global, socket.keepalive.enable, true
  547. DEFAULT: none
  548. KEY: kafka_broker_host
  549. DESC: Defines one or multiple, comma-separated, Kafka brokers. If only a single broker
  550. IP address is defined then the broker port is read via the kafka_broker_port config
  551. directive (legacy syntax); if multiple brokers are defined then each broker port,
  552. if not left to default 9092, is expected as part of this directive, for example:
  553. "broker1:10000,broker2". When defining multiple brokers, if the host is IPv4, the
  554. value is expected as 'address:port'. If IPv6, it is expected as '[address]:port'.
  555. When defining a single broker, this is not needed as the IPv6 address is detected
  556. and wrapped-around '[' ']' symbols. FQDNs are also accepted. SSL connections can be
  557. configured as "ssl://broker3:9000,ssl://broker2".
  558. DEFAULT: 127.0.0.1
  559. KEY: kafka_broker_port
  560. DESC: Defines the Kafka broker port. See also kafka_broker_host.
  561. DEFAULT: 9092
  562. KEY: kafka_partition
  563. DESC: Defines the Kafka broker topic partition ID. RD_KAFKA_PARTITION_UA or ((int32_t)-1)
  564. is to define the configured or default partitioner (slower than sending to a fixed
  565. partition). See also kafka_broker_host.
  566. DEFAULT: -1
  567. KEY: kafka_partition_key
  568. DESC: Defines the Kafka broker topic partition key. A string of printable characters is
  569. expected as value.
  570. DEFAULT: none
  571. KEY: [ bgp_daemon_msglog_kafka_broker_host | bgp_table_dump_kafka_broker_host |
  572. bmp_daemon_msglog_kafka_broker_host | bmp_dump_kafka_broker_host |
  573. sfacctd_counter_kafka_broker_host | telemetry_daemon_msglog_kafka_broker_host |
  574. telemetry_dump_kafka_broker_host ] [GLOBAL]
  575. DESC: See kafka_broker_host
  576. DEFAULT: See kafka_broker_host
  577. KEY: [ bgp_daemon_msglog_kafka_broker_port | bgp_table_dump_kafka_broker_port |
  578. bmp_daemon_msglog_kafka_broker_port | bmp_dump_kafka_broker_port |
  579. sfacctd_counter_kafka_broker_port | telemetry_daemon_msglog_kafka_broker_port |
  580. telemetry_dump_kafka_broker_port ] [GLOBAL]
  581. DESC: See kafka_broker_port
  582. DEFAULT: See kafka_broker_port
  583. KEY: [ bgp_daemon_msglog_kafka_topic | bgp_table_dump_kafka_topic |
  584. bmp_daemon_msglog_kafka_topic | bmp_dump_kafka_topic |
  585. sfacctd_counter_kafka_topic | telemetry_daemon_msglog_kafka_topic |
  586. telemetry_dump_kafka_topic ] [GLOBAL]
  587. DESC: See kafka_topic
  588. DEFAULT: none
  589. KEY: [ bgp_daemon_msglog_kafka_topic_rr | bgp_table_dump_kafka_topic_rr |
  590. bmp_daemon_msglog_kafka_topic_rr | bmp_dump_kafka_topic_rr |
  591. telemetry_daemon_msglog_kafka_topic_rr | telemetry_dump_kafka_topic_rr ]
  592. [GLOBAL]
  593. DESC: See kafka_topic_rr
  594. DEFAULT: See kafka_topic_rr
  595. KEY: [ bgp_daemon_msglog_kafka_partition | bgp_table_dump_kafka_partition |
  596. bmp_daemon_msglog_kafka_partition | bmp_dump_kafka_partition |
  597. sfacctd_counter_kafka_partition | telemetry_daemon_msglog_kafka_partition |
  598. telemetry_dump_kafka_partition ] [GLOBAL]
  599. DESC: See kafka_partition
  600. DEFAULT: See kafka_partition
  601. KEY: [ bgp_daemon_msglog_kafka_partition_key |
  602. bgp_table_dump_kafka_partition_key |
  603. bmp_daemon_msglog_kafka_partition_key | bmp_dump_kafka_partition_key |
  604. sfacctd_counter_kafka_partition_key |
  605. telemetry_daemon_msglog_kafka_partition_key |
  606. telemetry_dump_kafka_partition_key ] [GLOBAL]
  607. DESC: See kafka_partition_key
  608. DEFAULT: See kafka_partition_key
  609. KEY: [ bgp_daemon_msglog_kafka_retry | bmp_daemon_msglog_kafka_retry |
  610. sfacctd_counter_kafka_retry | telemetry_daemon_msglog_kafka_retry ] [GLOBAL]
  611. DESC: Defines the interval of time, in seconds, after which a connection to the Kafka
  612. broker should be retried after a failure is detected.
  613. DEFAULT: 60
  614. KEY: [ bgp_daemon_msglog_kafka_config_file | bgp_table_dump_kafka_config_file |
  615. bmp_daemon_msglog_kafka_config_file | bmp_dump_kafka_config_file |
  616. sfacctd_counter_kafka_config_file | telemetry_daemon_msglog_kafka_config_file |
  617. telemetry_dump_kafka_config_file ] [GLOBAL]
  618. DESC: See kafka_config_file
  619. DEFAULT: See kafka_config_file
  620. KEY: pidfile (-F) [GLOBAL]
  621. DESC: Writes PID of Core process to the specified file. PIDs of the active plugins are written
  622. aswell by employing the following syntax: 'path/to/pidfile-<plugin_type>-<plugin_name>'.
  623. This gets particularly useful to recognize which process is which on architectures where
  624. pmacct does not support the setproctitle() function.
  625. DEFAULT: none
  626. KEY: networks_file (-n)
  627. DESC: Full pathname to a file containing a list of networks - and optionally ASN information,
  628. BGP next-hop (peer_dst_ip) and IP prefix labels (read more about the file syntax in
  629. examples/networks.lst.example). Purpose of the feature is to act as a resolver when
  630. network, next-hop and/or peer/origin ASN information is not available through other
  631. means (ie. BGP, IGP, telemetry protocol) or for the purpose of overriding such
  632. information with custom/self-defined one. IP prefix labels rewrite the resolved
  633. source and/or destination IP prefix into the supplied label; labels can be up to 15
  634. characters long.
  635. DEFAULT: none
  636. KEY: networks_file_filter
  637. VALUES [ true | false ]
  638. DESC: Makes networks_file work as a filter in addition to its basic resolver functionality:
  639. networks and hosts not belonging to defined networks are zeroed out. This feature can
  640. interfere with the intended behaviour of networks_no_mask_if_zero, if they are both
  641. set to true.
  642. DEFAULT: false
  643. KEY: networks_file_no_lpm
  644. VALUES [ true | false ]
  645. DESC: Makes a matching IP prefix defined in a networks_file win always, even if it is not
  646. the longest. It applies when the aggregation method includes src_net and/or dst_net
  647. and nfacctd_net (or equivalents) and/or nfacctd_as (or equivalents) configuration
  648. directives are set to 'longest' (or 'fallback'). For example we receive the following
  649. PDU via NetFlow:
  650. SrcAddr: 10.0.8.29 (10.0.8.29)
  651. DstAddr: 192.168.5.47 (192.168.5.47)
  652. [ .. ]
  653. SrcMask: 24 (prefix: 10.0.8.0/24)
  654. DstMask: 27 (prefix: 192.168.5.32/27)
  655. a BGP peering is available and BGP contains the following prefixes: 192.168.0.0/16 and
  656. 10.0.0.0/8. Such a scenario is typical when more specifics are not re-distributed in
  657. BGP but are only available in the IGP. A networks_file contains the prefixes 10.0.8.0/24
  658. and 192.168.5.0/24. 10.0.8.0/24 is the same as in NetFlow; but 192.168.5.0/24 (say,
  659. representative of a range dedicated to a specific customer across several locations and
  660. hence composed of several sub-prefies) would not be the longest match and hence the
  661. prefix from NetFlow, 192.168.5.32/27, would be the outcome of the network aggregation
  662. process; setting networks_file_no_lpm to true makes 192.168.5.0/24, coming from the
  663. networks_file, win instead.
  664. DEFAULT: false
  665. KEY: networks_no_mask_if_zero
  666. VALUES [ true | false ]
  667. DESC: If set to true, IP prefixes with zero mask - that is, unknown ones or those hitting a
  668. default route - are not masked (ie. they are applied a full 0xF mask, that is, 32 bits
  669. for IPv4 addresses and 128 bits for IPv6 ones). The feature applies to *_net fields
  670. and makes sure individual IP addresses belonging to unknown IP prefixes are not zeroed
  671. out. This feature can interfere with the intended behaviour of networks_file_filter,
  672. if they are both set to true.
  673. DEFAULT: false
  674. KEY: networks_mask
  675. DESC: Specifies the network mask - in bits - to apply to IP address values in L3 header. The
  676. mask is applied sistematically and before evaluating the 'networks_file' content (if
  677. any is specified).
  678. DEFAULT: none
  679. KEY: networks_cache_entries
  680. DESC: Networks Lookup Table (which is the memory structure where the 'networks_file' data is
  681. loaded) is preeceded by a Network Lookup Cache where lookup results are saved to speed
  682. up later searches. NLC is structured as an hash table, hence, this directive is aimed to
  683. set the number of buckets for the hash table. The default value should be suitable for
  684. most common scenarios, however when facing with large-scale network definitions, it is
  685. quite adviceable to tune this parameter to improve performances. A prime number is highly
  686. recommended.
  687. DEFAULT: IPv4: 99991; IPv6: 32771
  688. KEY: ports_file
  689. DESC: Full pathname to a file containing a list of (known/interesting/meaningful) ports (one
  690. for each line, read more about the file syntax into examples/ tree). The directive allows
  691. to rewrite as zero port numbers not matching any port defined in the list. Indeed, this
  692. makes sense only if aggregating on either 'src_port' or 'dst_port' primitives.
  693. DEFAULT: none
  694. KEY: sql_db
  695. DESC: Defines the SQL database to use. Remember that when using the SQLite3 plugin, this
  696. directive refers to the full path to the database file
  697. DEFAULT: 'pmacct'; SQLite 3.x: '/tmp/pmacct.db'
  698. KEY: [ sql_table | print_output_file ]
  699. DESC: In SQL this defines the table to use; in print plugin it defines the file to write output
  700. to. Dynamic names are supported through the use of variables, which are computed at the
  701. moment when data is purged to the backend. The list of supported variables follows:
  702. %d The day of the month as a decimal number (range 01 to 31).
  703. %H The hour as a decimal number using a 24 hour clock (range 00 to 23).
  704. %m The month as a decimal number (range 01 to 12).
  705. %M The minute as a decimal number (range 00 to 59).
  706. %s The number of seconds since Epoch, ie., since 1970-01-01 00:00:00 UTC.
  707. %w The day of the week as a decimal, range 0 to 6, Sunday being 0.
  708. %W The week number of the current year as a decimal number, range
  709. 00 to 53, starting with the first Monday as the first day of
  710. week 01.
  711. %Y The year as a decimal number including the century.
  712. $ref Configured refresh time value for the plugin.
  713. $hst Configured sql_history value, in seconds, for the plugin.
  714. $peer_src_ip Record value for peer_src_ip primitive (if primitive is not part of
  715. the aggregation method then this will be set to a null value).
  716. $tag Record value for tag primitive ((if primitive is not part of the
  717. aggregation method then this will be set to a null value).
  718. $tag2 Record value for tag2 primitive ((if primitive is not part of the
  719. aggregation method then this will be set to a null value).
  720. SQL plugins notes:
  721. Time-related variables require 'sql_history' to be specified in order to work correctly
  722. (see 'sql_history' entry in this in this document for further information) and that the
  723. 'sql_refresh_time' setting is aligned with the 'sql_history', ie.:
  724. sql_history: 5m
  725. sql_refresh_time: 300
  726. Furthermore, if the 'sql_table_schema' directive is not specified, tables are expected
  727. to be already in place. This is an example on how to split accounted data among multiple
  728. tables basing on the day of the week:
  729. sql_history: 1h
  730. sql_history_roundoff: h
  731. sql_table: acct_v4_%w
  732. The above directives will account data on a hourly basis (1h). Also the above sql_table
  733. definition will make: Sunday data be inserted into the 'acct_v4_0' table, Monday into
  734. the 'acct_v4_1' table, and so on. The switch between the tables will happen each day at
  735. midnight: this behaviour is ensured by the use of the 'sql_history_roundoff' directive.
  736. Ideally sql_refresh_time and sql_history values should be aligned for the dynamic tables
  737. to work; sql_refresh_time with a value smaller than sql_history is also supported; whereas
  738. the feature does not support values of sql_refresh_time greater than sql_history. The
  739. maximum table name length is 64 characters.
  740. Print plugin notes:
  741. * if a non-dynamic filename is selected, content is overwritten to the existing one in
  742. case print_output_file_append is set to false (default). Are supported scenarios where
  743. multiple level of directories need to be created in order to create the target file,
  744. ie. "/path/to/%Y/%Y-%m/%Y-%m-%d/blabla-%Y%m%d-%H%M.txt". Shell replacements are not
  745. supported though, ie. '~' symbol to denote the user home directory. print_history
  746. values are used for time-related variables substitution of dynamic print_output_file
  747. names.
  748. MongoDB plugin notes:
  749. The table name is expected as <database>.<collection> . Default table is test.acct
  750. Common notes:
  751. The maximum number of variables it may contain is 32.
  752. DEFAULT: see notes
  753. KEY: print_output_file_append
  754. VALUES: [ true | false ]
  755. DESC: If set to true, print plugin will append to existing files instead of overwriting. If
  756. appending, and in case of an output format requiring a title, ie. csv, formatted, etc.,
  757. intuitively the title is not re-printed.
  758. DEFAULT: false
  759. KEY: print_output_lock_file
  760. DESC: If no print_output_file is defined (ie. print plugin output goes to stdout), this
  761. directive defined a global lock to serialize output to stdout, ie. in cases where
  762. multiple print plugins are defined or purging events of the same plugin queue up.
  763. By default output is not serialized and a warning message is printed to flag the
  764. condition.
  765. KEY: print_latest_file
  766. DESC: Defines the full pathname to pointer(s) to latest file(s). Dynamic names are supported
  767. through the use of variables, which are computed at the moment when data is purged to the
  768. backend: refer to print_output_file for a full listing of supported variables; time-based
  769. variables are not allowed. Three examples follow:
  770. #1:
  771. print_output_file: /path/to/spool/foo-%Y%m%d-%H%M.txt
  772. print_latest_file: /path/to/spool/foo-latest
  773. #2:
  774. print_output_file: /path/to/spool/%Y/%Y-%m/%Y-%m-%d/foo-%Y%m%d-%H%M.txt
  775. print_latest_file: /path/to/spool/latest/foo
  776. #3:
  777. print_output_file: /path/to/$peer_src_ip/foo-%Y%m%d-%H%M.txt
  778. print_latest_file: /path/to//spool/latest/blabla-$peer_src_ip
  779. NOTES: Update of the latest pointer is done evaluating files name. For correct working of the
  780. feature, responsibility is put on the user. A file is reckon as latest if it is
  781. lexicographically greater than an existing one: this is generally fine but requires
  782. dates to be in %Y%m%d format rather than %d%m%Y. Also, upon restart of the daemon, if
  783. print_output_file is modified to a different location good practice would be to 1)
  784. manually delete latest pointer(s) or 2) move existing print_output_file files to the
  785. new targer location. Finally, if upgrading from pmacct releases before 1.5.0rc1, it is
  786. recommended to delete existing symlinks.
  787. DEFAULT: none
  788. KEY: sql_table_schema
  789. DESC: Full pathname to a file containing a SQL table schema. It allows to create the SQL table
  790. if it does not exist; this directive makes sense only if a dynamic 'sql_table' is in use.
  791. A configuration example where this directive could be useful follows:
  792. sql_history: 5m
  793. sql_history_roundoff: h
  794. sql_table: acct_v4_%Y%m%d_%H%M
  795. sql_table_schema: /usr/local/pmacct/acct_v4.schema
  796. In this configuration, the content of the file pointed by 'sql_table_schema' should be:
  797. CREATE TABLE acct_v4_%Y%m%d_%H%M (
  798. [ ... PostgreSQL/MySQL specific schema ... ]
  799. );
  800. This setup, along with this directive, are mostly useful when the dynamic tables are not
  801. closed in a 'ring' fashion (e.g., the days of the week) but 'open' (e.g., current date).
  802. DEFAULT: none
  803. KEY: sql_table_version (-v)
  804. VALUES [ 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ]
  805. DESC: Defines the version of the SQL table. SQL table versioning was introduced to achieve two
  806. goals: a) make tables work out-of-the-box for the SQL beginners, smaller installations
  807. and quick try-outs; and in this context b) to allow introduction of new features over
  808. time without breaking backward compatibility. For the SQL experts, the alternative to
  809. versioning is 'sql_optimize_clauses' which allows custom mix-and-match of primitives:
  810. in such a case you have to build yourself custom SQL schemas and indexes. Check in the
  811. 'sql/' sub-tree the SQL table profiles which are supported by the pmacct version you are
  812. currently using. It is always adviced to explicitely define a sql_table_version in
  813. order to predict which primitive will be written to which column. All versioning rules
  814. are captured in sql/README.[mysql|sqlite3|pgsql] documents.
  815. DEFAULT: 1
  816. KEY: sql_table_type
  817. VALUES [ original | bgp ]
  818. DESC: BGP-related primitives are divided in legacy and non-legacy. Legacy are src_as, dst_as;
  819. non-legacy are all the rest. Up to "original" tables v5 src_as and dst_as were written
  820. in the same field as src_host and dst_host. From "original" table v6 and if sql_table_type
  821. "bgp" is selected, src_as and dst_as are written in their own field (as_src and as_dst
  822. respectively). sql_table_type is by default set to "original" and is switched to "bgp"
  823. automatically if any non-legacy primitive is in use, ie. peer_dst_ip, as_path, etc. This
  824. directive allows to make the selection explicit and/or circumvent default behaviour.
  825. Apart from src_as and dst_as, regular table versioning applies to all non-BGP related
  826. fields, for example: a) if "sql_table_type: bgp" and "sql_table_version: 1" then the "tag"
  827. field will be written in the "agent_id" column whereas; b) if "sql_table_type: bgp" and
  828. "sql_table_version: 9" instead, then the "tag" field will be written in the "tag" column.
  829. All versioning rules are captured in sql/README.[mysql|sqlite3|pgsql] documents.
  830. DEFAULT: original
  831. KEY: sql_data
  832. VALUES: [ typed | unified ]
  833. DESC: This switch makes sense only when using PostgreSQL plugin and supplied default tables
  834. up to v5: the pgsql scripts in the sql/ tree, up to v5, will in fact create a 'unified'
  835. table along with multiple 'typed' tables. The 'unified' table has IP and MAC addresses
  836. specified as standard CHAR strings, slower and not space savy but flexible; 'typed'
  837. tables sport PostgreSQL own types (inet, mac, etc.), resulting in a faster but more
  838. rigid structure. Since v6 unified mode is being discontinued leading to simplification.
  839. The supplied 'typed' schema can still be customized, ie. to write IP addresses in CHAR
  840. fields because making use of IP prefix labels, transparently to pmacct - making this
  841. configuration switch deprecated.
  842. DEFAULT: typed
  843. KEY: sql_host
  844. DESC: Defines the backend server IP/hostname
  845. DEFAULT: localhost
  846. KEY: sql_user
  847. DESC: Defines the username to use when connecting to the server.
  848. DEFAULT: pmacct
  849. KEY: sql_passwd
  850. DESC: Defines the password to use when connecting to the server.
  851. DEFAULT: 'arealsmartpwd'
  852. KEY: [ sql_refresh_time | print_refresh_time | amqp_refresh_time | kafka_refresh_time ] (-r)
  853. DESC: Time interval, in seconds, between consecutive executions of the plugin cache scanner. The
  854. scanner purges data into the plugin backend. Note: internally all these config directives
  855. write to the same variable; when using multiple plugins it is recommended to bind refresh
  856. time definitions to specific plugins, ie.:
  857. plugins: mysql[x]
  858. sql_refresh_time[x]: 900
  859. As doing otherwise can originate unexpected behaviours.
  860. DEFAULT: 60
  861. KEY: [ sql_startup_delay | print_startup_delay | amqp_startup_delay | kafka_startup_delay ]
  862. DESC: Defines the time, in seconds, the first cache scan event has to be delayed. This delay
  863. is, in turn, propagated to the subsequent scans. It comes useful in two scenarios: a) so
  864. that multiple plugins can use the same refresh time (ie. sql_refresh_time) value, allowing
  865. them to spread the writes among the length of the time-bin; b) with NetFlow, when using
  866. a RDBMS, to keep original flow start time (nfacctd_time_new: false) while enabling the
  867. sql_dont_try_update feature (for RDBMS efficiency purposes); in such a context,
  868. sql_startup_delay value should be greater (better >= 2x the value) of the NetFlow active
  869. flow timeout.
  870. DEFAULT: 0
  871. KEY: sql_optimize_clauses
  872. VALUES: [ true | false ]
  873. DESC: Enables the optimization of the statements sent to the RDBMS essentially allowing to a)
  874. run stripped-down variants of the default SQL tables or b) totally customized SQL tables
  875. by a free mix-and-match of the available primitives. Either case, you will need to build
  876. the custom SQL table schema and indexes. As a rule of thumb when NOT using this directive
  877. always remember to specify which default SQL table version you intend to stick to by using
  878. the 'sql_table_version' directive.
  879. DEFAULT: false
  880. KEY: [ sql_history | print_history | amqp_history | kafka_history ]
  881. VALUES: #[s|m|h|d|w|M]
  882. DESC: Enables historical accounting by placing accounted data into configurable time-bins. It
  883. will use the 'stamp_inserted' (base time of the time-bin) and 'stamp_updated' (last time
  884. the time-bin was touched) fields. The supplied value defines the time slot length during
  885. which counters are accumulated. For a nice effect, it's adviceable to pair this directive
  886. with 'sql_history_roundoff'. In nfacctd, where a flow can span across multiple time-bins,
  887. flow counters can be pro-rated (seconds timestamp resolution) over involved time-bins by
  888. setting nfacctd_pro_rating to true. Note that this value is fully disjoint from the
  889. *_refresh_time directives which set the time intervals at which data has to be written to
  890. the backend instead. The final effect is close to time slots in a RRD file. Examples of
  891. valid values are: '300s' or '5m' - five minutes, '3600s' or '1h' - one hour, '14400s' or
  892. '4h' - four hours, '86400s' or '1d' - one day, '1w' - one week, '1M' - one month).
  893. DEFAULT: none
  894. KEY: [ sql_history_offset | print_history_offset | amqp_history_offset | kafka_history_offset ]
  895. DESC: Sets an offset to timeslots basetime. If history is set to 30 mins (by default creating
  896. 10:00, 10:30, 11:00, etc. time-bins), with an offset of 900 seconds (so 15 mins) it will
  897. create 10:15, 10:45, 11:15, etc. time-bins. It expects a positive value, in seconds.
  898. DEFAULT: 0
  899. KEY: [ sql_history_roundoff | print_history_roundoff | amqp_history_roundoff |
  900. kafka_history_roundoff ]
  901. VALUES [m,h,d,w,M]
  902. DESC: Enables alignment of minutes (m), hours (h), days of month (d), weeks (w) and months (M)
  903. in print (to print_refresh_time) and SQL plugins (to sql_history and sql_refresh_time).
  904. Suppose you go with 'sql_history: 1h', 'sql_history_roundoff: m' and it's 6:34pm. Rounding
  905. off minutes gives you an hourly timeslot (1h) starting at 6:00pm; so, subsequent ones will
  906. start at 7:00pm, 8:00pm, etc. Now, you go with 'sql_history: 5m', 'sql_history_roundoff: m'
  907. and it's 6:37pm. Rounding off minutes will result in a first slot starting at 6:35pm; next
  908. slot will start at 6:40pm, and then every 5 minutes (6:45pm ... 7:00pm, etc.). 'w' and 'd'
  909. are mutually exclusive, that is: you can either reset the date to last Monday or reset the
  910. date to the first day of the month.
  911. DEFAULT: none
  912. KEY: sql_recovery_backup_host
  913. DESC: Enables recovery mode; recovery mechanism kicks in if DB fails. It works by checking for
  914. the successful result of each SQL query. By default it is disabled. By using this key
  915. aggregates are recovered to a secondary DB. See INTERNALS 'Recovery modes' section for
  916. details about this topic. SQLite 3.x note: the plugin uses this directive to specify
  917. a the full path to an alternate database file (e.g., because you have multiple file
  918. system on a box) to use in the case the primary backend fails.
  919. DEFAULT: none
  920. KEY: [ sql_max_writers | print_max_writers | amqp_max_writers | kafka_max_writers ]
  921. DESC: Sets the maximum number of concurrent writer processes the plugin is allowed to start.
  922. This setting allows pmacct to degrade gracefully during major backend lock/outages/
  923. unavailability. The value is split as follows: up to N-1 concurrent processes will
  924. queue up; the Nth process will go for the recovery mechanism, if configured (ie.
  925. sql_recovery_backup_host for SQL plugins), writers beyond Nth will stop managing data
  926. (so, data will be lost at this stage) and an error message is printed out.
  927. DEFAULT: 10
  928. KEY: [ sql_cache_entries | print_cache_entries | amqp_cache_entries | kafka_cache_entries ]
  929. DESC: All plugins have a memory cache in order to store data until next purging event (see
  930. refresh time directives, ie. sql_refresh_time). In case of network traffic data, the
  931. cache allows to accumulate bytes and packets counters. This directive sets the number
  932. of cache buckets, the cache being structured in memory as a hash with conflict chains.
  933. Default value is suitable for mid-sized scenarios, however when facing large-scale
  934. networks, it is recommended to tune this parameter to improve performances (ie. keep
  935. conflict chains shorter). Cache entries value should be also reviewed if the amount
  936. of entries are not sufficient for a full refresh time interval - in which case a
  937. "Finished cache entries" informational message will appear in the logs. Use a prime
  938. number of buckets.
  939. NOTES: * non SQL plugins: the cache structure has two dimensions, a base and a depth. This
  940. setting defines the base (the amount of cache buckets) whereas the depth can't be
  941. influenced by configuration and is set to an average depth of 10. This means that
  942. the default value (16411) allows for approx 150K entries to fit the cache structure.
  943. To properly size a plugin cache, it is recommended to determine the maximum amount
  944. of entries purged by such plugin and make calculations basing on that; if, for
  945. example, the plugin purges a peak of 2M entries then a cache entries value of 259991
  946. is sufficient to cover the worse-case scenario. In case memory is constrained, the
  947. alternative option is to purge more often (ie. lower print_refresh_time) while
  948. retaining the same time-binning (ie. equal print_history) at the expense of having
  949. to consolidate/aggregate entries later in the collection pipeline; if opting for
  950. this, be careful having print_output_file_append set to true if using the print
  951. plugin).
  952. * SQL plugins: the cache structure is similar to the one described for the non SQL
  953. plugins but slightly different and more complex. Soon this cache structure will
  954. be removed and SQL plugins will be migrated to the same structure as the non SQL
  955. plugins, as described in the previous paragraph.
  956. * It is important to estimate how much space will take the base cache structure for
  957. a configured amount of cache entries - especially because configuring too many
  958. entries for the available memory can result in a crash of the plugin process right
  959. at startup. For this purpose, before trying to allocate the cache structure, the
  960. plugin will log an informational message saying "base cache memory=<size>". Why
  961. the wording "base cache memory": because cache entries, depending on the configured
  962. aggregation method, can have extra structures allocated ad-hoc, ie. BGP-, NAT-,
  963. MPLS-related primitives; all these can make the total cache memory size increase
  964. slightly at runtime.
  965. DEFAULT: print_cache_entries, amqp_cache_entries, kafka_cache_entries: 16411;
  966. sql_cache_entries: 32771
  967. KEY: sql_dont_try_update
  968. VALUES: [ true | false ]
  969. DESC: By default pmacct uses an UPDATE-then-INSERT mechanism to write data to the RDBMS; this
  970. directive instructs pmacct to use a more efficient INSERT-only mechanism. This directive
  971. is useful for gaining performances by avoiding UPDATE queries. Using this directive puts
  972. some timing constraints, specifically sql_history == sql_refresh_time, otherwise it may
  973. lead to duplicate entries and, potentially, loss of data. When used in nfacctd it also
  974. requires nfacctd_time_new to be enabled.
  975. DEFAULT: false
  976. KEY: sql_use_copy
  977. VALUES: [ true | false ]
  978. DESC: Instructs the plugin to build non-UPDATE SQL queries using COPY (in place of INSERT). While
  979. providing same functionalities of INSERT, COPY is also more efficient. To have effect, this
  980. directive requires 'sql_dont_try_update' to be set to true. It applies to PostgreSQL plugin
  981. only.
  982. NOTES: Error handling of the underlying PostgreSQL API is somewhat limited. During a COPY only
  983. transmission errors are detected but not syntax/semantic ones, ie. related to the query
  984. and/or the table schema.
  985. DEFAULT: false
  986. KEY: sql_delimiter
  987. DESC: If sql_use_copy is true, uses the supplied character as delimiter. This is thought in cases
  988. where the default delimiter is part of any of the supplied strings to be inserted into the
  989. database.
  990. DEFAULT: ','
  991. KEY: [ amqp_multi_values | sql_multi_values | kafka_multi_values ]
  992. DESC: In SQL plugin, sql_multi_values enables the use of multi-values INSERT statements. The value
  993. of the directive is intended to be the size (in bytes) of the multi-values buffer. The directive
  994. applies only to MySQL and SQLite 3.x plugins. Inserting many rows at the same time is much
  995. faster (many times faster in some cases) than using separate single-row INSERT statements.
  996. It's adviceable to check the size of this pmacct buffer against the size of the corresponding
  997. MySQL buffer (max_allowed_packet). In AMQP and Kafka plugins, [amqp|kafka]_multi_values allow
  998. the same with JSON serialization (for Avro see avro_buffer_size); in this case data is encoded
  999. in JSON objects newline-separated (preferred to JSON arrays for performance).
  1000. DEFAULT: 0
  1001. KEY: [ sql_trigger_exec | print_trigger_exec | amqp_trigger_exec | kafka_trigger_exec ]
  1002. DESC: Defines the executable to be launched at fixed time intervals to post-process aggregates;
  1003. in SQL plugins, intervals are specified by the 'sql_trigger_time' directive; if no interval
  1004. is supplied 'sql_refresh_time' value is used instead: this will result in a trigger being
  1005. fired each purging event. A number of environment variables are set in order to allow the
  1006. trigger to take actions; take a look to docs/TRIGGER_VARS to check them out. In the print
  1007. plugin a simpler implementation is made: triggers can be fired each time data is written to
  1008. the backend (ie. print_refresh_time) and no environment variables are passed over to the
  1009. executable.
  1010. DEFAULT: none
  1011. KEY: sql_trigger_time
  1012. VALUES: #[s|m|h|d|w|M]
  1013. DESC: Specifies time interval at which the executable specified by 'sql_trigger_exec' has to
  1014. be launched; if no executables are specified, this key is simply ignored. Values need to be
  1015. in the 'sql_history' directive syntax (for example, valid values are '300' or '5m', '3600'
  1016. or '1h', '14400' or '4h', '86400' or '1d', '1w', '1M'; eg. if '3600' or '1h' is selected,
  1017. the executable will be fired each hour).
  1018. DEFAULT: none
  1019. KEY: [ sql_preprocess | print_preprocess | amqp_preprocess | kafka_preprocess ]
  1020. DESC: Allows to process aggregates (via a comma-separated list of conditionals and checks) while
  1021. purging data to the backend thus resulting in a powerful selection tier; aggregates filtered
  1022. out may be just discarded or saved through the recovery mechanism (if enabled, if supported
  1023. by the backend). The set of available preprocessing directives follows:
  1024. KEY: qnum
  1025. DESC: conditional. Subsequent checks will be evaluated only if the number of queries to be
  1026. created during the current cache-to-DB purging event is '>=' qnum value. SQL plugins
  1027. only.
  1028. KEY: minp
  1029. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1030. only if the number of packets is '>=' minp value. All plugins.
  1031. KEY: minf
  1032. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1033. only if the number of flows is '>=' minf value. All plugins.
  1034. KEY: minb
  1035. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1036. only if the bytes counter is '>=' minb value. An interesting idea is to set its value
  1037. to a fraction of the link capacity. Remember that you have also a timeframe reference:
  1038. the 'sql_refresh_time' seconds. All plugins.
  1039. For example, given the following parameters:
  1040. Link Capacity = 8Mbit/s, THreshold = 0.1%, TImeframe = 60s
  1041. minb = ((LC / 8) * TI) * TH -> ((8Mbit/s / 8) * 60s) * 0.1% = 60000 bytes.
  1042. Given a 8Mbit link, all aggregates which have accounted for at least 60Kb of traffic
  1043. in the last 60 seconds, will be written to the DB.
  1044. KEY: maxp
  1045. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1046. only if the number of packets is '<' maxp value. SQL plugins only.
  1047. KEY: maxf
  1048. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1049. only if the number of flows is '<' maxf value. SQL plugins only.
  1050. KEY: maxb
  1051. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1052. only if the bytes counter is '<' maxb value. SQL plugins only.
  1053. KEY: maxbpp
  1054. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1055. only if the number of bytes per packet is '<' maxbpp value. SQL plugins only.
  1056. KEY: maxppf
  1057. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1058. only if the number of packets per flow is '<' maxppf value. SQL plugins only.
  1059. KEY: minbpp
  1060. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1061. only if the number of bytes per packet is '>=' minbpp value. All plugins.
  1062. KEY: minppf
  1063. DESC: check. Aggregates on the queue are evaluated one-by-one; each object is marked valid
  1064. only if the number of packets per flow is '>=' minppf value. All plugins.
  1065. KEY: fss
  1066. DESC: check. Enforces flow (aggregate) size dependent sampling, computed against the bytes
  1067. counter and returns renormalized results. Aggregates which have collected more than the
  1068. supplied 'fss' threshold in the last time window (specified by the 'sql_refresh_time'
  1069. configuration key) are sampled. Those under the threshold are sampled with probability
  1070. p(bytes). The method allows to get much more accurate samples compared to classic 1/N
  1071. sampling approaches, providing an unbiased estimate of the real bytes counter. It would
  1072. be also adviceable to hold the the equality 'sql_refresh_time' = 'sql_history'.
  1073. For further references: http://www.research.att.com/projects/flowsamp/ and specifically
  1074. to the papers: N.G. Duffield, C. Lund, M. Thorup, "Charging from sampled network usage",
  1075. http://www.research.att.com/~duffield/pubs/DLT01-usage.pdf and N.G. Duffield and C. Lund,
  1076. "Predicting Resource Usage and Estimation Accuracy in an IP Flow Measurement Collection
  1077. Infrastructure", http://www.research.att.com/~duffield/pubs/p313-duffield-lund.pdf
  1078. SQL plugins only.
  1079. KEY: fsrc
  1080. DESC: check. Enforces flow (aggregate) sampling under hard resource constraints, computed
  1081. against the bytes counter and returns renormalized results. The method selects only 'fsrc'
  1082. flows from the set of the flows collected during the last time window ('sql_refresh_time'),
  1083. providing an unbiasied estimate of the real bytes counter. It would be also adviceable
  1084. to hold the equality 'sql_refresh_time' = 'sql_history'.
  1085. For further references: http://www.research.att.com/projects/flowsamp/ and specifically
  1086. to the paper: N.G. Duffield, C. Lund, M. Thorup, "Flow Sampling Under Hard Resource
  1087. Constraints", http://www.research.att.com/~duffield/pubs/DLT03-constrained.pdf
  1088. SQL plugins only.
  1089. KEY: usrf
  1090. DESC: action. Applies the renormalization factor 'usrf' to counters of each aggregate. Its use
  1091. is suitable for use in conjunction with uniform sampling methods (for example simple random
  1092. - e.g. sFlow, 'sampling_rate' directive or simple systematic - e.g. sampled NetFlow by
  1093. Cisco and Juniper). The factor is applied to recovered aggregates also. It would be also
  1094. adviceable to hold the equality 'sql_refresh_time' = 'sql_history'. Before using this action
  1095. to renormalize counters generated by sFlow, take also a read of the 'sfacctd_renormalize'
  1096. key. SQL plugins only.
  1097. KEY: adjb
  1098. DESC: action. Adds (or subtracts) 'adjb' bytes to the bytes counter multiplied by the number of
  1099. packet in each aggregate. This is a particularly useful action when - for example - fixed
  1100. lower (link, llc, etc.) layer sizes need to be included into the bytes counter (as explained
  1101. by Q7 in FAQS document). SQL plugins only.
  1102. KEY: recover
  1103. DESC: action. If previously evaluated checks have marked the aggregate as invalid, a positive
  1104. 'recover' value makes the packet to be handled through the recovery mechanism (if enabled).
  1105. SQL plugins only.
  1106. For example, during a data purge, in order to filter in only aggregates counting 100KB or more
  1107. the following line can be used to instrument the print plugin: 'print_preprocess: minb=100000'.
  1108. DEFAULT: none
  1109. KEY: [ sql_preprocess_type | print_preprocess_type | amqp_preprocess_type | kafka_preprocess_type ]
  1110. VALUES: [ any | all ]
  1111. DESC: When more checks are to be evaluated, this directive tells whether aggregates on the queue
  1112. are valid if they just match one of the checks (any) or all of them (all).
  1113. DEFAULT: any
  1114. KEY: timestamps_secs
  1115. VALUES: [ true | false ]
  1116. DESC: Sets timestamp (timestamp_start, timestamp_end, timestamp_arrival primitives) resolution to
  1117. seconds, ie. prevents residual time fields like timestamp_start_residual to be populated.
  1118. In nfprobe plugin, when exporting via NetFlow v9 (nfprobe_version: 9), allows to fallback
  1119. to first and last swithed times in seconds.
  1120. DEFAULT: false
  1121. KEY: timestamps_since_epoch
  1122. VALUES [ true | false ]
  1123. DESC: All timestamps (ie. timestamp_start, timestamp_end, timestamp_arrival primitives; sql_history-
  1124. related fields stamp_inserted, stamp_updated; etc.) in the standard seconds since the Epoch
  1125. format. This not only makes output more compact but also prevents computationally expensive
  1126. time-formatting functions to be invoked, resulting in speed gains at purge time. In case the
  1127. output is to a RDBMS, setting this directive to true will require changes to the default types
  1128. for timestamp fields in the SQL schema.
  1129. MySQL: DATETIME ==> INT(8) UNSIGNED
  1130. PostgreSQL: timestamp without time zone ==> bigint
  1131. SQLite3: DATETIME ==> INT(8)
  1132. DEFAULT: false
  1133. KEY: [ print_markers | amqp_markers | kafka_markers ]
  1134. VALUES: [ true | false ]
  1135. DESC: Enables the use of start/end markers each time data is purged to the backend. Both start
  1136. and end markers return additional information, ie. writer PID, number of entries purged,
  1137. elapsed time, etc. When plugin output is in JSON or Avro plugin outputs, markers are
  1138. encoded in JSON format and event_type is set to purge_init and purge_close respectively.
  1139. In the case of Kafka topics with multiple partitions, the purge_close message can arrive
  1140. out of order so other mechanisms should be used to correlate messages as being part of
  1141. the same batch (ie. writer_id).
  1142. DEFAULT: false
  1143. KEY: print_output
  1144. VALUES: [ formatted | csv | json | avro | event_formatted | event_csv ]
  1145. DESC: Defines the print plugin output format. 'formatted' enables tabular output; 'csv' is to enable
  1146. comma-separated values format, suitable for injection into 3rd party tools. 'event' versions of
  1147. the output strips trailing bytes and packets counters. 'json' is to enable JavaScript Object
  1148. Notation format, also suitable for injection into 3rd party tools. Being a self-descriptive
  1149. format (hence not requiring a table title), JSON does not require a event-counterpart; on the
  1150. cons, JSON serialization introduces some lag due to the extensive string manipulation (as an
  1151. example: 10M lines may be written to disk in 30 secs as CSV and 150 secs as JSON). The 'json'
  1152. format requires compiling the package against Jansson library (downloadable at the following
  1153. URL: http://www.digip.org/jansson/). 'avro' enables storing the data using the Apache Avro
  1154. data serialization system. This format stores the data more compactly than JSON and thus is
  1155. more appropriate for intensive captures. The 'avro' format requires compiling the package
  1156. against the Apache Avro library (downloadable at the following URL: http://avro.apache.org/).
  1157. NOTES: * Jansson and Avro libraries don't have the concept of unsigned integers. integers up to 32
  1158. bits are packed as 64 bits signed integers, working around the issue. No work around is
  1159. possible for unsigned 64 bits integers instead (ie. tag, tag2, packets, bytes).
  1160. * If the output format is 'avro' and no print_output_file was specified, the Avro-based
  1161. representation of the data will be converted to JSON and displayed on the standard output.
  1162. DEFAULT: formatted
  1163. KEY: print_output_separator
  1164. DESC: Defines the print plugin output separator when print_output is set to csv or event_csv. Value
  1165. is expected to be a single character and cannot be a spacing (if spacing separator is wanted
  1166. then 'formatted' output should be the natural choice instead)
  1167. DEFAULT: ','
  1168. KEY: [ amqp_output | kafka_output ]
  1169. VALUES: [ json | avro ]
  1170. DESC: Defines the output format for messages sent to a message broker (amqp and kafka plugins).
  1171. 'json' is to send the messages in the JavaScript Object Notation format. The 'json' format
  1172. requires compiling the package against the Jansson library (downloadable at the following URL
  1173. : http://www.digip.org/jansson/). 'avro' is to send the messages encoded with the Apache Avro
  1174. serialization system. The 'avro' format requires compiling the package against the Apache Avro
  1175. library (downloadable at the following URL: http://avro.apache.org/).
  1176. NOTES: * Jansson and Avro libraries don't have the concept of unsigned integers. integers up to 32
  1177. bits are packed as 64 bits signed integers, working around the issue. No work around is
  1178. possible for unsigned 64 bits integers instead (ie. tag, tag2, packets, bytes).
  1179. DEFAULT: json
  1180. KEY: avro_buffer_size
  1181. DESC: When the Avro format is used to encode the messages sent to a message broker (amqp and kafka
  1182. plugins), this option defines the size in bytes of the buffer used by the Avro data serialization
  1183. system. The buffer needs to be large enough to store at least a single Avro record. If the
  1184. buffer does not have enough capacity to store the number of records defined by the
  1185. [amqp, kafka]_multi_values configuration directive, the current records stored in the buffer
  1186. will be sent to the message broker and the buffer will be cleared to accomodate subsequent
  1187. records.
  1188. DEFAULT: 8192
  1189. KEY: avro_schema_output_file
  1190. DESC: When the Avro format is used to encode the messages sent to a message broker (amqp and kafka
  1191. plugins), this option causes the schema used to encode the messages to be dumped to the file
  1192. path given. The schema can then be used by the receiving end to decode the messages. Note
  1193. that the schema will be dynamically built based on the aggregation primitives chosen. This
  1194. has also effect in the print plugin but in this case the schema is also always included in
  1195. the print_output_file as mandated by Avro specification.
  1196. KEY: [ amqp_avro_schema_routing_key | kafka_avro_schema_topic ]
  1197. DESC: AMQP routing key or Kafka topic on which the generated Avro schema is sent over at regular
  1198. time intervals by AMQP and Kafka plugins (it can potentially be the same as kafka_topic or
  1199. amqp_routing_key). The schema can then be used by the receiving end to decode the messages.
  1200. All other parameters to connect to the broker, ie. host, port, etc. are shared with the main
  1201. plugin routing key or topic. The time intervals are set via amqp_avro_schema_refresh_time
  1202. and kafka_avro_schema_refresh_time. Schemas are carried as part of the 'schema' field in
  1203. an envelope JSON message with 'event_type' set to purge_schema.
  1204. DEFAULT: none
  1205. KEY: [ amqp_avro_schema_refresh_time | kafka_avro_schema_refresh_time ]
  1206. DESC: Time interval, in seconds, at which the generated Avro schema is sent over the configured
  1207. AMQP routing key (amqp_avro_schema_routing_key) or Kafka topic (kafka_avro_schema_topic).
  1208. DEFAULT: 60
  1209. KEY: [ print_num_protos | sql_num_protos | amqp_num_protos | kafka_num_protos ]
  1210. VALUES: [ true | false ]
  1211. DESC: Defines whether IP protocols (ie. tcp, udp) should be looked up and presented in string format
  1212. or left numerical. The default is to look protocol names up.
  1213. DEFAULT: false
  1214. KEY: sql_num_hosts
  1215. VALUES: [ true | false ]
  1216. DESC: Defines whether IP addresses should be left numerical (in network bytes ordering) or converted
  1217. into human-readable strings. Applies to MySQL and SQLite plugins only and assumes the INET_ATON()
  1218. and INET6_ATON() function are defined in the RDBMS. INET_ATON() is always defined in MySQL whereas
  1219. INET6_ATON() requires MySQL >= 5.6.3. Both functions are not defined by default in SQLite instead
  1220. and are to be user-defined: if pmacct is compiled with --disable-ipv6, a INET_ATON() function is
  1221. invoked; if pmacct is compiled with --enable-ipv6 (default), a INET6_ATON() function is invoked.
  1222. The feature is not compatible with making use of IP prefix labels. Default setting, false, is to
  1223. convert IP addresses and prefixes into strings.
  1224. DEFAULT: false
  1225. KEY: [ nfacctd_port | sfacctd_port ] (-l) [GLOBAL, NO_PMACCTD, NO_UACCTD]
  1226. DESC: Defines the UDP port where to bind nfacctd (nfacctd_port) and sfacctd (sfacctd_port) daemons.
  1227. DEFAULT: nfacctd_port: 2100; sfacctd_port: 6343
  1228. KEY: [ nfacctd_ip | sfacctd_ip ] (-L) [GLOBAL, NO_PMACCTD, NO_UACCTD]
  1229. DESC: Defines the IPv4/IPv6 address where to bind the nfacctd (nfacctd_ip) and sfacctd (sfacctd_ip)
  1230. daemons.
  1231. DEFAULT: all interfaces
  1232. KEY: core_proc_name
  1233. DESC: Defines the name of the core process. This is the equivalent to instantiate named plugins but
  1234. for the core process.
  1235. DEFAULT: 'default'
  1236. KEY: proc_priority
  1237. DESC: Redefines the process scheduling priority, equivalent to using the 'nice' tool. Each daemon
  1238. process, ie. core, plugins, etc., can define a different priority.
  1239. DEFAULT: 0
  1240. KEY: [ nfacctd_allow_file | sfacctd_allow_file ] [GLOBAL, NO_PMACCTD, NO_UACCTD]
  1241. DESC: Full pathname to a file containing the list of IPv4/IPv6 addresses (one for each line) allowed
  1242. to send packets to the daemon. Current syntax does not implement network masks but individual
  1243. IP addresses only. The Allow List is intended to be small; firewall rules should be preferred
  1244. to long ACLs.
  1245. DEFAULT: none (ie. allow all)
  1246. KEY: nfacctd_time_secs [GLOBAL, NFACCTD_ONLY]
  1247. VALUES: [ true | false ]
  1248. DESC: Makes 'nfacctd' expect times included in NetFlow header to be in seconds rather than msecs. This
  1249. knob makes sense for NetFlow up to v8 - as in NetFlow v9 and IPFIX different fields are reserved
  1250. for secs and msecs timestamps, increasing collector awareness.
  1251. DEFAULT: false
  1252. KEY: [ nfacctd_time_new | pmacctd_time_new | sfacctd_time_new ] [GLOBAL, NO_UACCTD]
  1253. VALUES: [ true | false ]
  1254. DESC: Makes the daemon to ignore external timestamps associated to data, ie. included in NetFlow
  1255. header or pcap header, and generate new ones (reflecting data arrival time to the collector).
  1256. This gets particularly useful to assign flows to time-bins based on the flow arrival time at
  1257. the collector rather than the flow original (start) time.
  1258. DEFAULT: false
  1259. KEY: nfacctd_pro_rating [NFACCTD_ONLY]
  1260. VALUES: [ true | false ]
  1261. DESC: If nfacctd_time_new is set to false (default) and historical accounting (ie. sql_history) is
  1262. enabled, this directive enables pro rating of NetFlow/IPFIX flows over time-bins, if needed.
  1263. For example, if sql_history is set to '5m' (so 300 secs), the considered flow duration is 1000
  1264. secs, its bytes counter is 1000 bytes and, for simplicity, its start time is at the base time
  1265. of t0, time-bin 0, then the flow is inserted in time-bins t0, t1, t2 and t3 and its bytes
  1266. counter is proportionally split among these time-bins: 300 bytes during t0, t1 and t2 and
  1267. 100 bytes during t3.
  1268. NOTES: If NetFlow sampling is enabled, it is recommended to have counters renormalization enabled
  1269. (nfacctd_renormalize set to true).
  1270. DEFAULT: false
  1271. KEY: nfacctd_templates_file [NFACCTD_ONLY]
  1272. DESC: Full pathname to a file containing serialized templates data from previous nfacctd use.
  1273. Templates are loaded from this file when nfacctd is (re)started in order to reduce the
  1274. amount of dropped packets due to unknown templates. Be aware that this file will be
  1275. written to with possible new templates and updated versions of provided ones. Hence, an
  1276. empty file can be specified and incoming templates will be cached into it. This file
  1277. will be created if it does not exist. Only JSON format is currently supported and
  1278. requires compiling against Jansson library (--enable-jansson when configuring for
  1279. compiling).
  1280. DEFAULT: none
  1281. KEY: [ nfacctd_stitching | sfacctd_stitching | pmacctd_stitching | uacctd_stitching ]
  1282. VALUES: [ true | false ]
  1283. DESC: If set to true adds two new fields, timestamp_min and timestamp_max: given an aggregation
  1284. method ('aggregate' config directive), timestamp_min is the timestamp of the first element
  1285. contributing to a certain aggregate, timestamp_max is the timestamp of the last element. In
  1286. case the export protocol provides time references, ie. NetFlow/IPFIX, these are used; if not
  1287. of if using NetFlow/IPFIX as export protocol and nfacctd_time_new is set to true the current
  1288. time (hence time of arrival to the collector) is used instead. The feature is not compatible
  1289. with pro-rating, ie. nfacctd_pro_rating. Also, the feature is supported on all plugins except
  1290. the 'memory' one (please get in touch if you have a use-case for it).
  1291. DEFAULT: false
  1292. KEY: nfacctd_account_options [GLOBAL, NFACCTD_ONLY]
  1293. VALUES: [ true | false ]
  1294. DESC: If set to true account for NetFlow/IPFIX option records. This will require define custom
  1295. primitives via aggregate_primitives. pre_tag_map offers sample_type value of 'option' in
  1296. order to split option data records from flow or event data ones.
  1297. DEFAULT: false
  1298. KEY: [ nfacctd_as | sfacctd_as | pmacctd_as | uacctd_as ] [GLOBAL]
  1299. VALUES: [ netflow | sflow | file | bgp | longest ]
  1300. DESC: When set to 'netflow' or 'sflow' it instructs nfacctd and sfacctd to populate 'src_as',
  1301. 'dst_as', 'peer_src_as' and 'peer_dst_as' primitives from information in NetFlow and sFlow
  1302. datagrams; when set to 'file', it instructs nfacctd and sfacctd to populate 'src_as',
  1303. 'dst_as' and 'peer_dst_as' by looking up source and destination IP addresses against a
  1304. supplied networks_file. When 'bgp' is specified, source and destination IP addresses are
  1305. looked up against the BGP RIB of the peer from which the NetFlow (or sFlow) datagram was
  1306. received (see also bgp_agent_map directive for more complex mappings). 'longest' behaves
  1307. in a longest-prefix match wins fashion: in nfacctd and sfacctd lookup is done against a
  1308. networks_file (if specified), sFlow/NetFlow protocol and BGP (if the BGP thread is started)
  1309. with the following logics: networks_file < sFlow/NetFlow < <= BGP.
  1310. In pmacctd and uacctd: 'file' expects a 'networks_file' to be defined; 'bgp' just works
  1311. as described previously for nfacctd and sfacctd; 'longest' lookup is done against a
  1312. networks_file and BGP only (networks_file <= BGP) since no export protocol lookup method
  1313. is available. Read nfacctd_net description for an example of operation of the 'longest'
  1314. method.
  1315. Unless there is a specific goal do achieve, it is highly recommended that this definition,
  1316. ie. nfacctd_as, is kept in sync with its net equivalent, ie. nfacctd_net.
  1317. DEFAULT: none
  1318. KEY: [ nfacctd_net | sfacctd_net | pmacctd_net | uacctd_net ] [GLOBAL]
  1319. VALUES: [ netflow | sflow | mask | file | igp | bgp | longest ]
  1320. DESC: Determines the method for performing IP prefix aggregation - hence directly influencing 'src_net',
  1321. 'dst_net', 'src_mask', 'dst_mask' and 'peer_dst_ip' primitives. 'netflow' and 'sflow' get values
  1322. from NetFlow and sFlow protocols respectively; these keywords are only valid in nfacctd, sfacctd.
  1323. 'mask' applies a defined networks_mask; 'file' selects a defined networks_file; 'igp' and 'bgp'
  1324. source values from IGP/IS-IS daemon and BGP daemon respectively. For backward compatibility, the
  1325. default behaviour in pmacctd and uacctd is: 'mask' and 'file' are turned on if a networks_mask and
  1326. a networks_file are respectively specified by configuration. If they are both defined, the outcome
  1327. will be the intersection of their definitions. 'longest' behaves in a longest-prefix match wins
  1328. fashion: in nfacctd and sfacctd lookup is done against a networks list (if networks_file is defined)
  1329. sFlow/NetFlow protocol, IGP (if the IGP thread started) and BGP (if the BGP thread is started) with
  1330. the following logics: networks_file < sFlow/NetFlow < IGP <= BGP; in pmacctd and uacctd lookup is
  1331. done against ia networks list, IGP and BGP only (networks_file < IGP <= BGP). For example we receive
  1332. the following PDU via NetFlow:
  1333. SrcAddr: 10.0.8.29 (10.0.8.29)
  1334. DstAddr: 192.168.5.47 (192.168.5.47)
  1335. [ .. ]
  1336. SrcMask: 24 (prefix: 10.0.8.0/24)
  1337. DstMask: 27 (prefix: 192.168.5.32/27)
  1338. a BGP peering is available and BGP contains the following prefixes: 192.168.0.0/16 and 10.0.0.0/8.
  1339. A networks_file contains the prefixes 10.0.8.0/24 and 192.168.5.0/24. 'longest' would select as
  1340. outcome of the network aggregation process 10.0.8.0/24 for the src_net and src_mask respectively
  1341. and 192.168.5.32/27 for dst_net and dst_mask.
  1342. Unless there is a specific goal to achieve, it is highly recommended that the definition of this
  1343. configuration directive is kept in sync with its ASN equivalent, ie. nfacctd_as.
  1344. DEFAULT: nfacctd: 'netflow'; sfacctd: 'sflow'; pmacctd and uacctd: 'mask', 'file'
  1345. KEY: use_ip_next_hop [GLOBAL]
  1346. VALUES: [ true | false ]
  1347. DESC: When IP prefix aggregation (ie. nfacctd_net) is set to 'netflow', 'sflow' or 'longest' (in
  1348. which case longest winning match is via 'netflow' or 'sflow') populate 'peer_dst_ip' field
  1349. from NetFlow/sFlow IP next hop field if BGP next-hop is not available.
  1350. DEFAULT: false
  1351. KEY: [ nfacctd_mcast_groups | sfacctd_mcast_groups ] [GLOBAL, NO_PMACCTD, NO_UACCTD]
  1352. DESC: Defines one or more IPv4/IPv6 multicast groups to be joined by the daemon. If more groups are
  1353. supplied, they are expected comma separated. A maximum of 20 multicast groups may be joined by
  1354. a single daemon instance. Some OS (noticeably Solaris -- seems) may also require an interface
  1355. to bind to which - in turn - can be supplied declaring an IP address ('nfacctd_ip' key).
  1356. DEFAULT: none
  1357. KEY: [ nfacctd_disable_checks | sfacctd_disable_checks ] [GLOBAL, NO_PMACCTD, NO_UACCTD]
  1358. VALUES: [ true | false ]
  1359. DESC: Both nfacctd and sfacctd can log warning messages for failing basic checks against incoming
  1360. NetFlow/sFlow datagrams, ie. sequence number checks, protocol version. You may want to disable
  1361. such feature, default, because of buggy or non-standard implementations. Also, for sequencing
  1362. checks, the 'export_proto_seqno' primitive is recommended instead (see 'aggregate' description
  1363. and notes).
  1364. DEFAULT: true
  1365. KEY: nfacctd_disable_opt_scope_check [GLOBAL, ONLY_NFACCTD]
  1366. VALUES: [ true | false ]
  1367. DESC: Mainly a workaround to implementations not encoding NetFlow v9/IPIFX option scope correctly,
  1368. this knob allows to disable option scope checking. By doing so, options are considered scoped
  1369. to the system level (ie. to the IP address of the expoter).
  1370. DEFAULT: false
  1371. KEY: pre_tag_map [MAP]
  1372. DESC: Full pathname to a file containing tag mappings. Tags can be internal-only (ie. for filtering
  1373. purposes, see pre_tag_filter configuration directive) or exposed to users (ie. if 'tag', 'tag2'
  1374. and/or 'label' primitives are part of the aggregation method). Take a look to the examples/
  1375. sub-tree for all supported keys and detailed examples (pretag.map.example). Pre-Tagging is
  1376. evaluated in the Core Process and each plugin can be defined a local pre_tag_map. Result of
  1377. evaluation of pre_tag_map overrides any tags passed via NetFlow/sFlow by a pmacct nfprobe/
  1378. sfprobe plugin. Number of map entries (by default 384) can be modified via maps_entries.
  1379. Content can be reloaded at runtime by sending the daemon a SIGUSR2 signal (ie. "killall -USR2
  1380. nfacctd").
  1381. DEFAULT: none
  1382. KEY: maps_entries
  1383. DESC: Defines the maximum number of entries a map (ie. pre_tag_map and all directives with the
  1384. 'MAP' flag in this document) can contain. The default value is suitable for most scenarios,
  1385. though tuning it could be required either to save on memory or to allow for more entries.
  1386. Refer to the specific map directives documentation in this file to see which are affected by
  1387. this setting.
  1388. DEFAULT: 384
  1389. KEY: maps_row_len
  1390. DESC: Defines the maximum length of map (ie. pre_tag_map and all directives with the 'MAP' flag in
  1391. this document) rows. The default value is suitable for most scenario, though tuning it could
  1392. be required either to save on memory or to allow for more entries.
  1393. DEFAULT: 256
  1394. KEY: maps_refresh [GLOBAL]
  1395. VALUES: [ true | false ]
  1396. DESC: When enabled, this directive allows to reload map files (ie. pre_tag_map and all directives
  1397. with the 'MAP' flag in this document) without restarting the daemon instance. For example,
  1398. it may result particularly useful to reload pre_tag_map or networks_file entries in order
  1399. to reflect some change in the network. After having modified the map files, a SIGUSR2 has
  1400. to be sent (e.g.: in the simplest case "killall -USR2 pmacctd") to the daemon to notify the
  1401. change. If such signal is sent to the daemon and this directive is not enabled, the signal
  1402. is silently discarded. The Core Process is in charge of processing the Pre-Tagging map;
  1403. plugins are devoted to Networks and Ports maps instead. Then, because signals can be sent
  1404. either to the whole daemon (killall) or to just a specific process (kill), this mechanism
  1405. also offers the advantage to elicit local reloads.
  1406. DEFAULT: true
  1407. KEY: maps_index [GLOBAL]
  1408. VALUES: [ true | false ]
  1409. DESC: Enables indexing of maps (ie. pre_tag_map and all directives with the 'MAP' flag in this
  1410. document) to increase lookup speeds on large maps and/or sustained lookup rates. Indexes
  1411. are automatically defined basing on structure and content of the map, up to a maximum of
  1412. 8. Indexing of pre_tag_map, bgp_peer_src_as_map, flow_to_rd_map is supported. Only a sub-
  1413. set of pre_tag_map fields are supported, including: ip, bgp_nexthop, vlan, cvlan, src_mac,
  1414. mpls_vpn_rd, src_as, dst_as, peer_src_as, peer_dst_as, input, output. Only IP addresses,
  1415. ie. no IP prefixes, are supported as part of the 'ip' field. Also, negations are not
  1416. supported (ie. 'in=-216' match all but input interface 216). bgp_agent_map and sampling_map
  1417. implement a separate caching mechanism and hence do not leverage this feature. Duplicates
  1418. in the key part of the map entry, key being defined as all fields except set_* ones, are
  1419. not supported and may result in a "out of index space" message.
  1420. DEFAULT: false
  1421. KEY: pre_tag_filter, pre_tag2_filter [NO_GLOBAL]
  1422. VALUES: [ 0-2^64-1 ]
  1423. DESC: Expects one or more tags (when multiple tags are supplied, they need to be comma separated
  1424. and a logical OR is used in the evaluation phase) as value and allows to filter aggregates
  1425. basing upon their tag (or tag2) value: in case of a match, the aggregate is filtered in, ie.
  1426. it is delivered to the plugin it is attached to. This directive has to be attached to a
  1427. plugin (that is, it cannot be global) and is suitable, for example, to split tagged data
  1428. among the active plugins. This directive also allows to specify a value '0' to match untagged
  1429. data, thus allowing to split tagged traffic from untagged one. It also allows negations by
  1430. pre-pending a minus sign to the tag value (ie. '-6' would send everything but traffic tagged
  1431. as '6' to the plugin it is attached to, hence achieving a filter out behaviour) and ranges
  1432. (ie. '10-20' would send over traffic tagged in the range 10..20) and any combination of these.
  1433. This directive makes sense if coupled with 'pre_tag_map'.
  1434. DEFAULT: none
  1435. KEY: pre_tag_label_filter [NO_GLOBAL]
  1436. DESC: Expects one or more labels (when multiple labels are supplied, they need to be comma
  1437. separated and a logical OR is used in the evaluation phase) as value and allows to filter in
  1438. aggregates basing upon their label value(s): only in case of match data is delivered to the
  1439. plugin. This directive has to be attached to a plugin (that is, it cannot be global). Null
  1440. label values (ie. unlabelled data) can be matched using the 'null' keyword. Negations are
  1441. allowed by pre-pending a minus sign to the label value. The use of this directive makes
  1442. sense if coupled with 'pre_tag_map'.
  1443. DEFAULT: none
  1444. KEY: [ post_tag | post_tag2 ]
  1445. VALUES: [ 1-2^64-1 ]
  1446. DESC: Expects a tag as value. Post-Tagging is evaluated in the plugins. The tag is used as 'tag'
  1447. (post_tag) or 'tag2' (post_tag2) primitive value. Use of these directives hence makes sense
  1448. if tag and/or tag2 primitives are part of the plugin aggregation method.
  1449. DEFAULT: none
  1450. KEY: sampling_rate
  1451. VALUES: [ >= 1 ]
  1452. DESC: Enables packet sampling. It expects a number which is the mean ratio of packets to be sampled
  1453. (1 out of N). The currently implemented sampling algorithm is a simple randomic one. If using
  1454. any SQL plugin, look also to the powerful 'sql_preprocess' layer and the more advanced sampling
  1455. choices it offers: they will allow to deal with advanced sampling scenarios (e.g. probabilistic
  1456. methods). Finally, note that this 'sampling_rate' directive can be renormalized by using the
  1457. 'usrf' action of the 'sql_preprocess' layer.
  1458. DEFAULT: none
  1459. KEY: sampling_map [GLOBAL, NO_PMACCTD, NO_UACCTD, MAP]
  1460. DESC: Full pathname to a file containing traffic sampling mappings. It is mainly meant to be used
  1461. in conjunction with nfacctd and sfacctd for the purpose of fine-grained reporting of sampling
  1462. rates circumventing bugs and issues in router operating systems. Renormalization must be
  1463. enabled (nfacctd_renormalize or sfacctd_renormalize set to true) in order for the feature to
  1464. work. If a specific router is not defined in the map, the sampling rate advertised by the
  1465. router itself is applied. Take a look to the examples/ sub-tree 'sampling.map.example' for all
  1466. supported keys and detailed examples. Number of map entries (by default 384) can be modified
  1467. via maps_entries. Content can be reloaded at runtime by sending the daemon a SIGUSR2 signal
  1468. (ie. "killall -USR2 nfacctd").
  1469. DEFAULT: none
  1470. KEY: [ pmacctd_force_frag_handling | uacctd_force_frag_handling ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1471. VALUES: [ true | false ]
  1472. DESC: Forces 'pmacctd' to join together IPv4/IPv6 fragments: 'pmacctd' does this only whether any of
  1473. the port primitives are selected (src_port, dst_port, sum_port); in fact, when not dealing with
  1474. any upper layer primitive, fragments are just handled as normal packets. However, available
  1475. filtering rules ('aggregate_filter', Pre-Tag filter rules) will need such functionality enabled
  1476. whether they need to match TCP/UDP ports. So, this directive aims to support such scenarios.
  1477. DEFAULT: false
  1478. KEY: [ pmacctd_frag_buffer_size | uacctd_frag_buffer_size ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1479. DESC: Defines the maximum size of the fragment buffer. In case IPv6 is enabled two buffers of equal
  1480. size will be allocated. The value is expected in bytes.
  1481. DEFAULT: 4MB
  1482. KEY: [ pmacctd_flow_buffer_size | uacctd_flow_buffer_size ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1483. DESC: Defines the maximum size of the flow buffer. This is an upper limit to avoid unlimited growth
  1484. of the memory structure. This value has to scale accordingly to the link traffic rate. In case
  1485. IPv6 is enabled two buffers of equal size will be allocated. The value is expected in bytes.
  1486. DEFAULT: 16MB
  1487. KEY: [ pmacctd_flow_buffer_buckets | uacctd_flow_buffer_buckets ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1488. DESC: Defines the number of buckets of the flow buffer - which is organized as a chained hash table.
  1489. To exploit better performances, the table should be reasonably flat. This value has to scale to
  1490. higher power of 2 accordingly to the link traffic rate. For example, it has been reported that
  1491. a value of 65536 works just fine under full 100Mbit load.
  1492. DEFAULT: 256
  1493. KEY: [ pmacctd_conntrack_buffer_size | uacctd_conntrack_buffer_size ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1494. DESC: Defines the maximum size of the connection tracking buffer. In case IPv6 is enabled two buffers
  1495. of equal size will be allocated. The value is expected in bytes.
  1496. DEFAULT: 8MB
  1497. KEY: [ pmacctd_flow_lifetime | uacctd_flow_lifetime ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1498. DESC: Defines how long a non-TCP flow could remain inactive (ie. no packets belonging to such flow
  1499. are received) before considering it expired. The value is expected in seconds.
  1500. DEFAULT: 60
  1501. KEY: [ pmacctd_flow_tcp_lifetime | uacctd_flow_tcp_lifetime ] [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  1502. DESC: Defines how long a TCP flow could remain inactive (ie. no packets belonging to such flow are
  1503. received) before considering it expired. The value is expected in seconds.
  1504. DEFAULT: 60 secs if classification is disabled; 432000 secs (120 hrs) if clssification is enabled
  1505. KEY: [ pmacctd_ext_sampling_rate | uacctd_ext_sampling_rate | nfacctd_ext_sampling_rate |
  1506. sfacctd_ext_sampling_rate ] [GLOBAL]
  1507. Flags pmacctd that captured traffic is being sampled at the specified rate. Such rate can then
  1508. be renormalized by using 'pmacctd_renormalize' or otherwise is propagated by the NetFlow/sFlow
  1509. probe plugins, if any of them is activated. External sampling might be performed by capturing
  1510. frameworks the daemon is linked against (ie. PF_RING, NFLOG) or appliances (ie. sampled packet
  1511. mirroring).
  1512. In nfacctd and sfacctd daemons this directive can be used to tackle corner cases, ie. sampling
  1513. rate reported by the NetFlow/sFlow agent is missing or not correct.
  1514. DEFAULT: none
  1515. KEY: [ sfacctd_renormalize | nfacctd_renormalize | pmacctd_renormalize | uacctd_renormalize ] (-R)
  1516. [GLOBAL]
  1517. VALUES: [ true | false ]
  1518. DESC: Automatically renormalizes byte/packet counters value basing on information acquired from
  1519. either the NetFlow data unit or sFlow packet. In particular, it allows to deal with scenarios
  1520. in which multiple interfaces have been configured at different sampling rates. The feature also
  1521. calculates an effective sampling rate (sFlow only) which could differ from the configured one -
  1522. expecially at high rates - because of various losses. Such estimated rate is then used for
  1523. renormalization purposes.
  1524. DEFAULT: false
  1525. KEY: pmacctd_nonroot [GLOBAL]
  1526. VALUES: [ true | false ]
  1527. DESC: Allow to run pmacctd from a user with non root privileges. This can be desirable on systems
  1528. supporting a tool like setcap, ie. 'setcap "cap_net_raw,cap_net_admin=ep" /path/to/pmacctd',
  1529. to assign specific system capabilities to unprivileged users.
  1530. DEFAULT: false
  1531. KEY: sfacctd_counter_file [GLOBAL, SFACCTD_ONLY]
  1532. DESC: Enables streamed logging of sFlow counters. Each log entry features a time reference, sFlow
  1533. agent IP address event type and a sequence number (to order events when time reference is not
  1534. granular enough). Currently it is not possible to filter in/out specific counter types (ie.
  1535. generic, ethernet, vlan, etc.). The list of supported filename variables follows:
  1536. $peer_src_ip sFlow agent IP address.
  1537. Files can be re-opened by sending a SIGHUP to the daemon core process.
  1538. DEFAULT: none
  1539. KEY: sfacctd_counter_output [GLOBAL, SFACCTD_ONLY]
  1540. VALUES: [ json ]
  1541. DESC: Defines output format for the streamed logging of sFlow counters. Only JSON format is currently
  1542. supported and requires compiling against Jansson library (--enable-jansson when configuring for
  1543. compiling).
  1544. DEFAULT: json
  1545. KEY: sql_aggressive_classification
  1546. VALUES: [ true | false ]
  1547. DESC: Usually 5 to 10 packets are required to classify a stream by the 'classifiers' feature. Until
  1548. the flow is not classified, such packets join the 'unknown' class. As soon as classification
  1549. engine is successful identifying the stream, the packets are moved to their correct class if
  1550. they are still cached by the SQL plugin. This directive delays 'unknown' streams - but only
  1551. those which would have still chances to be correctly classified - from being purged to the DB
  1552. but only for a small number of consecutive sql_refresh_time slots. It is incompatible with
  1553. sql_dont_try_update and sql_use_copy directives. This feature/directive is being phased-out.
  1554. DEFAULT: false
  1555. KEY: sql_locking_style
  1556. VALUES: [ table | row | none ]
  1557. DESC: Defines the locking style for the SQL table. MySQL supports "table" and "none" values whereas
  1558. PostgreSQL supports "table", "row" and "none" values. With "table" value, the plugin will lock
  1559. the entire table when writing data to the DB with the effect of serializing access to the
  1560. table whenever multiple plugins need to access it simultaneously. Slower but light and safe,
  1561. ie. no risk for deadlocks and transaction-friendly; "row", the plugin will lock only the rows
  1562. it needs to UPDATE/DELETE. It results in better overral performances but has some noticeable
  1563. drawbacks in dealing with transactions and making the UPDATE-then-INSERT mechanism work
  1564. smoothly; "none" disables locking: while this method can help in some cases, ie. when grants
  1565. over the whole database (requirement for "table" locking in MySQL) is not available, it is not
  1566. recommended since serialization allows to contain database load.
  1567. DEFAULT: table
  1568. KEY: nfprobe_timeouts
  1569. DESC: Allows to tune a set of timeouts to be applied over collected packets. The value is expected in
  1570. the following form: 'name=value:name=value:...'. The set of supported timeouts and their default
  1571. values are listed below:
  1572. tcp (generic tcp flow life) 3600
  1573. tcp.rst (TCP RST flow life) 120
  1574. tcp.fin (TCP FIN flow life) 300
  1575. udp (UDP flow life) 300
  1576. icmp (ICMP flow life) 300
  1577. general (generic flow life) 3600
  1578. maxlife (maximum flow life) 604800
  1579. expint (expiry interval) 60
  1580. DEFAULT: see above
  1581. KEY: nfprobe_hoplimit
  1582. VALUES: [ 1-255 ]
  1583. DESC: Value of TTL for the newly generated NetFlow datagrams.
  1584. DEFAULT: Operating System default
  1585. KEY: nfprobe_maxflows
  1586. DESC: Maximum number of flows that can be tracked simultaneously.
  1587. DEFAULT: 8192
  1588. KEY: nfprobe_receiver
  1589. DESC: Defines the remote IP address/hostname and port to which NetFlow dagagrams are to be exported.
  1590. If IPv4, the value is expected as 'address:port'. If IPv6, it is expected as '[address]:port'.
  1591. DEFAULT: 127.0.0.1:2100
  1592. KEY: nfprobe_source_ip
  1593. DESC: Defines the local IP address from which NetFlow dagagrams are to be exported. Only a numerical
  1594. IPv4/IPv6 address is expected. The supplied IP address is required to be already configured on
  1595. one of the interfaces. This parameter is also required for graceful encoding of NetFlow v9 and
  1596. IPFIX option scoping.
  1597. DEFAULT: IP address is selected by the Operating System
  1598. KEY: nfprobe_version
  1599. VALUES: [ 5, 9, 10 ]
  1600. DESC: Version of outgoing NetFlow datagrams. NetFlow v5/v9 and IPFIX (v10) are supported. NetFlow v5
  1601. features a fixed record structure and if not specifying an 'aggregate' directive it gets
  1602. populated as much as possible; NetFlow v9 and IPFIX feature a dynamic template-based structure
  1603. instead and by default it is populated as: 'src_host, dst_host, src_port, dst_Port, proto, tos'.
  1604. DEFAULT: 5
  1605. KEY: nfprobe_engine
  1606. DESC: Allows to define Engine ID and Engine Type fields. It applies only to NetFlow v5/v9 and IPFIX.
  1607. In NetFlow v9/IPFIX, the supplied value fills last two bytes of SourceID field. Expects two
  1608. non-negative numbers, up to 255 each and separated by the ":" symbol. It also allows a collector
  1609. to distinguish between distinct probe instances running on the same box; this is also important
  1610. for letting NetFlow v9/IPFIX templates to work correctly: in fact, template IDs get automatically
  1611. selected only inside single daemon instances.
  1612. DEFAULT: 0:0
  1613. KEY: [ nfacctd_peer_as | sfacctd_peer_as | nfprobe_peer_as | sfprobe_peer_as ]
  1614. VALUES: [ true | false ]
  1615. DESC: When applied to [ns]fprobe src_as and dst_as fields are valued with peer-AS rather than origin-AS
  1616. as part of the NetFlow/sFlow export. Requirements to enable this feature on the probes are: a) one
  1617. of the nfacctd_as/sfacctd_as/pmacctd_as/uacctd_as set to 'bgp' and b) a fully functional BGP
  1618. daemon (bgp_daemon). When applied to [ns]facctd instead it uses src_as and dst_as values of the
  1619. NetFlow/sFlow export to populate peer_src_as and peer_dst_as primitives.
  1620. DEFAULT: false
  1621. KEY: [ nfprobe_ipprec | sfprobe_ipprec | tee_ipprec ]
  1622. DESC: Marks self-originated NetFlow (nfprobe) and sFlow (sfprobe) messages with the supplied IP
  1623. precedence value.
  1624. DEFAULT: 0
  1625. KEY: [ nfprobe_direction | sfprobe_direction ]
  1626. VALUES: [ in, out, tag, tag2 ]
  1627. DESC: Defines traffic direction. Can be statically defined via 'in' and 'out' keywords. It can also
  1628. be dynamically determined via lookup to either 'tag' or 'tag2' values. Tag value of 1 will be
  1629. mapped to 'in' direction, whereas tag value of 2 will be mapped to 'out'. The idea underlying
  1630. tag lookups is that pre_tag_map supports, among the other features, 'filter' matching against
  1631. a supplied tcpdump-like filter expression; doing so against L2 primitives (ie. source or
  1632. destination MAC addresses) allows to dynamically determine traffic direction (see example at
  1633. 'examples/pretag.map.example').
  1634. DEFAULT: none
  1635. KEY: [ nfprobe_ifindex | sfprobe_ifindex ]
  1636. VALUES: [ tag, tag2, <1-4294967295> ]
  1637. DESC: Associates an interface index (ifIndex) to a given nfprobe or sfprobe plugin. This is meant as
  1638. an add-on to [ns]probe_direction directive, ie. when multiplexing mirrored traffic from different
  1639. sources on the same interface (ie. split by VLAN). Can be statically defined via a 32-bit integer
  1640. or semi-dynamically determined via lookup to either 'tag' or 'tag2' values (read full elaboration
  1641. on [ns]probe_direction directive). This definition will be also always overridden whenever the
  1642. ifIndex can be determined dynamically (ie. via NFLOG framework).
  1643. DEFAULT: none
  1644. KEY: sfprobe_receiver
  1645. DESC: Defines the remote IP address/hostname and port to which sFlow dagagrams are to be exported.
  1646. The value is expected to be in the usual form 'address:port'.
  1647. DEFAULT: 127.0.0.1:6343
  1648. KEY: sfprobe_agentip
  1649. DESC: Sets the value of agentIp field inside the sFlow datagram header.
  1650. DEFAULT: none
  1651. KEY: sfprobe_agentsubid
  1652. DESC: Sets the value of agentSubId field inside the sFlow datagram header.
  1653. DEFAULT: none
  1654. KEY: sfprobe_ifspeed
  1655. DESC: Statically associates an interface speed to a given sfprobe plugin. Value is expected in bps.
  1656. DEFAULT: 100000000
  1657. KEY: bgp_daemon [GLOBAL]
  1658. VALUES: [ true | false ]
  1659. DESC: Enables the BGP daemon thread. Neighbors are not defined explicitely but a maximum amount
  1660. of peers is specified (bgp_daemon_max_peers); also, for security purposes, the daemon does
  1661. not implement outbound BGP UPDATE messages and acts passively (ie. it never establishes
  1662. a connection to a remote peer but waits for incoming connections); upon receipt of a BGP
  1663. OPEN message, the local daemon presents itself as belonging to the same AS number and
  1664. supporting the same (or a subset of the) BGP capabilities as the remote peer; capabilities
  1665. currently supported are MP-BGP, 4-bytes ASNs, ADD-PATH. Per-peer RIBs are maintained basing
  1666. on the IP address of the peer (and for clarity not its BGP Router-ID). In case of ADD-PATH
  1667. capability, the correct BGP info is linked to traffic data using BGP next-hop (or IP next-
  1668. hop if use_ip_next_hop is set to true) as selector among the paths available.
  1669. DEFAULT: false
  1670. KEY: bmp_daemon [GLOBAL]
  1671. VALUES: [ true | false ]
  1672. DESC: Enables the BMP daemon thread. BMP, BGP Monitoring Protocol, can be used to monitor BGP
  1673. sessions. The implementation was originally based on the draft-ietf-grow-bmp-07 IETF
  1674. document (whereas the current review is against draft-ietf-grow-bmp-17). The BMP daemon
  1675. currently supports BMP data, events and stats, ie. initiation, termination, peer up,
  1676. peer down, stats and route monitoring messages. The daemon enables to write BMP messages
  1677. to files, AMQP and Kafka brokers, real-time (msglog) or at regular time intervals (dump).
  1678. Also, route monitoring messages are saved in a RIB structure for IP prefix lookup.
  1679. For further referece see examples in the QUICKSTART document and/or description of the
  1680. bmp_* config keys in this document. The BMP daemon is a separate thread in the NetFlow
  1681. (nfacctd) and sFlow (sfacctd) collectors.
  1682. DEFAULT: false
  1683. KEY: [ bgp_daemon_ip | bmp_daemon_ip ] [GLOBAL]
  1684. DESC: Binds the BGP/BMP daemon to a specific interface. Expects as value an IPv4 address. For the
  1685. BGP daemon the same is value is presented as BGP Router-ID (read more about the BGP Router-ID
  1686. selection process at the bgp_daemon_id config directive description). Setting this directive
  1687. is highly adviced.
  1688. DEFAULT: 0.0.0.0
  1689. KEY: bgp_daemon_id [GLOBAL]
  1690. DESC: Defines the BGP Router-ID to the supplied value. Expected value is an IPv4 address. If this
  1691. feature is not used or an invalid IP address is supplied, ie. IPv6, the bgp_daemon_ip value
  1692. is used instead. If also bgp_daemon_ip is not defined or invalid, the BGP Router-ID defaults
  1693. to "1.2.3.4".
  1694. DEFAULT: 1.2.3.4
  1695. KEY: bgp_daemon_as [GLOBAL]
  1696. DESC: Defines the BGP Local AS to the supplied value. By default, no value supplied, the session
  1697. will be setup as iBGP with the Local AS received from the remote peer being copied back in
  1698. the BGP OPEN reply. This allows to explicitely set a Local AS which could be different from
  1699. the remote peer one hence establishing an eBGP session.
  1700. DEFAULT: none
  1701. KEY: [ bgp_daemon_port | bmp_daemon_port ] [GLOBAL]
  1702. DESC: Binds the BGP/BMP daemon to a port different from the standard port. Default port for BGP is
  1703. 179/tcp; default port for BMP is 1790.
  1704. DEFAULT: bgp_daemon_port: 179; bmp_daemon_port: 1790
  1705. KEY: [ bgp_daemon_ipprec | bmp_daemon_ipprec ] [GLOBAL]
  1706. DESC: Marks self-originated BGP/BMP messages with the supplied IP precedence value.
  1707. DEFAULT: 0
  1708. KEY: [ bgp_daemon_max_peers | bmp_daemon_max_peers ] [GLOBAL]
  1709. DESC: Sets the maximum number of neighbors the BGP/BMP daemon can peer to. Upon reaching of the
  1710. limit, no more BGP/BMP sessions can be established. BGP/BMP neighbors don't need to be
  1711. defined explicitely one-by-one rather an upper boundary to the number of neighbors applies.
  1712. pmacctd, uacctd daemons are limited to only two BGP peers (in a primary/backup fashion, see
  1713. bgp_agent_map); such hardcoded limit is imposed as the only scenarios supported in conjunction
  1714. with the BGP daemon are as NetFlow/sFlow probes on-board software routers and firewalls.
  1715. DEFAULT: 10
  1716. KEY: [ bgp_daemon_batch_interval | bmp_daemon_batch_interval ] [GLOBAL]
  1717. DESC: To prevent all BGP/BMP peers contend resources, this defines the time interval, in seconds,
  1718. between any two BGP/BMP peer batches. The first peer in a batch sets the base time, that is
  1719. the time from which the interval is calculated, for that batch.
  1720. DEFAULT: 0
  1721. KEY: [ bgp_daemon_batch | bmp_daemon_batch ] [GLOBAL]
  1722. DESC: To prevent all BGP/BMP peers to contend resources, this defines the number of BGP peers in
  1723. each batch. If a BGP/BMP peer is not allowed by an ACL (ie. bgp_daemon_allow_file), room is
  1724. recovered in the current batch; if a BGP/BMP peer in a batch is replenished (ie. connection
  1725. drops, is reset, etc.) no new room is made in the current batch (rationale being: be a bit
  1726. conservative, batch might have been set too big, let's try to limit flapping).
  1727. DEFAULT: 0
  1728. KEY: [ bgp_daemon_msglog_file | bmp_daemon_msglog_file | telemetry_daemon_msglog_file ] [GLOBAL]
  1729. DESC: Enables streamed logging of BGP tables/BMP events/Streaming Telemetry data. Each log entry
  1730. features a time reference, peer/exporter IP address, event type and a sequence number (to
  1731. order events when time reference is not granular enough). BGP UPDATE messages also contain
  1732. full prefix and BGP attributes information. The list of supported filename variables follows:
  1733. $peer_src_ip BGP/BMP peer IP address.
  1734. Files can be re-opened by sending a SIGHUP to the daemon core process.
  1735. DEFAULT: none
  1736. KEY: [ bgp_daemon_msglog_output | bmp_daemon_msglog_output | telemetry_daemon_msglog_output ]
  1737. [GLOBAL]
  1738. VALUES: [ json ]
  1739. DESC: Defines output format for the streamed logging of BGP/BMP messages and events/streaming
  1740. telemetry. Only JSON format is currently supported and requires compiling against Jansson
  1741. library (--enable-jansson when configuring for compiling).
  1742. DEFAULT: json
  1743. KEY: bgp_aspath_radius [GLOBAL]
  1744. DESC: Cuts down AS-PATHs to the specified number of ASN hops. If the same ASN is repeated multiple
  1745. times (ie. as effect of prepending), each of them is regarded as one hop. By default AS-PATHs
  1746. are left intact unless reaching the maximum length of the buffer (128 chars).
  1747. DEFAULT: none
  1748. KEY: [ bgp_stdcomm_pattern | bgp_extcomm_pattern ] [GLOBAL]
  1749. DESC: Filters BGP standard/extended communities against the supplied pattern. The underlying idea
  1750. is that many communities can be attached to a prefix; some of these can be of little or no
  1751. interest for the accounting task; this feature allows to select only the relevant ones. By
  1752. default the list of communities is left intact until reaching maximum length of the buffer
  1753. (96 chars). The filter does substring matching, ie. 12345:64 will match communities in the
  1754. ranges 64-64, 640-649, 6400-6499 and 64000-64999. The '.' symbol can be used to wildcard a
  1755. pre-defined number of characters, ie. 12345:64... will match community values in the range
  1756. 64000-64999 only. Multiple patterns can be supplied comma-separated.
  1757. DEFAULT: none
  1758. KEY: [ bgp_stdcomm_pattern_to_asn ] [GLOBAL]
  1759. DESC: Filters BGP standard communities against the supplied pattern. The algorithm employed is
  1760. the same as for the bgp_stdcomm_pattern directive: read implementation details there. The
  1761. first matching community is taken and split using the ':' symbol as delimiter. The first
  1762. part is mapped onto the peer AS field while the second is mapped onto the origin AS field.
  1763. The aim of this directive is to deal with IP prefixes on the own address space, ie. statics
  1764. or connected redistributed in BGP. Example: BGP standard community XXXXX:YYYYY is mapped as:
  1765. Peer-AS=XXXXX, Origin-AS=YYYYY. Multiple patterns can be supplied comma-separated.
  1766. DEFAULT: none
  1767. KEY: bgp_peer_as_skip_subas [GLOBAL]
  1768. VALUES: [ true | false ]
  1769. DESC: When determining the peer AS (source and destination), skip potential confederated sub-AS
  1770. and report the first ASN external to the routing domain. When enabled if no external ASNs
  1771. are found on the AS-PATH except the confederated sub-ASes, the first sub-AS is reported.
  1772. DEFAULT: false
  1773. KEY: bgp_peer_src_as_type [GLOBAL]
  1774. VALUES: [ netflow | sflow | map | bgp ]
  1775. DESC: Defines the method to use to map incoming traffic to a source peer ASN. "map" selects a
  1776. map, reloadable at runtime, specified by the bgp_peer_src_as_map directive (refer to it for
  1777. further information); "bgp" implements native BGP RIB lookups. BGP lookups assume traffic is
  1778. symmetric, which is often not the case, affecting their accuracy.
  1779. DEFAULT: netflow, sflow
  1780. KEY: bgp_peer_src_as_map [GLOBAL, MAP]
  1781. DESC: Full pathname to a file containing source peer AS mappings. The AS can be mapped to one or
  1782. a combination of: ifIndex, source MAC address and BGP next-hop (query against the BGP RIB
  1783. to look up the source IP prefix). This is sufficient to model popular tecniques for both
  1784. public and private BGP peerings. Sample map in 'examples/peers.map.example'. Content can
  1785. be reloaded at runtime by sending the daemon a SIGUSR2 signal (ie. "killall -USR2 nfacctd").
  1786. DEFAULT: none
  1787. KEY: bgp_src_std_comm_type [GLOBAL]
  1788. VALUES: [ bgp ]
  1789. DESC: Defines the method to use to map incoming traffic to a set of standard communities. Only
  1790. native BGP RIB lookups are currently supported. BGP lookups assume traffic is symmetric,
  1791. which is often not the case, affecting their accuracy.
  1792. DEFAULT: none
  1793. KEY: bgp_src_ext_comm_type [GLOBAL]
  1794. VALUES: [ bgp ]
  1795. DESC: Defines the method to use to map incoming traffic to a set of extended communities. Only
  1796. native BGP RIB lookups are currently supported. BGP lookups assume traffic is symmetric,
  1797. which is often not the case, affecting their accuracy.
  1798. DEFAULT: none
  1799. KEY: bgp_src_lrg_comm_type [GLOBAL]
  1800. VALUES: [ bgp ]
  1801. DESC: Defines the method to use to map incoming traffic to a set of large communities. Only
  1802. native BGP RIB lookups are currently supported. BGP lookups assume traffic is symmetric,
  1803. which is often not the case, affecting their accuracy.
  1804. DEFAULT: none
  1805. KEY: bgp_src_as_path_type [GLOBAL]
  1806. VALUES: [ bgp ]
  1807. DESC: Defines the method to use to map incoming traffic to an AS-PATH. Only native BGP RIB lookups
  1808. are currently supported. BGP lookups assume traffic is symmetric, which is often not the
  1809. case, affecting their accuracy.
  1810. DEFAULT: none
  1811. KEY: bgp_src_local_pref_type [GLOBAL]
  1812. VALUES: [ map | bgp ]
  1813. DESC: Defines the method to use to map incoming traffic to a local preference. Only native BGP
  1814. RIB lookups are currently supported. BGP lookups assume traffic is symmetric, which is
  1815. often not the case, affecting their accuracy.
  1816. DEFAULT: none
  1817. KEY: bgp_src_local_pref_map [GLOBAL, MAP]
  1818. DESC: Full pathname to a file containing source local preference mappings. The LP value can be
  1819. mapped to one or a combination of: ifIndex, source MAC address and BGP next-hop (query
  1820. against the BGP RIB to look up the source IP prefix). Sample map in 'examples/
  1821. lpref.map.example'. Content can be reloaded at runtime by sending the daemon a SIGUSR2
  1822. signal (ie. "killall -USR2 nfacctd").
  1823. DEFAULT: none
  1824. KEY: bgp_src_med_type [GLOBAL]
  1825. VALUES: [ map | bgp ]
  1826. DESC: Defines the method to use to map incoming traffic to a MED value. Only native BGP RIB
  1827. lookups are currently supported. BGP lookups assume traffic is symmetric, which is often
  1828. not the case, affecting their accuracy.
  1829. DEFAULT: none
  1830. KEY: bgp_src_med_map [GLOBAL, MAP]
  1831. DESC: Full pathname to a file containing source MED (Multi Exit Discriminator) mappings. The
  1832. MED value can be mapped to one or a combination of: ifIndex, source MAC address and BGP
  1833. next-hop (query against the BGP RIB to look up the source IP prefix). Sample map in
  1834. 'examples/med.map.example'. Content can be reloaded at runtime by sending the daemon a
  1835. SIGUSR2 signal (ie. "killall -USR2 nfacctd").
  1836. DEFAULT: none
  1837. KEY: bgp_agent_map [GLOBAL, MAP]
  1838. DESC: Full pathname to a file to map source IP address of NetFlow agents and AgentID of sFlow
  1839. agents to source IP address or Router ID of BGP peers. This is to provide flexibility
  1840. in a number of scenarios, for example and not limited to BGP peering with RRs, hub-and-
  1841. spoke topologies, single-homed networks - but also BGP sessions traversing NAT. pmacctd,
  1842. uacctd daemons are required to use a bgp_agent_map with up to two "catch-all" entries -
  1843. working in a primary/backup fashion (see agent_to_peer.map in the examples section):
  1844. this is because these daemons do not have a NetFlow/sFlow source address to match to.
  1845. Number of map entries (by default 384) can be modified via maps_entries. Content can be
  1846. reloaded at runtime by sending the daemon a SIGUSR2 signal (ie. "killall -USR2 nfacctd").
  1847. DEFAULT: none
  1848. KEY: flow_to_rd_map [GLOBAL, MAP]
  1849. DESC: Full pathname to a file to map flows (typically, a) ingress router, input interfaces or
  1850. b) MPLS bottom label, BGP next-hop couples) to BGP/MPLS Virtual Private Network (VPN)
  1851. Route Distinguisher (RD), based upon rfc4659. See flow_to_rd.map file in the examples
  1852. section for further info. Number of map entries (by default 384) can be modified via
  1853. maps_entries. Content can be reloaded at runtime by sending the daemon a SIGUSR2 signal
  1854. (ie. "killall -USR2 nfacctd").
  1855. DEFAULT: none
  1856. KEY: bgp_follow_default [GLOBAL]
  1857. DESC: Expects positive number value which instructs how many times a default route, if any, can
  1858. be followed in order to successfully resolve source and destination IP prefixes. This is
  1859. aimed at scenarios where neighbors peering with pmacct have a default-only or partial BGP
  1860. view. At each recursion (default route follow-up) the value gets decremented; the process
  1861. stops when one of these conditions is met:
  1862. * both source and destination IP prefixes are resolved
  1863. * there is no available default route
  1864. * the default gateway is not BGP peering with pmacct
  1865. * the the recusion value reaches zero
  1866. As soon as an IP prefix is matched, it is not looked up anymore in case more recursions
  1867. are required (ie. the closer the router is, the most specific the route is assumed to be).
  1868. pmacctd, uacctd daemons are internally limited to only two BGP peers hence this feature
  1869. can't properly work.
  1870. DEFAULT: 0
  1871. KEY: bgp_follow_nexthop [GLOBAL]
  1872. DESC: Expects one or more IP prefix(es), ie. 192.168.0.0/16, comma separated. A maximum of 32
  1873. IP prefixes is supported. It follows the BGP next-hop up (using each next-hop as BGP
  1874. source-address for the next BGP RIB lookup), returning the last next-hop part of the
  1875. supplied IP prefix(es) as value for the 'peer_ip_dst' primitive. bgp_agent_map is supported
  1876. at each recursion. This feature is aimed at networks, for example, involving BGP
  1877. confederations; underlying goal being to see the routing-domain "exit-point". The
  1878. The feature is internally protected against routing loops with an hardcoded limit of 20
  1879. lookups; pmacctd, uacctd daemons are internally limited to only two BGP peers hence this
  1880. feature can't properly work.
  1881. DEFAULT: none
  1882. KEY: bgp_follow_nexthop_external [GLOBAL]
  1883. VALUES: [ true | false ]
  1884. DESC: If set to true makes bgp_follow_nexthop return the next-hop from the routing table of
  1885. the last node part of the supplied IP prefix(es) as value for the 'peer_ip_dst' primitive.
  1886. This may help to pin-point the (set of) exit interface(s).
  1887. DEFAULT: false
  1888. KEY: bgp_neighbors_file [GLOBAL]
  1889. DESC: Writes a list of the BGP neighbors in the established state to the specified file, one
  1890. per line. This gets particularly useful for automation purposes (ie. auto-discovery of
  1891. devices to poll via SNMP).
  1892. DEFAULT: none
  1893. KEY: [ bgp_daemon_allow_file | bmp_daemon_allow_file ] [GLOBAL]
  1894. DESC: Full pathname to a file containing the list of IP addresses (one for each line) allowed
  1895. to establish a BGP/BMP session. Current syntax does not implement network masks but only
  1896. individual IP addresses.
  1897. DEFAULT: none (ie. allow all)
  1898. KEY: bgp_daemon_md5_file [GLOBAL]
  1899. DESC: Full pathname to a file containing the BGP peers (IP address only, one for each line)
  1900. and their corresponding MD5 passwords in CSV format (ie. 10.15.0.1, arealsmartpwd).
  1901. BGP peers not making use of a MD5 password should not be listed. The maximum number
  1902. of peers supported is 8192. For a sample map look in: 'examples/bgp_md5.lst.example'
  1903. The feature was tested working against a 2.6.32 Linux kernel.
  1904. DEFAULT: none
  1905. KEY: bgp_table_peer_buckets [GLOBAL]
  1906. VALUES: [ 1-1000 ]
  1907. DESC: Routing information related to BGP prefixes is kept per-peer in order to simulate a
  1908. multi-RIB environment and is internally structured as an hash with conflict chains.
  1909. This parameter sets the number of buckets of such hash structure; the value is directly
  1910. related to the number of expected BGP peers, should never exceed such amount and: a) if
  1911. only best-path is received this is best set to 1/10 of the expected peers; b) if BGP
  1912. ADD-PATHs is received this is best set to 1/1 of the expected peers. The default value
  1913. proved to work fine up to aprox 100 BGP peers sending best-path only, in lab. More
  1914. buckets means better CPU usage but also increased memory footprint - and vice-versa.
  1915. DEFAULT: 13
  1916. KEY: bgp_table_per_peer_buckets [GLOBAL]
  1917. VALUE: [ 1-128 ]
  1918. DESC: With same background information as bgp_table_peer_buckets, this parameter sets the
  1919. number of buckets over which per-peer information is distributed (hence effectively
  1920. creating a second dimension on top of bgp_table_peer_buckets, useful when much BGP
  1921. information per peer is received, ie. in case of BGP ADD-PATHs). Default proved to
  1922. work fine if BGP sessions are passing best-path only. In case of BGP ADD-PATHs it is
  1923. instead recommended to set this value to 1/3 of the configured maximum number of
  1924. paths per prefix to be exported.
  1925. DEFAULT: 1
  1926. KEY: bgp_table_attr_hash_buckets [GLOBAL]
  1927. VALUE: [ 1-1000000 ]
  1928. DESC: Sets the number of buckets of BGP attributes hashes (ie. AS-PATH, communities, etc.).
  1929. Default proved to work fine with BGP sessions passing best-path only and with up to
  1930. 25 BGP sessions passing ADD-PATH.
  1931. DEFAULT: 65535
  1932. KEY: bgp_table_per_peer_hash [GLOBAL]
  1933. VALUE: [ path_id ]
  1934. DESC: If bgp_table_per_peer_buckets is greater than 1, this parameter allows to set the
  1935. hashing to be used. By default hashing happens against the BGP ADD-PATH path_id field.
  1936. Hashing over other fields or field combinations (hashing over BGP next-hop is on the
  1937. radar) are planned to be supported in future.
  1938. DEFAULT: path_id
  1939. KEY: [ bgp_table_dump_file | bmp_dump_file | telemetry_dump_file ] [GLOBAL]
  1940. DESC: Enables dump of BGP tables/BMP events/Streaming Telemetry data at regular time
  1941. intervals (as defined by, for example, bgp_table_dump_refresh_time) into files.
  1942. Each dump event features a time reference and peer/exporter IP address along with the
  1943. rest of BGP/BMP/Streaming Telemetry data. The list of supported filename variables
  1944. follows:
  1945. %d The day of the month as a decimal number (range 01 to 31).
  1946. %H The hour as a decimal number using a 24 hour clock (range 00 to 23).
  1947. %m The month as a decimal number (range 01 to 12).
  1948. %M The minute as a decimal number (range 00 to 59).
  1949. %s The number of seconds since Epoch, ie., since 1970-01-01 00:00:00 UTC.
  1950. %w The day of the week as a decimal, range 0 to 6, Sunday being 0.
  1951. %W The week number of the current year as a decimal number, range
  1952. 00 to 53, starting with the first Monday as the first day of
  1953. week 01.
  1954. %Y The year as a decimal number including the century.
  1955. $peer_src_ip BGP or BMP peer/Streaming Telemetry exporter IP address.
  1956. DEFAULT: none
  1957. KEY: [ bgp_table_dump_output | bmp_dump_output | telemetry_dump_output ] [GLOBAL]
  1958. VALUES: [ json ]
  1959. DESC: Defines output format for the dump of BGP tables/BMP events/Streaming Telemetry data.
  1960. Only JSON format is currently supported and requires compiling against Jansson library
  1961. (--enable-jansson when configuring for compiling).
  1962. DEFAULT: json
  1963. KEY: [ bgp_table_dump_refresh_time | bmp_dump_refresh_time | telemetry_dump_latest_file ]
  1964. [GLOBAL]
  1965. VALUES: [ 60 .. 86400 ]
  1966. DESC: Time interval, in seconds, between two consecutive executions of the dump of BGP
  1967. tables/BMP events/Streaming Telemetry data to files.
  1968. DEFAULT: 0
  1969. KEY: [ bgp_table_dump_latest_file | bmp_dump_latest_file | telemetry_dump_refresh_time ]
  1970. [GLOBAL]
  1971. DESC: Defines the full pathname to pointer(s) to latest file(s). Dynamic names are supported
  1972. through the use of variables, which are computed at the moment when data is purged to the
  1973. backend: refer to bgp_table_dump_file (and companion directives) for a full listing of
  1974. supported variables; time-based variables are not allowed. Update of the latest pointer
  1975. is done evaluating files modification time. See also print_latest_file for examples.
  1976. DEFAULT: none
  1977. KEY: isis_daemon [GLOBAL]
  1978. VALUES: [ true | false ]
  1979. DESC: Enables the skinny IS-IS daemon thread. This feature requires the package to be supporting
  1980. multi-threading (--enable-threads). It implements P2P Hellos, CSNP and PSNP - and does not
  1981. send any LSP information out. It currently supports a single L2 P2P neighborship. Testing
  1982. has been done over a GRE tunnel.
  1983. DEFAULT: false
  1984. KEY: isis_daemon_ip [GLOBAL]
  1985. DESC: Sets the sub-TLV of the Extended IS Reachability TLV that contains an IPv4 address for the
  1986. local end of a link. No default value is set and a non-zero value is mandatory. It should
  1987. be set to the IPv4 address configured on the interface pointed by isis_daemon_iface.
  1988. DEFAULT: none
  1989. KEY: isis_daemon_net [GLOBAL]
  1990. DESC: Defines the Network entity title (NET) of the IS-IS daemon. In turn a NET defines the area
  1991. addresses for the IS-IS area and the system ID of the router. No default value is set and
  1992. a non-zero value is mandatory. Extensive IS-IS and ISO literature cover the topic, example
  1993. of the NET value format can be found as part of the "Quickstart guide to setup the IS-IS
  1994. daemon" in the QUICKSTART document.
  1995. DEFAULT: none
  1996. KEY: isis_daemon_iface [GLOBAL]
  1997. DESC: Defines the network interface (ie. gre1) where to bind the IS-IS daemon. No default value
  1998. is set and a non-zero value is mandatory.
  1999. DEFAULT: none
  2000. KEY: isis_daemon_mtu [GLOBAL]
  2001. DESC: Defines the available MTU for the IS-IS daemon. P2P HELLOs will be padded to such length.
  2002. When the daemon is configured to set a neighborship with a Cisco router running IOS, this
  2003. value should match the value of the "clns mtu" IOS directive.
  2004. DEFAUT: 1476
  2005. KEY: isis_daemon_msglog [GLOBAL]
  2006. VALUES: [ true | false ]
  2007. DESC: Enables IS-IS messages logging: as this can get easily verbose, it is intended for debug
  2008. and troubleshooting purposes only.
  2009. DEFAULT: false
  2010. KEY: [ geoip_ipv4_file | geoip_ipv6_file ] [GLOBAL]
  2011. DESC: If pmacct is compiled with --enable-geoip, this defines full pathname to the Maxmind GeoIP
  2012. Country v1 ( http://dev.maxmind.com/geoip/legacy/install/country/ ) IPv4/IPv6 databases
  2013. to use. pmacct, leveraging the Maxmind API, will detect if the file is updated and reload
  2014. it. The use of --enable-geoip is mutually exclusive with --enable-geoipv2.
  2015. DEFAULT: none
  2016. KEY: geoipv2_file [GLOBAL]
  2017. DESC: If pmacct is compiled with --enable-geoipv2, this defines full pathname to a Maxmind GeoIP
  2018. database v2 (libmaxminddb, ie. https://dev.maxmind.com/geoip/geoip2/geolite2/ ). It does
  2019. allow to resolve GeoIP-related primitives like countries and pocodes. Only the binary
  2020. database format is supported (ie. it is not possible to load distinct CSVs for IPv4 and
  2021. IPv6 addresses). The use of --enable-geoip is mutually exclusive with --enable-geoipv2.
  2022. Files can be reloaded at runtime by sending the daemon a SIGUSR signal (ie. "killall -USR2
  2023. nfacctd").
  2024. KEY: uacctd_group [GLOBAL, UACCTD_ONLY]
  2025. DESC: Sets the Linux Netlink NFLOG multicast group to be joined.
  2026. DEFAULT: 0
  2027. KEY: uacctd_nl_size [GLOBAL, UACCTD_ONLY]
  2028. DESC: Sets NFLOG Netlink internal buffer size (specified in bytes). It is 128KB by default, but to
  2029. safely record bursts of high-speed traffic, it could be further increased. For high loads,
  2030. values as large as 2MB are recommended. When modifying this value, it is also recommended
  2031. to reflect the change to the 'snaplen' option.
  2032. DEFAULT: 131072
  2033. KEY: uacctd_threshold [GLOBAL, UACCTD_ONLY]
  2034. DESC: Sets the number of packets to queue inside the kernel before sending them to userspace. Higher
  2035. values result in less overhead per packet but increase delay until the packets reach userspace.
  2036. DEFAULT: 1
  2037. KEY: tunnel_0 [GLOBAL, NO_NFACCTD, NO_SFACCTD]
  2038. DESC: Defines tunnel inspection in pmacctd and uacctd, disabled by default (note: this feature
  2039. is currently unrelated to tunnel_* primitives). The daemon will then account on tunnelled
  2040. data rather than on the envelope. The implementation approach is stateless, ie. control
  2041. messages are not handled. Up to 4 tunnel layers are supported (ie. <tun proto>, <options>;
  2042. <tun proto>, <options>; ...). Up to 8 tunnel stacks will be supported (ie. configuration
  2043. directives tunnel_0 .. tunnel_8), to be used in a strictly sequential order. First stack
  2044. matched at the first layering, wins. Below tunnel protocols supported and related options:
  2045. GTP, GPRS tunnelling protocol. Expects as option the UDP port identifying the protocol.
  2046. tunnel_0: gtp, <UDP port>
  2047. DEFAULT: none
  2048. KEY: tee_receivers [MAP]
  2049. DESC: Defines full pathname to a list of remote IP addresses and ports to which NetFlow/sFlow
  2050. dagagrams are to be replicated to. Examples are available in "examples/tee_receivers.lst.
  2051. example" file. Number of map entries (by default 384) can be modified via maps_entries.
  2052. Content can be reloaded at runtime by sending the daemon a SIGUSR2 signal (ie. "killall
  2053. -USR2 nfacctd").
  2054. DEFAULT: none
  2055. KEY: tee_source_ip
  2056. DESC: Defines the local IP address from which NetFlow/sFlow dagagrams are to be replicate from.
  2057. Only a numerical IPv4/IPv6 address is expected. The supplied IP address is required to be
  2058. already configured on one of the interfaces. Value is ignored when transparent replication
  2059. is enabled.
  2060. DEFAULT: IP address is selected by the Operating System
  2061. KEY: tee_transparent
  2062. VALUES: [ true | false ]
  2063. DESC: Enables transparent replication mode. It essentially spoofs the source IP address to the
  2064. original sender of the datagram. It requires super-user permissions.
  2065. DEFAULT: false
  2066. KEY: tee_max_receiver_pools
  2067. DESC: Tee receivers list is organized in pools (for present and future features that require
  2068. grouping) of receivers. This directive defines the amount of pools to be allocated and
  2069. cannot be changed at runtime.
  2070. DEFAULT: 128
  2071. KEY: tee_max_receivers
  2072. DESC: Tee receivers list is organized in pools (for present and future features that require
  2073. grouping) of receivers. This directive defines the amount of receivers per pool to be
  2074. allocated and cannot be changed at runtime.
  2075. DEFAULT: 32
  2076. KEY: tee_dissect_send_full_pkt
  2077. VALUES: [ true | false ]
  2078. DESC: When replicating and dissecting flow samples, send onto the tee plugin also the full
  2079. packet. This is useful in scenarios where, say, dissected flows are tagged while the
  2080. full packet is left untagged. By default this is left to false for security reasons.
  2081. DEFAULT: false
  2082. KEY: pkt_len_distrib_bins
  2083. DESC: Defines a list of packet length distributions, comma-separated, which is then used to
  2084. populate values for the 'pkt_len_ditrib' aggregation primitive. Values can be ranges or
  2085. exact, ie. "0-499,500-999,1000-1499,1500-9000". The maximum amount of bins that can be
  2086. defined is 255; packet lengths must be in the range 0-9000; if a length is part of more
  2087. than a single bin the latest definition wins.
  2088. DEFAULT: none
  2089. KEY: tmp_asa_bi_flow
  2090. VALUES: [ true | false ]
  2091. DESC: Bi-flows use two counters to report counters, ie. bytes and packets, in forward and
  2092. reverse directions. This hack (ab)uses the packets field in order to store the extra
  2093. bytes counter. The patch specifically targets NetFlow v9/IPFIX field types #231 and
  2094. #232 and has been tested against a Cisco ASA export.
  2095. DEFAULT: false
  2096. KEY: thread_stack
  2097. DESC: Defines the stack size for threads screated by the daemon. The value is expected in
  2098. bytes. A value of 0, default, leaves the stack size to the system default or pmacct
  2099. minimum (8192000) if system default is too low. Some systems may throw an error if
  2100. the defined size is not a multiple of the system page size.
  2101. DEFAULT: 0
  2102. KEY: telemetry_daemon [GLOBAL]
  2103. VALUES: [ true | false ]
  2104. DESC: Enables the Streaming Telemetry thread in all daemons except pmtelemetryd (which does
  2105. collect telemetry as part of its core functionalities). Quoting Cisco IOS-XR Telemetry
  2106. Configuration Guide at the time of this writing: "Streaming telemetry lets users direct
  2107. data to a configured receiver. This data can be used for analysis and troubleshooting
  2108. purposes to maintain the health of the network. This is achieved by leveraging the
  2109. capabilities of machine-to-machine communication. The data is used by development and
  2110. operations (DevOps) personnel who plan to optimize networks by collecting analytics of
  2111. the network in real-time, locate where problems occur, and investigate issues in a
  2112. collaborative manner.".
  2113. DEFAULT: false
  2114. KEY: telemetry_daemon_port_tcp [GLOBAL]
  2115. DESC: Makes the Streaming Telemetry daemon, pmtelemetryd, or the Streaming Telemetry thread
  2116. listen on the specified TCP port.
  2117. DEFAULT: none
  2118. KEY: telemetry_daemon_port_udp [GLOBAL]
  2119. DESC: Makes the Streaming Telemetry daemon, pmtelemetryd, or the Streaming Telemetry thread
  2120. listen on the specified UDP port.
  2121. DEFAULT: none
  2122. KEY: telemetry_daemon_ip [GLOBAL]
  2123. DESC: Binds the Streaming Telemetry daemon to a specific interface. Expects as value an IPv4/
  2124. IPv6 address.
  2125. DEFAULT: 0.0.0.0
  2126. KEY: telemetry_daemon_decoder [GLOBAL]
  2127. VALUES: [ json | zjson | cisco | cisco_json | cisco_zjson | cisco_gpb | cisco_gpb_kv ]
  2128. DESC: Sets the Streaming Telemetry data decoder to the specified type. Cisco versions of json,
  2129. gpb, etc. all prepend a 12 bytes proprietary header.
  2130. DEFAULT: none
  2131. KEY: telemetry_daemon_max_peers [GLOBAL]
  2132. DESC: Sets the maximum number of exporters the Streaming Telemetry daemon can receive data from.
  2133. Upon reaching of such limit, no more exporters can send data to the daemon.
  2134. DEFAULT: 100
  2135. KEY: telemetry_daemon_udp_timeout [GLOBAL]
  2136. DESC: Sets the timeout time, in seconds, to determine when a UDP session is to be expired.
  2137. DEFAULT: 300
  2138. KEY: telemetry_daemon_allow_file [GLOBAL]
  2139. DESC: Full pathname to a file containing the list of IPv4/IPv6 addresses (one for each line)
  2140. allowed to send packets to the daemon. Current syntax does not implement network masks
  2141. but individual IP addresses only. The Allow List is intended to be small; firewall
  2142. rules should be preferred to long ACLs.
  2143. DEFAULT: none (ie. allow all)
  2144. KEY: telemetry_daemon_pipe_size [GLOBAL]
  2145. DESC: Defines the size of the kernel socket used for Streaming Telemetry datagrams (see also
  2146. bgp_daemon_pipe_size for more info).
  2147. DEFAULT: Operating System default
  2148. KEY: telemetry_daemon_ipprec [GLOBAL]
  2149. DESC: Marks self-originated Streaming Telemetry messages with the supplied IP precedence value.
  2150. Applies to TCP sessions only.
  2151. DEFAULT: 0
  2152. KEY: classifier_num_roots [GLOBAL]
  2153. DESC: Defines the number of buckets of the nDPI memory structure on which to hash flows.
  2154. The more the buckets, the more memory will be allocated at startup and the smaller
  2155. - and hence more performing - each memory structure will be.
  2156. DEFAULT: 512
  2157. KEY: classifier_max_flows [GLOBAL]
  2158. DESC: Maximum number of concurrent flows allowed in the nDPI memory structure.
  2159. DEFAULT: 200000000
  2160. KEY: classifier_proto_guess [GLOBAL]
  2161. VALUES: [ true | false ]
  2162. DESC: If DPI classification is unsuccessful, and before giving up, try guessing the protocol
  2163. given collected flow characteristics, ie. IP protocol, port numbers, etc.
  2164. DEFAULT: false
  2165. KEY: classifier_idle_scan_period [GLOBAL]
  2166. DESC: Defines the time interval, in seconds, at which going through the memory structure to
  2167. find for idle flows to expire.
  2168. DEFAULT: 10
  2169. KEY: classifier_idle_scan_budget [GLOBAL]
  2170. DESC: Defines the amount of idle flows to expire per each classifier_idle_scan_period. This
  2171. feature is to prevent too many flows to expire can disrupt the regular classification
  2172. activity.
  2173. DEFAULT: 1024
  2174. KEY: classifier_giveup_proto_tcp [GLOBAL]
  2175. DESC: Defines the maximum amount of packets to try to classify a TCP flow. After such amount
  2176. of trials, the flow will be marked as given up and no classification attempts will be
  2177. made anymore, until it expires.
  2178. DEFAULT: 10
  2179. KEY: classifier_giveup_proto_udp [GLOBAL]
  2180. DESC: Same as classifier_giveup_proto_tcp but for UDP flows.
  2181. DEFAULT: 8
  2182. KEY: classifier_giveup_proto_other [GLOBAL]
  2183. DESC: Same as classifier_giveup_proto_tcp but for flows which IP protocol is different than
  2184. TCP and UDP.
  2185. DEFAULT: 8