GDC(8)
NAME
gdc - operational user interface for gated (8)
SYNOPSIS
gdc [ -q ] [ -n ] [ -c coresize ] [ -f filesize ] [ -m
datasize ] [ -s stacksize ] [ -t seconds ] command
DESCRIPTION
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 sig-
nals 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 run-
ning 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) facil-
ity 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 mes-
sages 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 maxi-
mum 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 configura-
tion. 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 occured.
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. Exe-
cuting 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 reopenned and tracing
initiated. This is useful for moving trace
files.
By default gated obtains its configuration from a file
normally named /etc/gated.config. 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 con-
figuration 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 recon-
figuration. 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 inspec-
tion.
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 configura-
tion 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 configu-
ration 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 pro-
cess 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 run-
ning. 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 signalled
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 ter-
minated, 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 execu-
tion, 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 configura-
tion file being checked.
FILES
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.
AUTHOR
Dennis Ferguson <A HREF="MAILTO:lt;dennis@ans.net">lt;dennis@ans.net</A>
SEE ALSO
gated(8) ospf_monitor(8) ripquery(8) routed(8)
route(8) syslog(8)
GateD Documentation
GateD Configuration Guide
BUGS
Many commands only work when gated is installed in the
system directory it was configured with.
There is not yet any way to tell gdc about systems which
name their core dump other than core (core.gated is a less
common possibility).
COPYRIGHT INFORMATION
Copyright (c) 1996, 1997 The Regents of the University of
Michigan
All Rights Reserved
License to use, copy, modify, and distribute this software
and its documentation can be obtained from Merit at the
University of Michigan.
This package and associated documentation is Copyright (c)
1990,1991,1992,1993,1994,1995 Cornell University., all
rights reserved. This software contains code that is
Copyright (c) 1988 Regents of the University of Califor-
nia., all rights reserved.;