--- name: "map" section: "3tnm" platform: "linux" package: "scotty" version: "4:00-02-21-2" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/map/3tnm" --- # map(3tnm) Manipulate network maps. ``` ``` ## 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. ## SEE ALSO [scotty(1)](/scotty/1.md), Tnm(n), [Tcl(n)](/Tcl/n.md) ## AUTHORS Juergen Schoenwaelder \