App::Netdisco::Manual::Configuration - How to Configure Netdisco
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.
There are two configuration files: config.yml (which lives inside Netdisco) and deployment.yml (which usually lives in ${HOME}/environments).
config.yml
deployment.yml
${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
1
0
true
false
List - Set of things using [a, b, c] on one line or - on separate lines
[a, b, c]
-
Dictionary - Key/Value pairs (like Perl Hash) using {key1: val1, key2, val2} on one line or key: value on separate lines
{key1: val1, key2, val2}
key: value
String - Quoted, just like in Perl (and essential if the item contains the colon character)
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 dsn (DB name, host, port), user and pass.
dsn
user
pass
log
Value: debug|warning|error. Default: warning.
debug|warning|error
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
Value: console|file. Default: file.
console|file
file
Destination for log messages. Console means standard ouput. When set to file, the default destination is the ${HOME}/logs directory.
${HOME}/logs
logger_format
Value: Format String. Default: '[%P] %L @%D> %m'.
'[%P] %L @%D> %m'
Structure of the log messages. See "logger_format" in Dancer::Logger::Abstract for details.
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:
guest
admin
port_control
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';
port
Value: Number. Default: 5000.
5000
Port which the web server listens on. Netdisco comes with a good pre-forking web server, so you can change this to 80 if you want to use it directly. However the default is designed to work well with servers such as Apache in reverse-proxy mode.
80
path
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.
/netdisco2
--path
netdisco-web
behind_proxy
A hint to the Netdisco web frontend that it's running behind a reverse proxy. In that case, Netdisco will pay attention to the X_FORWARDED_PROTOCOL, X_FORWARDED_HOST, etc settings in HTML headers.
X_FORWARDED_PROTOCOL
X_FORWARDED_HOST
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.
extra_web_plugins
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.
App::Netdisco::Web::Plugin::
+
X::
App::NetdiscoX::Web::Plugin::
Value: List of Modules. Default: Empty List.
List of additional App::Netdisco::Web::Plugin names to load. See also the web_plugins setting.
mibhome
Value: Directory. Default: ${HOME}/netdisco-mibs.
${HOME}/netdisco-mibs
Base directory in which to find mibdirs. This is where netdisco-deploy will drop MIB files.
mibdirs
netdisco-deploy
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:
rfc
mibdirs: - rfc - cisco - foundry
community
Value: List of Strings. Default: public.
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.
private
A list of read-write SNMP community strings to try on each device. The working community will be cached in the database.
snmpver
Value: 1|2|3. Default: 2.
1|2|3
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. 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.
discover_only
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).
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'
macsuck_all_vlans
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
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_bleed
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.
store_wireless_client
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.
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
Set to true to ignore device interfaces that are part of private nets (RFC 1918).
reverse_sysname
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.
sysName.0
vlanctl
Set to false to prevent Netdisco from changing the default VLAN on an interface.
portctl_nophones
Set to true to make sure an IP Phone port never can be turned off/on.
portctl_vlans
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
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.
no_port_control
Set to true to disable globally support for Port Control. Mainly useful for development to suppress web frontend job queue callbacks.
workers
Value: Settings Tree. Default:
workers: interactives: 2 pollers: 2 sleep_time: 5
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.
interactives
pollers
sleep_time is the number of seconds between polling the database to find new jobs. This is a balance between responsiveness and database load.
sleep_time
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).
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:
cron
housekeeping: discoverall: when: '0 9 * * *' arpwalk: when: min: 30 macwalk: when: hour: '*/2'
charset
Value: String. Default: UTF-8.
UTF-8
See "charset-string" in Dancer::Config.
warnings
Should warnings be considered as critical errors?
show_errors
Whether to show a stack trace when an error is caught in the web frontend.
engines
Value: Settings Tree.
Useful for overriding the Template Toolkit settings, if you want.
layout
Value: String. Default: main.
main
Don't touch this.
plugins
Useful for overriding the Database configuration, but only if you know what you're doing.
session
Value: String. Default: YAML.
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.
template_toolkit
Which engine to use for templating in the web frontend. Don't touch this.
route_cache
Whether to build a route cache for web requests, for better performance.
appname
Value: String. Default: Netdisco.
Netdisco
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.
arpnip_min_age
arpnip_no
arpnip_only
bulkwalk_no
bulkwalk_off
bulkwalk_repeaters
col_xxx_show
discover_min_age
expire_devices
expire_nodes
expire_nodes_archive
get_community
macsuck_min_age
macsuck_no
macsuck_no_devicevlan
macsuck_no_vlan
macsuck_only
macsuck_timeout
nonincreasing
port_info
portctl_timeout
portcontrol
snmpforce_v1
snmpforce_v2
snmpforce_v3
store_modules
timeout
v3_user
v3_users
v3_users_rw
web_console_models
web_console_vendors
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.