> ## 5 Running the Agent

> The chapter Running the Agent describes how the agent is configured and started. The topics include:

> - configuration directories and parameters
> - modifying the configuration files
> - starting the agent
> - debugging the agent.

> Refer also to the chapter Definition of Configuration Files which contains more detailed information about the configuration files.

> ### 5.1 Configuring the Agent

> The following two directories must exist in the system:

> - the configuration directory stores all configuration files (refer to the chapter Definition of Configuration Files for more information).
> - the database directory stores the internal database files.

> The agent uses application configuration parameters to find out where these directories are located. The parameters should be defined in an Erlang system configuration file. The following configuration parameters are defined for the SNMP application:

> `audit_trail_log = false | write_log | read_write_log <optional>`
>   Specifies if an audit trail log should be used. The `disk_log` module is used to maintain a wrap log. If `write_log` is specified, only set requests are logged. If `read_write_log`, all requests are logged. Default is `false`.
> `audit_trail_log_dir = string() <optional>`
>   Specifies where the audit trail log should be stored. If `audit_trail_log` specifies that logging should take place, this parameter must be defined.
> `audit_trail_log_size = {MaxBytes, MaxFiles} <optional>`
>   Specifies the size of the audit trail log. This parameter is sent to `disk_log`. If `audit_trail_log` specifies that logging should take place, this parameter must be defined.
> `bind_to_ip_address = bool() <optional>`
>   If `true` the agent binds to the agent IP adress. If `false` the agent listens on any IP address on the host where it is running. Default is `false`.
> `force_config_load = bool() <optional>`
>   If `true` the configuration files are re-read during startup, and the contents of the configuration database ignored. Thus, if `true`, changes to the configuration database are lost upon reboot of the agent. Default is `false`.
> `no_reuse_address = bool() <optional>`
>   If `true` the agent does not specify that the IP and port address should be reusable. If `false` the agent the address is set to reusable. Default is `false`.
> `snmp_agent_type = master | sub <optional>`
>   If `master`, one master agent is started. Otherwise, no agents are started. Default is `master`.
> `snmp_config_dir = string() <mandatory>`
>   Defines where the SNMP configuration files and the compiled master agent MIB files are stored.
> `snmp_db_dir = string() <mandatory>`
>   Defines where the SNMP internal db files are stored.
> `snmp_master_agent_mibs = [string()] <optional>`
>   Specifies a list of MIB names and defines which MIBs are initially loaded into the SNMP master agent. These MIBs are loaded from `snmp_config_dir`.
> `snmp_multi_threaded = bool() <optional>`
>   If `true`, the agent is multi-threaded, with one thread for each get request. Default is `false`.
> `snmp_priority = atom() <optional>`
>   Defines the Erlang priority for all SNMP processes. Default is `normal`.
> `v1 = bool() <optional>`
>   Defines if the agent shall speak SNMPv1. Default is `true`.
> `v2 = bool() <optional>`
>   Defines if the agent shall speak SNMPv2c. Default is `true`.
> `v3 = bool() <optional>`
>   Defines if the agent shall speak SNMPv3. Default is `true`.
> `snmp_local_db_auto_repair = false | true | true_verbose <optional>`
>   When starting snmp_local_db it always tries to open an existing database. If `false`, and some errors occur, a new datebase is created instead. If `true`, erroneous transactions (in the logfile) are ignored. If `true_verbose`, erroneous transactions (in the logfile) are igored and an error message is written. Default is `true`.
> `snmp_mibentry_override = bool() <optional>`
>   If this value is false, then when loading a mib each mib- entry is checked prior to installation of the mib. The perpose of the check is to prevent that the same symbolic mibentry name is used for in different oid's. Default is `false`.
> `snmp_trapentry_override = bool() <optional>`
>   If this value is false, then when loading a mib each trap is checked prior to installation of the mib. The perpose of the check is to prevent that the same symbolic trap name is used for in different trap's. Default is `false`.
> `snmp_error_report_mod = atom() <optional>`
>   Defines an error report module, other then the default. Two modules are provided with the toolkit: `snmp_error` and `snmp_error_io`. Default is `snmp_error`.
> `snmp_master_agent_verbosity = silence | info | log | debug | trace <optional>`
>   Specifies the startup verbosity for the SNMP master agent. Default is `silence`.
> `snmp_symbolic_store_verbosity = silence | info | log | debug | trace <optional>`
>   Specifies the startup verbosity for the SNMP symbolic store. Default is `silence`.
> `snmp_note_store_verbosity = silence | info | log | debug | trace <optional>`
>   Specifies the startup verbosity for the SNMP note store. Default is `silence`.
> `snmp_net_if_verbosity = silence | info | log | debug | trace <optional>`
>   Specifies the startup verbosity for the SNMP net if. Default is `silence`.
> `snmp_mibserver_verbosity = silence | info | log | debug | trace <optional>`
>   Specifies the startup verbosity for the SNMP mib server. Default is `silence`.
> `snmp_mib_storage = ets | {dets,Dir} | {dets,Dir,Action} | {mnesia,Nodes} | {mnesia,Nodes,Action} <optional>`
>   Specifies how info retrieved from the mibs will be stored. Default is `ets`.
>   `Dir = string()`. Dir is the directory where the (dets) files will be created.
>   `Nodes = [node()]`. If Nodes = [] then the own node is assumed.
>   `Action = clear | keep`. Default is `keep`. `Action` is used to specify what shall be done if the mnesia table already exist.

> ### 5.2 Modifying the Configuration Files

> To to start the agent, the agent configuration files must be modified and there are two ways of doing this. Either edit the files manually, or run the configuration tool as follows.

> If authentication or encryption is used (SNMPv3 only), start the `crypto` application.

>     1> application:start(crypto).
>     ok
>     2> snmp:config().

>     Simple SNMP configuration tool (v3.0)
>     ----------------------------------------------
>     Note: Non-trivial configurations still has to be done manually.
>     IP addresses may be entered as dront.ericsson.se (UNIX only) or 123.12.13.23

>     1. System name (sysName standard variable) [mbj's agent]
>     2. Engine ID (snmpEngineID standard variable)[mbj's engine]
>     3. The UDP port the agent listens to. (standard 161) [4000]
>     4. IP address for the agent (only used as id
>        when sending traps) [dront.ericsson.se]
>     5. IP address for the manager (only this manager will have access
>        to the agent, traps are sent to this one) [dront.ericsson.se]
>     6. To what UDP port at the manager should traps
>        be sent (standard 162)? [5000]
>     7. What SNMP version should be used (1,2,3,1&2,1&2&3,2&3)? [3]
>     7b. Should notifications be sent as traps or informs? [trap]
>     8. Do you want a none- minimum- or semi-secure configuration?
>        Note that if you chose v1 or v2, you will not get any security for these
>        requests (none, minimum, semi) [minimum]
>     8b. Give a password of at least length 8. It is used to generate
>     private keys for the  configuration.secretpasswd
>     9. Where is the configuration directory (absolute)? [/home/mbj/snmp_conf]
>     10. Current configuration files will now be overwritten. Ok [y]/n?
>     ------------------------
>     Info: 1. SecurityName "initial" has noAuthNoPriv read access and authenticated
>               write access to the "restricted" subtree.
>           2. SecurityName "all-rights" has noAuthNoPriv read/write access
>              to the "internet" subtree.
>           3. Standard traps are sent to the manager.
>     The following files were written: agent.conf, community.conf,
>        standard.conf, target_addr.conf, target_params.conf,
>        notify.conf vacm.conf, sys.config, usm.conf
>     ------------------------
>     ok

> ### 5.3 Starting the Agent

> Start Erlang with the command:

>     erl -config /home/mbj/snmp_conf/sys

> If authentication or encryption is used (SNMPv3 only), start the `crypto` application. If this step is forgotten, the agent will not start, but report a `{config_error,{unsupported_crypto,_}}` error.

>     1> application:start(crypto).
>     ok

>     2> application:start(snmp).
>     ok

> ### 5.4 Debugging the Agent

> It is possible to debug every process of the agent (possibly with the exception of the net_if module, which could be supplied by a user of the application). This can be done in two ways. Either by calling the `snmp:verbosity/2` function or using configuration parameters. The verbosity itself has several levels: `silence | info | log | debug | trace`. For the lowest verbosity `silence`, nothing is printed. The higher the verbosity, the more is printed. Default value is always `silence`.

> The old debugging is still available and produces more or less the same output, i.e. the debug flag can be turned on to verify that the configuration is correct and that the instrumentation functions behave as expected. The agent then shows all network communication (incoming/outgoing traffic), and calls to the instrumentation functions.

>     3> snmp:debug(snmp_master_agent, true).
>     ok
>     4>
>     %% Example of output from the agent when a get-next-request arrives:
>     ** SNMP NET-IF LOG:
>        got paket from {147,12,12,12}:5000

>     ** SNMP NET-IF MPD LOG:
>        v1, community: all-rights

>     ** SNMP NET-IF LOG:
>        got pdu from {147,12,12,12}:5000 {pdu, 'get-next-request',
>                                               62612569,noError,0,
>                                               [{varbind,[1,1],'NULL','NULL',1}]}

>     ** SNMP MASTER-AGENT LOG:
>        apply: snmp_generic,variable_func,[get,{sysDescr,persistent}]

>     ** SNMP MASTER-AGENT LOG:
>        returned: {value,"Erlang SNMP agent"}

>     ** SNMP NET-IF LOG:
>        reply pdu: {pdu,'get-response',62612569,noError,0,
>                        [{varbind,[1,3,6,1,2,1,1,1,0],
>                                  'OCTET STRING',
>                                  "Erlang SNMP agent",1}]}

>     ** SNMP NET-IF INFO: time in agent: 19711 mysec

> Another useful function for debugging is `snmp_local_db:print/0,1,2`. For example, this function can show the counters `snmpInPkts` and `snmpOutPkts`. Enter the following command:

>     4> snmp_local_db:print().
>     %% A lot of information.

Copyright © 1991-2003 Ericsson Utvecklings AB