.. _config-file: Configuration ************* .. contents:: .. toctree:: :maxdepth: 1 ssl authentication When you install NetSpyglass from rpm or deb package, the package also installs prototype configuration file `/opt/netspyglass/home/nw2.conf`. This file has comments to document all parameters, however it does not include all possible configuration parameters. The server uses "default" configuration that it loads from built-in configuration file and then merges it with configuration defined in the file `/opt/netspyglass/home/nw2.conf`. Parameters defined in file `/opt/netspyglass/home/nw2.conf` override those from the default built-in configuration. You can find a copy of the built-in default configuration file in the file `/opt/netspyglass/current/doc/default_config/netspyglass.conf`. This file has all recognized configuration parameters with comments, however it is provided for reference and is just a copy; editing it is not going to have any effect. If you want to change some of the parameters you find in it, copy them to your configuration file `/opt/netspyglass/home/nw2.conf` and make the change there. Configuration file has hierarchical structure and consists of individual variables, dictionaries and lists. Its syntax is losely based on JSON with some differences: * strings can be "bare" (unquoted) if they do not contain white space or special characters * list items do not need to be separated by comma when written one item per line * when value of a parameter is a dictionary, you can skip `=` or `:` * You can find more syntax rules and reference to the online documentation in :ref:`config-syntax` The syntax of the configuration file is described below in :ref:`config-syntax`. In the documentation we refer to the configuration parameters by combining enclosing dictionary name and the key name, separated by a dot. For example:: ui { url = "http://somehost:9100" } Parameter ``url`` can be referred to as ``ui.url`` in other parts of the configuration file. We also use this notation in the documentation. In order to start using the application, **edit at least the following parameters**: * ``home``: this should point to the directory where all files are located * ``ui.url``: this is the url UI backend is going to listen on. The default binds it to localhost but you probably need to change this to make it accessible from outside of the machine. We recommend using machine's IP address in ``ui.url``. Port number 9100 is used by the UI is just the default and can be changed in case of conflicts. For example:: ui { url = "http://192.168.1.100:9500/" } * ``network.name``: the name of your network. The name should be in double quotes if it includes white space * ``network.devices``: list of addresses and snmp communities of devices. See more on this below. By default server uses embedded SQL database. We recommend to keep it for evaluations, but if you intend to use your own MySQL database, change the following parameter: * ``ui.storage.connectionUrl``: this parameter tells UI backend how to connect to the database. Currently we support two databases: embedded HSQL database and MySQL. Prototype config file provides examples for both, including additional parameters where needed. The default is to use embedded database and place its files in the subdirectory "db" inside of the application home directory. MySQL connection string includes database name and authentication credentials in the following format:: ui.storage.connectionUrl = "mysql://sqlserver.domain.com:3306/nw2mon?user=nw2&password=nw2pass" here `nw2mon` is database name, `nw2` is user name and `nw2pass` is the password. .. note:: User `nw2` must have priviliges allowing it full access to the database. Database must exist at the time of server startup. See :ref:`databases` for more information. In addition to the paramerers listed above, here is a short list of the most basic configuration parameters you may need to change when you start using NetSpyGlass: * ``api.address``: This parameter is useful when machine where NetSpyGlass is running is multi-homed and has several ip addresses and you want to use one address for the UI web server access and another for the intra-cluster communication. Note that parameter ``ui.url`` should specify address `0.0.0.0` in this case. Other NetSpyGlass cluster servers will use address specified in the parameter ``api.address`` to connect to the server. * ``monitor.pollingIntervalSec``: polling interval in seconds. Default is 1 min * ``monitor.storage``: dictionary of parameters that describe Time Series Database you want to use to store monitoring data. We support the following databases: embedded RRD-like storage, Graphite, InfluxDb and hbase. Prototype config file provides examples for all of these, with embedded RRD storage enabled by default. It is also possible to run without any permanent storage at all if you comment out all storage parameters. Parameter ``memoryPoolDurationHrs`` is required though. * ``network.name``: the name of the network. This is going to appear in the UI and should be meaningful to you. Currently, NetSpyGlass supports only one network definition per application but this may change in the future. * ``network.devices``: list of device addresses and snmp community strings. Device is identified by the value of the parameter `address`, which can be either ip address or a host name. If the latter, then the server will try to resolve the name into ip address using DNS. If the name does not resolve, device can not be used (the server logs error and skips this configuration entry). When device is identified by the ip address, the name for the corresponding device object in NetSpyGlass is assigned using the following sources: if device responds to SNMP queries, then the value of `sysName` OID is used. IF device does not respond to SNMP queries, then the server uses reverse DNS lookup to find the name that corresponds to the specified ip address. If both methods fail, device name is going to be its ip address. Optional configuration parameter `name` can be used to assign the name to the device object when it is identified by its ip address in the parameter `address` and DNS PTR record does not exist for this address. Comments in the config prototype describe parameters and general syntax for this part of the configuration. Different devices can use different SNMP community strings and versions. If SNMP version parameter is missing, the version is assumed to be `2c`. If SNMP community is missing or is empty string, device will be added to the system and NetSpyGlass will try to put it on maps, but it is not going to send any SNMP queries to it. Here is an example:: devices = [ { address = "10.0.14.122", snmpCommunity = public }, { address = "10.0.14.123", name = "server1", snmpCommunity = public }, { address = "10.0.14.125", snmpCommunity = testcomm, snmpVersion = 1 }, ] .. note:: Since by default the server uses embedded SQL database and RRD storage, you can start minimal instance of the application by just editing home directory, connection urls and adding addresses of your devices in the ``network.devices`` section. Network Discovery ================= Once UI backend and monitor are running, connect to the url you configured in the ``ui.url`` configuration parameter with your browser. You should see the home page of the application with logo, network name and empty tiles. Start network discovery by clicking button "Discoverable". The program will start network discovery and you'll see a message "Discovery is in progress, started at ... " in the UI. It may take a few minutes to complete but once it is done, tiles should get populated with network maps and you should see discovery status ("Success" or "Failure") next to the "Discoverable" button. You can watch discovery progress in the log file `logs/info.log` Schedule -------- the program will run network discovery on schedule described by parameters discovery.schedule or discovery.interval in the configuration file. Only one of these can be present. Parameter discovery.interval simply defines interval in hours, beginning from the moment when the program has started. Parameter discvoery.schedule is a string in the cron-like format. Here is an example:: discovery { # scheduled discovery, interval is in hours # interval = 24 # Run discovery every day at 7am schedule = "0 0 7 * * ?" } The format is explained here: http://quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/tutorial-lesson-06 Supported Browsers ================== NetSpyGlass has been tested with * Chrome * Safari * FireFox v24 and later .. _config-syntax: Configuration file syntax ========================= Parsing of the configuration files is implemented using library "HOCON": https://github.com/typesafehub/config Basic rules of the config file format ------------------------------------- * Comments, with ``#`` or ``//`` * Allow omitting the {} around a root object * Allow ``=`` as a synonym for ``:`` * Allow omitting the ``=`` or ``:`` before a { so you can use ``foo { a : 42 }`` * Allow omitting commas as long as there's a newline * Allow trailing commas after last element in objects and arrays * Allow unquoted strings for keys and values * Unquoted keys can use dot-notation for nested objects, ``foo.bar=42`` means ``foo { bar : 42 }`` * Duplicate keys are allowed; later values override earlier, except for object-valued keys where the two objects are merged recursively * ``include`` feature merges root object in another file into current object, so ``foo { include "bar.json" }`` merges keys in bar.json into the object foo * include with no file extension includes any of .conf, .json, .properties * you can include files, URLs, or classpath resources; use ``include url("http://example.com")`` or ``file()`` or ``classpath()`` syntax to force the type, or use just ``include "whatever"`` to have the library do what you probably mean (Note: ``url()/file()/classpath()`` syntax is not supported in Play/Akka 2.0.) * substitutions ``foo : ${a.b}`` sets key foo to the same value as the ``b`` field in the ``a`` object * substitutions concatenate into unquoted strings, ``foo : the quick ${colors.fox} jumped`` * substitutions fall back to environment variables if they don't resolve in the config itself, so ``${HOME}`` would work as you expect. Also, most configs have system properties merged in so you could use ``${user.home}``. * substitutions normally cause an error if unresolved, but there is a syntax ``${?a.b}`` to permit them to be missing. * ``+=`` syntax to append elements to arrays, ``path += "/bin"`` * multi-line strings with triple quotes as in Python or Scala