Compaq TCP/IP Services for OpenVMS
Management

A.5 Creating the GATED Configuration File

To create a configuration file for your local host, edit a copy of the sample file TCPIP$GATED.TEMPLATE (located in the SYS$SYSDEVICE:[TCPIP$GATED] directory),then save the file to SYS$SYSDEVICE:TCPIP$GATED.CONF.

The following shows the template configuration file:

#------------------------------------------------------------------------------ # # TCPIP$GATED.CONF - Sample config file, preconfigured for RIP v1. # #------------------------------------------------------------------------------ # interfaces { interface all passive ; }; # # Protocols: # rip on { broadcast; interface all ripin ripout version 1; }; # redirect on; routerdiscovery server off; hello off; ospf off; egp off; bgp off; snmp off; # # Static routes: # #static { # 10.1.2.0 mask 255.255.255.0 gateway 10.1.1.1; # default gateway 10.1.2.3; # }; # # Policy: # #export proto rip { # proto static { all metric 1; }; # proto direct { all; }; # proto rip { all; }; # };

A.6 Defining Preferences and Routing

The configuration file can define routes from one protocol or peer to another, assigning each route a value, called a preference.

The preference value determines 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 referred to as a "tie breaker."

Preferences have the following characteristics:

May appear in several different configuration statements in the configuration file. Be aware, however, that the last, or most specific value set for a route is the value GATED will use.
May specify one network interface over another, one protocol over another, or one remote gateway over another.
Cannot be used to control the selection of routes within an interior gateway protocol (IGP). That function is accomplished automatically by the protocol based on metric.
May select routes from the same exterior gateway protocol (EGP) learned from different peers or autonomous systems.

The GATED daemon selects a route based on the following preference criteria:

The route with the best (numerically smallest) preference is selected.
If the two routes have the same preference, the route with the best (numerically smallest) preference2 is selected.
A route from an IGP is selected over a route from an EGP. The least preferred is a route learned indirectly by an IGP from an EGP.
If autonomous system (AS) path information is available, it is used to help determine the most preferred route as follows:
- A route with an AS path is selected over one without an AS path.
- If the AS paths and origins are identical, the route with the lower metric is selected.
- A route with an AS path origin of IGP is preferred over a route with an AS path origin of EGP. The 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 selected.
- The route with the lowest numeric next-hop address is used.

A.6.1 Assigning Preferences

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

Table A-2 lists each type of route, the statement (or clause within statements) that sets preference for the route, and the default preference for each type of route.

Note that a statement that is narrow in scope has a higher precedence given to its preference value, but affects a smaller set of routes.

Table A-2 Default Preference Values
Preference Defined by Statement Default

Direct connected networks interface 0

OSPF routes ospf 10

Internally generated default gendefault 20

Redirects redirect 30

Routes learned through 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

**Table A-2 Default Preference Values**
Preference	Defined by Statement	Default
Direct connected networks	interface	0
OSPF routes	ospf	10
Internally generated default	gendefault	20
Redirects	redirect	30
Routes learned through 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

A.6.2 Sample Preference Specifications

In the following example, the preference applicable to routes learned through RIP from gateway 138.66.12.1 is 75. The last preference applicable to routes learned through RIP from gateway 138.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.

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

A.7 Tracing Options

You can specify tracing options at the following levels: 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, Border Gateway Protocol (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 tracing options. At each level, tracing specifications override the inherited options.

The syntax for trace options statements is as follows:

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

Table A-3 describes the valid trace options.

Table A-3 Trace Options
Option Definition

trace_file Specifies the file to receive tracing information. If this file name does not begin with a slash (/), the directory in which GATED was started is prepended to the name.

replace Replaces an existing trace file. The default is to append to an existing file.

size size[k|m] files files Limits the maximum size of the trace file to the specified size (minimum 10 kilobytes). When the trace file reaches the specified size, it is renamed to file.0, then file.1, file.2, up to the maximum number of files (minimum specification is 2).

control_options Specifies options that control the appearance of tracing. The only valid value is nostamp, which specifies that a timestamp should not be prepended to all trace lines.

except trace_options Enables a broad class of tracing and then disables more specific options.

none Specifies that all tracing should be turned off for this protocol or peer.

**Table A-3 Trace Options**
Option	Definition
`trace_file`	Specifies the file to receive tracing information. If this file name does not begin with a slash (/), the directory in which GATED was started is prepended to the name.
`replace`	Replaces an existing trace file. The default is to append to an existing file.
`size size[k\|m] files files`	Limits the maximum size of the trace file to the specified size (minimum 10 kilobytes). When the trace file reaches the specified size, it is renamed to file.0, then file.1, file.2, up to the maximum number of files (minimum specification is 2).
`control_options`	Specifies options that control the appearance of tracing. The only valid value is nostamp, which specifies that a timestamp should not be prepended to all trace lines.
`except trace_options`	Enables a broad class of tracing and then disables more specific options.
`none`	Specifies that all tracing should be turned off for this protocol or peer.

A.7.1 Global Tracing Options

There are two types of global options: those with global significance (Table A_4) and those with protocol significance (Table A-5).

Table A-4 Global Significance Options
Option Definition

parse Traces the lexical analyzer and parser. Used mainly by GATED developers for debugging.

adv Traces the allocation of and freeing of policy blocks. Used mainly by the GATED developers for debugging.

symbols Traces symbols read from the kernel at startup. The principal way to specify this level of tracing is by the -t option on the command line, because the symbols are read from the kernel before parsing the configuration file.

iflist Traces the reading of the kernel interface list. It is useful to specify this with the -t option on the command line, because the first interface scan is done before reading the configuration file.

**Table A-4 Global Significance Options**
Option	Definition
`parse`	Traces the lexical analyzer and parser. Used mainly by GATED developers for debugging.
`adv`	Traces the allocation of and freeing of policy blocks. Used mainly by the GATED developers for debugging.
`symbols`	Traces symbols read from the kernel at startup. The principal way to specify this level of tracing is by the -t option on the command line, because the symbols are read from the kernel before parsing the configuration file.
`iflist`	Traces the reading of the kernel interface list. It is useful to specify this with the -t option on the command line, because the first interface scan is done before reading the configuration file.

Table A-5 Protocol Significance Options
Option Description

all Turns on all of the options flags.

general A shorthand notation for specifying both normal and route.

state Traces state machine transitions in the protocols.

normal Traces normal protocol occurrences. Abnormal protocol occurrences are always traced.

policy Traces the application of protocol and user-specified policy to routes being imported and exported.

task Traces system interface and processing associated with this protocol or peer.

timer Traces timer usage by this protocol or peer.

route Traces routing table changes for routes installed by this protocol or peer.

**Table A-5 Protocol Significance Options**
Option	Description
`all`	Turns on all of the options flags.
`general`	A shorthand notation for specifying both normal and route.
`state`	Traces state machine transitions in the protocols.
`normal`	Traces normal protocol occurrences. Abnormal protocol occurrences are always traced.
`policy`	Traces the application of protocol and user-specified policy to routes being imported and exported.
`task`	Traces system interface and processing associated with this protocol or peer.
`timer`	Traces timer usage by this protocol or peer.
`route`	Traces routing table changes for routes installed by this protocol or peer.

Note

Not all of these 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).

It is not possible to specify packet tracing from the command line 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 do not 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.

A.7.2 Packet Tracing

Every protocol has one or more options for tracing packets. All protocols allow the packets keyword to be used 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 Specifies a more verbose format to provide more information about the contents of the packet. The detail option must be specified before send or recv . By default, packets are traced in a terse form of one or two lines.

send Limits the tracing to packets sent received. If neither the send nor the recv option is specified, both sent and received packets are traced.

recv Limits the tracing to packets received. If neither the send nor the recv option is specified, both sent and received packets are traced.

Note

If a protocol allows several different types of packet tracing, modifiers can be applied to each individual type. Be aware, however, that within one tracing specification the trace flags are summed up, so specifying detail packets turns on full tracing for all packets.

A.8 Directive Statements

Directive statements provide direction to the GATED 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 semicolon (;), but directive statements terminate with a new line. The two directive statements are as follows:

%directory directory
Defines the directory in which the include files are stored. When it is used, GATED searches the directory identified by path name for any included files that do not have a fully qualified file name (do not begin with "/"). This statement does not change the current directory; it only specifies the prefix applied to included file names.
%include filename
Identifies an include file. The contents of the file is included in the TCPIP$GATED.CONF file at the point where the %include directive is located. If the file name is not fully qualified (does not begin with backslash (/), it is considered to be relative to the directory defined in the %directory directive. The %include directive statement causes the specified file to be parsed completely before resuming with this file. Nesting up to ten levels is supported. The maximum nesting level can be increased by changing the definition of FI_MAX in the parse.h file.

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

A.9 Options Statements

The options statement allows specification of some global options. If used, options must appear before any other type of configuration statement in the TCPIP$GATED.CONF file.

The syntax for the options statement is as follows:

options [nosend] [noresolv] [gendefault [preference preference] [gateway gateway]] [mark time] ;

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

gendefault [preference preference] [gateway gateway]

When gendefault is enabled and a BGP or EGP neighbor is up, a default route with the special protocol default is created. This can be disabled per BGP/EGP group with the nogendefault option. By default, this route has a preference of 20. This route is normally not installed in the kernel forwarding table; it is only present so it can be announced to other protocols.
If a gateway is specified, the default route is installed in the kernel forwarding table with a next hop of the listed gateway.
Note that the use of the more general [generate default] option is preferred to the use of the gendefault option. The gendefault option may be removed in the future. See Section A.18.6 for more information.

nosend Do not send any packets. This option makes it possible to run GATED on a live network to test protocol interactions without actually participating in the routing protocols. The packet traces in the GATED log can be examined to verify that GATED is functioning properly. This is useful for the RIP interface. This option does not apply to BGP and is not useful with EGP and OSPF.

noresolv By default, GATED tries to resolve symbolic names into IP addresses by using the gethostbyname() and getnetbyname() library calls. These calls usually use the Domain Name System (DNS) instead of the host's local host and network tables. If there is insufficient routing information to send DNS queries, GATED deadlocks during startup. This option can be used to prevent these calls; symbolic names result in configuration file errors.

mark time Specifying this option causes GATED to output a message to the trace log at the specified interval. This can be used to determine if GATED is still running.

A.10 Interface Statements

An interface is the connection between a router and one of its attached networks. A physical interface can 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 a wildcard or interface type name. Be careful with the use of interface names because future versions of TCP/IP Services may allow more than one address per interface. 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.

The syntax for the interfaces statement is as follows:

interfaces { options [strictinterfaces] [scaninterval time] [aliases-nexthop ( primary | lowestip | keepall ) ; interface interface_list [preference preference] [down preference preference] [passive] [simplex] [reject] [blackhole] [ AS autonomoussystem ] ; define address [broadcast address] | [pointtopoint address] [netmask mask] [multicast] ; } ;

The options portion of the interfaces statement allows configuration of the following global options related to interfaces:

strictinterfaces Indicates that it is a fatal error to refer to an interface in the configuration file that is not present when GATED is started and not listed in a define statement. Without strictinterfaces , a warning message is issued but GATED will continue.

scaninterval time Specifies how often GATED scans the kernel interface list for changes. The default is every 15 seconds on most systems, and 60 seconds on systems that pass interface status changes through the routing socket (BSD 4.4). Note that GATED also scans the interface list on receipt of a SET GATED/CHECK_INTERFACES.

aliases-nexthop primary | lowestip | keepall

Specifies which address GATED will install as the next hop for interface routes. If you specify primary , the primary interface address (default) will be installed. If you specify lowestip , the address with the lowest IP address will be installed. If you specify keepall , all interface routes are kept in the kernel up to a maximum of RT_N_MULTIPATH routes. aliases-nexthop is a compile-time constant. aliases-nexthop is a global parameter that may be overridden for interfaces using the interface option.

The interface portion of the interfaces statement sets interface options on the specified interfaces. An interface list is all or a list of interface names (see Section A.10.1), domain names, or numeric addresses. Options available on this statement are:

preference preference

Sets the preference for routes to this interface when it is up and appears to be functioning properly. The default preference is 0.

down preference preference

Sets the preference for routes to this interface when GATED does not believe it to be functioning properly, but the kernel does not indicate it is down. The default value is 120.

passive Prevents GATED from changing the preference of the route to this interface if it is not believed to be functioning properly due to lack of received routing information. The GATED daemon only performs this check if the interface is actively participating in a routing protocol.

simplex Defines an interface as unable to hear its own broadcast packets. Some systems define an interface as simplex with the IFF_SIMPLEX flag; others require it to be specified in the configuration file. On simplex interfaces, a sender's own packets are assumed to have been looped back in software and are not used as an indication that the interface is functioning properly.

reject Specifies that the address of the interface matching these criteria is used as the local address when installing reject routes in the kernel.
Use reject only with systems based on BSD 4.3 Tahoe or earlier that have installed a reject/blackhole pseudo-interface.

blackhole Specifies that the address of the interface matching these criteria is used as the local address when installing reject routes in the kernel. Use this only with systems based on BSD 4.3 Tahoe or earlier that have installed a reject/blackhole pseudo interface.

The define portion of the interfaces statement defines interfaces that might not be present when GATED is started so they may be referenced in the configuration file when strictinterfaces is defined. The following are valid define keywords:

broadcast address Defines the interface as broadcast capable (for example, Ethernet or Token Ring) and specifies the broadcast address.

pointopoint address Defines the interface as a point-to-point interface (for example, SLIP or PPP) and specifies the address on the local side. The first address on the define statement references the address of the host on the remote end of the interface, the address specified after this pointopoint keyword defines the address on the local side of the interface.

netmask mask Specifies the subnet mask to be used on this interface. This is ignored on point-to-point interfaces.

multicast Specifies that the interface is multicast capable.

AS autonomoussystem Specifies the AS that will be used to create an AS path associated with the route created from the definition of this interface.

Contents

Index

`detail`	Specifies a more verbose format to provide more information about the contents of the packet. The `detail` option must be specified before `send` or `recv` . By default, packets are traced in a terse form of one or two lines.
`send`	Limits the tracing to packets sent received. If neither the `send` nor the `recv` option is specified, both sent and received packets are traced.
`recv`	Limits the tracing to packets received. If neither the `send` nor the `recv` option is specified, both sent and received packets are traced.

`gendefault` [preference preference] [gateway gateway]
	When `gendefault` is enabled and a BGP or EGP neighbor is up, a default route with the special protocol default is created. This can be disabled per BGP/EGP group with the `nogendefault` option. By default, this route has a preference of 20. This route is normally not installed in the kernel forwarding table; it is only present so it can be announced to other protocols. If a gateway is specified, the default route is installed in the kernel forwarding table with a next hop of the listed gateway. Note that the use of the more general [generate default] option is preferred to the use of the `gendefault` option. The `gendefault` option may be removed in the future. See Section A.18.6 for more information.
`nosend`	Do not send any packets. This option makes it possible to run GATED on a live network to test protocol interactions without actually participating in the routing protocols. The packet traces in the GATED log can be examined to verify that GATED is functioning properly. This is useful for the RIP interface. This option does not apply to BGP and is not useful with EGP and OSPF.
`noresolv`	By default, GATED tries to resolve symbolic names into IP addresses by using the gethostbyname() and getnetbyname() library calls. These calls usually use the Domain Name System (DNS) instead of the host's local host and network tables. If there is insufficient routing information to send DNS queries, GATED deadlocks during startup. This option can be used to prevent these calls; symbolic names result in configuration file errors.
`mark time`	Specifying this option causes GATED to output a message to the trace log at the specified interval. This can be used to determine if GATED is still running.

`strictinterfaces`	Indicates that it is a fatal error to refer to an interface in the configuration file that is not present when GATED is started and not listed in a define statement. Without `strictinterfaces` , a warning message is issued but GATED will continue.
`scaninterval time`	Specifies how often GATED scans the kernel interface list for changes. The default is every 15 seconds on most systems, and 60 seconds on systems that pass interface status changes through the routing socket (BSD 4.4). Note that GATED also scans the interface list on receipt of a SET GATED/CHECK_INTERFACES.
`aliases-nexthop primary \| lowestip \| keepall`
	Specifies which address GATED will install as the next hop for interface routes. If you specify `primary` , the primary interface address (default) will be installed. If you specify `lowestip` , the address with the lowest IP address will be installed. If you specify `keepall` , all interface routes are kept in the kernel up to a maximum of RT_N_MULTIPATH routes. `aliases-nexthop` is a compile-time constant. `aliases-nexthop` is a global parameter that may be overridden for interfaces using the interface option.

`preference preference`
	Sets the preference for routes to this interface when it is up and appears to be functioning properly. The default preference is 0.
`down preference preference`
	Sets the preference for routes to this interface when GATED does not believe it to be functioning properly, but the kernel does not indicate it is down. The default value is 120.
`passive`	Prevents GATED from changing the preference of the route to this interface if it is not believed to be functioning properly due to lack of received routing information. The GATED daemon only performs this check if the interface is actively participating in a routing protocol.
`simplex`	Defines an interface as unable to hear its own broadcast packets. Some systems define an interface as simplex with the IFF_SIMPLEX flag; others require it to be specified in the configuration file. On simplex interfaces, a sender's own packets are assumed to have been looped back in software and are not used as an indication that the interface is functioning properly.
`reject`	Specifies that the address of the interface matching these criteria is used as the local address when installing reject routes in the kernel. Use `reject` only with systems based on BSD 4.3 Tahoe or earlier that have installed a reject/blackhole pseudo-interface.
`blackhole`	Specifies that the address of the interface matching these criteria is used as the local address when installing reject routes in the kernel. Use this only with systems based on BSD 4.3 Tahoe or earlier that have installed a reject/blackhole pseudo interface.

`broadcast address`	Defines the interface as broadcast capable (for example, Ethernet or Token Ring) and specifies the broadcast address.
`pointopoint address`	Defines the interface as a point-to-point interface (for example, SLIP or PPP) and specifies the address on the local side. The first address on the define statement references the address of the host on the remote end of the interface, the address specified after this pointopoint keyword defines the address on the local side of the interface.
`netmask mask`	Specifies the subnet mask to be used on this interface. This is ignored on point-to-point interfaces.
`multicast`	Specifies that the interface is multicast capable.
`AS autonomoussystem`	Specifies the AS that will be used to create an AS path associated with the route created from the definition of this interface.

Compaq TCP/IP Services for OpenVMSManagement