rtrmgr.tex

xorp源码hg

  \item{\tt bool}\\
  Boolean - valid values are {\tt true} and {\tt false}.

  \item{\tt toggle}\\
  Similar to boolean, but requires a default value.  Display of the
  config tree node is suppressed if the value is the default.

  \item{\tt ipv4}\\
  An IPv4 address in dotted decimal format.

  \item{\tt ipv4net}\\
  An IPv4 address and prefix length in the
  conventional format.  E.g.: {\tt 1.2.3.4/24}.

  \item{\tt ipv4range}\\
  A range of IPv4 addresses defined by an upper and lower inclusive boundary.
  IPv4 addresses are specified in dotted decimal format delimited by two dots,
  e.g. {\tt 1.2.3.4..5.6.7.8}. If upper and lower boundaries are equal it is
  sufficient to specify only a single value, e.g. {\tt 1.2.3.4}.

  \item{\tt ipv6}\\
  An IPv6 address in the canonical colon-separated human-readable format.

  \item{\tt ipv6net}\\
  An IPv6 address and prefix in the conventional format.
  E.g.: {\tt fe80::1/64}

  \item{\tt ipv6range}\\
  A range of IPv6 addresses defined by an upper and lower inclusive boundary.
  IPv6 addresses are specified in colon-separated format and are delimited
  by two dots, e.g. {\tt fe80::1234..fe80::5678}.
  If upper and lower boundaries are equal it is
  sufficient to specify only a single value, e.g. {\tt fe80::1234}.

  \item{\tt macaddr}\\
  An MAC address in the conventional colon-separated hex format.
  E.g.: {\tt 00:c0:4f:68:8c:58}

  \item{\tt com32}\\
  Unsigned 32 bit integer representing a BGP community tag.  It can be
  specified either in a colon-separated format using two 16 bit integers,
  e.g. {\tt 65001:1}, or as a single 32 bit unsigned integer.

\end{description}

It is likely that additional types will be added in the future, as
they are found to be needed.

\subsection{Template Tree Commands}
This section provides a complete listing of all the template tree
commands that the rtrmgr supports.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%modinfo} Command.}

The sub-commands to the {\tt \%modinfo} command are:

\begin{description}

  \item {{\tt \%modinfo: provides }{\it ModuleName}} \\
  The {\tt provides} subcommand takes one additional parameter, which gives the
  name of the module providing the functionality rooted at this node.

  \item {{\tt \%modinfo: depends }{\it list of modules}} \\
  The {\tt depends} subcommand takes at least one additional
  parameter, giving a list of the other modules that must
  be running and configured before this module may be started.

  \item {{\tt \%modinfo: path }{\it ProgramPath}} \\
  The {\tt path} subcommand takes one additional parameter giving the pathname
  of the software to be run
  to provide this functionality.  The pathname may be absolute or
  relative to the root of the XORP tree. The ordering in computing the root of
  the tree is: (a) the shell environment XORP\_ROOT (if exists); (b) the parent
  directory the rtrmgr is run from (only if it contains the
  etc/templates and the xrl/targets directories); (c) the XORP\_ROOT value as
  defined in config.h (currently this is the installation directory, and
  defaults to ``/usr/local/xorp'').

  \item {{\tt \%modinfo: default\_targetname }{\it TargetName}} \\
  The {\tt default\_targetname} subcommand takes one additional parameter
  giving the value of the XRL target name that should be used by default when
  validating an XRL specification (\eg if the specification uses a variable
  inside that module to specify the XRL target name).

  \item {{\tt \%modinfo: start\_commit }{\it method }{\it argument}} \\
  The {\tt start\_commit} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be call before performing any
  change to the configuration of the module. The only methods currently
  supported are {\tt xrl} which takes an XRL specification as an argument, and
  {\tt program} which takes an executable program as an argument.

  \item {{\tt \%modinfo: end\_commit }{\it method }{\it argument}} \\
  The {\tt end\_commit} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be called to complete any change
  to the configuration of the module. The only methods currently supported are
  {\tt xrl} which takes an XRL specification as an argument, and {\tt program}
  which takes an executable program as an argument.
  Both {\tt start\_commit} and {\tt end\_commit} are optional. They provide a
  way to make batch changes to a module configuration as an atomic operation.

  \item {{\tt \%modinfo: status\_method }{\it method }{\it argument}} \\
  The {\tt status\_method} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be used to discover the status of
  the module.
  The only methods current supported are {\tt xrl} which takes an XRL
  specification as an argument, and {\tt program} which takes an executable
  program as an argument.

  \item {{\tt \%modinfo: startup\_method }{\it method }{\it argument}} \\
  The {\tt startup\_method} subcommand takes two or more additional parameters,
  that are used to specify the mechanism to be used to gracefully startup the
  module. The only methods current supported are {\tt xrl} which takes an XRL
  specification as an argument, and {\tt program} which takes an executable
  program as an argument.

  Before the {\tt startup\_method} subcommand is called, it is expected
  that the process is in {\tt PROC\_STARTUP} state; after the subcommand
  is called the process should transition to the {\tt PROC\_READY} state.
  Note that this subcommand is optional and if it is not specified, then
  it is expected that the process will transition on its own to the
  {\tt PROC\_READY} state.

  \item {{\tt \%modinfo: shutdown\_method }{\it method }{\it argument}} \\
  The {\tt shutdown\_method} subcommand takes two or more additional
  parameters, that are used to specify the mechanism to be used to gracefully
  shutdown the module. The only methods current supported are {\tt xrl} which
  takes an XRL specification as an argument, and {\tt program} which takes an
  executable program as an argument.
  If the process does not then transition to {\tt PROC\_SHUTDOWN} state, the
  rtrmgr will then kill the process.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%mandatory} Command.}

{\tt \%mandatory} is used to specify the list of nodes or variables
that must be configured in the user configuration file or that must
have a default value. This command can appear multiple times anywhere in the
template tree. If it appears multiple times within the same template node,
then all listed nodes are mandatory. However, note that it cannot be used
to specify a multi-value node such as\\
{\tt \$(interfaces.interface.@.vif.@.address.@)}.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%create} Command.}

{\tt \%create} is used to create a new instance of an interior node in
the configuration tree.

\begin{itemize}

  \item The first parameter indicates the form of
  action to take to perform this action - typically it is {\tt xrl}
  which indicates an XRL should be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to create the new configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to create the new configuration tree instance of this
  template tree node. 

\end{itemize}

Note that if a node has no {\tt \%create} command, then the {\tt \%set}
command (if exists) for that node is used instead (see below).

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%activate} Command.}

{\tt \%activate} is used to activate a new instance of an interior
node in the configuration tree.  It is typically paired with {\tt
\%create} - the {\tt \%create} command is executed before the relevant
configuration of the node's children has been performed, whereas {\tt
\%activate} is executed after the node's children have been
configured.  A particular interior node might have either {\tt
\%create}, {\tt \%activate} or both.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to activate the new configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to activate the new configuration tree instance of this
  template tree node.

\end{itemize}

For example, if the template tree held the following:

\begin{tabbing}
\tt addr\=\tt ess \=\tt@: ipv4 \{\\
    \>\tt\%create: xrl {\it XRL1};\\
    \>\tt\%activate: xrl {\it XRL2};\\
    \>\tt netmask: ipv4 \{\\
        \>\>\tt\%set: xrl {\it XRL3};\\
    \>\tt\}\\
\tt\}
\end{tabbing}

Then when an instance of address and netmask are created and
configured, the execution order of the XRLs will be: {\it XRL1, XRL3, XRL2}.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%update} Command.}

{\tt \%update} is used to update an existing instance of a
node in the configuration tree.  It is typically paired with {\tt
\%activate} - the {\tt \%activate} command is executed
after the node's children have been configured for very first time (\eg on
startup), whereas {\tt \%update} is executed if some of the node's children
have been modified (\eg via xorpsh).

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to update the configuration tree instance of this template tree
  node.

  \item If the action is {\tt program}, then the second parameter specifies
  the program to execute to update the configuration tree instance of this
  template tree node.

\end{itemize}

Note that if the value of a node is modified, only the closest {\tt \%update}
command up in the hierarchy is executed. For example, if the template tree
held the following:

\begin{tabbing}
\tt addr\=\tt ess \=\tt@: i\=\tt pv4 \{\\
    \>\tt\%create: xrl {\it XRL1};\\
    \>\tt\%activate: xrl {\it XRL2};\\
    \>\tt\%update: xrl {\it XRL3};\\
    \>\tt netmask: ipv4 \{\\
        \>\>\tt\%update: xrl {\it XRL4};\\
        \>\>\tt disable: bool \{\\
             \>\>\>\tt\%set:;\\
        \>\>\tt\}\\
    \>\tt\}\\
    \>\tt broadcast: ipv4 \{\\
        \>\>\tt\%set:;\\
    \>\tt\}\\
\tt\}
\end{tabbing}

Then when the value of {\tt disable} is modified, only
{\it XRL4} will be called. If the value of {\tt broadcast} is modified,
then {\it XRL3} will be called.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%list} Command.}

{\tt \%list} is called to obtain a list of all the configuration tree
instances of a particular template tree node.  For example, a
particular template tree node might represent the interfaces on a
router.  The configuration tree would then contain an instance of this
node for each interface currently configured.  The {\tt \%list}
command on this node would then return the list of interfaces.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to return the list.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to return the list.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%

\subsubsection{The {\tt \%delete} Command.}
{\tt \%delete} is called to delete a configuration tree node and all its
children.  A node that has a {\tt \%create} or {\tt \%activate}
command should also have a {\tt \%delete} command.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to delete the configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to delete the configuration tree instance of this
  template tree node.

\end{itemize}

If a node that is deleted does not have a {\tt \%delete} command, then
the {\tt \%delete} commands of its children are called instead.
This rule is applied recursively for each child that does not have
a {\tt \%delete} command.
For example, lets say A is a parent of B1 and B2, and B1 is a parent of C1.
Also, lets say that only B2 and C1 have {\tt \%delete} methods.
If we delete A, then both B2's and C1's {\tt \%delete} methods are invoked.
If, however, B1 also has a {\tt \%delete} method, then deleting A will invoke
only B1 and B2's {\tt \%delete} methods.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%set} Command.}

{\tt \%set} is called to set the value of a leaf node in the
configuration tree.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to set the value of configuration tree instance of this template
  tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to set the value of configuration tree instance of this
  template tree node.

\end{itemize}

Note that when a new instance of a node in the configuration tree is created,
if that node has no {\tt \%create} command, then the {\tt \%set}
command (if exists) for that node is used instead.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%unset} Command.}

{\tt \%unset} is called to unset the value of a leaf node in the
configuration tree.  The value will return to its default value if a
default value is specified.

\begin{itemize}

  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to unset the value of configuration tree instance of this
  template tree node.

  \item If the action is {\tt program}, then the second parameter specifies the
  program to execute to unset the value of configuration tree instance of this
  template tree node.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%get} Command.}

{\tt \%get} is called to get the value of a leaf node in the
configuration tree.  Normally the rtrmgr will know the value if there
is no external means to change the value, but the {\tt \%get} command
provides a way for the rtrmgr to re-sync if the value has changed.

\begin{itemize}
  \item The first parameter indicates the form of action to take to perform
  this action - typically it is {\tt xrl} which indicates an XRL should
  be called.
  To execute an external program instead, the action should be {\tt program}.