~brightbox/bird/debian-packaging

is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf>

947

on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP

948

address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.

949

950

<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as

951

<cf><M>ipaddress</M>/<M>pxlen</M></cf>, or

928

<tag/bool/ This is a boolean type, it can have only two values,

929

<cf/true/ and <cf/false/. Boolean is the only type you can use in

930

<cf/if/ statements.

931

932

<tag/int/ This is a general integer type. It is an unsigned 32bit type;

933

i.e., you can expect it to store values from 0 to 4294967295.

934

Overflows are not checked. You can use <cf/0x1234/ syntax to write

935

hexadecimal values.

936

937

<tag/pair/ This is a pair of two short integers. Each component can have

938

values from 0 to 65535. Literals of this type are written as

939

<cf/(1234,5678)/. The same syntax can also be used to construct a pair

940

from two arbitrary integer expressions (for example <cf/(1+2,a)/).

941

942

<tag/quad/ This is a dotted quad of numbers used to represent router IDs

943

(and others). Each component can have a value from 0 to 255. Literals

944

of this type are written like IPv4 addresses.

945

946

<tag/string/ This is a string of characters. There are no ways to modify

947

strings in filters. You can pass them between functions, assign them

948

to variables of type <cf/string/, print such variables, use standard

949

string comparison operations (e.g. <cf/=, !=, <, >, <=,

950

>=/), but you can't concatenate two strings. String literals are

951

written as <cf/"This is a string constant"/. Additionaly matching

952

<cf/&tilde;/ operator could be used to match a string value against a

953

shell pattern (represented also as a string).

954

955

<tag/ip/ This type can hold a single IP address. Depending on the

956

compile-time configuration of BIRD you are using, it is either an IPv4

957

or IPv6 address. IP addresses are written in the standard notation

958

(<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special

959

operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out

960

all but first <cf><M>num</M></cf> bits from the IP address. So

961

<cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.

962

963

<tag/prefix/ This type can hold a network prefix consisting of IP

964

address and prefix length. Prefix literals are written

965

as <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or

952

966

<cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special

953

operators on prefixes:

954

<cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix

955

length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.

967

operators on prefixes: <cf/.ip/ which extracts the IP address from the

968

pair, and <cf/.len/, which separates prefix length from the

969

pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.

956

970

957

<tag/ec/ This is a specialized type used to represent BGP

958

extended community values. It is essentially a 64bit value,

959

literals of this type are usually written as <cf>(<m/kind/,

960

<m/key/, <m/value/)</cf>, where <cf/kind/ is a kind of

961

extended community (e.g. <cf/rt/ / <cf/ro/ for a route

962

target / route origin communities), the format and possible

963

values of <cf/key/ and <cf/value/ are usually integers, but

971

<tag/ec/ This is a specialized type used to represent BGP extended

972

community values. It is essentially a 64bit value, literals of this

973

type are usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>,

974

where <cf/kind/ is a kind of extended community (e.g. <cf/rt/ /

975

<cf/ro/ for a route target / route origin communities), the format and

976

possible values of <cf/key/ and <cf/value/ are usually integers, but

964

977

it depends on the used kind. Similarly to pairs, ECs can be

965

constructed using expressions for <cf/key/ and

966

<cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where

967

<cf/myas/ is an integer variable).

978

constructed using expressions for <cf/key/ and <cf/value/ parts,

979

(e.g. <cf/(ro, myas, 3*10)/, where <cf/myas/ is an integer variable).

968

980

969

970

Filters recognize four types of sets. Sets are similar to strings: you can pass them around

971

but you can't modify them. Literals of type <cf>int set</cf> look like <cf>

972

[ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in

973

sets.

981

982

of sets. Sets are similar to strings: you can pass them around but you

983

can't modify them. Literals of type <cf>int set</cf> look like <cf> [

984

1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are

985

permitted in sets.

974

986

975

987

For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in

976

988

that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range

1267

1279

1268

1280

<chapt>Protocols

1269

1281

1282

<sect><label id="sect-bfd">BFD

1283

1284

<sect1>Introduction

1285

1286

Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it

1287

is an independent tool providing liveness and failure detection. Routing

1288

protocols like OSPF and BGP use integrated periodic "hello" messages to monitor

1289

liveness of neighbors, but detection times of these mechanisms are high (e.g. 40

1290

seconds by default in OSPF, could be set down to several seconds). BFD offers

1291

universal, fast and low-overhead mechanism for failure detection, which could be

1292

attached to any routing protocol in an advisory role.

1293

1294

BFD consists of mostly independent BFD sessions. Each session monitors an

1295

unicast bidirectional path between two BFD-enabled routers. This is done by

1296

periodically sending control packets in both directions. BFD does not handle

1297

neighbor discovery, BFD sessions are created on demand by request of other

1298

protocols (like OSPF or BGP), which supply appropriate information like IP

1299

addresses and associated interfaces. When a session changes its state, these

1300

protocols are notified and act accordingly (e.g. break an OSPF adjacency when

1301

the BFD session went down).

1302

1303

BIRD implements basic BFD behavior as defined in

1304

RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt">

1305

(some advanced features like the echo mode or authentication are not implemented),

1306

IP transport for BFD as defined in

1307

RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and

1308

RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt">

1309

and interaction with client protocols as defined in

1310

RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">.

1311

1312

Note that BFD implementation in BIRD is currently a new feature in

1313

development, expect some rough edges and possible UI and configuration changes

1314

in the future. Also note that we currently support at most one protocol instance.

1315

1316

<sect1>Configuration

1317

1318

BFD configuration consists mainly of multiple definitions of interfaces.

1319

Most BFD config options are session specific. When a new session is requested

1320

and dynamically created, it is configured from one of these definitions. For

1321

sessions to directly connected neighbors, <cf/interface/ definitions are chosen

1322

based on the interface associated with the session, while <cf/multihop/

1323

definition is used for multihop sessions. If no definition is relevant, the

1324

session is just created with the default configuration. Therefore, an empty BFD

1325

configuration is often sufficient.

1326

1327

Note that to use BFD for other protocols like OSPF or BGP, these protocols

1328

also have to be configured to request BFD sessions, usually by <cf/bfd/ option.

1329

1330

Some of BFD session options require <m/time/ value, which has to be specified

1331

with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds

1332

are allowed as units, practical minimum values are usually in order of tens of

1333

milliseconds.

1334

1335

<code>

1336

protocol bfd [<name>] {

1337

interface <interface pattern> {

1338

interval <time>;

1339

min rx interval <time>;

1340

min tx interval <time>;

1341

idle tx interval <time>;

1342

multiplier <num>;

1343

passive <switch>;

1344

};

1345

multihop {

1346

interval <time>;

1347

min rx interval <time>;

1348

min tx interval <time>;

1349

idle tx interval <time>;

1350

multiplier <num>;

1351

passive <switch>;

1352

};

1353

neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];

1354

}

1355

</code>

1356

1357

1358

<tag>interface <m/pattern [, ...]/ { <m/options/ }</tag>

1359

Interface definitions allow to specify options for sessions associated

1360

with such interfaces and also may contain interface specific options.

1361

See <ref id="dsc-iface" name="interface"> common option for a detailed

1362

description of interface patterns. Note that contrary to the behavior of

1363

<cf/interface/ definitions of other protocols, BFD protocol would accept

1364

sessions (in default configuration) even on interfaces not covered by

1365

such definitions.

1366

1367

<tag>multihop { <m/options/ }</tag>

1368

Multihop definitions allow to specify options for multihop BFD sessions,

1369

in the same manner as <cf/interface/ definitions are used for directly

1370

connected sessions. Currently only one such definition (for all multihop

1371

sessions) could be used.

1372

1373

<tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>

1374

BFD sessions are usually created on demand as requested by other

1375

protocols (like OSPF or BGP). This option allows to explicitly add

1376

a BFD session to the specified neighbor regardless of such requests.

1377

1378

The session is identified by the IP address of the neighbor, with

1379

optional specification of used interface and local IP. By default

1380

the neighbor must be directly connected, unless the the session is

1381

configured as multihop. Note that local IP must be specified for

1382

multihop sessions.

1383

</descrip>

1384

1385

Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):

1386

1387

1388

<tag>interval <m/time/</tag>

1389

BFD ensures availability of the forwarding path associated with the

1390

session by periodically sending BFD control packets in both

1391

directions. The rate of such packets is controlled by two options,

1392

<cf/min rx interval/ and <cf/min tx interval/ (see below). This option

1393

is just a shorthand to set both of these options together.

1394

1395

<tag>min rx interval <m/time/</tag>

1396

This option specifies the minimum RX interval, which is announced to the

1397

neighbor and used there to limit the neighbor's rate of generated BFD

1398

control packets. Default: 10 ms.

1399

1400

<tag>min tx interval <m/time/</tag>

1401

This option specifies the desired TX interval, which controls the rate

1402

of generated BFD control packets (together with <cf/min rx interval/

1403

announced by the neighbor). Note that this value is used only if the BFD

1404

session is up, otherwise the value of <cf/idle tx interval/ is used

1405

instead. Default: 100 ms.

1406

1407

<tag>idle tx interval <m/time/</tag>

1408

In order to limit unnecessary traffic in cases where a neighbor is not

1409

available or not running BFD, the rate of generated BFD control packets

1410

is lower when the BFD session is not up. This option specifies the

1411

desired TX interval in such cases instead of <cf/min tx interval/.

1412

Default: 1 s.

1413

1414

<tag>multiplier <m/num/</tag>

1415

Failure detection time for BFD sessions is based on established rate of

1416

BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this

1417

multiplier, which is essentially (ignoring jitter) a number of missed

1418

packets after which the session is declared down. Note that rates and

1419

multipliers could be different in each direction of a BFD session.

1420

Default: 5.

1421

1422

<tag>passive <m/switch/</tag>

1423

Generally, both BFD session endpoinds try to establish the session by

1424

sending control packets to the other side. This option allows to enable

1425

passive mode, which means that the router does not send BFD packets

1426

until it has received one from the other side. Default: disabled.

1427

</descrip>

1428

1429

<sect1>Example

1430

1431

<code>

1432

protocol bfd {

1433

interface "eth*" {

1434

min rx interval 20 ms;

1435

min tx interval 50 ms;

1436

idle tx interval 300 ms;

1437

};

1438

interface "gre*" {

1439

interval 200 ms;

1440

multiplier 10;

1441

passive;

1442

};

1443

multihop {

1444

interval 200 ms;

1445

multiplier 10;

1446

};

1447

1448

neighbor 192.168.1.10;

1449

neighbor 192.168.2.2 dev "eth2";

1450

neighbor 192.168.10.1 local 192.168.1.1 multihop;

1451

}

1452

</code>

1453

1270

1454

<sect>BGP

1271

1455

1272

1456

The Border Gateway Protocol is the routing protocol used for backbone

1281

1465

common routing policy. It is identified by a unique 16-bit number

1282

1466

(ASN). Routers within each AS usually exchange AS-internal routing

1283

1467

information with each other using an interior gateway protocol (IGP,

1284

such as OSPF or RIP). Boundary routers at the border of

1285

the AS communicate global (inter-AS) network reachability information with

1468

such as OSPF or RIP). Boundary routers at the border of the AS

1469

communicate global (inter-AS) network reachability information with

1286

1470

their neighbors in the neighboring AS'es via exterior BGP (eBGP) and

1287

1471

redistribute received information to other routers in the AS via

1288

1472

interior BGP (iBGP).

1356

1540

for each neighbor using the following configuration parameters:

1357

1541

1358

1542

1359

<tag>local [<m/ip/] as <m/number/</tag> Define which AS we

1360

are part of. (Note that contrary to other IP routers, BIRD is

1361

able to act as a router located in multiple AS'es

1362

simultaneously, but in such cases you need to tweak the BGP

1363

paths manually in the filters to get consistent behavior.)

1364

Optional <cf/ip/ argument specifies a source address,

1365

equivalent to the <cf/source address/ option (see below).

1543

<tag>local [<m/ip/] as <m/number/</tag> Define which AS we are part

1544

of. (Note that contrary to other IP routers, BIRD is able to act as a

1545

router located in multiple AS'es simultaneously, but in such cases you

1546

need to tweak the BGP paths manually in the filters to get consistent

1547

behavior.) Optional <cf/ip/ argument specifies a source address,

1548

equivalent to the <cf/source address/ option (see below). This

1549

parameter is mandatory.

1550

1551

<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router this

1552

instance will be talking to and what AS it's located in. In case the

1553

neighbor is in the same AS as we are, we automatically switch to iBGP.

1366

1554

This parameter is mandatory.

1367

1555

1368

<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router

1369

this instance will be talking to and what AS it's located in. Unless

1370

you use the <cf/multihop/ clause, it must be directly connected to one

1371

of your router's interfaces. In case the neighbor is in the same AS

1372

as we are, we automatically switch to iBGP. This parameter is mandatory.

1556

<tag>direct</tag> Specify that the neighbor is directly connected. The

1557

IP address of the neighbor must be from a directly reachable IP range

1558

(i.e. associated with one of your router's interfaces), otherwise the

1559

BGP session wouldn't start but it would wait for such interface to

1560

appear. The alternative is the <cf/multihop/ option. Default: enabled

1561

for eBGP.

1373

1562

1374

<tag>multihop [<m/number/]</tag> Configure multihop BGP

1375

session to a neighbor that isn't directly connected.

1376

Accurately, this option should be used if the configured

1377

neighbor IP address does not match with any local network

1378

subnets. Such IP address have to be reachable through system

1379

routing table. For multihop BGP it is recommended to

1380

explicitly configure <cf/source address/ to have it

1381

stable. Optional <cf/number/ argument can be used to specify

1382

the number of hops (used for TTL). Note that the number of

1383

networks (edges) in a path is counted, i.e. if two BGP

1384

speakers are separated by one router, the number of hops is

1385

2. Default: switched off.

1563

<tag>multihop [<m/number/]</tag> Configure multihop BGP session to a

1564

neighbor that isn't directly connected. Accurately, this option should

1565

be used if the configured neighbor IP address does not match with any

1566

local network subnets. Such IP address have to be reachable through

1567

system routing table. The alternative is the <cf/direct/ option. For

1568

multihop BGP it is recommended to explicitly configure the source

1569

address to have it stable. Optional <cf/number/ argument can be used to

1570

specify the number of hops (used for TTL). Note that the number of

1571

networks (edges) in a path is counted; i.e., if two BGP speakers are

1572

separated by one router, the number of hops is 2. Default: enabled for

1573

iBGP.

1386

1574

1387

1575

<tag>source address <m/ip/</tag> Define local address we

1388

1576

should use for next hop calculation and as a source address

1429

1617

table, and was used in older versions of BIRD, but does not

1430

1618

handle well nontrivial iBGP setups and multihop. Recursive

1431

1619

mode is incompatible with <ref id="dsc-sorted" name="sorted

1432

tables">. Default: <cf/direct/ for singlehop eBGP,

1433

<cf/recursive/ otherwise.

1620

tables">. Default: <cf/direct/ for direct sessions,

1621

<cf/recursive/ for multihop sessions.

1434

1622

1435

1623

<tag>igp table <m/name/</tag> Specifies a table that is used

1436

1624

as an IGP routing table. Default: the same as the table BGP is

1437

1625

connected to.

1438

1626

1627

<tag>bfd <M>switch</M></tag>

1628

BGP could use BFD protocol as an advisory mechanism for neighbor

1629

liveness and failure detection. If enabled, BIRD setups a BFD session

1630

for the BGP neighbor and tracks its liveness by it. This has an

1631

advantage of an order of magnitude lower detection times in case of

1632

failure. Note that BFD protocol also has to be configured, see

1633

<ref id="sect-bfd" name="BFD"> section for details. Default: disabled.

1634

1439

1635

<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the

1440

1636

generalized TTL security mechanism). GTSM protects against

1441

1637

spoofed packets by ignoring received packets with a smaller

1486

1682

This option requires that the connected routing table is

1487

1683

<ref id="dsc-sorted" name="sorted">. Default: off.

1488

1684

1685

<tag>allow local as [<m/number/]</tag>

1686

BGP prevents routing loops by rejecting received routes with

1687

the local AS number in the AS path. This option allows to

1688

loose or disable the check. Optional <cf/number/ argument can

1689

be used to specify the maximum number of local ASNs in the AS

1690

path that is allowed for received routes. When the option is

1691

used without the argument, the check is completely disabled

1692

and you should ensure loop-free behavior by some other means.

1693

Default: 0 (no local AS number allowed).

1694

1489

1695

<tag>enable route refresh <m/switch/</tag> When BGP speaker

1490

1696

changes its import filter, it has to re-examine all routes

1491

1697

received from its neighbor against the new filter. As these

2010

2216

real broadcast <switch>;

2011

2217

ptp netmask <switch>;

2012

2218

check link <switch>;

2219

bfd <switch>;

2013

2220

ecmp weight <num>;

2014

2221

ttl security [<switch>; | tx only]

2015

2222

tx class|dscp <num>;

2284

2491

prefix) is propagated. It is possible that some hardware

2285

2492

drivers or platforms do not implement this feature. Default value is no.

2286

2493

2494

<tag>bfd <M>switch</M></tag>

2495

OSPF could use BFD protocol as an advisory mechanism for neighbor

2496

liveness and failure detection. If enabled, BIRD setups a BFD session

2497

for each OSPF neighbor and tracks its liveness by it. This has an

2498

advantage of an order of magnitude lower detection times in case of

2499

failure. Note that BFD protocol also has to be configured, see

2500

<ref id="sect-bfd" name="BFD"> section for details. Default value is no.

2501

2287

2502

<tag>ttl security [<m/switch/ | tx only]</tag>

2288

2503

TTL security is a feature that protects routing protocols

2289

2504

from remote spoofed packets by using TTL 255 instead of TTL 1

Older »