Annotation of embedaddon/bird/doc/bird-5.html, revision 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 > 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 [<prefix>] [table <t>] [filter <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>=, !=, <, >, <=, >=</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 <= ip1 <= len2</CODE>. A valid prefix pattern
! 231: has to satisfy <CODE>low <= 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<b, a>=b)</CODE>.
! 343: Logical operations include unary not (<CODE>!</CODE>), and (<CODE>&&</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>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to bird-5.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc