Trace Statements

Trace statements allow you to control the trace file and its contents from within the gated.conf file. The trace statement is:

traceoptions ["trace_file" [replace] [size bytes[k|m] files n]] [nostamp] trace_options [except trace_options] ;

Its components are as follows:

• trace_file
• Identifies the file that receives the trace output. It has exactly the same function as the trace_file argument on the gated command line.
• replace
• Replaces the existing trace file. If you do not use this keyword, the trace output is appended to the current contents of the file.
• size bytes[k|m] [files n]
• Limits the trace file to a maximum size of bytes. The optional k or m indicates thousands (k) or millions (m) of bytes. Thus and m are equivalent entries. The size of the trace file cannot be less than 10k bytes. n defines the maximum number of trace files that should be saved. When the trace file reaches the maximum size, it is saved as trace_file.0, trace_file.1, trace_file.2 up to trace_file.n. The next save then overwrites trace_file.0. The value for n must be at least 2.
• nostamp
• Specifies that trace lines should not begin with a timestamp. Timestamping each line of trace data is the default.
• trace_options
• Defines the events to be traced by gated. Each trace option is specified by a keyword name. The available trace options are:
  • none
  • Turns off all tracing.
  • all
  • Turns on all types of global tracing.
  • general
  • Turns on both normal and route tracing.
  • state
  • Traces state machine transitions for protocols such as OSPF and BGP. The RFCs describe these protocols using finite state machine (FSM) diagrams or tables. The protocols transition from one state to another based on the occurrence of certain events. For example, the state might change from idle to connect when a connection open event occurs. This is a highly specialized trace flag, useful only to those who have a thorough understanding of the protocols involved. Use this option within the protocol statement to trace a specific protocol's transitions.
  • normal
  • Traces normal protocol interactions. Errors are always traced.
  • policy
  • Traces the application of routing policies. Use this to check that you have properly configured your routing policy.
  • task
  • Traces system-level processing.
  • timer
  • Traces the various timers used by a protocol or peer.
  • route
  • Traces routing table changes. Use this to check that routes are properly installed by the protocol.
  • detail
  • Traces the contents of the packets exchanged by the router. Must be specified before send or recv.
  • send
  • Limits the detail trace to packets sent by this router.
  • recv
  • Limits the detail trace to packets received by this router. Without these two options, all packets are traced when detail is specified.
  • symbols
  • Traces the symbols read from the kernel at startup. See the -t command-line argument.
  • iflist
  • Traces the kernel interface list. See the -t command-line argument.
  • parse
  • Traces the lexical analyzer and parser.
  • adv
  • Traces the allocation and release of blocks.
• except trace_options
• Disables specific trace options. Must be used in conjunction with trace_options that enable a wide variety of tracing. For example, traceoptions all except state turns on all traces except for finite state machine tracing.

gated provides the flexibility for you to choose where you want to control tracing -- on the command line or in the configuration file. By and large, the same trace options can be set on the gated command line or in the configuration file. detail, send, and recv can be set only in the configuration file.

Two others, symbols and iflist, are primarily used on the command line. Refer to the section on the gated command for a description of setting trace options with -t.

Some trace options are useful only for protocol developers and other experts. For most of us, general, which enables normal and route tracing, is an appropriate level of information for debugging routing problems. Occasionally, policy is useful for testing a routing policy. Most of the time, however, no tracing is needed.