Annotation of embedaddon/bird/doc/bird-5.html, revision 1.1.1.1

1.1       misho       1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
                      2: <HTML>
                      3: <HEAD>
                      4:  <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
                      5:  <TITLE>BIRD User's Guide: Filters</TITLE>
                      6:  <LINK HREF="bird-6.html" REL=next>
                      7:  <LINK HREF="bird-4.html" REL=previous>
                      8:  <LINK HREF="bird.html#toc5" REL=contents>
                      9: </HEAD>
                     10: <BODY>
                     11: <A HREF="bird-6.html">Next</A>
                     12: <A HREF="bird-4.html">Previous</A>
                     13: <A HREF="bird.html#toc5">Contents</A>
                     14: <HR>
                     15: <H2><A NAME="filters"></A> <A NAME="s5">5.</A> <A HREF="bird.html#toc5">Filters</A></H2>
                     16: 
                     17: <H2><A NAME="filters-intro"></A> <A NAME="ss5.1">5.1</A> <A HREF="bird.html#toc5.1">Introduction</A>
                     18: </H2>
                     19: 
                     20: <P>BIRD contains a simple programming language. (No, it can't yet read mail :-).
                     21: There are two objects in this language: filters and functions. Filters are
                     22: interpreted by BIRD core when a route is being passed between protocols and
                     23: routing tables. The filter language contains control structures such as if's and
                     24: switches, but it allows no loops. An example of a filter using many features can
                     25: be found in <CODE>filter/test.conf</CODE>.
                     26: <P>
                     27: <P>Filter gets the route, looks at its attributes and modifies some of them if
                     28: it wishes. At the end, it decides whether to pass the changed route through
                     29: (using <CODE>accept</CODE>) or whether to <CODE>reject</CODE> it. A simple filter looks like
                     30: this:
                     31: <P>
                     32: <HR>
                     33: <PRE>
                     34: filter not_too_far
                     35: int var;
                     36: {
                     37:         if defined( rip_metric ) then
                     38:                 var = rip_metric;
                     39:         else {
                     40:                 var = 1;
                     41:                 rip_metric = 1;
                     42:         }
                     43:         if rip_metric &gt; 10 then
                     44:                 reject "RIP metric is too big";
                     45:         else
                     46:                 accept "ok";
                     47: }
                     48: </PRE>
                     49: <HR>
                     50: <P>
                     51: <P>As you can see, a filter has a header, a list of local variables, and a body.
                     52: The header consists of the <CODE>filter</CODE> keyword followed by a (unique) name of
                     53: filter. The list of local variables consists of <CODE><I>type name</I>;</CODE>
                     54: pairs where each pair defines one local variable. The body consists of <CODE>{ <I>statements</I> }</CODE>. Each <I>statement</I> is terminated by a <CODE>;</CODE>. You
                     55: can group several statements to a single compound statement by using braces
                     56: (<CODE>{ <I>statements</I> }</CODE>) which is useful if you want to make a bigger
                     57: block of code conditional.
                     58: <P>
                     59: <P>BIRD supports functions, so that you don't have to repeat the same blocks of
                     60: code over and over. Functions can have zero or more parameters and they can have
                     61: local variables. Recursion is not allowed. Function definitions look like this:
                     62: <P>
                     63: <HR>
                     64: <PRE>
                     65: function name ()
                     66: int local_variable;
                     67: {
                     68:         local_variable = 5;
                     69: }
                     70: 
                     71: function with_parameters (int parameter)
                     72: {
                     73:         print parameter;
                     74: }
                     75: </PRE>
                     76: <HR>
                     77: <P>
                     78: <P>Unlike in C, variables are declared after the <CODE>function</CODE> line, but before
                     79: the first <CODE>{</CODE>. You can't declare variables in nested blocks. Functions are
                     80: called like in C: <CODE>name(); with_parameters(5);</CODE>. Function may return
                     81: values using the <CODE>return <I>[expr]</I></CODE> command. Returning a value exits
                     82: from current function (this is similar to C).
                     83: <P>
                     84: <P>Filters are declared in a way similar to functions except they can't have
                     85: explicit parameters. They get a route table entry as an implicit parameter, it
                     86: is also passed automatically to any functions called. The filter must terminate
                     87: with either <CODE>accept</CODE> or <CODE>reject</CODE> statement. If there's a runtime error in
                     88: filter, the route is rejected.
                     89: <P>
                     90: <P>A nice trick to debug filters is to use <CODE>show route filter <I>name</I></CODE>
                     91: from the command line client. An example session might look like:
                     92: <P>
                     93: <HR>
                     94: <PRE>
                     95: pavel@bug:~/bird$ ./birdc -s bird.ctl
                     96: BIRD 0.0.0 ready.
                     97: bird> show route
                     98: 10.0.0.0/8         dev eth0 [direct1 23:21] (240)
                     99: 195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
                    100: 127.0.0.0/8        dev lo [direct1 23:21] (240)
                    101: bird> show route ?
                    102: show route [&lt;prefix>] [table &lt;t>] [filter &lt;f>] [all] [primary]...
                    103: bird> show route filter { if 127.0.0.5 ~ net then accept; }
                    104: 127.0.0.0/8        dev lo [direct1 23:21] (240)
                    105: bird>
                    106: </PRE>
                    107: <HR>
                    108: <P>
                    109: <P>
                    110: <H2><A NAME="data-types"></A> <A NAME="ss5.2">5.2</A> <A HREF="bird.html#toc5.2">Data types</A>
                    111: </H2>
                    112: 
                    113: <P>Each variable and each value has certain type. Booleans, integers and enums
                    114: are incompatible with each other (that is to prevent you from shooting in the
                    115: foot).
                    116: <P>
                    117: <DL>
                    118: <DT><CODE>
                    119: <A NAME="type-bool"></A> bool</CODE><DD><P>This is a boolean type, it can have only two values, <CODE>true</CODE> and
                    120: <CODE>false</CODE>. Boolean is the only type you can use in <CODE>if</CODE> statements.
                    121: <P>
                    122: <DT><CODE>
                    123: <A NAME="type-int"></A> int</CODE><DD><P>This is a general integer type. It is an unsigned 32bit type; i.e., you
                    124: can expect it to store values from 0 to 4294967295. Overflows are not
                    125: checked. You can use <CODE>0x1234</CODE> syntax to write hexadecimal values.
                    126: <P>
                    127: <DT><CODE>
                    128: <A NAME="type-pair"></A> pair</CODE><DD><P>This is a pair of two short integers. Each component can have values
                    129: from 0 to 65535. Literals of this type are written as <CODE>(1234,5678)</CODE>.
                    130: The same syntax can also be used to construct a pair from two arbitrary
                    131: integer expressions (for example <CODE>(1+2,a)</CODE>).
                    132: <P>
                    133: <DT><CODE>
                    134: <A NAME="type-quad"></A> quad</CODE><DD><P>This is a dotted quad of numbers used to represent router IDs (and
                    135: others). Each component can have a value from 0 to 255. Literals of
                    136: this type are written like IPv4 addresses.
                    137: <P>
                    138: <DT><CODE>
                    139: <A NAME="type-string"></A> string</CODE><DD><P>This is a string of characters. There are no ways to modify strings in
                    140: filters. You can pass them between functions, assign them to variables
                    141: of type <CODE>string</CODE>, print such variables, use standard string
                    142: comparison operations (e.g. <CODE>=, !=, &lt;, &gt;, &lt;=, &gt;=</CODE>), but
                    143: you can't concatenate two strings. String literals are written as
                    144: <CODE>"This is a string constant"</CODE>. Additionally matching (<CODE>~,
                    145: !~</CODE>) operators could be used to match a string value against
                    146: a shell pattern (represented also as a string).
                    147: <P>
                    148: <DT><CODE>
                    149: <A NAME="type-ip"></A> ip</CODE><DD><P>This type can hold a single IP address. Depending on the compile-time
                    150: configuration of BIRD you are using, it is either an IPv4 or IPv6
                    151: address. IP addresses are written in the standard notation
                    152: (<CODE>10.20.30.40</CODE> or <CODE>fec0:3:4::1</CODE>). You can apply special operator
                    153: <CODE>.mask(<I>num</I>)</CODE> on values of type ip. It masks out all but
                    154: first <CODE><I>num</I></CODE> bits from the IP address. So
                    155: <CODE>1.2.3.4.mask(8) = 1.0.0.0</CODE> is true.
                    156: <P>
                    157: <DT><CODE>
                    158: <A NAME="type-prefix"></A> prefix</CODE><DD><P>This type can hold a network prefix consisting of IP address and prefix
                    159: length. Prefix literals are written as <CODE><I>ipaddress</I>/<I>pxlen</I></CODE>,
                    160: or <CODE><I>ipaddress</I>/<I>netmask</I></CODE>. There are two special
                    161: operators on prefixes: <CODE>.ip</CODE> which extracts the IP address from the
                    162: pair, and <CODE>.len</CODE>, which separates prefix length from the pair.
                    163: So <CODE>1.2.0.0/16.len = 16</CODE> is true.
                    164: <P>
                    165: <DT><CODE>
                    166: <A NAME="type-ec"></A> ec</CODE><DD><P>This is a specialized type used to represent BGP extended community
                    167: values. It is essentially a 64bit value, literals of this type are
                    168: usually written as <CODE>(<I>kind</I>, <I>key</I>, <I>value</I>)</CODE>, where
                    169: <CODE>kind</CODE> is a kind of extended community (e.g. <CODE>rt</CODE> / <CODE>ro</CODE> for a
                    170: route target / route origin communities), the format and possible values
                    171: of <CODE>key</CODE> and <CODE>value</CODE> are usually integers, but it depends on the
                    172: used kind. Similarly to pairs, ECs can be constructed using expressions
                    173: for <CODE>key</CODE> and <CODE>value</CODE> parts, (e.g. <CODE>(ro, myas, 3*10)</CODE>, where
                    174: <CODE>myas</CODE> is an integer variable).
                    175: <P>
                    176: <DT><CODE>
                    177: <A NAME="type-lc"></A> lc</CODE><DD><P>This is a specialized type used to represent BGP large community
                    178: values. It is essentially a triplet of 32bit values, where the first
                    179: value is reserved for the AS number of the issuer, while meaning of
                    180: remaining parts is defined by the issuer. Literals of this type are
                    181: written as <CODE>(123, 456, 789)</CODE>, with any integer values. Similarly to
                    182: pairs, LCs can be constructed using expressions for its parts, (e.g.
                    183: <CODE>(myas, 10+20, 3*10)</CODE>, where <CODE>myas</CODE> is an integer variable).
                    184: <P>
                    185: <DT><CODE>
                    186: <A NAME="type-set"></A> int|pair|quad|ip|prefix|ec|lc|enum set</CODE><DD><P>Filters recognize four types of sets. Sets are similar to strings: you
                    187: can pass them around but you can't modify them. Literals of type <CODE>int
                    188: set</CODE> look like <CODE> [ 1, 2, 5..7 ]</CODE>. As you can see, both simple
                    189: values and ranges are permitted in sets.
                    190: <P>For pair sets, expressions like <CODE>(123,*)</CODE> can be used to denote
                    191: ranges (in that case <CODE>(123,0)..(123,65535)</CODE>). You can also use
                    192: <CODE>(123,5..100)</CODE> for range <CODE>(123,5)..(123,100)</CODE>. You can also use
                    193: <CODE>*</CODE> and <CODE>a..b</CODE> expressions in the first part of a pair, note that
                    194: such expressions are translated to a set of intervals, which may be
                    195: memory intensive. E.g. <CODE>(*,4..20)</CODE> is translated to <CODE>(0,4..20),
                    196: (1,4..20), (2,4..20), ... (65535, 4..20)</CODE>.
                    197: <P>EC sets use similar expressions like pair sets, e.g. <CODE>(rt, 123,
                    198: 10..20)</CODE> or <CODE>(ro, 123, *)</CODE>. Expressions requiring the translation
                    199: (like <CODE>(rt, *, 3)</CODE>) are not allowed (as they usually have 4B range
                    200: for ASNs).
                    201: <P>Also LC sets use similar expressions like pair sets. You can use ranges
                    202: and wildcards, but if one field uses that, more specific (later) fields
                    203: must be wildcards. E.g., <CODE>(10, 20..30, *)</CODE> or <CODE>(10, 20, 30..40)</CODE>
                    204: is valid, while <CODE>(10, *, 20..30)</CODE> or <CODE>(10, 20..30, 40)</CODE> is not
                    205: valid.
                    206: <P>You can also use expressions for int, pair, EC and LC set values.
                    207: However, it must be possible to evaluate these expressions before daemon
                    208: boots. So you can use only constants inside them. E.g.
                    209: <P>
                    210: <HR>
                    211: <PRE>
                    212:          define one=1;
                    213:          define myas=64500;
                    214:          int set odds;
                    215:          pair set ps;
                    216:          ec set es;
                    217: 
                    218:          odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
                    219:          ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
                    220:          es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
                    221:         
                    222: </PRE>
                    223: <HR>
                    224: <P>Sets of prefixes are special: their literals does not allow ranges, but
                    225: allows prefix patterns that are written
                    226: as <CODE><I>ipaddress</I>/<I>pxlen</I>{<I>low</I>,<I>high</I>}</CODE>.
                    227: Prefix <CODE><I>ip1</I>/<I>len1</I></CODE> matches prefix
                    228: pattern <CODE><I>ip2</I>/<I>len2</I>{<I>l</I>,<I>h</I>}</CODE> if the
                    229: first <CODE>min(len1, len2)</CODE> bits of <CODE>ip1</CODE> and <CODE>ip2</CODE> are
                    230: identical and <CODE>len1 &lt;= ip1 &lt;= len2</CODE>. A valid prefix pattern
                    231: has to satisfy <CODE>low &lt;= high</CODE>, but <CODE>pxlen</CODE> is not
                    232: constrained by <CODE>low</CODE> or <CODE>high</CODE>. Obviously, a prefix matches a
                    233: prefix set literal if it matches any prefix pattern in the prefix set
                    234: literal.
                    235: <P>There are also two shorthands for prefix patterns: <CODE><I>address</I>/<I>len</I>+</CODE>
                    236: is a shorthand for <CODE><I>address</I>/<I>len</I>{<I>len</I>,<I>maxlen</I>}</CODE>
                    237: (where <CODE><I>maxlen</I></CODE> is 32 for IPv4 and 128 for IPv6), that means
                    238: network prefix <CODE><I>address</I>/<I>len</I></CODE> and all its       subnets.
                    239: <CODE><I>address</I>/<I>len</I>-</CODE> is a shorthand for
                    240: <CODE><I>address</I>/<I>len</I>{0,<I>len</I>}</CODE>, that means network prefix
                    241: <CODE><I>address</I>/<I>len</I></CODE> and all its supernets (network prefixes
                    242: that contain it).
                    243: <P>For example, <CODE>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24}
                    244: ]</CODE> matches prefix <CODE>1.0.0.0/8</CODE>, all subprefixes of
                    245: <CODE>2.0.0.0/8</CODE>, all superprefixes of <CODE>3.0.0.0/8</CODE> and prefixes
                    246: <CODE>4.X.X.X</CODE> whose prefix length is 16 to 24. <CODE>[ 0.0.0.0/0{20,24} ]</CODE>
                    247: matches all prefixes (regardless of IP address) whose prefix length is
                    248: 20 to 24, <CODE>[ 1.2.3.4/32- ]</CODE> matches any prefix that contains IP
                    249: address <CODE>1.2.3.4</CODE>. <CODE>1.2.0.0/16 ~ [ 1.0.0.0/8{15,17} ]</CODE>
                    250: is true, but <CODE>1.0.0.0/16 ~ [ 1.0.0.0/8- ]</CODE> is false.
                    251: <P>Cisco-style patterns like <CODE>10.0.0.0/8 ge 16 le 24</CODE> can be expressed
                    252: in BIRD as <CODE>10.0.0.0/8{16,24}</CODE>, <CODE>192.168.0.0/16 le 24</CODE> as
                    253: <CODE>192.168.0.0/16{16,24}</CODE> and <CODE>192.168.0.0/16 ge 24</CODE> as
                    254: <CODE>192.168.0.0/16{24,32}</CODE>.
                    255: <P>
                    256: <DT><CODE>
                    257: <A NAME="type-enum"></A> enum</CODE><DD><P>Enumeration types are fixed sets of possibilities. You can't define your
                    258: own variables of such type, but some route attributes are of enumeration
                    259: type. Enumeration types are incompatible with each other.
                    260: <P>
                    261: <DT><CODE>
                    262: <A NAME="type-bgppath"></A> bgppath</CODE><DD><P>BGP path is a list of autonomous system numbers. You can't write
                    263: literals of this type. There are several special operators on bgppaths:
                    264: <P><CODE><I>P</I>.first</CODE> returns the first ASN (the neighbor ASN) in path <I>P</I>.
                    265: <P><CODE><I>P</I>.last</CODE> returns the last ASN (the source ASN) in path <I>P</I>.
                    266: <P><CODE><I>P</I>.last_nonaggregated</CODE> returns the last ASN in the non-aggregated part of the path <I>P</I>.
                    267: <P>Both <CODE>first</CODE> and <CODE>last</CODE> return zero if there is no appropriate
                    268: ASN, for example if the path contains an AS set element as the first (or
                    269: the last) part. If the path ends with an AS set, <CODE>last_nonaggregated</CODE>
                    270: may be used to get last ASN before any AS set.
                    271: <P><CODE><I>P</I>.len</CODE> returns the length of path <I>P</I>.
                    272: <P><CODE>prepend(<I>P</I>,<I>A</I>)</CODE> prepends ASN <I>A</I> to path <I>P</I> and
                    273: returns the result.
                    274: <P><CODE>delete(<I>P</I>,<I>A</I>)</CODE> deletes all instances of ASN <I>A</I> from
                    275: from path <I>P</I> and returns the result. <I>A</I> may also be an integer
                    276: set, in that case the operator deletes all ASNs from path <I>P</I> that are
                    277: also members of set <I>A</I>.
                    278: <P><CODE>filter(<I>P</I>,<I>A</I>)</CODE> deletes all ASNs from path <I>P</I> that are
                    279: not members of integer set <I>A</I>. I.e., <CODE>filter</CODE> do the same as
                    280: <CODE>delete</CODE> with inverted set <I>A</I>.
                    281: <P>Statement <CODE><I>P</I> = prepend(<I>P</I>, <I>A</I>);</CODE> can be shortened to
                    282: <CODE><I>P</I>.prepend(<I>A</I>);</CODE> if <I>P</I> is appropriate route attribute
                    283: (for example <CODE>bgp_path</CODE>). Similarly for <CODE>delete</CODE> and <CODE>filter</CODE>.
                    284: <P>
                    285: <DT><CODE>
                    286: <A NAME="type-bgpmask"></A> bgpmask</CODE><DD><P>BGP masks are patterns used for BGP path matching (using <CODE>path
                    287: ~ [= 2 3 5 * =]</CODE> syntax). The masks resemble wildcard patterns
                    288: as used by UNIX shells. Autonomous system numbers match themselves,
                    289: <CODE>*</CODE> matches any (even empty) sequence of arbitrary AS numbers and
                    290: <CODE>?</CODE> matches one arbitrary AS number. For example, if <CODE>bgp_path</CODE>
                    291: is 4 3 2 1, then: <CODE>bgp_path ~ [= * 4 3 * =]</CODE> is true,
                    292: but <CODE>bgp_path ~ [= * 4 5 * =]</CODE> is false. BGP mask
                    293: expressions can also contain integer expressions enclosed in parenthesis
                    294: and integer variables, for example <CODE>[= * 4 (1+2) a =]</CODE>. You can
                    295: also use ranges, for example <CODE>[= * 3..5 2 100..200 * =]</CODE>.
                    296: There is also old (deprecated) syntax that uses / .. / instead of [= .. =]
                    297: and ? instead of *.
                    298: <P>
                    299: <DT><CODE>
                    300: <A NAME="type-clist"></A> clist</CODE><DD><P>Clist is similar to a set, except that unlike other sets, it can be
                    301: modified. The type is used for community list (a set of pairs) and for
                    302: cluster list (a set of quads). There exist no literals of this type.
                    303: There are three special operators on clists:
                    304: <P><CODE><I>C</I>.len</CODE> returns the length of clist <I>C</I>.
                    305: <P><CODE>add(<I>C</I>,<I>P</I>)</CODE> adds pair (or quad) <I>P</I> to clist <I>C</I> and
                    306: returns the result. If item <I>P</I> is already in clist <I>C</I>, it does
                    307: nothing. <I>P</I> may also be a clist, in that case all its members are
                    308: added; i.e., it works as clist union.
                    309: <P><CODE>delete(<I>C</I>,<I>P</I>)</CODE> deletes pair (or quad) <I>P</I> from clist
                    310: <I>C</I> and returns the result. If clist <I>C</I> does not contain item
                    311: <I>P</I>, it does nothing. <I>P</I> may also be a pair (or quad) set, in that
                    312: case the operator deletes all items from clist <I>C</I> that are also
                    313: members of set <I>P</I>. Moreover, <I>P</I> may also be a clist, which works
                    314: analogously; i.e., it works as clist difference.
                    315: <P><CODE>filter(<I>C</I>,<I>P</I>)</CODE> deletes all items from clist <I>C</I> that are
                    316: not members of pair (or quad) set <I>P</I>. I.e., <CODE>filter</CODE> do the same
                    317: as <CODE>delete</CODE> with inverted set <I>P</I>. <I>P</I> may also be a clist, which
                    318: works analogously; i.e., it works as clist intersection.
                    319: <P>Statement <CODE><I>C</I> = add(<I>C</I>, <I>P</I>);</CODE> can be shortened to
                    320: <CODE><I>C</I>.add(<I>P</I>);</CODE> if <I>C</I> is appropriate route attribute (for
                    321: example <CODE>bgp_community</CODE>). Similarly for <CODE>delete</CODE> and <CODE>filter</CODE>.
                    322: <P>
                    323: <DT><CODE>
                    324: <A NAME="type-eclist"></A> eclist</CODE><DD><P>Eclist is a data type used for BGP extended community lists. Eclists
                    325: are very similar to clists, but they are sets of ECs instead of pairs.
                    326: The same operations (like <CODE>add</CODE>, <CODE>delete</CODE> or <CODE>~</CODE> and
                    327: <CODE>!~</CODE> membership operators) can be used to modify or test
                    328: eclists, with ECs instead of pairs as arguments.
                    329: <P>
                    330: <DT><CODE>lclist</CODE><DD><P>Lclist is a data type used for BGP large community lists. Like eclists,
                    331: lclists are very similar to clists, but they are sets of LCs instead of
                    332: pairs. The same operations (like <CODE>add</CODE>, <CODE>delete</CODE> or <CODE>~</CODE>
                    333: and <CODE>!~</CODE> membership operators) can be used to modify or test
                    334: lclists, with LCs instead of pairs as arguments.
                    335: </DL>
                    336: <P>
                    337: <P>
                    338: <H2><A NAME="operators"></A> <A NAME="ss5.3">5.3</A> <A HREF="bird.html#toc5.3">Operators</A>
                    339: </H2>
                    340: 
                    341: <P>The filter language supports common integer operators <CODE>(+,-,*,/)</CODE>,
                    342: parentheses <CODE>(a*(b+c))</CODE>, comparison <CODE>(a=b, a!=b, a&lt;b, a&gt;=b)</CODE>.
                    343: Logical operations include unary not (<CODE>!</CODE>), and (<CODE>&amp;&amp;</CODE>) and or
                    344: (<CODE>||</CODE>). Special operators include (<CODE>~</CODE>,
                    345: <CODE>!~</CODE>) for "is (not) element of a set" operation - it can be used on
                    346: element and set of elements of the same type (returning true if element is
                    347: contained in the given set), or on two strings (returning true if first string
                    348: matches a shell-like pattern stored in second string) or on IP and prefix
                    349: (returning true if IP is within the range defined by that prefix), or on prefix
                    350: and prefix (returning true if first prefix is more specific than second one) or
                    351: on bgppath and bgpmask (returning true if the path matches the mask) or on
                    352: number and bgppath (returning true if the number is in the path) or on bgppath
                    353: and int (number) set (returning true if any ASN from the path is in the set) or
                    354: on pair/quad and clist (returning true if the pair/quad is element of the
                    355: clist) or on clist and pair/quad set (returning true if there is an element of
                    356: the clist that is also a member of the pair/quad set).
                    357: <P>
                    358: <P>There is one operator related to ROA infrastructure - <CODE>roa_check()</CODE>. It
                    359: examines a ROA table and does <A HREF="http://www.rfc-editor.org/info/rfc6483">RFC 6483</A> route origin validation for a
                    360: given network prefix. The basic usage is <CODE>roa_check(<I>table</I>)</CODE>, which
                    361: checks current route (which should be from BGP to have AS_PATH argument) in the
                    362: specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
                    363: ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
                    364: ROAs but none of them match. There is also an extended variant
                    365: <CODE>roa_check(<I>table</I>, <I>prefix</I>, <I>asn</I>)</CODE>, which allows to specify a
                    366: prefix and an ASN as arguments.
                    367: <P>
                    368: <P>
                    369: <H2><A NAME="control-structures"></A> <A NAME="ss5.4">5.4</A> <A HREF="bird.html#toc5.4">Control structures</A>
                    370: </H2>
                    371: 
                    372: <P>Filters support two control structures: conditions and case switches.
                    373: <P>
                    374: <P>Syntax of a condition is: <CODE>if <I>boolean expression</I> then <I>command1</I>;
                    375: else <I>command2</I>;</CODE> and you can use <CODE>{ <I>command_1</I>; <I>command_2</I>;
                    376: <I>...</I> }</CODE> instead of either command. The <CODE>else</CODE> clause may be
                    377: omitted. If the <CODE><I>boolean expression</I></CODE> is true, <I>command1</I> is
                    378: executed, otherwise <I>command2</I> is executed.
                    379: <P>
                    380: <P>The <CODE>case</CODE> is similar to case from Pascal. Syntax is <CODE>case
                    381: <I>expr</I> { else: | <I>num_or_prefix [ .. num_or_prefix]</I>: <I>statement</I> ; [
                    382: ... ] }</CODE>. The expression after <CODE>case</CODE> can be of any type which can be
                    383: on the left side of the ~ operator and anything that could be a member of
                    384: a set is allowed before <CODE>:</CODE>. Multiple commands are allowed without <CODE>{}</CODE>
                    385: grouping. If <CODE><I>expr</I></CODE> matches one of the <CODE>:</CODE> clauses, statements
                    386: between it and next <CODE>:</CODE> statement are executed. If <CODE><I>expr</I></CODE> matches
                    387: neither of the <CODE>:</CODE> clauses, the statements after <CODE>else:</CODE> are executed.
                    388: <P>
                    389: <P>Here is example that uses <CODE>if</CODE> and <CODE>case</CODE> structures:
                    390: <P>
                    391: <HR>
                    392: <PRE>
                    393: case arg1 {
                    394:         2: print "two"; print "I can do more commands without {}";
                    395:         3 .. 5: print "three to five";
                    396:         else: print "something else";
                    397: }
                    398: 
                    399: if 1234 = i then printn "."; else {
                    400:   print "not 1234";
                    401:   print "You need {} around multiple commands";
                    402: }
                    403: </PRE>
                    404: <HR>
                    405: <P>
                    406: <P>
                    407: <H2><A NAME="route-attributes"></A> <A NAME="ss5.5">5.5</A> <A HREF="bird.html#toc5.5">Route attributes</A>
                    408: </H2>
                    409: 
                    410: <P>A filter is implicitly passed a route, and it can access its attributes just
                    411: like it accesses variables. Attempts to access undefined attribute result in a
                    412: runtime error; you can check if an attribute is defined by using the
                    413: <CODE>defined( <I>attribute</I> )</CODE> operator. One notable exception to this
                    414: rule are attributes of clist type, where undefined value is regarded as empty
                    415: clist for most purposes.
                    416: <P>
                    417: <DL>
                    418: <DT><CODE>
                    419: <A NAME="rta-net"></A> <I>prefix</I> net</CODE><DD><P>Network the route is talking about. Read-only. (See the chapter about
                    420: routing tables.)
                    421: <P>
                    422: <DT><CODE>
                    423: <A NAME="rta-scope"></A> <I>enum</I> scope</CODE><DD><P>The scope of the route. Possible values: <CODE>SCOPE_HOST</CODE> for routes
                    424: local to this host, <CODE>SCOPE_LINK</CODE> for those specific for a physical
                    425: link, <CODE>SCOPE_SITE</CODE> and <CODE>SCOPE_ORGANIZATION</CODE> for private routes and
                    426: <CODE>SCOPE_UNIVERSE</CODE> for globally visible routes. This attribute is not
                    427: interpreted by BIRD and can be used to mark routes in filters. The
                    428: default value for new routes is <CODE>SCOPE_UNIVERSE</CODE>.
                    429: <P>
                    430: <DT><CODE>
                    431: <A NAME="rta-preference"></A> <I>int</I> preference</CODE><DD><P>Preference of the route. Valid values are 0-65535. (See the chapter
                    432: about routing tables.)
                    433: <P>
                    434: <DT><CODE>
                    435: <A NAME="rta-from"></A> <I>ip</I> from</CODE><DD><P>The router which the route has originated from.
                    436: <P>
                    437: <DT><CODE>
                    438: <A NAME="rta-gw"></A> <I>ip</I> gw</CODE><DD><P>Next hop packets routed using this route should be forwarded to.
                    439: <P>
                    440: <DT><CODE>
                    441: <A NAME="rta-proto"></A> <I>string</I> proto</CODE><DD><P>The name of the protocol which the route has been imported from.
                    442: Read-only.
                    443: <P>
                    444: <DT><CODE>
                    445: <A NAME="rta-source"></A> <I>enum</I> source</CODE><DD><P>what protocol has told me about this route. Possible values:
                    446: <CODE>RTS_DUMMY</CODE>, <CODE>RTS_STATIC</CODE>, <CODE>RTS_INHERIT</CODE>, <CODE>RTS_DEVICE</CODE>,
                    447: <CODE>RTS_STATIC_DEVICE</CODE>, <CODE>RTS_REDIRECT</CODE>, <CODE>RTS_RIP</CODE>, <CODE>RTS_OSPF</CODE>,
                    448: <CODE>RTS_OSPF_IA</CODE>, <CODE>RTS_OSPF_EXT1</CODE>, <CODE>RTS_OSPF_EXT2</CODE>, <CODE>RTS_BGP</CODE>,
                    449: <CODE>RTS_PIPE</CODE>, <CODE>RTS_BABEL</CODE>.
                    450: <P>
                    451: <DT><CODE>
                    452: <A NAME="rta-cast"></A> <I>enum</I> cast</CODE><DD><P>Route type (Currently <CODE>RTC_UNICAST</CODE> for normal routes,
                    453: <CODE>RTC_BROADCAST</CODE>, <CODE>RTC_MULTICAST</CODE>, <CODE>RTC_ANYCAST</CODE> will be used in
                    454: the future for broadcast, multicast and anycast routes). Read-only.
                    455: <P>
                    456: <DT><CODE>
                    457: <A NAME="rta-dest"></A> <I>enum</I> dest</CODE><DD><P>Type of destination the packets should be sent to
                    458: (<CODE>RTD_ROUTER</CODE> for forwarding to a neighboring router,
                    459: <CODE>RTD_DEVICE</CODE> for routing to a directly-connected network,
                    460: <CODE>RTD_MULTIPATH</CODE> for multipath destinations,
                    461: <CODE>RTD_BLACKHOLE</CODE> for packets to be silently discarded,
                    462: <CODE>RTD_UNREACHABLE</CODE>, <CODE>RTD_PROHIBIT</CODE> for packets that should be
                    463: returned with ICMP host unreachable / ICMP administratively prohibited
                    464: messages). Can be changed, but only to <CODE>RTD_BLACKHOLE</CODE>,
                    465: <CODE>RTD_UNREACHABLE</CODE> or <CODE>RTD_PROHIBIT</CODE>.
                    466: <P>
                    467: <DT><CODE>
                    468: <A NAME="rta-ifname"></A> <I>string</I> ifname</CODE><DD><P>Name of the outgoing interface. Sink routes (like blackhole, unreachable
                    469: or prohibit) and multipath routes have no interface associated with
                    470: them, so <CODE>ifname</CODE> returns an empty string for such routes. Read-only.
                    471: <P>
                    472: <DT><CODE>
                    473: <A NAME="rta-ifindex"></A> <I>int</I> ifindex</CODE><DD><P>Index of the outgoing interface. System wide index of the interface. May
                    474: be used for interface matching, however indexes might change on interface
                    475: creation/removal. Zero is returned for routes with undefined outgoing
                    476: interfaces. Read-only.
                    477: <P>
                    478: <DT><CODE>
                    479: <A NAME="rta-igp-metric"></A> <I>int</I> igp_metric</CODE><DD><P>The optional attribute that can be used to specify a distance to the
                    480: network for routes that do not have a native protocol metric attribute
                    481: (like <CODE>ospf_metric1</CODE> for OSPF routes). It is used mainly by BGP to
                    482: compare internal distances to boundary routers (see below). It is also
                    483: used when the route is exported to OSPF as a default value for OSPF type
                    484: 1 metric.
                    485: </DL>
                    486: <P>
                    487: <P>There also exist some protocol-specific attributes which are described in the
                    488: corresponding protocol sections.
                    489: <P>
                    490: <P>
                    491: <H2><A NAME="other-statements"></A> <A NAME="ss5.6">5.6</A> <A HREF="bird.html#toc5.6">Other statements</A>
                    492: </H2>
                    493: 
                    494: <P>The following statements are available:
                    495: <P>
                    496: <DL>
                    497: <DT><CODE>
                    498: <A NAME="assignment"></A> <I>variable</I> = <I>expr</I></CODE><DD><P>Set variable to a given value.
                    499: <P>
                    500: <DT><CODE>
                    501: <A NAME="filter-accept-reject"></A> accept|reject [ <I>expr</I> ]</CODE><DD><P>Accept or reject the route, possibly printing <CODE><I>expr</I></CODE>.
                    502: <P>
                    503: <DT><CODE>
                    504: <A NAME="return"></A> return <I>expr</I></CODE><DD><P>Return <CODE><I>expr</I></CODE> from the current function, the function ends
                    505: at this point.
                    506: <P>
                    507: <DT><CODE>
                    508: <A NAME="print"></A> print|printn <I>expr</I> [<I>, expr...</I>]</CODE><DD><P>Prints given expressions; useful mainly while debugging filters. The
                    509: <CODE>printn</CODE> variant does not terminate the line.
                    510: <P>
                    511: <DT><CODE>
                    512: <A NAME="quitbird"></A> quitbird</CODE><DD><P>Terminates BIRD. Useful when debugging the filter interpreter.
                    513: </DL>
                    514: <P>
                    515: <P>
                    516: <HR>
                    517: <A HREF="bird-6.html">Next</A>
                    518: <A HREF="bird-4.html">Previous</A>
                    519: <A HREF="bird.html#toc5">Contents</A>
                    520: </BODY>
                    521: </HTML>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>