'\" et .TH BGPGREP 1 @VERSION@ BGPGREP "User Commands" .\" .SH NAME @UTILITY@ \(em filter and print BGP data within MRT dumps .SH SYNOPSIS .LP .nf @UTILITY@ \fB[\fIOPTIONS\fB]\fR... \fB[\fIFILES\fB]\fR... \fB[\fIEXPRESSION\fB] .fi .SH DESCRIPTION The .IR @UTILITY@ utility reads each possibly compressed Multithreaded Routing Toolkit (MRT) dump file specified by .IR FILES and formats its contents to standard output (or any custom output file as specified by .IR OPTIONS ). .IR @UTILITY@ may optionally evaluate a predicate defined by .IR EXPRESSION over every MRT record containing a BGP message. Whenever such predicate evaluates as false the relevant BGP message is discarded from output (see the .IR EXAMPLES section below). .P .IR EXPRESSION predicates only affect BGP messages output, other kind of information, such as state changes, is always printed by .IR @UTILITY@ regardless of any filtering rule. .P .IR @UTILITY@ prints diagnostics to standard error, it detects and tolerates data corruption as much as possible. Corruption within a BGP message causes only the affected message to be dropped. Though unrecoverable errors affecting the entire MRT dump file may require it to be dropped as a whole, .IR @UTILITY@ will then move to the next file in .IR FILES , if any. .P Such events are always reported with reasonable diagnostic errors. Parsed data up to the corruption point may still be printed to regular output. .SH OPTIONS .IR @UTILITY@ expects its options before the .IR FILES list. This is due to the fact that .IR @UTILITY@ must distinguish between options and its expression predicate (see the .IR OPERANDS section below, for details on how .IR @UTILITY@ makes such distinction). .P The following options are supported: .IP "\fB\-\-dump\-bytecode\fP" 10 Debug option, causes .IR @UTILITY@ to dump its filtering engine bytecode to standard error before starting MRT dump files processing. .IP "\fB\-\-no\-color\fP" 10 .IR @UTILITY@ may ease visualization by surrounding some output with color escape sequences, on terminals that support this feature. This option forces colored text output off. .IP "\fB\-o \fI\fP" 10 Write output to .BR file . Instead of using standard output, .IR @UTILITY@ shall format MRT contents to the specified file. If option occurs multiple times, last specified file is used. This option forces colored text output off. .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 OPERANDS .IR @UTILITY@ interprets all its operands up to but not including the first operand that starts with a `\-' , or is a `(' or a `!', as the .IR FILES operand. Each of these operands are pathnames to a MRT dump file to be processed. An actual `\-' is a placemarker to read uncompressed MRT data from standard input at that point during processing (see .IR STDIN section below). .P The first operand that starts with a `\-' , or is a `(' or a `!', and any subsequent arguments, are interpreted as an .IR EXPRESSION predicate. Legal predicates are composed of the following terms: .IP "\fB\-type\ \fImsg\-type\fR" 10 Evaluates as true if the BGP message type matches .IR `msg\-type' . Message types may be provided by a human readable type name, as defined by .IR "RFC 4271" ", " "Section 4" (e.g. OPEN, UPDATE), or any other relevant RFC defining the message type (e.g. ROUTE_REFRESH). An explicit numeric code may also be provided (e.g. 1 as an equivalent to OPEN). .IP "\fB\-attr\ \fIattribute\-type\fR" 10 Evaluates as true if the BGP message is an UPDATE containing a path attribute of type .IR `attribute\-type' . The attribute type may be specified by a human readable name, as defined by .IR "RFC 4271" ", " "Section 5.1" (e.g. AS_PATH, ATOMIC_AGGREGATE), or any other relevant RFCs defining the interesting path attribute (e.g. COMMUNITY). An explicit numeric code may also be provided (e.g. 8 as an equivalent to COMMUNITY), which is especially useful to specify non-standard path attributes. .IP "\fB\-aspath\ \fIpattern\fR" 10 Evaluates as true if the BGP message is an UPDATE with an AS_PATH that matches the regular expression specified by .IR `pattern' . See the .IR "AS_PATH REGULAR EXPRESSIONS" section below for details. .IP "\fB\-peer\ \fIpeer\-expression\fR" 10 Evaluates as true if .IR `peer\-expression' matches the peer that provided the BGP data. This term matches the PEER field as displayed by the .IR "LINE ORIENTED OUTPUT" format (see section below for details). Supported peer matching expressions are documented in the .IR "PEER MATCHING EXPRESSIONS" section below. .IP "\fB\-loops\fR" 10 Evaluates as true if BGP message is an UPDATE whose AS_PATH contains loops. .IP "\fB\-bogon\-asn\fR" 10 Evaluates as true if BGP message is an UPDATE whose AS_PATH contains bogon ASN. Any of the following is classified as a bogon ASN: .RS .IP "\fI0\fR" 25 Reserved by .IR "RFC 7607" . .IP "\fI23456\fR" 25 .IR AS_TRANS , see .IR "RFC 6793" . .IP "\fI64496\-64511\fR" 25 Reserved for use in docs and code by .IR "RFC 5398" . .IP "\fI64512\-65534\fR" 25 Reserved for private use by .IR "RFC 6996" . .IP "\fI65535\fR" 25 Reserved by .IR "RFC 7300" . .IP "\fI65536\-65551\fR" 25 Reserved for use in docs and code by .IR "RFC 5398" . .IP "\fI65552\-131071\fR" 25 Reserved by IANA. .IP "\fI4200000000\-4294967294\fR" 25 Reserved for private use by .IR "RFC 6996" . .IP "\fI4294967295\fR" 25 Reserved by .IR "RFC 7300" . .RE .IP "\fB\-exact\ \fIprefix\-expression\fR" 10 Evaluates as true if BGP message is an UPDATE and contains at least one of the relevant networks of interest specified in .IR `prefix\-expression' . See .IR "PREFIX MATCHING EXPRESSIONS" section for details. .IP "\fB\-supernet\ \fIprefix\-expression\fR" 10 Similar to .BR \-exact , but evaluates as true if BGP message contains supernets of the relevant networks of interest, or the actual networks themselves. .IP "\fB\-subnet\ \fIprefix\-expression\fR" 10 Similar to .BR \-exact, but evaluates as true if BGP message contains subnets of the relevant networks of interest. .IP "\fB\-related\ \fIprefix\-expression\fR" 10 Similar to .BR \-exact but evaluates as true if BGP message contains prefixes related to the relevant networks of interest. A related network is defined to be either a subnet or a supernet of the specified prefix. .IP "\fB\-timestamp\ \fItime\-expression\fP" 10 Evaluates as true if the timestamp at which the BGP data was originated or collected matches the specified .IR 'time\-expression' . Accepted expressions are described in the .IR "TIMESTAMP MATCHING EXPRESSIONS" section. .IP "\fB\-communities\ \fIcommunities\-expression\fP" 10 Evaluates as true if BGP message is an UPDATE whose path attributes contains at least one community specified within .IR 'communities\-expression' , see the .IR "COMMUNITY MATCHING EXPRESSIONS" section below for details. .IP "\fB\-all\-communities\ \fIcommunities\-expression\fP" 10 Similar to .BR \-communities , but requires all communities inside .IR `communities\-expression' to be present inside UPDATE message path attributes. .P Terms can be combined with the following operators (in order of decreasing precedence): .IP "(\ \fIexpression\fR\ )" 10 Evaluates as true if expression is true, may be used to explicitly control precedence. .IP "\fB!\ \fIexpression\fR\ or\ \fB-not\ \fIexpression\fR" 10 Negation of expression; the unary NOT operator. .IP "\fIexpression\ \fB[\-a]\ \fIexpression\fR\ or\ \fIexpression \fB[\-and]\ \fIexpression\fR" 10 Conjunction of expressions; the AND operator is implicit if no other operator is provided inbetween two consecutive expressions, but can be made explicit by explicitly inserting the .BR \-a or .BR \-and operators. The second expression is not evaluated if the first one is false. .IP "\fIexpression\ \fB\-o\ \fIexpression\fR\ or\ \fIexpression\ \fB\-or\ \fIexpression\fR" 10 Alternation of expressions; the OR operator. The second expression is not evaluated if the first one is true. .SH "AS_PATH REGULAR EXPRESSIONS" .IR @UTILITY@ uses a specialized regular expression (regexp) style pattern matching approach for AS_PATH. .P AS_PATH regular expressions support most features found in string pattern matching, except backreferences, classes and counted repetition. .P ASN are specified by a numeric value, for example 19819 represents AS19819. In their simplest form, AS_PATH expressions match an ASN sequence against the merged BGP data AS_PATH (as specified by .IR "RFC 4893" ), indipendently by its starting position. In the same way a regexp would match a string of characters. For example `19819 172' matches AS_PATH `AS121 .BR AS19819 .BR AS172 AS1111'. .P The following features, commonly found in regular expressions, are supported by .IR @UTILITY@ : .IP "\fIComplements" 10 The prefix `!' operator can be used to match any but the specified ASN, for example `!871' matches any ASN but AS871. .IP "\fIAnchors" 10 `^' and `$' assume a special meaning, they match with the beginning and the end, respectively, of the AS_PATH. This allows to assert a particular position within the AS_PATH at which an ASN sequence is supposed to appear. .IP "\fIGrouping and alternation" 10 Groups can be defined inside regexp by enclosing them inside parentheses, for example `( 202 397 )' defines a group with the single ASN sequence `AS202 AS397'. The alternation operator `|' provides additional flexibility, allowing multiple sequences inside groups, like `( 202 397 | 1111 5439 )', which would match both `AS1921 .BR AS202 .BR AS397 ' and `AS2431 .BR AS1111 .BR AS5439 AS79'. Alternation can be used even outside groups and alternatives may very well be more than two. Groups may be nested. .IP "\fIMetacharacters" 10 The `.' metacharacter can be used to match any ASN in its position. The metacharacters `*', `?' and `+' are repetition operators, they can be used to match the preceding ASN or group multiple times in different ways. `191*' matches AS191 zero or more times, `191?' matches AS191 zero or one time, while `191+' matches AS191 one or more times. .P These features may be combined at will to provide powerful expressions, for example `^ !432' matches any AS_PATH that does not start with AS432. .P Extensive usage examples can be found in the .IR EXAMPLES section. .SH "PEER MATCHING EXPRESSIONS" Peer matching expressions specify a set of relevant peers, either by providing their IP address, their ASN, or both. The constructed set is then matched against the peer providing the BGP data inside the MRT input files. .P Allowed constructs are: .IP "\fIpeer\-asn\fR" 10 Only peer ASN is matched for equality. .IP "\fIpeer\-address\fR" 10 Only peer IP address is matched for equality. .IP "\(dq\fIpeer\-address\ \fIpeer\-asn\fR\(dq" Both peer IP address and ASN are tested for equality. .P When both IP address and ASN are provided, the match should be quoted so that it is understood to be a single match as opposed to one match by peer address followed by another match by peer ASN. .P Multiple peer matches can be provided at the same time by enclosing them in parentheses, for example `( \(aq199036\(aq \(aq173.2.2.1 7566\(aq )' matches both peer AS199036 and peer AS7566 with IP address 173.2.2.1. .P Whenever a peer matching expression is expected, a filepath to a text file may be specified in its place. In this case .IR @UTILITY@ will read the peer matches directly from file. Matches inside file may be separated by either spaces or newlines. No parentheses are necessary, though quoting may still be necessary for matches specifying both peer address and ASN. Typical C and C++ style comments are supported within the file. .P See the .IR EXAMPLES section for usage examples. .SH "COMMUNITY MATCHING EXPRESSIONS" COMMUNITY matching expressions define a set of interesting communities. Communities may be specified in any of the following ways: .IP \[bu] A well-known COMMUNITY name (e.g. BLACKHOLE for COMMUNITY 0xFFFF029A). .IP \[bu] A hexadecimal numeric COMMUNITY code (e.g. 0xFFFFFF01 for NO_EXPORT). .IP \[bu] The canonical representation of a COMMUNITY as two fields separated by `:', such as `65535:65282' for NO_ADVERTISE. In this form either one of the two field, but not both, may be left unspecified by marking it with `*'. In this case, communities will be matched only against the specified portion. For example `65535:*' matches any COMMUNITY whose first two octets match 65535. .P Multiple communities may be listed by enclosing them in parentheses, for example `( \(aq65535:*\(aq \(aq0:*\(aq )' matches any reserved COMMUNITY as per .IR "RFC 1997" . .P Whenever a community matching expression is expected, a filepath to a text file may be provided in its place. In this case .IR @UTILITY@ will parse the communities from the file itself. Each COMMUNITY inside file may be separated by either spaces or newlines. No parentheses are required. Typical C and C++ style comments are supported within the file. .P See the .IR EXAMPLES section for usage examples. .SH "PREFIX MATCHING EXPRESSIONS" Prefix matching expressions define a set of interesting networks. Networks are specified as prefixes in their CIDR notation, for example 193.0.0.0/16 or 2001:67c::/32. If prefix length is not defined explicitly, it is taken to be the full IP address length, that is 32 for IPv4 addresses and 64 for IPv6 addresses. .P Prefix matching can be restricted to announcements or withdrawals. Syntax is: .IP "\fB+\fIprefix\fR" 10 Restrict matching to announcements only. .IP "\fB-\fIprefix\fR" 10 Restrict matching to withdrawals only. .P If none of `+' or `-' is prepended, then matching takes place on both announcements and withdrawals. .P Multiple prefixes can be specified at the same time by enclosing them in parentheses, for example: `( \(aq+193.0.0.0/16\(aq \(aq2001:67c::/32\(aq )'. .P Whenever a prefix matching expression is expected, a filepath to a text file may be specified in its place. In this case .IR @UTILITY@ will parse the relevant prefixes from the file itself. Inside file, prefixes may be separated by either spaces or newlines. No parentheses are required. Typical C and C++ style comments are supported within the file. .P See the .IR EXAMPLES section for usage examples. .SH "TIMESTAMP MATCHING EXPRESSIONS" Timestamp matching expressions define a time point and a matching direction. Expressions are matched either to the MRT header timestamp, in case of BGP4MP and ZEBRA records (commonly referred to as updates), or to the ORIGINATED field in case of TABLE_DUMPV2 or TABLE_DUMP snapshots (commonly referred to as RIB snapshots). Timestamps may be specified in either of the two following formats: .IP \[bu] A .IR "Unix timestamp" in its explicit numeric representation, such as `1622725323', which is equivalent to `2021\-06\-03 13:02:03 GMT'. Microsecond resolution may be added appending a followed by the subsecond part, such as `1622725323.000030'. .IP \[bu] A human readable .IR "RFC 3339" UTC timestamp. This format is commonly found in JSON. For example `1985\-04\-12T23:20:50.52Z' . .P Matching direction may be any of the following: .IP "\fB>=\fItimestamp\fR" 10 Matches if BGP data was originated after or exactly at the relevant timestamp. .IP "\fB>\fItimestamp\fR" 10 Matches if BGP data was originated after the relevant timestamp. .IP "\fB=\fItimestamp\fR" 10 Matches if BGP data was originated exactly at the relevant timestamp. .IP "\fB<\fItimestamp\fR" 10 Matches if BGP data was originated before the relevant timestamp. .IP "\fB<=\fItimestamp\fR" 10 Matches if BGP data was originated before or exactly at the relevant timestamp. .P If no matching direction is provided, `=' is implicitly assumed. See the .IR EXAMPLES section for usage examples. .SH "LINE ORIENTED OUTPUT" .IR @UTILITY@ prints each MRT record into multiple lines, each one representing either .BR "ROUTE INFORMATION" or .BR "BGP SESSION STATUS" . .P .BR "ROUTE INFORMATION" can be either an announcement, a route withdrawn or a routing table (RIB) snapshot. Each .BR "ROUTE INFORMATION" line is a sequence of the following `|' separated fields: .RS 4 .sp .RS 4 .nf TYPE|PREFIXES|PATH ATTRIBUTES|PEER|TIMESTAMP|ASN32BIT .fi .P .RE .P Fields have the following meaning: .IP "\fBTYPE\fR" 4 Single character describing the route information type, may be `=' (RIB snapshot entry), `+' (announcement), or `-' (withdrawn). .IP "\fBPREFIXES\fR" 4 The list of prefixes carried into the message. If the information is an announcement, then this enumerates the prefixes within NLRI and MP_REACH_NLRI fields. If the information is a withdrawn, then this enumerates the prefixes within WITHDRAWN_ROUTES and MP_UNREACH_NLRI fields. If the information is a RIB snapshot entry, then this is the prefix related to the current RIB entry. Multiple prefixes are separated by a single space. .IP "\fBPATH ATTRIBUTES\fR" 4 This is a `|' separated list of the most common BGP path attributes characterizing a route. Each field is left empty if the corresponding path attribute is not present in the collected BGP data (e.g. route announcements without optional attributes, or route withdrawals). The currently displayed path attributes are: .RS 4 .sp .RS 4 .nf AS_PATH|NEXT_HOP|ORIGIN|ATOMIC_AGGREGATE|AGGREGATOR|COMMUNITIES .fi .P .RE .P If the BGP peer does not support ASN32BIT capability, then the AS_PATH field contains the result of the merging procedure between AS_PATH and AS4_PATH attributes, according to .IR "RFC 4893" , and the AGGREGATOR field contains the AS4_AGGREGATOR attribute (if present). Otherwise, AS_PATH and AGGREGATOR fields contain the respective attribute. .P NEXT_HOP field contains either the NEXT_HOP attribute (IPv4) or the next hop address(es) listed into the MP_REACH_NLRI attribute (IPv6), as described in .IR "RFC 4760" . .P ORIGIN contains the corresponding attribute encoded as a single character, `i' (IGP), `e' (EGP), `?' (INCOMPLETE). .P ATOMIC_AGGREGATE field contains .BR "AT" if the attribute is set, it is left empty otherwise. .P COMMUNITIES field contains both COMMUNITY ( .IR "RFC 1997" ) and LARGE_COMMUNITY ( .IR "RFC 8092" ) displayed in their canonical representation. Well\-known communities are displayed according to their IANA assigned names (e.g. NO_EXPORT instead of `65535:65281'). .P .RE .IP "\fBPEER\fP" 4 The BGP peer that provided the BGP message. If the peer uses the ADD\-PATH extension ( .IR "RFC 7911" ) to announce BGP data, then it is displayed as `peer\-address peer\-asn path\-id', otherwise as `peer\-address peer\-asn'. .IP "\fBTIMESTAMP\fP" 4 Displays the Unix epoch time at which the information was collected. If extended timestamp information is available, the Unix Epoch time is followed by a `.' and the microsecond precision is appended right after it. Timestamp is displayed as a raw numerical value. .IP "\fBASN32BIT\fP" 4 May be either 1, if BGP data has ASN32BIT capability, or 0. .P .RE The .BR "BGP SESSION STATUS" is encoded as a BGP session state change according to .IR "RFC 6936" ", " "Section 4.4.1" . The format of a line representing a state change is the following: .RS 4 .sp .RS 4 .nf #|OLD_STATE-NEW_STATE|||||||PEER|TIMESTAMP|ASN32BIT .fi .P .RE .P Each field has the following format: .IP "\fBOLD_STATE\-NEW_STATE\fP" 4 Represents the old and new state of the BGP session respectively, according to the BGP Finite State Machine states numerical codes. .IP "\fBPEER, TIMESTAMP, ASN32BIT\fP" 4 Have identical format and meaning with regards to the .BR "ROUTING INFORMATION" case. .P .RE Each line produced always has the same `|' character count, in both .BR "ROUTING INFORMATION" 's and .BR "BGP SESSION STATUS" 's case. This facilitates the task of writing simple scripts that manipulate .IR @UTILITY@ 's output text. .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 . .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 BGP message data, 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. Any BGP message output is exclusive to standard output or any file explicitly specified by .IR OPTIONS . .SH EXAMPLES This section contains some useful examples, starting from trivial ones, demonstrating basic .IR @UTILITY@ usage, to more complex ones employing sophisticated filtering predicates. Examples in this section use paranoid quoting, since this a worthwhile habit that eliminates potential pitfalls introduced by shell expansion. .IP \[bu] The following is the simplest way to invoke .IR @UTILITY@ : .nf \& .in +2m @UTILITY@ .in \& .fi It formats and prints all the BGP data it inside the uncompressed MRT input data it receives from standard input. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ -- -peer \(aq199036\(aq .in \& .fi finds all BGP data announced by peer AS199036, taking MRT input data implicitly from standard input. Notice how an explicit `\-\-' is necessary for .IR @UTILITY@ to interpret .BR \-peer as an actual .IR EXPRESSION operand, rather than incorrectly mistaking it for .IR OPTIONS. .IP \[bu] The following is equivalent to the previous example: .nf \& .in +2m @UTILITY@ ./rib.1.bz2 -peer \(aq199036\(aq .in \& .fi but takes MRT input data from a .IR bzip (1), compressed file. The file argument removes the necessity of an explicit `\-\-' to separate .IR FILES and .IR EXPRESSION operands. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./updates.*.gz -aspath \(aq^199036\(aq .in \& .fi finds every message whose first ASN in AS_PATH is AS199036, inside all .IR gzip (1) compressed files resulting from the glob expansion. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./updates.*.gz -aspath \(aq3333$\(aq .in \& .fi is similar to the previous example, but uses .IR "AS_PATH REGULAR EXPRESSIONS" to find every BGP message whose last ASN in AS_PATH is AS3333. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./updates.*.gz -aspath \(aq174 3356\(aq .in \& .fi demonstrates yet another basic use of .IR "AS_PATH REGULAR EXPRESSIONS" to find every BGP message whose AS_PATH crosses link AS174 AS3356. Notice how the argument of .BR \-aspath needs quoting. .IP \[bu] The following command demonstrates a more advanced use of .IR "AS_PATH REGULAR EXPRESSIONS": .nf \& .in +2m @UTILITY@ ./updates.*.gz -aspath \(aq174 (2603+|202+|303+) 3356\(aq .in \& .fi It finds every BGP message whose AS_PATH crosses AS174 and AS3356, through one intermediate ASN among AS2603, AS202, or AS303. It also takes care of possible prepending for the inbetween ASN. .IP \[bu] The following commands are equivalent: .nf \& .in +2m @UTILITY@ ./updates.*.gz -aspath \(aq^7854 .* 5032$\(aq -or -aspath \(aq109 .* 9081$\(aq @UTILITY@ ./updates.*.gz -aspath \(aq^7854 .* 5032$ | ^109 .* 9081$\(aq .in \& .fi They both find every BGP message whose AS_PATH starts at AS7854 and terminates at AS5032, or starts at AS109 and terminates at AS9081. The second being the most efficient. This example illustrates the use of alternation inside .IR "AS_PATH REGULAR EXPRESSIONS" to test multiple patterns at the same time. .IP \[bu] The following example: .nf \& .in +2m @UTILITY@ ./rib.*.xz -subnet \(aq192.65.0.0/16\(aq -aspath \(aq174 137\(aq .in \& .fi finds all subnets of 192.65.0.0/16 crossing link AS174 AS137. It combines two .IR EXPRESSION terms with an implicit AND operator, since no explicit .BR \-and and no .BR \-or was provided, as detailed by the .IR OPERANDS section. .IP \[bu] The following commands are equivalent: .nf \& .in +2m @UTILITY@ ./rib.*.gz \e( -subnet \(aq193.0.0.0/16\(aq -or -subnet \(aq2001:67c::/32\(aq \e) -aspath \(aq3333$\(aq @UTILITY@ ./rib.*.gz -subnet \e( \(aq193.0.0.0/16\(aq \(aq2001:67c::/32\(aq \e) -aspath \(aq3333$\(aq .in \& .fi They both print every message containing subnets of 193.0.0.0/16 or 2001:67c::/32 destinated to AS3333, the second being a more efficient alternative. In the latter, notice the use of `(' and `)' inside .BR \-subnet to provide multiple arguments. This behavior is further explained in the .IR "PREFIX MATCHING EXPRESSIONS" section, and is common to most matching expressions provided by .IR @UTILITY@ . .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./rib.*.bz2 -peer \(aq202\(aq -timestamp \(aq>=2012-10-01\(aq -timestamp \(aq<2012-11-01\(aq -loops .in \& .fi is another example combining multiple .IR EXPRESSION terms to achieve complex filtering. It scans all .IR bzip2 (1) compressed MRT input files resulting from glob expansion, and prints every BGP message provided by peer AS202 during the month of October, 2012 containing loops in its AS_PATH. Notice how multiple .BR \-timestamp terms can be combined to effectively define bounded time ranges. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./rib.*.bz2 -communities \e( \(aq0:*\(aq \(aq65535:*\(aq \e) -peer \(aq185.169.236.135 201\(aq .in \& .fi prints all the BGP messages containing reserved communities, provided by peer AS201 with IP address 185.169.236.135. .IP \[bu] The following command: .nf \& .in +2m @UTILITY@ ./rib.*.bz2 -all-communities ./commlist.tpl -subnet ./netlist.tpl .in \& .fi demonstrates the use of filepath arguments for .BR \-all\-communities and .BR \-subnet .IR EXPRESSION terms. .IR bgpgrep will parse the two text files and use their contents as arguments. This is especially useful to create templates containing relevant networks, communities, or peers and reuse them across various runs. .SH "APPLICATION USAGE" The .IR @UTILITY@ utility and its filtering engine have been designed for performance. Providing predicates has the double role of cleaning the output of irrelevant data, without resorting to complex scripting, and avoid wasting time to decode useless data. Therefore .IR @UTILITY@ can gain a lot performance\-wise when provided with restrictive predicates, that cut away significant amounts of BGP data from its input files. .P .IR @UTILITY@ deliberately mimics the .IR find (1) utility operands convention, in an attempt to feel familiar to the experienced shell user and provide a powerful .IR EXPRESSION syntax that feels both expressive and readable. Though, many of .IR find (1)'s subtleties also apply to .IR bgpgrep . When writing .IR EXPRESSION , it should be noted that `!', `(', `<' and `>' have special meaning to the shell, and should be quoted accordingly. .IR @UTILITY@ provides the alternative .BR \-not syntax for the unary NOT .BR ! operator that avoids the problem. Still, care should be used with other .IR EXPRESSION terms arguments. When in doubt use explicit quotes, as demonstrated in the .IR EXAMPLES section. .P .IR @UTILITY@ attempts to provide descriptive output for syntax errors that should help with most of these problems. .P Another common source of errors is the distinction between .IR FILES and .IR EXPRESSION . .IR bgpgrep treats any operand starting with `\-' and followed by at least one character as the beginning of an .IR EXPRESSION , and an actual `\-' as a placeholder for standard input (see .IR STDIN and .IR OPERANDS sections for details). In the unlikely event of having to deal with files that may generate ambiguity (e.g. a file named `\-'), make the file reference explicit by prepending `./' (e.g. `./\-' to reference a file named `\-' in the current directory). If the .IR FILES list should be left empty, but an .IR EXPRESSION should still be applied, then provide an explicit `\-\-' to mark the empty file list, as shown in the .IR EXAMPLES section. .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" .IP \[bu] 2m .IR "IANA Border Gateway Protocol (BGP) Well\-known Communities" ". Updated list of well\-known communities as of 2021\-05\-07." .SH AUTHOR .IR @UTILITY@ was written by .UR lcg@\:inventati.\:org Lorenzo Cogotti .UE . .IR @UTILITY@ is an evolution over .IR bgpscanner originally developed by the same author at the Institute of Informatics and Telematics of the Italian National Research Council (IIT\-CNR), with significant contributions by the Isolario project development team at the time.