Deploying Initial Device Configurations

netlab initial command uses expanded Ansible inventory data created with netlab create command, device-specific Jinja2 templates, and an internal Ansible playbook to deploy initial device configurations.

netlab initial skips devices with unmanaged attribute (those devices are not part of Ansible inventory) and devices in the unprovisioned group.

After a successful completion of the Ansible playbook, netlab initial displays the help message defined in the lab topology.

netlab initial functional diagram

The Ansible playbook invoked by netlab initial command deploys device configurations in three steps:

  • Initial device configurations[1]

  • Module-specific device configurations[2]

  • Custom configuration templates[3]

Jinja2 templates are used together with device_config Ansible modules to configure most devices. In some cases, the configuration task list includes additional tasks[4]. Some devices (for example, Fortinet firewall) are configured through calls to device-specific Ansible modules. See Platform Caveats for more details.

When run with -v parameter, the command displays device configurations before deploying them.


netlab initial command does not need a topology file; It’s just a thin wrapper around an Ansible playbook which uses Ansible inventory created by netlab create or netlab up command. You don’t have to specify the topology file name or other netlab create CLI parameters you used to tweak the lab topology.


usage: netlab initial [--log] [-q] [-v] [-i] [-m [MODULE]] [-c] [--fast] [-o [OUTPUT]]

Initial device configurations

optional arguments:
  -h, --help            show this help message and exit
  --log                 Enable basic logging
  -q, --quiet           Report only major errors
  -v, --verbose         Verbose logging
  -i, --initial         Deploy just the initial configuration
  -m [MODULE], --module [MODULE]
                        Deploy module-specific configuration (optionally including a 
                        list of modules separated by commas)
  -c, --custom          Deploy custom configuration templates (specified in "config" 
                        group or node attribute)
  --fast                Use "free" strategy in Ansible playbook for faster
                        configuration deployment
  -o [OUTPUT], --output [OUTPUT]
                        Create a directory with initial configurations instead of
                        deploying them

All other arguments are passed directly to ansible-playbook

Initial Device Configurations

Initial device configurations are created from inventory data and templates in netsim/ansible/templates/initial directory[5]. Device-specific configuration template is selected using network_device_type or ansible_network_os value (making IOSv and CSR 1000v templates identical). See Deploying Device Configurations for more details.

The following initial configuration parameters are supported:

  • hostname

  • interface IPv4 and IPv6 addresses

  • unnumbered interfaces

  • interface descriptions

  • interface MAC addresses

  • interface bandwidth (when supported by the device)

The initial configuration also includes LLDP running on all interfaces apart from the management interface (not configurable).

Default passwords and other default configuration parameters are supposed to be provided by the Vagrant boxes.

Module Configurations

Module-specific device configurations are created from templates in netsim/ansible/templates/_module_ directory[6]. Device-specific configuration template is selected using netlab_device_type or ansible_network_os value.

More details:

Custom Deployment Templates

Custom deployment templates are specified in config group- or node parameter. initial-config.ansible playbook used by netlab initial command tries to find the target configuration template in user- and system (netsim/extra) directories and uses node name, netlab_device_type, and ansible_network_os Ansible variables to allow you to create numerous device-specific configuration templates.

You’ll find more details in Finding Custom Configuration Templates documentation.

Limiting the Scope of Configuration Deployments

Without specifying -i or -m flag, the command deploys all initial configurations. To control the deployment of initial configurations:

  • use the -i flag to deploy initial device configurations.

  • use the -m flag to deploy module-specific configurations.

  • use the -m flag followed by a module name (example: -m ospf -m bgp) to deploy device configuration for specific modules. You can use the -m flag multiple times.

  • use the -c flag to deploy custom configuration templates.

All unrecognized parameters are passed to internal initial-config.ansible Ansible playbook. You can use ansible-playbook CLI parameters to modify the configuration deployment, for example:

  • -l parameter to deploy device configurations on a subset of devices.

  • -C parameter to run the Ansible playbook in dry-run mode. Combine it with -v parameter to see the configuration changes that would be deployed[7]

Debugging Initial Configurations

  • Use -o flag to create device configurations without deploying them. The optional value of -o parameter specifies the output directory name (default: config)

  • To display device configurations from within the Ansible playbook without deploying them, use -v --tags test flags (a bogus playbook tag disables configuration deployment).