Configuration guide

From Sanet

Jump to: navigation, search


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:

Most objects can be renamed with the rename command, issue 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 imput 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


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 :

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:

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:


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).


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 (

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
. : ATM0
. : Ethernet0
. : Null0
. : ATM0-atm layer
. : ATM0.0-atm subif
. : ATM0-aal5 layer
. : ATM0.0-aal5 layer
. : ATM0-interleave
. : ATM0-fast
. : ATM0-adsl
. : ATM0.1-atm subif
. : 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:

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
. : lo
. : eth0
. : eth1
. : eth2
. : eth3
. : eth4
. : 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($community@$node,$instance)
Creating interface e2 in node myfw
sanet(config-node-iface)# exit
sanet(config-node)# int e3 instance xform$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
 interface e1 instance eth1 xform byRegexpUnique(,^$instance$)
  category iface-nochecks
 interface e2 instance 00163e6333e7 xform byBinaryValue($community@$node,$instance)
  category iface-nochecks
 interface e3 instance xform$instance:$community@$node
  category iface-nochecks

sanet# sh int node myfw e0
ID               : 60
NODE             : myfw
INSTANCE         : 2
XFORM            :
IFINDEX          : None
TARGETS          : 0
MEASURES         : 0
CONNECTS         :

sanet# sh int node myfw e1
ID               : 61
NODE             : myfw
INSTANCE         : eth1
XFORM            : byRegexpUnique(,^$instance$)
IFINDEX          : None
TARGETS          : 0
MEASURES         : 0
CONNECTS         :

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(,^$instance$)
IFINDEX          : 3
TARGETS          : 0
MEASURES         : 0
CONNECTS         :

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.


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:

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:

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:

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:


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 '%'


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 os 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:


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:

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
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

primary: 1
msg_upbody: (%N $node up)

Il server $node e' di nuovo in servizio, si riesce di nuovo a raggiungere.


msg_downbody: (%N $node down)

Il server $node e' fuori servizio, non e' piu' raggiungibile!

(%m, tries %n)

(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"

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

Node and interface categories

A node-category is a set of checks to be applied to one or more nodes, each check having

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
 target reach
 target cisco-procram
 target cisco-ioram
 target cisco-cpu
 measure cisco-cpugraph
 target reboot
 measure cisco-procramgraph
 measure cisco-ioramgraph

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
 target rootfs category storageperc
  parameter storage_descr "root fs"
  parameter storage_re ^/$
 measure rootfs-graph category storage
  parameter storage_descr "root fs"
  parameter storage_re ^/$
 target cpuperc-hr
 measure cpu-hr
 target reboot-hr
 target ramperc-ucd
 measure ram-ucd
 measure swap-ucd
 target swapperc-ucd
 target loadavg category loadavg-threshold-ucd
 measure loadavg-graph category loadavg-ucd
 target nonidle-ucd
 measure nonidle-graph-ucd

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

  storage_descr: root fs
  storage_re: ^/$

  storage_descr: root fs
  storage_re: ^/$

sanet# sh cat int labsmu-giga
NAME        : labsmu-giga
ID          : 13



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$
 target dhcpd category proc-hr
  parameter process dhcpd
 target named category proc-hr
  parameter process named
 target nmbd category proc-hr
  parameter process nmbd
 target ntpsync
 target postgres category proc-hr
  parameter process postgres
 target usbhd category storageperc
  parameter storage_descr "fs usbhd"
  parameter storage_re ^/usbhd$
 measure mntgraph category storage
  parameter storage_descr "mnt fs"
  parameter storage_re ^/mnt$
 interface eth1 instance 5
  category labsmu-100

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 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.

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:

Silencing is stored with similar parameters:

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:

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 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:

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.


Holidays are considered as sundays, whatever their day of week actually is. You can verify the list of holidays in and change it by adding lines in You can also change the day of week that is forced for holidays, or disable this feature, as described in the comments in

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:

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:

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:

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:

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
 display-order 1
 container geo
  icon container
  map "geo: geo"
   open geo

sanet# sh tree
-- ---- ---- --------- -----------
 1 geo     1         1

sanet# sh containers
-- ---- ---- ------ ----- - - ---- -- -----------
 1 geo  geo             0       10

sanet# sh cont tree geo geo det
ID          : 1
TREE        : geo
NAME        : geo
PARENT      :
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
-- ---- ---- ------ ----- - - ---- -- -----------
 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 This must be an existing user, and should be a superuser.

You can enable authentication at the CLI by setting CLI_AUTH=True in, 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"
sanet(config-user)# password testing123
sanet(config-user)# sh conf user joe
username joe
 secret sha1$7b959$90d30cad6bee73e9460de1ab7d9a776ac4f24176
 container Principale
  description "Contenitore utente principale"

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"
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

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:

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
-- ----------- ----------- ------ -----------
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:

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.

Personal tools