-
Notifications
You must be signed in to change notification settings - Fork 0
/
UPGRADE
207 lines (183 loc) · 9.91 KB
/
UPGRADE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
UPGRAGE guidelines.
pmacct is developed keeping an eye to backward compatibility: the upgrade to some
newer version should be as smooth as possible from an user standpoint. This is
because, for example, features like SQL table versioning have been introduced
over the time.
However, sometimes the upgrade may require some easy operations aimed to support
the changes done or break old assumptions no longer valid. Such happenings have
been (and will be) very limited through the development process.
TO: >= 1.5.0rc3
FROM: <= 1.5.0rc2
TOPIC: SQL plugins, agent_id2 field
DESC: Over the years, agent_id, agent_id2 fields were found confusing to
store tag, tag2 primitives respectively. agent_id is now renamed 'tag'
and backwards compatibility is preserved by issuing schema version #9.
agent_id2 is not defined in any sql_table_schema instead and hence its
renaming will be disruptive for existing deployments.
TO: >= 1.5.0rc2
FROM: <= 1.5.0rc1
TOPIC: print plugin, dynamic file names and pointer to latest file
DESC: Until 1.5.0rc1 pointer to latest file available was built as "<plugin
name>-latest". Possibility to build variable spool directory structure
and introduction of primitives-related variables, ie. $peer_src_ip, do
phase-out the simple way of producing pointers, jeopardizing backward
compatibility aswell. From 1.5.0rc2 a print_latest_file configuration
directive allows to explicitely define pointer(s) to latest file(s):
please refer to CONFIG-KEYS for more details about the feature. When
upgrading, it is recommended to delete existing symlinks.
TO: >= 1.5.0rc2
FROM: <= 1.5.0rc1
TOPIC: print plugin, dynamic file names and time-related variables
DESC: Time-related variables substitution is now based solely on the value of
print_history. Previously, if print_history was not specified, this was
based on the value of print_refresh_time. While this breaks backward-
compatibility, it makes print plugin acting consistently to the rest of
pmacct plugins.
TO: >= 1.5.0rc1
FROM: <= 0.14.3
TOPIC: print plugin, no entries to print_output_file
DESC: In line with SQL plugins, in case there are no entries to account for the
last print_refresh_time period, the purge function will not be invoked.
As a result of that, if print_output_file contains time-based variables
and if required to, output files will not be created anymore in case of
no traffic to account for. Until 0.14.3, under same conditions, an empty
output file (title only in case of formatted, CSV output) would have been
printed out.
TO: >= 1.5.0rc1
FROM: <= 0.14.3
TOPIC: IPv6, peer_src_ip primitive, NetFlow exporter IP address
DESC: Upon enabling IPv6 at compile time, via --enable-ipv6 switch, an IPv4
NetFlow exporter IP address, ie. 10.0.0.1, was being written as IPv4-
mapped IPv6 address, ie. ::ffff:10.0.0.1. This was causing confusion
when composing maps, ie. the 'ip' field would change depending on whether
IPv6 was enabled or not. To make maps consistent and simplify transitions
to IPv6 compiled pmacct executables, IPv4-mapped IPv6 addresses are now
internally translated to plain IPv4 ones.
TO: >= 0.14.3
FROM: <= 0.14.2
TOPIC: networks_file & host aggregation primitives
DESC: In previous releases defining a networks_file in conjunction with host
aggregation primitives would automatically work as a filter (ie. zero out
hosts not included in the networks_file); whereas defining a networks_file
in conjunction with net primitives would only work as a resolver. Now this
behaviour has been streamlined by introducing a networks_file_filter true-
false configuration directive to explicitely enable/disable the filtering
feature (for both host and net primitives) on top of the resolver one. To
summarize: if using a networks_file in conjunction with host aggregation
primitives, and in order to keep the same behaviour while upgrading, a
line should be added to the configuration: "networks_file_filter: true".
TO: >= 0.14.3
FROM: <= 0.14.2
TOPIC: xlate_src and xlate_dst
DESC: Feature has been obsoleted and replaced by proper aggregation primitives
(nat_event, post_nat_*) to support NEL (NetFlow Event Logging) as currently
implemented on Cisco ASR devices and to support CGNAT kind of scenarios.
TO: >= 0.14.3
FROM: <= 0.14.2
TOPIC: nfacctd_sql_log
DESC: Feature has been obsoleted and replaced by proper aggregation primitives
(timestamp_start, timestamp_end) that effectively convert pmacct into a
logger if enabled.
TO: >= 0.14.0
FROM: <= 0.14.0rc3
TOPIC: peer_dst_ip
DESC: The peer_dst_ip primitive is being attached to IP prefix resolution method
(ie. as defined by nfacctd_net directive) from AS number resolution method
in the past (ie. as defined by nfacctd_as_new directive).
TO: >= 0.14.0
FROM: <= 0.14.0rc3
TOPIC: Fallback resolution of networks and ASNs (ie. nfacctd_net, nfacctd_as_new)
DESC: Longest match wins has been introduced to select which route resolution
method to use in fallback scenarios. For example up to 0.14.0rc3, a route
advertised via BGP would have been winning over any more specific route
learned via sFlow/NetFlow regardless.
TO: >= 0.14.0rc3
FROM: <= 0.14.0rc2
TOPIC: is_symmetric
DESC: Support for is_symmetric aggregation primitive has been ceased due to lack
of interest from the general community.
TO: >= 0.14.0rc3
FROM: <= 0.14.0rc2
TOPIC: peer_src_ip
DESC: peer_src_ip primitive must represent a reference (IP address, Agent ID) of
the NetFlow or sFlow emitter for a certain flow. Due to previous work, this
primitive was connected to the [ns]facctd_as_new mechanism which, if set to
'bgp', was making it represent the IP address of a BGP peer instead. This is
found not correct and hence peer_src_ip has now been disconnected from the
[ns]facctd_as_new feature and always constitutes a reference to the NetFlow
or sFlow emitter.
TO: >= 0.14.0rc2
FROM: <= 0.14.0rc1
TOPIC: NetFlow v9 sampling
DESC: Support for sampling in NetFlow v9 and IPFIX is elegant from an architecture
point of view - but complex if compared to NetFlow v5 and sFlow for example.
Such increased complexity lacking of proper framing by means of a supportive
RFC exposes to bizzarre and creative implementations by vendors. 0.14.0rc2
introduces fixes and workarounds to its sampled NetFlow v9 support in an
effort to tackle specific but popular platforms among operators - and which
can result in breaking some backward compatibility in this sense. 0.14.0rc2
introduces a sampling_map feature, which although not rocket science from a
concept point of view, it helps supporting sampled NetFlow v9 in heterogeneous
network hardware environments at the cost of an extra static setting to care
about; on the other hand it's also true sampling rates are often uniform and
seldomly redefined in a production network.
TO: >= 0.12.1
FROM <= 0.12.0
TOPIC: Data source for ASNs must be explicitely defined
DESC: data source for 'src_as' and 'dst_as' primitives for nfprobe and sfprobe
plugins is now expected to be explicitely defined via the [ pmacctd_as |
uacctd_as ] directive. All other plugins were already working like that.
In terms of backward compatibility the only case affected is getting ASN
values out of a Networks File: up to 0.12.0, it was sufficient to define
a networks_file to implicitely use it.
TO: >= 0.12.0rc1
FROM: <= 0.11
TOPIC: agent_id size and SQL table schemas
DESC: With release 0.12, the agent_id field becomes 4-bytes large (from 2-bytes
previously). SQL table schemas have been updated accordingly. If running
a previous release and upgrading, you might incur into the risk that both
Pre/Post-tagging infrastructures will accept values up to ~4M while the
underlying SQL table schema is configured with a 2-bytes field. Solution
is to run an "ALTER TABLE" statement to increase the field size during a
maintenance window.
TO: >= 0.12.0rc1
FROM: <= 0.11
TOPIC: nfprobe plugin: NetFlow v9 and 32-bit ASNs
DESC: Release 0.12 introduces support for 32-bit ASNs in pmacct; things do not
change in NetFlow v5 as if a 32-bit ASN is encountered, it is written as
AS23456. In NetFlow v9, though, the source and destination AS fields are
specified as 4 bytes long in the template. Given the template nature of
NetFlow v9, this shouldn't pose a problem with 3rd party implementations
but it's better to pay some extra attention while upgrading an existing
installation.
TO: >= 0.10.0
FROM: <= 0.10.0rc3
TOPIC: Configuration directives and command-line options
DESC: In all previous releases, commandline options ( ie. -D -c ) were mutually
exclusive with respect to configuration directives; now, they can cohexist
and, more specifically, commandline options will override the content of
the configuration file. This exposes to more interesting usages:
shell> pmacctd -I <tracefile> -f <cfg>
to launch pmacctd sharing an unique configuration file while reading data
from different tcpdump/ethereal tracefiles among multiple runs.
TO: >= 0.8.3
FROM: <= 0.8.2
TOPIC: Pre-Tagging, Post-Tagging
DESC: In all previous releases, the 'pre_tag_map' and 'post_tag' directives were
causing the captured traffic to be automatically tagged while forwarded to
each active plugin; this behaviour can result in reduced flexibility; the
0.8.3 release makes the two forementioned directives just to evaluate the
tag to be assigned to captured traffic; a new 'aggregate' directive keyword
- tag - causes the traffic to be marked (basing on the previous evaluation).
So, a configuration like the following:
...
pre_tag_map: /usr/local/pmacct/pre_tag.map
aggregate[dummy]: src_host,dst_host,src_port,dst_port
...
Have to be rewritten the following way in order for the plugin 'dummy' to
receive the tags:
...
pre_tag_map: /usr/local/pmacct/pre_tag.map
aggregate[dummy]: tag,src_host,dst_host,src_port,dst_port
...
[EOF]