Configuration

Introduction
- YAML Guidance
  - Boolean
  - List
  - Dictionary
  - String
- Access Control Lists
Supported Settings
Unsupported

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: config.yml (which lives inside the Netdisco package) 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. Do keep in mind that lists will be overwritten.

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:

Boolean

True/False value, using 1 and 0 or true and false respectively, e.g.:

check_userlog: false

List

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

community: ['public', 'another']

discover_no:
  - 192.0.2.0/24
  - '2001:db8::/32'

‼️	Currently netdisco does not merge configuration items which are lists, instead it will overwrite them with the values you define.

This means that if you want to add an item to (for example) the ignore_interfaces list, you can’t just use the following (this will overwrite the already existing ignore_interfaces list).

ignore_interfaces:
  - 'dontcare'

Instead you should copy the current ignore_interfaces key to your local deployment.yml and add additional keys there. Regretfully this is not the best solution since changes to the config.yml in the netdisco distribution might not be picked up. It is on our radar to make this work. Check the issue tracker ticket and our wishlist for this.

Dictionary

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

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

String

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

log: 'debug'
expire_devices: 15

Access Control Lists

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

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

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

IP address range, using a hyphen on the last octet/hextet, and no whitespace:
```
- 192.0.2.1-10
```
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.*$
```
“property:regexp” to match against any device or device port property, such as model, vendor or port (for port name). Devices not yet discovered have only the ip field available. For example:
```
- 'vendor:cisco'
```
Regular expressions must match the complete value (begin/end anchors are enforced and do not need to be included).
“cf:fieldname:regexp” to match a custom field from the custom_fields setting. For example:
```
- 'cf:patch:33-[AB]-yy'
```
Regular expressions must match the complete value (begin/end anchors are enforced and do not need to be included).
“tag:tagname” to match a tag from the tags setting. The match is exact and case sensitive.
“group:groupname” to reference the “groupname” group from the host_groups setting. This is a way to either include ACLs in other ACLs, or re-use ACLs.
“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).

To negate any item in an ACL (except YAML regexp), prefix with “!”, for example “!192.0.2.0/29”. In that case the test will be that the ACL entry does 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 “op:and” in the ACL if appropriate.

To match any device, use the special “group:__ANY__”. To match no devices use “!group:__ANY__”. To match only IPv4 addresses use “0.0.0.0/0”, and for IPv6 addresses “::/0”.

It should be clear from settings documentation whether you’re matching a Device or a Device Port. Hostnames, IP addresses, address ranges, and DNS name regexp will do the right thing: matching the device canonical IP or the Layer 3 interface IP depending on context. If you wish to be explicit, the property for a device ip is ip and the property for a Layer 3 interface address is alias.

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

devices_no: 'group:router_loopbacks'

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.

database:
  name: 'netdisco'
  user: 'changeme'
  pass: 'changeme'
  #host: 'localhost'
  #displayname: 'Backbone'

`name`

Value: String. Default: netdisco

name of the database you want netdisco to connect to.

`user`

Value: String. Default: changeme

username used to connect to the database. see host for caveats.

`pass`

Value: String. Default: changeme

password used to connect to the database. see host for caveats.

`host`

Value: String. Default: empty

With default settings in pg_hba.conf the following will apply:

when not filled out netdisco will use peer type authentication
when set to localhost or 127.0.0.1 netdisco will use ident type authentication
when set to a hostname or ip netdisco will use password authentication

💡	if you wish to use different usernames for running netdisco & connecting to the database it’s best to set `host` to a hostname or ip address. see DBD::Pg for details.

💡	the host field can also contain other attributes that can go into a Postgres connection string, e.g. to connect on a custom port to the first writeable replica in a cluster: `host: 'pg1.example.org,pg2.example.org;port=5433;target_session_attrs=read-write'`

`displayname`

Value: String. Default: "Default"

This optional field is used if you also configure tenant_databases and provides a name for the default database (also the one used for authentication).

General Settings

`log`

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

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

`logger_format`

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

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

`include_paths`

Value: List. Default: Empty List.

Additional library paths for the application (both web frontend and backend poller daemons). You can also use a colon-separated list in the “NETDISCO_INC” environment variable which makes code available even earlier in the app startup sequence.

`template_paths`

Value: List. Default: Empty List.

Additional paths for 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 “views” subdirectory created.

`site_local_files`

Value: Boolean. Default: false.

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

`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 tag is required and maps to the database key if you use the Generic Reports feature (see "reports", below), or becomes the Dancer database schema name if you program the Plugin directly.

`tenant_databases`

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

This setting enables a single Netdisco web frontend to connect to multiple databases. For example, if you have network zones and separate pollers and databases for each zone, or you have tenant Netdisco installations each with their own databases, you can use one web frontend to query them all.

Obviously, each database must be a complete and up to date deployment of Netdisco’s own schema, created using netdisco-deploy.

Enabling the setting adds a menu at the right of the Netdisco web titlebar (next to the username) which can be used to switch tenancy. For example:

tenant_databases:
  - tag: offices
    displayname: Offices
    name: offices_db
    host: 192.0.2.1
    user: oliver
    pass: letmein
  - tag: datacenter
    displayname: 'Data Center'

The two required fields are tag which is used in URL paths, and displayname which is used in the web interface to refer to the tenancy.

The other fields (name, host, user, pass) are exactly as you have used in the main database configuration. If you omit name then the tag is used as the database name (as in the example above).

Netdisco MUST still have the main database configuration set, which is used for your web interface login. This "tenant" will also appear in the list, and is named “Default” or you can use the displayname field under database setting to have something else.

The Netdisco API will also work with tenants and you can query the data at any tenant. However, all Authentication happens against your Default tenant and all and API keys also come from your Default tenant, as configured in database settings.

You can browse the Swagger interface for a tenant by following the link in the user menu (when viewing any tenant). API endpoints for tenants are prefixed with /t/tenantname as in the example below:

https://localhost:5000/t/demo/api/v1/search/device?q= ...

`custom_fields`

Value: List of setting dictionaries under the device and device_port keys. Default: None.

Activates custom fields (or attributes) on Devices or Device Ports in which you can store arbitrary data (text format). You do NOT have to make any changes to the database schema for this, it is automatically managed.

Configuration is a list of field settings for either Device or Device Ports. For example:

custom_fields:
  device:
    - name: 'displayname'
      label: 'Friendly Name'
      editable: true
    - name: 'warranty'
      hidden: true
  device_port:
    - name: 'patch'
      editable: true
      default: 'checked'
      position: 'left'

The name setting is required and is the name of the custom field in the database as well as being used internally to Netdisco for the web field. Try to limit this to characters which are compatible with database identifiers.

The label setting is what you will see in the web interface. If not given, it defaults to the name field with the first letter(s) capitalised.

The editable setting enables live edit and save in the web interface (works similar to Device Location, Contact, and Port Name fields). The user needs the "port control" role to allow this. On hitting "Enter" the changed field is immediately updated in the database.

The hidden setting will hide the field in the web interface (Device Details or Ports tab).

Specifically for Device Port fields, you can add a default setting (boolean) for whether the column is included in defaults ("checked") or not, and a position setting for where in the set of columns it should go: "left", "mid" or "right".

When a device is re-discovered (usually once a day), any custom fields which are no longer referenced in this configuration setting will be removed.

Users with Port Control or Admin rights can also update custom fields through the API (see API documentation for an example.

Custom fields can be matched in Access Control Lists using a cf:fieldname:value rule.

`tags`

Value: List of ACL mappings under the device and device_port keys. Default: None.

Assigns textual tags to Devices or Device Ports. Tags are shown in the web interface and returned in API calls as an array type on devices and ports.

Configuration is a mapping of tag name to Access Control List (matching either the Device only or Device Ports). For example:

tags:
  device:
    'BACKUP': 'group:backup_these_devices'
  device_port:
    'NO MONITOR 👀🚫':
      'group:monitored_devices': 'port:TenGigabitEthernet1/0/[12]'

In the above example, the group of devices matching the backup_these_devices ACL will be assigned the “BACKUP” tag. The ports TenGigabitEthernet1/0/1 and TenGigabitEthernet1/0/2 on devices matching the monitored_devices ACL will be assigned the “NO MONITOR 👀🚫” tag.

Devices and Device Ports can have more than one tag assigned. Tags are refreshed to match configuration on each re-discovery (so, once per day).

Tags can be matched in Access Control Lists using a tag:tagname rule.

Web Frontend

`domain_suffix`

Value: List of Strings or Regular Expressions. Default: None.

Set this to your local site’s domain name(s). These are usually removed from node names in the web interface to make things more readable. Make sure to include the leading dot character! For example:

domain_suffix:
  - '.test'
  - '.example'
  - !!perl/regexp '\.(?:test|example)'

Note that the regular expressions must be compatible with the limited syntax supported by PostgreSQL Advanced Regular Expressions (which is similar to Perl but not exactly the same).

`no_auth`

Value: Boolean. Default: false.

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

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

`navbar_autocomplete`

Value: Boolean. Default: true.

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

`external_links`

Value: Fixed key dictionary of lists of configuration stanza. Default: None.

Easily create hyperlinks to external web sites from Node Search results (MAC or IP), Device Details tab, or Device Ports tab. Links will dynamically include the relevant device or node IP or MAC address. No coding is required.

For example:

external_links:
  node:
    - url: 'https://my.wifi.manager.example.com/search?node=[% node %]'
      displayname: 'WiFi Manager'
      for_mac: true       # either this, or `for_ip`, are required
      mac_format: 'Cisco' # optional
    - url: 'https://my.ddi.example.com/search?host=[% node %]'
      displayname: 'DNS Manager'
      for_ip: true
  device:
    - url: 'https://my.dcim.example.com/search?host=[% device %]'
      displayname: 'DCIM System'
  device_port:
    - url: 'https://my.monitoring.example.com/search?host=[% device %]&port=[% port %]'
      displayname: 'Traffic Monitoring System'

For each entry in the configuration Netdisco will add a hyperlink on the Node search results page, or the Device Details tab, or a Device Port row.

Each link has a required url field which is a template that includes the node or device and/or port. The link text shown on the page is the displayname field.

For Node search results, you can create links for MAC addresses by specifying for_mac: true, and then the [% node %] substitution in your link is the MAC address. Similarly you can create links for IP addresses (v4 and v6) by specifying for_ip: true and then [% node %] is the IP address. If you wish you can specify both.

Also for Nodes, you can set mac_format to one of 'IEEE', 'Cisco', 'Microsoft', or 'Sun'. The default is 'IEEE' format (like aa:bb:cc:11:22:33).

For Device hyperlinks, the following preset fields are available:

device - canonical IP address
fqdn - DNS resolution of the canonical IP
sysname - device SNMP System Name
mac - device MAC address
serial - device serial number
hostname - the fqdn without its domain_suffix
Any Device Custom Field prefixed by cf_

For Device Port hyperlinks, the following preset fields are available:

device - device canonical IP address
fqdn - DNS resolution of the device canonical IP
sysname - device SNMP System Name
hostname - the fqdn without its domain_suffix
port - port name
mac - port’s MAC address
ifindex - port’s SNMP Interface Index
Any Device Port Custom Field prefixed by cf_

Actually, you can use any other variable which the web templates have access. Explore and take a look (for example the Device Details tab template). Note that the preset fields listed above are automatically escaped for including in a URL.

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

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

`validate_remote_user`

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

`tacacs`

Value: Settings Tree or List. Default: None.

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

tacacs:
  server: 'server.example.com'
  key: 'letmein'

You can also supply the port and timeout keys to override the defaults.

To specify multiple TACACS+ servers for high availability, pass a list of server and key tuples, like so:

tacacs:
  - { server: 'server1.example.com', key: 'letmein1' }
  - { server: 'server2.example.com', key: 'letmein2' }

`radius`

Value: Settings Tree. Default: None.

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

radius:
  server: 'server.example.com'
  secret: 'letmein'

To specify multiple RADIUS servers for high availability, pass a list of hosts to the server key instead:

radius:
  server: ['server1.example.com', 'server2.example.com']
  secret: 'letmein'

Optionally, you can provide a timeout value and Vendor Specific Attributes (VSAs):

radius:
  server: ['server1.example.com', 'server2.example.com']
  secret: 'letmein'
  timeout: 30
  vsa:
    - name: Class
      value: Netdisco
    - name: 101
      value: Netdisco
      type: string
      vendor: 123

The default timeout is 15 seconds. VSA support allows for the attributes name, type, value, vendor and tag, and none are required.

`ldap`

Value: Settings Tree. Default: None.

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

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

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.

Depending on your Operating System various other formats of user_string may be needed. For example CentOS 7.x works with %USER%@DOMAIN and CentOS or RHEL 8.x with DOMAIN\%USER%.

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`

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.

`tls_opts`

A hash which, when defined, causes the connection to 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_home`

Value: String. Default: '/inventory'.

After login, the page to which users will be sent. You could change this to be '/', for example.

`web_plugins`

Value: List of Modules. Default: List of bundled plugin names.

Netdisco’s plugin system allows you to alter, add, or remove, components of the web user interface. Plugins can be distributed independently from Netdisco and are an alternative to source code patches. This setting is the list of Plugins which are used in the default Netdisco distribution.

💡	See the Web Plugins documentation for how to write and install web UI components.

If you only want to add to the default list then use the extra_web_plugins setting, below, which allows the Netdisco developers to update default web_plugins in a future release.

Any change should go into your local deployment.yml configuration file. If you want to view the default settings, see the share/config.yml file in the App::Netdisco distribution.

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

`extra_web_plugins`

Value: List of Modules. Default: Empty List.

This setting is used if you want to add new plugins but not change the set enabled by default. If you wish to change the built-in default plugins set, then create a version of web_plugins instead.

💡	See the Web Plugins documentation for how to write and install web UI components.

The order of the entries is significant. Unsurprisingly, the modules are loaded in order. Therefore Navigation Bar items appear in the order listed, and Tabs appear on the Search and Device pages in the order listed, and so on.

Netdisco will prepend App::Netdisco::Web::Plugin:: to any entry in the list. For example, "Inventory" will load the App::Netdisco::Web::Plugin::Inventory module. Netdisco uses the standard Perl @INC path searching mechanism to load plugin modules. See the include_paths and site_local_files settings in order to modify @INC for loading local plugins.

If an entry in the list starts with a “+” (plus) sign then Netdisco attempts to load the module as-is, without prepending anything to the name. This allows you to have App::Netdisco web UI plugins in other namespaces.

For your own plugins, use the "Netdisco extension" namespace App::NetdiscoX. You can prefix module names with "X::", and Netdisco will prepend App::NetdiscoX::Web::Plugin:: to the entry. For example, X::Observium will load the App::NetdiscoX::Web::Plugin::Observium module.

`sidebar_defaults`

Value: Settings Tree. Default: here in the source tree.

This setting is used internally by Netdisco to build web interface sidebar layouts. You could use this to change a default, which is quite simply done by overriding any key, for example:

sidebar_defaults:
  search_node:
    mac_format:
      default: Microsoft
  device_ports:
      p_vlan_names: { default: checked }
      p_hide1002:   { default: checked }
  device_netmap:
    too_many_devices:
      default: 2500

Note that not all sidebar fields are specified in sidebar_defaults, and if one is missing you’d like to see, please contact the Netdisco developers.

`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', _searchable: true}
      - {ps1_type: 'PS1 Type'}
      - {ps1_status: 'PS1 Status'}
    query: |
      SELECT d.name, d.ps1_type, d.ps1_status
        FROM device d
      ORDER BY name

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

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

If any column content contains an IPv4, IPv6, or MAC address, you can ask Netdisco to add search hyperlinks on the results.

If any column content is an SQL Array type, Netdisco will split it over multiple lines when displaying in the web.

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

`tag`

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

`label`

Title for the Report.

`columns`

List of single-key dictionaries which map database column (field) name to table heading. Optionally add a “_searchable” key with true value to the dictionary (as in the example above) to request a hyperlink to Netdisco’s global search on any IPv4, IPv6, or MAC address in the table cell.

`query`

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

If you want to display a Device name but don’t know if it has a DNS entry, try this COALESCE trick:

query: |
  SELECT ip, COALESCE(NULLIF(dns,''), NULLIF(name,''), '(none)') AS devname
   FROM ...

`category` (optional)

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

`hidden` (optional)

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

`database` (optional)

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

`query_columns` (optional)

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

`bind_params` (optional)

You can use placeholders in the SQL query (that is, “?”) to bind user-supplied parameters. This setting should be the names of the URL query string parameters, given in the same order as the bind params of the SQL. For example:

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

# would enable:
# http://localhost:5000/report/my_report?device=192.0.2.1&port=Vlan142

However, the URL parameter name does not need to match the SQL field name.

Default values for bind parameters can be provided by using COALESCE in the query. For example:

query: |
  SELECT ... FROM ...
  WHERE creation > (LOCALTIMESTAMP - COALESCE(NULLIF(?,''), '2 months')::interval)
bind_params: ['since']

`show_sidebar` (optional)

Set to true, and when bind_params is in use, a sidebar will be shown in the web interface where users can submit values for the paramers. The fields are plain text boxes and do not validate data, so might result in (a safe) SQL failure.

`system_reports`

Value: List of Reports dictionaries. Default: Built-in reports.

This is Netdisco’s internal version of the reports setting. Do not touch.

`jobqueue_refresh`

Value: Integer Number. Default: 5.

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

`jobs_qdepth`

Value: Integer Number. Default: 50.

Number of rows returned in the Job Queue panel in the web interface.

`safe_password_store`

Value: Boolean. Default: true.

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

`table_pagesize`

Value: Number. Default: 10.

The default number of rows in a table page.

`table_showrecordsmenu`

Value: Number. Default:

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

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

`inventory_collapse_threshold`

Value: Number. Default: 0.

When there are more than this number of platforms or releases in the inventory, the collapsing feature is enabled so that long lists are collapsed down. If the value is zero (the default) then the feature is enabled. For example set to 5.

When enabled, there are two other settings, inventory_platforms_collapse_threshold and inventory_releases_collapse_threshold which control the number of platforms or releases respectively above which they are collapsed. They default to 5, each.

`portctl_by_role`

Value: Dictionary of role name to ACL mappings. Default: None.

Use this setting to limit which devices and ports a user is able to use "Port Control" features on (such as up/down status, change name, change vlan).

You can create a role name, and map that to an Access Control Lists which describes either a set of devices or a set of ports on one or more devices. Then in the User Management admin panel, a role can be assigned to a user.

The simplest forms are to use a set of devices either in a named ACL group or as a list, as below:

portctl_by_role:
  alldevicespermitted: 'group:__ANY__'
  somedevicesonly:
    - '192.0.2.1'
    - '192.0.2.2'

Alternatively you can specify a set of ports for one or more devices:

portctl_by_role:
  justthisport:
    '192.0.2.1': 'port:1/1/1'
  theseportsonalldevices:
    'group:__ANY__': 'port:GigabitEthernet[12]/0/(?:15|16)'
  setofports:
    'group:__ANY__':
      - 'port:1/1/1'
      - 'port:1/1/2'
    '192.0.2.1': 'port:GigabitEthernet[12]/0/(?:15|16)'

In the User Management admin panel, as well as "Off" and "Enabled (any port)", you’ll also see each role name (justthisport, etc) as options for the Port Control field.

After changing a user’s role, please ask them to refresh their browser fully so that the Netdisco web interface can take into account the new permissions.

This setting is the only port control ACL which can prevent a port description change (that is, it overrides portctl_nameonly).

Limitation: current implementation does not restrict by Port Control function (set up/down status, change name, change vlan, etc). All Port Control features are available to the user on the permitted device ports, within limits of the other port control settings.

`portctl_no`

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

Devices in the list will not allow port control actions (with the exception of changing the port name which is always allowed).

`portctl_only`

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

Only devices in the list will allow port control actions (with the exception of changing the port name which is always allowed).

`portctl_nameonly`

Value: Boolean. Default: false.

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

`portctl_native_vlan`

Value: Boolean. Default: true.

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

This setting was formerly named vlanctl.

`portctl_nowaps`

Value: Boolean. Default: false.

Set to true to make sure a wirelss AP port never can be turned off/on or its PoE status changed.

`portctl_nophones`

Value: Boolean. Default: false.

Set to true to make sure an IP Phone port never can be turned off/on or its PoE status changed.

`portctl_uplinks`

Value: Boolean. Default: false.

Set to true to allow Netdisco to be able to disable Uplinks.

Netdisco uses many heuristics to reveal uplinks, including looking for VLAN subinterfaces, ports tagging multiple VLANs, or ports with multipl MAC addresses connected.

🔥	Turning off uplinks will take out chunks of your network.

`portctl_topology`

Value: Boolean. Default: false.

Set to true to allow Port Control users to also update the Manual Topology connection for a Device Port.

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

`check_userlog`

Value: Boolean. Default: false.

Set to true to enable the periodic AJAX check for completed entries in the job queue for this user. Mainly useful for development to show noisy web frontend activity.

`devport_vlan_limit`

Value: Number. Default: 150.

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

This setting used to be called deviceport_vlan_membership_threshold.

`login_logo`

Value: String. Default: none.

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

`hide_deviceports`

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

This works very similarly to ignore_deviceports except that it simply hides them from the web interface Device Ports list, instead of ignoring them completely. The ports are still used for macsuck and show up in searches.

This setting can be used where some devices have a lot of interfaces which are potentially used but not in service at your site. You can hide the interfaces but change this configuration and show them when they become interesting. For example:

hide_deviceports:
  'vendor:juniper':
    - 'group:__LOOPBACK_WITH_NO_IP__'
    - 'port:.+\.0'
    - 'port:irb(?:\.\d+)?'
    - 'port:lsi(?:\.\d+)?'
    - 'port:vtep(?:\.\d+)?'
    - 'type:other'

There is a new tickbox in the Device Ports sidebar which controls hiding, and it defaults to "on" (hiding).

Netdisco Core

`host_groups`

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

Several configuration settings in Netdisco make use of Access Control Lists to identify lists of devices or hosts. Examples are the *_no settings such as discover_no, the *_only settings such as macsuck_no, and some “only” settings which appear in device_auth and dns configuration.

The 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 “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 Access Control Lists.

`host_group_displaynames`

Value: Dictionary of host group to alias name mappings. Default: None.

Some web frontend features of Netdisco can make use of predefined host groups that are configured with the host_groups setting (above). Use this setting to assign the groups friendly names which will be used in the web interface.

The dictionary maps from host group name to friendly alias. For example:

host_group_displaynames:
  backbone_switches: 'Backbone Core'
  backbone_distribution: 'Backbone Edge Routers'
  cpe_devices: 'Customer Premises'

A useful side effect of this configuration setting is that not all host groups configured in the host_groups setting are used by the web frontend. Only those given aliases in host_group_displaynames will be offered to the user.

`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 identify them (thereby confusing users) you can correct that here.

The 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 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 host group references to match devices. Regular expressions and combinations of device attributes should be placed in a 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 device_identity where the 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 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 Access Control Lists you can use “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 device_identity configuration and the next "discover" job will not revert any device’s identity.

Remember that all 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 “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 device_identity is not specified. If you need to control the sequence, pass a 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'

`mibhome`

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

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

`mibdirs`

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

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

mibdirs:
  - rfc
  - cisco
  - foundry

`community`

Value: List of Strings. Default: public.

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

community:
  - public
  - anotherstring
  - mycommunity

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

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

`community_rw`

Value: List of Strings. Default: private.

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

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

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

`device_auth`

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

This setting configures authentication for all polling, and provides an alternative fine-grained control for SNMPv1 and SNMPv2 community strings. You provide a list of authentication "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 IPv4 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'
  - tag: sshexample
    driver: cli
    platform: Linux
    only: 192.0.2.1
    username: oliver
    password: letmein
    ssh_master_opts:
        - "-o"
        - "StrictHostKeyChecking=no" # use at your own risk!

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

For any stanza you can add read and/or write booleans to control whether it is used for get and/or set operations, and IP restrictions using only and no (see Access Control Lists for what you can use here).

For SNMPv3 the tag and user keys are required. Providing an auth section enables the authentication security level, providing a priv section enables the message encryption security level. When configuring multiple SNMPv3 stanza please use only and/or no ACLs for each, otherwise only the first stanza is ever used (this is a limitation in the underlying 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 priv without auth. The supported methods on your system depend on the Net-SNMP package provided, either consult the manual for snmpcmd or check the SNMP::Info docs (todo netdisco/snmp-info#515). Cisco specific configuration can be found here.

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

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 max_deferrals setting, below.

SNMP is the default driver and does not need to be explicitly stated. For other mechanisms (HTTP API, CLI, etc), each transport will have different settings, but the driver key is required, and usually a username and password as well. See the transport or driver documentation pages for further details. An example for SSH collection is shown above.

The action key allows you to restrict credentials to certain actions or even stages of actions on the remote device, such as ARP table gathering (arpnip::nodes).

The platform key is specific to the "CLI" driver (SSH transport) and indicates the App::Netdisco::SSHCollector::Platform to use. Each platform might add additional configuration keys (for example the Linux platform allows specification of the location of the arp utility in arp_command).

For drivers other than SNMP, only one stanza will be tried, and it is a fatal error to have more than one stanza available for a target device. For SNMP, all stanzas will be tried until one succeeds, or Netdisco runs out of options.

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

This setting used to be called snmp_auth.

If you are looking for the sshcollector configuration, then please read the deprecation notice to find out how to migrate it to device_auth.

`get_credentials`

Value: String. Default none.

An external program to run to get the authentication credentials 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 device_auth.

The command must return output in one of the following forms:

community=<comma-separated list of readonly-communities>
setCommunity=<comma-separated list of write-communities>
{ a JSON encoding of one or more device_auth stanza dictionaries }

The strings “%IP%” and “%HOST%” in the command are replaced by the IP address and the hostname (or IP address if no hostname is known) of the system being contacted. The string “%MODE%” is replaced with "read" or "write" depending on what Netdisco is requesting to do at the time. For example:

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

If the credentials are not known for the given device, the command should return no output. Netdisco will continue to try other credentials configured in the device_auth part of deployment.yml.

This setting used to be called get_community.

`use_legacy_rancidexport`

Value: Boolean. Default false.

Since release 2.038034 the netdisco-rancid-export script has been deprecated and since release 2.042006 will exit silently with a success status if run. However should you wish it to continue to execute fully, then set this to true.

More details can be found here: https://metacpan.org/pod/App::Netdisco::Worker::Plugin::MakeRancidConf

`use_legacy_sshcollector`

Value: Boolean. Default false.

Since release 2.041000 the netdisco-sshcollector script has been deprecated and will exit silently with a success status if run. However should you wish it to continue to execute fully, then set this to true.

`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: Single item or list of Network Identifiers or Device Properties. Default: Empty List.

IP addresses in the list will use GETNEXT (and not BULKWALK). See Access Control Lists for what you can use here.

`bulkwalk_repeaters`

Value: Number. Default: 20.

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

`nonincreasing`

Value: Boolean. Default: false.

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

`snmpver`

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

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

`snmpforce_v1`

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

Forces matching devices to use SNMPv1.

`snmpforce_v2`

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

Forces matching devices to use SNMPv2c.

`snmpforce_v3`

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

Forces matching devices to use SNMPv3.

`snmptimeout`

Value: Number. Default: 3000000.

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.

`snmp_try_slow_connect`

Value: Boolean. Default: true.

Set this to false to avoid slow and repeated SNMP connection attempts.

For SNMP connections where there is no cached (known-working) configuration, Netdisco will try all available configurations. It will first try them with aggressive/fast snmptimeout and snmpretries and then try again but slower.

If your network is reliable and you expect a lot of failed discoveries (for example you’re attempting to discover a large IP prefix in one go), then you can set this to false and avoid backend workers being tied up with slow SNMP retries.

`snmp_remoteport`

Value: Map of UDP port number to list of Device Identifiers. Default: Empty Map.

Use this setting to override the UDP port used for SNMP connections to devices. The key is the port number, and the value is an Access Control Lists entry. For example:

snmp_remoteport:
  1161: 'any'

`snmp_field_protection`

Value: Dictionary of dictionaries of Network Identifiers or Device Properties.

If a database field is listed here and the discovered device matches the corresponding ACL, the protection is activated. This causes Netdisco to abort the discover job if the device returns an empty value for the field when it had previously returned something else.

The default configuration is to protect the Serial Number, like so:

snmp_field_protection:
  device:
    serial: ['group:__ANY__']

`net_snmp_options`

Value: Dictionary of configuration options to net-snmp’s SNMP::Session. Default: None.

Any entries in this setting will be added to the instantiation of the SNMP::Session instance for SNMP connections. Settings will override those provided by Netdisco. Enable debug at command line (netdisco-do -D) to see the options provided to SNMP::Session.

Unfortunately the most useful option, clientAddr, is only available at the net-snmp command line 😞.

`devices_no`

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

The value will be copied into discover_no, macsuck_no, arpnip_no, and nbtstat_no, so is a shorthand way to restrict backend workers to avoid these device targets. See Access Control Lists for what you can use here.

`devices_only`

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

The value will be copied into discover_only, macsuck_only, arpnip_only, and nbtstat_only, so is a shorthand way to restrict backend workers to only specified device targets. See Access Control Lists for what you can use here.

`<actionname>_timeout`

Value: number of seconds.

The named action will be aborted if it takes longer than this time. There is no default, meaning that the timeout setting (default 10 minutes) takes precedence. Set to zero to disable timeout for an action (job type).

`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 Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`discover_no_type`

Value: List of Strings. Default: Empty list.

Place regular expression patterns here to exclude the discovery of certain devices based on their advertised CDP/LLDP device type information.

See also the discover_phones and discover_waps settings if you want to suppress discovery of these types of devices more easily.

`discover_waps`

Value: Boolean. Default: True.

Tells Netdisco whether to allow discovery of devices which seem to be wireless access points, based on their advertised CDP/LLDP system information.

The specific strings to match are held (and may be changed) in the wap_capabilities and wap_platforms settings.

`discover_phones`

Value: Boolean. Default: False.

Tells Netdisco whether to allow discovery of devices which seem to be phones, based on their advertised CDP/LLDP system information.

The specific strings to match are held (and may be changed) in the phone_capabilities and phone_platforms settings.

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

`discover_neighbors`

Value: Boolean. Default: true.

Netdisco will create discover jobs for undiscovered neighbors. Set this to false to skip the operation.

`discover_routed_neighbors`

Value: Boolean. Default: true.

Netdisco will create discover jobs for the next-hop routers known for each routing protocol (BGP, OSPF, IS-IS, EIGRP). Set this to false to skip the operation.

`skip_neighbors`

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

IP addresses in the list will not have undiscovered neighbors added to the discovery queue. See Access Control Lists for what you can use here.

See also the discover_neighbors global setting.

`ignore_layers`

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

Devices matching the list will always have macsuck, arpnip and nbtstat jobs run, regardless of what capabilities they actually report in "Layers" (sysServices). See Access Control Lists for what you can use here.

`force_macsuck`

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

Devices matching the list will always have macsuck and nbtstat jobs run, regardless of what capabilities they actually report in "Layers" (sysServices). See Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`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 somehow interfering.

`macsuck_no_unnamed`

Value: Boolean. Default: false.

Set to true to skip macsucking 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:

macsuck_no_vlan:
  - 'SAM-vlan-appliance-management'
  - 'SAM-vlan-boot'
  - 'SAM-vlan-management'
  - 'fcoe-vsan-4048'
  - 'fddi-default'
  - 'fddinet-default'
  - 'token-ring-default'
  - 'trbrf-default'
  - 'trcrf-default'
  - 'trnet-default'

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

`macsuck_no_devicevlan`

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

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

`macsuck_no_deviceports`

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

This setting allows you to suppress macsuck on specific ports on specific devices. That is, nodes (laptops, workstations, printers, etc) on these ports will not be gathered, and hence unseen by Netdisco.

Note that when enabled for the first time, Nodes do not disappear from the web interface — they need to expire. Immediate expiry will be addressed in a future patch.

The 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 the device’s ports to avoid for macsuck. The format of the Access Control Lists is described in 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 host group references to match devices. Regular expressions and combinations of device attributes should be placed in a host_groups entry and referenced by name. For example:

host_groups:
  backbone_devices:
    - 'op:and'
    - 'vendor:arista'
    - 'model:.*(?i:DCS7508).*'

macsuck_no_deviceports:
  'group:backbone_devices':
    - 'type:other'
    - 'vlan:100'
  '192.0.2.1': 'port:(?i)TenGigabitEthernet.+'

During "macsuck" jobs, Netdisco will find all entries in macsuck_no_deviceports where the key matches the device in some way. For those entries, the device’s ports are tested in turn against the entry’s value. If any port matches, then the nodes on the port are ignored.

When using an Access Control List for the value (port selection), as well as the options described in Access Control Lists you can use any port or interface IP field in Netdisco, using “fieldname:regexp” to match.

Remember that all 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 “op:and” modifier to require that all items in the list match the device.

`macsuck_unsupported`

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

Similar to macsuck_no, in that it is a list of devices not to be visited for macsuck. However the difference is that instead of also skipping all the nodes on the device (and reporting "possible uplink"), nodes are allowed to gather on the upstream device port.

This is useful for devices which can be discovered by Netdisco but do not provide a MAC address table via SNMP. See Access Control Lists for what you can use here.

`macsuck_unsupported_type`

Value: List of Strings. Default: None.

A different approach to macsuck_unsupported. The macsuck job is not avoided, but still the nodes are allowed to gather on the upstream device port.

Place regular expression patterns here to skip macsuck of certain devices based on the CDP/LLDP device type information they advertise. For example:

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

`macsuck_bleed`

Value: Boolean. Default: false.

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

`macsuck_min_age`

Value: Number. Default: 0.

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

`force_arpnip`

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

Device matching the list will always have an arpnip job run, regardless of what capabilities they actually report in "Layers" (sysServices). See Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`arpnip_min_age`

Value: Number. Default: 0.

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

`nbtstat_no`

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

IP addresses in the list will not be visited for nbtstat. See Access Control Lists for what you can use here.

`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 Access Control Lists for what you can use here.

`nbtstat_max_age`

Value: Number. Default: 7.

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

`nbtstat_interval`

Value: Number. Default: 0.02.

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

`nbtstat_response_timeout`

Value: Number. Default: 1.

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

This setting used to be called nbtstat_timeout.

`node_freshness`

Value: Number of Minutes. Default: 0

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

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

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

`expire_devices`

Value: Number of Days. Default: 60

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

`expire_nodes`

Value: Number of Days. Default: 90

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

`expire_nodes_archive`

Value: Number of Days. Default: 60

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

`expire_nodeip_freshness`

Value: Number of Days. Default: same as expire_nodes or expire_nodes_archive.

Controls the behaviour of Netdisco when expiring IP-MAC entries (from the node_ip table). The default behaviour, as in Netdisco 1, is to remove these entries (when older than expire_nodes or expire_nodes_archive), even if the IP relates to a Node that is not going to be expired.

Alternatively, assign a number of days to this setting and these still-linked IP entries will be kept for that long. Set to zero to keep them indefinitely (that is, for as long as a Node remains which shares the MAC address).

Note that in situations where a Node cycles through many IP addresses in a short time, such as with wireless roaming or IPv6 Privacy Addressing, then setting to zero can massively inflate your Netdisco database.

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

`expire_userlog`

Value: Number of Days. Default: 365

Logs of user activity kept in the database table user_log older than this value will be deleted during the scheduled expiry process.

`dns`

Value: Settings Tree. Default:

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

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

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

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

no is a single item or list of IP addresses or CIDR ranges to excluded from DNS resolution (see Access Control Lists). Link local addresses are excluded as in the defaults shown above.

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

`skip_modules`

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

IP addresses in the list will not have chassis modules gathered (from Entity MIB) during device discovery. See Access Control Lists for what you can use here.

See also the store_modules global setting.

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

See also the skip_modules ACL for per-device control.

`ignore_deviceports`

Value: Dictionary of Access Control List mappings. Default:

host_groups:
  __IGNORE_INTERFACES__:
    - 'port:EOBC'
    - 'port:unrouted VLAN(?: \d+)?'
    - 'port:StackPort'
    - 'port:Control Plane Interface'
    - 'port:SPAN (S|R)P Interface'
    - 'port:StackSub-.*'
    - 'port:StackPort\d+'
    - 'port:netflow'
    - 'port:Vlan\d+-mpls layer'
    - 'port:BRI\S+-Bearer Channel'
    - 'port:BRI\S+-Physical'
    - 'port:BRI\S+-Signalling'
    - 'port:BRI\S+-Signaling'
    - 'port:Embedded-Service-Engine\d+\/\d+'
    - 'port:Virtual-Template\d+'
    - 'port:Virtual-Access\d+'
    - 'port:(E|T)\d \d\/\d\/\d'
    - 'port:InLoopback0'
    - 'port:NULL\d'
    - 'port:Register-Tunnel\d'
    - 'port:Blade-Aggregation\d'
    - 'port:M-GigabitEthernet\d\/\d\/\d'
    - 'port:Ethernet(?:-| )QOS Packet Scheduler'
    - 'port:Ethernet(?:-| )WFP (?:802\.3|Native) MAC Layer Lightweight Filter'
    - 'port:ii\d\/\d\/\d+'
  __IGNORE_INTERFACE_TYPES__: []
  __NOTPRESENT_TYPES__:
    - 'type:ethernetCsmacd'
    - 'type:tunnel'
    - 'type:ieee8023adLag'
  __IGNORE_NOTPRESENT_TYPES__:
    - 'op:and'
    - 'up:notPresent'
    - 'group:__NOTPRESENT_TYPES__'
ignore_deviceports:
  'group:__ANY__':
    - 'group:__IGNORE_INTERFACES__'
    - 'group:__IGNORE_INTERFACE_TYPES__'
    - 'group:__IGNORE_NOTPRESENT_TYPES__'
  'vendor:juniper':
    - 'subnet:128\.0\.0\.0/2'
    - 'port:.+\.1638\d'
    - 'port:.+\.3276\d'

This setting allows you to ignore on specific ports on specific devices. That is, these ports will never show up in Netdisco. For a more gentle approach see also the hide_deviceports setting.

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

The 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 the device’s ports to ignore. The format of the Access Control Lists is described in 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 host group references to match devices. Regular expressions and combinations of device attributes should be placed in a host_groups entry and referenced by name.

During "discover" jobs, Netdisco will find all entries in ignore_deviceports where the key matches the device in some way. For those entries, the device’s ports are tested in turn against the entry’s value. If any port matches, then the nodes on the port are ignored.

When using an Access Control List for the value (port selection), as well as the options described in Access Control Lists you can use any port or interface IP field in Netdisco, using “fieldname:regexp” to match. This allows you to ignore layer 3 interfaces as well as layer 2 ports.

Remember that all 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 “op:and” modifier to require that all items in the list match the device.

`ignore_interfaces`

Value: List of Strings. Default: see ignore_deviceports.

If you apply configuration here, it will replace the default IGNORE_INTERFACES host group as shown in ignore_deviceports.

`ignore_interface_types`

Value: List of Strings. Default: None, see ignore_deviceports.

Perhaps not that useful in practice, as it would apply globally to all devices.

If you apply configuration here, it will replace the default IGNORE_INTERFACE_TYPES host group as shown in ignore_deviceports.

`ignore_notpresent_types`

Value: List of Strings. Default: see ignore_deviceports.

Some devices have interfaces which have status notPresent, instead of the normal Up or Down. Since these interfaces are not actually present in the device they can be ignored. If an interface has status notPresent and its interface type also fully matches with any type in this setting, then the interface will be ignored by the discovery process.

This behaviour has currently only been seen on CiscoSB devices.

If you apply configuration here, it will replace the default NOTPRESENT_TYPES host group as shown in ignore_deviceports.

`ignore_private_nets`

Value: Boolean. Default: false.

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

`reverse_sysname`

Value: Boolean. Default: false.

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

`phone_capabilities`

Value: List of Strings. Default:

phone_capabilities:
  - '(?i:phone)'

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

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

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

`phone_platforms`

Value: List of Strings. Default:

phone_platforms:
  - '(?i:phone)'
  - '(?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:

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

`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:

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

`wap_platforms`

Value: List of Strings. Default:

wap_platforms:
  - '(?i:\bwap\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:

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

Backend Daemon

`workers`

Value: Settings Tree. Default:

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

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

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

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

timeout is the maximum runtime of any action (job), after which it will be aborted (so the default is 10 minutes). Set to zero to disable such management. You can override the setting per action-type using the “<actionname>_timeout” setting, described above.

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

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.

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 disable this feature configure the setting with a value of zero. Restarting the backend poller or making a job request via the web or CLI will cause any job to be tried once again.

retry_after is the time when each job is retried once, even when permanently deferred. The default is each job retried once per week. To disable this feature (that is, never periodically retry) configure the setting with a value of zero.

`jobs_stale_after`

Value: Integer number of seconds. Default: 3000 (50 minutes).

This is the time after which jobs started will be considered stale by the backend manager process. It allows duplicate jobs to start to run, by assuming that the worker running the job crashed and for some reason the job was not cleaned up correctly.

`schedule`

Value: Settings Tree. Default:

schedule:
  discoverall:
    when: '5 7 * * *'
  arpwalk:
    when:
      min: 20
  macwalk:
    when:
      min: 50
  nbtwalk:
    when: '0 8,13,21 * * *'
  expire:
    when: '30 23 * * *'
  makerancidconf: null

This is the schedule for jobs in the backend daemon when it is running. The keys are any valid action name (see netdisco-do) and the values are an Algorithm::Cron specification. This means if you add your own actions through Backend Plugins, they can also be scheduled for periodic execution. Your own schedule configuration will merge with the default (as above), at the top level only.

You can run more than one scheduler for redundancy (on different servers), but make sure they all have good NTP. You can also run scheduler-only nodes (by having tasks: 0 within the workers setting), or worker-only nodes (by unsetting this configuration with schedule: null). You can disable any default schedule by assigning the value "null", for example:

schedule:
  nbtwalk: null

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

schedule:
  macwalk:
    when:
      min: 50
      hour: '*/2'
      wday: 'mon-fri'

Note that unspecified “when” fields default to "all" (i.e. “*”). See Algorithm::Cron for further details.

You can schedule the same action several times by using a different title, and adding the action key. This also allows selection of specific action stages. For example:

schedule:
  # standard schedule
  macwalk:
    when: '50 * * * *'
  # duplicate that action for increased frequency for a specific device
  macsuck_specific:
    action: macsuck
    when: '15,45 * * * *'
    device: '192.0.2.1'
  # run a specific stage of an action
  refresh_neighbors:
    action: 'discover::neighbors'
    when: '20 8,11,14,17 * * *'
  # provide additional arguments
  psql:
    when: '5 7 * * *'
    extra: 'COPY (SELECT COUNT (*) FROM user_log) TO STDOUT WITH CSV HEADER'

The netdisco-do parameters of device, port, and extra may be added to any scheduled action.

If an IP prefix (subnet) is given for the device field then it will be expanded to one job for each of the included IP addresses (ignoring what devices are known). A more efficient way of running a scheduled job on a range of devices is to use the "only/no" ACL config as shown below, which would target only known devices.

You can add Access Control Lists to limit a schedule to specific known devices. This uses the only and no fields as below, which can be added to any action or aliased action. However you should not use this with the "walk" actions (discoverall, macwalk, arpwalk), but directly on the action itself (i.e., discover, macsuck, arpnip).

schedule:
  # macsuck known devices in this IP prefix more frequently
  # which is more efficient than using `device` field with IP prefix
  macsuck_extra:
    action: macsuck
    when: '15,45 * * * *'
    only: '192.0.2.0/24'
  # following config is basically the equivalent of arpnip_no on this device
  arpwalk: null
  arpwalk_excluding_one:
    action: arpnip
    when: '20 * * * *'
    no: '192.0.2.1'

A couple of caveats with use of ACLs: First, it’s usually best to use the global "no" and "only" settings like discover_no (etc), and leave the default schedule alone. Second, if you run multiple backend poller servers which can access the same devices, you must keep any schedule config using ACLs synchronisd (i.e., the same) on these backends including any action alias names (otherwise the job runs for all devices and ignores the ACL).

This setting used to be called housekeeping. The expire action used to be called expiry.

`hooks`

Value: List of action configurations. Default: Empty List.

Hooks allow you to perform custom actions after some Events happen within Netdisco’s polling engine. For example you can call the web API of another management software after discovering a new Device.

See the Hooks documentation for hook event and type details. Some examples:

hooks:
  - type: 'http'
    event: 'new_device'
    with:
      url: 'https://dcim.example.com/api/v1/add/[% ip %]'

hooks:
  - type: 'http'
    event: 'new_device'
    with:
      url: 'https://netdisco:[email protected]/api/v1/add'
      custom_headers:
        Cookie: 'UUIDv4=55e564b0-c29d-4e5b-938f-112f018eb764'
      body: '{"ip": "[% ip %]"}'

`worker_plugins`

Value: List of Modules. Default: List of bundled plugin names.

Netdisco’s worker plugin system allows you to alter, add to, remove, or override, stages of the backend daemon’s activity. Plugins can be distributed independently from Netdisco and are an alternative to source code patches. This setting is the list of Plugins which are used in the default Netdisco distribution.

💡	See the Backend Plugins documentation for how to write and manage backend worker actions.

If you only want to add to the default list then use the extra_worker_plugins setting, below, which allows the Netdisco developers to update default worker_plugins in a future release.

Any change should go into your local deployment.yml configuration file. If you want to view the default settings, see the share/config.yml file in the App::Netdisco distribution.

Entries in the list will by default omit the leading App::Netdisco::Worker::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::Worker::Plugin:: namespace.

`extra_worker_plugins`

Value: List of Modules. Default: Empty List.

This setting is used if you want to add new plugins but not change the set enabled by default. If you wish to change the built-in default plugins set, then create a version of worker_plugins instead. The order of the entries is not significant.

💡	See the Backend Plugins documentation for how to write and manage backend worker actions.

Netdisco will prepend App::Netdisco::Worker::Plugin:: to any entry in the list. For example, Expire will load the App::Netdisco::Worker::Plugin::Expire module. Netdisco uses the standard Perl @INC path searching mechanism to load plugin modules. See the include_paths and site_local_files settings in order to modify @INC for loading local plugins.

If an entry in the list starts with a “+” (plus) sign then Netdisco attempts to load the module as-is, without prepending anything to the name. This allows you to have App::Netdisco worker plugins in other namespaces.

For your own plugins, use the "Netdisco extension" namespace App::NetdiscoX. You can prefix module names with X::, and Netdisco will prepend App::NetdiscoX::Worker::Plugin:: to the entry. For example, X::ConfigBackup will load the App::NetdiscoX::Worker::Plugin::ConfigBackup module.

`driver_priority`

Value: Dictionary of driver names and priorities. Default:

direct:   1000000
restconf: 500
netconf:  400
eapi:     300
cli:      200
snmp:     100

The mapping of driver names to worker priority. When assigning a worker priority yourself, you can choose to make it relative to one of these values. See the Worker Cookbook for further details.

Dancer Internal

`charset`

Value: String. Default: UTF-8.

See 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: cookie.

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

`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

These settings are from Netdisco 1.x but are yet to be supported in Netdisco 2. They are deemed unnecessary, although feel free to contact the developer team if you disagree!

phone_ouis
wap_ouis
col_xxx_show
port_info

Netdisco

Home
Installation ⇗
Configuration ⚙
- Environment Variables
API
Hooks
Cookbook
Troubleshooting
Install Tips
Vendor Tips
Database Tips
Custom Reports
Release Notes
Docker Images ⇗
Commercial Support

Configuration

Introduction

YAML Guidance

Boolean

List

Dictionary

String

Access Control Lists

Supported Settings

Essential Settings

name

user

pass

host

displayname

General Settings

log

logger_format

include_paths

template_paths

site_local_files

external_databases

tenant_databases

custom_fields

tags

Web Frontend

domain_suffix

no_auth

navbar_autocomplete

external_links

suggest_guest

trust_remote_user

trust_x_remote_user

validate_remote_user

tacacs

radius

ldap

servers

user_string

base

proxy_user

proxy_pass

opts

tls_opts

path

web_home

web_plugins

extra_web_plugins

sidebar_defaults

reports

tag

label

columns

query

category (optional)

hidden (optional)

database (optional)

query_columns (optional)

bind_params (optional)

show_sidebar (optional)

system_reports

jobqueue_refresh

jobs_qdepth

safe_password_store

table_pagesize

table_showrecordsmenu

inventory_collapse_threshold

portctl_by_role

portctl_no

portctl_only

portctl_nameonly

portctl_native_vlan

portctl_nowaps

portctl_nophones

portctl_uplinks

portctl_topology

port_control_reasons

check_userlog

devport_vlan_limit

login_logo

`name`

`user`

`pass`

`host`

`displayname`

`log`

`logger_format`

`include_paths`

`template_paths`

`site_local_files`

`external_databases`

`tenant_databases`

`custom_fields`

`tags`

`domain_suffix`

`no_auth`

`navbar_autocomplete`

`external_links`

`suggest_guest`

`trust_remote_user`

`trust_x_remote_user`

`validate_remote_user`

`tacacs`

`radius`

`ldap`

`servers`

`user_string`

`base`

`proxy_user`

`proxy_pass`

`opts`

`tls_opts`

`path`

`web_home`

`web_plugins`

`extra_web_plugins`

`sidebar_defaults`

`reports`

`tag`

`label`

`columns`

`query`

`category` (optional)

`hidden` (optional)

`database` (optional)

`query_columns` (optional)

`bind_params` (optional)

`show_sidebar` (optional)

`system_reports`

`jobqueue_refresh`

`jobs_qdepth`

`safe_password_store`

`table_pagesize`

`table_showrecordsmenu`

`inventory_collapse_threshold`

`portctl_by_role`

`portctl_no`

`portctl_only`

`portctl_nameonly`

`portctl_native_vlan`

`portctl_nowaps`

`portctl_nophones`

`portctl_uplinks`

`portctl_topology`

`port_control_reasons`

`check_userlog`

`devport_vlan_limit`

`login_logo`

`hide_deviceports`

`host_groups`

`host_group_displaynames`

`device_identity`

`mibhome`

`mibdirs`

`community`

`community_rw`

`device_auth`

`get_credentials`

`use_legacy_rancidexport`

`use_legacy_sshcollector`