Configuration guide
From Sanet
Configuration guide
Using the CLI
SANET is configured via an IOS-like CLI. You can start the cli with the command $SANET_HOME/bin/sanet-cli (you can put or symlink it in your PATH). It is designed to be familiar for people skilled with Cisco IOS.
In the cli the usual line-editing facilities from the readline library, including history and completion, are available. History is not persistent between sessions. Completion works with the TAB key or with the question mark, and gives help on the available commands or arguments.
After most commands you can put a pipe sign "|" followed by keywords for include, exclude, etc. This is designed to mimic IOS, with some additions from JunOS.
The CLI starts at the main prompt, and you can enter a different prompt "downwards" with the appropriate command, and exit one level with exit or quit. The current mode can be seen in the prompt.
Most of the configuration work is done in configuration mode, you enter it from the main prompt with configure terminal. You can view the current configuration with show configuration. Changes are immediately saved to the DB and made active (there is no "write mem").
Some commands are available at all levels: they are called ubiquitous commands, and the most prominent is the show command. If you are an IOS user, there is no "do", you just issue "show". If you are a JunOS user, "show" in config prompt is the regular "show", it doesn't show the configuration (but you can use "show conf" anyway).
You can save a copy of your current configuration from the unix prompt in a text with $SANET_HOME/etc/rc.sanet cli-save, the file will be named current-cli-confg in $SANET_HOME/etc, and any old file with the same name will be saved in a timestamped version.
Creating an object usually implies entering the object's configuration prompt, if the object is complex enough to have some configuration (some aren't, e.g. groups and notes).
Negating a command is usually done with the no form of the same command. This is true also for deleting objects, but usually the CLI requires you to confirm your will to delete the object by repeating its name twice. For example:
- To create a node, you enter configuration mode and issue node mynode
- To delete that same node, you return to configuration mode and issue no node mynode mynode
- To configure a tree for containing all nodes, in the tree configuration prompt you issue allnodes.
- If you want to revert the tree to containing only specific nodes, you issue no allnodes.
Most objects can be renamed with the rename command, issued at the same configuration level where you would create the object. So, to rename a node you enter the main configuration prompt and issue rename node oldname newname command. Renaming preserves the object's configuration and takes care of all the references to the object from other objects: in the few cases where this is impossible for SANET to do, renaming is disallowed and the corresponding command is missing.
Escaping at the SANET cli is quite tricky. You can escape spaces and other special characters enclosing the arguments in double quotes, and using the backslash. Non-ascii characters can be entered directly in UTF-8 (if your terminal does so) or by backslash-escaping the bytes in hex (you have to know the UTF-8 encoding of the character to do that). Example:
sanet(config)# site description Sito di città sanet(config)# sh conf site | i description site description "Sito di citt\xc3\xa0"
Some commands are designed to accept multiline input as dot-terminated text, as in the SMTP protocol. You terminate your input with a line consisting of a single dot, and if you need to enter a line made of a single dot you can do that by entering two dots.
The detailed documentation for the CLI commands can be found in the CLI reference.
Configuring site parameters
Site parameters control the general appearance or working of the SANET installation. You can view the current site informations with show version, and the site configuration with show configuration site. You should at a minimum configure the site name.
sanet# conf t sanet(config)# site ? banner Set login banner (input dot-terminated text) description Set site description delay-per-target Set a delay for each target checked details Set site HTML details (input dot-terminated text) icon Set site icon mincycletime Set minimun cycle time name Set site name statperiod Set interval between stat entries in log threads Set number of threads watchdog-period Set interval between watchdog messages watchdog-mail Set watchdog messages recipient note Assign a note to site (input dot-terminated text)
For the site name, it is customary to use a short uppercase string, like MYCOMPANY. Description will be shown in the web, into the site details block, and in alarm messages. Site details is a piece of HTML that will be copied verbatim in the web, site details block: you can put here HTML tags for images, or links to whatever you find useful to have in that block. To customize your site icon, see #Configuring icons.
The number of threads is 50 by default, it is the number of threads launched by the poller for checking targets and measures. The default should be OK for medium installations, you con raise or lower it according to your needs, but keep in mind that each thread will consume resources (mainly RAM), and raising above 200 - 300 is not very effective because of technical limitations in the Python interpreter. Changing requires restarting the poller.
Configuring nodes, interfaces and links
Nodes
A SANET node is the object representing a network device or a server that you want to keep monitored. The node has a unique name, that SANET will use to retrieve the IP address(es) of the node. The node name must be a valid dns name in lowercase, max 63 chars, or an IPv4 literal. If the name is not qualified, it will be resolved according to your OS settings. You can see what the node name resolvs to with show ip nodes <name>.
sanet(config)# node myserver Creating node myserver sanet(config-node)# sh ip nodes myserver myserver : 192.168.0.2
Add a human-readable description for the node with decription, anc change its icon with icon.
If you plan to use SNMP on this node you should set the community and snmpversion. snmpversion can be:
- 0 to disable SNMP for this node, it will never be queried (not even when you issue "sh node")
- 1 for snmpv1 over UDP over IPv4
- 2 for snmpv2c over UDP over IPv4
- 3 for snmpv3 over UDP over IPv4
- 61 for snmpv1 over UDP over IPv6
- 62 for snmpv2c over UDP over IPv6
- 63 for snmpv3 over UDP over IPv6
Please note that most devices do not answer SNMP queries over IPv6 (at the time of this writing).
When using SNMPv3 the privacy and authentication parameters, as well as the context, are encoded into the community string. The community has the format:
username:<username>,sec_level:[noauth|auth|crypt][,auth_proto:[md5|sha]][,auth_pass:<password>][,priv_pass:<password>][,context:<context>]
When contacting a node via IPv6, SANET by defaults tries to resolve the node name to an IPv6 address. If your node has separate names for IPv4 and IPv6, you can configure its ipv6name to its IPv6 name or to its IPv6 address literal.
Configuration of the node category, targets and measures is covered in Monitoring nodes and interfaces.
You can see the node configuration with show configuration node <name>, or a summary with show node (less details) or show node <name> (more details).
Interfaces
You can think of an interface as an RJ45 jack (female, i.e. a receptacle) in your node. An interface in SANET is a little more general than this: roughly, it is one of the rows of the node's SNMP IfTable (1.3.6.1.2.1.2.2).
If you want to monitor an interface of a node in SANET, you have to create the interface in the node configuration menu, and tell SANET enough information to uniquely determine the interface among the (possibly many) actual interfaces of the node.
Interfaces in SNMP are identified by their ifIndex, an integer which acts as the "primary key" of the ifTable. You can match interface names with their ifindexes with an SNMP walk:
sanet# sh walk smallrouter 1.3.6.1.2.1.2.2.1.2 .1.3.6.1.2.1.2.2.1.2.1 : ATM0 .1.3.6.1.2.1.2.2.1.2.2 : Ethernet0 .1.3.6.1.2.1.2.2.1.2.3 : Null0 .1.3.6.1.2.1.2.2.1.2.4 : ATM0-atm layer .1.3.6.1.2.1.2.2.1.2.5 : ATM0.0-atm subif .1.3.6.1.2.1.2.2.1.2.6 : ATM0-aal5 layer .1.3.6.1.2.1.2.2.1.2.7 : ATM0.0-aal5 layer .1.3.6.1.2.1.2.2.1.2.8 : ATM0-interleave .1.3.6.1.2.1.2.2.1.2.9 : ATM0-fast .1.3.6.1.2.1.2.2.1.2.10 : ATM0-adsl .1.3.6.1.2.1.2.2.1.2.11 : ATM0.1-atm subif .1.3.6.1.2.1.2.2.1.2.12 : ATM0.1-aal5 layer
If you want to use the ifIndex to identify the interface, you can do that with the instance keyword of the interface command, at node configuration level:
sanet# conf t sanet(config)# node smallrouter Creating node smallrouter sanet(config-node)# int e0 instance 2 Creating interface e0 in node smallrouter
In many devices ifIndexes are not constant, and change at reboots or at reconfiguration, and so there is a concrete risk of monitoring the right interface for some time, and then for an obscure reason start monitoring the wrong interface. SANET has a very powerful feature to identify the interface by different means, like name, MAC, IP, etc. This is achieved with the xform keyword.
If you use the xform keyword when creating a SANET interface, then you give sanet an expression, that transforms the instance in the ifindex. SANET expressions are the basis for target and measures, and you can find a reference of the language used in expressions in the Expression language reference.
For now, you can keep in mind the following cookbok:
- by ifindex: instance is the ifindex, no xform.
- by ifdescr: instance is the ifdescr, e.g. Ethernet0, xform is "byRegexpUnique(1.3.6.1.2.1.2.2.1.2,^$instance$)". This xform can be abbreviated as xform ifdescr.
- by ifAlias: instance is the ifAlias, e.g. Ethernet0, xform is "byRegexpUnique(1.3.6.1.2.1.31.1.1.1.18, ^$instance$)"
- by cisco "description" command, anchored: instance is the cisco description, e.g. "Line leading to ACME", xform is "byRegexpUnique(1.3.6.1.4.1.9.2.2.1.1.28,^$instance$)".
- by cisco "description" command, not anchored: instance is a regexp matching the description (of one and only one interface of that node), e.g. "ACME", xform is "byRegexpUnique(1.3.6.1.4.1.9.2.2.1.1.28,$instance)".
- by assigned IP address: instance is the dotted quad of the IP address, xform is "1.3.6.1.2.1.4.20.1.2.$instance:$community@$node".
- by MAC address (ethernet only): instance is the MAC in hex lowercase without any separator, exactly 12 chars, xform is "byBinaryValue(1.3.6.1.2.1.2.2.1.6:$community@$node,$instance)".
- by IP route present: instance is the dotted quad of the base of the routed prefix, xform is "1.3.6.1.2.1.4.21.1.2.$instance:$community@$node". This will not work with multiple routes with same base and different prefix lengths nor with multiple routes in different VRFs.
- by CDP neighbor: instance is a regexp uniquely matching the neighbor name (not anchored), xform is "oidFirst(byRegexpUnique(1.3.6.1.4.1.9.9.23.1.2.1.1.6,$instance))".
- by MAC in the FDB table: useful for monitoring ports of switches leading to specific servers, instance is the hex of the MAC without separators, xform is "1.3.6.1.2.1.17.4.3.1.2.byBinaryValue(1.3.6.1.2.1.17.4.3.1.1:$community@$node,$instance):$community@$node".
The instance and xform combination must identify an unique interface. If the node has two or more interfaces matching the configured instance and xform, SANET will try to "stick" with the first of the matching interfaces, but this is seldom the desired behaviour.
The actual ifIndex of the interface will be evaluated whenever SANET needs do chek a target or perform a measure on it. You can force immediate evaluation with the refresh ifindex <node> <interface> command.
sanet# sh walk myfw 1.3.6.1.2.1.2.2.1.2 .1.3.6.1.2.1.2.2.1.2.1 : lo .1.3.6.1.2.1.2.2.1.2.2 : eth0 .1.3.6.1.2.1.2.2.1.2.3 : eth1 .1.3.6.1.2.1.2.2.1.2.4 : eth2 .1.3.6.1.2.1.2.2.1.2.5 : eth3 .1.3.6.1.2.1.2.2.1.2.6 : eth4 .1.3.6.1.2.1.2.2.1.2.7 : eth5 sanet# conf t sanet(config)# node myfw Creating node myfw sanet(config-node)# inter e0 instance 2 Creating interface e0 in node myfw sanet(config-node-iface)# exit sanet(config-node)# inter e1 instance eth1 xform ifdescr Creating interface e1 in node myfw sanet(config-node-iface)# exit sanet(config-node)# int e2 instance 00163e6333e7 xform byBinaryValue(1.3.6.1.2.1.2.2.1.6:$community@$node,$instance) Creating interface e2 in node myfw sanet(config-node-iface)# exit sanet(config-node)# int e3 instance 192.168.0.1 xform 1.3.6.1.2.1.4.20.1.2.$instance:$community@$node Creating interface e3 in node myfw sanet(config-node-iface)# exit sanet(config-node)# exit sanet(config)# exit sanet# sh conf node myfw node myfw category node-nochecks icon node interface e0 instance 2 category iface-nochecks exit interface e1 instance eth1 xform byRegexpUnique(1.3.6.1.2.1.2.2.1.2,^$instance$) category iface-nochecks exit interface e2 instance 00163e6333e7 xform byBinaryValue(1.3.6.1.2.1.2.2.1.6:$community@$node,$instance) category iface-nochecks exit interface e3 instance 192.168.0.1 xform 1.3.6.1.2.1.4.20.1.2.$instance:$community@$node category iface-nochecks exit exit sanet# sh int node myfw e0 ID : 60 NODE : myfw INSTANCE : 2 XFORM : IFINDEX : None TARGETS : 0 MEASURES : 0 CONNECTS : DESCRIPTION : SNMP_DESCRIPTION : None SNMP_OPERSTATUS : None sanet# sh int node myfw e1 ID : 61 NODE : myfw INSTANCE : eth1 XFORM : byRegexpUnique(1.3.6.1.2.1.2.2.1.2,^$instance$) IFINDEX : None TARGETS : 0 MEASURES : 0 CONNECTS : DESCRIPTION : SNMP_DESCRIPTION : None SNMP_OPERSTATUS : None
For now "sh int" shows the ifindex as "None" because SANET never needed to evaluate it. Now let's force its evaluation:
sanet# refresh ifindex myfw e1 ... lots of verbiage omitted ... sanet# sh int node myfw e1 ID : 61 NODE : myfw INSTANCE : eth1 XFORM : byRegexpUnique(1.3.6.1.2.1.2.2.1.2,^$instance$) IFINDEX : 3 TARGETS : 0 MEASURES : 0 CONNECTS : DESCRIPTION : SNMP_DESCRIPTION : eth1 eth1 SNMP_OPERSTATUS : 1 sanet# refresh ifindex myfw e2 ... more verbiage omitted ... sanet# sh int node myfw e2 | i IFINDEX IFINDEX : 4 sanet# refresh ifindex myfw e3 ... more verbiage omitted ... sanet# sh int node myfw e3 | i IFINDEX IFINDEX : 5
Once the interface is created, you can add a description at interface configuration prompt with description: this will be shown in addition to the mixed description from SNMP (ifDescr, cisco description, and some data from ifXtable). If you later want to change instance or xform you can do that at the interface configuration prompt with the instance and xform commands. Monitoring commands will be seen later, in #Monitoring nodes and interfaces.
Links
SANET can build graphical maps and can check adjacencies, if you tell it which interface is linked to which other interface. To configure a link between two interfaces you use, from the main configuration prompt, the command: link <node1> <iface1> <node2> <iface2>. SANET enforces some rules on links:
- You can link exactly two interfaces, no more, no less.
- An interface which is already linked, cannot be linked again to a third interface.
- You cannot link an interface to itself (but you can link two distinct interfaces of the same node).
SANET does not check that the link is actually there, nor that it makes any sense: you can link an ADSL to an ethernet, and it will not complain. It checks actual adjacencies if it is told to do so when configuring monitoring.
SANET links are designed to represent actual physical links, e.g. RJ45 UTP cables or optical fiber pairs. They are not designed to represent multiaccess networks like coax ethernet cables, WiFI networks, pseudowires, etc. In fact, if you are an experienced network professional you probably can think of many situations that cannot easily be modeled with SANET interfaces and links: VLANs, dot1q subinterfaces, trunks and portchannels, MPLS TE tunnels, etc. To achieve your monitoring goals for you specific situation, keep in mind the following:
- In order for SANET to monitor an interface with the checks that you find in the library, the interface needs to have a row in the ifTable.
- Adiacency targets (those using the adjacent() function) check adjacency with the linked interface by default. You can tweak them to check adjacency with someting else, but it is cumbersome and mostly untested.
- Maps in the web interface display a graph with an edge for each link having both endpoints in the map. There is an external application called Vlink, not installed by default, for adding virtual links that will be used for map display only.
- For map readability you can create fake nodes representing multiaccess networks, or cloud-like things like VRFs, the Internet, your provider's MPLS, etc. You can then give the fake node "snmpversion 0" and "icon internet", and an interface for each thing that will connect to it, for linking them to actual physical interfaces of actual physical nodes.
Monitoring nodes and interfaces
Understanding SANET monitoring
SANET monitoring is based on periodical checks of given conditions, and on information retrieval from network devices, server, and services that are part of the network of interest. SANET monitoring is always "active", i.e. a poller process retrieves data from devices, to issue alarms or populate graphs. SANET is not based on traps or syslog messages.
SANET monitoring is done with targets and measures, that can be associated to a node or an interface.
Targets and measures together are called checks. Node and interfaces together are called elements. Checks are identified with a set of parameters, each having a name and a value. Since it is very tedious to configure all parameters directly for each and every check, you use a hierarchical templating system made of categories with some inheritance.
You will find that you often define very similar targets or measures, e.g. the reachability target (ping) for a node, or the traffic in/out an interface. You can thus define a target-category or an interface-category with all the parameter that are common to similar targets or measures, and their values. Sometimes you need two almost, but not quite, equal target-categories o measure-categories: you can then use inheritance, setting one category as parent of the other will make the children inherit all the parameters of the parent and their values, and then you can change parameters in the children as needed.
You will also realize that there are installation with many nodes or interfaces quite similar to each other, i.e. having the same, or almost the same, set of targets and measures. You will then define a node-category or an interface-category, with a set of targets and measures of their respective target-category or measure-category, possibly overwriting the values of some of their parameters. There is no inheritance among node- and interface- categories.
When you place an element in a category (a node in a node-category or an interface in an interface-category), SANET will create all the resulting targets and measures, with the appropriate values for the parameter. If you later modify the target-, measure-, node- or interface- categories involved, sanet will automatically recompute the set of targets and measures and the values of the parameters.
The real world is made of rules and exceptions: you can happen to have 100 nodes, 99 of them identical, and one of them very similar but just a bit different, e.g. needing just one more target, or one less measure, or just a parameter changed in a target. You carefully built the category for the 99 nodes with many checks in it, and you don't want to have an almost duplicate category. SANET allows you to add, change or delete targets and measures for a specific node in a category. When you add a check to an element, independently of its node- or interface- category, you are creating an additional check for the element, where you can also specify values for its parameters. You can also modify the value of a parameter for a check of an element which is not an additional check (i.e. it is a check inherited from its element category, or a category check), with the category-target or category-measure commands at the element configuration prompt. Deletion of a target is done via the deleted parameter: such a check will not show up in the web and will never be evaluated.
To summarize:
- The elements of you network are nodes and interfaces
- SANET performs checks, which are targets and measures, on the elements
- Checks are defined by a set of parameters and their values
- A check has a target- or measure- category, defining the parameter it needs and their values, with inheritance among categories
- A node- or interface- category is a set of checks, with possible assigned values for their parameters, that overwrite the values in the target- or measure- category
- You can put an element in a node- or interface- category, and you can overwrite the value of some of the parameters of the inherited checks, including the "deleted" parameter that actually deletes the check
- You can define additional checks for an element, independent of the element category
Every element will then have a set of checks. Each of them will be an additional check or a category check. Each check will have a check category, defining the set of parameters that apply to the check.
The value of each parameter of each check is evaluated as follows:
- If it is an additional check with that parameter specified, than use that value, otherwise
- If it is a category check with the parameter specified in the element, use that value, otherwise
- If it is a category check with the parameter specified in the element category, use that value, otherwise
- If the parameter value is specified in the check category, use that value, otherwise recurse to the parent check category, otherwise
- Use the default value for the parameter.
Targets
A target is yes/no check, given by an expression. Every time the target is checked, its expression is evaluated: basically, if the result is nonzero the target is UP (green), if it is zero the target is DN (red). The expression is probably the most important parameter of the target, and its name is expr.
In more detail, there are many parameters controlling how and when a target is evaluated, and the states are more than two.
SANET tries to check the target every minperiod seconds. If it finds that it cannot be checked (because it cannot read SNMP values from the node, or because the target dependson another target which is currently down), it puts the target in one of the UU or UD states, depending on its previous state (UP goes to UU, DN goes to UD).
You can configure a target to be checked at specific times of the day or week. If the target is not to be checked for this reason, it will go into one of the TU or TD states.
For planned downtime, you can suspend checking a target, by switching its suspended parameter, and it will go in the IN (inactive) state.
When a target is UP and its checking time comes and its expression evaluates to false, you might want to give it some grace period before declaring it down, and you do so with the maxtries parameter. When the target is UP and fails its check, it goes in state FA (yellow, failing), and stays there for maxtries-1 consecutive checks before becoming DN. If maxtries is 1, it goes directly in DN.
All target state changes are logged in the database with their reason, and you can view the log from the CLI or from the web interface. For important state change (roughly those between UP,FA,UU,TU and DN,UD,TD) SANET can send you an email with subject msg-downsubj or msg-upsubj and body msg-downbody or msg-upbody (the email is subject to $parameter and %char substitution, see later). You can differentiate addresses for down email and upemail, and use the string "none" if you don't want emails.
A target is usually identified by its path, a string with the following format:
<node name>:[<interface name>]:[<element category name>]:<target name>
The interface name is empty for nodes, and the element category name is empty for additional targets. The target name is usually the name of its target-category, but can be overwritten when inserting the target in the element category, or when creating the additional target.
The %char substitutions recognized for email subject and body are:
%N site name %T target path %m last verbstatus %A node's IP addresses, space separated %ID interface SNMP description %E target expression %e poller executable name %F the value of ETC_DIR in settings %H node name %I interface name %L node and interface linked to the interface %M maxtries %n tries %P target priority %t current time in time_t format %s current time in human-readable format %V value fetched from SNMP %y current date %U URL to resource page %p percent sign '%'
Measures
A measure is the periodic collection of two numbers, given with expr1 and expr2. The most important and useful example is the traffic in/out an interface. Measures are taken at every minperiod, and stored in an RRD file in the var/rrd directory. SANET uses the RRD library to manipulate those files and to generate the web images. The style is somehow similar to MRTG, with solid green for expr1 and blue line for expr2. A measure is controlled by many parameters, all having similar name and meaning as in the MRTG configuration.
Measure data is NOT kept in the database, it is only kept in RRD files. This means that it will lose resolution as time passes, and won't be backed up together with your DB: you have to backup the var/rrd directory if you want to keep this data safe. If you do, you will find that RRD files are difficult to backup consistently because they are frequently updated with random access writes, and if you simply copy them you can end up with an inconsistent copy: this is a general problem, heavily discussed on the RRD mailing lists. That said, most people simply copy the RRD files and in those few cases of actual restore that we know of, it worked fairly well with no apparent problem.
The default minperiod of a measure is one minute. The default time series are those given by the rrdcreate argument:
RRA:AVERAGE:0.5:1:4000 RRA:AVERAGE:0.5:30:800 RRA:AVERAGE:0.5:120:800 RRA:AVERAGE:0.5:1440:800
If you want to alter the minperiod or series of a measure, you will have to delete your old rrd files, since sanet uses the series parameter only at the time of file creation, managing possible export/import by hand.
A measure is usually identified by its path, defined in the same way as the path of a target.
Evaluating a measure can have a varying outcome:
- ok: Check was successful, values were retrieved and stored.
- dependson: Measure depends on a target which is not OK.
- strange: Values were retrieved and stored, but they were unusual, e.g. zero. This can be normal for some measures.
- uncheckable: Values could not be retrieved due to SNMP timeout, community, or other reasons.
- error: Values were retrieved, but could not be stored in the RRD, due to file permissions, clock inconsistency, value inconsistency, or other reasons.
Parameters
SANET comes with a set of predefined parameters that suffice for basic usage. You can view the defined parameters with show parameters, and more details with show parameters <name>.
Parameters have attributes that define their behaviour. One of the attributes is the value, which is often overwritten by the templating system based on categories.
The scope of a parameter is the set of checks to which the parameters applies:
sanet(config-param)# scope ? all parameter will be passed to all targets and measures measure parameter will be passed to all measures optional parameter will be passed to target and measures requiring it target parameter will be passed to all targets
Having scope optional means that you can use that parameter when defining a category of checks, and only checks in that category will use it.
The source of a parameter is its origin. A system parameter is used internaly by the algorithms in SANET, and you cannot modify its attributes (you can overwrite its value, of course). A library parameter is defined in the library of checks that comes with SANET in etc/library-<LANG>, and modifying it makes sense only when maintaining the library. A site parameter is a parameter that you define and lives in this site. The templating system is designed to allow updates to the library and also local development of categories, with minimal probability of conflict.
The type of a parameter is the kind of validation and parsing that SANET will do on its values:
- str: ascii string
- num: number (integer or float)
- bool: boolean (usually 0 or 1)
- timestamp: seconds since 1970-01-01 UTC
- target: a reference to a target
A parameter also has a description and a default value. Please remember that the value is likely to be overwritten by the templating system based on categories.
Here are the parameters defined as system or library:
sanet# sh param | ex " site optional" ID NAME TYPE SOURCE SCOPE DESCRIPTION -- --------------------------- ----- ------- -------- ------------------------------------------------------------------------------------------------------- 31 bits num system measure 68 component_description str library optional The human description of an hardware component 69 component_re str library optional Regexp to match the system description of one hardware component 3 deleted bool system all If nonzero, then this target or measure is deleted, and will not be performed nor displayed. 8 dependson str system all The path of a target that must be UP in order to make this check. If "" (empty), the primary target of+ 19 descr str system all This will show up as a description of the check. 67 device str library optional Name of disk device in IO statistics table, found in 1.3.6.1.4.1.2021.13.15.1.1.2 11 email str system target Email address to notify when target goes down. If empty or "none", no notification. Multiple addresses+ 47 error_threshold num library optional Percentage threshold for interface errors 13 expr str system target The expression that must be nonzero in order for the target to be UP. 20 expr1 str system measure First data (green) for the measure. 21 expr2 str system measure Second data (blue) for the measure, leave blank if unused. 14 flap_damp_limit num system target When flapping values goes above this threshold, target is flap dampened. 16 flap_half_life num system target When the target does not change state for this time, in seconds, its flap value is halfened. 15 flap_penalty num system target Each time the target state changes, this value is added to its flapping value. Use 0 to disable dampen+ 17 flap_undamp_limit num system target When a target is dampened and its flapping value returns under this threshold, target is undampened. 30 gauge num system measure 71 juniper_ps num library optional Juniper power supply number, starting at 0 70 juniper_status num library optional Juniper chassis MIB status code for a component 26 legend_1 str system measure 27 legend_2 str system measure 28 legend_i str system measure 29 legend_o str system measure 33 maxbytes1 num system measure Float 34 maxbytes2 num system measure Float 35 maxtries num system target When the target fails for oone round it is failing. When it fails for this number of consecutive round+ 45 minbytes1 num system measure Minimum value for the first data series 46 minbytes2 num system measure Minimum value for the second data series 1 minperiod num system all Minimum time in seconds between two consecutive checks or measurements. If the system is loaded, it ca+ 41 msg_downbody str system target Body of the email when target goes down. 37 msg_downlog str system target Text in the logfile when target goes down. 39 msg_downsubj str system target Subject of the email when target goes down. 36 msg_faillog str system target Text in the logfile when target goes into failing state. 42 msg_upbody str system target Body of the email when target goes up. 38 msg_uplog str system target Text in the logfile when target goes from down to up. 40 msg_upsubj str system target Subject of the email when target goes up. 32 nopercent num system measure 48 peer_ip str library optional IP address of the peer in dotted quad 49 port num library optional TCP or other protocol port number 50 power_supply num library optional The power supply number, starting from 1 2 primary bool system target If nonzero, then when this target is down, the whole node is displayed down. 43 priority num system target Target relevance. 51 probesize num library optional Size of the ICMP payload. To have a datagram of length 1500, use 1472 for IPv4 and 1452 for IPv6. 52 process str library optional The name of a process executable, as in hrSWRunName 66 proxy_password str library optional Proxy user for HTTP basi authentication. 63 proxy_port str library optional Proxy port. 64 proxy_realm str library optional Proxy realm 62 proxy_server str library optional Proxy server (ip or full qualified name). 65 proxy_user str library optional Proxy user for HTTP basi authentication. 22 series str system measure Averaging series specification. See man rrdcreate. 24 shortlegend str system measure 10 shorttries num system all Generic number of retries for ICMP or UDP when performing this check. 53 snmpport num library optional SNMP udp port, use when node has multiple agents on different ports 44 statuschange_script str system target Script executed on status change 54 storage_descr str library optional An informational description of the storage in the hrStorageTable, used in messages 55 storage_re str library optional Regular expression matching the storage description in the hrStorageTable 56 stpifacestate num library optional State of STP interface: 2 blocking, 5 forwarding (1 disabled, 3 listening, 4 learning, 6 broken) 7 suspend_auto_resume time+ system all When to auto-resume this target 6 suspend_reason str system all Reason why the operator suspended this check 5 suspend_time time+ system all When this check was suspended 4 suspended bool system all If nonzero, then this check is temporarily suspended, will not be performed but will be displayed. 57 tcpport num library optional TCP port number 58 threshold num library optional Generic threshold for use in targets, actual meaning depends on the target 9 times str system all When this check will be made. Can be empty, "all" (same meaning) or a string with format: hh[:mm]-hh[:+ 23 title str system all 18 uncheckable_fallback str system target Force a specific state when the target is not checkable. If empty, use the normal uncheckable state, o+ 12 upemail str system target Email address to notify when target goes up. If empty then it is the same as the "email" parameter. If+ 59 url str library optional an http or https URL to check 60 urlregex str library optional PCRE compatible regular expression to math in URL, with slash delimiters and possible final 'i' for ca+ 61 usage_threshold num library optional Percentage usage threshold for a resource (fs, ram, etc.) 25 ylegend str system measure
Target and measure categories
A target-category or measure-category is a set of parameters and their values, that you can apply to an element (node or interface) to create an actual target or measure. Together they are called check categories.
The SANET library includes many check categories of common use, and in most basic cases you will not need to define new ones. You should never modify the library in your site, since it is often modified during updates.
Element categories have inheritance, so you can define one of them giving the differences from a pre-existing one. This inheritance is used in the library, and you are encouraged to build your own check categories by inheriting from library categories (e.g. for changing email text).
You can view the complete configuration of check categories with the show conf <target|measure>-category commands. You can view a summary with show categories <target|measure>-categories, appending the name of the category for more details:
sanet# show categories target-categories NAME ID KIND SOURCE DESCRIPTION ----------------------------------- ------ ------- ------- --------------------------------------------------- fullduplex 25 target library Full duplex check for an ethernet interface hp-fan 26 target library HP Procurve 4000, 2524, 2510, 2824, etc. fan status iferrs 27 target library Interface errors threshold reach 50 target library This is the standard ICMP reachability check reach6 53 target library ICMP IPv6 reachability reach-crit 51 target library ICMP reachability check for critical devices reach-server 52 target library ICMP reachability check for servers ... sanet# show categories target-categories reach-server NAME : reach-server ID : 52 KIND : target: Verify a true or false condition SOURCE : library: Defined in the library that comes with the program DESCRIPTION : ICMP reachability check for servers PARENT : reach USED_PARAMETERS : deleted, dependson, description, minperiod, shorttries, suspended, times, title, email, expr, flap_damp_limit, flap_half_life, flap_penalty, flap_undamp_limit, maxtries, msg_downbody, msg_downlog, msg_downsubj, msg_faillog, msg_upbody, msg_uplog, msg_upsubj, primary, uncheckable_fallback, upemail, probesize REFERENCED_FROM : BOUND PARAMETERS: primary: 1 msg_upbody: (%N $node up) Il server $node e' di nuovo in servizio, si riesce di nuovo a raggiungere. (%m) %s msg_downbody: (%N $node down) Il server $node e' fuori servizio, non e' piu' raggiungibile! (%m, tries %n) %s
(please forgive the italian email messages in this example)
You create a check category from the main configuration prompt with the target-category or measure-category command, giving it a unique name. Please note that you cannot have both a target-category and a measure-category with the same name. Creating a check category will enter its configuration prompt where you can set its description, its parent, and where you can manipulate the values of the parameters.
To change or add a parameter to the category, use the parameter <name> <value> command. This will associate the parameter to the check category if not already associated, and will overwrite the value inherited from the parent or from the parameter's default.
You can also associate a parameter without overwriting its value, using the form parameter <name> without value. This is used when your check category needs a parameter, but you are happy with the default value of the parameter or you plan to overwrite it later.
To remove the parameter from the check category use the no parameter <name> command.
A check category has a source, that can be library or site: all the check categories you create will have "source site". Let's see some examples from the library-it:
target-category reach source library description "This is the standard ICMP reachability check" parameter probesize parameter minperiod 30 parameter shorttries 3 parameter maxtries 2 parameter expr "isReachable($node, $probesize)" parameter msg_upsubj "%N $node di nuovo in servizio" parameter msg_downsubj "%N $node fuori servizio" parameter msg_downbody "(%N $node down)\n\nL\'apparato $node e\' fuori servizio, non e\' piu\' raggiungibile!\n\n(%m, tries %n)\n%s\n" parameter msg_upbody "(%N $node up)\n\nL\'apparato $node e\' di nuovo in servizio, si riesce di nuovo a raggiungere.\n\n(%m)\n%s\n" parameter primary 1 parameter title "Raggiungibilita\' ICMP" exit target-category reach-server source library description "ICMP reachability check for servers" parent reach parameter msg_downbody "(%N $node down)\n\nIl server $node e\' fuori servizio, non e\' piu\' raggiungibile!\n\n(%m, tries %n)\n%s\n" parameter msg_upbody "(%N $node up)\n\nIl server $node e\' di nuovo in servizio, si riesce di nuovo a raggiungere.\n\n(%m)\n%s\n" parameter primary 1 exit
Node and interface categories
A node-category is a set of checks to be applied to one or more nodes, each check having
- a check category
- a name (default being the name of its check category)
- zero or more names and values of parameter, overwriting the values in the check category
- a switch or router flag, used in the Netdb plugin to specify that the node has a meaningful ARP table (router) or FDB table (switch).
An interface category is the same thing for an interface, and together they are called element categories. An interface-category has no router and switch flags, but has a noedge flag for the Netdb plugin.
You create an element category with the <node|interface>-category <name> command in the main configuration prompt, and insert a check into an elemnt category with the <target|measure> <name> [category <check category name>] commands from the element category configuration prompt, entering element category check configuration prompt:
node-category routercisco router target reach exit target cisco-procram exit target cisco-ioram exit target cisco-cpu exit measure cisco-cpugraph exit target reboot exit measure cisco-procramgraph exit measure cisco-ioramgraph exit exit
In simple cases, this is just a list of targets and measures. In the element category check configuration prompt you can overwrite parameters with the parameter' command. Let's see an example with nondefault names and some overwriting of parameter values:
sanet# sh conf node-category server-linux node-category server-linux target reach-server exit target rootfs category storageperc parameter storage_descr "root fs" parameter storage_re ^/$ exit measure rootfs-graph category storage parameter storage_descr "root fs" parameter storage_re ^/$ exit target cpuperc-hr exit measure cpu-hr exit target reboot-hr exit target ramperc-ucd exit measure ram-ucd exit measure swap-ucd exit target swapperc-ucd exit target loadavg category loadavg-threshold-ucd exit measure loadavg-graph category loadavg-ucd exit target nonidle-ucd exit measure nonidle-graph-ucd exit exit
An element category cannot have two checks with the same name, so using nondefault names is mandatory if you want to insert two checks having the same category.
You can see the configuration for the element categories with the show conf <node|interface>-category <name> commands, and summary informations with the show categories <node|interface>-categories [<name>] commands, with more details when name is given.
sanet# sh cat no server-linux NAME : server-linux ID : 17 DESCRIPTION : TARGETS: reach-server rootfs storage_descr: root fs storage_re: ^/$ cpuperc-hr reboot-hr ramperc-ucd swapperc-ucd loadavg nonidle-ucd MEASURES: rootfs-graph storage_descr: root fs storage_re: ^/$ cpu-hr ram-ucd swap-ucd loadavg-graph nonidle-graph-ucd sanet# sh cat int labsmu-giga NAME : labsmu-giga ID : 13 DESCRIPTION : TARGETS: operstatus iferrs nucast-threshold MEASURES: ifgraph-1G ifnugraph
Placing nodes and interfaces in categories
An element is placed in an element category with the category <name> command from its configuration prompt. There are two predefined categories, node-nochecks and iface-nochecks, whose set of checks is empty. If you want to remove an element from its category, you can place it in the appropriate predefined empty category.
When you place an element in a category, SANET creates all the resulting checks, i.e. all its category checks, with parameters having values from the element category. You can view the set of targets and measures for an element with the show <targets|measures> [node <name> [interface <name>]] command.
Overwriting parameters for category checks in an element
If for a specific element a category check needs some different values of some parameters, you can change them at the element configuration prompt issuing the category-<target|measure> <name> command, and entering the element in-category check configuration prompt. Here you can change parameters with the parameter <name> <value> command.
If you don't want that check, set the deleted parameter to 1.
With the no parameter <name> form of the command, the overwriting for that parameter is removed, and the parameter will have the value inherited according to the standard SANET algorithm. If you remove all the overwritings for a category check in an element, the category-<target|measure> command will disappear from the configuration (there is no "no" form of this command).
Please note that overwriting a parameter value in this way can have some meaning even if you overwrite it with the very same value that it inherits from the element category: if the element category, or the target category, will be changed later, the value for this specific check will remain the same.
Using additional targets and measures
You can add an additional check to an element with the <target|measure> <name> [category <name] commands in the element configuration prompt. These commands will also enter the additional check configuration prompt, where you can change the value of parameters. Additional checks are commony used for things unique to that element, in order to avoid having a big number of node or interface categories. An examples are processes and filesystems in servers:
sanet# sh conf node myserver node myserver description "My big old server" category server-linux icon linux target mnt category storageperc parameter storage_descr "fs mnt" parameter storage_re ^/mnt$ exit target dhcpd category proc-hr parameter process dhcpd exit target named category proc-hr parameter process named exit target nmbd category proc-hr parameter process nmbd exit target ntpsync exit target postgres category proc-hr parameter process postgres exit target usbhd category storageperc parameter storage_descr "fs usbhd" parameter storage_re ^/usbhd$ exit measure mntgraph category storage parameter storage_descr "mnt fs" parameter storage_re ^/mnt$ exit interface eth1 instance 5 category labsmu-100 exit exit
Fine-tuning your monitoring
Using the parameters dependson and primary
The dependson parameter in a check is a reference to a target. Whan the referenced target is down, SANET will not try to perform the check: it will set it to UU or UD if it is a target, and it will simply stop collecting data if it is a measure.
This is commonly used to avoid wasting polling resources querying an unreachable node, or checking errors on an interface which isn't operational.
For most elements, it is easy to identify a target from which all the others should depend on: for a node, this will probably be its reachability, for an interface it will be its operstatus. Such a target is called the primary target for the element. The primary target will be used as a default target for the dependson parameter of the other checks, and will be used in maps and in statistics reporting to distinguish between an element having some problems and an element which is completely out of service.
You can tell SANET which target is the primary using the primary boolean parameter. In the library, this parameter is true for reachability targets and operstatus targets, and all the other checks depends on this targets. You must exercise care to avoid having an element with more than one primary target (SANET will essentially choose a random one), or with no primary target (unless of course the element has no targets at all). This is a common issue when you define two or more reachability targets for a node: in this case remember to switch off primary for all but one.
The dependson parameter is specified as text, and SANET will try to identify the referred target according to the following rules:
- The string "NONE": no dependson, the check will always be performed
- The empty string "" (default): the primary target for this element, if it is not the referring check. If the referring target is the primary, and the element is an interface, the primary target of the node. If the referring target is the primary, and the element is a node, no dependson.
- A string with no colons ":" in it: the target with that name in the same element. If there are two of them they will be one category target and one additional target, and it will use the additional one. If a target with that name is not found and the element is an interface, ity will look for a target with that name in the node.
- A string with three colons ":" in it: look for a target with the exact path. You can use this to make a check depend on a target of a different node.
The referred target will be identified whenever a (referring) check's configuration is updated. This can lead to inconsistencies if you change the primary parameters for targets already having checks referring to them, because the referring checks are unchanged and will not be recomputed. You can manually force recomputation of the resulting check configuration for a node, an interface or for a category with the refresh command.
Using the parameter priority
The priority parameter for targets is an integer specifying relative "importance" of the target. Its default value is 1, and it is not changed from the default in the library.
- An higher priority will make the target appear towards the top in the web interface.
- A zero priority will prevent the target from appearing in the web interface.
Suspending and Silencing checks
You can deal with planned downtime by suspending or silencing a check.
Suspending a check means that the check will not be done, its result will not be evaluated, mail will not be sent (if it is a target), data will not be saved (if it is a measure). If it is a target, its state will be IN as "inactive".
Silencing a target means that it will be done as usual, its state will change if necessary, but emails will not be sent. A measure cannot be silenced.
Suspending is stored in the configuration as a set of parameters:
- suspended: if true, the check is not performed and, if it is a target, it is in the IN state.
- suspend_reason: human-readable text that the operator inserted when the check was suspended
- suspend_time: the when the check was suspended
- suspend_auto_resume: If nonzero and the check is suspended, the poller will automatically resume the check at that time.
Silencing is stored with similar parameters:
- silenced: if true, the target is performed and changes state as usual, but mail is not sent
- silence_reason: human-readable text that the operator inserted when the target was silenced
- silence_time: the when the target was silenced
- silence_auto_unsilence: If nonzero and the target is silenced, the poller will automatically unsilence the target at that time.
Checks can be suspended from the CLI with the suspend <upto> <what> <reason> command, with automatic resume at specified time or in the specified number of seconds (use "forever" for no auto resume). Check can be manually resumed with the resume command. You can suspend and resume a single check, all targets of an element, or all targets of a container.
Targets are silenced from the CLI with the silence command, that works in the same way as the suspend command, and unsilenced tieh the unsilence command.
Suspended checks are shown in show <targets|measures> with an "S" in the "SD" column. Silenced targets have an "H" in the "SHD" column.
When you suspend, resume, silence or unsilence a check, the CLI will place (or remove) values for these parameters at the lowest possible level: this will be the element in-category check prompt it the check is a category check, or the element additional prompt if it is an additional check.
When you suspend or silence a whole element or container, the CLI will actually suspend or silence individual targets in the same way. This can lead to some inconsistencies, e.g. if you:
- put a node in a container
- suspend the container
- remove the node from the container
- resume the container
then at this point the node will still be suspended.
Please note that if you directly manipulate the suspended parameter in targets, the target will not automatically enter and exit the IN status. This is considered a bug.
Suspended checks are shown in the web interface with a character overstrike. Silenced target are shown with a mail-suppresed icon.
Flap dampening
Warning: this feature is seldom used and is likely to be removed in a future release.
Target flap dampening is a feature similar to the route flap dampening of the BGP protocol. When a target goes UP and DN, a penalty is applied to it, and when the penalty reaches a threshold, SANET "flap dampens" the target and stops sending emails for it. When the target is evaluated and the status doesn't change, the penalty is reduced according to an exponential function, and when the penalty falls beyond a reuse threshold, the target is no more flap dampened.
The parameters for configuring flap dampening are:
- flap_penalty: Each time the target state changes, this value is added to its flapping value. Use 0 to disable dampening (default), 500 can be a reasonable value
- flap_damp_limit: When flapping values goes above this threshold, target is flap dampened (default 2000).
- flap_half_life: When the target does not change state for this time, in seconds, its flap value is halfened (default 900).
- flap_undamp_limit: When a target is dampened and its flapping value returns under this threshold, target is undampened (default 750).
Flap dampening can be useful, but most users find it confusing because it makes the actual sending of emails difficult or impossible to predict, and you can end up with unmatched "up" or "dn" emails. Use it with care.
Executing a script on target status changes
You can execute a script whenever a target status changes using the statuschange_script parameter.
The script must be an executable in the $SANET_HOME/exec directory, and will be executed as root, with environment variables specifying what happened. This two variables are specific to this parameter:
- SANET_RESOURCE_OLD_STATE The two-letters old state
- SANET_RESOURCE_NEW_STATE The two-letters new state
There will also be the variables used in the scripts launched from the context menu in the web interface, including the path of the target in SANET_RESOURCE_NAME.
The script will be launched with no controlling terminal, and will not be waited for.
Performing checks only on specified times
The time parameters control the times of day and week when the check will be performed. Outside these times, it will be in TU or TD state.
If times is the string "all", then the check will always be performed, otherwise the format is:
hh[:mm]-hh[:mm][,hh[:mm]-hh[:mm] ... ][/d-d[,d-d ...]][|hh...]
Hours "hh" are local time, and week days "d" from sunday 0 to saturday 6.
Examples:
- "9-18": from 9 to eighteen, every day
- "9:30-18:15": from 9.30 to 18:15, every day
- "9-12,14:30-19": from 9 to 12 and also from 14:30 to 19, every day
- "9-19/1-5,9-13/6" from 9 to 19 mon-fri, from 9 to 13 sat, no check on sunday.
Holidays are considered as sundays, whatever their day of week actually is. You can verify the list of holidays in default_settings.py and change it by adding lines in settings.py. You can also change the day of week that is forced for holidays, or disable this feature, as described in the comments in default_settings.py.
To verify what happens in complicated cases you can use the show timespec command.
Forcing uncheckable targets to down
SANET puts target in one of the "uncheckable" states (UU, UD) when it cannot evaluate the expression for some reason. Among the possible reasons, we mention:
- Missing SNMP variables
- Failed name resolution while retrieving an SNMP variable
With some of the functions used in SANET expressions, it can be difficult to know in advance what the result will be (up, down or uncheckable) for specific corner cases: some are documented, but there are corner cases that were never tested and so are simply not known, and in these cases the only way to know is to experiment.
You can force SANET to never evaluate a specific target's expression to uncheckable with the uncheckable_fallback parameter, setting it to the string "UP" or "DN" (its default value is the empty string). SANET will convert uncheckable states resulting from inability to evaluate the expression to the specified state, and act accordingly (send emails, etc.).
This parameter will not affect uncheckability due to:
- dependency from a target which is currently in a down state (dependson)
- being out of the specified times parameter (states TU and TD)
In these cases the target will still be uncheckable.
Grouping nodes in trees and containers
Understanding trees and containers
Trees and containers are used for nodes classification and to define various network views.
In each tree there are containers, arranged in a tree-like structure, like the directories of a file system. Nodes are in (at most) one container of the tree, so a container can contain nodes and containers, that in turn can contain other nodes and containers, etc.
You can use containers to:
- Display maps: each container has at least one associated map, thath shows the nodes and containers in it. The containers can be shown as closed (icons) or open (submaps in a rectangle).
- Logically group nodes to see a "slice" of the current alarms: when you select a container in the web UI, you will see alarms, measures, logs, notes and summary statistics only for nodes recursively contained in it.
- suspend and resume many nodes in one operation
Sometime a tree built for one purpose does not fit a different purpose, so you can create multiple trees. Each tree can represent a way to classify nodes, e.g. by geographic location, by responsible team, by vendor, by username/password (useful for rancid integration), etc. You can define trees that contain a subset of nodes only. Trees are also used to manage user permissions on nodes.
Each tree shows up in the web UI as a folder, which is its root container, with subfolders. The name of the tree is never shown in the web UI.
SANET enforces (or tries to) the following rules:
- A container has zero or one parent. In a tree there must be exactly one container with no parent, and it is called the root container. There cannot be "parenthood" loops.
- If the tree is defined to contain all nodes, then each node belongs to exactly one container (by default, to the root container).
- If the tree is defined to contain a subset of the nodes, then each node belongs to zero or one container. By default, the tree is empty.
- By default there is one tree "geo", defined to contain all nodes, with one container "geo" (its root container), having a map "geo: geo". You cannot delete nor rename this tree, but you can rename its root container.
- A container contains containers and nodes: a container cannot contain other objects (like interfaces, targets, etc.). For this purpose you can use usercontainers.
- A container has at least one associated map. Each map of the container defines the state (open or closed) of the containers in it, you can have different maps for different combinations of open/close states.
Containers should not be confused with usercontainers, which are unrelated objects defined for a single user and following different rules.
Creating and configuring trees
Trees are created from the main configuration prompt with the tree <name> command, that creates the tree if it doesn't exists, and enters its configuration prompt.
At the configuration prompt you can give the tree a description. You can tell SANET that the trees contains all nodes with allnodes, or not with no allnodes (the default for new trees). You can adjust the tree's display-order to show the list of root containers of trees in the web UI as you whish. You can create containers and give permissions to groups (both will be seen later).
You can use the show trees [<name>] command to show some summary information about trees.
Trees can be deleted with no tree <name> <name> and renamed with rename tree <old> <new>.
Creating and configuring containers
Containers are created and configured in the CLI at the tree configuration prompt for the tree. You can view containers with show containers [tree <treename> [<containername> [details]]] and the current configuration with [show configuration tree [<name>]. The default configuration of a new SANET installation, with the output of some "show" commands, follows:
sanet# sh conf tree tree geo allnodes display-order 1 container geo icon container map "geo: geo" open geo exit exit exit sanet# sh tree ID NAME SORT ALLNODES? DESCRIPTION -- ---- ---- --------- ----------- 1 geo 1 1 sanet# sh containers ID TREE NAME PARENT NODES X Y Z SZ DESCRIPTION -- ---- ---- ------ ----- - - ---- -- ----------- 1 geo geo 0 10 sanet# sh cont tree geo geo det ID : 1 TREE : geo NAME : geo PARENT : NODES UNDER : 0 X : Y : Z : 10 SZ : DESCR :
To create a new container, you enter the tree configuration prompt and use the container <name> command to create it and its associated default map. You should immediately give it a parent container with the parent command.
sanet# conf t sanet(config)# tree geo sanet(config-tree)# cont test Creating container test in tree geo sanet(config-tree-container)# parent geo sanet(config-tree-container)# sh cont ID TREE NAME PARENT NODES X Y Z SZ DESCRIPTION -- ---- ---- ------ ----- - - ---- -- ----------- 1 geo geo 0 10 2 geo test geo 0 10
Please note that the CLI tries to enforce trees to have one and only one root container, but is (currently) not very good at it. Don't try too hard to make a tree with two roots or no roots, because you could succeed and the web interface would be quite confused.
All containers are created, deleted and renamed at the tree configuration prompt, independently of their nesting level (you don't crete a container in its parent's configuration prompt).
To rename a container use rename container <old> <new> and to delete it use no container <name> <name>.
Container can be given a nondefault icon and a description. You can put a node in a container with the node command.
The node command can take parameters to specify the exact placement (in pixels) of the node in the maps, and the zindex for determining which covers which. The placement of the container in the maps of its parent container can be controlled in the same way with the rectangle command. This placement is usually not done in the CLI: nodes and containers can be dragged in the web UI maps and their position saved with a button, and the new positions will be found in the configuration.
Nodes can be removed from a container with the no node <name> command in the container configuration prompt. If the tree has allnodes, deleting a node from a container will place it in the root container (deleting from the root container will have no effect). This command is not to be confused with the "no node" command in the main configuration prompt, which deletes the node from the configuration and requires repeating the node name.
Configuring maps
Maps are created at the container configuration prompt with map <name>, that also enters the map configuration prompt.
Containers are closed in maps by default, and can be configured as open with open <name> in the map configuration prompt. Containers can be reverted to closed with no open <name>.
Maps can be deleted and renamed at the container configuration promtp with no map <name> <name> and rename map <old> <new>. The last map of a container cannot be deleted.
Different maps of a container can be selected for display in the web UI with the widget in the map block. Please remind that a map does not store the information about what containers and nodes it contains: this information is stored in the tree structure and in the containers (with the node, parent and rectangle commands), the map only stores informations about containers in it being open or closed.
Authentication and authorization
Understanding authentication and authorization
The SANET web UI is a multiuser system, with authorization at the node level. This means that you can configure web users to see a subset of the SANET nodes.
Authentication is done by default via username and password, which are kept in the sanet DB and managed via CLI. The password is always kept in encrypted and salted format. You can authenticate against a backend via RADIUS, LDAP, etc. with the standard machinery and plugins provided by Django, since SANET users are Django users. This is common, but not documented in SANET: see Django documentation if this is what you need. Remember that if you authenticate against an external backend the user's password that you give in the SANET configuration will be ignored, and you should decide (and test) if new users (authenticated, but unknown to SANET) will be automatically added, and with what attributes, or not.
The default user that is created at installation has the "superuser" flag set: such users have all permissions on all nodes. If you don't need authorization, just set the superuser flag on all users and you don't need to configure anything else.
When using the WEB interface, "superusers" can "impersonate" at any time other normal users. This means that "supersuer" can access to and modify normal users' settings and resources (see "usercontainers").
If you need authorization, you need to put your non-super users in groups, and give the groups some permissions on trees. The trees contains nodes, and the users will end up having permissions on the nodes belonging to trees on which they have some permission.
Users also have a set of usercontainers, which are groups of recources (nodes, containers, targets and measures) that the user can see together. Users have a personal page with a custom arrangement of blocks, but this is configured in the web UI and not in the CLI.
Authentication in the CLI and the web UI
By default, authentication is enabled in the web UI and disabled in the CLI.
You can disable authentication in the web UI by providing a nonempty AUTOLOGIN_USERNAME in settings.py. This must be an existing user, and should be a superuser.
You can enable authentication at the CLI by setting CLI_AUTH=True in settings.py, the CLI will prompt for username and password, and let only superusers in. Please note that you have to be root to use the CLI anyway, so CLI authentication can be useful only in special cases: in a collaborative environment, or for creative setups with the CLI directly attached to an sshd or telnetd (untested and likely insecure).
Managing users and groups
A user is created at the main configuration prompt with the username <name> command, that also enters the user configuration prompt. Users are deleted and renamed as usual with no username <name> <name> and rename username <old> <new>.
A user cannot login until a password is set: you can do that at the user configuration prompt with password <cleartext password>, or you can give a salted hash of the password with secret <hash>. The cleartext password will never be stored as such, if you use the password command, you will find the secret command in the configuration:
sanet(config)# user joe Creating username joe sanet(config-user)# sh conf user joe username joe secret ! container Principale description "Contenitore utente principale" exit exit sanet(config-user)# password testing123 sanet(config-user)# sh conf user joe username joe secret sha1$7b959$90d30cad6bee73e9460de1ab7d9a776ac4f24176 container Principale description "Contenitore utente principale" exit exit
You can also set the user's firstname, lastname and email for your records (SANET will store but not use this fields). You can disable a user with no enable, and later re-enable it with enable. You can make it a superuser with superuser, and clear this flag with no superuser.
In order to control the set of nodes that a user can see, you put the user in a group, and give that group some permissions on trees. The group is created at the main configuration prompt with the group <name> command (there is no group configuration prompt). To put a user in a group you go into the user configuration prompt and issue group <name>.
To display the current configuration there are the show conf user [<username>] and show conf group commands. show user [<name>] and show group [<name>] display tabular information about users and groups and, when used with a name, details including last login (for users) and memberships (both ways).
Each user can build its usercontainers from the web interface with simple drag and drop operations, but you can also build usercontainers for a users from the CLI if you whish.
Each user has by default a usercontainer, you can create new ones with container <name> at the user configuration prompt (entering the usercontainer configuration prompt), and also delete and rename them as usual with no container <name> <name> and rename container <old> <new>.
In the container configuration prompt you can populate the container with node <name>, target <path>, measure <path>, and with the no forms of the same commands. You can set a usercontainer's parent with parent <name>. A user can have many usercontainers with no parent, and can have the same resource in many usercontainers: usercontainers are very different in this regard from containers, the system-level objects grouped in trees and having maps.
Managing authorization
A group of users if authorized to see or modify all the nodes in a tree with the group <name> [ro|rw] command at the tree configuration prompt. Authorization is removed with the no form of the same command.
Pleas keep in mind that users having the superuser flag do not need to be authorized in this way: the are automatically permitted to see and do anything.
Groups and trees should be created as needed to satisfy your specific authorization requirements. As an example, if you have a user "joe" and you want him to see only the node "localhost", you could do:
sanet(config)# group joe sanet(config)# user joe Creating username joe sanet(config-user)# pass joepass sanet(config-user)# exit sanet(config)# tree joe Creating tree joe sanet(config-tree)# group joe sanet(config-tree)# cont joe Creating container joe in tree joe sanet(config-tree-container)# node localhost sanet(config-tree-container)# exit sanet(config-tree)# exit sanet(config)# sh conf user joe username joe group joe secret sha1$00ab9$7a6f97c988ed194a4529f40d76eb4c570635b4ef container Principale description "Contenitore utente principale" exit exit sanet(config)# sh conf tree joe tree joe no allnodes display-order 1 group joe container joe icon container node localhost map "joe: joe" open joe exit exit exit
You can test the resulting permissions of a user for a node with show authorization <username> node <name>:
sanet# sh authorization joe node localhost read only
show authorization can also be used with other kind of resources, but the rules are simple:
- For targets, measures and interfaces, same permissions as those on the node
- For containers, same permissione as those on the tree
Currently write permissions are needed only for suspending and resuming via web.
Configuring icons
SANET comes with a predefined set of icons, that you can see with show icons [<name>]:
sanet# sh icons ID NAME FNAME SUBST DESCRIPTION -- ----------- ----------- ------ ----------- 12 accesspoint accesspoint FFFFFF 13 bigswitch bigswitch FFFFFF 11 building building FFFFFF 2 container container FFFFFF 19 firewall firewall FFFFFF 15 fw-left fw-left FFFFFF 16 fw-right fw-right FFFFFF 7 host host FFFFFF 4 iface iface FFFFFF 8 internet internet FFFFFF 14 l3switch l3switch FFFFFF 17 linux linux FFFFFF 10 measure measure FFFFFF 1 node node 808080 6 router router FFFFFF 3 site site FFFFFF 5 switch switch FFFFFF 9 target target FFFFFF 18 windows windows FFFFFF
Most of them are the standard cisco concept icons. There is usually no point in configuring one of the predefined icons, but new icons can be defined to suit your specific needs (this is used mainly for the site icon).
To define a new icon you need to do the following:
- choose a short name, e.g. "myicon", made with lowercase characters, digits and dash "-"
- copy the following files in $SANET_HOME/static/theme/img/resources/
- myicon128x128.png, size 128x128 with default coloring (will be displayed when status is not meaningful)
- myicon128x128-UP.png, green colored
- myicon128x128-DN.png, red colored
- myicon128x128-FA.png, yellow colored
- myicon128x128-UN.png, grey colored
- myicon128x128-UU.png, a copy of myicon128x128-UN.png
- myicon16x16.png, size 16x16 with default coloring
- make sure the files you copied are readable by the web server
- create the icon in the configuration, from the main configuration prompt, with icon <name>, in the example "icon myicon", entering its configuration prompt.
At the icon configuration prompt, you should at least configure its base file name with the filename <basename> command, in the example (and in the predefined icons) this is the same as the icon name. You can also give it a description. The subst-color was meant to let SANET perform the coloring according to status, but was never really implemented, so it is currently ignored.
