netdisco/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.

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.

=head2 GUIDANCE

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

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:

=over 4

=item *

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

=item *

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

=item *

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

=item *

String - Quoted, just like in Perl (and essential if the item contains the
colon character)

=back

=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] %L @%D> %m' >>.

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

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

=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. You I<must> install the
L<Net::LDAP> Perl module in order to use this feature. For example:

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

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>

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.

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

=head2 Netdisco Core

=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. The working
community will be cached in the database.

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

=head3 C<snmpver>

Value: C<1|2|3>. Default: 2.

Version of the SNMP protocol used when connecting to devices.

=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<discover_no>

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

IP addresses in the list will not be visited during device discovery. You can
include hostnames, IP addresses and subnets (IPv4 or IPv6) in the list.

=head3 C<discover_only>

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

If present, device discovery will be limited to IP addresses matching entries
in this list. You can include hostnames, IP addresses and subnets (IPv4 and
IPv6).

=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. Default: Empty List.

IP addresses in the list will not be visited for macsuck. You can include
hostnames, IP addresses and subnets (IPv4 or IPv6) in the list.

=head3 C<macsuck_only>

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

If present, macsuck will be limited to IP addresses matching entries in this
list. You can include hostnames, IP addresses and subnets (IPv4 and IPv6).

=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_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. Default: Empty List.

IP addresses in the list will not be visited for arpnip. You can include
hostnames, IP addresses and subnets (IPv4 or IPv6) in the list.

=head3 C<arpnip_only>

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

If present, arpnip will be limited to IP addresses matching entries in this
list. You can include hostnames, IP addresses and subnets (IPv4 and IPv6).

=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<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<vlanctl>

Value: Boolean. Default: C<true>.

Set to false to prevent Netdisco from changing the default VLAN on an
interface.

=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<no_port_control>

Value: Boolean. Default: C<false>.

Set to true to disable globally support for Port Control. Mainly useful for
development to suppress web frontend job queue callbacks.

=head2 Backend Daemon

=head3 C<workers>

Value: Settings Tree. Default:

 workers:
   interactives: 2
   pollers: 5
   sleep_time: 2

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

C<interactives> and C<pollers> sets how many workers are started for
interactive jobs (port control) and polling jobs (discover, macsuck, arpnip)
on this node, respectively. Other nodes can have different settings.

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.

=head3 C<housekeeping>

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 Pollers configured in C<workers>. It's
okay to have this node schedule housekeeping but not do any of the polling
itself (C<pollers: 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:

 housekeeping:
   discoverall:
     when: '0 9 * * *'
   arpwalk:
     when:
       min: 30
   macwalk:
     when:
       min: 15
       hour: '*/2'
       wday: 'mon-fri'

Note that the 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<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).

=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<bulkwalk_no>

=item *

C<bulkwalk_off>

=item *

C<bulkwalk_repeaters>

=item *

C<col_xxx_show>

=item *

C<expire_devices>

=item *

C<expire_nodes>

=item *

C<expire_nodes_archive>

=item *

C<get_community>

=item *

C<macsuck_no_devicevlan>

=item *

C<macsuck_no_vlan>

=item *

C<macsuck_timeout>

=item *

C<nonincreasing>

=item *

C<port_info>

=item *

C<portctl_timeout>

=item *

C<snmpforce_v1>

=item *

C<snmpforce_v2>

=item *

C<snmpforce_v3>

=item *

C<timeout>

=item *

C<v3_user>

=item *

C<v3_users>

=item *

C<v3_users_rw>

=back

=cut