rtrmgr.tex

xorp源码hg

  \item If the action is {\tt xrl}, then the second parameter specifies the
  XRL to call to get 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 get the value of configuration tree instance of this
  template tree node.

\end{itemize}

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

The {\tt \%allow} command provides a way to restrict the value of
certain nodes to specific values.

\begin{itemize}

  \item The first parameter gives the name of the variable to be restricted.

  \item The second parameter is a possible allowed value for this variable.

  \item The third parameter must be the ``\%help:'' keyword.

  \item The fourth parameter is the help string for this value.

\end{itemize}

If there is more than one possible values, each of them should be
specified by a separate {\tt \%allow} command.

For example, a node might specify an address family, which is intended
to be one of ``inet'' or ``inet6''.  The type of the node is {\tt
txt}, which would allow any value, so the allow command might allow
the rtrmgr to restrict the legal values without having to
communicate with the process providing this functionality.

A more subtle use might be to allow certain nodes to exist only if a
parent node was of a certain value.

For example:

\begin{verbatim}
      family @: txt {
          %allow: $(@) "inet" %help: "IPv4 address family";
          %allow: $(@) "inet6" %help: "IPv6 address family";
          address @: ipv4 {
              %allow: $(family.@) "inet" %help: "IPv4 address family";
              broadcast: ipv4;
          }
          address @: ipv6 {
              %allow: $(family.@) "inet6" %help: "IPv6 address family";
          }
      }
\end{verbatim}

In this case, there are two different typed versions of the ``{\tt
address @}'' node, once for IPv4 and one for IPv6.  Only one of them has
a leaf node called {\tt broadcast}.  The allow command permits the
rtrmgr to do type-checking to ensure that only the permitted
combinations are allowed.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%allow-range} Command.}

The {\tt \%allow-range} command restricts the range of values an
integer configuration item may take.  The syntax is:

\texttt{\%allow-range: }{\it varName lowValue highValue \%help: help-string}\texttt{;}

\noindent where the first parameter, \textit{varName}, gives the name
of the variable to be restricted.  This is typically
\texttt{\"\$(@)\"}.  The {\it lowValue} and {\it highVal} parameters
specify the lower and upper bound of the allowed range of values.
The {\it \%help:} is a mandatory keyword and is followed by the help
string. The help string is used for command-line completion purpose.

An example of use appears in the interface address prefix specification:

\begin{verbatim}
       address @: ipv4 {
         prefix-length: u32;
       }
       ...
       address @: ipv4 {
         prefix-length {
           %allow-range: $(@) "1" "32" %help: "The prefix length";
           %set: xrl "...";
           %get: xrl "...";
         }
       }
\end{verbatim}

If there is more than one {\tt \%allow-range} command restricting
the value of a variable, then the assigned value must belong to any
of the specified ranges.

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

The {\tt \%help} command specifies the CLI configuration-mode help string.
The syntax is:

\texttt{\%help: }{$\{short \mid long\}$} \texttt{"Help string"}\texttt{;}

\noindent where the first parameter, \textit{short} or \textit{long},
specifies whether this is the short-version or the long-version of the
help, and the second parameter is the help string itself.

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

The {\tt \%deprecated} command can be used to deprecate a template tree
node and the subtree below it.
The syntax is:

\texttt{\%deprecated: } \texttt{"String with reason"}\texttt{;}

If the XORP startup configuration contains a statement that uses a
deprecated node in the template, the rtrmgr prints an error with
the string with the reason, and exits.
If, however, a third-party user program (\eg other than xorpsh) sends
to the rtrmgr configuration that contains a deprecated statement, the
rtrmgr returns an error to xorpsh, and the error message will contain
the string with the reason.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%user-hidden} Command.}

The {\tt \%user-hidden} command can be used to hide a template tree
node and the subtree below it from the user. Such node or a subtree
can be used by the rtrmgr itself for internal purpose only and is
not visible to the user (\eg via xorpsh or when saving the configuration
to a file).
The syntax is:

\texttt{\%user-hidden: } \texttt{"String with reason"}\texttt{;}

However, if the XORP startup configuration contains a statement that
uses an user-hidden node, the rtrmgr will accept
the configuration. Similarly, if a third-party user program
(\eg other than xorpsh) sends to the rtrmgr configuration that contains
an user-hidden statement, the rtrmgr would accept that statement. This
is an experimental feature may become permanent or may be disabled in
the future.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%read-only} Command.}

The {\tt \%read-only} command can be used to specify a template tree
node as read-only.
The syntax is:

\texttt{\%read-only: } \texttt{"String with reason"}\texttt{;}

or

\texttt{\%read-only:;}

Only a leaf node that contains a value can be marked as read-only.
If a node is marked as a read-only, then its value cannot be
changed from the default template value. For example, a read-only
node could be part of the startup configuration, but if its
value is different from the default template value the rtrmgr
will reject the configuration.

Note that by definition a read-only node is also permanent
(see Section \ref{sec:permanent-command}):
it cannot be deleted directly, but it will be removed if its
parent is deleted.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The {\tt \%permanent} Command.}
\label{sec:permanent-command}

The {\tt \%permanent} command can be used to specify a template tree
node as a permanent node that cannot be deleted.
The syntax is:

\texttt{\%permanent: } \texttt{"String with reason"}\texttt{;}

or

\texttt{\%permanent:;}

If a node is marked as permanent, the node itself cannot be deleted
directly. However, deleting the parent node will delete the permanent
node as well. Also, adding or deleting children of a permanent node
is allowed.

If a permanent node never should be deleted, then all its ancestors
should be marked as permanent.

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

The {\tt \%order} command provides a way to specify the ordering of
multiple nodes of the same type in the configuration.  For example, if
no ordering is specified in the template file, such as with interfaces:

\begin{verbatim}
      interfaces {
        interface @: txt {
        }
      }
\end{verbatim}

\noindent Then this template would allow the configuration for each
{\tt interface} to be displayed and configured in the order they were
entered.  For example, the configuration might be:

\begin{verbatim}
      interfaces {
        interface fxp1 {
          vif fxp1 {
             address: 10.0.0.1
          }
        }
        interface dc0 {
          vif dc0 {
             address: 10.0.1.1
          }
        }
        interface fxp0 {
          vif fxp0 {
             address: 10.0.2.1
          }
        }
      }
\end{verbatim}

\noindent The ordering of the {\tt interface} sections here is
arbitrary, in the order they were entered by the user.

\noindent In many cases this is what is desired, but in some cases such as
firewall rules, this is not desired, and the {\tt \%order} command
provides a way to enforce an ordering.

\noindent For example, a simple firewall (not the actual XORP firewall) might
use a template such as:

\begin{verbatim}
      firewall {
        interface @: txt {
           rule @: u32 {
             %order: sorted-numeric;
             permit @: txt;
             deny @:txt;
           }
         }
       }
\end{verbatim}

\noindent Thus, some configured firewall rules might be:

\begin{verbatim}
      firewall {
        interface fxp0 {
          rule 100 {
            permit "net 10.0.0.0/24"
          }
          rule 300 {
            deny "all"
          }
        }
      }
\end{verbatim}

\noindent The ordering here is now dictated by {\tt rule} number, in accordance
with the {tt \%order} command.  If a new {\tt rule 200} was
subsequently inserted, it would always be displayed and configured
after {\tt rule 100} and before {\tt rule 300}.

\noindent The available parameters for the {\tt \%order} command are:

\begin{itemize}

  \item {\tt unsorted} - the default, ordered in the order of entry.

  \item {\tt sorted-numeric} - sorted in increasing numeric interger
  order.

  \item {\tt sorted-alphabetic} - sorted in increasing alphabetic order.

\end{itemize}

\noindent Note that if {\tt sorted-numeric} is applied to a {\tt txt}
field, the sort order for non-numeric values is undefined, but numeric
values will be sorted correctly.

%%%%%%%%%%%%%%%%%%%%%%
\subsection{Template Tree Command Actions}

Template tree commands such as:
\begin{itemize}

  \item {\tt \%modinfo: start\_commit <method>;} 

  \item {\tt \%modinfo: end\_commit <method>;}

  \item {\tt \%modinfo: status\_method <method>;}

  \item {\tt \%modinfo: startup\_method <method>;}

  \item {\tt \%modinfo: shutdown\_method <method>;}

\end{itemize}

are used to specify the mechanism to be call before any configuration
change of a module, the mechanism to discover the status of a module, and so
on.
Template tree commands such as {\tt \%create}, {\tt \%activate} and
{\tt \%set} are used to specify the actions that need to be performed
when the router configuration is created or modified.

This section provides a complete listing of all the template tree
actions that the rtrmgr supports.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Template Tree {\tt xrl} Action}

The {\tt xrl} command action specifies the XRL to be executed. The XRL
and its arguments must be inside quotes and it may contains variables
that will be substituted with the particular values at execution time.
For example, if the template tree held the following:

\begin{verbatim}
    bgp-id {
        %set: xrl "$(bgp.targetname)/bgp/0.2/set_bgp_id?id:ipv4=$(@)";
    }
\end{verbatim}

Then when we set the value of {\tt bgp-id}, first the rtrmgr will substitute
{\tt \$(bgp.targetname)} with the particular value of that variable, and
{\tt \$(@)} with the value of {\tt bgp-id}. After the substitution it will
call XRL {\tt bgp/0.2/set\_bgp\_id} with argument {\tt id:ipv4} set to the
value of {\tt bgp-id}.

We could use {\tt xrl} actions to get the value of a particular variable,
store the value inside the rtrmgr and then use that value by other actions.
For example, if the template tree held the following:

\begin{verbatim}
interface {
    ...
    %modinfo: start_commit xrl "$(interface.targetname)/ifmgr/0.1/
                           start_transaction->tid:u32=$(interface.TID)";
    %modinfo: end_commit   xrl "$(interface.targetname)/ifmgr/0.1/
                           commit_transaction?tid:u32=$(interface.TID)";
    ...
    TID {
        %create:;
    }

    interface @: txt {
        %create: xrl "$(interface.targetname)/ifmgr/0.1/
                 create_interface?tid:u32=$(interface.TID)&ifname:txt=$(@)";
    }

    ...
}
\end{verbatim}

Then whenever the interface configuration is changed the {\tt start\_commit}
and {\tt end\_commit} XRLs will be call before and after performing any change
to the configuration of the module. The {\tt start\_commit} XRL will return
the transaction ID {\tt tid} of type {\tt u32}. The rtrmgr will store
that value internally in the {\tt \$(interface.TID)} local variable
(note that this variable should be declared as a leaf node without type).
Then this value can be used by other actions such as the
{\tt \%create} and the {\tt end\_commit} XRL actions in the above example.

%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Template Tree {\tt program} Action}

The {\tt xrl} command action specifies the external program to be executed.
The program and its arguments must be inside quotes and it may contains
variables that will be substituted with the particular values at execution
time.
For example, if the template tree held the following:

\begin{verbatim}
    foo {
        %set: program "/bin/echo -n '$(@)' >> /tmp/file.txt";
    }
\end{verbatim}

Then when we set the value of {\tt foo}, first the rtrmgr will substitute
{\tt \$(@)} with the value of {\tt foo}. After the substitution it will