254 lines
5.9 KiB
Groff
254 lines
5.9 KiB
Groff
'\" et
|
|
.TH PEERINDEX 1 @VERSION@ PEERINDEX "User Commands"
|
|
.\"
|
|
.SH NAME
|
|
@UTILITY@
|
|
\(em inspect MRT TABLE_DUMPV2 Peer Index Table
|
|
.SH SYNOPSIS
|
|
.LP
|
|
.nf
|
|
@UTILITY@ \fB[\fIOPTIONS\fB]\fR... \fB[\fIFILES\fB]\fR...
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
The
|
|
.IR @UTILITY@
|
|
utility reads each possibly compressed Multithreaded Routing Toolkit
|
|
(MRT)
|
|
Routing Information Base
|
|
(RIB)
|
|
file specified by
|
|
.IR FILES ,
|
|
and extracts information related to PEER INDEX TABLE
|
|
records.
|
|
.IR @UTILITY@
|
|
processes and formats such records according to the options specified by
|
|
.IR OPTIONS .
|
|
.IR @UTILITY@
|
|
prints diagnostics to standard error,
|
|
it detects and tolerates data corruption as much as possible.
|
|
If data corruption cannot be tolerated, the entire MRT dump file is dropped,
|
|
.IR @UTILITY@
|
|
will then move to the next file in
|
|
.IR FILES ,
|
|
if any.
|
|
.P
|
|
Such events are always reported with reasonable diagnostic errors.
|
|
.P
|
|
See the
|
|
.IR EXAMPLES
|
|
section below for usage examples.
|
|
|
|
.SH OPTIONS
|
|
The following options are supported:
|
|
|
|
.IP "\fB\-o \fI<file>\fP" 10
|
|
Write output to
|
|
.BR file .
|
|
Instead of using standard output,
|
|
.IR @UTILITY@
|
|
shall output PEER INDEX TABLE information to the specified file. If option
|
|
occurs multiple times, last specified file is used.
|
|
|
|
.IP "\fB\-r or \-\-only\-refs\fP" 10
|
|
By default
|
|
.IR @UTILITY@
|
|
writes all PEER INDEX TABLE entries, this option causes
|
|
.IR @UTILITY@
|
|
to only print peers that are referenced by RIB entries.
|
|
|
|
.IP "\fB\-h or \-\-help\fP" 10
|
|
Prints a short help message, summarizing
|
|
.IR @UTILITY@
|
|
functionality.
|
|
|
|
.IP "\fB\-?\fP" 10
|
|
Equivalent to
|
|
.BR \-h .
|
|
|
|
.SH "LINE ORIENTED OUTPUT"
|
|
.IR @UTILITY@
|
|
splits each PEER INDEX TABLE record into multiple lines, every line represents a peer.
|
|
Note that
|
|
.IR OPTIONS
|
|
may cause some peers inside PEER INDEX TABLES to be discarded (See the
|
|
.IR OPTIONS
|
|
section for details).
|
|
|
|
Each peer is formatted as the following `|' separated fields:
|
|
.RS 4
|
|
.nf
|
|
|
|
PEER ENTRY|ASN32BIT
|
|
.fi
|
|
.P
|
|
.RE
|
|
.P
|
|
Fields have the following meaning:
|
|
|
|
.IP "\fBPEER ENTRY\fP" 4
|
|
The peer entry inside PEER INDEX TABLE, displayed as `peer\-address peer\-asn'.
|
|
|
|
.IP "\fBASN32BIT\fP" 4
|
|
May be either 1, if the peer AS number was encoded within 32 bits, or 0 otherwise.
|
|
.P
|
|
Note that this flag being 0 does not necessarily imply that the peer does not have
|
|
ASN32BIT capability, it is merely an indicator of how the peer entry was encoded within
|
|
the PEER INDEX TABLE record (namely, it only used 2 octets to encode its ASN).
|
|
.P
|
|
.RE
|
|
|
|
Multiple PEER INDEX TABLES are concatenated within the output, meaning that
|
|
the same peer appearing in multiple PEER INDEX TABLE records may appear twice in
|
|
.IR @UTILITY@
|
|
output.
|
|
|
|
.SH "EXIT STATUS"
|
|
The following exit values are returned:
|
|
.IP "\00" 6
|
|
All input data was scanned successfully,
|
|
and data was written to output correctly.
|
|
.IP >0 6
|
|
Errors were detected in input data, write error occurred,
|
|
or an unrecoverable error occurred (such as out of memory errors).
|
|
|
|
.SH STDIN
|
|
The standard input is used only if no
|
|
.IR FILES
|
|
arguments are provided, or when any of the specified
|
|
.IR FILES
|
|
arguments is `\-' , in which case MRT data is read from standard input at that
|
|
point, up to an <end\-of\-file>.
|
|
.P
|
|
Whenever
|
|
.IR @UTILITY@
|
|
reads from standard input, MRT data is assumed to be uncompressed.
|
|
|
|
.SH "INPUT FILES"
|
|
.IR @UTILITY@
|
|
supports most MRT dump formats as written by the majority of Route Collecting
|
|
projects (see the
|
|
.IR STANDARDS
|
|
section below for additional references).
|
|
MRT dumps may be provided either in their plain uncompressed form, or
|
|
as files compressed by
|
|
.IR gzip (1),
|
|
.IR bzip2 (1),
|
|
or
|
|
.IR xz (1).
|
|
.IR @UTILITY@
|
|
performs appropriate decompression on the fly.
|
|
File extension is used, in a case insensitive way, to discriminate among
|
|
supported compression formats. If the file extension is not recognized,
|
|
or there is no extension, then it is assumed to be uncompressed.
|
|
|
|
.SH STDOUT
|
|
Unless redirected explicitly via
|
|
.IR OPTIONS ,
|
|
the standard output is used to print a human readable text representation of
|
|
PEER INDEX TABLE contents, nothing else shall be written to the standard output.
|
|
.IR @UTILITY@
|
|
may detect and treat as error whenever the standard output is a regular file,
|
|
and is the same file as any of the
|
|
.IR FILES
|
|
arguments.
|
|
The default output format used by
|
|
.IR @UTILITY@
|
|
is documented in the
|
|
.IR "LINE ORIENTED OUTPUT"
|
|
section.
|
|
|
|
.SH STDERR
|
|
The standard error is used only for diagnostic messages and error reporting.
|
|
|
|
.SH EXAMPLES
|
|
This section contains some useful examples, demonstrating basic
|
|
.IR @UTILITY@
|
|
usage.
|
|
|
|
.IP \[bu]
|
|
The following is the simplest way to invoke
|
|
.IR @UTILITY@ :
|
|
.nf
|
|
\&
|
|
.in +2m
|
|
@UTILITY@
|
|
.in
|
|
\&
|
|
.fi
|
|
It formats and prints all peers inside the uncompressed MRT
|
|
RIB input data it receives from standard input.
|
|
|
|
.IP \[bu]
|
|
The following command:
|
|
.nf
|
|
\&
|
|
.in +2m
|
|
@UTILITY@ -r
|
|
.in
|
|
\&
|
|
.fi
|
|
formats and print only peer entries referenced by at least one RIB entry
|
|
inside the uncompressed MRT RIB input data coming from standard input.
|
|
|
|
.IP \[bu]
|
|
The following is equivalent to the previous example:
|
|
.nf
|
|
\&
|
|
.in +2m
|
|
@UTILITY@ -r ./rib.1.bz2
|
|
.in
|
|
\&
|
|
.fi
|
|
but takes MRT input data from a
|
|
.IR bzip (1)
|
|
compressed file.
|
|
|
|
.IP \[bu]
|
|
The following is equivalent to the previous example:
|
|
.nf
|
|
\&
|
|
.in +2m
|
|
@UTILITY@ -r ./rib.*.gz
|
|
.in
|
|
\&
|
|
.fi
|
|
but takes MRT input data from multiple
|
|
.IR gzip (1)
|
|
compressed files resulting from the glob expansion.
|
|
Most likely the command output is going to
|
|
contain data coming from multiple PEER INDEX TABLES,
|
|
peers may appear more than once.
|
|
|
|
.IP \[bu]
|
|
The following command:
|
|
.nf
|
|
\&
|
|
.in +2m
|
|
@UTILITY@ ./rib.*.gz
|
|
.in
|
|
\&
|
|
.fi
|
|
is similar to the previous example, but does not remove
|
|
unreferenced peer entries from output.
|
|
|
|
.SH SEE ALSO
|
|
.IR awk (1),
|
|
.IR grep (1)
|
|
|
|
.SH STANDARDS
|
|
The
|
|
.IR @UTILITY@
|
|
utility conforms to:
|
|
.IP \[bu] 2m
|
|
.IR "RFC 6396" " \-" "Multi\-Threaded Routing Toolkit (MRT) Routing Information Export Format"
|
|
.IP \[bu] 2m
|
|
.IR "RFC 8050" " \- " "Multi\-Threaded Routing Toolkit (MRT) Routing Information Export Format with BGP Additional Path Extensions"
|
|
|
|
.SH AUTHOR
|
|
.IR @UTILITY@
|
|
was written by
|
|
.UR lcg@\:inventati.\:org
|
|
Lorenzo Cogotti
|
|
.UE .
|