Overview

• Initialize an exporter
• Add one or more collectors that receive the monitoring data
• Define one or more templates
• Loop 1
• Loop 2
• Start a data set for a given template
• Assemble one or more data records according to the template (convert to network byte order first, if necessary)
• End data set
• Call ipfix_send to trigger the export of the monitoring data to the collector
• Deinit the exporter to terminate

For a detailed and commented example, see example_code.c in the doc/ directory.

Synopsis

#include "ipfixlolib.h"

typedef struct ipfix_exporter

int ipfix_init_exporter(uint32_t source_id, ipfix_exporter **exporter)
int ipfix_deinit_exporter(ipfix_exporter *exporter)
int ipfix_add_collector(ipfix_exporter* exporter, char* coll_ip4_addr, int coll_port, ipfix_transport_protocol proto)
int ipfix_remove_collector(ipfix_exporter* exporter, char *coll_ip4_addr, int coll_port)

int ipfix_start_template_set(ipfix_exporter* exporter, uint16_t template_id, uint16_t field_count)
int ipfix_start_optionstemplate_set(ipfix_exporter* exporter, uint16_t template_id, uint16_t scope_length, uint16_t option_length)
int ipfix_start_datatemplate_set(ipfix_exporter* exporter, uint16_t template_id, uint16_t field_count, uint16_t fixedfield_count)
int ipfix_put_template_field(ipfix_exporter* exporter, uint16_t template_id, uint16_t length, uint16_t type, uint32_t enterprise)
int ipfix_put_template_fixedfield(ipfix_exporter *exporter, uint16_t template_id, uint16_t template_id, uint16_t type, uint16_t length, uint32_t enterprise_id)
int ipfix_put_template_data(ipfix_exporter *exporter, uint16_t template_id, void* data, uint16_t data_length)
int ipfix_end_template_set(ipfix_exporter *exporter, uint16_t template_id)
int ipfix_remove_template_set(ipfix_exporter* exporter, uint16_t template_id)

int ipfix_start_data_set(ipfix_exporter* exporter, uint16_t template_id)
void ipfix_put_data_field(ipfix_exporter *exporter, char *data, uint16_t length)
int ipfix_set_data_field_marker(ipfix_exporter *exporter);
int ipfix_delete_data_fields_upto_marker(ipfix_exporter *exporter);
int ipfix_end_data_set(ipfix_exporter *exporter, uint16_t number_of_records)
int ipfix_cancel_data_set(ipfix_exporter *exporter);


int ipfix_send(ipfix_exporter *exporter)

int ipfix_id_rangecheck(int id)

int ipfix_name_lookup(char *name)
struct ipfix_identifier * ipfix_id_lookup(int n)

struct ipfix_identifier {
        char *name;
        uint16_t id;
        uint8_t length;
};


List of valid field identifiers

Remark:

IPFIXLOLIB does not provide any conversion of monitoring data into network byte order. This has to be done by the user. On the contrary, template IDs, field IDs etc. have to be provided in host byte order (there is one exception in ipfix_start_data_set).

In the following, parameters that have to be provided in network byte order are marked with NBO in the description.

Detailed description

typedef struct ipfix_exporter;

typedef struct {
	uint32_t sequence_number;
	uint32_t source_id;
	ipfix_sendbuffer *template_sendbuffer;
	ipfix_sendbuffer *data_sendbuffer;
	int collector_num;
	int collector_max_num;
	ipfix_receiving_collector *collector_arr;

	uint32_t last_template_transmission_time;
	uint32_t template_transmission_timer;

	int ipfix_lo_template_maxsize;
	int ipfix_lo_template_current_count;
	ipfix_lo_template *template_arr;

} ipfix_exporter;

Initialize a new exporter.

source_id: denotes the exporter's source ID
exporter: a pointer to a pointer to the exporter struct

Cleanup previously initialized exporter and free memory.

exporter: pointer to exporter struct

Add a collector to the given exporter and open connection.

exporter: pointer to the previously initialized exporter struct
coll_ip4_addr: IP address of receiving collector in dotted notation (eg 1.2.3.4)
coll_port: port number of receiving collector
proto: transport protocol to use (check for current implementation state)
enum ipfix_transport_protocol { UDP, TCP, SCTP }

Remove collector from the exporter and close connection

exporter: pointer to exporter struct
coll_ip4_addr: IP address of receiving collector in dotted notation
coll_port: port number of receiving collector

Start defining a new template.

exporter: pointer to exporter struct
template_id: ID for this template
field_count: number of fields to add

NOTE: It is not possible to start and define multiple templates in parallel.
ipfix_end_template_set() has to be called first before a new template can be defined.

Start defining a new option template.

exporter: pointer to exporter struct
template_id: ID for this template
scope_length: length of the scope, in bytes
option_length: length of options

NOTE: It is not possible to start and define multiple templates in parallel.
ipfix_end_template_set() has to be called first before a new template can be defined.

Start defining a new data template.

exporter: pointer to exporter struct
template_id: an ID for this template
field_count: number of fields to add
fixedfield_count: number of fixed-value fields to add

NOTE: It is not possible to start and define multiple templates in parallel.
ipfix_end_template_set() has to be called first before a new template can be defined.

Add a field to the previously started template, options template, or data template.

exporter: pointer to exporter struct
template_id: ID of the template
length: length of field, in bytes
type: type of field; see template fields
enterprise: enterprise number (set to 0 if not used)

Add a fixed-value data type field to the previously started data template.

exporter: pointer to exporter struct
template_id: ID of the template
length: length of field, in bytes
type: type of field; see template fields
enterprise: enterprise number (set to 0 if not used)

Add fixed-value data to the previously started data template.

exporter: pointer to exporter struct
template_id: ID of the template
data: pointer to the data (NBO)
data_length: length of data to be added, in bytes

End a previously started and defined template, options template, or data template.

exporter: pointer to exporter struct
template_id: ID of the template

Remove a template, options template, or data template from the exporter and free resources.

exporter: the exporter
template_id: ID of the template to be removed

Start a new data set.

exporter: pointer to exporter struct
template_id: ID of a previously defined template (NBO here, because we want to avoid frequent conversions)

NOTE: It is not possible to start multiple data sets in parallel.
ipfix_end_data_set() has to be called first.

Add data to a previously started data set. This function is realized as a macro.

exporter: pointer to exporter struct
data: pointer to the data (NBO)
length: length of data, in bytes

NOTE: The data pointed to by *data has to be valid until ipfix_send() has been called, since the data is not copied.
The data must be in network byte order for compatibility; no conversion is done.

Sets a marker to the current position in order to be able to undo the following fields with ipfix_delete_data_fields_upto_marker.

exporter: pointer to exporter struct

Undos (deletes) previously added fields up to the marker set with ipfix_set_data_field_marker.

exporter: pointer to exporter struct

NOTE: Only fields within an "unended" set can be deleted, i.e. before calling ipfix_end_data_set.

End a previously started data set.

exporter: pointer to exporter struct
number_of_records: number of records included in the terminated set (used to update the sequence number of the next IPFIX message)

Cancel a previously started data set. Can be used instead of ipfix_end_data_set.

exporter: pointer to exporter struct

Send an IPFIX packet with the added data sets. If necessary, an IPFIX packet including the templates is (re)sent before.
(The sending of templates is handled transparently by this function: If a template has changed or a timeout for periodic sending has occured, the all templates are resent.)

exporter: pointer to exporter struct

NOTE: The *data off all data fields in the data sets have to remain valid until this function returns.

Retrieve the IPFIX / PSAMP ID of a given string. -1 indicates "not found".

Retrieve full info about an IPFIX / PSAMP ID, including name, ID and length (in bytes).
FIXME: HOW TO DISTINGUISH MULTI-OCTET (OCTET-STRING) FIELDS?

Check if a given ID is within valid IPFIX/PSAMP ranges.
Return 0 on error (because we think boolean).

Appendix

Range	Description
0	reserved
1 - 127	standardized field IDs, compatible to NetFlow version 9
128 - 32767	standardized field IDs, assigned by IANA
32768 - 65535	vendor-defined field IDs

IPFIX

ID	Name
0	RESERVED
1	octetDeltaCount	unsigned64
2	packetDeltaCount	unsigned64
3	RESERVED
4	protocolIdentifier	octet
5	classOfServiceIPv4	octet
6	tcpControlBits	octet
7	sourceTransportPort	unsigned16
8	sourceIPv4Address	ipv4Address
9	sourceIPv4Mask	octet
10	ingressInterface	unsigned32
11	destinationTransportPort	unsigned16
12	destinationIPv4Address	ipv4Address
13	destinationIPv4Mask	octet
14	egressInterface	unsigned32
15	ipNextHopIPv4Address	ipv4Address
16	bgpSourceAsNumber	unsigned16
17	bgpDestinationAsNumber	unsigned16
18	bgpNextHopIPv4Address	ipv4Address
19	postMCastPacketDeltaCount	unsigned64
20	postMCastOctetDeltaCount	unsigned64
21	flowEndSysUpTime	unsigned32
22	flowStartSysUpTime	unsigned32
23	postOctetDeltaCount	unsigned64
24	postPacketDeltaCount	unsigned64
25	minimumPacketLength	unsigned16
26	maximumPacketLength	unsigned16
27	sourceIPv6Address	ipv6Address
28	destinationIPv6Address	ipv6Address
29	sourceIPv6Mask	octet
30	destinationIPv6Mask	octet
31	flowLabelIPv6	unsigned32
32	icmpTypeCodeIPv4	unsigned16
33	igmpType	octet
34	RESERVED
35	RESERVED
36	flowActiveTimeOut	unsigned16
37	flowInactiveTimeout	unsigned16
38	RESERVED
39	RESERVED
40	exportedOctetTotalCount	unsigned64
41	exportedMessageTotalCount	unsigned64
42	exportedFlowTotalCount	unsigned64
43	RESERVED
44	sourceIPv4Prefix	ipv4Address
45	destinationIPv4Prefix	ipv4Address
46	mplsTopLabelType	octet
47	mplsTopLabelIPv4Address	ipv4Address
48	RESERVED
49	RESERVED
50	RESERVED
51	RESERVED
52	minimumTTL	octet
53	maximumTTL	octet
54	identificationIPv4	unsigned16
55	postClassOfServiceIPv4	octet
56	sourceMacAddress	macAddress
57	postDestinationMacAddress	macAddress
58	vlanId	unsigned16
59	postVlanId	unsigned16
60	ipVersion	octet
61	RESERVED
62	ipNextHopIPv6Address	ipv6Address
63	bgpNextHopIPv6Address	ipv6Address
64	ipv6ExtensionHeaders	unsigned32
65	RESERVED
66	RESERVED
67	RESERVED
68	RESERVED
69	RESERVED
70	mplsTopLabelStackEntry	unsigned32
71	mplsLabelStackEntry2	unsigned32
72	mplsLabelStackEntry3	unsigned32
73	mplsLabelStackEntry4	unsigned32
74	mplsLabelStackEntry5	unsigned32
75	mplsLabelStackEntry6	unsigned32
76	mplsLabelStackEntry7	unsigned32
77	mplsLabelStackEntry8	unsigned32
78	mplsLabelStackEntry9	unsigned32
79	mplsLabelStackEntry10	unsigned32
80	destinationMacAddress	macAddress
81	postSourceMacAddress	macAddress
82	RESERVED
83	RESERVED
84	RESERVED
85	octetTotalCount	unsigned64
86	packetTotalCount	unsigned64
87	RESERVED
88	fragmentOffsetIPv4	unsigned16
89	RESERVED
90	RESERVED
91	RESERVED
92	RESERVED
93	RESERVED
94	RESERVED
95	RESERVED
96	RESERVED
97	RESERVED
98	RESERVED
99	RESERVED
100	RESERVED
101	RESERVED
102	RESERVED
103	RESERVED
104	RESERVED
105	RESERVED
106	RESERVED
107	RESERVED
108	RESERVED
109	RESERVED
110	RESERVED
111	RESERVED
112	RESERVED
113	RESERVED
114	RESERVED
115	RESERVED
116	RESERVED
117	RESERVED
118	RESERVED
119	RESERVED
120	RESERVED
121	RESERVED
122	RESERVED
123	RESERVED
124	RESERVED
125	RESERVED
126	RESERVED
127	RESERVED
128	bgpNextAdjacentAsNumber	unsigned16
129	bgpPrevAdjacentAsNumber	unsigned16
130	exporterIPv4Address	ipv4Address
131	exporterIPv6Address	ipv6Address
132	droppedOctetDeltaCount	unsigned64
133	droppedPacketDeltaCount	unsigned64
134	droppedOctetTotalCount	unsigned64
135	droppedPacketTotalCount	unsigned64
136	flowEndReason	octet
137	classOfServiceIPv6	octet
138	postClassOfServiceIPv6	octet
139	icmpTypeCodeIPv6	unsigned16
140	mplsTopLabelIPv6Address	ipv6Address
141	lineCardId	unsigned32
142	portId	unsigned32
143	meteringProcessId	unsigned32
144	exportingProcessId	unsigned32
145	templateId	unsigned16
146	wlanChannelId	octet
147	wlanSsid	string
148	flowId	unsigned32
149	sourceId	unsigned32
150	flowStartSeconds	dateTimeSeconds
151	flowEndSeconds	dateTimeSeconds
152	flowStartMilliSeconds	dateTimeMilliSeconds
153	flowEndMilliSeconds	dateTimeMilliSeconds
154	flowStartMicroSeconds	dateTimeMicroSeconds
155	flowEndMicroSeconds	dateTimeMicroSeconds
156	flowStartNanoSeconds	dateTimeNanoSeconds
157	flowEndNanoSeconds	dateTimeNanoSeconds
158	flowStartDeltaMicroSeconds	dateTimeMicroSeconds
159	flowEndDeltaMicroSeconds	dateTimeMicroSeconds
160	systemInitTimeMilliSeconds	dateTimeMilliSeconds
161	flowDurationMilliSeconds	dateTimeMilliSeconds
162	flowDurationMicroSeconds	dateTimeMicroSeconds
163	observedFlowTotalCount	unsigned64
164	ignoredPacketTotalCount	unsigned64
165	ignoredOctetTotalCount	unsigned64
166	notSentFlowTotalCount	unsigned64
167	notSentPacketTotalCount	unsigned64
168	notSentOctetTotalCount	unsigned64
169	destinationIPv6Prefix	ipv6Address
170	sourceIPv6Prefix	ipv6Address
171	postOctetTotalCount	unsigned64
172	postPacketTotalCount	unsigned64
173	flowKeyIndicator	unsigned64
174	postMCastPacketTotalCount	unsigned64
175	postMCastOctetTotalCount	unsigned64
176	icmpTypeIPv4	octet
177	icmpCodeIPv4	octet
178	icmpTypeIPv6	octet
179	icmpCodeIPv6	octet
180	udpSourcePort	unsigned16
181	udpDestinationPort	unsigned16
182	tcpSourcePort	unsigned16
183	tcpDestinationPort	unsigned16
184	tcpSequenceNumber	unsigned32
185	tcpAcknowledgementNumber	unsigned32
186	tcpWindowSize	unsigned16
187	tcpUrgentPointer	unsigned16
188	tcpHeaderLength	unsigned16
189	ipHeaderLength	octet
190	totalLengthIPv4	unsigned16
191	payloadLengthIPv6	unsigned32
192	ipTimeToLive	octet
193	nextHeaderIPv6	octet
194	ipClassOfService	octet
195	ipDiffServCodePoint	octet
196	ipPrecedence	octet
197	fragmentFlagsIPv4	octet
198	octetDeltaSumOfSquares	unsigned64
199	octetTotalSumOfSquares	unsigned64
200	mplsTopLabelTtl	octet
201	mplsLabelStackLength	unsigned32
202	mplsLabelStackDepth	unsigned32
203	mplsTopLabelExp	octet
204	ipPayloadLength	unsigned64
205	udpMessageLength	unsigned16
206	isMulticast	octet
207	internetHeaderLengthIPv4	octet
208	ipv4Options	unsigned32
209	tcpOptions	unsigned64
210	paddingOctets	octetArray
211	RESERVED
212	RESERVED
213	headerLengthIPv4	octet
214	mplsPayloadLength	unsigned32

PSAMP

ID	Name
300	selectorId	unsigned16
301	selectorInputSequenceNumber	unsigned32
302	selectorAlgorithm	octet
303	RESERVED
304	samplingPacketInterval	unsigned32
305	samplingPacketSpace	unsigned32
306	samplingTimeInterval	dateTimeMicroSeconds
307	samplingTimeSpace	dateTimeMicroSeconds
308	samplingPopulation	unsigned32
309	samplingSize	unsigned32
310	samplingProbabilityN	unsigned32
311	samplingProbabilityM	unsigned32
312	RESERVED
313	ipHeaderPacketSection	octetArray
314	ipPayloadPacketSection	octetArray
315	l2HeaderPacketSection	octetArray
316	l2PayloadPacketSection	octetArray
317	mplsLabelStackSection	octetArray
318	mplsPayloadPacketSection	octetArray
319	meteringProcesssId	octet
320	ObservationPointID	octet
321	associationsId	octet
322	RESERVED
323	selectorType	octet
324	packetsObserved	octet
325	packetsSelected	octet
326	accuracy	octet
327	RESERVED
328	RESERVED
329	RESERVED