Purpose
Provides an operational user interface
for gated.
Description
The gdc command provides
a user-oriented interface for the operation of the gated routing
daemon. It provides support for:
- starting and stopping the daemon
- the delivery of signals to manipulate the daemon when it is operating
- the maintenance and syntax checking of configuration files
- for the production and removal of state dumps and core dumps.
The gdc command can reliably determine gated's running state and produces a reliable exit status when errors
occur, making it advantageous for use in shell scripts which manipulate gated. Commands executed using gdc and, optionally, error
messages produced by the execution of those commands, are logged via
the same syslogd facility which gated itself uses, providing
an audit trail of operations performed on the daemon.
Flags
| Item |
Description |
| -n |
Runs without changing the kernel forwarding table. This is
useful for testing, and when operating as a route server which does
no forwarding. |
| -q |
Runs quietly. With this flag informational messages which
are normally printed to the standard output are suppressed and error
messages are logged with syslogd instead of being printed
to the standard error output. This is convenient when running gdc from a shell script. |
| -t seconds |
Specifies the time in seconds that gdc waits for gated to complete certain operations, in particular at termination
and startup. By default this value is set to 10 seconds. |
| -c coresize |
Sets the maximum size of a core dump a gated started
with gdc produces. This is useful on systems where the default
maximum core dump size is too small for gated to produce a
full core dump on errors. |
| -f filesize |
Sets the maximum file size a gated started with gdc will produce. Useful on systems where the default maximum
file dump size is too small for gated to produce a full state
dump when requested. |
| -m datasize |
Sets the maximum size of the data segment of a gated started with gdc. Useful on systems where the default data
segment size is too small for gated to run. |
| -s stacksize |
Sets the maximum size of stack of a gated started with gdc. Useful on systems where the default maximum stack size is
too small for gated to run. |
Subcommands
The following subcommands cause signals to be delivered to
gated for various purpose:
| Item |
Description |
| COREDUMP |
Sends an abort signal to gated, causing it to terminate
with a core dump. |
| dump |
Signals gated to dump its current state into the file /var/tmp/gated_dump. |
| interface |
Signals gated to recheck the interface configuration. gated normally does this
periodically in any event, but the facility can be used to force the daemon to check interface
status immediately when changes are known to have occurred. |
| KILL |
Causes gated to terminate ungracefully. |
| reconfig |
Signals gated to reread its configuration file, reconfiguring
its current state as appropriate. |
| term |
Signals gated to terminate after shutting down all
operating routing protocols gracefully. Executing this command a second
time causes gated to terminate even if some protocols have
not yet fully shut down. |
| toggletrace |
Causes tracing to be suspended, and if gated is currently
tracing to a file, closes the trace file. If gated tracing
is current suspended, this subcommand causes the trace file to be
reopened and tracing initiated. This is useful for moving trace files. |
The following subcommands perform operations related to configuration
files:
| Item |
Description |
| checkconf |
Check /etc/gated.conf for syntax errors. This is usefully
done after changes to the configuration file but before sending a reconfig signal to the currently running gated, to ensure
that there are no errors in the configuration which would cause the
running gated to terminate on reconfiguration. When this command
is used, gdc issues an informational message indicating whether
there were parse errors or not, and if so saves the error output in
a file for inspection. |
| checknew |
Like checkconf except that the new configuration
file, /etc/gated.conf+, is checked instead. |
| newconf |
Move the /etc/gated.conf+ file into place as /etc/gated.conf, retaining the older versions of the file as described above. gdc will decline to do anything when given this command if the new configuration file doesn't exist or otherwise looks suspect. |
| backout |
Rotate the configuration files in the newer direction,
in effect moving the old configuration file to /etc/gated.conf. The command will decline to perform the operation if /etc/gated.conf- doesn't exist or is zero length, or if the operation would delete
an existing, non-zero length /etc/gated.conf+ file. |
| BACKOUT |
Perform a backout operation even if /etc/gated.conf+ exists and is of non-zero length. |
| modeconf |
Set all configuration files to mode 664, owner root, group
system. |
| createconf |
If /etc/gated.conf+ does not exist, create a zero length
file with the file mode set to 664, owner root, group system. |
The following subcommands provide support for starting and
stopping
gated, and for determining its running state:
| Item |
Description |
| running |
Determine if gated is currently running. This is done
by checking to see if gated has a lock on the file containing
its pid, if the pid in the file is sensible and if there is a running
process with that pid. Exits with zero status if gated is
running, non-zero otherwise. |
| start |
Start gated. The command returns an error if gated is already running. Otherwise it executes the gated binary
and waits for up to the delay interval (10 seconds by default, as
set with the -t option otherwise) until the newly started process
obtains a lock on the pid file. A non-zero exit status is returned
if an error is detected while executing the binary, or if a lock is
not obtained on the pid file within the specified wait time. |
| stop |
Stop gated, gracefully if possible, ungracefully if not. The command returns an error
(with non-zero exit status) if gated is not currently running. Otherwise it sends a terminate
signal to gated and waits for up to the delay interval (10 seconds by default, as specified
with the -t option otherwise) for the process to exit. Should gated fail to exit
within the delay interval it is then signaled again with a second terminate signal. Should it fail
to exit by the end of the second delay interval it is signaled for a third time with a kill signal.
This should force immediate termination unless something is very broken. The command terminates with
zero exit status when it detects that gated has terminated, non-zero otherwise. |
| restart |
If gated is running it is terminated via the same procedure
as is used for the stop command above. When the previous gated terminates, or if it was not running prior to command execution,
a new gated process is executed using the procedures described
for the start command above. A non-zero exit status is returned
if any step in this procedure appears to have failed. |
The following subcommands allow the removal of files created
by the execution of some of the commands above:
| Item |
Description |
| rmcore |
Removes any existing gated core dump file. |
| rmdump |
Removes any existing gated state dump file. |
| rmparse |
Removes the parse error file generated when a checkconf or checknew command is executed and syntax errors are encountered
in the configuration file being checked. |
By default
gated obtains its configuration from a
file normally named
/etc/gated.conf. The
gdc program
also maintains several other versions of the configuration file, in
particular named:
| Item |
Description |
| /etc/gated.conf+ |
The new configuration file. When gdc is requested
to install a new configuration file, this file is renamed /etc/gated.conf. |
| /etc/gated.conf- |
The old configuration file. When gdc is requested
to install a new configuration file, the previous /etc/gated.conf is renamed to this name. |
| /etc/gated.conf— |
The really old configuration file. gdc retains the
previous old configuration file under this name. |
Files
| Item |
Description |
| /usr/sbin/gated |
The gated binary. |
| /etc/gated.conf |
Current gated configuration file. |
| /etc/gated.conf+ |
Newer configuration file. |
| /etc/gated.conf- |
Older configuration file |
| /etc/gated.conf— |
Much older configuration file |
| /etc/gated.pid |
Where gated stores its pid. |
| /var/tmp/gated_dump |
gated's state dump file |
| /var/tmp/gated.log |
Where config file parse errors go. |