netdisco/lib/App/Netdisco/Manual/Configuration.pod

=head1 NAME

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

=head1 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.

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

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

=head2 YAML GUIDANCE

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

=over 4

=item *

Boolean - True/False value, using C<1> and C<0> or C<true> and C<false>
respectively, e.g.:

 check_userlog: true

=item *

List - Set of things using C<[a, b, c]> on one line or C<-> on separate lines,
e.g.:

 community: ['public', 'another']
 
 discover_no:
   - 192.0.2.0/24
   - '2001:db8::/32'

=item *

Dictionary - Key/Value pairs (like Perl Hash) using C<< {key1: val1, key2:
val2} >> on one line or C<key: value> on separate lines, e.g.:

 port_control_reasons:
   address:   'Address Allocation Abuse'
   copyright: 'Copyright Violation'

=item *

String - Optionally quoted, just like in Perl (quotes required if the item
contains a colon character). For example:

 log: 'debug'
 expire_devices: 15

=back

=head2 ACCESS CONTROL LISTS

Access Control Lists (ACLs) appear in many places in the configuration file,
used to select or exclude devices or hosts for certain settings. ACLs are a
single item or YAML list of items, which can contain:

=over 4

=item *

Hostname, IP address, IP prefix (i.e. subnet), such as:

 - hostname.example.com
 - 192.0.2.1
 - '2001:db8::/32'

=item *

IP address range, using a hyphen on the last octet/hextet, and no whitespace:

 - 192.0.2.1-10

=item *

Regular expression in YAML format (no enforced anchors) which will match the
device DNS name (using a fresh DNS lookup, so works on new discovery), e.g.:

 - !!perl/regexp ^sep0.*$

=item *

"C<property:regexp>" to match against a device property, such as C<model> or
C<vendor> (with enforced begin/end regexp anchors). When matching a device's
interface, "C<port:regexp>" is also an option (see C<device_identity>).

 - 'vendor:cisco'

=item *

"C<group:groupname>" to reference the "C<groupname>" group from the
C<host_groups> setting. This is a way to either include ACLs in other ACLs, or
re-use ACLs.

=item *

"C<op:and>" to require all items to match (or not match) the provided IP or
device. Note that this includes IP address version mismatches (v4-v6).

=back

To negate any item in an ACL (except YAML regexp), prefix with "C<!>", for
example "C<!192.0.2.0/29>". In that case the test will be that the ACL entry
does I<not> match the device or IP being assessed. Note, however, that the
first match in an ACL wins (because the default mode is "OR"), so take care
with the order of items or include "C<op:and>" in the ACL if appropriate.

To match any device, use "C<any>". To match no devices use "C<!any>".

Configuration settings in Netdisco that take an Access Control List (most of
the "C<*_no>" and "C<*_only>" settings, and "C<only>" settings) can accept
either a YAML list of the above items, or merely a single item. This is useful
if you create a C<host_groups> entry and wish to reference that as the ACL.

=head1 SUPPORTED SETTINGS

=head2 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 C<name>, C<host>, C<user> and C<pass>.

=head2 General Settings

=head3 C<log>

Value: C<debug|warning|error>. Default: C<warning>.

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

=head3 C<logger_format>

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

Structure of the log messages. See L<Dancer::Logger::Abstract/"logger_format">
for details.

=head3 C<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
"C<NETDISCO_INC>" environment variable which makes code available even earlier
in the app startup sequence.

=head3 C<template_paths>

Value: List. Default: Empty List.

Additional paths for L<Template::Toolkit> templates. Files in these paths will
be loaded before (and hence override) any templates built in to Netdisco.

If you want to copy and override a built in web template, then create the
directories necessary (such as "ajax" or "sidebar") in this path.  Note that
templates may need to have a further "C<views>" subdirectory created.

=head3 C<site_local_files>

Value: Boolean. Default: false.

A shortcut for using C<include_paths> and C<template_paths>. Setting this to
true will push C<< $ENV{NETDISCO_HOME}/nd-site-local/{lib,share} >> into those
settings, respectively. You can then put Perl code in C</lib> and templates in
C</share> within the C<nd-site-local> directory.

Note that you still need to create the directories yourself, and templates may
need to have a further "C<views>" subdirectory created within "C<share>".

=head3 C<external_databases>

Value: List of Database Configuration dictionaries. Default: None.

The Plugins and User Reports features of Netdisco can gather data from
external databases. You need to install the Perl database driver for the
target database platform, and configure this setting appropriately. For
example:

 external_databases:
   - tag: externaldb
     dsn: 'dbi:Pg:dbname=myexternaldb;host=192.0.2.1'
     user: oliver
     password: letmein
     options:
       pg_enable_utf8: true

Note that C<tag> is I<required> and maps to the C<database> key if you use the
Generic Reports feature (see "L</reports>", below), or becomes the Dancer
database schema name if you program the Plugin directly.

=head2 Web Frontend

=head3 C<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.

=head3 C<no_auth>

Value: Boolean. Default: C<false>.

Enable this to disable login authentication in the web frontend. The username
will be set to C<guest> so if you want to allow extended permissions (C<admin>
or C<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';

=head3 C<navbar_autocomplete>

Value: Boolean. Default: C<true>.

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

=head3 C<suggest_guest>

Value: Boolean. Default: C<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".

=head3 C<trust_remote_user>

Value: Boolean. Default: C<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 C<REMOTE_USER>
environment variable. See L<Dancer::Deployment/Running from Apache> for
further details.

=head3 C<trust_x_remote_user>

Value: Boolean. Default: C<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 C<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

When running securely (https), replace C<< "%{REMOTE_USER}e" >> with C<<
"%{REMOTE_USER}s" >>.

=head3 C<validate_remote_user>

Value: Boolean. Default: C<false>.

Enable this to check that remote users (usernames that come from a frontend
proxy server) also exist in the Netdisco Users database. No password check is
made.

This can be useful when you have web login or single sign-on on the frontend
web server, but also want to limit to a set of known users in Netdisco. You
can still load those users into the database in Netdisco and enable this
setting to check any proxied access can be mapped to a known user.

=head3 C<ldap>

Value: Settings Tree. Default: None.

If set, and a user has the C<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: 0

There are several options within this setting:

=head4 C<servers>

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

=head4 C<user_string>

String to construct the user portion of the DN. C<%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 C<MYDOMAIN\%USER%> and skip all other
options except C<servers>, as this notation eliminates the need to construct
the full distinguished name.

Examples: C<cn=%USER%> or C<uid=%USER%>.

=head4 C<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
C<user_string> to construct the distinguished name for authentication.

=head4 C<proxy_user>

User to bind with to perform searches. If defined as C<anonymous>, then
anonymous binds will be performed and C<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.

=head4 C<proxy_pass>

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

=head4 C<opts>

Dictionary 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.

=head4 C<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 L<Net::LDAP> documentation under
start_tls for options, but the defaults should work in most cases.

=head3 C<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. C</netdisco2>.
As an alternative you can use the C<--path> option to C<netdisco-web>.

=head3 C<web_plugins>

Value: List of Modules. Default: List of bundled L<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 C<extra_web_plugins>, which allows the Netdisco
developers to update default C<web_plugins> in a future release.

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

=head3 C<extra_web_plugins>

Value: List of Modules. Default: Empty List.

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

=head3 C<reports>

Value: List of Reports dictionaries. Default: None.

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

 reports:
   - tag: power_inventory
     label: 'Power Supply Inventory'
     category: Device
     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 C<tag> of each item in the C<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 C<reports> key into the "C<site_plugins>" directory
of Netdisco's home area. The script can access C<$config> for its
configuration and C<@data> for the retrieved data. It should return a list of
munged data.

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

=head4 C<tag>

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

=head4 C<label>

Title for the Report.

=head4 C<columns>

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

=head4 C<query>

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

=head4 C<category> (optional)

Section of the Reports menu where this report will appear. See
L<WritingWebPlugins|App::Netdisco::Manual::WritingWebPlugins> for the full list.
If not supplied, reports appear in a I<My Reports> category.

=head4 C<hidden> (optional)

Set to true to skip inclusion of this report from the Reports menu.

=head4 C<database> (optional)

The database "tag" used in C<external_databases> so that you can query another
database (even in another database server) and display the results in a
Netdisco report.

=head4 C<query_columns> (optional)

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

=head4 C<bind_params> (optional)

You can use placeholders in the SQL C<query> (that is, "C<?>") 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

=head3 C<jobqueue_refresh>

Value: Integer Number. Default: 5.

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

=head3 C<safe_password_store>

Value: Boolean. Default: true.

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

=head3 C<table_pagesize>

Value: Number. Default: 10.

The default number of rows in a table page.

=head3 C<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 "C<-1>" means Show All
Records.

=head3 C<vlanctl>

Value: Boolean. Default: C<true>.

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

=head3 C<portctl_nameonly>

Value: Boolean. Default: C<false>.

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

=head3 C<portctl_nophones>

Value: Boolean. Default: C<false>.

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

=head3 C<portctl_vlans>

Value: Boolean. Default: C<false>.

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

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

=head3 C<portctl_uplinks>

Value: Boolean. Default: C<false>.

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

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

=head3 C<port_control_reasons>

Value: Dictionary 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.

=head3 C<check_userlog>

Value: Boolean. Default: C<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.

=head3 C<devport_vlan_limit>

Value: Number. Default: C<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 I<not> shown (regardless of Display Columns setting.

=head3 C<login_logo>

Value: String. Default: none.

Set to the URL of an image file which will be displayed alongside the C<Log
In> form.

=head2 Netdisco Core

=head3 C<host_groups>

Value: Dictionary of Access Control Lists. Default: None.

Several configuration settings in Netdisco make use of L</"ACCESS CONTROL
LISTS"> to identify lists of devices or hosts. Examples are the C<*_no>
settings such as C<discover_no>, the C<*_only> settings such as C<macsuck_no>,
and some "C<only>" settings which appear in C<device_auth> and C<dns>
configuration.

The C<host_groups> setting allows for naming of groups which are then
referenced in settings or even within other groups, to include the values.
Each item in the dictionary has the name of the group for the key, and the ACL
for its value. Note that ACLs may be single items, or lists. For example:

 host_groups:
   problem_switches: badhost.example.com
   friendly_devices:
     - 192.0.2.0/24
     - 'group:problem_switches'
 
 macsuck_no: 'group:problem_switches'
 discover_only:
   - 'group:friendly_devices'
   - '2001:db8::/32'

As you can see, a host group is referenced by prefixing its name with
"C<group:>" and enclosing in quotes (because the colon character is part of
YAML syntax too). Host groups may be used in any setting that mentions support
for L</"ACCESS CONTROL LISTS">.

=head3 C<device_identity>

Value: Dictionary of Access Control List mappings. Default: None.

This setting allows you to control the canonical name or identity of devices
in Netdisco. For example if Netdisco discovers devices and uses the "wrong"
interface to identfy them (thereby confusing users) you can correct that here.

The C<device_identity> setting is a dictionary where each key is an Access
Control List matching a device and the corresponding value is another Access
Control List matching one of the device's interfaces to use as the device
canonical identity. The format of Access Control Lists is described in
L</"ACCESS CONTROL LISTS">.

In general, because the key of a dictionary must be a simple text string, you
can use hostname, IP prefix, device properties, and group references to match
devices. Regular expressions and combinations of device attributes should be
placed in a C<host_groups> entry and referenced by name. For example:

 host_groups:
   backbone_devices:
     - 'op:and'
     - 'vendor:arista'
     - 'model:.*(?i:DCS7508).*'
 
 device_identity:
   'group:backbone_devices':
     - !!perl/regexp ^.*\.backbone\.example\.com$
     - '172.16.20.0/24'
   'vendor:cisco': '192.0.2.0/24'

During "discover" jobs, Netdisco will find all entries in C<device_identity>
where the I<key> matches the device in some way. For those entries, the
device's interface IPs are put in ascending order, and then tested in turn
against the entry's I<value>. If any interface matches, then the device is
renumbered to use that interface as its new identity and the process stops.

When using an Access Control List for the value (interface selection), as well
as the options described in L</"ACCESS CONTROL LISTS"> you can use
"C<port:regexp>" to match an interface's port name. For example to renumber
any device to the IP and host name of its Mgmt1 interface (if it has one), you
could use:

 device_identity:
   'any': 'port:(?i)mgmt1'

Once a device is renumbered, its new identity is "sticky". That is, you could
remove the C<device_identity> configuration and the next "discover" job will
not revert any device's identity.

Remember that all L</"ACCESS CONTROL LISTS"> have an implicit "OR" condition -
any of their entries matching will cause the whole list to match.  If you need
very specific matching on devices, use a host group of several properties
together with the "C<op:and>" modifier to require that all items in the list
match the device (as in the example above).

Note also that whatever interface you select as canonical for the device must
be reachable by SNMP. Interfaces where an SNMP connection fails are ignored.

The order in which Netdisco evaluates clauses in C<device_identity> is not
specified. If you need to control the sequence, pass a I<list> of single-key
dictionaries instead of one multi-key dictionary. The above example could then
become:

 device_identity:
   - 'group:backbone_devices':
       - !!perl/regexp ^.*\.backbone\.example\.com$
       - '172.16.20.0/24'
   - 'vendor:cisco': '192.0.2.0/24'

=head3 C<mibhome>

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

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

=head3 C<mibdirs>

Value: List of Directories. Default: All subdirectories of C<mibhome>.

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

 mibdirs:
   - rfc
   - cisco
   - foundry

=head3 C<community>

Value: List of Strings. Default: C<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 C<device_auth>, below.

=head3 C<community_rw>

Value: List of Strings. Default: C<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 C<device_auth>, below.

=head3 C<device_auth>

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

This setting configures authenticaiton for all polling, and provides an
alternative fine-grained control for SNMPv1 and SNMPv2 community strings. You
provide a list of authentication "I<stanza>", 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 devices, 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 when referring to the configuration.

 device_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: aclexample
     community: s3kr1t
     read: false
     write: true
     only:
       - 192.0.2.0/30
       - 172.20.10.0/24
     no: '172.20.10.1'

For SNMPv1 and SNMPv2, only the C<community> key is required.  Unlike the
global C<community>/C<community_rw> setting, this is not a list but a single
item. Therefore, to configure multiple community strings, have one stanza per
community, as in the examples above and below.

For any sanza you can add C<read> and/or C<write> booleans to control whether
it is used for get and/or set operations, and IP restrictions using C<only>
and C<no> (see L</"ACCESS CONTROL LISTS"> for what you can use here).

For SNMPv3 the C<tag> and C<user> keys are required. Providing an C<auth>
section enables the authentication security level, providing a C<priv> section
enables the message encryption security level. When configuring multiple
SNMPv3 stanza please use C<only> and/or C<no> ACLs for each, otherwise only
the first stanza is ever used (this is a limitation in the underlying L<SNMP>
library).

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 C<priv> without C<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 "C<vlan->" (i.e. C<vlan-1>, C<vlan-2>, etc). Add the C<context_prefix>
key to a stanza to override this default.

For other authentication mechanisms (HTTP, SSH, etc), C<tag> is also required.
Each transport will have different settings, but usually a C<username> and
C<password> are required, and optionally some other settings. See the
transport or driver documentation pages for further details. For example:

 device_auth:
   - tag: ye_olde_snmp
     community: public
   - tag: sshcollector
     only: 'group:sshcollectordevices'
     driver: cli
     method: arpnip_nodes
     username: foo
     password: bar
   - tag: netconf_devices
     only: 'vendor:juniper'
     driver: netconf
     username: oliver
     password: letmein

Netdisco caches both the successful SNMPv2 read and write community strings,
as well as the C<tag> names if available. This allows for faster operations
once a connection has previously been made to a device. Tags are recommended.

If you have SNMP connect failures, or notice that devices are not appearing in
Netdisco, take a look at the "SNMP Connect Failures" Admin Report, and also
the C<max_deferrals> setting, below.

Finally, a reminder that multiple SNMPv2 community strings need to be in
separate named stanza, as below. However for simple v2 configurations you can
revert to the "C<community>" setting, instead:

 device_auth:
   - tag: 'default_v2_readonly1'
     community: 'read1'
   - tag: 'default_v2_readonly2'
     community: 'read2'
  
 # or...
 community: ['read1', 'read2']

=head3 C<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
C<device_auth>.

The strings "C<%IP%>" and "C<%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 C<device_auth>,
C<community>, and C<community_rw> will be used instead.

=head3 C<bulkwalk_off>

Value: Boolean. Default C<false>.

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

=head3 C<bulkwalk_no>

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

IP addresses in the list will use C<GETNEXT> (and not C<BULKWALK>).  See
L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<bulkwalk_repeaters>

Value: Number. Default: 20.

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

=head3 C<nonincreasing>

Value: Boolean. Default: C<false>.

Setting this to C<true> prevents bulkwalk of device tables with
non-increasing OIDs throwing an error C<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.

=head3 C<snmpver>

Value: C<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.

=head3 C<snmpforce_v1>

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

Forces matching devices to use SNMPv1.

=head3 C<snmpforce_v2>

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

Forces matching devices to use SNMPv2c.

=head3 C<snmpforce_v3>

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

Forces matching devices to use SNMPv3.

=head3 C<snmptimeout>

Value: Number. Default: 1000000.

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

=head3 C<snmpretries>

Value: Number. Default: 2.

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

=head3 C<devices_no>

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

The value will be copied into C<discover_no>, C<macsuck_no>, C<arpnip_no>, and
C<nbtstat_no>, so is a shorthand way to restrict backend workers to avoid
these device targets. See L</"ACCESS CONTROL LISTS"> for what you can use
here.

=head3 C<devices_only>

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

The value will be copied into C<discover_only>, C<macsuck_only>,
C<arpnip_only>, and C<nbtstat_only>, so is a shorthand way to restrict backend
workers to only specified device targets. See L</"ACCESS CONTROL LISTS"> for
what you can use here.

=head3 C<discover_no>

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

IP addresses in the list will not be visited during device discovery.  See
L</"ACCESS CONTROL LISTS"> for what you can use here.


=head3 C<discover_only>

Value: Single item or 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. See L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<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'

=head3 C<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.

=head3 C<macsuck_no>

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

IP addresses in the list will not be visited for macsuck. See L</"ACCESS
CONTROL LISTS"> for what you can use here.

=head3 C<macsuck_only>

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

If present, macsuck will be limited to IP addresses matching entries in this
list.  See L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<macsuck_all_vlans>

Value: Boolean. Default: C<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.

=head3 C<macsuck_no_unnamed>

Value: Boolean. Default: C<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.

=head3 C<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.

=head3 C<macsuck_no_devicevlan>

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

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

=head3 C<macsuck_unsupported>

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

Similar to C<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.
See L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<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
C<macscuk_unsupported> setting. For example:

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

=head3 C<macsuck_bleed>

Value: Boolean. Default: C<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.

=head3 C<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.

=head3 C<arpnip_no>

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

IP addresses in the list will not be visited for arpnip.  See L</"ACCESS
CONTROL LISTS"> for what you can use here.

=head3 C<arpnip_only>

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

If present, arpnip will be limited to IP addresses matching entries in this
list.  See L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<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.

=head3 C<nbtstat_no>

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

IP addresses in the list will not be visited for nbtstat.  See L</"ACCESS
CONTROL LISTS"> for what you can use here.

=head3 C<nbtstat_only>

Value: Single item or list of Network Identifiers. Default: Empty List.

If present, nbtstat will be limited to IP addresses matching entries in this
list.  See L</"ACCESS CONTROL LISTS"> for what you can use here.

=head3 C<nbtstat_max_age>

Value: Number. Default: 7.

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

=head3 C<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.

=head3 C<nbtstat_timeout>

Value: Number. Default: 1.

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

=head3 C<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
"C<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.

=head3 C<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.

=head3 C<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.

=head3 C<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.

=head3 C<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).

=head3 C<dns>

Value: Settings Tree. Default:

 dns:
   max_outstanding: 50
   hosts_file: '/etc/hosts'
   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.

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

Similarly, the location of the Hosts file can be overridden in this config, or
using the C<PERL_ANYEVENT_HOSTS> environment variable.

C<no> is a single item or list of IP addresses or CIDR ranges to excluded from
DNS resolution (see L</"ACCESS CONTROL LISTS">). Link local addresses are
excluded as in the defaults shown above.

=head3 C<store_wireless_clients>

Value: Boolean. Default: C<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.

=head3 C<store_modules>

Value: Boolean. Default: C<true>.

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

=head3 C<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.

=head3 C<ignore_private_nets>

Value: Boolean. Default: C<false>.

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

=head3 C<reverse_sysname>

Value: Boolean. Default: C<false>.

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

=head3 C<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

=head3 C<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

=head3 C<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

=head3 C<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

=head2 Backend Daemon

=head3 C<workers>

Value: Settings Tree. Default:

 workers:
   tasks: 'AUTO * 2'
   sleep_time: 1
   min_runtime: 0
   max_deferrals: 10
   retry_after: '7 days'

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

C<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.

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

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

C<min_runtime> allows you to set a time that each worker will sleep before
recycling and starting another job. Some users report this needs to be set
to avoid a 'runaway worker' bug. It can take a fractional number of seconds.

C<max_deferrals> is the number of times an SNMP connect failure can occur
before the device is no longer polled. The setting and counters are local to
each poller backend. To reset device counters, restart the backend daemon. To
disable this feature configure the setting with a value of zero.

C<retry_after> is the time when each job is retried once, even when
permanently deferred. The default is each job retried once per week.

=head3 C<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 C<workers>. It's
okay to have this node schedule schedule but not do any of the polling
itself (C<tasks: 0>).

Work can be scheduled using C<cron> style notation, or a simple weekday and
hour fields (which accept same types as C<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 "C<when>" fields default to "all" (i.e. "C<*>") when not
specified. See L<Algorithm::Cron> for further details.

=head2 Dancer Internal

=head3 C<charset>

Value: String. Default: C<UTF-8>.

See L<Dancer::Config/"charset-string">.

=head3 C<warnings>

Value: Boolean. Default: C<false>.

Should warnings be considered as critical errors?

=head3 C<show_errors>

Value: Boolean. Default: C<false>.

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

=head3 C<logger>

Value: C<console|file>. Default: C<console>.

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

=head3 C<engines>

Value: Settings Tree.

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

=head3 C<layout>

Value: String. Default: C<main>.

Don't touch this.

=head3 C<plugins>

Value: Settings Tree.

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

=head3 C<session>

Value: String. Default: C<cookie>.

How to handle web sessions. Default is to store in an encrypted cookie
using a key stored in the database by C<netdisco-deploy>.

=head3 C<template>

Value: String. Default: C<template_toolkit>.

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

=head3 C<route_cache>

Value: Boolean. Default: C<true>.

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

=head3 C<appname>

Value: String. Default: C<Netdisco>.

Don't touch this.

=head3 C<behind_proxy>

Value: Boolean. Default: C<false>.

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

=head1 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.

=over 4

=item *

C<phone_ouis>

=item *

C<wap_ouis>

=item *

C<col_xxx_show>

=item *

C<macsuck_timeout>

=item *

C<port_info>

=item *

C<portctl_timeout>

=item *

C<timeout>

=back

=cut