The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter provides information about the tables used in WAE plan files, in the following sections.
Plan files contain a complete representation, or model, of a network. This includes topology, configuration, state, traffic, and visualization data.
WAE Collector creates plan files when collecting from a network and makes them available for use by applications, such as WAE Design and WAE Live, as well as by other WAE modules. CLI tools and WAE Design GUI tools also provide a means of creating and manipulating plan files.
Plans have the following file formats.
The GUI and CLI tools use these formats interchangeably for input and output files. The default format for the GUI is the.pln format file.
The.pln format is the native WAE format for plan files. This format is small in size, so opening and saving the file is fast. When scripting, you generally work with some combination of.pln and.txt format plans and tables. For a description of the tables in the.pln format file, refer to the External Tables section.
Each.txt format plan contains plan information in plain text that you can view and edit in an Excel spreadsheet or text editor. Excel is particularly useful because most of the data has tab-delimited fields that Excel can convert to a spreadsheet.
Each file contains a collection of tables, including the required <Network> table that specifies the WAE version that created the plan and other high-level plan properties. Each table is preceded by a table heading, such as and <Nodes> and <Sites>. Rows starting with a pound sign (#) are ignored and treated as comments.
There are two types of.txt format plan files.
Example: <LSPs> table with no entries.
– All columns that contain only default values.
Example: Empty Protected values in the <Nodes> table default to F. So if all values in the column are F, it is not included in the.txt format plan.
This format is smaller and easier to edit manually. However, it can be more difficult for a script to parse because the script must check for missing tables and columns. We do not recommend this format when using scripts.
To view sample tables in a simple.txt format plan, open the samples/euro4.txt
file in Excel, or any text file editor. Following are a few euro4.txt
excerpts for some of the most important tables in the plan.
|
|
---|---|
Note If the Version row is missing, the version property defaults to 4.1, not the current version, for backward compatibility. Plans in Version 4.1 did not require an explicit version.
|
|
|
|
---|---|---|---|
|
|
|
|
---|---|---|---|
Table 2-4 <Interfaces> Excerpt
|
|
|
---|---|---|
|
|
|
|
|
|
---|---|---|---|---|---|
|
|
|
|
---|---|---|---|
Table 2-7 <DemandTraffic> Excerpt
|
|
|
|
|
|
---|---|---|---|---|---|
The GUI and CLI use the.pln and.txt formats interchangeably. When you save a file from the GUI, the.pln format is the default. To save to a different format, select the File->Save As menu.
From the CLI, the format of a saved file depends on the extension of the output filename. A.pln extension produces a.pln format file and a.txt extension produces a.txt format file. A command-line argument ( -simple-txt-out-file
) specifies the simple.txt format plan.
To convert one format to another, use the mate_convert
CLI tool. This tool can convert formats within the current software version, or from an earlier version to the current version. For example, mate_convert
can upgrade a 5.6 plan file to the 6.0 file format.
All aspects of a plan are defined using a collection of tables. Developers can access and modify all tables using command-line tools. For a complete online listing of tables and their columns, refer to the table_schema.html
file in the $CARIDEN_HOME/docs
directory. You can also refer to the WAE Design Plan Table Schema and CLI Reference, which lists the most commonly used columns of each of these plan tables.
The columns in a plan file table contain data in one of the following categories.
In the table_schema.html
file, key columns are highlighted in orange.
In the table_schema.html
file, plan columns are highlighted in blue.
table_extract
when the tables are extracted from the plan file. For example, Remote Node in the <Interfaces> table is derived by looking up the remote node for the interface as defined in the <Circuits> table. Some derived information can be more complex to obtain. For example, the Traff Sim column is a derived column that is the result of a simulation performed on the network. The entries in tables generated in the GUI and from table_extract
can depend on some pre-specified parameters. For example, the <Interfaces> table Traff Meas column is the measured traffic on that interface for a specified traffic level. For a particular QoS selection the column can be overall ( undifferentiated) traffic, traffic on a particular queue, or traffic for a particular service class.
In the table_schema.html
file, derived columns are highlighted in gray.
Objects in WAE Design are represented by rows in tables, and object properties are represented by column entries in that table, or by entries in tables of related objects. For example, LSP objects are defined in the LSPs table. Columns in this table, such as Setup BW, define properties of each LSP. The paths of each LSP are also properties of the LSP, but those LSP paths are defined as objects in separate LSP Paths, Named Paths, and Named Path Hops tables.
Table 2-8 lists the notation that WAE Design uses to specify a plan object when the type of object is not known from the context. Except for the IP address, these notations have a one-to-one mapping with key columns for each object.
Table 2-8 Single Object Notation
In a text plan file, each table starts with <TableName> to identify the name of the table, for example, <Nodes>.
The first row of the table body contains the column headings, followed by rows that describe the table entries. The order of the columns is irrelevant, and only the key columns must be present.
Each plan table is defined using an excerpt from the database schema, the part that defines that table. For example, Table 2-9 lists a table schema excerpt for the <NamedPaths> table. Table 2-10 shows an example of a <NamedPaths> table that has been populated within a plan file.
In Table 2-10 , the first column is Name, which is described in the first row of Table 2-9 . In this case, the Name of the named path (PathA or PathB) is the same in the plan file and GUI, it’s the name of the path, has a data type of text, and is a table key. Being a key means the Name column is among the columns that uniquely define a row. In this case, the Name and Source together define a unique row.
Table 2-9 NamedPaths Table Schema
|
|
|
|
|
---|---|---|---|---|
T if all hops in path are resolved in plan, F if not, na if no hops. |
Table 2-10 <NamedPaths> Example
|
|
|
---|---|---|
You can add new tables of your own design and new columns to the standard tables. Using these structures can help reduce the number of extra files required in a solution, and are helpful in custom scripts that need to carry information from one step to another.
WAE Design does not check them for errors. However, they are preserved on import and export, and their contents are displayed in the Plan Window under the Plan Tables hierarchy.
These user-defined structures use namespaces, which is a convenient way of grouping tables or grouping columns under one name. Each user-defined table or column is prefixed with a namespace.
The format of the namespace prefix is as follows. You only need one Namespace, though you can chain them together using :: between their names.
<Namespace1::Namespace2::... ::TableName>
<Namespace1::Namespace2::... ::ColumnName>
The following example shows a new table that defines rack space for nodes. The table title is prefixed with MyTables::, which identifies it as a user-defined table in the MyTables namespace.
Table 2-11 Example: User-Defined <MyTables::Rackspace> Table
|
|
|
---|---|---|
The next example shows how to add a user-defined column to a standard <Sites> table. The new column is prefixed with Customer::, which identifies it as a user-defined column in the Customer namespace.
Table 2-12 Example: User-Defined Column
|
|
---|---|
This section describes how to modify plan tables from the CLI or GUI, or how to use table files as arguments for command-line tools.
This section explains how to add, modify, or delete tables in a plan file. Basically, you extract the desired table, edit the extracted file, then replace the table in the plan. Changes to columns of type Derived are ignored when replacing a table. Only columns of type Plan are relevant for changes.
The replacement tool does not validate the changed table, so the resulting plan could be incomplete, inconsistent, or have erroneous data. Such problems are flagged the next time the plan is opened in WAE Design.
See also the Plan Tables and SQL Queries in WAE Design sections.
Step 1 Create the desired table as a text format file, or extract one from another plan file. If you create a table manually, the table name and columns must confirm to the table definitions in this chapter.
Step 2 Add the table to the plan using table_replace
. This overwrites an existing table if one exists.
Step 1 Extract the table from the plan using table_extract
and save it to a.txt format file.
Step 2 Change the data in the table using in one of the following tools.
table_edit
. mate_sql
. Step 3 Replace the table in a plan file with the modified table, using table_replace
.
You normally replace the table in the original plan file, but the result of table_replace
can be a different file or even a different plan format. For example, you could replace a table in a text format plan and save the result as a binary format file (.pln), leaving the original file unchanged.
This example shows how to increase the IGP Metric for interfaces on core routers in the us-wan
plan, which is in the $CARIDEN_HOME/samples
directory. Figure 2-1 shows an excerpt from the original plan file. The Interfaces table has three columns: Node, Interface, and IGPMetric, which are all either “key” or “plan” columns. You only need the “key” values to uniquely define an interface.
Figure 2-1 Interfaces Table in us-wan.txt
In this simple example, a user could manually update the IGPMetric column, using Excel or another text editor. To script the process however, use the CLI tools.
Step 1 First, extract the Interfaces table from the plan file to a temporary file, if-table.txt
:
Figure 2-2 Extracted Interfaces Table
Figure 2-2 shows an excerpt from the extracted Interfaces table. The interesting part of the extracted table is that it contains more than just “key” and “plan” columns, it also has “derived” columns, which WAE Design creates when it reads a plan file or performs simulations. These extra columns make it is easier to identify the Core routers in this example because there is now a Function column.
Step 2 The next step is to increase the IGP Metric for core router interfaces. The command below reads the extracted Interfaces file, if-table.txt
, finds the IGPMetric column of the Interfaces table, filters the rows to those with ‘core’ in the Function column, adds 100 to the IGPMetric in the filtered rows, and saves the result to a new file named if-table-edited.txt
.
Figure 2-3 Interfaces Table After Replacement
Figure 2-3 shows an excerpt from the updated file, if-table-edited.txt
, which has the expected result in the IGPMetric column: the four core routers (nodes) shown have their IGP metrics increased by 100, and the edge router metric is unchanged.
Step 3 The last step is to update the original plan file, or to create a new one. In this case, the example command creates a new plan file, one that uses the.pln format. Changing the file format in this example just shows the flexibility of the tools.
Step 4 As a confirmation, you could open the us_wan.pln
file just created to verify the updates. The GUI table would contain the same information shown in Figure 2-3.
Step 1 Select the Edit->Plan Tables as Database menu. The Plan Table Database Editor dialog box opens, showing all possible tables in the left pane.
Step 2 In the left pane, select the desired table. If the table already exists in the plan, it is displayed.
Step 3 Optional: Filter the table entries by using the Filter control menu or by entering text in the Search field (top right).
Step 4 Click on the field you want to change and then edit the information, or choose one of these more advanced editing options.
Step 5 Visually verify that the change is correct.
Step 6 To open the new plan, click “Open in WAE Design.” To save the new plan without opening it, click “Save as File.”
Because plan files can be edited directly by the user, errors must be handled when opening plan files. The default behavior for table errors is to log a warning and ignore any row of any table that is inconsistent with information already processed. For example, if the <Nodes> table lists two nodes with the same name (which is a key column) the second row is ignored.
To simplify user editing of. txt
format plan files, WAE Design gracefully handles common problems encountered during the opening process. For example, although the simplest plan can contain nodes, interfaces, and circuits, there are certain situations in which only an <Interfaces> table need be specified.
WAE Design makes the following changes when opening a plan with missing or incomplete information.
Many CLI tools take arguments that require the specification of a set of plan objects. For example, merge_nodes
takes a nodes-table
parameter that specifies the list of nodes to merge. Such a list can be specified in a file containing a table in the WAE Design table format. Tables used as arguments must contain at least the key columns defined for that table for the tool to uniquely match the objects in the import table with the objects in the plan.
To create tables for use as command-line tools arguments, follow these steps.
Step 1 Extract the full table of objects from the plan that is the target of the command-line tool, using table_extract
.
Step 2 Use an editor to select the appropriate rows in the table, and delete the rest. Or, typically in a script, use mate_select
to select the rows using SQL syntax.
To create an LSP mesh between the core routers in sites ATL, MIA, and WDC of the us_wan.txt
plan, you must first create a file that contains the list routers in the mesh. The following example extracts the Nodes table from the plan file, and then selects the desired core routers, and saves the result as lsp_nodes.txt
.
Step 1 First, extract the Nodes table from the plan file.
Step 2 Select the desired core routers and save the result as lsp_nodes.txt
.
Note The SQL query uses LIKE
, rather than =
, when selecting sites to avoid case-insensitivity problems.
The resulting lsp_nodes.txt
file contains the following list of nodes.
Step 3 Create the LSP mesh by invoking the lsp_mesh_creator
tool, specifying the lsp_nodes.txt
file as a command-line argument.
Three command-line tools in WAE Design use SQL syntax for filtering, summarizing, and manipulating plan files and reports.
Step 1 mate_select
—Filters tables in the reports.
Step 2 mate_summary
—Summarizes tables in the reports, primarily to provide summary data for network visualization over time, using the archive feature.
Step 3 mate_sql
—An advanced SQL query tool.
WAE Design uses the SQLite implementation of the SQL language (see www.sqlite.org, especially www.sqlite.org/lang.html).
The following operators have special meaning in WAE Design.
Is true for Name
equal to 'CR'
, 'Cr'
or 'CR01'
. (But not for Name
equal to 'er.cr'
)
MATCH
—Some columns in the tables contain semicolon-delimited lists, for example a list of tags in the Tags column of the Nodes and Interfaces tables, or the list of interfaces in the Actual Path column of the LSP table. The MATCH
operator tests for membership in these lists. For example, Is true for Tags equal to 'Asia;Europe'
, 'EUROPE'
, and so on. The matching is case-insensitive.
The operator '=' is case-sensitive in SQL. The operator LIKE
, which is case-insensitive, is often more useful for plan schema tables because the case is never relevant.
This function has the following syntax options.
– SUBNET(Column_Name, 'ip_address/prefixlen')
– SUBNET(Column_Name, 'ip_address/netmask')
– SUBNET(Column_Name, 'ip_address', 'prefixlen')
– SUBNET(Column_Name, 'ip_address', 'netmask')
The following examples demonstrate usage of each syntax.
– SUBNET(Column_Name, '192.168.1.0/24')
– SUBNET(Column_Name, '192.168.1.0/255.255.255.0')
– SUBNET(Column_Name, '192.168.1.0', '24')
– SUBNET(Column_Name, 'ip_address', '192.168.1.0, '255.255.255.0)
The following shows usage in a real SELECT statement.
select * from Table where subnet(IPAddress, '192.168.1.0/24');
This WHERE clause matches a row if the field IPAddress is an IP address in the 192.168.1.* network.
SQLite does not allow arbitrary functions to have infix notation, so the following notation is impossible.
Where IPAddress SUBNET '192.168.1.0/24'
Syntax: SUBSTITUTE(Column_Name, 'old', 'new')
where 'old' and 'new' are values like those used in the syntax: s/old/new
The following example shows how you could replace the m with c in all node names that start with mr.
table_edit -plan-file x.txt -out-file y.txt -table Nodes -column Name
-value "SUBSTITUTE(Name,'\(mr\).*','cr\1)"
WAE Design provides Perl modules that simplify access to files that use the plan schema table file format. This format is used, for example, in exported plan files and report files generated from the GUI. The Perl modules are contained in the $CARIDEN_HOME/lib/perl
directory. Documentation is available using perldoc. For example, execute the following command from the installation directory.
Note To run a Perl script in a Windows installation, a Perl implementation needs to be present. We recommend ActivePerl, which can be downloaded for free.
In addition to plan tables, external tables provide input to plan files or are the result (output) of running tools on the plan file.
A <DemandMesh> table contains columns that identify the source and destination endpoints for a demand mesh, and optionally contains columns that specify the source and destination traffic for each ().
Figure 2-4 Example <DemandMesh> Table
The table_edit
CLI tool can optionally use a file containing an <Edits> table, which is a very time-efficient means of globally modifying plan schema tables.
NameSpace::Name
. Example: This example shows an Edits file that change the forecast values in the demands table. The following tables show the original demands table, the edits table, and the updated demands table after running table_edit
.
Table 2-13 Original <Demands> Table
|
|
|
---|---|---|
|
|
|
|
---|---|---|---|
Table 2-15 Updated <Demands> Table
|
|
|
---|---|---|