NAME

App::Netdisco::Manual::Configuration - How to Configure Netdisco

INTRODUCTION

The configuration files for Netdisco come with all options set to sensible default values, and just a few that you must initially set yourself.

However as you use the system over time, there are many situations where you might want to tune the behaviour of Netdisco, and for that we have a lot of configuration settings available.

GUIDANCE

There are two configuration files: config.yml (which lives inside Netdisco) and deployment.yml (which usually lives in ${HOME}/environments).

The config.yml file includes defaults for every setting, and should be left alone. Any time you want to set an option, use only the deployment.yml file. The two are merged when Netdisco starts, with your settings in deployment.yml overriding the defaults from config.yml.

The configuration file format for Netdisco is YAML. This is easy for humans to edit, but you should take care over whitespace and avoid TAB characters. YAML supports several data types:

Boolean - True/False value, using 1 and 0 or true and false respectively
List - Set of things using [a, b, c] on one line or - on separate lines
Dictionary - Key/Value pairs (like Perl Hash) using {key1: val1, key2, val2} on one line or key: value on separate lines
String - Quoted, just like in Perl (and essential if the item contains the colon character)

SUPPORTED SETTINGS

Essential Settings

If you followed the installation instructions, then you should have set the database connection parameters to match those of your local system. That is, the database name, host, user and pass.

General Settings

`log`

Value: debug|warning|error. Default: warning.

The log level used by Netdisco. It's useful to see warning messages from the backend poller, as this can highlight broken topology.

`logger_format`

Value: Format String. Default: '[%P] %U %L %m'.

Structure of the log messages. See "logger_format" in Dancer::Logger::Abstract for details.

`include_paths`

Value: List. Default: Empty List.

Additional library paths for the application (both web frontend and backend poller daemons). You can also use a colon-separated list in the "NETDISCO_INC" environment variable.

Web Frontend

`domain_suffix`

Value: String. Default: None.

Set this to your local site's domain name. This is usually removed from node names in the web interface to make things more readable. Make sure to include the leading dot character.

`no_auth`

Value: Boolean. Default: false.

Enable this to disable login authentication in the web frontend. The username will be set to guest so if you want to allow extended permissions (admin or port_control), create a dummy user with the appropriate flag in the database:

netdisco=> insert into users (username) values ('guest');
netdisco=> update users set port_control = true where username = 'guest';
netdisco=> update users set admin = true where username = 'guest';

`navbar_autocomplete`

Value: Boolean. Default: true.

Set this to false to disable the device autocomplete in the main navbar.

`suggest_guest`

Value: Boolean. Default: false.

Enable this to display a banner suggesting to log in with a guest account. The username and password of this account must both be "guest".

`trust_remote_user`

Value: Boolean. Default: false.

Enable this if Netdisco is running within another web server such as Apache, and you want that server to handle user authentication. Normally the authenticated username will automatically be set in the REMOTE_USER environment variable. See "Running from Apache" in Dancer::Deployment for further details.

`trust_x_remote_user`

Value: Boolean. Default: false.

Enable this if you proxy requests to Netdisco via another web server such as Apache, and you want that server to handle user authentication. You need to configure the authorized username to be passed from the frontend environment to Netdisco in the X-REMOTE_USER HTTP Header. For example with Apache:

RequestHeader unset X-REMOTE_USER
RequestHeader set X-REMOTE_USER "%{REMOTE_USER}e" env=REMOTE_USER

`ldap`

Value: Settings Tree. Default: None.

If set, and a user has the ldap flag also set on their account, then LDAP authentication will be used for their login.

ldap:
  servers:
    - 'ad.example.com'
  user_string: 'MYDOMAIN\%USER%'
  opts:
    debug: 3

There are several options within this setting:

`servers`

This must be a list of one or more LDAP servers. If using Active Directory these would be your Domain Controllers.

`user_string`

String to construct the user portion of the DN. %USER% is a variable which will be replaced at runtime with the logon name entered on the logon page of the application.

Active Directory users may simply use MYDOMAIN\%USER% and skip all other options except servers, as this notation eliminates the need to construct the full distinguished name.

Examples: cn=%USER% or uid=%USER%.

`base`

Indicates where in the hierarchy to begin searches. If a proxy user is not defined and anonymous binds are not enabled this value will be appended to the user_string to construct the distinguished name for authentication.

`proxy_user`

User to bind with to perform searches. If defined as anonymous, then anonymous binds will be performed and proxy_pass will be ignored. For organizations with users in multiple OUs this option can be used to search for the user and construct the DN based upon the result.

`proxy_pass`

Proxy user password. Ignored if proxy user defined as anonymous.

`opts`

Hash of options to add to the connect string. Normally only needed if server does not support LDAPv3, or to enable debugging as in the example above.

`tls_opts`

A hash which, when defined, causes the connection tol use Transport Layer Security (TLS) which provides an encrypted connection. TLS is the preferred method of encryption, ldaps (port 636) is not supported.

This is only possible if using LDAPv3 and the server supports it. These are the options for the TLS connection. See the Net::LDAP documentation under start_tls for options, but the defaults should work in most cases.

`path`

Value: String. Default: None.

Mount point for the Netdisco web frontend. This is usually the root of the web server. Set this to the path under which all pages live, e.g. /netdisco2. As an alternative you can use the --path option to netdisco-web.

`web_plugins`

Value: List of Modules. Default: List of bundled App::Netdisco::Web::Plugin names.

Netdisco's plugin system allows the user more control over the user interface. Plugins can be distributed independently from Netdisco and are a better alternative to source code patches. This setting is the list of Plugins which are used in the default Netdisco distribution.

You can override this to set your own list. If you only want to add to the default list then use extra_web_plugins, which allows the Netdisco developers to update default web_plugins in a future release.

Entries in the list will by default omit the leading App::Netdisco::Web::Plugin:: from the name. To override this for one entry, prefix it with a + sign. You can also prefix with X:: to signify the alternate App::NetdiscoX::Web::Plugin:: namepsace.

`extra_web_plugins`

Value: List of Modules. Default: Empty List.

List of additional App::Netdisco::Web::Plugin names to load. See also the web_plugins setting.

`reports`

Value: List of Reports Hashes. Default: None.

Use this configuration to add reports to Netdisco without writing any Perl code or HTML templates. For example:

reports:
  - tag: power_inventory
    category: Device
    label: 'Power Supply Inventory'
    columns:
      - {name: 'Name'}
      - {ps1_type: 'PS1 Type'}
      - {ps1_status: 'PS1 Status'}
    query: |
      SELECT d.name, d.ps1_type, d.ps1_status
        FROM device d
      ORDER BY name

The tag of each item in the reports configuration is an alias for the report, and becomes part of the web path.

You can munge the data retrieved from the database by placing a Perl script with the same name as the reports key into the "site_plugins" directory of Netdisco's home area. The script can access $config for its configuration and @data for the retrieved data. It should return a list of munged data.

Within the tree you can provide each of the keys below:

`tag`

Alias for the Report, which must be usable in a web path.

`label`

Title for the Report.

`columns`

List of single-key Hashes which map database column (field) name to table heading.

`query`

SQL which returns the data. Make sure that the columns are named the same as the keys of the columns or query_columns configuration. Note the way the SQL is specified in the example above, using the pipe symbol and then indenting the query text.

`category` (optional)

Section of the Reports menu where this report will appear. See WritingPlugins for the full list. If not supplied, reports appear in a My Reports category.

`query_columns` (optional)

If supplying code to munge the data, the columns returned from your database query may not be the same as those in the web report. Set this to a list of the columns in query. The columns setting will then be used for the web report.

`bind_params` (optional)

You can use placeholders in the SQL query (that is, "?") to bind user-supplied parameters. This setting should be a list of the parameters to pick out of the URL query string and match to the placeholders in the same order. For example:

query: |
  SELECT ... FROM ... WHERE device = ? AND port = ?
bind-params: ['device', 'port']

# then
http://localhost:5000/report/my_special_report?device=192.0.2.1&port=Vlan142

`jobqueue_refresh`

Value: Integer Number. Default: 5.

Number of seconds between reloads of the Job Queue panel in the web interface.

`safe_password_store`

Value: Boolean. Default: true.

Set to "false" if you MUST maintain backwards compatibility with the Netdisco 1.x web interface. Strongly recommended that you leave this set to "true".

`table_pagesize`

Value: Number. Default: 10.

The default number of rows in a table page.

`table_showrecordsmenu`

Value: Number. Default:

table_showrecordsmenu:
  - [10, 25, 50, 100, '-1']
  - [10, 25, 50, 100, 'All']

The choices available to users for selecting the number of rows per page. The format is two lists: one of the values and one of the labels in the web interface. You can see in the default that a value of "-1" means Show All Records.

`vlanctl`

Value: Boolean. Default: true.

Set to false to prevent users from changing the default VLAN on an interface. This setting has no effect when portctl_nameonly below is set to true.

`portctl_nameonly`

Value: Boolean. Default: false.

Set to true to limit port control action to only changing the interface name (description).

`portctl_nophones`

Value: Boolean. Default: false.

Set to true to make sure an IP Phone port never can be turned off/on.

`portctl_vlans`

Value: Boolean. Default: false.

Set to true to allow Netdisco to be able to disable VLAN trunk interfaces.

EXTREMELY VERY DANGEROUS: Turning off a VLAN trunk link could take out most of your network.

`portctl_uplinks`

Value: Boolean. Default: false.

Set to true to allow Netdisco to be able to disable Uplinks. (Router Interfaces too)

EXTREMELY VERY DANGEROUS: Turning off uplinks will take out chunks of your network.

`port_control_reasons`

Value: Hash of Strings. Default:

port_control_reasons:
  address:     'Address Allocation Abuse'
  copyright:   'Copyright Violation'
  dos:         'Denial of Service'
  bandwidth:   'Excessive Bandwidth'
  polling:     'Excessive Polling of DNS/DHCP/SNMP'
  noserv:      'Not In Service'
  exploit:     'Remote Exploit Possible'
  compromised: 'System Compromised'
  other:       'Other'
  resolved:    'Issue Resolved'

When a user has Port Control rights and shuts down a port, they are asked for a reason. This configuration lists those reasons, and can be overridden to add or remove any entries.

`check_userlog`

Value: Boolean. Default: true.

Set to false to disable the periodic AJAX check for completed entries in the job queue for this user. Mainly useful for development to suppress noisy web frontend activity.

`devport_vlan_limit`

Value: Number. Default: 150.

When showing Device Ports, Netdisco calculates first an average number of VLANs across all device ports. If this is above this configurable threshold, the VLAN Membership is not shown (regardless of Display Columns setting.

Netdisco Core

`mibhome`

Value: Directory. Default: ${HOME}/netdisco-mibs.

Base directory in which to find mibdirs. This is where netdisco-deploy will drop MIB files.

`mibdirs`

Value: List of Directories. Default: All subdirectories of mibhome.

A list of subdirectories of mibhome from which to load MIB files. You should always include rfc. For example:

mibdirs:
  - rfc
  - cisco
  - foundry

`community`

Value: List of Strings. Default: public.

A list of read-only SNMP community strings to try on each device. This is the simplest way to configure your SNMPv1 or SNMPv2 community strings. For example:

community:
  - public
  - anotherstring
  - mycommunity

Each is tried in turn when polling the device, and then the working community string will be cached in the database.

For fine-grained control over which communities are tried for which devices, or to set SNMPv3 authentication, see snmp_auth, below.

`community_rw`

Value: List of Strings. Default: private.

A list of read-write SNMP community strings to try on each device. The working community will be cached in the database.

This is the simplest way to configure SNMPv1 or SNMPv2 community strings. Each is tried in turn when writing to the device, and then the working community string will be cached in the database.

For fine-grained control over which communities are tried for which devices, or to set SNMPv3 authentication, see snmp_auth, below.

`snmp_auth`

Value: List of Settings Trees. Default: Empty List.

This setting is used for SNMPv3 authentication configuration, and also provides an alternative fine-grained control for SNMPv1 and SNMPv2 community strings. You provide a list of authentication stanzas, and Netdisco will try each in turn, then cache the one which works for a device.

Each stanza can be restricted for use only on specific IP prefixes (subnets), and also limited to read (get) and/or write (set) operations. By default, a stanza is enabled for all device IPs, for read access only. The "tag" of a stanza is simply a friendly name used by Netdisco to refer to the configuration.

snmp_auth:
  - community: public
  - community: publictwo
  - community: mycommunity
    write: true
  - community: mycommunity2
    read: false
    write: true
  - tag: v3example
    user: netdisco
    auth:
      pass: netdiscokey
      proto: MD5
    priv:
      pass: netdiscokey2
      proto: DES
  - tag: v3aclexample
    user: netdisco2
    only:
      - 192.0.2.0/30
      - 172.20.10.0/24
  - tag: v2aclexample
    community: s3kr1t
    read: false
    write: true
    only:
      - 2001:db8::/32

For SNMPv1 and SNMPv2, only the community key is required. Unlike the global community/community_rw setting, this is not a list but a single item. To emulate their list behaviour, have multiple entries at the top snmp_auth level, as in the example above.

You can add read and/or write restrictions, and an IP restriction using only. Giving the stanza a tag name is optional, but recommended.

For SNMPv3 the tag and user keys are required. You can add read and/or write restrictions, and an IP restriction using only. Providing an auth section enables the authentication security level. Providing a priv section enables the message encryption security level.

As per Net-SNMP, the default SNMPv3 authentication security method is MD5, and the default encryption protocol is DES, with AES or AES256 being common alternatives. Note that you cannot have priv without auth.

On some device platforms SNMPv3 contexts are used to macsuck each VLAN. For this you usually configure a common context prefix, with Netdisco's default being "vlan-" (i.e. vlan-1, vlan-2, etc). Add the context_prefix key to a stanza to override this.

`get_community`

Value: String. Default none.

An external program to run to get the community string for a given device. This is useful if, for example, you have you devices already configured in another NMS and you want to use that information instead of configuring snmp_auth.

The strings "%IP%" and "%HOST%" are replaced by the IP address and the hostname (or IP address if no hostname is known) of the system being contacted. For example:

get_community: '/path/to/my/program %IP%'

The command must return output in the following form:

community=<comma-separated list of readonly-communities>
setCommunity=<comma-separated list of write-communities>

If the community string is not known for the given system, the command should return no output and the community strings configured in snmp_auth, community, and community_rw will be used instead.

`bulkwalk_off`

Value: Boolean. Default false.

Set to true to use GETNEXT instead of the standard BULKWALK for every device. This will slow things down, but might be necessary for problem devices. For more fine-grained control see the bulkwalk_no setting.

`bulkwalk_no`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

IP addresses in the list will use GETNEXT (and not BULKWALK). You can include hostnames, IP addresses, subnets (IPv4 or IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace) in the list.

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`bulkwalk_repeaters`

Value: Number. Default: 20.

Sets the Net-SNMP MaxRepeaters value, which is used on BULKWALK operations. See SNMP for more info.

`nonincreasing`

Value: Boolean. Default: false.

Setting this to true prevents bulkwalk of device tables with non-increasing OIDs throwing an error OID not increasing when encountered. The default is to allow non-increasing OIDs during bulkwalk (which may, in very badly performing SNMP agents, result in a never-ending loop). Requires Net-SNMP 5.3 or higher.

`snmpver`

Value: 1|2|3. Default: 3.

Highest version of the SNMP protocol used when connecting to devices. Use this setting to disable SNMP v3 globally. Usually you don't need to configure this.

`snmpforce_v1`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

Forces matching devices to use SNMPv1.

`snmpforce_v2`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

Forces matching devices to use SNMPv2c.

`snmpforce_v3`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

Forces matching devices to use SNMPv3.

`snmptimeout`

Value: Number. Default: 1000000.

Micro-seconds before connection retry in SNMP::Session. 1000000 micro-seconds = 1 second.

`snmpretries`

Value: Number. Default: 2.

Number of times to retry connecting to a device before giving up.

`discover_no`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

IP addresses in the list will not be visited during device discovery. You can include hostnames, IP addresses, subnets (IPv4 or IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace) in the list.

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`discover_only`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

If present, device discovery will be limited to IP addresses matching entries in this list. You can include hostnames, IP addresses, subnets (IPv4 and IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace).

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`discover_no_type`

Value: List of Strings. Default: None.

Place regular expression patterns here to exclude the discovery of certain devices based on the CDP/LLDP device type information. Good for excluding a whole device class like lightweight access points or IP phones that have CDP but don't talk SNMP. For example:

discover_no_type:
  - 'cisco\s+AIR-LAP'
  - '(?i)Cisco\s+IP\s+Phone'

`discover_min_age`

Value: Number. Default: 0.

Sets the minimum amount of time in seconds which must elapse between any two discover jobs for a device.

`macsuck_no`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

IP addresses in the list will not be visited for macsuck. You can include hostnames, IP addresses, subnets (IPv4 or IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace) in the list.

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`macsuck_only`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

If present, macsuck will be limited to IP addresses matching entries in this list. You can include hostnames, IP addresses, subnets (IPv4 and IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace).

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`macsuck_all_vlans`

Value: Boolean. Default: false.

Set to macsuck all VLANs, not just the ones that are being used on ports. This is a debug option. Set this if you think that the option of not macsucking VLANs that aren't in use on device ports is some how interfering.

`macsuck_no_unnamed`

Value: Boolean. Default: false.

Set to true to skip macsuck-ing on VLANs which have no name set. This option may be useful on Cisco Catalyst family devices where ports are a member of a VLAN which is not defined in the VLAN database.

`macsuck_no_vlan`

Value: List of VLAN names or numbers. Default: fddi-default, token-ring-default,fddinet-default,trnet-default.

On some devices, per-VLAN macsuck will timeout with specific VLAN numbers. You can put those numbers (or their names) into this list to have them skipped.

`macsuck_no_devicevlan`

Value: List of "IP:vlan-number" or "IP:vlan-name". Default: Empty List.

Similar to macsuck_no_vlan, but allows specifying the device root (canonical) IP, in order to restrict VLAN skipping only to some devices.

`macsuck_unsupported`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

Similar to macsuck_no, but instead of skipping nodes on this device, they are allowed to gather on the upstream device port. Useful for devices which can be discovered by Netdisco but do not provide a MAC address table via SNMP.

`macsuck_unsupported_type`

Value: List of Strings. Default: None.

Place regular expression patterns here to skip macsuck of certain devices based on the CDP/LLDP device type information they advertise. MAC addresses will be allowed to gather on the upstream device port, as in the macscuk_unsupported setting. For example:

macsuck_unsupported_type:
  - 'cisco\s+AIR-LAP'
  - '(?i)Cisco\s+IP\s+Phone'

`macsuck_bleed`

Value: Boolean. Default: false.

Set to true will let nodes accumulate on uplink ports without topology information. This is a debug option to help you figure out your topology and generally should not be set.

`macsuck_min_age`

Value: Number. Default: 0.

Sets the minimum amount of time in seconds which must elapse between any two macsuck jobs for a device.

`arpnip_no`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

IP addresses in the list will not be visited for arpnip. You can include hostnames, IP addresses, subnets (IPv4 or IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace) in the list.

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`arpnip_only`

Value: List of Network Identifiers or Device Properties. Default: Empty List.

If present, arpnip will be limited to IP addresses matching entries in this list. You can include hostnames, IP addresses, subnets (IPv4 and IPv6), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace).

Alternatively include a "property:regex" entry to match the named property of the device. The regex must match the complete value.

`arpnip_min_age`

Value: Number. Default: 0.

Sets the minimum amount of time in seconds which must elapse between any two arpnip jobs for a device.

`nbtstat_no`

Value: List of Network Identifiers. Default: Empty List.

IP addresses in the list will not be visited for nbtstat. You can include hostnames, IP addresses, subnets (nbtstat only supports IPv4), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace) in the list.

`nbtstat_only`

Value: List of Network Identifiers. Default: Empty List.

If present, nbtstat will be limited to IP addresses matching entries in this list. You can include hostnames, IP addresses, subnets (nbtstat only supports IPv4), YAML Regexp to match the DNS name, and address ranges (using a hyphen and no whitespace).

`nbtstat_max_age`

Value: Number. Default: 7.

The maximum age of a node in days for it to be checked for NetBIOS information.

`nbtstat_interval`

Value: Number. Default: 0.02.

Interval between nbtstat requests in each poller. Defaults to 0.02 seconds, equating to 50 requests per second per poller.

`nbtstat_timeout`

Value: Number. Default: 1.

Seconds nbtstat will wait for a response before time out. Accepts fractional seconds as well as integers.

`node_freshness`

Value: Number of Minutes. Default: 0

Controls the behaviour of Netdisco when a node (workstation, printer, etc) has disappeared from the network (device MAC address tables).

If set to 0, the default, nodes will remain on the last-seen switch port until "expire_nodes" days have passed (when they'll be deleted if you run the Expire job). This is the same behaviour as Netdisco 1.

Set to a number of minutes to enforce some kind of ageing on this data. For example you could set to 60 to match the default macsuck schedule, meaning nodes are archived if they're not in the device tables at the time of polling.

`expire_devices`

Value: Number of Days. Default: 60

Devices that have not been refreshed in this number of days will be removed. All nodes connected to this device will be removed as well.

`expire_nodes`

Value: Number of Days. Default: 90

Nodes that have not been refreshed in this number of days will be removed from the database. Archived and non-archived nodes are removed. This includes SwitchPort/MAC and MAC/IP mappings.

`expire_nodes_archive`

Value: Number of Days. Default: 60

Archived data for switch-port/MAC and MAC/IP mappings older than this number of days will be removed.

`expire_jobs`

Value: Number of Days. Default: 14

Jobs which entered the job queue more than this many days ago will be removed from the queue during the scheduled expiry process (regardless of whether they were ever run).

`dns`

Value: Settings Tree. Default:

dns:
  max_outstanding: 50
  hosts_file: '/etc/hosts'
  no: ['fe80::/64','169.254.0.0/16']

After arpnip, each found IP will have its DNS name resolved. Similarly on device discovery, all interface aliases will have their IPs resolved to names.

This setting controls how many outstanding DNS queries are permitted at any time. You can also override this setting using the PERL_ANYEVENT_MAX_OUTSTANDING_DNS environment variable. Similarly, the location of the Hosts file can be overridden in this config, or using the PERL_ANYEVENT_HOSTS environment variable.

`store_wireless_clients`

Value: Boolean. Default: true.

Set to false to skip the wireless client information gathering. This is captured at macsuck time, so if you aren't using the information you can skip it.

`store_modules`

Value: Boolean. Default: true.

Set to false to skip the module inventory on device discovery. On some platforms this can double the discovery time.

`ignore_interfaces`

Value: List of Strings. Default:

ignore_interfaces:
  - 'EOBC'
  - 'unrouted VLAN'
  - 'StackPort'
  - 'Control Plane Interface'
  - 'SPAN (S|R)P Interface'
  - 'StackSub'
  - 'netflow'
  - 'Vlan\d+-mpls layer'
  - 'BRI\S+-Bearer Channel'
  - 'BRI\S+-Physical'
  - 'BRI\S+-Signalling'
  - 'Embedded-Service-Engine\d+\/\d+'
  - 'Virtual-Template\d+'
  - 'Virtual-Access\d+'
  - '(E|T)\d \d\/\d\/\d'

If present, device ports whose names match fully any of the items in this list will be ignored by the discovery process.

Note this may have side effects - connected devices and nodes on those ports will in turn also not be discovered.

`ignore_private_nets`

Value: Boolean. Default: false.

Set to true to ignore device interfaces that are part of private nets (RFC 1918).

`reverse_sysname`

Value: Boolean. Default: false.

Turn this on to have Netdisco do a reverse lookup of the device sysName.0 field to use as the management IP address for a device.

`phone_capabilities`

Value: List of Strings. Default:

phone_capabilities:
  - '(?i:phone)'

Regular expressions to match the Capability field received within neighbor discovery protocols such as CDP/FDP/LLDP. Netdisco uses this to display a "phone" icon alongside devices or nodes in the Device Ports table.

To find the received Capabilities on an upstream device, run this command:

~netdisco/bin/netdisco-do show -d <IP-of-device> -e c_cap

`phone_platforms`

Value: List of Strings. Default:

phone_platforms:
  - '(?i:mitel.5\d{3})'

Regular expressions to match the Platform field received within neighbor discovery protocols such as CDP/FDP/LLDP. Netdisco uses this to display a "phone" icon alongside devices or nodes in the Device Ports table.

To find the received Platforms on an upstream device, run this command:

~netdisco/bin/netdisco-do show -d <IP-of-device> -e c_platform

`phone_ouis`

Value: List of Strings. Default: Empty List.

If you can't get phone_capabilities or phone_platforms to match, as a last ditch attempt you can match on the MAC address of the device (if it has one). This is a set of regular expressions matched against the whole MAC address (not only the OUI portion) in IEEE format. For example:

phone_ouis:
  - '^a4:0c:c3'

`wap_capabilities`

Value: List of Strings. Default:

wap_capabilities:
  - 'wlanAccessPoint'

Regular expressions to match the Capability field received within neighbor discovery protocols such as CDP/FDP/LLDP. Netdisco uses this to display a "wireless signal" icon alongside devices or nodes in the Device Ports table.

To find the received Capabilities on an upstream device, run this command:

~netdisco/bin/netdisco-do show -d <IP-of-device> -e c_cap

`wap_platforms`

Value: List of Strings. Default:

wap_platforms:
  - '(?i:\bw?ap\b)'
  - 'cisco\s+AIR-[L|C]?AP'
  - '-K9W8-'

Regular expressions to match the Platform field received within neighbor discovery protocols such as CDP/FDP/LLDP. Netdisco uses this to display a "wireless signal" icon alongside devices or nodes in the Device Ports table.

To find the received Platforms on an upstream device, run this command:

~netdisco/bin/netdisco-do show -d <IP-of-device> -e c_platform

`wap_ouis`

Value: List of Strings. Default: Empty List.

If you can't get wap_capabilities or wap_platforms to match, as a last ditch attempt you can match on the MAC address of the device (if it has one). This is a set of regular expressions matched against the whole MAC address (not only the OUI portion) in IEEE format. For example:

wap_ouis:
  - '^a4:0c:c3'

Backend Daemon

`workers`

Value: Settings Tree. Default:

workers:
  tasks: 'AUTO * 2'
  sleep_time: 1

Control the activity of the backend daemon with this configuration setting.

tasks sets how many worker processes are started for interactive jobs (port control) and polling jobs (discover, macsuck, arpnip) on this node. Other nodes can have different settings.

"AUTO" is the number of CPU cores. Set tasks to "0" to disable all workers (which allows you to have a scheduler-only node).

sleep_time is the number of seconds between polling the database to find new jobs. This is a balance between responsiveness and database load.

`dns`

Value: Settings Tree. Default:

dns:
  max_outstanding: 250
  no: ['fe80::/64','169.254.0.0/16']

Controls the asynchronous DNS resolver used to resolve IP addresses to names during arpnip and discovery of device aliases.

max_outstanding sets the maximum number of outstanding requests for asynchronous DNS resolution. This setting overrides the PERL_ANYEVENT_MAX_OUTSTANDING_DNS environment value and the AnyEvent library default of 10.

no is a list of IP addresses or CIDR ranges to excluded from DNS resolution. Link local addresses are excluded by default.

`schedule`

Value: Settings Tree. Default: None.

If set, then this node's backend daemon will schedule polling jobs (discover, macsuck, arpnip, etc) in the central database. It's fine to have multiple nodes scheduling work for redundancy (but make sure they all have good NTP).

Note that this is independent of the Tasks configured in workers. It's okay to have this node schedule schedule but not do any of the polling itself (tasks: 0).

Work can be scheduled using cron style notation, or a simple weekday and hour fields (which accept same types as cron notation). For example:

schedule:
  discoverall:
    when: '0 9 * * *'
  arpwalk:
    when:
      min: 30
  macwalk:
    when:
      min: 15
      hour: '*/2'
      wday: 'mon-fri'
  nbtwalk:
    when: '0 8,13,21 * * *'
  expire:
    when: '20 23 * * *'

Note that the "when" fields default to "all" (i.e. "*") when not specified. See Algorithm::Cron for further details.

Dancer Internal

`charset`

Value: String. Default: UTF-8.

See "charset-string" in Dancer::Config.

`warnings`

Value: Boolean. Default: false.

Should warnings be considered as critical errors?

`show_errors`

Value: Boolean. Default: false.

Whether to show a stack trace when an error is caught in the web frontend.

`logger`

Value: console|file. Default: console.

Destination for log messages. Should usually be console, which does the right thing when running foreground apps, and is also captured to ${HOME}/logs when running daemonized. Only change this if you know what you're doing.

`engines`

Value: Settings Tree.

Useful for overriding the Template Toolkit settings, if you want.

`layout`

Value: String. Default: main.

Don't touch this.

`plugins`

Value: Settings Tree.

Useful for overriding the Database configuration, but only if you know what you're doing.

`session`

Value: String. Default: YAML.

How to handle web sessions. Default is to store on disk so they can be shared between multiple web server processes (although it's slower).

`template`

Value: String. Default: template_toolkit.

Which engine to use for templating in the web frontend. Don't touch this.

`route_cache`

Value: Boolean. Default: true.

Whether to build a route cache for web requests, for better performance.

`appname`

Value: String. Default: Netdisco.

Don't touch this.

`behind_proxy`

Value: Boolean. Default: false.

There's no need to touch this. See deployment documentation for how to proxy.

UNSUPPORTED (SO FAR)

These settings are from Netdisco 1.x but are yet to be supported in Netdisco 2. If you really need the feature, please let the developers know.

col_xxx_show
macsuck_timeout
port_info
portctl_timeout
timeout

To install App::Netdisco, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::Netdisco

CPAN shell

perl -MCPAN -e shell
install App::Netdisco

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INTRODUCTION

GUIDANCE

SUPPORTED SETTINGS

Essential Settings

General Settings

log

logger_format

include_paths

Web Frontend

domain_suffix

no_auth

navbar_autocomplete

suggest_guest

trust_remote_user

trust_x_remote_user

ldap

servers

user_string

base

proxy_user

proxy_pass

opts

tls_opts

path

web_plugins

extra_web_plugins

reports

tag

label

columns

query

category (optional)

query_columns (optional)

bind_params (optional)

jobqueue_refresh

safe_password_store

table_pagesize

table_showrecordsmenu

vlanctl

portctl_nameonly

portctl_nophones

portctl_vlans

portctl_uplinks

port_control_reasons

check_userlog

devport_vlan_limit

Netdisco Core

mibhome

mibdirs

community

community_rw

snmp_auth

get_community

bulkwalk_off

bulkwalk_no

bulkwalk_repeaters

nonincreasing

snmpver

snmpforce_v1

snmpforce_v2

snmpforce_v3

snmptimeout

snmpretries

discover_no

discover_only

discover_no_type

discover_min_age

macsuck_no

macsuck_only

macsuck_all_vlans

macsuck_no_unnamed

macsuck_no_vlan

macsuck_no_devicevlan

macsuck_unsupported

macsuck_unsupported_type

macsuck_bleed

macsuck_min_age

arpnip_no

arpnip_only

`log`

`logger_format`

`include_paths`

`domain_suffix`

`no_auth`

`navbar_autocomplete`

`suggest_guest`

`trust_remote_user`

`trust_x_remote_user`

`ldap`

`servers`

`user_string`

`base`

`proxy_user`

`proxy_pass`

`opts`

`tls_opts`

`path`

`web_plugins`

`extra_web_plugins`

`reports`

`tag`

`label`

`columns`

`query`

`category` (optional)

`query_columns` (optional)

`bind_params` (optional)

`jobqueue_refresh`

`safe_password_store`

`table_pagesize`

`table_showrecordsmenu`

`vlanctl`

`portctl_nameonly`

`portctl_nophones`

`portctl_vlans`

`portctl_uplinks`

`port_control_reasons`

`check_userlog`

`devport_vlan_limit`

`mibhome`

`mibdirs`

`community`

`community_rw`

`snmp_auth`

`get_community`

`bulkwalk_off`

`bulkwalk_no`

`bulkwalk_repeaters`

`nonincreasing`

`snmpver`

`snmpforce_v1`

`snmpforce_v2`

`snmpforce_v3`

`snmptimeout`

`snmpretries`

`discover_no`

`discover_only`

`discover_no_type`

`discover_min_age`

`macsuck_no`

`macsuck_only`

`macsuck_all_vlans`

`macsuck_no_unnamed`

`macsuck_no_vlan`

`macsuck_no_devicevlan`

`macsuck_unsupported`

`macsuck_unsupported_type`

`macsuck_bleed`

`macsuck_min_age`

`arpnip_no`

`arpnip_only`

`arpnip_min_age`

`nbtstat_no`

`nbtstat_only`

`nbtstat_max_age`

`nbtstat_interval`

`nbtstat_timeout`

`node_freshness`

`expire_devices`