# Trace Statements

Trace statements control tracing options. GateD's tracing options may be configured at many levels. Tracing options include the file specifications, control options, and global and protocol specific tracing options. Unless overridden, tracing options from the next higher level are inherited by lower levels. For example, BGP peer tracing options are inherited from BGP group tracing options, which are inherited from global BGP tracing options, which are inherited from global GateD tracing options. At each level tracing specifications override the inherited options.

## Global tracing options

There are two types of global options, those which only affect global operations and those which have potential significance to protocols.

### Global significance only

The trace flags that only have global significance are:

parse
  Trace the lexical analyzer and parser. Mostly used by GateD developers for debugging.
adv
  Trace the allocation of and freeing of policy blocks. Mostly used by the GateD developers for debugging.
symbols
  Used to trace symbols read from the kernel at startup. The only useful way to specify this level of tracing is via the `-t` option on the command line since the symbols are read from the kernel before parsing the configuration file.
iflist
  Used to trace the reading of the kernel interface list. It is useful to specify this with the `-t` option on the command line since the first interface scan is done before reading the configuration file.

### Protocol significance

The options flags that have potential significance to protocols are:

all
  Turn on all of the following.
general
  A shorthand notation for specifying both `normal` and `route`.
state
  Trace state machine transitions in the protocols.
normal
  Trace normal protocols occurrences. Abnormal protocol occurrences are always traced.
policy
  Trace application of protocol and user-specified policy to routes being imported and exported.
task
  Trace system interface and processing associated with this protocol or peer.
timer
  Trace timer usage by this protocol or peer.
route
  Trace routing table changes for routes installed by this protocol or peer.

Not all of the above options apply to all of the protocols. In some cases their use does not make sense (for instance, RIP does not have a state machine) and in some instances the requested tracing has not been implemented (such as RIP support of the `policy` option).

It is not currently possible to specify packet tracing from the command line. This is because a global option for packet tracing would potentially create too much output.

When protocols inherit their tracing options from the global tracing options, tracing levels that don't make sense (such as `parse`, `adv` and packet tracing options) are masked out.

Global tracing statements have an immediate effect, especially parsing options that effect the parsing of the configuration file. Tracing values inherited by protocols specified in the configuration file are initially inherited from the global options in effect as they are parsed, unless they are overridden by more specific options. After the configuration file is read, tracing options that were not explicitly specified are inherited from the global options in effect at the end of the configuration file.

## Packet tracing

Tracing of packets is very flexible. For any given protocol there are one or more options for tracing packets. all protocols allow use of the packets keyword allows for tracing all packets sent and received by the protocol. most protocols have other options for limiting tracing to a useful subset of packet types. These tracing options can be further controlled with the following modifiers:

detail
  `detail` must be specified before `send` or `recv`. Normally packets are traced in a terse form of one or two lines. When `detail` is specified, a more verbose format is used to provide further detail on the contents of the packet.
send
recv
  These options limit the tracing to packets sent or received. Without these options both sent and received packets will be traced.

`Detail`, if specified, must be before `send` or `recv`. If a protocol allows for several different types of packet tracing, modifiers may be applied to each individual type. But be aware that within one tracing specification the trace flags are summed up, so specifying `detail packets` will turn on full tracing for all packets.

## Traceoptions syntax

        traceoptions ["trace_file" [replace] [size size[k|m] files files]]
    	[control_options] trace_options [except trace_options] ;

        traceoptions none ;

trace_file
  Specifies the file to receive tracing information. If this file name does not begin with a slash (/) the directory where gated was started in prepended to the name.
replace
  Tracing should start by replacing an existing file. The default is to append to an existing file.
size size[k|m] files files
  Limit the maximum size of the trace file to the specified size (mimimum 10k). When the trace file reaches the specified size, it is renamed to `file.0`, then `file.1`, `file.2` up to the maximum number of files (minimum specification is 2).
control_options
  Specifies options that control the appearance of tracing. Valid values are:
  nostamp
    Specifies that a timestamp should not be prepended to all trace lines.
except trace_options
  Used to enable a broad class of tracing and then disable more specific options.
none
  Specifies that all tracing should be turned off for this protocol or peer.

Last updated 1994/03/16 21:38:49.