4.4.1.2 Configuring the SNMP Agent

The application specific SNMP agent gets configured by a the file 'snmp.setup'. If this file exists in the VLC's home directory while the M&C server starts, the SNMP agent is started. The sat-nms software contains a utility program called 'create-snmp.template' to create a template of this file including all parameters of a particular M&C / VLC. The file is a text file using the following format:

• Empty lines and lines starting with '#' are ignored.
• At the beginning of the file, the global settings 'systemname', 'systemid' and 'traphost' must be defined (see example below).
• After this file header, each line must contain exactly one sat-nms parameter identifier, consisting of the device name followed by a dot and the variable identifier.
• Each parameter identifier may be followed by zero or more parameter attributes, separated by space characters.

Global settings

The file 'snmp.setup' must define the global settings 'systemname', 'systemid' and 'traphost' before the first parameter identifier appears in the file. The order of appearance does not matter.

• traphost<aaa.bbb.ccc.ddd> --- Defines the IP address of the host which shall receive any traps from this M&C. Traps always are sent to the standard port number 162.
• systemid <n> --- Defines the base node number of the MIB tree created for this M&C. The created MIB tree is a branch of iso.org.dod.internet.private.enterprises.satservice , the 'systemid' parameter defines the number of the child node below satservice . Numbers 1 .. 99 are reserved for special applications. The 'create-snmp.template' utility program uses the M&C serial number as a default for this parameter to ensure a unique value for each M&C.
• systemname <name> --- Defines the memnotics for the 'systemid' parameter described above. Following the conventions for MIB definition, this should be a single word, starting with a letter and consisting entirely of letters and digits. The 'create-snmp.template' utility program prepends 'vlc' to the serial number in order to create a unique value for this parameter.

Parameter attributes

The software accepts the following parameter attribute keywords following a parameter identifier. The activate the corresponding translation option for this parameter.

• RO --- Forces this parameter to be treated as read-only, even if it has read-write access within the sat-nms environment. It is not necessary to mark parameters with RO if they already are marked as read-only by the sat-nms device driver.
• TEXT --- Forces this parameter to be translated into a readable text (OCTET-STRING) when exported to the SNMP world, regardless of it's native data type. See chapter SNMP Parameter Translations for more information about the software converts native data types to SNMP types an vice versa.
• NORANGE --- Suppresses the output of a mi/max range for numeric parameters. This is useful for parameter which dynamically change their limits. See chapter SNMP Parameter Translations for more information about the software converts native data types to SNMP types an vice versa.
• TRAP --- Tells the software to send an SNMP trap if this parameter changes. Although mostly used for fault flags, this feature is not limited to this application. Any M&C parameter may be monitored by sending TRAPS.

MIB tree creation

When reading the 'snmp.setup' file, the software dynamically allocates MIB nodes for each parameter. The program splits up parameter identifiers at the dots and builds a MIB tree breaking down the M&C parameter structure along devices and subsystems. Node numbers are assigned automatically starting at 1, parent nodes are created as needed. This means, the order of the parameters in the 'snmp.setup' file determines the numbering of OIDs.

As a consequence of the automatic MIB tree creation, existing MIBs usually become invalid after a configuration change in a M&C, due to the renumbering of the OIDs.

However, with the knowledge about the OID assignment algorithm used by the software, minor configuration changes can be worked into the SNMP configuration while keeping the existing OID numbering unchanged. There are simply two rules to follow:

1. Do not remove existing definitions. Neither single parameters nor complete devices. Deleting definitions would cause a renumbering (decrement) of the following nodes.
2. Add additional parameter definitions always at the very end of the 'snmp.setup' file. Although for human readers the order of parameters in the file will look somewhat 'messy', the software will assign the OIDs in a way that the numbering of existing parameters will not change.

If you follow the rules above, you still can use the previous MIB of a M&C after an extension of the configuration. You however will not be able to access the added parameters as long you use the old MIB.

'snmp.setup' Example

The example below shows the contents of a short 'snmp.setup' file.

### snmp.setup example
### created on Thu Jun 22 19:11:18 GMT 2006

traphost 127.0.0.1
systemname vlc2345
systemid 2345

SUMMARY.fault                          TRAP
E1.fault                               TRAP
E1.mode                                RO
SW.fault                               TRAP
SW.mode                                RO

Fault messages

If the software encounters problems while it reads the 'snmp.setup' file, it issues fault messages to the sat-nms event log. Hence, after a change of the SNMP configuration, you should inspect the event log after the server restart. The following error messages are possible:

Unknown variable in line n of 'snmp.setup': The snmp.setup file references a sat-nms variable which does not exist. The reason may be a misspelled parameter name or you changed the sat-nms device setup without adapting the SNMP configuration.

Unknown attribute ABC in line n of 'snmp.setup': You specified a parameter attribute which is neither 'TRAP', 'TEXT' nor 'RO'.

Warning: 'snmp.setup' has 0 entries: There is a 'snmp.setup' file, but it does not specify any parameters

Failed to read 'snmp.setup': A general error occurred. Delete and recreate 'snmp.setup'.