map(3tnm) · carta

NAME

Tnm::map - Manipulate network maps.

DESCRIPTION

The Tnm::map command allows to manipulate network maps. Network maps describe the topology of a network which is managed by applications based on the Tnm Tcl extension. A map is composed out of several items. Each item is of a specific type (e.g. node, network, port or link). The type defines the operations a Tcl script can perform on an item.

ATTRIBUTES

Every map and every item can have arbitrary user-defined attributes. These attributes can be used for different purposes:

1.: Attributes can be used to attach useful administrative information to network maps or items, like contact information or registration numbers.

2.: Attributes can contain parameters that are needed in order to talk to an item, like for example parameters for SNMP sessions.

3.: Attributes can specify parameters that control monitoring or testing functions. A classic example is an attribute which allows to define the interface speed in case the interface speed reported by an SNMP agent does not match reality.

4.: Attributes can store temporary information that is needed by monitoring or testing functions in order to complete their job.

An attribute naming convention is used to make sure that attributes can be used for all these purposes without the risk to run into name clashes. Attributes are grouped into persistent and non-persistent attributes. (Persistent attributes are saved with a network map while non-persistent attributes are ignored.)

Attribute names may only consist of uppercase and lowercase letters, digits and the symbol `:'. Persistent attribute names use the following naming scheme:

[Scope]:Name[:Qualifier]*

A persistent attribute name usually starts with a scope name, which is a capitalized string. An attribute name, which must be capitalized, is said to be global if the scope name is missing. (This means that the name starts with a colon.) The name can be followed by multiple qualifiers, where each qualifier is separated by a colon. Examples of persistent attribute names are:

:Contact
Icmp:Timeout
Tnm:Monitor:ifSpeed:1

Non-persistent attributes have no restriction, except that they are not allowed to start with a capital letter or a colon. It is however recommended to qualify non-persistent names with a common prefix in order to avoid name clashes.

EVENTS

Network maps support an event driven programming style where the functions to test or monitor properties of map items are separated from the code that handles the results. A test or monitoring function, which might be running periodically in the background, generates events that are either associated with a map item or with the map as a whole. Events have an event tag which is used to describe the event type (e.g. Tnm:Error:Snmp:noResponse). It is suggested to use the same naming conventions for event tags which are described above in the paragraph about persistent attribute names.

BINDINGS

Events can trigger event bindings, which allow to execute arbitrary Tcl commands. Event bindings are either associated with an item or with a complete map. A binding is defined by a pattern, which is matched against event tags. The match uses the same rules as described for the Tcl string match command. The body of an event binding is a Tcl script, which is executed in global context whenever an event tag matches the binding pattern.

Events that are associated with a map item will first trigger all event bindings for that particular item. Afterwards, the event will be passed to the parent item (if any). Once the event has reached the root item, the event will be passed to the network map. Events that are associated with a network map will only trigger the event bindings defined for that particular map.

The processing of event bindings can be controlled by returning a break or continue return code from the script. A break return code will stop event processing. A continue return code will stop event processing for the current item and immediately start with the bindings defined for the parent item (if any) or for the whole map.

Event details can be accessed in the script which is bound to an event by means of % substitutions. These substitutions happen before the script is passed to the Tcl interpreter. The following substitutions are defined:

%%: Replaced with a single percent.

%A: Replaced with the event arguments.

%B: Replaced with the handle for the binding that matched the event tag.

%E: Replaced with the unique handle for the event.

%I: Replaced with the handle for the item or an empty string if the event is generated for a map.

%M: Replaced with the handle for the map.

%N: Replaced with the event name that triggered the binding.

%P: Replaced with the pattern that matched the event tag.

MESSAGES

Messages can be attached to maps or map items. A message consists of a time-stamp, a time interval, a tag and a text string. Messages are only kept for a short period in memory. Messages can also be saved in files. Every message is prepended with the message time-stamp and the message interval.

Messages are saved in files if two conditions are met. First, the associated item or map must have a non-empty -path option. Second, the message tag must match one of the pattern contained in the value of the -store option. The -store option is a convenient way to select which messages go to a file and which not.

The file name is derived from the value of the -path option. It is constructed from the -path value by appending a subdirectory for the current day and the message tag as a file name. The message text itself is prepended by the time-stamp (in seconds), a tab character, the time interval, another tab character and appended to the file. New directories are created on the fly if needed.

As an example, lets assume we have a map where the -path option has the value /tmp/yourmap and the -store option contains the list element "ifload*". A message is generated on May 27th, 1997 with the tag ifload-3 and the text "52". This message will be appended to the file /tmp/yourmap/1997-05-27/ifload-3.

Messages provide a convenient mechanism to collect statistics. However, message files can consume quite a bit of disk space. No attempts are made to compress raw message files and there are currently no commands to read and process them later via Tcl in a convenient way. Compression, data reduction or analysis of the statistics should be done by specialized programs which are run periodically.

MAP COMMAND

Tnm::map create [option value ...]: The Tnm::map create command is used to create network maps. The command returns a handle which can be used to manipulate the new map. A Tcl interpreter is able to control an arbitrary number of map instances.

Tnm::map info subject ?pattern?: The Tnm::map info command retrieves information about the maps handled by the Tcl interpreter. The optional pattern is used to select a subset. The subject maps returns the list of existing maps. The pattern is matched against the map name. The subject types returns the list of item types. The pattern is matched against the type name.

MAP INSTANCE COMMANDS

map# attribute [name [value]]: The map# attribute command allows to save map specific data in map attributes. If called without any arguments, all existing attribute names for this map will be returned. If called with a name argument, the current value of the attribute will be returned. Non-existing attributes do not produce an error. Instead, an empty string is returned. Evaluating the map# attribute command with a name and a value argument causes the value to be saved in the map attribute name.

map# bind pattern script: The map# bind command binds a Tcl script to an event. A binding is created by evaluating this command with a pattern which is later matched against event tags. A successful match will trigger the evaluation of the Tcl script bound to the pattern. Pattern matching is done as described in the documentation for the Tcl string match command. It is possible to create multiple bindings for the same pattern. The map# bind command returns a handle for the new binding.

map# cget option: The map# cget command retrieves the value of a map option given by option. See the description of map options below for more details.

map# clear: The map# clear command re-initializes the map into an empty state. All data currently associated with the map is deleted.

map# configure [option value ...]: The map# configure command allows to query or change the current configuration options of a map instance. See the description of map options below for more details.

map# copy items: The map copy command copies a Tcl script on the internal clipboard buffer which can be used to create a clone of the items. The internal clipboard buffer is shared between all maps in the running process. It can therefore be used to copy objects between maps.

map# create type [option value ...]: The map# create command allows to create a new item of the given type. It returns a handle which can be used later to manipulate the new item. Item type specific options can be passed as part of the map# create command in order to initialize the new item. Consult the item type specific option description for a list of valid options.

map# destroy: The map# destroy command destroys the map. All data associated with the map is deleted. No attempts are made to save the contents of the map. It is the responsibility of the script to save the map before destroying it.

map# dump: The map dump command returns a Tcl script which can be evaluated to create a copy of the current map.

map# find [-type type] [-name name] [-address address] [-tags patternList] [-sort mode] [-order direction]: The map# find command retrieves a list of item handles that match the search options. If no options are present, a list of all items on the network map is returned. The -type option restricts this list to those items of a given type. The -name and -address options restrict the list to all those items, where the name or address matches the given name or address pattern. The -tags option matches the tag associated with an item against the pattern contained in the patternList. Matching is done according to the rules defined for the Tcl string match command. The -sort option sorts the output according to a given sort mode. Valid sort modes are mtime and ctime. The sorting order can be specified by setting the -order option to increasing or decreasing. Increasing sort order is the default.

map# info subject ?pattern?: The map# info command returns a list of handles that are related to this map. The optional pattern is used to select a subset. The subject events returns the events associated with the map. The pattern is matched against the event name. The subject messages returns the message handles associated with the map. The pattern is matched agains the message tag. The subject bindings returns the list of binding handles for the map. The pattern is matched agains the binding pattern.

map# load channel: The map load command loads a map from a Tcl channel, which might point to a previously opened file or a network connection. This command actually merges the items since existing items are not removed or overwritten. The use of a channel allows to load maps in safe Tcl interpreters by passing the channel from a trusted Tcl interpreter to a safe Tcl interpreter.

map# message [-interval sec] [-health value] tag text

The map# message command creates a message which contains the given text. The message is kept in memory until it expires. Messages might be appended to files if the message tag matches one of the patterns contained in the value of the -store map option and if the value -f the -path map option is not empty.

Message are used to report statistics or events. Every message is automatically augmented with a time-stamp. However, many statistics or events are bound to a time interval. The -interval option allows to specify such a time interval in seconds. The interval value is set to 0 if this option is missing.

Messages can also be used to influence the health of the map. The value of the -health option must be in the range of -100..100 and indicates a negative or positive health change. The exact computation of the health of the map uses these indications to derive a new health value whenever the map ticks. The health value is be set to 0 if this option is missing.

map# paste: The map paste command evaluates the Tcl script found on the internal clipboard buffer. This creates a clone of the items that have been previously copied on the clipboard.

map# raise tag [args]: The map# raise command raises an event on the map. The event type is identified by the string tag. Additional arguments, which describe event details, can be supplied in the optional args parameter. The map# raise command returns a handle for the new event. This handle can be used later to retrieve information about this specific event or to delete this event.

map# save channel: The map save command writes a Tcl script to the given channel, which, when evaluated, re-generates the current network map. The save command makes it possible to write a map from a safe Tcl interpreter to a channel provided by a trusted interpreter, if the channel is shared between both interpreters.

map# update: The map update command processes all pending updates. This includes removal of events or messages that have expired.

MAP OPTIONS

The following options control parameters of a network map object.

-expire seconds: The -expire option defines the default lifetime for events and messages in seconds. Events and messages are removed from the event history automatically if the -tick option is greater than zero and the lifetime of the event or message has expired.

-height height: The -height option defines the height of the map in terms of virtual pixels.

-name name: The -name option defines the name of the map.

-path path: The -path option defines the path in the file system, where map statistics will be stored. All statistic files are maintained in a sub-directory, which is used to group together all statistics of a particular day.

-store patternList: The -store option is used to maintain a list of message tag pattern that are used to control whether a message is written to a file or not. Each element of the patternList is matched against a message tag. A positive match will cause the message to be saved in a file.

-tick interval

The -tick option defines the tick interval in seconds. The map implementation updates internal data every time the tick interval has passed. Internal operations include the update of the health of all map items or the expiration of events or messages. Setting the tick interval to 0 means that no internal updates will be performed.

A tick interval of 0 may result in a serious memory leak if events or messages are generated frequently. The default value for the tick interval is 60 seconds.

-width width: The -width option defines the width of the map in terms of virtual pixels.

EVENT INSTANCE COMMANDS

The following commands can be used to query event objects for event specific parameters. Note that event objects can disappear automatically if their lifetime expires. These commands are read-only in the sense that you can not modify an existing event other than deleting it.

event# args: The event# args command returns the argument string that was passed to a map# raise or item# raise command when the event was created.

event# destroy: The event# destroy command destroys the event object.

event# item: The event# item command returns the item which is associated with the event. An empty string is returned if the event is not associated with an item.

event# map: The event# map command returns the map which is associated with the event. If the event is associated with an item, the map which owns the item will be returned.

event# tag: The event# tag command returns the string which is used to identify the event type. This is the same string which has been used when the event was created by a map# raise or item# raise command.

event# time: The event# time command returns the date and time when this event was generated as a system-dependent integer value. The resolution of the event timestamp is seconds. The value has the same properties as timestamps returned by the Tcl clock seconds command.

event# type: The event# type command returns the type of the event object, which is always the string "event".

BINDING INSTANCE COMMANDS

The commands described in this section allow to query event bindings for their parameters. These commands are read-only in the sense that you can not modify an existing binding other than deleting it.

bind# destroy: The bind# destroy command destroys the binding object.

bind# item: The bind# item command returns the item which is associated with the binding. An empty string is returned if the binding is not associated with an item.

bind# map: The bind# map command returns the map which is associated with the binding. If the binding is associated with an item, the map which owns the item will be returned.

bind# pattern: The bind# pattern returns the pattern that is matched against event tags. This is the same string that was passed to a map# bind or item# bind command when the binding was created.

bind# script: The bind# script returns the script that is associated with the event binding. This is the script parameter that was passed to a map# bind or item# bind command when the binding was created.

bind# type: The bind# type command returns the type of the binding object, which is always the string "binding".

MESSAGE INSTANCE COMMANDS

The following commands can be used to query message objects for message specific parameters. Note that message objects can disappear automatically if their lifetime expires. These commands are read-only in the sense that you can not modify an existing message other than deleting it.

message# destroy: The message# destroy command destroys the message object.

message# health: The message# health command returns the health change value of the message object in the range -100..100.

message# interval: The message# interval command returns the time interval associated with the message object in seconds.

message# item: The message# item command returns the item which is associated with the message. An empty string is returned if the message is not associated with an item.

message# map: The message# map command returns the map which is associated with the message. If the message is associated with an item, the map which owns the item will be returned.

message# tag: The message# tag command returns the string which is used to identify the message type. This is the same string which has been used when the message was created.

message# text: The message# text command returns the argument string that was passed when the message was created.

message# time: The message# time command returns the date and time when this message was generated as a system-dependent integer value. The resolution of the message timestamp is seconds. The value has the same properties as timestamps returned by the Tcl clock seconds command.

message# type: The message# type command returns the type of the message object, which is always the string "message".

COMMON ITEM COMMANDS

This section describes commands that are common to most item types. The sections that describe particular item types define the subset of these common item commands applicable to a particular item type.

item# attribute [name [value]]: The item# attribute command allows to save item specific data in item attributes. If called without any arguments, all existing attribute names for this item will be returned. If called with a name argument, the current value of the attribute will be returned. Non-existing attributes do not produce an error. Instead, an empty string is returned. Evaluating the item# attribute command with a name and a value argument causes the value to be saved in the item attribute name.

item# bind pattern script: The item# bind command binds a Tcl script to an event. A binding is created by evaluating this command with a pattern which is later matched against event tags. A successful match will trigger the evaluation of the Tcl script bound to the pattern. Pattern matching is done as described in the documentation for the Tcl string match command. It is possible to create multiple bindings for the same pattern. The item# bind command returns a handle for the new binding.

item# cget option: The item# cget command retrieves the value of an item option given by option. See the description of item options below for more details.

item# configure [option value ...]: The item# configure command allows to query or change the current configuration options of a item instance. See the description of item options below for more details.

item# destroy: The item# destroy command destroys the item. All data associated with the item is deleted.

item# dump: The item dump command returns a Tcl script which can be evaluated to create a copy of the current item.

item# info subject ?pattern?: The item# info command returns the list of handles that are related to this item. The optional pattern is used to select a subset. The subject events returns the events associated with the item. The pattern is matched against the event name. The subject messages returns the message handles associated with the item. The pattern is matched agains the message tag. The subject bindings returns the list of binding handles for the item. The pattern is matched agains the binding pattern. The subject member, which is only supported by container objects, returns the list of members of this item. The pattern is ignored in this case.

item# map: The item# map command returns the map which controls this item. Items are always associated with a single map and items can not move directly from one map to another.

item# message [-interval sec] [-health value] tag message

The item# message command creates a message which contains the given text. The message is kept in memory until it expires. Messages might be appended to files if the message tag matches one of the patterns contained in the value of the -store item option and if the value -f the -path item option is not empty.

Message are used to report statistics or events. Every message is automatically augmented with a time-stamp. However, many statistics or events are bound to a time interval. The -interval option allows to specify such a time interval in seconds. The interval value is set to 0 if this option is missing.

Messages can also be used to influence the health of the item. The value of the -health option must be in the range of -100..100 and indicates a negative or positive health change. The exact computation of the health of the item uses these indications to derive a new health value whenever the item ticks. The health value is be set to 0 if this option is missing.

item# move [x y]: The item# move command moves the item from the current position on the virtual map by adding x and y to the current position. The command returns the new position as a list containing the x and the y position. The item# move command only returns the current position if the optional arguments are missing.

item# raise tag [args]: The item# raise command raises an event on the item. The event type is identified by the string tag. Additional arguments, which describe event details, can be supplied in the optional args parameter. The item# raise command returns a handle for the new event. This handle can be used later to retrieve information about this specific event or to delete this event.

item# type: The item# type command returns the type of an item. See below for a description of item types.

COMMON ITEM OPTIONS

This section describes common item options. The sections that describe particular item types define the subset of these options applicable to a particular item type.

-address address: The -address option defines the address of the item. No assumptions are made by the Tnm map implementation about the format and the semantics of the address. Scripts that interpret the value of a -address option should carefully check whether the format is acceptable.

-color color: The -color option gets or sets the color of the item. No assumptions are made on the format of the color value. It is however suggested to use Tk color names.

-ctime time: The -ctime option gives access to the creation date and time as a system-dependent integer value. The resolution of the creation time is seconds. The value has the same properties as time-stamps returned by the Tcl clock seconds command. This option is read-only because the creation time-stamp is maintained entirely by the map implementation.

-expire seconds: The -expire option defines the default lifetime for events and messages in seconds. Events and messages are removed from the event history automatically if the -tick option is greater than zero and the lifetime of the event or message has expired.

-font font: The -font option gets or sets the font of the item. No assumptions are made on the format of the font value. It is however suggested to use Tk font names.

-group group: The -group option is used to make the item a member of the group group. Setting this option to an empty string removes the calling item from the group.

-icon icon: The -icon option gets or sets the icon associated with an item. No assumptions are made on the format of the icon value.

-mtime time: The -mtime option gives access to the last modification date and time as a system-dependent integer value. The resolution of the modification time is seconds. The value has the same properties as time-stamps returned by the Tcl clock seconds command. This option is read-only because the modification time-stamp is maintained entirely by the map implementation.

-name name: The -name option defines the name of the item. No assumptions are made by the Tnm map implementation about the format and the semantics of the name. Scripts that interpret the value of a -name option should carefully check whether the format is acceptable.

-path path: The -path option defines the path in the file system, where item statistics will be stored. All statistic files are maintained in a sub-directory, which is used to group together all statistics of a particular day.

-store patternList: The -store option is used to maintain a list of message tag pattern that are used to control whether a message is written to a file or not. Each element of the patternList is matched against a message tag. A positive match will cause the message to be saved in a file.

-tags tagList: The -tags option is used to tag items. Tags are a convenient way to group items together to form target sets for management operations. For example, one might want to tag all routers with the tag "router" and all devices from vendor acme with "acme". The map# find command can later be used to retrieve all "routers" from vendor "acme".

NODE ITEMS

Node items are used to model network elements like bridges, router, switches, or end-systems. Node systems can contain several port items which interface to other objects.

PORT ITEMS

Port items are always associated to a node item and represent an interface to other objects. A common usage of port objects is to represent interfaces on a router. Ports can also be used to represent ends of ATM VPCs or ports on an Ethernet bridge. A port item can be the source or destination of a link object which connects the port to other ports or networks.

Port item specific options:

-node node: The -node option is used to associate a port item with a node. Setting this option to an empty string removes the calling item from the node. Port items should always be associated to node items. This is however not strictly enforced by the implementation.

NETWORK ITEMS

Network items represent transmission networks like e.g an Ethernet segment, an X.25 or an ATM connection. A network object might also represent a complex network if there is no need to have more detailed information available. It is up to the application to determine the required level of detail.

LINK ITEMS

Node items are connected to other items by means of link items. A link item connects a port item to another port item or a network item. It is therefore not possible to connect to networks with a single link item. It is also not possible to connect a node with another node or a network without attaching a port object to the node.

GROUP ITEMS

Group items are container items that can contain a set of other items, including other group items. However, the containment structure must form a hierarchy. It is not allowed to have a group which directly or indirectly contains itself. It is however allowed, that a single item is a member of several different groups.

TODO

There are some item type specific options and commands that are not yet documented. The current version also does a poor job to clearly describe which option and command is supported by which item type.

AUTHORS

Juergen Schoenwaelder <[email protected]>