Oliver Gorwits > App-Netdisco-2.018000_001 > App::Netdisco::Manual::Configuration

Download:
App-Netdisco-2.018000_001.tar.gz

Annotate this POD

Website

View/Report Bugs
Source   Latest Release: App-Netdisco-2.028000

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:

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

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

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';

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. You must install the 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:

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.

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

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.

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 and subnets (IPv4 or IPv6) 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: Numnber. 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 will allow the bulkwalk of devices that have tables with non-increasing OIDs. The default is to not allow this behavior, to prevent discovery on problem devices from looping indefinitely. Requires Net-SNMP 5.3 or higher.

snmpver

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

Version of the SNMP protocol used when connecting to devices.

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 and subnets (IPv4 or IPv6) 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 and subnets (IPv4 and IPv6).

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 and subnets (IPv4 or IPv6) 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 and subnets (IPv4 and IPv6).

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

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.

macsucl_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_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 and subnets (IPv4 or IPv6) 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 and subnets (IPv4 and IPv6).

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.

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.

vlanctl

Value: Boolean. Default: true.

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

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.

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.

Backend Daemon

workers

Value: Settings Tree. Default:

 workers:
   interactives: 2
   pollers: 5
   sleep_time: 2

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

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

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

Sets the maximum number of outstanding requests for asynchronous DNS resolution used during arpnip and device alias discovery.

This setting overrides the PERL_ANYEVENT_MAX_OUTSTANDING_DNS environment value and the AnyEvent library default of 10.

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

 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. "*") 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.

syntax highlighting: