Gdc provides a user-oriented interface for the operation of the
gated (8) routing daemon. It provides support for starting and
stopping the daemon, for the delivery of signals to manipulate the
daemon when it is operating, for the maintenance and syntax checking of
configuration files, and for the production and removal of state dumps
and core dumps.
Gdc 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(8) facility which gated itself uses, providing an
audit trail of operations performed on the daemon.
If installed as a setuid root program gdc will allow non-root
users who are members of a trusted group (by default the gdmaint
group) to manipulate the routing daemon while denying access to
others. The name of the user is logged along via syslogd(8)
along with an indication of each command executed, for audit purposes.
The command-line options are:
-n
Run without changing the kernel forwarding table. Useful for
testing, and when operating as a route server which does no
forwarding.
-q
Run quietly. With this option informational messages which are
normally printed to the standard output are suppressed and error
messages are logged via syslogd(8) instead of being
printed to the standard error output. This is often convenient
when running gdc from a shell script.
-t seconds
Specifies the time in seconds which gdc will
spend waiting for gated to complete certain operations,
in particular at termination and startup. By default this value
is set to 10 seconds.
These additional command-line options may be present, depending on the
options used to compile gdc:
-c coresize
Sets the maximum size of a core dump a gated started
with gdc will produce. 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.
The following commands cause signals to be delivered to gated
for various purpose:
COREDUMP
Sends an abort signal to gated, causing it to terminate with
a core dump.
dump
Signal gated to dump its current state into the file
/usr/tmp/gated_dump.
interface
Signal 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
Cause gated to terminate ungracefully. Normally useful
when the daemon has hung.
reconfig
Signal gated to reread its configuration file,
reconfiguring its current state as appropriate.
term
Signal gated to terminate after shutting down all
operating routing protocols gracefully. Executing this command a
second time should cause gated to terminate even if some
protocols have not yet fully shut down.
toggletrace
If gated is currently tracing to a file, cause tracing
to be suspended and the trace file to be closed. If
gated tracing is current suspended, cause the trace file
to be reopened and tracing initiated. This is useful for moving
trace files.
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:
/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.
The following commands perform operations related to configuration files:
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
gdmaint. This allows a trusted non-root user to modify the
configuration files.
createconf
If /etc/gated.conf+ does not exist, create a zero length
file with the file mode set to 664, owner root, group gdmaint.
This allows a trusted non-root user to install a new
configuration file.
The following commands provide support for starting and stopping
gated, and for determining its running state:
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 commands allow the removal of files created by the
execution of some of the commands above:
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.
Many of default filenames listed below contain the string %s, which is
replaced by the name with which gated is invoked. Normally this is
gated, but if invoked as gated-test, gated will by
default look for /etc/gated-test.conf. These paths may all be
changed at compilation time.
/etc/gated
the gated binary. Another popular location is
/usr/local/sbin/gated.
/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, the default is
/etc/%s.pid. Another popular location is
/var/run/%s.pid.
/usr/tmp/gated_dump
gated's state dump file, the default is
/usr/tmp/%s_dump. Another popular location is
/var/tmp/%s_dump.
/usr/tmp/gated_parse
where config file parse errors go, the default is
/usr/tmp/%s_parse. Another popular location is
/var/tmp/%s_parse.
/usr/tmp
where gated drops its core file. Another popular
location is /var/tmp. The core file is usually
core, but some systems use core.gated.
