Files Reference

gated.conf File Format for TCP/IP

Purpose

Contains configuration information for the gated daemon.

Description

The /etc/gated.conf file contains configuration information for the gated daemon. The file contains a sequence of statements. Statements are composed of tokens separated by white space. You can create white space using any combination of blanks, tabs, and new lines. The gated.conf file supports several statements:

Directive Statements

Directive statements provide direction to the gated.conf configuration language parser about included files and the directories in which these files reside. Directive statements are immediately acted upon by the parser. Other statements terminate with a semi-colon (;), but directive statements terminate with a newline. The two directive statements are:

In a complex environment, segmenting a large configuration into smaller more easily understood segments might be helpful, but one of the great advantages of gated.conf is that it combines the configuration of several different routing protocols into a single file. Segmenting a small file unnecessarily complicates routing configurations.

Trace Statements

Trace statements control tracing options. gated.conf's tracing options may be configured at many levels. Tracing options include the file specifications, control options, and global and protocol specific tracing options. Unless overridden, tracing options from the next higher level are inherited by lower levels. For example, BGP peer tracing options are inherited from BGP group tracing options, which are inherited from global BGP tracing options, which are inherited from global gated.conf tracing options. At each level, tracing specifications override the inherited options.

Global tracing options

There are two types of global options, those that only affect global operations, and those that have potential significance to protocols.

Global significance only

The trace flags that only have global significance are:

Protocol significance

The options flags that have potential significance to protocols are:

1. Not all of the above options apply to all of the protocols. In some cases, their use does not make sense (for instance, RIP does not have a state machine) and in some instances the requested tracing has not been implemented (such as RIP support of the policy option).
2. It is not currently possible to specify packet tracing from the command line. This is because a global option for packet tracing would potentially create too much output.

When protocols inherit their tracing options from the global tracing options, tracing levels that don't make sense (such as parse, adv and packet tracing options) are masked out.

Global tracing statements have an immediate effect, especially parsing options that affect the parsing of the configuration file. Tracing values inherited by protocols specified in the configuration file are initially inherited from the global options in effect as they are parsed, unless they are overridden by more specific options. After the configuration file is read, tracing options that were not explicitly specified are inherited from the global options in effect at the end of the configuration file.

Packet tracing

Tracing of packets is very flexible. For any given protocol, there are one or more options for tracing packets. All protocols allow use of the packets keyword that allows for tracing all packets sent and received by the protocol. Most protocols have other options for limiting tracing to a useful subset of packet types. These tracing options can be further controlled with the following modifiers:

detail

The detail must be specified before send or recv. Normally packets are traced in a terse form of one or two lines. When detail is specified, a more verbose format is used to provide further detail on the contents of the packet.

send

recv

These options limit the tracing to packets sent or received. Without these options both sent and received packets will be traced.

Traceoptions syntax

traceoptions ["trace_file" [replace] [size size[k|m] files files]]
        [control_options] trace_options [except trace_options] ;

    traceoptions none ;

Options Statements

Options statements allow specification of some global options. If used, options must appear before any other type of configuration statement in the gated.conf file.

The options statement syntax is:

The options list can contain one or more of the following options:

Interface Statement

Interface Syntax

interfaces {
options
[ strictinterfaces ]
[ scaninterval time ]
;
interface interface_list
[ preference preference ]
[ down preference preference ]
[ passive ]
[ simplex ]
[ reject ]
[ blackhole ]
;
define address
[ broadcast address ] | [ pointtopoint address ]
[ netmask mask ]
[ multicast ]
;
} ;

An interface is the connection between a router and one of its attached networks. A physical interface may be specified by interface name, by IP address, or by domain name, (unless the network is an unnumbered point-to-point network.) Multiple levels of reference in the configuration language allow identification of interfaces using wildcard, interface type name, or delete word addresses. The interface_list is a list of one or more interface names including wildcard names (names without a number) and names that may specify more than one interface or address, or the token all for all interfaces.

Interface Lists

An interface list is a list of references to interfaces or groups of interfaces. There are four methods available for referring to interfaces. They are listed here from most general to most specific.

If many interface lists are present in the config file with more than one parameter, these parameters are collected at run-time to create the specific parameter list for a given interface. If the same parameter is specified on more than one list, the parameter with the most specific interface is used.

For example, consider a system with three interfaces: en0, en1, and tr0.

    rip yes {
        interface all noripin noripout;
	interface en ripin;
	interface en1 ripout;
    } ;

RIP packets would only be accepted from interfaces en0 and en1, but not from tr0. RIP packets would only be sent on interface en1.

IP Interface Addresses and Routes

The gated daemon insures that there is a route available to each IP interface that is configured and up. Normally this is done by the ifconfig command that configures the interface; the gated daemon does it to insure consistency.

For point-to-point interfaces, the gated daemon installs some special routes. If the local address on one or more point-to-point interfaces is not shared with a non-point-to-point interface, the gated daemon installs a route to the local address pointing at the loopback interface with a preference of 110. This insures that packets originating on this host destined for this local address are handled locally. OSPF prefers to route packets for the local interface across the point-to-point link where they will be returned by the router on the remote end. This is used to verify operation of the link. Since OSPF installs routes with a preference of 10, these routes will override the route installed with a preference of 110.

If the local address of one or more point-to-point interfaces is shared with a non-point-to-point interface, the gated daemon installs a route to the local with a preference of 0 that will not be installed in the forwarding table. This is to prevent protocols like OSPF from routing packets to this address across a serial interface when this system could be functioning as a host.

When the status of an interface changes, the gated daemon notifies all the protocols, which take the appropriate action. The gated daemon assumes that interfaces that are not marked UP do not exist.

The gated daemon ignores any interfaces that have invalid data for the local, remote, or broadcast addresses or the subnet mask. Invalid data includes zeros in any field. The gated daemon will also ignore any point-to-point interface that has the same local and remote addresses.

Definition Statements

Definition statements are general configuration statements that relate to all of gated daemon or at least to more than one protocol. The three definition statements are autonomoussystem, routerid, and martians. If used, autonomoussystem, routerid, and martians must appear before any other type of configuration statement in the gated daemon file.

Autonomous System Configuration

autonomoussystem autonomous_system [loops number] ;

Sets the autonomous system number of this router to be autonomous system. This option is required if BGP or EGP are in use. The AS number is assigned by the Network Information Center (NIC).

Loops is only for protocols supporting AS paths, such as BGP. It controls the number of times this autonomous system may appear in an AS path and defaults to 1 (one).

Router ID Configuration

routerid host ;

Sets the router identifier for use by the BGP and OSPF protocols. The default is the address of the first interface encountered by the gated daemon. The address of a non-point-to-point interface is preferred over the local address of a point-to-point interface and an address on a loopback interface that is not the loopback address (127.0.0.1) is most preferred.

Martian Configuration

    martians {
        host host [allow] ;
	network [allow] ;
	network mask mask [allow] ;
	network masklen number [allow] ;
        default [allow] ;
    } ; 

Defines a list of martian addresses about which all routing information is ignored. Sometimes a misconfigured system sends out obviously invalid destination addresses. These invalid addresses, called martians, are rejected by the routing software. This command allows additions to the list of martian addresses. See the section on Route Filtering for more information on specifying ranges. Also, the allow parameter may be specified to explicitly allow a subset of a range that was disallowed.

Sample Definition Statements

    options gendefault ;
    autonomoussystem 249 ;
    interface 128.66.12.2 passive ;
    martians {
        0.0.0.26
    };

The statements in the sample perform the following functions:

• The options statement tells the system to generate a default route when it peers with an EGP or BGP neighbor.
• The autonomoussystem statement tells the gated daemon to use the AS number 249 for EGP and BGP.
• The interface statement tells the gated daemon not to mark interface 128.66.12.2 as down even if it sees no traffic.
• The martians statement prevents routes to 0.0.0.26 from ever being accepted.

The RIP Statement

rip yes | no | on | off [{
broadcast ;
nobroadcast ;
nocheckzero ;
preference preference ;
defaultmetric metric ;
query authentication [none | [[simple|md5] password]] ;
interface interface_list
[noripin] | [ripin]
[noripout] | [ripout]
[metricin metric]
[metricout metric]
[version 1]|[version 2 [multicast|broadcast]]
[[secondary] authentication [none | [[simple|md5] password]] ;
trustedgateways gateway_list ;
sourcegateways gateway_list ;
traceoptions trace_options ;
} ] ;

The rip statement enables or disables RIP. If the rip statement is not specified, the default is rip on ;. If enabled, RIP will assume nobroadcast when there is only one interface and broadcast when there is more than one.

The options are as follows:

broadcast

Specifies that RIP packets will be broadcast regardless of the number of interfaces present. This is useful when propagating static routes or routes learned from another protocol into RIP. In some cases, the use of broadcast when only one network interface is present can cause data packets to traverse a single network twice.

nobroadcast

Specifies that RIP packets will not be broadcast on attached interfaces, even if there is more than one. If a sourcegateways clause is present, routes will still be unicast directly to that gateway.

nocheckzero

Specifies that RIP should not make sure that reserved fields in incoming version 1 RIP packets are zero. Normally RIP will reject packets where the reserved fields are zero.

preference preference

Sets the preference for routes learned from RIP. The default preference is 100. This preference may be overridden by a preference specified in import policy.

defaultmetric metric

Defines the metric used when advertising routes via RIP were learned from other protocols. If not specified, the default value is 16 (unreachable). This choice of values requires you to explicitly specify a metric in order to export routes from other protocols into RIP. This metric may be overridden by a metric specified in export policy.

query authentication [none | [[simple|md5] password]] ;

Specifies the authentication required of query packets that do not originate from routers. The default is none.

interface interface_list

Controls various attributes of sending RIP on specific interfaces. See the section on interface list specification for a description of the interface_list.

Note

If there are multiple interfaces configured on the same subnet, RIP updates will only be sent from the first one from which RIP output is configured.

The possible parameters are:

noripin

Specifies that RIP packets received via the specified interface will be ignored. The default is to listen to RIP packets on all non-loopback interfaces.

ripin

This is the default. This argument may be necessary when noripin is used on a wildcard interface descriptor.

noripout

Specifies that no RIP packets will be sent on the specified interfaces. The default is to send RIP on all broadcast and non-broadcast interfaces when in broadcast mode. The sending of RIP on point-to-point interfaces must be manually configured.

ripout

This is the default. This argument is necessary when it is desired to send RIP on point-to-point interfaces and may be necessary when noripin is used on a wildcard interface descriptor.

metricin metric

Specifies the RIP metric to add to incoming routes before they are installed in the routing table. The default is the kernel interface metric plus 1 (which is the default RIP hop count). If this value is specified it will be used as the absolute value, the kernel metric will not be added. This option is used to make this router prefer RIP routes learned via the specified interface(s) less than RIP routes from other interfaces.

metricout metric

Specifies the RIP metric to be added to routes that are sent via the specified interface(s). The default is zero. This option is used to make other routers prefer other sources of RIP routes over this router.

version 1

Specifies that RIP packets sent via the specified interface(s) will be version 1 packets. This is the default.

version 2

Specifies that RIP version 2 packets will be sent on the specified interfaces(s). If IP multicast support is available on this interface, the default is to send full version 2 packets. If it is not available, version 1 compatible version 2 packets will be sent.

multicast

Specifies that RIP version 2 packets should be multicast on this interface. This is the default.

broadcast

Specifies that RIP version 1 compatible version 2 packets should be broadcast on this interface, even if IP multicast is available.

[secondary] authentication [none | [simple|md5] password]

This defines the authentication type to use. It applies only to RIP version 2 and is ignored for RIP-1 packets. The default authentication type is none. If a password is specified, the authentication type defaults to simple. The password should be a quoted string with between 0 and 16 characters.

If secondary is specified, this defines the secondary authentication. If omitted, the primary authentication is specified. The default is primary authentication of none and no secondary authentication.

trustedgateways gateway_list

Defines the list of gateways from which RIP will accept updates. The gateway_list is simply a list of host names or IP addresses. By default, all routers on the shared network are trusted to supply routing information. But if the trustedgateways clause is specified, only updates from the gateways in the list are accepted.

sourcegateways gateway_list

Defines a list of routers to which RIP sends packets directly, not through multicast or broadcast. This can be used to send different routing information to specific gateways. Updates to gateways in this list are not affected by noripout on the interface.

traceoptions trace_options

Specifies the tracing options for RIP. (See Trace Statements and the RIP specific tracing options below.)

Tracing options

The policy option logs info whenever a new route is announced, the metric being announced changes, or a route goes or leaves holddown.

Packet tracing options (which may be modified with detail, send, or recv):

The RIPNG Statement

Enables or disables ripng. If the ripng statement is not specified, the default is ripng on ;. The options are the same as for rip, but all the addresses will be IPv6 addresses.

The syntax is:

     ripng yes | no | on | off [ {
        broadcast ;
        nobroadcast ;
        nocheckzero ;
        preference <preference> ;
        defaultmetric <metric> ;
        query authentication [none | [[simple|md5] <password>]] ;
        interface <interface_list>
            [noripin] | [ripin]
            [noripout] | [ripout]
            [metricin <metric>]
            [metricout <metric>]
            [version 1]|[version 2 [multicast|broadcast]]
            [[secondary] authentication [none | [[simple|md5] <password>]] ;
        trustedgateways <gaeway_list> ;
        sourcegateways <gaeway_list> ;
        traceoptions <trace_options> ;
     } ] ;

The Hello Statement

hello yes | no | on | off [{
broadcast ;
nobroadcast ;
preference preference ;
defaultmetric metric ;
interface interface_list
[nohelloin] | [helloin]
[nohelloout] | [helloout]
[metricin metric]
[metricout metric] ;
trustedgateways gateway_list ;
sourcegateways gateway_list ;
traceoptions trace_options ;
} ] ;

The hello statement enables or disables HELLO. If the hello statement is not specified, the default is hello off. If enabled, HELLO will assume nobroadcast when there is only one interface and broadcast when there is more than one interface.

Tracing options

The policy option logs info whenever a new route is announced, the metric being announced changes, or a route goes or leaves holddown.

Packet tracing options (which may be modified with detail, send, and/or recv):

The IS-IS Statement

    isis no | dual | ip | iso {
        level 1|2 ;
        [traceoptions <isis_traceoptions> ;]
        [systemid <6_digit_hexstring> ;]
        [area <hexstring> ;]
        [set <isis_parm> <value> ; ... ]
        circuit <string>
            metric [level 1|2] <1..63>
            ...
            priority [level 1|2] <0..127>
            ...
            ;
        ...
    } ;

This statement enables the IS-IS protocol in the gated daemon. By default, IS-IS is disabled. The dual option specifies that the IS-IS protocol is enabled for both ISO and IP addressing. The isis statement consists of an initial description of the IS and a list of statements that determine the configuration of the specific circuits and networks to be managed. Statements may appear in any order and include:

On a level 2 IS, to configure a circuit with a Level 1 metric of 10 and a Level 2 metric of 20, add two metric options to the circuit statement.

The default Level is 1: the default metric is 63. The default preference for IS-IS Level 1 is 15 for IS-IS Level 2 is 18.

Tracing options

Traceoptions can be one or more of the following:

all
iih
lanadj
p2padj
lspdb
lspcontent
lspinput
flooding
buildlsp
csnp
psnp
route
update
paths
spf
events

The OSPF Statement

ospf yes | no | on | off [{
defaults {
preference preference ;
cost cost ;
tag [as ] tag ;
type 1 | 2 ;
} ;
exportlimit routes ;
exportinterval time ;
traceoptions trace_options ;
monitorauthkey authkey ;
monitorauth none | ( [simple | md5 ] authkey ) ;
backbone | ( area area ) {
authtype 0 | 1 | none | simple ;
stub [cost cost] ;
networks {
network [restrict ] ;
network mask mask [restrict ] ;
network masklen number [restrict ] ;
host host [restrict ] ;
} ;
stubhosts {
host cost cost ;
} ;
interface interface_list; [cost cost ] {
interface_parameters
} ;
interface interface_list nonbroadcast [cost cost ] {
pollinterval time ;
routers {
gateway [eligible ] ;
} ;
interface_parameters
} ;
Backbone only:
virtuallink neighborid router_id transitarea area {
interface_parameters
} ;
};
} ];

The following are the interface_parameters referred to above. They may be specified on any class of interface and are described under the interface clause.

    enable | disable;
    retransmitinterval time;
    transitdelay time;
    priority priority;
    hellointerval time;
    routerdeadinterval time;
    authkey auth_key;

defaults

These parameters specify the defaults used when importing OSPF ASE routes into the gated routing table and exporting routes from the gated routing table into OSPF ASEs.

preference preference

Preference is used to determine how OSPF routes compete with routes from other protocols in the gated routing table. The default value is 150.

cost cost

Cost is used when exporting a non-OSPF route from the gated routing table into OSPF as an ASE. The default value is 1. This may be explicitly overridden in export policy.

tag [as ] tag

OSPF ASE routes have a 32 bit tag field that is not used by the OSPF protocol, but may be used by export policy to filter routes. When OSPF is interacting with an EGP, the tag field may be used to propagate AS path information, in which case the as keyword is specified and the tag is limited to 12 bits of information. If not specified, the tag is set to zero.

type 1 | 2

Routes exported from the gated routing table into OSPF default to becoming type 1 ASEs. This default may be explicitly changed here and overridden in export policy.

ASE export rate

Because of the nature of OSPF, the rate at which ASEs are flooded must be limited. These two parameters can be used to adjust those rate limits.

exportinterval time

This specifies how often a batch of ASE link state advertisements will be generated and flooded into OSPF. The default is once per second.

exportlimit routes

This parameter specifies how many ASEs will be generated and flooded in each batch. The default is 100.

traceoptions trace_options

Specifies the tracing options for OSPF. (See Trace Statements and the OSPF specific tracing options below.)

monitorauthkey authkey

OSPF state may be queried using the ospf_monitor command utility. This utility sends non-standard OSPF packets that generate a text response from OSPF. By default, these requests are not authenticated if an authentication key is configured, the incoming requests must match the specified authentication key. No OSPF state may be changed by these packets, but the act of querying OSPF can utilize system resources.

backbonearea area

Each OSPF router must be configured into at least one OSPF area. If more than one area is configured, at least one must be backbone. The backbone may only be configured using the backbone keyword, it may not be specified as area 0. The backbone interface may be a virtuallink.

authtype 0 | 1 | none | simple

OSPF specifies an authentication scheme per area. Each interface in the area must use this same authentication scheme although it may use a different authenticationkey. The currently valid values are none (0) for no authentication, or simple (1) for simple password authentication.

stub [cost cost]

A stub area is one in which there are no ASE routes. If a cost is specified, this is used to inject a default route into the area with the specified cost.

networks

The networks list describes the scope of an area. Intra-area LSAs that fall within the specified ranges are not advertised into other areas as inter-area routes. Instead, the specified ranges are advertised as summary network LSAs. If restrict is specified, the summary network LSAs are not advertised. Intra-area LSAs that do not fall into any range are also advertised as summary network LSAs. This option is very useful on well designed networks in reducing the amount of routing information propagated between areas. The entries in this list are either networks, or a subnetwork/mask pair. See the section on Route Filtering for more detail about specifying ranges.

stubhosts

This list specifies directly attached hosts that should be advertised as reachable from this router and the costs they should be advertised with. Point-to-point interfaces on which it is not desirable to run OSPF should be specified here.

It is also useful to assign an additional address to the loopback interface (one not on the 127 network) and advertise it as a stub hosts. If this address is the same one used as the router-id, it enables routing to OSPF routers by router-id, instead of by an interface address. This is more reliable than routing to one of the router's interface addresses that may not always be reachable.

interface interface_list [cost cost ]

This form of the interface clause is used to configure a broadcast (which requires IP multicast support) or a point-to-point interface. See the section on interface list specification for the description of the interface_list.

Each interface has a cost. The costs of all interfaces a packet must cross to reach a destination are summed to get the cost to that destination. The default cost is one, but another non-zero value may be specified.

Interface parameters common to all types of interfaces are:

retransmitinterval time

The number of seconds between link state advertisement retransmissions for adjacencies belonging to this interface.

transitdelay time

The estimated number of seconds required to transmit a link state update over this interface. Transitdelay takes into account transmission and propagation delays and must be greater than 0.

priority priority

A number between 0 and 255 specifying the priority for becoming the designated router on this interface. When two routers attached to a network both attempt to become the designated router, the one with the highest priority wins. A router whose router priority is set to 0 is ineligible to become the designated router.

hellointerval time

The length of time, in seconds, between Hello packets that the router sends on the interface.

routerdeadinterval time

The number of seconds not hearing a router's Hello packets before the router's neighbors will declare it down.

authkey auth_key

Used by OSPF authentication to generate and verify the authentication field in the OSPF header. The authentication key can be configured on a per interface basis. It is specified by one to eight decimal digits separated by periods, a one to eight byte hexadecimal string preceded by 0x, or a one to eight character string in double quotes.

Point-to-point interfaces also support this additional parameter:

nomulticast

By default, OSPF packets to neighbors on point-to-point interfaces are sent via the IP multicast mechanism. If the use of IP multicasting is not desired, the nomulticast parameter may be specified to force the use of unicast OSPF packets. gated.conf will detect this condition and fall back to using sending unicast OSPF packets to this point-to-point neighbor.

If the use of IP multicasting is not desired because the remote neighbor does not support it, the nomulticast parameter may be specified to force the use of unicast OSPF packets. This option may also be used to eliminate warnings when gated.conf detects the bug mentioned above.

interface interface_list nonbroadcast [cost cost ]

This form of the interface clause is used to specify a nonbroadcast interface on a non-broadcast multi-access (NBMA) media. Since an OSPF broadcast media must support IP multicasting, a broadcast-capable media, such as Ethernet, that does not support IP multicasting must be configured as a non-broadcast interface.

A non-broadcast interface supports any of the standard interface clauses listed above, plus the following two that are specific to non-broadcast interfaces:

pollinterval time

Before adjacency is established with a neighbor, OSPF packets are sent periodically at the specified pollinterval.

routers

By definition, it is not possible to send broadcast packets to discover OSPF neighbors on a non-broadcast, so all neighbors must be configured. The list includes one or more neighbors and an indication of their eligibility to become a designated router.

virtuallink neighborid router_id transitarea area

Virtual links are used to establish or increase connectivity of the backbone area. The neighborid is the router_id of the other end of the virtual link. The transit area specified must also be configured on this system. All standard interface parameters defined by the interface clause above may be specified on a virtual link.

Tracing options

In addition to the following OSPF specific trace flags, OSPF supports the state that traces interface and neighbor state machine transitions.

Packet tracing options (which may be modified with detail, send and recv):

The EGP Statement

EGP yes | no | on | off
[{
preference preference ;
defaultmetric metric ;
packetsize number ;
traceoptions trace_options ;
group
[peeras autonomous_system ]
[localas autonomous_system ]
[maxup number ]
{
neighbor host
[metricout metric ]
[preference preference ]
[preference2 preference ]
[ttl ttl ]
[nogendefault ]
[importdefault ]
[exportdefault ]
[gateway gateway ]
[lcladdr local_address ]
[sourcenet network ]
[minhello | p1 time ]
[minpoll | p2 time ]
[traceoptions trace_options ]
;
} ;
} ] ;

preference preference

Sets the preference for routes learned from RIP. The default preference is 200. This preference may be overridden by a preference specified on the group or neighbor statements or by import policy.

defaultmetric metric ;

Defines the metric used when advertising routes via EGP. If not specified, the default value is 255 that some systems may consider unreachable. This choice of values requires you to explicitly specify a metric when exporting routes to EGP neighbors. This metric may be overridden by a metric specified on the neighbor or group statements or in export policy.

packetsize maxpacketsize

This defines the expected maximum size of a packet that EGP expects to receive from this neighbor. If a packet larger than this value is received, it will be incomplete and have to be discarded. The length of this packet will be noted and the expected size will be increased to be able to receive a packet of this size. Specifying the parameter here will prevent the first packet from being dropped. If not specified, the default size is 8192 bytes. All packet sizes are rounded up to a multiple of the system page size.

traceoptions trace_options

Specifies the tracing options for EGP. By default these are inherited from the global trace options. These values may be overridden on a group or neighbor basis. (See Trace Statements and the EGP specific tracing options below.)

group

EGP neighbors must be specified as members of a group. A group is usually used to group all neighbors in one autonomous system. Parameters specified on the group clause apply to all of the subsidiary neighbors unless explicitly overridden on a neighbor clause. Any number of group clauses may specify any number of neighbor clauses.

Any parameters from the neighbor subclause may be specified on the group clause to provide defaults for the whole group (which may be overridden for individual neighbors). In addition, the group clause is the only place to set the following attributes:

peeras

Identifies the autonomous system number expected from peers in the group. If not specified, it will be learned dynamically.

localas

Identifies the autonomous system that gated.conf is representing to the group. The default is that which has been set globally in the autonomoussystem statement. This option is usually only used when masquerading as another autonomous system and its use is discouraged.

maxup

Specifies the number of neighbors the gated daemon should acquire from this group. The default is to acquire all of the neighbors in the group. The gated daemon will attempt to acquire the first maxup neighbors in the order listed. If one of the first neighbors is not available, it will acquire one further down the list. If after start-up the gated daemon does manage to acquire the more desirable neighbor, it will drop the less desirable one.

neighbor neighbor_address

Each neighbor subclause defines one EGP neighbor within a group. The only part of the subclause that is required is the neighbor_address argument that is the symbolic host name or IP address of the neighbor. All other parameters are optional.

preference preference

Specifies the preference used for routes learned from these neighbors. This can differ from the default EGP preference set in the EGP statement, so that the gated daemon can prefer routes from one neighbor, or group of neighbors, over another. This preference may be explicitly overridden by import policy.

preference2 preference

In the case of a preference tie, the second preference, preference2 may be used to break the tie. The default value is 0.

metricout metric

This defines a metric to be used for all routes sent to this neighbor. The value overrides the default metric set in the EGP statement and any metrics specified by export policy, but only for this specific neighbor or group of neighbors.

nogendefault

Prevents gated.conf from generating a default route when EGP receives a valid update from its neighbor. The default route is only generated when the gendefault option is enabled.

importdefault

Enables the gated daemon to accept the default route (0.0.0.0) if it is included in a received EGP update. If not specified, the default route contained in an EGP update is ignored. For efficiency, some networks have external routers announce a default route to avoid sending large EGP update packets.

exportdefault

Enables the gated daemon to include the default route (0.0.0.0) in EGP updates sent to this EGP neighbor. This allows the system to advertise the default route via EGP. Normally a default route is not included in EGP updates.

gateway gateway

If a network is not shared with a neighbor, gateway specifies a router on an attached network to be used as the next hop router for routes received from this neighbor. This option is only rarely used.

lcladdr local_address

Specifies the address to be used on the local end of the connection with the neighbor. The local address must be on an interface that is shared with the neighbor or with the neighbor's gateway when the gateway parameter is used. A session will only be opened when an interface with the appropriate local address (through which the neighbor or gateway address is directly reachable) is operating.

sourcenet network

Specifies the network queried in the EGP Poll packets. By default, this is the network shared with the neighbor's address specified. If there is no network shared with the neighbor, one of the networks the neighbor is attached to should be specified. This parameter can also be used to specify a network shared with the neighbor other than the one on which the EGP packets are sent. This parameter is normally not needed.

p1 time

minhello time

Sets the minimum acceptable interval between the transmission of EGP HELLO packets. The default hello interval is 30 seconds. If the neighbor fails to respond to three hello packets, the gated daemon stops trying to acquire the neighbor. Setting a larger interval gives the neighbor a better chance to respond. Minhello is an alias for the P1 value defined in the EGP specification.

p2 time

minpoll time

Sets the time interval between polls to the neighbor. The default is 120 seconds. If three polls are sent without a response, the neighbor is declared "down" and all routes learned from that neighbor are removed from the routing database. A longer polling interval supports a more stable routing database but is not as responsive to routing changes. Minpoll is an alias for the P2 value defined in the EGP specification.

ttl ttl

By default, the gated daemon sets the IP TTL for local neighbors to one and the TTL for non-local neighbors to 255. This option is provided when attempting to communicate with improperly functioning routers that ignore packets sent with a TTL of one.

traceoptions trace_options

Specifies the tracing options for this EGP neighbor. By default, these are inherited from group or EGP global trace options. (See Trace Statements and the EGP specific tracing options below.)

Tracing options

The state and policy options work with EGP.

Packet tracing options (which may be modified with detail, send and recv):

The BGP Statement

bgp yes | no | on | off
[ {
preference preference ;
defaultmetric metric ;
traceoptions trace_options ;
group type ( external peeras autonomous_system )
| ( internal peeras autonomous_system )
| ( IGP peeras autonomous_system proto proto )
| ( routing peeras autonomous_system proto proto
interface interface_list )
| ( test peeras autonomous_system )
{
allow {
network
network mask mask
network masklen number
all
host host
} ;
peer host
[ metricout metric ]
[ localas autonomous_system ]
[ nogendefault]
[ gateway gateway ]
[ preference preference ]
[ preference2 preference ]
[ lcladdr local_address ]
[ holdtime time ]
[ version number ]
[ passive]
[ indelay time ]
[ outdelay time ]
[ keep [ all | none] ]
[ noaggregatorid]
[ keepalivesalways]
[ v3asloopokay]
[ nov4asloop]
[ logupdown]
[ ttl ttl ]
[ traceoptions trace_options ]
;
} ;
}] ;

external | internal | IGP | test

The bgp statement enables or disables BGP. By default, BGP is disabled. The default metric for announcing routes via BGP is not to send a metric.

Groups

BGP peers are grouped by type and the autonomous system of the peers. Any number of groups may be specified, but each must have a unique combination of type and peer autonomous system. There are four possible group types:

group type external peeras autonomous_system

In the classic external BGP group, full policy checking is applied to all incoming and outgoing advertisements. The external neighbors must be directly reachable through one of the machine's local interfaces. By default no metric is included in external advertisements, and the next hop is computed with respect to the shared interface.

group type internal peeras autonomous_system

An internal group operating where there is no IP-level IGP. All neighbors in this group are required to be directly reachable via a single interface. All next hop information is computed with respect to this interface. Import and export policy may be applied to group advertisements. Routes received from external BGP or EGP neighbors are by default readvertised with the received metric.

group type IGP peeras autonomous_system proto proto

An internal group that runs in association with an interior protocol. The IGP group examines routes that the IGP is exporting and sends an advertisement only if the path attributes could not be entirely represented in the IGP tag mechanism. Only the AS path, path origin, and transitive optional attributes are sent with routes. No metric is sent, and the next hop is set to the local address used by the connection. Received internal BGP routes are not used or readvertised. Instead, the AS path information is attached to the corresponding IGP route and the latter is used for readvertisement. Since internal IGP peers are sent only a subset of the routes that the IGP is exporting, the export policy used is the IGP's. There is no need to implement the "don't routes from peers in the same group" constraint since the advertised routes are routes that IGP already exports.

group type routing peeras autonomous_system proto proto interface interface_list

An internal group that uses the routes of an interior protocol to resolve forwarding addresses. A type routing group propagates external routes between routers that are not directly connected, and computes immediate next hops for these routes by using the BGP next hop that arrived with the route as a forwarding address to be resolved via an internal protocol's routing information. In essence, internal BGP is used to carry AS external routes, while the IGP is expected to only carry AS internal routes, and the latter is used to find immediate next hops for the former.

The proto names the interior protocol to be used to resolve BGP route next hops, and may be the name of any IGP in the configuration. By default, the next hop in BGP routes advertised to type routing peers will be set to the local address on the BGP connection to those peers, as it is assumed a route to this address will be propagated via the IGP. The interface_list can optionally provide list interfaces whose routes are carried via the IGP for which third party next hops may be used instead.

group type test peeras autonomous_system

An extension to external BGP that implements a fixed policy using test peers. Fixed policy and special case code make test peers relatively inexpensive to maintain. Test peers do not need to be on a directly attached network. If the gated daemon and the peer are on the same (directly attached) subnet, the advertised next hop is computed with respect to that network, otherwise the next hop is the local machine's current next hop. All routing information advertised by and received from a test peer is discarded, and all BGP advertisable routes are sent back to the test peer. Metrics from EGP- and BGP-derived routes are forwarded in the advertisement, otherwise no metric is included.

Group parameters

The BGP statement has group clauses and peer subclauses. Any number of peer subclauses may be specified within a group. A group clause usually defines default parameters for a group of peers, these parameters apply to all subsidiary peer subclauses. Any parameters from the peer subclause may be specified on the group clause to provide defaults for the whole group (which may be overridden for individual peers).

Specifying peers

Within a group, BGP peers may be configured in one of two ways. They may be explicitly configured with a peer statement, or implicitly configured with the allow statement. Both are described here:

Within each group clause, individual peers can be specified or a group of potential peers can be specified using allow. Allow is used to specify a set of address masks. If the gated daemon receives a BGP connection request from any address in the set specified, it will accept it and set up a peer relationship.

Peer parameters

The BGP peer subclause allows the following parameters, which can also be specified on the group clause. All are optional.

metricout metric

If specified, this metric is used as the primary metric on all routes sent to the specified peer(s). This metric overrides the default metric, a metric specified on the group and any metric specified by export policy.

localas autonomous_system

Identifies the autonomous system that the gated daemon is representing to this group of peers. The default is that which has been set globally in the autonomoussystem statement.

nogendefault

Prevents gated.conf from generating a default route when EGP receives a valid update from its neighbor. The default route is only generated when the gendefault option is enabled.

gateway gateway

If a network is not shared with a peer, gateway specifies a router on an attached network to be used as the next hop router for routes received from this neighbor. This parameter is not needed in most cases.

preference preference

Specifies the preference used for routes learned from these peers. This can differ from the default BGP preference set in the bgp statement, so that the gated daemon can prefer routes from one peer, or group of peer, over others. This preference may be explicitly overridden by import policy.

preference2 preference

In the case of a preference tie, the second preference, preference2 may be used to break the tie. The default value is 0.

lcladdr local_address

Specifies the address to be used on the local end of the TCP connection with the peer. For external peers the local address must be on an interface that is shared with the peer or with the peer's gateway when the gateway parameter is used. A session with an external peer will only be opened when an interface with the appropriate local address (through which the peer or gateway address is directly reachable) is operating. For other types of peers, a peer session will be maintained when any interface with the specified local address is operating. In either case, incoming connections will only be recognized as matching a configured peer if they are addressed to the configured local address.

holdtime time

Specifies the BGP holdtime value to use when negotiating the connection with this peer, in seconds. According to BGP, if the gated daemon does not receive a keepalive, update, or notification message within the period specified in the Hold Time field of the BGP Open message, then the BGP connection will be closed. The value must be either 0 (no keepalives will be sent) or at least 3.

version version

Specifies the version of the BGP protocol to use with this peer. If not specified, the highest supported version is used first and version negotiation is attempted. If it is specified, only the specified version will be offered during negotiation. Currently supported versions are 2, 3 and 4.

passive

Specifies that active OPENs to this peer should not be attempted. the gated daemon should wait for the peer to issue an OPEN. By default, all explicitly configured peers are active, they periodically send OPEN messages until the peer responds.

indelay time

outdelay time

Used to dampen route fluctuations. Indelay is the amount of time a route learned from a BGP peer must be stable before it is accepted into the gated routing database. Outdelay is the amount of time a route must be present in the gated routing database before it is exported to BGP. The default value for each is 0, meaning that these features are disabled.

keep all

Used to retain routes learned from a peer even if the routes' AS paths contain one of our exported AS numbers.

noaggregatorid

Causes the gated daemon to specify the routerid in the aggregator attribute as zero (instead of its routerid) in order to prevent different routers in an AS from creating aggregate routes with different AS paths.

keepalivesalways

Causes the gated daemon to always send keepalives, even when an update could have correctly substituted for one. This allows interoperability with routers that do not completely obey the protocol specifications on this point.

v3asloopokay

By default, the gated daemon will not advertise routes whose AS path is looped (that is, with an AS appearing more than once in the path) to version 3 external peers. Setting this flag removes this constraint. Ignored when set on internal groups or peers.

nov4asloop

Prevents routes with looped AS paths from being advertised to version 4 external peers. This can be useful to avoid advertising such routes to peers that would incorrectly forward the routes on to version 3 neighbors.

logupdown

Causes a message to be logged via the syslog mechanism whenever a BGP peer enters or leaves the ESTABLISHED state.

traceoptions trace_options

Specifies the tracing options for this BGP neighbor. By default, these are inherited from group or BGP global trace options.(See Trace Statements and the BGP specific tracing options below.)

Tracing options

Packet tracing options (which may be modified with detail, send, and recv):

The BGP4+ Statement

The options are the same for BGP4+ as they are for bgp but all the addresses will be IPv6 addresses.

The syntax is:

     
     bgp4+ yes | no | on | off
     [ {
        preference <preference> ;
        defaultmetric <metric> ;
        traceoptions <trace_options> ;
        group type ( external peeras <autonomous_system> )
            | ( internal peeras <autonomous_system> )
            | ( igp peeras <autonomous_system> proto <proto> )
            | ( routing peeras <autonomous_system> proto <proto>
                    interface <interface_list> )
            | ( test peeras <autonomous_system> )
        {
            allow {
                <network>
                <network> masklen <number>
                all
                host <IPv6 host address>
            } ;
            peer <IPv6 host address>
                [ metricout <metric> ]
                [ localas <autonomous_system> ]
                [ nogendefault ]
                [ gateway <gateway> ]
                [ preference <preference> ]
                [ preference2 <preference> ]
                [ lcladdr <local_address> ]
                [ holdtime <time> ]
                [ version <number> ]
                [ passive ]
                [ sendbuffer <number> ]
                [ recvbuffer <number> ]
                [ indelay <time> ]
                [ outdelay <time> ]
                [ keep [ all | none ] ]
                [ analretentive ]
                [ noauthcheck ]
                [ noaggregatorid ]
                [ keepalivesalways ]
                [ v3asloopokay ]
                [ nov4asloop ]
                [ logupdown ]
                [ ttl <ttl> ]
                [ traceoptions <trace_options> ]
                ;
        } ;
     } ] ;

The ICMP Statement

 icmp   {
     traceoptions   trace_options ;
 } 

Tracing options

Packet tracing options (which may be modified with detail and recv):

The SNMP Statement

The Simple Network Management Protocol (SNMP) is a not a routing protocol but a network management protocol. The snmp statement controls whether gated.conf tries to contact the SNMP Multiplexing daemon to register supported variables. The SNMP daemon, smuxd, must be run independently. The snmp statement only controls whether gated.conf keeps the management software apprised of its status.

gated.conf communicates with the SNMP daemon via the SMUX protocol that is described in RFC 1227.

 snmp   yes  |  no  |  on  |  off
[ {
     port  port ;
     debug;
     traceoptions  traceoptions;
 }] ; 

Reporting is enabled by specifying yes or on and disabled with no or off. The default is on.

Tracing options

There are no SNMP-specific trace options. The detail, send, and recv options are not supported.

Static Statements

Static statements define the static routes used by the gated daemon. A single static statement can specify any number routes. The static statements occur after protocol statements and before control statements in the gated.conf file. Any number of static statements may be specified, each containing any number of static route definitions. These routes can be overridden by routes with better preference values.

host host gateway gateway_list ( network [ ( mask mask ) | ( masklen number ) ] ) default gateway gateway_list

This is the most general form of the static statement. It defines a static route through one or more gateways. Static routes are installed when one or more of the gateways listed are available on directly attached interfaces.

Parameters for static routes are:

interface interface_list	When this parameter is specified, gateways are only considered valid when they are on one of these interfaces. See the section on interface_list specification for the description of the interface_list.
preference preference	This option selects the preference of this static route. The preference controls how this route competes with routes from other protocols. The default preference is 60.
retain	Normally the gated daemon removes all routes except interface routes from the kernel forwarding table during a graceful shutdown. The retain option may be used to prevent specific static routes from being removed. This is useful to insure that some routing is available when gated is not running.
reject	Instead of forwarding a packet like a normal route, reject routes cause packets to be dropped and unreachable messages to be sent to the packet originators. Specifying this option causes this route to be installed as a reject route. Not all kernel forwarding engines support reject routes.
blackhole	A blackhole route is the same as a reject route except that unreachable messages are not supported.
noinstall	Normally the route with the lowest preference is installed in the kernel forwarding table and is the route exported to other protocols. When noinstall is specified on a route, it will not be installed in the kernel forwarding table when it is active, but it will still be eligible to be exported to other protocols.

( network [ (mask mask ) | ( masklen number ) ] ) interface interface

This form defines a static interface route that is used for primitive support of multiple network addresses on one interface. The preference, retain, reject, blackhole and noinstall options are the same as described above.

The Import Statement

Importation of routes from routing protocols and installation of the routes in the gated daemon's routing database is controlled by import statements. The format of an import statement varies depending on the source protocol.

Specifying preferences

In all cases, one of two keywords may be specified to control how routes compete with other protocols:

Route Filters

All the formats allow route filters as shown below. See the section on route filters for a detailed explanation of how they work. When no route filtering is specified (that is, when restrict is specified on the first line of a statement), all routes from the specified source will match that statement. If any filters are specified, only routes that match the specified filters will be imported. Put differently, if any filters are specified, an all restrict; is assumed at the end of the list.

    network [ exact | refines ]
    network mask mask [exact | refines ]
    network masklen number [ exact | refines ]
    default
    host host

Importing Routes from BGP and EGP

import proto bgp | EGP autonomoussystem autonomous_system
restrict ;
import proto bgp | EGP autonomoussystem autonomous_system
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;

import proto bgp aspath aspath_regexp
origin any | ( [ IGP ] [EGP ] [ incomplete ] )
restrict ;
import proto bgp aspath aspath_regexp
origin any | ( [ IGP ] [EGP ] [ incomplete ] )
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;

EGP importation may be controlled by autonomous system.

BGP also supports controlling propagation by the use of AS path regular expressions, which are documented in the section on Matching AS paths.

EGP and BGP both store any routes that were rejected implicitly by not being mentioned in a route filter, or explicitly with the restrict keyword in the routing table with a negative preference. A negative preference prevents a route from becoming active, which prevents it from being installed in the forwarding table, or exported to other protocols. This alleviates the need to break and re-establish a session upon reconfiguration if importation policy is changed.

Importing Routes from RIP, HELLO and Redirects

import proto rip | hello | redirect
[ ( interface interface_list ) | (gateway gateway_list ) ]
restrict ;
import proto rip | hello | redirect
[ ( interface interface_list ) | (gateway gateway_list ) ]
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;

The importation of RIP, HELLO, and Redirect routes may be controlled by any of protocol, source interface, and source gateway. If more than one is specified, they are processed from most general (protocol) to most specific (gateway).

RIP and HELLO don't support the use of preference to choose between routes of the same protocol. That is left to the protocol metrics. These protocols do not save routes that were rejected since they have short update intervals.

Importing Routes from OSPF

import proto ospfase [ tag ospf_tag ] restrict ;
import proto ospfase [ tag ospf_tag ]
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;

Due to the nature of OSPF, only the importation of ASE routes may be controlled. OSPF intra- and inter-area routes are always imported into the gated routing table with a preference of 10. If a tag is specified, the import clause will only apply to routes with the specified tag.

It is only possible to restrict the importation of OSPF ASE routes when functioning as an AS border router. This is accomplished by specifying an export ospfase clause. Specification of an empty export clause may be used to restrict importation of ASEs when no ASEs are being exported.

Like the other interior protocols, preference can not be used to choose between OSPF ASE routes, that is done by the OSPF costs. Routes that are rejected by policy are stored in the table with a negative preference.

The Export Statement

The import statement controls routes received from other systems that are used by the gated daemon, and the export statement controls which routes are advertised by the gated daemon to other systems. Like the import statement, the syntax of the export statement varies slightly per protocol. The syntax of the export statement is similar to the syntax of the import statement, and the meanings of many of the parameters are identical. The main difference between the two is that while route importation is just controlled by source information, route exportation is controlled by both destination and source.

The outer portion of a given export statement specifies the destination of the routing information you are controlling. The middle portion restricts the sources of importation that you wish to consider And the innermost portion is a route filter used to select individual routes.

Specifying Metrics

The most specific specification of a metric is the one applied to the route being exported. The values that may be specified for a metric depend on the destination protocol that is referenced by this export statement.

    restrict
    metric metric

Route Filters

All the formats allow route filters as shown below. See the section on route filters for a detailed explanation of how they work. When no route filtering is specified (that is, when restrict is specified on the first line of a statement), all routes from the specified source will match that statement. If any filters are specified, only routes that match the specified filters will be exported. Put differently, if any filters are specified, an all restrict ; is assumed at the end of the list.

    network [ exact | refines ]
    network mask mask [exact | refines ]
    network masklen number [ exact | refines ]
    default
    host host

Specifying the Destination

As mentioned above, the syntax of the export statement varies depending on the protocol to which it is being applied. One thing that applies in all cases is the specification of a metric. All protocols define a default metric to be used for routes being exported, in most cases this can be overridden at several levels of the export statement.

The specification of the source of the routing information being exported (the export_list) is described below.

Exporting to EGP and BGP

export proto bgp | EGP as autonomous system
    restrict ;
export proto bgp | EGP as autonomous system
    [ metric metric ] {
    export_list ;
} ;

Exportation to EGP and BGP is controlled by autonomous system, the same policy is applied to all routers in the AS.

EGP metrics range from 0 to 255 inclusive with 0 being the most attractive.

BGP metrics are 16 bit unsigned quantities, that is, they range from 0 to 65535 inclusive with 0 being the most attractive.

If no export policy is specified, only routes to attached interfaces will be exported. If any policy is specified, the defaults are overridden. It is necessary to explicitly specify everything that should be exported.

Exporting to RIP and HELLO

export proto rip | hello
[ ( interface interface_list ) | (gateway gateway_list ) ]
restrict ;
export proto rip | hello
[ ( interface interface_list ) | (gateway gateway_list ) ]
[ metric metric ] {
export_list ;
} ;

Exportation to RIP and HELLO is controlled by any of protocol, interface or gateway. If more than one is specified, they are processed from the most general (protocol) to the most specific (gateway).

It is not possible to set metrics for exporting RIP routes into RIP, or exporting HELLO routes into HELLO. Attempts to do this are silently ignored.

If no export policy is specified, RIP and interface routes are exported into RIP and HELLO and interface routes are exported into HELLO. If any policy is specified, the defaults are overridden. It is necessary to explicitly specify everything that should be exports.

RIP version 1 and HELLO assume that all subnets of the shared network have the same subnet mask so they are only able to propagate subnets of that network. RIP version 2 removes that restriction and is capable of propagating all routes when not sending version 1 compatible updates.

To announce routes that specify a next hop of the loopback interface (that is, static and internally generated default routes) via RIP or HELLO, it is necessary to specify the metric at some level in the export clause. For example, just setting a default metric for RIP or HELLO is not sufficient. This is a safeguard to verify that the announcement is intended.

Exporting to OSPF

export proto osfpase [ type 1 | 2 ] [ tag ospf_tag ]
    restrict ;
export proto osfpase [ type 1 | 2 ] [ tag ospf_tag ]
    [ metric metric ] {
    export_list ;
} ;                        

It is not possible to create OSPF intra- or inter-area routes by exporting routes from the the gated daemon routing table into OSPF. It is only possible to export from the gated daemon routing table into OSPF ASE routes. It is also not possible to control the propagation of OSPF routes within the OSPF protocol.

There are two types of OSPF ASE routes, type 1 and type 2. See the OSPF protocol configuration for a detailed explanation of the two types. The default type is specified by the defaults subclause of the ospf clause. This may be overridden by a specification on the export statement.

OSPF ASE routes also have the provision to carry a tag. This is an arbitrary 32 bit number that can be used on OSPF routers to filter routing information. See the OSPF protocol configuration for detailed information on OSPF tags. The default tag specified by the ospf defaults clause may be overridden by a tag specified on the export statement.

Specifying the Source

The export list specifies export based on the origin of a route and the syntax varies depending on the source.

Exporting BGP and EGP Routes

proto bgp | EGP autonomoussystem autonomous_system
    restrict ;
proto bgp | EGP autonomoussystem autonomous_system
    [ metric metric ] {
    route_filter [ restrict | ( metric metric ) ] ;
} ;

BGP and EGP routes may be specified by the source autonomous system. All routes may be exported by as path, see the Exporting by AS Path section for more information.

Exporting RIP and HELLO Routes

proto rip | hello
[ ( interface interface_list ) | (gateway gateway_list ) ]
restrict ;
proto rip | hello
[ ( interface interface_list ) | (gateway gateway_list ) ]
[ metric metric ] {
route_filter [ restrict | ( metric metric ) ] ;
} ;

RIP and HELLO routes may be exported by protocol, source interface, and/or source gateway.

Exporting OSPF Routes

proto ospf | ospfase restrict ;
proto ospf | ospfase [ metric metric ] {
    route_filter [ restrict | ( metric metric ) ] ;
} ;

Both OSPF and OSPF ASE routes may be exported into other protocols. See below for information on exporting by tag.

Exporting Routes from Non-routing Protocols

Non-routing with Interface

proto direct | static | kernel
[ (interface interface_list ) ]
restrict ;
proto direct | static | kernel
[ (interface interface_list ) ]
[ metric metric ] {
route_filter [ restrict | ( metric metric ) ] ;
} ;

These protocols may be exported by protocol, or by the interface of the next hop. These protocols are:

Non-routing by Protocol

proto default | aggregate
    restrict ;
proto default | aggregate
    [ metric metric ] {
    route_filter [ restrict | ( metric metric ) ] ;
} ;

These protocols may only be referenced by protocol.

Exporting by AS Path

proto proto | all aspath aspath_regexp
    origin any | ( [ IGP ] [EGP ] [ incomplete ] )
    restrict ;
proto proto | all aspath aspath_regexp
    origin any | ( [ IGP ] [EGP ] [ incomplete ] )
    [ metric metric ] {
    route_filter [ restrict | ( metric metric ) ] ;
} ;

When BGP is configured, all routes are assigned an AS path when they are added to the routing table. For all interior routes, this AS path specifies IGP as the origin and no ASEs in the AS path (the current AS is added when the route is exported). For EGP routes this AS path specifies EGP as the origin and the source AS as the AS path. For BGP routes, the AS path is stored as learned from BGP.

AS path regular expressions are documented in the section on Matching AS paths.

Exporting by Route Tag

proto proto | all tag tag restrict ;
proto proto | all tag tag
    [ metric metric ] {
    route_filter [ restrict | ( metric metric ) ] ;
} ;

Both OSPF and RIP version 2 currently support tags; all other protocols always have a tag of zero. The source of exported routes may be selected based on this tag. This is useful when routes are classified by a tag when they are exported into a given routing protocol.

Route Aggregation

Route aggregation is a method of generating a more general route given the presence of a specific route. It is used, for example, at an autonomous system border to generate a route to a network to be advertised via EGP given the presence of one or more subnets of that network learned via RIP. No aggregation is performed unless explicitly requested in an aggregate statement.

Route aggregation is also used by regional and national networks to reduce the amount of routing information passed around. With careful allocation of network addresses to clients, regional networks can just announce one route to regional networks instead of hundreds.

Aggregate routes are not actually used for packet forwarding by the originator of the aggregate route, only by the receiver (if it wishes).

A slight variation of aggregation is the generation of a route based on the existence of certain conditions. This is sometimes known as the route of last resort. This route inherits the next hops and aspath from the contributor specified with the lowest (most favorable) preference. The most common usage for this is to generate a default based on the presence of a route from a peer on a neighboring backbone.

Aggregation and Generation syntax

aggregate default
| ( network [ ( mask mask ) | ( masklen number ) ] )
[ preference preference ] [ brief ] {
proto [ all | direct | static | kernel | aggregate | proto ]
[ ( as autonomous system ) | ( tag tag )
| ( aspath aspath_regexp ) ]
restrict ;
proto [ all | direct | static | kernel | aggregate | proto ]
[ ( as autonomous system ) | ( tag tag )
| ( aspath aspath_regexp ) ]
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;
} ;

generate default
| ( network [ ( mask mask ) | ( masklen number ) ] )
[ preference preference ] {
[ ( as autonomous system ) | ( tag tag )
| ( aspath aspath_regexp ) ]
restrict ;
proto [ all | direct | static | kernel | aggregate | proto ]
[ ( as autonomous system ) | ( tag tag )
| ( aspath aspath_regexp ) ]
[ preference preference ] {
route_filter [ restrict | ( preference preference ) ] ;
} ;
} ;

Routes that match the route filters are called contributing routes. They are ordered according to the aggregation preference that applies to them. If there are more than one contributing routes with the same aggregating preference, the route's own preferences are used to order the routes. The preference of the aggregate route will be that of contributing route with the lowest aggregate preference.

A route may only contribute to an aggregate route that is more general than itself; it must match the aggregate under its mask. Any given route may only contribute to one aggregate route, which will be the most specific configured, but an aggregate route may contribute to a more general aggregate.

Route Filters

All the formats allow route filters as shown below. See the section on route filters for a detailed explanation of how they work. When no route filtering is specified (that is, when restrict is specified on the first line of a statement), all routes from the specified source will match that statement. If any filters are specified, only routes that match the specified filters will be considered as contributors. Put differently, if any filters are specified, an all restrict ; is assumed at the end of the list.

    network [ exact | refines ]
    network mask mask [exact | refines ]
    network masklen number [ exact | refines ]
    default
    host host

Preference

Preference is the value the gated daemon uses to order preference of routes from one protocol or peer over another. Preference can be set in the gated.conf configuration file in several different configuration statements.

Preference can be set based on network interface over another, from one protocol over another, or from one remote gateway over another.

Preference may not be used to control the selection of routes within an IGP, this is accomplished automatically by the protocol based on metric. Preference may be used to select routes from the same EGP learned from different peers or autonomous systems.

Each route has only one preference value associated with it, even though preference can be set at many places in the configuration file. Simply, the last or most specific preference value set for a route is the value used. The preference value is an arbitrarily assigned value used to determine the order of routes to the same destination in a single routing database. The active route is chosen by the lowest preference value.

Some protocols implement a second preference (preference2), sometimes refered to as a tie-breaker.

Selecting a Route

• The route with the best (numerically smallest) preference is preferred.
• If the two routes have the same preference, the route with the best (numerically smallest) preference2 (also known as a tie-breaker) is preferred.
• A route learned from a IGP is preferred to a route learned from an EGP. Least preferred is a route learned indirectly by an IGP from an EGP.
• If AS path information is available it is used to help determine the most preferred route.
  • A route with an AS path is preferred over one without an AS path.
  • If the AS paths and origins are identical, the route with the lower metric is preferred.
  • A route with an AS path origin of IGP is preferred over a route with an AS path origin of EGP. Least preferred is an AS path with an unknown origin.
  • A route with a shorter AS path is preferred.
• If both routes are from the same protocol and AS, the one with the lowest metric is preferred.
• The route with the lowest numeric next-hop address is used.

Assigning Preferences

A default preference is assigned to each source from which the gated daemon receives routes. Preference values range from 0 to 255 with the lowest number indicating the most preferred route.

The following table summarizes the default preference values for routes learned in various ways. The table lists the statements (some of these are clauses within statements) that set preference, and shows the types of routes to which each statement applies. The default preference for each type of route is listed, and the table notes preference precedence between protocols. The narrower the scope of the statement, the higher precedence its preference value is given, but the smaller the set of routes it affects.

  Preference Of                    Defined by Statement             Default
  direct connnected networks           interface                       0
  OSPF routes                          ospf                            10
  IS-IS level 1 routes                 isis level 1                    15
  IS-IS level 2 routes                 isis level 2                    18
  internally generated default         gendefault                      20
  redirects                            redirect                        30
  routes learned via route socket      kernel                          40
  static routes from config            static                          60
  ANS SPF (SLSP) routes                slsp                            70
  HELLO routes                         hello                           90
  RIP routes                           rip                             100
  point-to-point interface                                             110
  routes to interfaces that are down   interfaces                      120
  aggregate/generate routes            aggregate/generate              130
  OSPF AS external routes              ospf                            150
  BGP routes                           bgp                             170
  EGP                                  EGP                             200

Sample Preference Specifications

    interfaces {
	    interface 138.66.12.2 preference 10 ;
    } ;
    rip yes {
	preference 90 ;
    } ;
    import proto rip gateway 138.66.12.1 preference 75 ;

In these statements, the preference applicable to routes learned via RIP from gateway 138.66.12.1 is 75. The last preference applicable to routes learned via RIP from gateway 128.66.12.1 is defined in the accept statement. The preference applicable to other RIP routes is found in the rip statement. The preference set on the interface statement applies only to the route to that interface.

The Router Discovery Protocol

The Router Discovery Protocol is an IETF standard protocol used to inform hosts of the existence of routers. It is used in place of, or in addition to statically configured default routes in hosts.

The protocol is split into two portions, the server portion which runs on routers, and the client portion that runs on hosts. The gated daemon treats these much like two separate protocols, only one of which may be enabled at a time.

The Router Discovery Server

The Router Discovery Server runs on routers and announces their existence to hosts. It does this by periodically multicasting or broadcasting a Router Advertisement to each interface on which it is enabled. These Router Advertisements contain a list of all the routers addresses on a given interface and their preference for use as default routers.

Initially, these Router Advertisements occur every few seconds, then fall back to every few minutes. In addition, a host may send a Router Solicitation to which the router will respond with a unicast Router Advertisement (unless a multicast or broadcast advertisement is due momentarily).

Each Router Advertisement contains an Advertisement Lifetime field indicating for how long the advertised addresses are valid. This lifetime is configured such that another Router Advertisement will be sent before the lifetime has expired. A lifetime of zero is used to indicate that one or more addresses are no longer valid.

The Router Advertisements are by default sent to the all-hosts multicast address 224.0.0.1. However, the use of broadcast may be specified. When Router Advertisements are being sent to the all-hosts multicast address, or an interface is configured for the limited-broadcast address 255.255.255.255, all IP addresses configured on the physical interface are included in the Router Advertisement. When the Router Advertisements are being sent to a net or subnet broadcast, only the address associated with that net or subnet is included.

The Router Discovery Server Statement

routerdiscovery server yes | no | on | off [ {
traceoptions trace_options ;
interface interface_list
[minadvinterval time]
[maxadvinterval time]
[lifetime time]
;
address interface_list
[advertise] | [ignore]
[broadcast] | [multicast]
[ineligible] | [preference preference]
;
} ] ;

traceoptions trace_options

Specifies the Router Discovery tracing options. (See Trace Statements and the Router Discovery specific tracing options below.)

interface interface_list

Specifies the parameters that apply to physical interfaces. Note a slight difference in convention from the rest of the gated daemon, interface specifies just physical interfaces (such as en0 and tr0), while address specifies protocol (in this case IP) addresses.

Interface parameters are:

maxadvinterval time

The maximum time allowed between sending broadcast or multicast Router Advertisements from the interface. Must be no less than 4 and no more than 30:00 (30 minutes or 1800 seconds). The default is 10:00 (10 minutes or 600 seconds).

minadvinterval time

The minimum time allowed between sending unsolicited broadcast or multicast Router Advertisements from the interface. Must be no less than 3 seconds and no greater than maxadvinterval. The default is 0.75 * maxadvinterval.

lifetime time

The lifetime of addresses in a Router Advertisement. Must be no less than maxadvinterval and no greater than 2:30:00 (two hours, thirty minutes or 9000 seconds). The default is 3 * maxadvinterval.

address interface_list

Specifies the parameters that apply to the specified set of addresses on this physical interface. Note a slight difference in convention from the rest of gated.conf; interface specifies just physical interfaces (such as en0 and tr0), while address specifies protocol (in this case IP) addresses.

advertise

Specifies that the specified address(es) should be included in Router Advertisements. This is the default.

ignore

Specifies that the specified address(es) should not be included in Router Advertisements.

broadcast

Specifies that the given address(es) should be included in a broadcast Router Advertisement because this system does not support IP multicasting, or some hosts on attached network do not support IP multicasting. It is possible to mix addresses on a physical interface such that some are included in a broadcast Router Advertisement and some are included in a multicast Router Advertisement. This is the default if the router does not support IP multicasting.

multicast

Specifies that the given address(es) should only be included in a multicast Router Advertisement. If the system does not support IP multicasting the address(es) will not be included. If the system supports IP multicasting, the default is to include the address(es) in a multicast Router Advertisement if the given interface supports IP multicasting, if not the address(es) will be included in a broadcast Router Advertisement.

preference preference

The preferability of the address(es) as a default router address, relative to other router addresses on the same subnet. A 32-bit, signed, twos-complement integer, with higher values meaning more preferable. Note that hex 80000000 may only be specified as ineligible. The default is 0.

ineligible

Specifies that the given address(es) will be assigned a preference of (hex 80000000) that means that it is not eligible to be the default route for any hosts.

This is useful when the address(es) should not be used as a default route, but are given as the next hop in an ICMP redirect. This allows the hosts to verify that the given addresses are up and available.

The Router Discovery Client

A host listens for Router Advertisements via the all-hosts multicast address (224.0.0.2), If IP multicasting is available and enabled, or on the interface's broadcast address. When starting up, or when reconfigured, a host may send a few Router Solicitations to the all-routers multicast address, 224.0.0.2, or the interface's broadcast address.

When a Router Advertisement with non-zero lifetime is received, the host installs a default route to each of the advertised addresses. If the preference ineligible, or the address is not on an attached interface, the route is marked unusable but retained. If the preference is usable, the metric is set as a function of the preference such that the route with the best preference is used. If more than one address with the same preference is received, the one with the lowest IP address will be used. These default routes are not exportable to other protocols.

When a Router Advertisement with a zero lifetime is received, the host deletes all routes with next-hop addresses learned from that router. In addition, any routers learned from ICMP redirects pointing to these addresses will be deleted. The same will happen when a Router Advertisement is not received to refresh these routes before the lifetime expires.

The Router Discovery Client Statement

routerdiscovery client yes | no | on | off [ {
traceoptions trace_options ;
preference preference ;
interface interface_list
[ enable ] | [ disable ]
[ broadcast ] | [ multicast ]
[ quiet ] | [ solicit ]
;
} ] ;

traceoptions trace_options

Specifies the tracing options for Router Discovery Client. (See Trace Statements and the Router Discovery Client specific tracing options below.)

preference preference ;

Specifies the preference of all Router Discovery default routes. The default is 55.

interface interface_list

Specifies the parameters that apply to physical interfaces. Note a slight difference in convention from the rest of gated, interface specifies just physical interfaces (such as en0 and tr0). The Router Discovery Client has no parameters that apply only to interface addresses.

enable

Specifies that Router Discovery should be performed on the specified interface(s). This is the default.

disable

Specifies that Router Discovery should not be performed on the specified interface(s).

broadcast

Specifies that Router Solicitations should be broadcast on the specified interface(s). This is the default if IP multicast support is not available on this host or interface.

multicast

Specifies that Router Solicitations should be multicast on the specified interface(s). If IP multicast is not available on this host and interface, no solicitation will be performed. The default is to multicast Router Solicitations if the host and interface support it, otherwise Router Solicitations are broadcast.

quiet

Specifies that no Router Solicitations will be sent on this interface, even though Router Discovery will be performed.

solicit

Specifies that initial Router Solicitations will be sent on this interface. This is the default.

Tracing options

The Router Discovery Client and Server support the state trace flag that traces various protocol occurrences.

The Router Discovery Client and Server do not directly support any packet tracing options, tracing of router discovery packets is enabled via the ICMP Statement.

Route Filtering

Routes are filtered by specifying configuration language that will match a certain set of routes by destination, or by destination and mask. Among other places, route filters are used on martians, import and export statements.

The action taken when no match is found is dependent on the context, for instance import and export route filters assume an all reject ; at the end of a list.

A route will match the most specific filter that applies. Specifying more than one filter with the same destination, mask and modifiers will generate an error.

Filtering syntax

    network [ exact | refines ]
    network mask mask [ exact | refines ]
    network masklen number [ exact | refines ]
    all
    default
    host host

These are all the possible formats for a route filter. Not all of these formats are available in all places, for instance the host and default formats are not valid for martians.

In most cases it is possible to specify additional parameters relevent to the context of the filter. For example, on a martian statement it is possible to specify the allow keyword, on an import statement you can specify a preference, and on a export you can specify a metric.

network [ exact | refines ]

network mask mask [ exact | refines ]

network masklen number [ exact | refines ]

Matching usually requires both an address and a mask, although the mask is implied in the shorthand forms listed below. These three forms vary in how the mask is specified. In the first form, the mask is implied to be the natural mask of the network. In the second, the mask is explicitly specified. In the third, the mask is specified by the number of contiguous one bits.

If no additional parameters are specified, any destination that falls in the range given by the network and mask is matched, the mask of the destination is ignored. If a natural network is specified, the network, any subnets, and any hosts will be match. The two optional modifiers cause the mask of the destination to be considered also:

exact

This parameter specifies that the mask of the destination must match the supplied mask exactly. This is used to match a network, but no subnets or hosts of that network.

refines

Specifies that the mask of the destination must be more specified (that is, longer) than the filter mask. This is used to match subnets and/or hosts of a network, but not the network.

all

This entry matches anything. It is equivalent to:

0.0.0.0 mask 0.0.0.0

default

Matches the default route. To match, the address must be the default address and the mask must be all zeros. This is equivalent to:

0.0.0.0 mask 0.0.0.0 exact

host host

Matches the specific host. To match, the address must exactly match the specified host and the network mask must be a host mask (that is, all ones). This is equivalent to:

host mask 255.255.255 exact

Matching AS Paths

An AS path is a list of autonomous_systems that routing information has passed through to get to this router, and an indicator of the origin of the AS path. This information can be used to prefer one path to a destination network over another. The primary method for doing this with gated.conf is to specify a list of patterns to be applied to AS paths when importing and exporting routes.

Each autonomous system that a route passed through prepends its AS number to the beginning of the AS path.

The origin information details the completeness of AS path information. An origin of IGP indicates the route was learned from an interior routing protocol and is most likely complete. An origin of EGP indicates the route was learned from an exterior routing protocol that does not support AS paths (EGP, for example) and the path is most likely not complete. When the path information is definitely not complete, an origin of incomplete is used.

AS path regular expressions are defined in RFC 1164 section 4.2.

AS Path Matching Syntax

An AS path is matched using the following syntax:

aspath aspath_regexp origin any | ( [IGP] [EGP] [incomplete] )

This specifies that an AS matching the aspath_regexp with the specified origin is matched.

AS Path Regular Expressions

Technically, an AS path regular expression is a regular expression with the alphabet being the set of AS numbers. An AS path regular expression is composed of one or more AS paths expressions. An AS path expressions is composed of AS path terms and AS path operators.

AS Path Terms

An AS path term is one of the following three objects:

autonomous_system
.
( aspath_regexp )

AS Path Operators

An AS path operator is one of the following:

aspath_term {m,n}
aspath_term {m}
aspath_term {m,}
aspath_term *
aspath_term +
aspath_term ?
aspath_term | aspath_term