.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "IPFIXDUMP 1" .TH IPFIXDUMP 1 "%v" "2.4.0" "libfixbuf" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ipfixDump \- Print contents of an IPFIX file as human\-readable text .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& ipfixDump [\-\-in FILE_NAME] [\-\-out FILE_NAME] \& [\-\-rfc5610] [\-\-element\-file FILE_NAME] [\-\-yaf] \& [\-\-templates] [\-\-data] [\-\-stats] \& [\-\-hexdump[=LEN]] \& \& ipfixDump [\-\-version] \& \& ipfixDump [\-\-help] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBipfixDump\fR is a tool to read an \s-1IPFIX\s0 file and print its contents as human-readable \s-1ASCII\s0 to assist the user in analyzing the file. \fBipfixDump\fR prints all message headers, templates, data records, options templates, and options records to the output, plus a one line summary of the file's content. .PP \&\fBipfixDump\fR supports \s-1IPFIX\s0 structured data in the form of basicLists, subTemplateLists, and subTemplateMultiLists. .PP By default, \fBipfixDump\fR reads the \s-1IPFIX\s0 file from the standard input and writes the text to the standard output. To specify the input or output file's location, use the \fB\-\-in\fR or \fB\-\-out\fR option, respectively. .PP \&\fBipfixDump\fR requires the input file to contain the \s-1IPFIX\s0 templates that describe the data records within the file, and the template must appear before the records that use it. Any records that do not have a corresponding template are ignored. .PP The default information model used by \fBipfixDump\fR includes only the standard information elements defined by \&\s-1IANA\s0 and provided by libfixbuf. There are three ways to augment the set of elements: .IP "1." 4 The \fB\-\-rfc5610\fR option instructs \fBipfixDump\fR to watch the input for options records that define private enterprise information elements (as defined by \&\s-1RFC5610\s0 ) and to add those elements to the information model. .IP "2." 4 The \fB\-\-element\-file=\f(BI\s-1FILE_NAME\s0\fB\fR option tells \fBipfixDump\fR to parse the contents of \fI\s-1FILE_NAME\s0\fR and add those information elements to the information model. The argument is an \s-1XML\s0 file whose schema is that used by \s-1IANA\s0's \s-1XML\s0 Information Element Registry , with the following additions: .RS 4 .IP "cert:enterpriseId" 4 .IX Item "cert:enterpriseId" A number representing the Private Enterprise Number of the element .IP "cert:reversible" 4 .IX Item "cert:reversible" A boolean value (\f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, or \f(CW1\fR for true; \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`no\*(C'\fR, or \f(CW0\fR for false) that specifies whether the element may have a separate identity in a reverse flow. .RE .RS 4 .Sp The \fB\-\-element\-file\fR option may be used multiple times to load multiple files, and the loaded elements replace existing elements with the same identifier. .RE .IP "3." 4 The \fB\-\-yaf\fR option loads the \s-1CERT\s0 private enterprise information elements into the information model. These elements are used by the NetSA tools \fB\fByaf\fB\|(1)\fR, \&\fB\fBpipeline\fB\|(8)\fR, \fB\fBsuper_mediator\fB\|(1)\fR, and \fB\fBrwsilk2ipfix\fB\|(1)\fR. This option is implemented as a wrapper over the \fB\-\-element\-file\fR option where the file name is \fIcert_ipfix.xml\fR and \fBipfixDump\fR checks several directories to attempt to find this file, stopping once it finds the first file. The list of directories, in search order, is .RS 4 .IP "\(bu" 4 the directory \fI../share/libfixbuf\fR relative to the directory containing the application .IP "\(bu" 4 the \fIlibfixbuf\fR subdirectory of the \f(CW\*(C`datadir\*(C'\fR directory specified when \&\fBipfixDump\fR was configured (defaults to \fI\f(CI$prefix\fI/share\fR) .IP "\(bu" 4 the \fIshare/libfixbuf\fR subdirectory installation folder for the GLib\-2 library .IP "\(bu" 4 the \fIlibfixbuf\fR subdirectory of the directories specified by the \&\f(CW$XDG_DATA_DIRS\fR environment variable, or \fI/usr/local/share\fR and \&\fI/usr/share/libfixbuf\fR when that variable is empty .RE .RS 4 .Sp \&\fBipfixDump\fR exits with an error if it is unable to find the \fIcert_ipfix.xml\fR file. See for additional information about this file. .RE .SH "OPTIONS" .IX Header "OPTIONS" The following options are available for \fBipfixDump\fR: .IP "\fB\-\-in\fR \fI\s-1FILE_NAME\s0\fR" 4 .IX Item "--in FILE_NAME" Sets the input file name to \fI\s-1FILE_NAME\s0\fR. When the option is not specified, \&\fBipfixDump\fR reads from the standard input or exits with an error when the standard input is a terminal. \fBipfixDump\fR reads from the standard input if \&\fI\s-1FILE_NAME\s0\fR is '\f(CW\*(C`\-\*(C'\fR'. .IP "\fB\-\-out\fR \fI\s-1FILE_NAME\s0\fR" 4 .IX Item "--out FILE_NAME" Sets the output file name to \fI\s-1FILE_NAME\s0\fR. If \fI\s-1FILE_NAME\s0\fR exists, it is overwritten. The string '\f(CW\*(C`\-\*(C'\fR' may be used to write to standard output (the default). .IP "\fB\-\-rfc5610\fR" 4 .IX Item "--rfc5610" Tells \fBipfixDump\fR to scan the \s-1IPFIX\s0 input file for options records that define private enterprise information elements and to add those elements to the information model. .IP "\fB\-\-element\-file\fR \fI\s-1FILE_NAME\s0\fR" 4 .IX Item "--element-file FILE_NAME" Loads the \s-1XML\s0 file \fI\s-1FILE_NAME\s0\fR and incorporates information element information found in it. The format of the file is described above. The option may be used multiple times to load multiple files, and later elements replace existing elements when they have the same identifier. .IP "\fB\-\-yaf\fR" 4 .IX Item "--yaf" Searches for a file named \fIcert_ipfix.xml\fR in several locations and loads that file as if it was an argument to \fB\-\-element\-file\fR. \fBipfixDump\fR exits with an error if it is unable to find the \fIcert_ipfix.xml\fR file. .IP "\fB\-\-templates\fR" 4 .IX Item "--templates" Suppresses the printing of records, causing the output to contain only message headers, templates, and a summary line. .IP "\fB\-\-data\fR" 4 .IX Item "--data" Suppresses the printing of templates, causing the output to contain only message headers, records, and a summary line. .IP "\fB\-\-stats\fR" 4 .IX Item "--stats" Suppresses the printing of all message headers, templates, and records. The output consists of the number of messages, templates, and records present in the input, and a two-column list showing template IDs found in the input and a count of the number of records that used that template. .IP "\fB\-\-hexdump\fR" 4 .IX Item "--hexdump" For data record elements whose type is octetArray, prints each octet as a 2\-digit hexadecimal value with a no separator between the values. The length of the element precedes the hexadecimal output. \fBipfixDump\fR uses this display for octetArray elements that are variable length or whose length is greater than eight. Without this option, only the length of the octetArray elements are printed. Note that fixed-width octetArray elements whose length is less than or equal to eight are always printed as a decimal number regardless of this option. .IP "\fB\-\-hexdump=\f(BI\s-1LEN\s0\fB\fR" 4 .IX Item "--hexdump=LEN" When the optional parameter \fI\s-1LEN\s0\fR is provided to \fB\-\-hexdump\fR, only the first \&\fI\s-1LEN\s0\fR octets of the value are printed. If \fI\s-1LEN\s0\fR is zero, only the length of octetArray values is printed. A \fI\s-1LEN\s0\fR that is negative or larger than 65535 is treated as the maximum, 65535. .IP "\fB\-\-version\fR" 4 .IX Item "--version" Prints version and copyright information to standard error and exits. .IP "\fB\-\-help\fR" 4 .IX Item "--help" Prints a brief usage message to the standard output and exits. .SH "Examples" .IX Header "Examples" In the following examples, the dollar sign (\*(L"$\*(R") represents the shell prompt. The text after the dollar sign represents the command line. .Sp .Vb 1 \& $ ipfixDump \-\-in \- \-\-out \- \& \& $ ipfixDump \-\-in /data/ipfix.ipfix \-\-out /data/text.txt \-\-yaf .Ve .SH "Known Issues" .IX Header "Known Issues" Bug reports may be sent directly to the Network Situational Awareness team at . .SH "AUTHORS" .IX Header "AUTHORS" Emily Sarneso and the \s-1CERT\s0 Network Situational Awareness Group Engineering Team, . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fB\fByaf\fB\|(1)\fR, \fB\fByafscii\fB\|(1)\fR, \fB\fByafdpi\fB\|(1)\fR, \fB\fBsuper_mediator\fB\|(1)\fR, \fB\fBpipeline\fB\|(8)\fR, \&\fB\fBrwsilk2ipfix\fB\|(1)\fR, ,