Annotation of embedaddon/bird/doc/bird-5.html, revision 1.1.1.2
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>.
1.1.1.2 ! misho 272: <P><CODE><I>P</I>.empty</CODE> resets path <I>P</I> to empty path.
1.1 misho 273: <P><CODE>prepend(<I>P</I>,<I>A</I>)</CODE> prepends ASN <I>A</I> to path <I>P</I> and
274: returns the result.
275: <P><CODE>delete(<I>P</I>,<I>A</I>)</CODE> deletes all instances of ASN <I>A</I> from
276: from path <I>P</I> and returns the result. <I>A</I> may also be an integer
277: set, in that case the operator deletes all ASNs from path <I>P</I> that are
278: also members of set <I>A</I>.
279: <P><CODE>filter(<I>P</I>,<I>A</I>)</CODE> deletes all ASNs from path <I>P</I> that are
280: not members of integer set <I>A</I>. I.e., <CODE>filter</CODE> do the same as
281: <CODE>delete</CODE> with inverted set <I>A</I>.
282: <P>Statement <CODE><I>P</I> = prepend(<I>P</I>, <I>A</I>);</CODE> can be shortened to
283: <CODE><I>P</I>.prepend(<I>A</I>);</CODE> if <I>P</I> is appropriate route attribute
284: (for example <CODE>bgp_path</CODE>). Similarly for <CODE>delete</CODE> and <CODE>filter</CODE>.
285: <P>
286: <DT><CODE>
287: <A NAME="type-bgpmask"></A> bgpmask</CODE><DD><P>BGP masks are patterns used for BGP path matching (using <CODE>path
288: ~ [= 2 3 5 * =]</CODE> syntax). The masks resemble wildcard patterns
289: as used by UNIX shells. Autonomous system numbers match themselves,
290: <CODE>*</CODE> matches any (even empty) sequence of arbitrary AS numbers and
291: <CODE>?</CODE> matches one arbitrary AS number. For example, if <CODE>bgp_path</CODE>
292: is 4 3 2 1, then: <CODE>bgp_path ~ [= * 4 3 * =]</CODE> is true,
293: but <CODE>bgp_path ~ [= * 4 5 * =]</CODE> is false. BGP mask
294: expressions can also contain integer expressions enclosed in parenthesis
295: and integer variables, for example <CODE>[= * 4 (1+2) a =]</CODE>. You can
296: also use ranges, for example <CODE>[= * 3..5 2 100..200 * =]</CODE>.
297: There is also old (deprecated) syntax that uses / .. / instead of [= .. =]
298: and ? instead of *.
299: <P>
300: <DT><CODE>
301: <A NAME="type-clist"></A> clist</CODE><DD><P>Clist is similar to a set, except that unlike other sets, it can be
302: modified. The type is used for community list (a set of pairs) and for
303: cluster list (a set of quads). There exist no literals of this type.
304: There are three special operators on clists:
305: <P><CODE><I>C</I>.len</CODE> returns the length of clist <I>C</I>.
1.1.1.2 ! misho 306: <P><CODE><I>C</I>.empty</CODE> resets clist <I>C</I> to empty clist.
1.1 misho 307: <P><CODE>add(<I>C</I>,<I>P</I>)</CODE> adds pair (or quad) <I>P</I> to clist <I>C</I> and
308: returns the result. If item <I>P</I> is already in clist <I>C</I>, it does
309: nothing. <I>P</I> may also be a clist, in that case all its members are
310: added; i.e., it works as clist union.
311: <P><CODE>delete(<I>C</I>,<I>P</I>)</CODE> deletes pair (or quad) <I>P</I> from clist
312: <I>C</I> and returns the result. If clist <I>C</I> does not contain item
313: <I>P</I>, it does nothing. <I>P</I> may also be a pair (or quad) set, in that
314: case the operator deletes all items from clist <I>C</I> that are also
315: members of set <I>P</I>. Moreover, <I>P</I> may also be a clist, which works
316: analogously; i.e., it works as clist difference.
317: <P><CODE>filter(<I>C</I>,<I>P</I>)</CODE> deletes all items from clist <I>C</I> that are
318: not members of pair (or quad) set <I>P</I>. I.e., <CODE>filter</CODE> do the same
319: as <CODE>delete</CODE> with inverted set <I>P</I>. <I>P</I> may also be a clist, which
320: works analogously; i.e., it works as clist intersection.
321: <P>Statement <CODE><I>C</I> = add(<I>C</I>, <I>P</I>);</CODE> can be shortened to
322: <CODE><I>C</I>.add(<I>P</I>);</CODE> if <I>C</I> is appropriate route attribute (for
323: example <CODE>bgp_community</CODE>). Similarly for <CODE>delete</CODE> and <CODE>filter</CODE>.
324: <P>
325: <DT><CODE>
326: <A NAME="type-eclist"></A> eclist</CODE><DD><P>Eclist is a data type used for BGP extended community lists. Eclists
327: are very similar to clists, but they are sets of ECs instead of pairs.
328: The same operations (like <CODE>add</CODE>, <CODE>delete</CODE> or <CODE>~</CODE> and
329: <CODE>!~</CODE> membership operators) can be used to modify or test
330: eclists, with ECs instead of pairs as arguments.
331: <P>
332: <DT><CODE>lclist</CODE><DD><P>Lclist is a data type used for BGP large community lists. Like eclists,
333: lclists are very similar to clists, but they are sets of LCs instead of
334: pairs. The same operations (like <CODE>add</CODE>, <CODE>delete</CODE> or <CODE>~</CODE>
335: and <CODE>!~</CODE> membership operators) can be used to modify or test
336: lclists, with LCs instead of pairs as arguments.
337: </DL>
338: <P>
339: <P>
340: <H2><A NAME="operators"></A> <A NAME="ss5.3">5.3</A> <A HREF="bird.html#toc5.3">Operators</A>
341: </H2>
342:
343: <P>The filter language supports common integer operators <CODE>(+,-,*,/)</CODE>,
344: parentheses <CODE>(a*(b+c))</CODE>, comparison <CODE>(a=b, a!=b, a<b, a>=b)</CODE>.
345: Logical operations include unary not (<CODE>!</CODE>), and (<CODE>&&</CODE>) and or
346: (<CODE>||</CODE>). Special operators include (<CODE>~</CODE>,
347: <CODE>!~</CODE>) for "is (not) element of a set" operation - it can be used on
348: element and set of elements of the same type (returning true if element is
349: contained in the given set), or on two strings (returning true if first string
350: matches a shell-like pattern stored in second string) or on IP and prefix
351: (returning true if IP is within the range defined by that prefix), or on prefix
352: and prefix (returning true if first prefix is more specific than second one) or
353: on bgppath and bgpmask (returning true if the path matches the mask) or on
354: number and bgppath (returning true if the number is in the path) or on bgppath
355: and int (number) set (returning true if any ASN from the path is in the set) or
356: on pair/quad and clist (returning true if the pair/quad is element of the
357: clist) or on clist and pair/quad set (returning true if there is an element of
358: the clist that is also a member of the pair/quad set).
359: <P>
360: <P>There is one operator related to ROA infrastructure - <CODE>roa_check()</CODE>. It
361: examines a ROA table and does <A HREF="http://www.rfc-editor.org/info/rfc6483">RFC 6483</A> route origin validation for a
362: given network prefix. The basic usage is <CODE>roa_check(<I>table</I>)</CODE>, which
363: checks current route (which should be from BGP to have AS_PATH argument) in the
364: specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
365: ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
366: ROAs but none of them match. There is also an extended variant
367: <CODE>roa_check(<I>table</I>, <I>prefix</I>, <I>asn</I>)</CODE>, which allows to specify a
368: prefix and an ASN as arguments.
369: <P>
370: <P>
371: <H2><A NAME="control-structures"></A> <A NAME="ss5.4">5.4</A> <A HREF="bird.html#toc5.4">Control structures</A>
372: </H2>
373:
374: <P>Filters support two control structures: conditions and case switches.
375: <P>
376: <P>Syntax of a condition is: <CODE>if <I>boolean expression</I> then <I>command1</I>;
377: else <I>command2</I>;</CODE> and you can use <CODE>{ <I>command_1</I>; <I>command_2</I>;
378: <I>...</I> }</CODE> instead of either command. The <CODE>else</CODE> clause may be
379: omitted. If the <CODE><I>boolean expression</I></CODE> is true, <I>command1</I> is
380: executed, otherwise <I>command2</I> is executed.
381: <P>
382: <P>The <CODE>case</CODE> is similar to case from Pascal. Syntax is <CODE>case
383: <I>expr</I> { else: | <I>num_or_prefix [ .. num_or_prefix]</I>: <I>statement</I> ; [
384: ... ] }</CODE>. The expression after <CODE>case</CODE> can be of any type which can be
385: on the left side of the ~ operator and anything that could be a member of
386: a set is allowed before <CODE>:</CODE>. Multiple commands are allowed without <CODE>{}</CODE>
387: grouping. If <CODE><I>expr</I></CODE> matches one of the <CODE>:</CODE> clauses, statements
388: between it and next <CODE>:</CODE> statement are executed. If <CODE><I>expr</I></CODE> matches
389: neither of the <CODE>:</CODE> clauses, the statements after <CODE>else:</CODE> are executed.
390: <P>
391: <P>Here is example that uses <CODE>if</CODE> and <CODE>case</CODE> structures:
392: <P>
393: <HR>
394: <PRE>
395: case arg1 {
396: 2: print "two"; print "I can do more commands without {}";
397: 3 .. 5: print "three to five";
398: else: print "something else";
399: }
400:
401: if 1234 = i then printn "."; else {
402: print "not 1234";
403: print "You need {} around multiple commands";
404: }
405: </PRE>
406: <HR>
407: <P>
408: <P>
409: <H2><A NAME="route-attributes"></A> <A NAME="ss5.5">5.5</A> <A HREF="bird.html#toc5.5">Route attributes</A>
410: </H2>
411:
412: <P>A filter is implicitly passed a route, and it can access its attributes just
413: like it accesses variables. Attempts to access undefined attribute result in a
414: runtime error; you can check if an attribute is defined by using the
415: <CODE>defined( <I>attribute</I> )</CODE> operator. One notable exception to this
416: rule are attributes of clist type, where undefined value is regarded as empty
417: clist for most purposes.
418: <P>
419: <DL>
420: <DT><CODE>
421: <A NAME="rta-net"></A> <I>prefix</I> net</CODE><DD><P>Network the route is talking about. Read-only. (See the chapter about
422: routing tables.)
423: <P>
424: <DT><CODE>
425: <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
426: local to this host, <CODE>SCOPE_LINK</CODE> for those specific for a physical
427: link, <CODE>SCOPE_SITE</CODE> and <CODE>SCOPE_ORGANIZATION</CODE> for private routes and
428: <CODE>SCOPE_UNIVERSE</CODE> for globally visible routes. This attribute is not
429: interpreted by BIRD and can be used to mark routes in filters. The
430: default value for new routes is <CODE>SCOPE_UNIVERSE</CODE>.
431: <P>
432: <DT><CODE>
433: <A NAME="rta-preference"></A> <I>int</I> preference</CODE><DD><P>Preference of the route. Valid values are 0-65535. (See the chapter
434: about routing tables.)
435: <P>
436: <DT><CODE>
437: <A NAME="rta-from"></A> <I>ip</I> from</CODE><DD><P>The router which the route has originated from.
438: <P>
439: <DT><CODE>
440: <A NAME="rta-gw"></A> <I>ip</I> gw</CODE><DD><P>Next hop packets routed using this route should be forwarded to.
441: <P>
442: <DT><CODE>
443: <A NAME="rta-proto"></A> <I>string</I> proto</CODE><DD><P>The name of the protocol which the route has been imported from.
444: Read-only.
445: <P>
446: <DT><CODE>
447: <A NAME="rta-source"></A> <I>enum</I> source</CODE><DD><P>what protocol has told me about this route. Possible values:
448: <CODE>RTS_DUMMY</CODE>, <CODE>RTS_STATIC</CODE>, <CODE>RTS_INHERIT</CODE>, <CODE>RTS_DEVICE</CODE>,
449: <CODE>RTS_STATIC_DEVICE</CODE>, <CODE>RTS_REDIRECT</CODE>, <CODE>RTS_RIP</CODE>, <CODE>RTS_OSPF</CODE>,
450: <CODE>RTS_OSPF_IA</CODE>, <CODE>RTS_OSPF_EXT1</CODE>, <CODE>RTS_OSPF_EXT2</CODE>, <CODE>RTS_BGP</CODE>,
451: <CODE>RTS_PIPE</CODE>, <CODE>RTS_BABEL</CODE>.
452: <P>
453: <DT><CODE>
454: <A NAME="rta-cast"></A> <I>enum</I> cast</CODE><DD><P>Route type (Currently <CODE>RTC_UNICAST</CODE> for normal routes,
455: <CODE>RTC_BROADCAST</CODE>, <CODE>RTC_MULTICAST</CODE>, <CODE>RTC_ANYCAST</CODE> will be used in
456: the future for broadcast, multicast and anycast routes). Read-only.
457: <P>
458: <DT><CODE>
459: <A NAME="rta-dest"></A> <I>enum</I> dest</CODE><DD><P>Type of destination the packets should be sent to
460: (<CODE>RTD_ROUTER</CODE> for forwarding to a neighboring router,
461: <CODE>RTD_DEVICE</CODE> for routing to a directly-connected network,
462: <CODE>RTD_MULTIPATH</CODE> for multipath destinations,
463: <CODE>RTD_BLACKHOLE</CODE> for packets to be silently discarded,
464: <CODE>RTD_UNREACHABLE</CODE>, <CODE>RTD_PROHIBIT</CODE> for packets that should be
465: returned with ICMP host unreachable / ICMP administratively prohibited
466: messages). Can be changed, but only to <CODE>RTD_BLACKHOLE</CODE>,
467: <CODE>RTD_UNREACHABLE</CODE> or <CODE>RTD_PROHIBIT</CODE>.
468: <P>
469: <DT><CODE>
470: <A NAME="rta-ifname"></A> <I>string</I> ifname</CODE><DD><P>Name of the outgoing interface. Sink routes (like blackhole, unreachable
471: or prohibit) and multipath routes have no interface associated with
1.1.1.2 ! misho 472: them, so <CODE>ifname</CODE> returns an empty string for such routes. Setting it
! 473: would also change route to a direct one (remove gateway).
1.1 misho 474: <P>
475: <DT><CODE>
476: <A NAME="rta-ifindex"></A> <I>int</I> ifindex</CODE><DD><P>Index of the outgoing interface. System wide index of the interface. May
477: be used for interface matching, however indexes might change on interface
478: creation/removal. Zero is returned for routes with undefined outgoing
479: interfaces. Read-only.
480: <P>
481: <DT><CODE>
482: <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
483: network for routes that do not have a native protocol metric attribute
484: (like <CODE>ospf_metric1</CODE> for OSPF routes). It is used mainly by BGP to
485: compare internal distances to boundary routers (see below). It is also
486: used when the route is exported to OSPF as a default value for OSPF type
487: 1 metric.
488: </DL>
489: <P>
490: <P>There also exist some protocol-specific attributes which are described in the
491: corresponding protocol sections.
492: <P>
493: <P>
494: <H2><A NAME="other-statements"></A> <A NAME="ss5.6">5.6</A> <A HREF="bird.html#toc5.6">Other statements</A>
495: </H2>
496:
497: <P>The following statements are available:
498: <P>
499: <DL>
500: <DT><CODE>
501: <A NAME="assignment"></A> <I>variable</I> = <I>expr</I></CODE><DD><P>Set variable to a given value.
502: <P>
503: <DT><CODE>
504: <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>.
505: <P>
506: <DT><CODE>
507: <A NAME="return"></A> return <I>expr</I></CODE><DD><P>Return <CODE><I>expr</I></CODE> from the current function, the function ends
508: at this point.
509: <P>
510: <DT><CODE>
511: <A NAME="print"></A> print|printn <I>expr</I> [<I>, expr...</I>]</CODE><DD><P>Prints given expressions; useful mainly while debugging filters. The
512: <CODE>printn</CODE> variant does not terminate the line.
513: <P>
514: <DT><CODE>
515: <A NAME="quitbird"></A> quitbird</CODE><DD><P>Terminates BIRD. Useful when debugging the filter interpreter.
516: </DL>
517: <P>
518: <P>
519: <HR>
520: <A HREF="bird-6.html">Next</A>
521: <A HREF="bird-4.html">Previous</A>
522: <A HREF="bird.html#toc5">Contents</A>
523: </BODY>
524: </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