Provided by: python3-ipfix_0.9.7-1_all 
NAME
python-ipfix - python-ipfix Documentation
IPFIX implementation for Python 3.3.
This module provides a Python interface to IPFIX message streams, and provides tools for
building IPFIX Exporting and Collecting Processes. It handles message framing and
deframing, encoding and decoding IPFIX data records using templates, and a bridge between
IPFIX ADTs and appropriate Python data types.
Before using any of the functions of this module, it is necessary to populate the
information model with Information Elements. ipfix.ie.use_iana_default() populates the
default IANA IPFIX Information Element Registry shipped with the module; this is the
current registry as of release time. ipfix.ie.use_5103_default() populates the reverse
counterpart IEs as in RFC 5103. The module also supports the definition of
enterprise-specific Information Elements via ipfix.ie.for_spec() and
ipfix.ie.use_specfile(); see ipfix.ie for more.
For reading and writing of records to IPFIX message streams with automatic message
boundary management, see the ipfix.reader and ipfix.writer modules, respectively. For
manual reading and writing of messages, see ipfix.message. In any case, exporters will
need to define templates; see ipfix.template.
This module is copyright 2013 Brian Trammell. It is made available under the terms of the
GNU Lesser General Public License, version 3 or, at your option, any later version.
Reference documentation for each module is found in the subsections below.
MODULE IPFIX.TYPES
Implementation of IPFIX abstract data types (ADT) and mappings to Python types.
Maps each IPFIX ADT to the corresponding Python type, as below:
┌─────────────────────┬─────────────┐
│IPFIX Type │ Python Type │
├─────────────────────┼─────────────┤
│octetArray │ bytes │
├─────────────────────┼─────────────┤
│unsigned8 │ int │
├─────────────────────┼─────────────┤
│unsigned16 │ int │
├─────────────────────┼─────────────┤
│unsigned32 │ int │
├─────────────────────┼─────────────┤
│unsigned64 │ int │
├─────────────────────┼─────────────┤
│signed8 │ int │
├─────────────────────┼─────────────┤
│signed16 │ int │
├─────────────────────┼─────────────┤
│signed32 │ int │
├─────────────────────┼─────────────┤
│signed64 │ int │
├─────────────────────┼─────────────┤
│float32 │ float │
├─────────────────────┼─────────────┤
│float64 │ float │
├─────────────────────┼─────────────┤
│boolean │ bool │
└─────────────────────┴─────────────┘
│macAddress │ bytes │
├─────────────────────┼─────────────┤
│string │ str │
├─────────────────────┼─────────────┤
│dateTimeSeconds │ datetime │
├─────────────────────┼─────────────┤
│dateTimeMilliseconds │ datetime │
├─────────────────────┼─────────────┤
│dateTimeMicroseconds │ datetime │
├─────────────────────┼─────────────┤
│dateTimeNanoseconds │ datetime │
├─────────────────────┼─────────────┤
│ipv4Address │ ipaddress │
├─────────────────────┼─────────────┤
│ipv6Address │ ipaddress │
└─────────────────────┴─────────────┘
Though client code generally will not use this module directly, it defines how each IPFIX
abstract data type will be represented in Python, and the concrete IPFIX representation of
each type. Type methods operate on buffers, as used internally by the
ipfix.message.MessageBuffer class, so we'll create one to illustrate encoding and
decoding:
>>> import ipfix.types
>>> buf = memoryview(bytearray(16))
Each of the encoding methods returns the offset into the buffer of the first byte after
the encoded value; since we're always encoding to the beginning of the buffer in this
example, this is equivalent to the length. We use this to bound the encoded value on
subsequent decode.
Integers are represented by the python int type:
>>> unsigned32 = ipfix.types.for_name("unsigned32")
>>> length = unsigned32.encode_single_value_to(42, buf, 0)
>>> buf[0:length].tolist()
[0, 0, 0, 42]
>>> unsigned32.decode_single_value_from(buf, 0, length)
42
...floats by the float type, with the usual caveats about precision:
>>> float32 = ipfix.types.for_name("float32")
>>> length = float32.encode_single_value_to(42.03579, buf, 0)
>>> buf[0:length].tolist()
[66, 40, 36, 166]
>>> float32.decode_single_value_from(buf, 0, length)
42.035789489746094
...strings by the str type, encoded as UTF-8:
>>> string = ipfix.types.for_name("string")
>>> length = string.encode_single_value_to("Grüezi", buf, 0)
>>> buf[0:length].tolist()
[71, 114, 195, 188, 101, 122, 105]
>>> string.decode_single_value_from(buf, 0, length)
'Grüezi'
...addresses as the IPv4Address and IPv6Address types in the ipaddress module:
>>> from ipaddress import ip_address
>>> ipv4Address = ipfix.types.for_name("ipv4Address")
>>> length = ipv4Address.encode_single_value_to(ip_address("198.51.100.27"), buf, 0)
>>> buf[0:length].tolist()
[198, 51, 100, 27]
>>> ipv4Address.decode_single_value_from(buf, 0, length)
IPv4Address('198.51.100.27')
>>> ipv6Address = ipfix.types.for_name("ipv6Address")
>>> length = ipv6Address.encode_single_value_to(ip_address("2001:db8::c0:ffee"), buf, 0)
>>> buf[0:length].tolist()
[32, 1, 13, 184, 0, 0, 0, 0, 0, 0, 0, 0, 0, 192, 255, 238]
>>> ipv6Address.decode_single_value_from(buf, 0, length)
IPv6Address('2001:db8::c0:ffee')
...and the timestamps of various precision as a python datetime, encoded as per
RFC5101bis:
>>> from datetime import datetime
>>> from datetime import timezone
>>> dtfmt = "%Y-%m-%d %H:%M:%S.%f"
>>> dt = datetime.strptime("2013-06-21 14:00:03.456789", dtfmt)
dateTimeSeconds truncates microseconds:
>>> dateTimeSeconds = ipfix.types.for_name("dateTimeSeconds")
>>> length = dateTimeSeconds.encode_single_value_to(dt, buf, 0)
>>> buf[0:length].tolist()
[81, 196, 92, 99]
>>> dateTimeSeconds.decode_single_value_from(buf, 0, length).strftime(dtfmt)
'2013-06-21 14:00:03.000000'
dateTimeMilliseconds truncates microseconds to the nearest millisecond:
>>> dateTimeMilliseconds = ipfix.types.for_name("dateTimeMilliseconds")
>>> length = dateTimeMilliseconds.encode_single_value_to(dt, buf, 0)
>>> buf[0:length].tolist()
[0, 0, 1, 63, 103, 8, 228, 128]
>>> dateTimeMilliseconds.decode_single_value_from(buf, 0, length).strftime(dtfmt)
'2013-06-21 14:00:03.456000'
dateTimeMicroseconds exports microseconds fully in NTP format:
>>> dateTimeMicroseconds = ipfix.types.for_name("dateTimeMicroseconds")
>>> length = dateTimeMicroseconds.encode_single_value_to(dt, buf, 0)
>>> buf[0:length].tolist()
[81, 196, 92, 99, 116, 240, 32, 0]
>>> dateTimeMicroseconds.decode_single_value_from(buf, 0, length).strftime(dtfmt)
'2013-06-21 14:00:03.456789'
dateTimeNanoseconds is also supported, but is identical to dateTimeMicroseconds, as the
datetime class in Python only supports microsecond-level timing.
class ipfix.types.IpfixType(name, num, valenc, valdec, valstr, valparse, roottype=None)
Abstract interface for all IPFIX types. Used internally.
exception ipfix.types.IpfixTypeError(*args)
Raised when attempting to do an unsupported operation on a type
class ipfix.types.OctetArrayType(name, num, valenc=<function _identity>, valdec=<function
_identity>, valstr=<built-in function hexlify>, valparse=<built-in function unhexlify>,
roottype=None)
Type encoded by byte array packing. Used internally.
class ipfix.types.StructType(name, num, stel, valenc=<function _identity>,
valdec=<function _identity>, valstr=<class 'str'>, valparse=<class 'int'>, roottype=None)
Type encoded by struct packing. Used internally.
ipfix.types.decode_varlen(buf, offset)
Decode a IPFIX varlen encoded length; used internally by template
ipfix.types.encode_varlen(buf, offset, length)
Encode a IPFIX varlen encoded length; used internally by template
ipfix.types.for_name(name)
Return an IPFIX type for a given type name
Parameters
name -- the name of the type to look up
Returns
IpfixType -- type instance for that name
Raises IpfixTypeError
ipfix.types.use_integer_ipv4()
Use integers instead of ipaddress.IPv4Address to store IPv4 addresses. Changes
behavior globally; should be called before using any IPFIX types. Designed for use
with numpy arrays, to not require a Python object for storing IP addresses.
MODULE IPFIX.IE
IESpec-based interface to IPFIX information elements, and interface to use the default
IPFIX IANA Information Model
An IESpec is a string representation of an IPFIX information element, including all the
information required to define it, as documented in Section 9 of
http://tools.ietf.org/html/draft-ietf-ipfix-ie-doctors. It has the format:
name(pen/num)<type>[size]
To specify a new Information Element, a complete IESpec must be passed to for_spec():
>>> import ipfix.ie
>>> e = ipfix.ie.for_spec("myNewInformationElement(35566/1)<string>")
>>> e
InformationElement('myNewInformationElement', 35566, 1, ipfix.types.for_name('string'), 65535)
The string representation of an InformationElement is its IESpec:
>>> str(e)
'myNewInformationElement(35566/1)<string>[65535]'
To get an Information Element already specified, an incomplete specification can be
passed; a name or number is enough:
>>> ipfix.ie.use_iana_default()
>>> ipfix.ie.use_5103_default()
>>> str(ipfix.ie.for_spec("octetDeltaCount"))
'octetDeltaCount(0/1)<unsigned64>[8]'
>>> str(ipfix.ie.for_spec("(2)"))
'packetDeltaCount(0/2)<unsigned64>[8]'
Reduced-length encoding and fixed-length sequence types are supported by the for_length
method; this is used internally by templates.
>>> str(e.for_length(32))
'myNewInformationElement(35566/1)<string>[32]'
An Information Element object can also be used to translate between native Python and
string representations of an Information Element value:
>>> ipfix.ie.for_spec("sourceIPv4Address").parse("192.0.2.19")
IPv4Address('192.0.2.19')
>>> from datetime import datetime
>>> ipfix.ie.for_spec("flowEndMilliseconds").unparse(datetime(2013,6,21,14))
'2013-06-21 14:00:00.000'
Most client code will only need the use_iana_default(), use_5103_default(), and
use_specfile() functions; client code using tuple interfaces will need spec_list() as
well.
class ipfix.ie.InformationElement(name, pen, num,
ietype=ipfix.types.for_name('octetArray'), length=None, valstr=None, valparse=None)
An IPFIX Information Element (IE). This is essentially a five-tuple of name,
element number (num), a private enterprise number (pen; 0 if it is an IANA
registered IE), a type, and a length.
Information Elements may also have value string and parser functions, for
representing the values as strings; if not set, these default to
InformationElement instances should be obtained using the for_spec() or
for_template_entry() functions.
for_length(length)
Get an instance of this IE for the specified length. Used to support
reduced-length encoding (RLE).
Parameters
length -- length of the new IE
Returns
this IE if length matches, or a new IE for the length
Raises ValueError
parse(s)
Parse a string to a value using the conversion function for this Information
Element. Uses the default string conversion for the IE's type if not
overridden at IE creation time.
Parameters
s -- string to parse using this IEs's string conversion
Returns
value for given string
Raises ValueError is not a valid string representation for this IE
unparse(v)
Unparse a value to a string using the conversion function for this
Information Element. Uses the default string conversion for the IE's type if
not overridden at IE creation time.
Parameters
v -- value to unparse using this IEs's string conversion
Returns
string representation of v
Raises ValueError if v is not a valid value for this IE
class ipfix.ie.InformationElementList(iterable=None)
A hashable ordered list of Information Elements.
Used internally by templates, and to specify the order of tuples to the tuple
append and iterator interfaces. Get an instance by calling spec_list()
ipfix.ie.clear_infomodel()
Reset the cache of known Information Elements.
ipfix.ie.for_spec(spec)
Get an IE from the cache of known IEs, or create a new IE if not found, given an
IESpec.
Parameters
spec -- IEspec, as in draft-ietf-ipfix-ie-doctors, of the form
name(pen/num)<type>[size]; some fields may be omitted unless creating a new
IE in the cache.
Returns
an IE for the name
Raises ValueError
ipfix.ie.for_template_entry(pen, num, length)
Get an IE from the cache of known IEs, or create a new IE if not found, given a
private enterprise number, element number, and length. Used internally by
Templates.
Parameters
• pen -- private enterprise number, or 0 for an IANA IE
• num -- IE number (Element ID)
• length -- length of the IE in bytes
Returns
an IE for the given pen, num, and length. If the IE has not been previously
added to the cache of known IEs, the IE will be named _ipfix_pen_num, and
have octetArray as a type.
ipfix.ie.parse_spec(spec)
Parse an IESpec into name, pen, number, typename, and length fields
ipfix.ie.spec_list(specs)
Given a list or iterable of IESpecs, return a hashable list of IEs. Pass this as
the ielist argument to the tuple export and iterator functions.
Parameters
specs -- list of IESpecs
Returns
a new Information Element List, suitable for use with the tuple export and
iterator functions in message
Raises ValueError
ipfix.ie.use_5103_default()
Load the module internal list of RFC 5103 reverse IEs for IANA registered IEs into
the cache of known IEs. Normally, biflow-aware client code should call this just
after use_iana_default().
ipfix.ie.use_iana_default()
Load the module internal list of IANA registered IEs into the cache of known IEs.
Normally, client code should call this before using any other part of this module.
ipfix.ie.use_specfile(filename)
Load a file listing IESpecs into the cache of known IEs
Parameters
filename -- name of file containing IESpecs to open
Raises ValueError
MODULE IPFIX.TEMPLATE
Representation of IPFIX templates. Provides template-based packing and unpacking of data
in IPFIX messages.
For reading, templates are handled internally. For writing, use from_ielist() to create a
template.
See ipfix.message for examples.
exception ipfix.template.IpfixDecodeError(*args)
Raised when decoding a malformed IPFIX message
exception ipfix.template.IpfixEncodeError(*args)
Raised on internal encoding errors, or if message MTU is too small
class ipfix.template.Template(tid=0, iterable=None)
An IPFIX Template.
A template is an ordered list of IPFIX Information Elements with an ID.
append(ie)
Append an IE to this Template
count()
Count IEs in this template
decode_from(buf, offset, packplan=None)
Decodes a record into a tuple containing values in template order
decode_namedict_from(buf, offset, recinf=None)
Decodes a record from a buffer into a dict keyed by IE name.
decode_tuple_from(buf, offset, recinf=None)
Decodes a record from a buffer into a tuple, ordered as the IEs in the
InformationElementList given as recinf.
encode_namedict_to(buf, offset, rec, recinf=None)
Encodes a record from a dict containing values keyed by IE name
encode_template_to(buf, offset, setid)
Encodes the template to a buffer. Encodes as a Template if setid is
TEMPLATE_SET_ID, as an Options Template if setid is OPTIONS_SET_ID.
encode_to(buf, offset, vals, packplan=None)
Encodes a record from a tuple containing values in template order
encode_tuple_to(buf, offset, rec, recinf=None)
Encodes a record from a tuple containing values ordered as the IEs in the
template.
finalize()
Compile a default packing plan. Called after append()ing all IEs.
fixlen_count()
Count of fixed-length IEs in this template before the first variable-length
IE; this is the size of the portion of the template which can be
encoded/decoded efficiently.
identical_to(other)
Determine if two templates are identical to each other.
Two templates are considered identical if they contain the same IEs in the
same order, and the same scope count. Template ID is not considered as part
of the test for template identity.
packplan_for_ielist
Given a list of IEs, devise and cache a packing plan. Used by the tuple
interfaces.
class ipfix.template.TemplatePackingPlan(tmpl, indices)
Plan to pack/unpack a specific set of indices for a template. Used internally by
Templates for efficient encoding and decoding.
ipfix.template.decode_template_from(buf, offset, setid)
Decodes a template from a buffer. Decodes as a Template if setid is
TEMPLATE_SET_ID, as an Options Template if setid is OPTIONS_SET_ID.
ipfix.template.for_specs(tid, *specs)
Create a template from a template ID and a list of IESpecs
Parameters
• tid -- Template ID, must be between 256 and 65535.
• *specs --
List of IESpecs
Returns
A new Template, ready to use for writing to a Message
MODULE IPFIX.MESSAGE
Provides the MessageBuffer class for encoding and decoding IPFIX Messages.
This interface allows direct control over Messages; for reading or writing records
automatically from/to streams, see ipfix.reader and ipfix.writer, respectively.
To create a message buffer:
>>> import ipfix.message
>>> msg = ipfix.message.MessageBuffer()
>>> msg
<MessageBuffer domain 0 length 0>
To prepare the buffer to write records:
>>> msg.begin_export(8304)
>>> msg
<MessageBuffer domain 8304 length 16 (writing)>
Note that the buffer grows to contain the message header.
To write records to the buffer, first you'll need a template:
>>> import ipfix.ie
>>> ipfix.ie.use_iana_default()
>>> import ipfix.template
>>> tmpl = ipfix.template.from_ielist(256,
... ipfix.ie.spec_list(("flowStartMilliseconds",
... "sourceIPv4Address",
... "destinationIPv4Address",
... "packetDeltaCount")))
>>> tmpl
<Template ID 256 count 4 scope 0>
To add the template to the message:
>>> msg.add_template(tmpl)
>>> msg
<MessageBuffer domain 8304 length 40 (writing set 2)>
Note that MessageBuffer.add_template() exports the template when it is written by default,
and that the current set ID is 2 (template set).
Now, a set must be created to add records to the message; the set ID must match the ID of
the template. MessageBuffer automatically uses the template matching the set ID for record
encoding.
>>> msg.export_ensure_set(256)
>>> msg
<MessageBuffer domain 8304 length 44 (writing set 256)>
Records can be added to the set either as dictionaries keyed by IE name:
>>> from datetime import datetime
>>> from ipaddress import ip_address
>>> rec = { "flowStartMilliseconds" : datetime.strptime("2013-06-21 14:00:00",
... "%Y-%m-%d %H:%M:%S"),
... "sourceIPv4Address" : ip_address("10.1.2.3"),
... "destinationIPv4Address" : ip_address("10.5.6.7"),
... "packetDeltaCount" : 27 }
>>> msg.export_namedict(rec)
>>> msg
<MessageBuffer domain 8304 length 68 (writing set 256)>
or as tuples in template order:
>>> rec = (datetime.strptime("2013-06-21 14:00:02", "%Y-%m-%d %H:%M:%S"),
... ip_address("10.8.9.11"), ip_address("10.12.13.14"), 33)
>>> msg.export_tuple(rec)
>>> msg
<MessageBuffer domain 8304 length 92 (writing set 256)>
Variable-length information elements will be encoded using the native length of the passed
value:
>>> ipfix.ie.for_spec("myNewInformationElement(35566/1)<string>")
InformationElement('myNewInformationElement', 35566, 1, ipfix.types.for_name('string'), 65535)
>>> tmpl = ipfix.template.from_ielist(257,
... ipfix.ie.spec_list(("flowStartMilliseconds",
... "myNewInformationElement")))
>>> msg.add_template(tmpl)
>>> msg.export_ensure_set(257)
>>> msg
<MessageBuffer domain 8304 length 116 (writing set 257)>
>>> rec = { "flowStartMilliseconds" : datetime.strptime("2013-06-21 14:00:04",
... "%Y-%m-%d %H:%M:%S"),
... "myNewInformationElement" : "Grüezi, Y'all" }
>>> msg.export_namedict(rec)
>>> msg
<MessageBuffer domain 8304 length 139 (writing set 257)>
Attempts to write past the end of the message (set via the mtu parameter, default 65535)
result in EndOfMessage being raised.
Messages can be written to a stream using MessageBuffer.write_message(), or dumped to a
byte array for transmission using MessageBuffer.to_bytes(). The message must be reset
before starting to write again.
>>> b = msg.to_bytes()
>>> msg.begin_export()
>>> msg
<MessageBuffer domain 8304 length 16 (writing)>
Reading happens more or less in reverse. To begin, a message is read from a byte array
using MessageBuffer.from_bytes(), or from a stream using MessageBuffer.read_message().
>>> msg.from_bytes(b)
>>> msg
<MessageBuffer domain 8304 length 139 (deframed 4 sets)>
Both of these methods scan the message in advance to find the sets within the message. The
records within these sets can then be accessed by iterating over the message. As with
export, the records can be accessed as a dictionary mapping IE names to values or as
tuples. The dictionary interface is designed for general IPFIX processing applications,
such as collectors accepting many types of data, or diagnostic tools for debugging IPFIX
export:
>>> for rec in msg.namedict_iterator():
... print(sorted(rec.items()))
...
[('destinationIPv4Address', IPv4Address('10.5.6.7')), ('flowStartMilliseconds', datetime.datetime(2013, 6, 21, 14, 0)), ('packetDeltaCount', 27), ('sourceIPv4Address', IPv4Address('10.1.2.3'))]
[('destinationIPv4Address', IPv4Address('10.12.13.14')), ('flowStartMilliseconds', datetime.datetime(2013, 6, 21, 14, 0, 2)), ('packetDeltaCount', 33), ('sourceIPv4Address', IPv4Address('10.8.9.11'))]
[('flowStartMilliseconds', datetime.datetime(2013, 6, 21, 14, 0, 4)), ('myNewInformationElement', "Grüezi, Y'all")]
The tuple interface for reading messages is designed for applications with a specific
internal data model. It can be much faster than the dictionary interface, as it skips
decoding of IEs not requested by the caller, and can skip entire sets not containing all
the requested IEs. Requested IEs are specified as an ipfix.ie.InformationElementList
instance, from ie.spec_list():
>>> ielist = ipfix.ie.spec_list(["flowStartMilliseconds", "packetDeltaCount"])
>>> for rec in msg.tuple_iterator(ielist):
... print(rec)
...
(datetime.datetime(2013, 6, 21, 14, 0), 27)
(datetime.datetime(2013, 6, 21, 14, 0, 2), 33)
Notice that the variable-length record written to the message are not returned by this
iterator, since that record doesn't include a packetDeltaCount IE. The record is,
however, still there:
>>> ielist = ipfix.ie.spec_list(["myNewInformationElement"])
>>> for rec in msg.tuple_iterator(ielist):
... print(rec)
...
("Grüezi, Y'all",)
exception ipfix.message.EndOfMessage(*args)
Exception raised when a write operation on a Message fails because there is not
enough space in the message.
class ipfix.message.MessageBuffer
Implements a buffer for reading or writing IPFIX messages.
active_template_ids()
Get an iterator over all active template IDs in the current domain.
Provided to allow callers to export some or all active Templates across
multiple Messages.
Returns
a template ID iterator
add_template(tmpl, export=True)
Add a template to this MessageBuffer. Adding a template makes it available
for use for exporting records; see export_new_set().
Parameters
• tmpl -- the template to add
• export -- If True, export this template to the MessageBuffer after
adding it.
Raises EndOfMessage
begin_export(odid=None)
Start exporting a new message. Clears any previous message content, but
keeps template information intact. Sets the message sequence number.
Parameters
odid -- Observation domain ID to use for export. By default, uses the
observation domain ID of the previous message. Note that templates
are scoped to observation domain, so templates will need to be added
after switching to a new observation domain ID.
Raises IpfixEncodeError
delete_template(tid, export=True)
Delete a template by ID from this MessageBuffer.
Parameters
• tid -- ID of the template to delete
• export -- if True, export a Template Withdrawal for this Template
after deleting it
Raises EndOfMessage
export_ensure_set(setid)
Ensure that the current set for export has the given Set ID. Starts a new
set if not using export_new_set()
Parameters
setid -- Set ID of the new Set; corresponds to the Template ID of the
Template that will be used to encode records into the Set. The
require Template must have already been added to the MessageBuffer,
see add_template().
Raises IpfixEncodeError, EndOfMessage
export_namedict(rec)
Export a record to the message, using the template for the current Set ID.
The record is a dictionary mapping IE names to values. The dictionary must
contain a value for each IE in the template. Keys in the dictionary not in
the template will be ignored.
Parameters
rec -- the record to export, as a dictionary
Raises EndOfMessage
export_needs_flush()
True if content has been written to this MessageBuffer since the last call
to begin_export()
export_new_set(setid)
Start exporting a new Set with the given set ID. Creates a new set even if
the current Set has the given set ID; client code should in most cases use
export_ensure_set() instead.
Parameters
setid -- Set ID of the new Set; corresponds to the Template ID of the
Template that will be used to encode records into the Set. The
require Template must have already been added to the MessageBuffer,
see add_template().
Raises IpfixEncodeError, EndOfMessage
export_record(rec, encode_fn=<function Template.encode_namedict_to>, recinf=None)
Low-level interface to record export.
Export a record to a MessageBuffer, using the template associated with the
Set ID given to the most recent export_new_set() or export_ensure_set()
call, and the given encode function. By default, the record is assumed to be
a dictionary mapping IE names to values (i.e., the same as
export_namedict()).
Parameters
• encode_fn -- Function used to encode a record; must be an (unbound)
"encode" instance method of the ipfix.template.Template class.
• recinf -- Record information opaquely passed to decode function
Raises EndOfMessage
export_template(tid)
Export a template to this Message given its template ID.
Parameters
tid -- ID of template to export; must have been added to this message
previously with add_template().
Raises EndOfMessage, KeyError
export_tuple(rec)
Export a record to the message, using the template for the current Set ID.
The record is a tuple of values in template order.
Parameters
rec -- the record to export, as a tuple in template order.
Raises EndOfMessage
from_bytes(bytes)
Read an IPFIX message from a byte array.
This populates message header fields and the internal setlist. Call for
each new message before iterating over records when reading from a byte
array.
Parameters
bytes -- a byte array containing a complete IPFIX message.
Raises IpfixDecodeError
get_export_time()
Return the export time of this message. When reading, returns the export
time as read from the message header. When writing, this is the argument of
the last call to set_export_time(), or, if :attr:auto_export_time is True,
the time of the last message export.
Returns
export time of the last message read/written.
namedict_iterator()
Iterate over all records in the Message, as dicts mapping IE names to
values.
Returns
a name dictionary iterator
read_message(stream)
Read a IPFIX message from a stream.
This populates message header fields and the internal setlist. Call for
each new message before iterating over records when reading from a stream.
Parameters
stream -- stream to read from
Raises IpfixDecodeError
record_iterator(decode_fn=<function Template.decode_namedict_from>,
tmplaccept_fn=<function accept_all_templates>, recinf=None)
Low-level interface to record iteration.
Iterate over records in an IPFIX message previously read with read_message()
or from_bytes(). Automatically handles templates in set order. By default,
iterates over each record in the stream as a dictionary mapping IE name to
value (i.e., the same as namedict_iterator())
Parameters
• decode_fn -- Function used to decode a record; must be an (unbound)
"decode" instance method of the ipfix.template.Template class.
• tmplaccept_fn -- Function returning True if the given template is
of interest to the caller, False if not. Default accepts all
templates. Sets described by templates for which this function
returns False will be skipped.
• recinf -- Record information opaquely passed to decode function
Returns
an iterator over records decoded by decode_fn.
set_export_time(dt=None)
Set the export time for the next message written with write_message() or
to_bytes(). Disables automatic export time updates. By default, sets the
export time to the current time.
Parameters
dt -- export time to set, as a datetime
template_for_id(tid)
Retrieve a Template for a given ID in the current domain.
Parameters
tid -- template ID to get
Returns
the template
Raises KeyError
to_bytes()
Convert this MessageBuffer to a byte array, suitable for writing to a binary
file, socket, or datagram. Finalizes the message by rewriting the message
header with current length, and export time.
Returns
message as a byte array
tuple_iterator(ielist)
Iterate over all records in the Message containing all the IEs in the given
ielist. Records are returned as tuples in ielist order.
Parameters
ielist -- an instance of ipfix.ie.InformationElementList listing IEs
to return as a tuple
Returns
a tuple iterator for tuples as in ielist order
write_message(stream)
Convenience method to write a message to a stream; see to_bytes().
MODULE IPFIX.READER
Interface to read IPFIX Messages from a stream.
class ipfix.reader.MessageStreamReader(stream)
Reads records from a stream of IPFIX messages.
Uses an ipfix.message.MessageBuffer internally, and continually reads messages from
the given stream into the buffer, iterating over records, until the end of the
stream. Use from_stream() to get an instance.
Suitable for reading from IPFIX files (see RFC 5655) as well as from UDP or TCP
sockets with socketserver.StreamRequestHandler. When opening a stream from a file,
use mode='rb'.
namedict_iterator()
Iterate over all records in the stream, as dicts mapping IE names to values.
Returns
a name dictionary iterator
tuple_iterator(ielist)
Iterate over all records in the stream containing all the IEs in the given
ielist. Records are returned as tuples in ielist order.
Parameters
ielist -- an instance of ipfix.ie.InformationElementList listing IEs
to return as a tuple
Returns
a tuple iterator for tuples in ielist order
ipfix.reader.from_stream(stream)
Get a MessageStreamReader for a given stream
Parameters
stream -- stream to read
Returns
a MessageStreamReader wrapped around the stream.
MODULE IPFIX.WRITER
class ipfix.writer.MessageStreamWriter(stream, mtu=65535)
Writes records to a stream of IPFIX messages.
Uses an ipfix.message.MessageBuffer internally, and continually writes records into
messages, exporting messages to the stream each time the maximum message size (MTU)
is reached. Use to_stream() to get an instance.
Suitable for writing to IPFIX files (see RFC 5655) as well as to TCP sockets. When
writing a stream to a file, use mode='wb'.
..warning: This class is not yet suitable for UDP export; this is an open
issue to be fixed in a subsequent release.
add_template(tmpl)
Add a template to this Writer. Adding a template makes it available for use
for exporting records; see set_export_template().
Parameters
tmpl -- the template to add
export_namedict(rec)
Export a record to the message, using the current template The record is a
dictionary mapping IE names to values. The dictionary must contain a value
for each IE in the template. Keys in the dictionary not in the template will
be ignored.
Parameters
rec -- the record to export, as a dictionary
flush()
Export an in-progress Message immediately.
Used internally to manage message boundaries, but can also be used to force
immediate export (e.g. to reduce delay due to buffer dwell time), as well as
to finish write operations on a Writer before closing the underlying stream.
set_domain(odid)
Sets the observation domain for subsequent messages sent with this Writer.
Parameters
odid -- Observation domain ID to use for export. Note that templates
are scoped to observation domain, so templates will need to be added
after switching to a new observation domain ID.
set_export_template(tid)
Set the template to be used for export by subsequent calls to
export_namedict() and export_tuple().
Parameters
tid -- Template ID of the Template that will be used to encode
records to the Writer. The corresponding Template must have already
been added to the Writer, see add_template().
ipfix.writer.to_stream(stream, mtu=65535)
Get a MessageStreamWriter for a given stream
Parameters
• stream -- stream to write
• mtu -- maximum message size in bytes; defaults to 65535, the largest
possible ipfix message.
Returns
a MessageStreamWriter wrapped around the stream.
• genindex
• modindex
• search
AUTHOR
Brian Trammell
COPYRIGHT
2013-2018, Brian Trammell