7.3 gdc
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 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 gdmaintgroup) 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.
7.3.1 Command-line Options
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 purposes:
- 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.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 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.
The following command allows the version information for gated to be displayed:
- version
- Show the version information for GateD. GateD cannot already be running at the time
this command is executed. No options of gdc are used with this command.
7.3.2 Related 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.
7.3.3 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).
AUTHOR
Dennis Ferguson <dennis@ans.net>
SEE ALSO
gated (8)
, ospf_monitor (8), ripquery (8), routed (8), route (8)syslog (8)
GateD Documentation
GateD Configuration Guide COPYRIGHT INFORMATION
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 California., all rights reserved.;
<!--
------------------------------------------------------------------------ GateD, Release 4.0 Copyright (c)
1996 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. Merit GateDaemon Project 4251 Plymouth Road, Suite C
Ann Arbor, MI 48105 THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE REGENTS OF THE UNIVERSITY OF MICHIGAN AND MERIT DO NOT WARRANT
THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET LICENSEE'S
REQUIREMENTS OR THAT OPERATION WILL BE UNINTERRUPTED OR ERROR FREE.
The Regents of the University of Michigan and Merit shall not be liable for any special, indirect,
incidental or consequential damages with respect to any claim by Licensee or any third party
arising from use of the software. GateDaemon was originated and developed through release 3.0
by Cornell University and its collaborators. Please forward bug fixes, enhancements and
questions to the gated mailing list: gated-people@gated.merit.edu.
------------------------------------------------------------------------ Portions of this software may
fall under the following copyrights: Copyright (c) 1988 Regents of the University of
California. All rights reserved. Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are duplicated in all such forms
and that any documentation, advertising materials, and other materials related to such
distribution and use acknowledge that the software was developed by the University of
California, Berkeley. The name of the University may not be used to endorse or promote
products derived from this software without specific prior written permission. THIS SOFTWARE
IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. >
Last updated April 27, 1997
gated@gated.merit.edu