A gated Reference (TCP/IP Network Administration, 3rd Edition)

This appendix covers the syntax of the gated command and the gated configuration language for Gated 3.6 -- the publicly available version of gated. As a reference to the gated configuration language, this appendix stands on its own. But to fully understand how to configure gated, use this reference in conjunction with the sample configuration files in Chapter 7, "Configuring Routing ".

gated is constantly being improved. As it is upgraded, the command language changes. Refer to the latest manpages for the most recent information about gated.

B.1. The gated Command

The syntax of the gated command is:

gated [-v] [-c] [-C] [-n] [-N] [-t trace_options] [-f config_file] [trace_file]

The -c and -n command-line options debug the routing configuration file without impacting the network or the kernel routing table. Frequently, these debugging options are used with a test configuration identified by the -f config_file option:

-c: Tells gated to read the configuration file and check for syntax errors. When gated finishes reading the configuration file, it produces a snapshot of its status and then terminates. It writes the snapshot to /usr/tmp/gated_dump. Running gated with the -c option does not require superuser privileges, and it is not necessary to terminate the active gated process.
-C: Checks the configuration file for syntax errors. gated exits with a status 1 if there are errors and 0 if there are none. Because this provides exit status, it is useful for script files.
-n: Tells gated not to update the kernel routing table. This is used to test the routing configuration with real routing data without interfering with system operation.
-f config_file: Tells gated to read the configuration from config_file instead of from the default configuration file, /etc/gated.conf. Used in conjunction with the -c option, -f checks a new configuration without interfering with the currently running gated configuration.

The -v option causes gated to display its version number. When this is used, no other options are used because gated terminates immediately after displaying the version information.

The -N command-line option prevents gated from running in background mode as a daemon. This option is used when gated is started from inittab. By default, gated runs as a daemon.

The command-line arguments trace_options and trace_file are used for protocol tracing. The trace_file argument names the file to which the trace output is written. If a file is not specified, the trace is written to the standard output. Tracing usually produces a large amount of output.

The command-line options used for tracing are:

-t

This option turns on tracing. If -t is specified with no trace_options, gated defaults to general tracing, which traces normal protocol interactions and routing table changes. gated always logs protocol errors even if no tracing is specified. You can define several different trace_options, all of which are described later in this appendix. A few trace_options (detail, send, recv) cannot be specified on the gated command line. Two others are most useful when they are defined on the command line:

symbols: Traces the symbols read from the kernel, which is primarily of interest to developers debugging the interaction of gated and the kernel.
iflist: Traces the list of interfaces read from the kernel. Use this to determine what interfaces are detected by the kernel interface scan.

The advantage of placing a trace option on the command line is that it can trace activities that happen before the configuration file is processed. For the two options listed above, this is an essential advantage. For other options, it is not very important. Most trace options are specified in the configuration file. See the traceoptions command later in this appendix for more details.

B.1.1. Signal Processing

gated processes the following signals:

SIGHUP: Tells gated to reread the configuration file. The new configuration replaces the one that gated is currently running. SIGHUP loads the new configuration file without interrupting gated service. SIGHUP is available for quick configuration changes. At most sites, the routing configuration changes infrequently. The few times you need to change to a new configuration, terminate gated and rerun it with the new configuration. This is a more accurate test of how things will run at the next boot.
SIGINT: Tells gated to snapshot its current state to the file /usr/tmp/gated_dump.
SIGTERM: Tells gated to shut down gracefully. All protocols are shut down following the rules of that protocol. For example, EGP sends a CEASE message and waits for it to be confirmed. SIGTERM removes from the kernel routing table all routes learned via the exterior routing protocols. If you need to preserve those routes while gated is out of operation, use SIGKILL.
SIGKILL: Tells gated to terminate immediately and dump core. Routes are not removed from the routing table, and no graceful shutdown is attempted.
SIGUSR1: Tells gated to toggle tracing. If no trace flags are set, SIGUSR1 has no effect. But if tracing is enabled, the first SIGUSR1 causes gated to toggle off tracing and to close the trace file. The next SIGUSR1 turns tracing back on and opens the trace file. When the trace file is closed, it can be moved or removed without interfering with the operation of gated. Use this to periodically empty out the trace file to prevent it from becoming too large.
SIGUSR2: Tells gated to check for changes in the status of the network interfaces.

The following is an example of gated signal handling. First, the SIGUSR1 signal is passed to the gated process using the process ID obtained from the gated.pid file (/var/run/gated.pid in this case).

# kill -USR1 'cat /var/run/gated.pid'

Next, the old trace file (/usr/tmp/gated.log in this case) is removed, and gated is passed another SIGUSR1 signal.

# rm /usr/tmp/gated.log
# kill -USR1 'cat /etc/gated.pid'

After receiving the second signal, gated opens a fresh trace file (still named /usr/tmp/gated.log). An ls shows that the new file has been created.

# ls -l /usr/tmp/gated.log
-rw-rw-r--  1 root          105 Jul  6 16:41 /usr/tmp/gated.log

Appendix B. A gated Reference

Contents:

B.1. The gated Command

B.1.1. Signal Processing