Table of Contents |
---|
Prerequisites
NMIS version 8.3.18G or greater.
Unix Shell access to the NMIS server and suitable Unix privileges to edit the NMIS configuration files, usually a member of the group "nmis" or the root user.
Introduction
While working with customers who wanted to extend NMIS and make it even more of a Network Management System , (e.g. to support parts of their operational processes and integrate more closely with their ITIL service management processes), we found that it could become difficult for them to maintain the customisations of the extended data collection. To To better support NMIS users we have simplified the way "Tables" in NMIS are defined and extended as well as how they are shown in the MenuMenus.
This article will briefly describe how this capability works and how it supports operational agility.
Custom Tables in NMIS
What are Tables in NMIS
...
Prerequisites
- NMIS version 8.3.18G or newer for custom tables
- NMIS version 8.6.2G or newer for input validation
- Shell access to the NMIS server and suitable user privileges to edit the NMIS configuration files
(which usually means being a member of the group "nmis" or having root privileges)
Custom Tables in NMIS
What are NMIS Tables?
To use NMIS various data is required, this data represents various policies, configuration, credentials or a combination of all of those. In the past NMIS users have added tables as they needed, this required some Perl coding. To support faster and more easily modified tables in NMIS the table definitions are now defined outside of the code base, making the tables themselves configuration items. So like the chicken and the egg, you need to start with something.
Typical Tables used in NMIS
The following tables are used in NMIS , this internally:
(Note that this also includes the new table, 'meta-table' Tables.nmis
, which defines the what other tables NMIS will present and allows presents, to allow dynamic definition of tables.)
File | Description |
Access.nmis | Access levels for Authorisation System |
BusinessServices.nmis | A list of Business Services to link to a node. |
Contacts.nmis | Contacts information used for notifications. |
Enterprise.nmis | List of “vendors” SNMP OID prefixes |
Escalations.nmis | Escalation policy, how notifications will happen |
Links.nmis | List of Links in the network. |
Locations.nmis | List of Locations |
Logs.nmis | Log viewer configuration file |
Modules.nmis | Opmantek modules integration |
Nodes.nmis | Main NMIS8 Nodes file |
Outage.nmis | Current planned outages (deprecated in 8.6.2G) |
Portal.nmis | Portal configuration for internal integrations |
PrivMap.nmis | Privilege mappings for authorisation |
Services.nmis | Services configuration file |
ServiceStatus.nmis | The definition of the Service Status's for NMIS (production, pre-production, etc) |
Toolset.nmis | External tools configuration file |
Tables.nmis | The list of Tables in NMIS |
Users.nmis | Users authorisation mappings |
ifTypes.nmis | List of standard interface types from IANA |
Config.nmis | 8.6.2G and newer: the main configuration file is now treated as a table, with validation and customisation features like the others. |
Table Configuration
Each table has a For each known type of table there is a separate "table configuration" file, these table configuration files are in essence little bits of code, which is evaluated at run time. The files live in /usr/local/nmis8/conf and all begin with "Table-", all of which are named Table-<yourtable>.nmis
(e.g. the table configuration for Nodes for table Users.nmis
the configuration file is called Table-
NodesUsers.nmis
. Let').
Both the actual tables and their configuration files live in the conf
directory, ie. /usr/local/nmis8/conf.
These table configuration files consist of declaration stanzas and little bits of code, which is evaluated at run time.
Let's look at an example, contents of ; this is what "Table-SampleTable.nmis" would could look like:
Code Block |
---|
%hash = ( SampleTable => [ { Email => { header => 'Email Address', display => 'key,header,text', value => [""] }}, { Name => { header => 'Name', display => 'header,text', value => [""] }}, { Age => { header => 'Age', display => 'header,text', value => [""] }}, { Married validate => { "int" => [ 0, undef ] }}}, { Married => { header => 'Married', display => 'popup', value => ["true", "false"] }}, { Children => { header => 'Children', display => 'popup', value => [0,1,2,3,4,5,6,7,8,9,10,11,12,"Many"] }}, ] ); |
SampleTable => [ | Is the name of the table, this should match the name, e.g. Table-SampleTable.nmis |
{ Email => { header => 'Email Address', display => 'key,header,text', value => [""] } }, | Each Column in the table is defined with an entry like this. In this case the column is called Email To define each column necessary fields are:
|
{ Married => { header => 'Married', display => 'popup', value => ["true", "false"] } }, | This field would not be displayed as a textbox in the main view but instead would contain a select list (drop down) to select true or false from. |
Display Options
Display controls how the field from the table configuration will be displayed and where it will be displayed, it is a comma separated list of values as shown in the examples above.
...
Value | Description | NMIS Version |
---|---|---|
header | If the value "header" is present, the field will be displayed when viewing the table. All fields are visible when editing an entry. | NMIS 8.1.1 |
key | This value is to be used as a key value, if multiple key values are defined, they will be combined together to make the key of the record. It is recommended to use a single value for a key value. | NMIS 8.1.1 |
readonly | A readonly field will not be editable, which means it must be added automatically as in the case of something like a UUID or edited from Unix. | NMIS 8.3.19G |
text | The standard field is a "text" field, this is equivalent to a HTML "input" form element. | NMIS 8.1.1 |
textbox | A text box being a little larger higher, this is equivalent to a HTML "textarea" form element. | NMIS 8.3.19G |
popup | A single value select box, this is equivalent to a HTML "select" form element. | NMIS 8.1.1 |
scrolling | A multiple select box, where you can select one or more values. This is equivalent to a HTML "select" form element with the attribute of "multiple" set to "multiple". | NMIS 8.1.1 |
Case Sensitive Keys for Tables
By default NMIS will treat all keys as lower case, that is whatever you enter, the key will be made lower case to make it case sensitive. To support case sensitive keys if required you can add your table name to the configuration option 'tables_case_sensitive_keys', table names are separated using a '|' (pipe) character, and NMIS will use the data as entered as the key.
Code Block |
---|
'tables_case_sensitive_keys' => 'Nodes|BusinessServices|ServiceStatus|Locations|Tables', |
Validation Options (8.6.2G and newer)
From NMIS version 8.6.2G onwards, a basic data validation mechanism is available for all NMIS tables. Not all properties are setup for validation yet, but the most critical ones are validation-enabled.
Validation is specificed by including a validate
section in your property definition, e.g. for Age
in the example above. A validation section can contain at most one rule for each supported validation type, but usually will contain just one rule altogether.
Validation Type | Arguments | Description | Example |
---|---|---|---|
int | [ min, max ] | The property value must be an integer. If min is set, the property must be equal to or greater than the min. If max is set, the property must be less than or equal to the max. If min or max is set to undef , then no limiting is enforced | between 0 and 50, incl: 'int' => [ 0, 50 ] non-negative integer: 'int' => [ 0, undef ] |
int-or-empty | [ min, max ] | Available in NMIS 8.6.3G and newer. Like | |
float | [ min, max, above, below ] | The property value must be a floating point number undef are skipped. | between 0 and 1, incl: 'float' => [ 0, 1, undef, undef ] greater than 0.1: [ undef, undef, 0.1, undef ] |
float-or-empty | [ min, max, above, below ] | Available in NMIS 8.6.3G and newer. Like | |
regex | a Perl regular expression given in qr/..../ format | The property value must be matched by the regular expression. | a blank string or a +HH:MM/-HH:MM timezone: 'regex' => qr/^([+-]?\d{1,2}(:\d{1,2})?)?$/ |
regex-or-empty | a Perl regular expression given in qr/..../ format | Available in NMIS 8.6.7G and newer. The property value must either be empty or match the given regular expression. | |
ip | [ acceptable IP versions ] | The property must be a valid IP address. The rule argument sets which IP versions are acceptable; it can contain 4, 6 or both. | any IP address: 'ip' => [ 4, 6 ] an IP V4 address: 'ip' => [ 4 ] |
resolvable | [ acceptabe IP versions ] | The property must be either a valid IP address, or it must be resolvable to a valid IP address (at the time of validation). Resolving is performed using the normal system mechanisms, ie. whatever combination of DNS and /etc/hosts is setup using nsswitch . | something with an IP V4 address: 'resolvable' => [ 4 ] something that resolves to an IP address: 'resolvable' => [ 4, 6 ] |
onefromlist | [ list of acceptable values ] or undef | The property value must be one of the given explicit values, or one of the default display values if no values are given in this rule. | exactly one of the values that was presented visually using value : 'onefromlist' => undefone of these: 'onefromlist' => [ 'yes', 'no', 'maybe' ] |
multifromlist | [ list of acceptable values ] or undef | Like onefromlist , but accepts multiple values from the accepted list. No values whatsoever does satisfy this validation rule. | zero or more of the presented values: 'multifromlist' => undef zero or more of these values: 'multifromlist' => [ 1, 2, 3, 4, 'OMGitsfulllofstars' ] |
Management of Tables
Adding a New Table to NMIS
...
- Create a table configuration
- Add the table to Tables.nmis
- Create permissions in Access.nmis
- Link to any other data
Create a Table Configuration
Create a file in /usr/local/nmis8/conf/, in our case /usr/local/nmis8/conf/Table-SampleTable.nmis, and add the appropriate configuration.
Add the table to Tables.nmis
Using the GUI or from the Unix prompt add the new table to Tables.nmis.
...
Refresh the NMIS Dashboard and your new table will exist in the menu but you will not be able to access it yet because there are no permissions defined for the table.
Create permissions in Access.nmis
You need to tell NMIS what Access permissions to add this with, we have created a script to add the tables with the default permissions which is as described in the table below, the command to run to add the permissions is.
...
The following table is the default permissions your table will be added with, if you want to change them, you can do that through the Access menu item at "System -> System Configuration -> Access Policy".
Level | Privilege | View | Read/Write |
---|---|---|---|
level0 | administrator | Yes | Yes |
level1 | manager | Yes | Yes |
level2 | engineer | Yes | Yes |
level3 | operator | Yes | No |
level4 | guest | No | No |
level5 | anonymous | No | No |
level6 | security | No | No |
* This step is intentionally done using the Unix shell, as we want to ensure that people adding privileges are truly NMIS admins and not someone sneaking up and using a browser window.
View the Table and Add Something
If you haven't already, refresh the NMIS Dashboard and access the new table through the menu, in this example "System -> System Configuration -> Sample Table". It will likely have an error message like "Error on loading table SampleTable" this is because there was not data.
...
Linking Data Between Tables
Creating new tables isn't that thrilling but if we could start linking data between them, e.g. a select (drop down) in the Nodes table could contain information from a new custom table, then we would have a much more useful system for adding properties. Custom tables allow us to do this, as an example lets add a look up (displayed as a drop down) to our SampleTable called "Business Service".
...