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.
A comprehensive set of online and offline tools are available to discover and retrieve information from an operational network for input into a plan file. There are various methods available, depending on sources of information and network access, such as SNMP access and router configuration files, and what information is to be imported.
Advanced collection configuration includes the following topics:
Note This section describes running multi-network collections using the manual collection method. You can also use the WAE UI to run multi-network collections. For more information on using the WAE UI, see Add Additional Networks for Collection.
The manner in which you configure multiple networks for inclusion in WAE Live depends on whether you are using an external archive or directly inserting plan files into WAE Live. This chapter describes both methods.
This chapter references the following terms.
$CARIDEN_ROOT
—Location of the installation. By default, this is
/opt/cariden
.
$CARIDEN_HOME
—Directory in which the WAE Design, WAE Live, and WAE Collector executables and binaries are installed. The default is
/opt/cariden/software/mate/current
.Note All instructions and examples assume you used /opt/cariden
as the default installation directory. If you did not, then substitute your installation directory for /opt/cariden
.
This chapter does not describe the details of configuring snapshots. Rather, it describes only the nuances of configuring manual snapshots for the purpose of discovering multiple networks . Using this chapter has several “knowledge” prerequisites, as follows.
archive_insert
and
ml_insert_plan
). For information, refer to their
-help
output. For information on configuring snapshot files and configuring manual snapshots, see Snapshot Files.
Best practice: Back up all configuration files before you begin.
Note This chapter uses two running examples. One is the collection for an “east” network where plan files are put into an external archive. The other is the collection for a “north” network where plan files are directly inserted in WAE Live. Such names are for example purposes only.
Note You can use the same authentication and network access files for all networks, or you can create and modify them on a per-network basis. For more information on these files, see Network Access File and Network Authentication.
Step 1 Run
mate_auth_init
once to create an authentication file (
auth.enc
) used by SNMP and login tools.
This is an interactive tool that first prompts you to choose the SNMP version and the relevant parameters. To create a different network authentication file for a network, use the
-auth-file
option. The recommendation is to use one of the default configuration paths:
~/.cariden/etc
,
$CARIDEN_HOME/etc
, or
$CARIDEN_ROOT/etc
.
Step 2 Optional: Customize network access. To create a different network access file, copy the default
$CARIDEN_HOME/etc/net_access.txt
, rename, and modify it. This file must be located in one of the default configuration paths:
~/.cariden/etc
,
$CARIDEN_HOME/etc
, or
$CARIDEN_ROOT/etc
.
Step 3 For new installations, copy the default snapshot.txt and snapshot.inc files to working configuration files. Uniquely name each set of .txt and .inc files to represent the network to which it is applicable.
If this is not a new installation, you can use existing snapshot files in
/opt/cariden/etc
and make modifications noted in this chapter as needed. However, you need one set of snapshot files (one .txt file and one .inc file) per network.
Each network
must have its own set of snapshot files that independently call
archive_insert
to insert plan files into a uniquely named archive. Remember, you must also configure the snapshots to discover, poll, and build the network model.
Step 1 Edit the ss-east.txt file, which contains the collection, polling, modeling, and insertion tasks to perform. This file controls the sequence of execution and also contains environment variables of common values used in the ss-east.inc file.
a. At minimum, you must define
unique
,
seed_router
,
igp
,
home_dir
, and
archive_dir
. By default, the
archive_insert
tool uses the
archive_dir
environment variables when inserting plan files into an external archive. Best practice is to use the default.
b. Edit the
include
environment variable to read the ss-east.inc file from
$(home_dir)/etc
.
Example:
include $(home_dir)/etc/ss-east.inc
c. Uncomment the ARCHIVE_INSERT task .
Step 2 As needed, edit the ss-east.inc file to modify and add tools that are to be called from the ss-east.txt file.
Configure the file to use
archive_insert
to insert plan files into the named external archive directory. You can use the default
archive_insert
configuration in the .inc file for this purpose.
Step 3 Run
archive_init
to initialize the archive repository into which the plan files are to be inserted. Text in <angle brackets> refers to environment variables that you set in the ss-east.txt file. The path entered for the External Archive on the WAE Live Settings > General Settings page must match this case-sensitive path.
Example:
archive_init -archive /opt/cariden/archives/east-archive
Step 4 Create a cron job that repeats the process of running the snapshot files that you created, which results in the insertion of plan files going into their respective archive repositories.
Note Both CARIDEN_ROOT and CARIDEN_HOME variables must be defined from within the crontab. You cannot use CARIDEN_HOME=$CARIDEN_ROOT/software/mate/current.
a. Open the file for editing as follows.
b. At the end of the file, add the following lines.
c. At the end of the file, add one entry to call the unique snapshot per network.
Note Best practice is to verify the snapshots are working prior to continuing to WAE Live configurations.
Each network
must have its own set of snapshot files that independently call
ml_insert_plan
to insert data directly into the WAE Live data store. These files must also call
archive_insert
to insert plan files directly into the Map archive. Remember, you must configure the snapshots to discover, poll, and build the network model.
Step 1 Edit the ss-north.txt file, which contains the collection, polling, modeling, and insertion tasks to perform. This file controls the sequence of execution and also contains environment variables of common values used in the ss-north.inc file.
a. At minimum, you must define
unique
,
seed_router
,
igp
,
and home_dir
.
If using the Map component, create an environment variable that uniquely specifies the Map archive.
b. Edit the
include
environment variable to read the ss-north.inc file from
$(home_dir)/etc
.
Example:
include $(home_dir)/etc/ss-north.inc
c. Uncomment the ML_INSERT task.
d. If using the Map component, add an MAP_ARCHIVE_INSERT task.
Step 2 As needed, edit the ss-north.inc file to modify and add tools that are to be called from the ss-north.txt file.
Configure the associated ss-north.inc file to use
ml_insert_plan
with the
-network
option. The
-network
option specifies the network partition of the data store into which you are placing data. This must match the case-sensitive network name added through the WAE Live UI. In this example, you would also have to create and name a WAE Live network called “north.”
Step 3 If using the Map component, configure the associated ss-north.inc file to use
archive_insert
to specify the Map archive. This must match the case-sensitive name given the Map archive in the WAE Live Settings > General Settings page. In this example, the Map archive in WAE Live would have to be
/opt/cariden/data/mldata/archive/north
.
Step 4 Create a cron job that repeats the process of running the snapshot files that you created, which results in the insertion of plan files going into their respective network segments within the WAE Live data store.
Note Both CARIDEN_ROOT and CARIDEN_HOME variables must be defined from within the crontab. You cannot use CARIDEN_HOME=$CARIDEN_ROOT/software/mate/current.
a. Open the file for editing as follows.
c. At the end of the file, add one entry to call the unique snapshot per network.
Best practice is to verify the snapshots are working prior to continuing to WAE Live configurations.
Note Configuring get_configs
is supported in both augmentation and manual collection methods. Using parse_configs
to augment a plan with RSVP LSP and/or SRLG data is supported through the augmentation method. Configuring parse_configs
to create a plan file for overall topology is supported only in manual collection.
This chapter describes the CLI tools available to discover and retrieve information from router configuration tools and from RRD tools, such as Cricket, Cacti, and MRTG.
The following tools are useful for capturing and importing network information. For instance, you can capture the configuration files or IGP databases and import them into WAE Collector.
get_configs
—Reads the configuration files from a list of routers and saves them in the specified directory.
parse_configs
—Reads a set of Cisco and/or Juniper Networks router configuration files, and creates a plan file of the network. See Import Router Configuration Files. For information on using this tool from the WAE Design GUI, see the
Cisco WAE Design Integration and Development Guide
.
parse_igp
—Converts IGP information from router
show
commands to a plan file. See Import IGP Database. For information on using this tool from the WAE Design GUI, see the
Cisco WAE Design Integration and Development Guide
.
get_show
and
get_xml
—Tools for entering router
show
commands and the XML equivalents for further processing by the user or an application. These commands are typically used because the WAE Collector does not include the output of the commands during plan file creation. The
get_xml
tool offers similar functions to
get_show
. It is used to get structured data from devices by executing XML commands on them. The command format is device-dependent.Note This section contains examples for Cisco and Juniper routers. For information about network discovery of routers for other vendors, please contact your support representative.
The
parse_configs
tool reads Cisco, Juniper, and Huawei router configuration files, and creates a plan file.
The router configuration files from the network, or part of the network, need to be available in a specific directory. The
parse_configs
tool reads files in this directory (
-data-dir
option), determines the router type/vendor, and parses the configuration.
The following information can be read from a router configuration file to create the plan file. After parsing this information, the tool matches corresponding interfaces in the IGP mesh to create the network topology.
|
With the
-igp-protocol
option, you can select which interfaces are part of the topology: IS-IS and/or OSPF enabled interfaces. The default is
isis
.
parse_configs
combines both levels into a single network, and Level 2 metrics take precedence. The
-isis-level
option specifies which option to use; the default is Level 2.
-ospf-area
option specifies the area ID or all. The default is area 0.
ASN is ignored by default. However, for networks that span multiple BGP ASNs, use the
-asn
option to read information from more than one IGP process ID or instance ID in an ASN.
Shared media segments in the network (non point-to-point circuits, such as Ethernet) are included in the topology by default unless the
-shared-media
option is set to
false
. A pseudonode and interface representing the medium are then created for every shared medium with more than two hosts, as used by OSPF and IS-IS routing protocols.
With the
-plan-file
option, you can merge an existing plan file with router configurations to create an augmented plan file. For example, you could use the
parse_igp
output as the input into
parse_configs
.
Note A useful tool for maintaining an archive of router configuration files is RANCID (http://www.shrubbery.net/rancid/
).
The parse_igp tool reads one or more databases that are generated from a router’s CLI. With the
-igp-protocol
option, you can select an IGP protocol.
isis
or
isisv6
option, respectively
ospf
or
ospfv3
option, respectively
With the
-plan-file
option, you can merge an existing plan file with the IGP databases to create an augmented plan file. For example, you could use the
parse_configs
output as the input into
parse_igp
.
This tool can generate a topology out of an IS-IS Level 1, Level 2, or both databases using the
-level
option.
To capture an IS-IS database from the CLI, log into a router within the IS-IS topology, display the IS-IS database, and save the output of that session to a file, as follows.
Step 1 Establish a terminal session on a host that has direct access to the network routers, for example, using telnet or SSH.
Step 2 Initiate a process to capture the entire session.
Step 3 Log on to the seed router, which is a router that contains IGP information for the network.
Step 4 Disable paging of output by setting the terminal length to infinite (0).
Step 5 Cisco Option: Disable dynamic host resolution in IS-IS if hostnames are longer than 14 characters and the unique part of the name is after 14 characters. Cisco routers truncate names at 14 characters. To disable dynamic host resolution, enter the
router isis <proc id>
command mode, and then enter:
Step 6 Display the IS-IS link-state database (LSDB).
Step 7 Log out of the router, the network host, and the screen capture, each time using the
exit
command.
Step 8 Save your session capture that was initiated in step #2 (
exit
when using
script
).
Repeat the above steps to capture IS-IS databases from additional routers (Level 1 and Level 2), if necessary. The resulting file or directory includes login and logout commands, as well as output. Now you can use the
parse_igp
tool.
-level
option to specify whether discovering Level 1 or Level 2 topology or both; the default is level 2.
-database-file
option.
-database-dir
option.
Example:
This command uses IS-IS Level 2 topology information stored in the
mobile_database.txt
file to create a plan file called
mobile_model.txt
.
By default, the IS-IS protocol used in IP networks (non MPLS) does not distribute the IP addresses of the interfaces in the network, nor the circuit capacities.
When the IS-IS TE-extensions (for MPLS) have been enabled in the network, that information becomes available, and will also be used by
parse_igp
.
mpls traffic-eng level-2
in the
router isis
configuration section, and
mpls traffic-eng tunnels
on the interfaces. Doing so makes both the IP addresses and circuit capacities available in IS-IS (and
parse_igp
).
Enable the
-use-dns
option by setting it to
true
if DNS (domain name server) needs to resolve IP addresses (router names) in the IS-IS database file.
Note Parallel circuits (non-TE enabled) between two Cisco routers, show up in the IS-IS database as a single circuit.
To capture an OSPF database from the CLI, log into a router with the OSPF topology, display the OSPF database, and save the output of that session to a file.
Step 1 Establish a terminal session on a host that has direct access to the network routers, for example, using telnet or SSH.
Step 2 Initiate a process to capture the entire session.
Step 3 Log on to the seed router. This is a router that contains IGP information for the network.
Step 4 Disable paging of output by setting the terminal length to infinite (0).
Juniper Networks:
set cli screen-length 0
Step 5 Follow the appropriate Cisco or Juniper Networks step.
Step 6 Log out of the router, the network host, and the screen capture, each time using the
exit
command.
Step 7 Save your session capture that was initiated in step #2 (
exit
when using
script
).
Repeat the above steps to capture OSPF databases from additional area border routers (ABRs), if necessary. The resulting file or directory includes login and logout commands, as well as output. Now you can pass the file created in the above steps to using the
parse_igp
tool using the
-database-file
option. If there are multiple files, then pass the directory name where the files are located using the
-database-dir
option.
By default,
parse_igp
collects the OSPF area 0 link-state database (LSDB). To generate topologies from non-zero area LSDBs, use the
-ospf-area all
option. The tool then identifies all ABRs and builds a complete multi-area OSPF network topology. Note that the
login_find_igp_db
tool uses this
-ospf-area all
option as well.
Unlike the IS-IS database, the OSPF database has IP address information for all interfaces in the network. If the network is TE-enabled, the OSPF database also contains circuit capacities.
Enable the
-use-dns
option by setting it to
true
if DNS needs to resolve IP addresses (router names) in the IS-IS database file.
Note Parsing IGP with the OSPF protocol option only processes area 0 routers per default. Use the -area
option to select another area, or all
for all areas.
The
get_show
tool is a wrapper for entering a
show
command on one or more routers. For example, the
get_show
tool with a
-cmd
argument of
show configuration
is equivalent to the
get_configs
tool. The
-command-table
option enables you to enter vendor-specific CLI commands, such as an ICMP ping in multi-vendor networks. You could also use this tool to get an OSPF or IS-IS database from the router.
Because
show
commands are highly dependent on router types, this tool can only operate on a homogeneous set of routers when more than one is specified. The IS-IS and OSPF
show
commands are listed in the IS-IS and OSPF sections, respectively.
In the
-nodes-table
or
-nodes
arguments, if an IP address is available, it is used. Otherwise, an IP lookup through DNS is tried. If that fails, an error is returned.
The
get_xml
tool offers the same function as
get_show
. It is used to get structured data from devices by executing XML commands on them. The command format is device-dependent.
WAE Collector can import network information from the following RRD tools.
The
cricket_poll_interfaces
tool reads a router interfaces file, discovers which interfaces the file specifies, and the RRD files that contain the data associated with each interface. It then reads the traffic measurements from the RRD file and imports them into to the <InterfaceTraffic> and <NetIntIfMeasurements> tables in a plan file.
Because Cacti is written in PHP and uses mysql, the importer is also implemented with a PHP script. Install the PHP script on the web server that is running Cacti, and then invoke
cacti_poll_interfaces
to import the traffic measurements into the <InterfaceTraffic> and <NetIntIfMeasurements> tables in a plan file.
To install the PHP script on a web server running Cacti, follow these steps.
Step 1 Copy the PHP script to the web server. You must have a guest account set up for Cacti. The script location is as follows.
Step 2 Add
"graph_info.php" => 7
, to
include/global_arrays.php
. The array location is as follows.
To import traffic measurements into a plan file, call
cacti_poll_interfaces
and provide the Cacti URL as an argument.
The
mrtg_poll_interfaces
tool imports traffic measurements into a plan file by reading an MRTG configuration file. First it discovers which interfaces the configuration file specifies, along with the RRD files that contain the data associated with each interface. Then it reads the RRD files and imports the traffic measurements into the <InterfaceTraffic> and <NetIntIfMeasurements> tables in a plan file.
Note Editing the network access file is supported for the WAE Collector UI collection and for the manual collection methods.
A network access file can be used to store network access parameters. These include timeout and retry settings, and settings for management of multiple simultaneous queries. Having these settings in a file, rather than as CLI parameters, removes the redundancy across many calls and allows for more complex settings (per router settings, for example).
The network access file provides default settings for all access parameters. You can use either the default network access file, or you can modify and put it in one of the following locations. The file is looked for in this sequence, and the first version found is used.
When the Collector server uses this file, it saves it as net_access_session.txt file. Augmented snapshots then use the net_access_session.txt file that was us chapter.
$CARIDEN_HOME/etc
before editing it, and ed in the last collection by the Collector server. For information on configuring the Collector server, see Collecting Basic Information Using the WAE Collector UI and put the edited version in
$CARIDEN_ROOT/etc
. This simplifies the upgrade process and preserves a copy of the original if needed.The network access file consists of two sections: one containing tables that set values globally and one containing tables that sets values on a per-router basis.
Note In the net_access.txt file an empty field means everything else, and this meaning is in context of the rows defined before it. If it is in the first row, it means everything.
WAE Collector network communication tools take advantage of the polling abilities that simultaneously process a large number of network requests. The Global section of the network access file defines constraints that are used to limit the impact to either the server doing the polling or to the network elements between the server and the network being polled. Examples of network elements that could be heavily impacted by polling traffic are a firewall, slow WAN circuits, or a NAT device.
This section consists of two tables that work in tandem: <GlobalModes> and <GlobalSettings>.
The network access file includes commented documentation for each <GlobalModes> property. Table 4-1 provides an example <GlobalModes> table.
– TaskRegExp—This is the WAE Collector CLI tool. The default is a blank, which matches all possible tools.
– GlobalMode—Mode to assign to all routers when running the matched CLI tool.
Table 4-2
provides an example <GlobalSettings> table. The empty field at the beginning of the last row means
everything except
snmp_poll
and
snmp_find_*
.
If you have concerns about specific device types or operating systems, you can constrain the WAE Collector network communication tool to execute on a per-router basis. For example, some devices might not respond well to short SNMP timeout values when they are busy, while others might need special settings for login access. Together, the <RouterModes> and <PerRouterSettings> tables enable you to adjust these types of settings.
The network access file includes commented documentation for each <RouterModes> property. Table 4-3 provides an example <RouterModes> table.
Each RouterMode is defined by the NodeRegExp, IPRegExp, and SQLFilter columns.
– NodeRegExp is matched against device names.
– IPRegExp is matched against device IP addresses.
– SQLFilter is an SQLite
sql
command that can reference any column of the Nodes table to match devices.
The TaskRegExp column provides constraints for one specific tool in the event that unique parameters are required for one discovery task.
Table 4-4
provides an example <PerRouterSettings> table. The empty fields in the first row mean
everything
. The empty TaskRegExp field in the last row means
everything except
snmp_find_multicast
and
snmp_poll
.
If you are discovering a network containing both Alcatel and non-Alcatel nodes, you must configure the <PerRouterSettings> table to tell the online tools to ignore the Alcatel objects and their traffic. The simplest method is to do the following.
Step 1 Add a comment (#) to this line to prevent the collection of Alcatel statistics.
Step 2 Uncomment this line to ignore the discovery of Alcatel nodes, interfaces, and LSPs, and to ignore the collection of statistics from them.
The
mate_access_test
tool enables you to specify a node, node IP, and task, or alternatively specify the router mode and global mode settings directly. The tool returns the global and per-router parameter settings that are applied if the network access file were used. The option is
-net-access-file
. The default value is net_access.txt.
Use
mate_access_test -net-access-file
to see the global and per-router parameter settings that are applied if a network access file is specified. The default value for
-net-access-file
option refers to the net_access.txt file in the configuration path.
Note Creating and editing the authentication file is supported for the manual collection method.
The authentication file consolidates the login, authentication, encryption, community strings, and other credentials needed by the WAE Collector tools to access routers and collect network data. It is required if the tools are to be called by scripts, or if different routers in the network require different authentication information. The file can be encrypted for security and protected with a master password.
mate_auth_init
tool simplifies the process of creating a default authentication file.
When an online discovery tool needs authentication information for a router (for example,
snmp_find_interfaces
needs a community string to perform an SNMPv2c query), it accesses the authentication file and looks for a match for the router. If successful, the tool uses the credentials from the file to access routers and collect network data. Without a match the tool generates a prompt or notification.
You can disable user interaction by setting the
-auth-prompt
option to
false.
Note Use this method of creating a network authentication file only if using the manual snapshot collection process.
The
mate_auth_init
tool is an interactive tool that simplifies the process of specifying a default set of authentication credentials that WAE Collector tools use to access all routers. The file is created in the directory from which you execute the command. To change the file location, enter a full path name.
The file it creates has credentials for SNMPv2c, SNMPv3, or both. SNMPv2c uses a less secure security model, passing community strings in clear text. SNMPv3 provides a strong security model that supports authentication, integrity, and confidentiality.
If
mate_auth_init
does not find an auth.enc file in one of the default locations, the tool prompts you to select one from a list.
The tool creates a file named
auth.enc
in the selected directory. However, you can override the default directory and filename by using the
-auth-file
option. The recommendation is to use one of the above default configuration paths. If you put this file in a different directory, binaries must be explicitly called using this path.
Example:
mate_auth_init -auth-file /opt/cariden/etc/auth-acme.enc
The
mate_auth_init
tool prompts you to choose SNMPv2c, SNMPv3, or both. Depending on your choice, the tool prompts you for authentication information that is pertinent to the selected SNMP version.
Note If both SNMPv2c and SNMPv3 are selected, the default is for the auth.enc file to put all nodes in both SNMPv2c and SNMPv3. When a node is mapped to both, then only SNMPv3 is used. To change this behavior, decrypt the auth.enc file using mate_auth_export
, edit the authentication tables based on the IPRegExp values, and then re-import the file using mate_auth_import
.
The authorization file password and default seed router login credentials consist of the following.
The SNMPv2c information is defined using a single value.
The SNMPv3 information defines authentication and encryption details.
– noAuthNoPriv—Authenticates by username, but does not validate the user and does not encrypt data.
– authNoPriv—Authenticates by username, validates the user using MD5 or SHA, but does not encrypt data.
– authPriv—Authenticates by username, validates the user using MD5 or SHA, and encrypts data using DES or AES.
After you have created the initial encrypted authentication file, you can manually edit the contents to add multiple profiles or communities and map routers to them. Each profile contains a complete set of SNMPv3 authentication and encryption information. Multiple profiles or communities are necessary when different groups of routers use different authentication credentials. For information about editing an encrypted authentication file, see Add Router-Specific Authentication Information.
The contents of the encryption file are organized into tables.
Note If both SNMPv2c and SNMPv3 are selected, the default is for the auth.enc file to put all nodes in both SNMPv2c and SNMPv3. When a node is mapped to both, then only SNMPv3 is used. To change this behavior, decrypt the auth.enc file using mate_auth_export
, edit the authentication tables based on the IPRegExp values, and then re-import the file using mate_auth_import
.
You can add additional router-specific information to the authentication file by adding rows to the authentication file tables (see Tables in the Authentication File). For router login and authentication, edit the <UserTable>. For SNMP, the following tables apply.
IPRegExp
column.
IPRegExp
column.
If the authentication file is encrypted using a master password, you must first export the contents to plain text using the
mate_auth_export
tool, edit the tables using a text editor, and then encrypt it using
mate_auth_import
.
For SNMPv2c communities only, a more convenient method is provided by
auth_try_communities
. First provide a list of nodes (routers), for example from a plan file obtained through parsing the IGP database. You are then prompted for a number of communities to try. The tool attempts SNMP access to all the routers using each of the communities. If any routers are accessed successfully, these communities are entered in the authentication file to match the router names.
You can run the
auth_try_communities
tool repeatedly to add communities to the authentication file.
Note There is no equivalent tool for SNMPv3.
You can view the entire contents of the authentication file using the
mate_auth_export
tool, which exports a decrypted version of an authentication file. You can also view authentication information for a specific router using the
mate_auth_test
tool. Either way, you need the master password to view the contents.
Test the authentication file using one of these tools.
mate_auth_test
—Prints authentication credentials for a specified authentication file, for a specified node IP address. The output returns whether the lookup is successful or optionally, shows all authentication details in plain text.
snmp_test
—Tests access to a specified router by sending a ping and an SNMP query using the credentials in the authentication file. If both SNMPv2c and SNMPv3 are present, then SNMPv3 is used.
login_test
—Tests login access to a specified router; in doing so it tests the login information provided by the authentication file. Note The tasks of configuring a plan file archive repository and inserting plan files into the archive are supported in both augmentation and manual collection methods. If you are collecting data only by configuring the WAE Collector web UI, then the archives described in this chapter are not applicable.
An archive is a repository containing network plan files, specific data items for plotting, and other data that is collected through augmented or manual snapshots. Additionally, information can be added to archives using CLI tools outside the snapshot process.
This chapter describes the basic archive tools.
Use
archive_init
to either create a new archive repository or to update the file structure of an existing archive.
archive_init
-archive
parameter to the path and name of the directory that will hold the archive. This creates a new, empty archive. The structure and support files for the archive are not complete until after the first recorded insertion.
archive_init
-archive
parameter to the directory of an existing archive and set
-upgrade
option to
true
. This updates the file structure of the existing archive to that of the latest release.
Use
archive_update
to update the summary of time-sequence plot data stored in an archive, for example after changing the summary format file.
-archive
parameter to the location of an existing archive.
-timeplot-summaries
parameter to
true
.
-start-time
parameter to the timestamp of the first record to update.
By default, this tool updates all records from the start time stamp to the end of the archive, however, you can optionally specify the
-end-time
.
For information on configuring the time-sequence plot data, see the Cisco WAE Design Archive User and Administration Guide .
Each archive record can contain one or more of the following files.
snapshot
tool.For WAE Design Archive, the archive can also contain a visual format file, which specifies how the time-sequence plot data should be displayed in the web browser.
You can insert files all at once using one
archive_insert
tool, or individually using multiple CLI tools. All files in the archive repository are stored and accessed using a timestamp, so unless you want to use the default current timestamp when adding files to the archive, you include the
-time <timestamp>
option.
Note If the snapshot
tool is configured to generate .txt format plan files, use the mate_convert
tool before archive_insert
to convert the .txt format plan file to the .pln format plan file.
Inserting a plan file into the archive automatically updates the files needed for interacting with the archive information via the web browser. For this reason, do not copy a file into the archive directory.
You can also insert WAE Design Archive plan files into the archive by choosing File > Save to > Design Archive in the WAE Design GUI. For information, see the Cisco WAE Design Archive User and Administration Guide .
After files have been archived, you can retrieve a copy using the
archive_extract
tool. CLI options specify which files to retrieve, where to copy them, and what to name them. You must include a timestamp. However, you can also specify that WAE Collector use the closest time to the timestamp provided, or you can specify a range of time to get a batch of files.
To retrieve user files with
archive_extract
, follow one of these options.
-user-files
option.
-user-files-list
option.
You can also use
archive_extract
to remove items from the archive. The procedure is the same as for extracting files, except that you use the
-delete
parameter to delete the file after extraction. This process ensures that you always have a local copy of files that you delete, in case the deletion was accidental or incorrect.
You can also retrieve plan files from the archive by choosing File > Open from > Design Archive or File > Open from > WAE Live in the WAE Design GUI. For information, see the Cisco WAE Network Visualization Guide .
The
archive_config
tool enables you to manage the archive repositories available to the WAE Design Archive application on the web server. This tool creates an
archivelist.xml
file in the
$CARIDEN_HOME/etc/archive/config
directory.
-action add
—Add the archive repository to a specific location.
-name
—Name of the archive repository.
-path
—Full path of the archive repository.
-template-dir
—Full path of the template.
-template-name
—Name of the template used by all files in this archive repository.
Example:
This example adds an archive named SW_Region that has a path of
acme/archives/acme_backbone
. The template directory is
acme/data
and the template name is
acme_backbone-template.pln
.
archive_config -action add -name SW_Region -path acme/archives/acme_backbone -template-dir acme/data -template-name acme_backbone-template.pln
Note The archive_config
CLI tool and the WAE Design GUI Archive feature do not apply to WAE Live.
Maintenance of archives sometimes requires similar updates to multiple files in an archive. Here are two examples:
You can perform this task with individual CLI tools, or in many cases you can use the
archive_do
tool to consolidate the CLI tools. The
archive_do
tool gets a list of timestamps between
-time
and
-time-to
, using
archive_extract
, and then performs the following for each timestamp.
archive_extract
to extract all
%extract_*
files into a local directory.
-cmd
argument sequence in the local directory.
Table 4-10
lists the valid variables in the
-cmd
argument.
archive_insert
to insert all
%insert_*
files into the archive.
The
archive_do
tool creates a list of CLI calls for all timestamps, fills in the temporary files at each step, and surrounds the calls with the relevant
archive_extrac
t and
archive_insert
tools. You can view the CLI tools without applying them to an archive by specifying the
-dry-run
option.
Example: This shows how to update the summary file for every plan in an archive.