CLI Hooks

Several netlab CLI commands can execute configurable commands during their operation. This functionality is configured in netlab.command topology defaults and is currently available in netlab up and netlab down commands.

Each CLI hook can specify a single CLI command (a string value). The commands executed as CLI hooks must be executable programs or scripts, not internal shell commands. For example, it’s perfectly fine to use touch some_file, bash some_script.sh, or python3 my_script.py, but not echo x. Output redirection is not supported; if you need it, create a bash script to handle it.

You can use the error exit status of the external commands to stop netlab processing – netlab will display a fatal error and stop its operation whenever an external command returns a non-zero exit status.

Example

You could emulate the behavior of the netlab.lock locking file with these CLI hooks:

defaults.netlab:
  up.pre_start_lab: touch lab.lock
  down.post_stop_lab: rm lab.lock

The above defaults define commands that are executed before the lab is started and after the lab is stopped.

After having the mechanism to create and delete the locking file, you could add netlab.up.pre_probe hook to check whether the locking file exists.

Environment Variables Available to CLI Hooks

CLI parameters specified in the netlab up and netlab down commands are passed to the CLI hooks as environment variables starting with NETLAB_ARGS_. netlab also sets the NETLAB_ARGS_TOPOLOGY variable to the name of the lab topology specified in the command line or stored in the transformed lab topology snapshot file.

For example:

  • When you execute netlab down --cleanup, the CLI hooks will have the NETLAB_ARGS_CLEANUP environment variable set to True.

  • When netlab up is started with -vvv parameter, the NETLAB_ARGS_VERBOSITY environment variable will be set to 3.

Tip

  • You can debug this process with the verbosity set to -vvv or more.

  • If you execute other netlab commands in the CLI hooks, those commands get the values of the NETLAB_ARGS_ environment variables in the defaults.args dictionary.

netlab up Hooks

You can define external programs to be executed at these points in the start the lab process in the defaults.netlab.up dictionary:

  • pre_probe – executed before the “do we have a working environment” probe. Use this command to run additional checks on your environment (for example, whether NETLAB_MULTILAB_ID is set).

  • pre_start_lab – executed before any of the virtual machines or containers are started

  • post_start_lab – executed after the virtual machines and containers are running. You can use this command to add licenses to your virtual machines.

Tip

‌containerlab does not always check whether the containers are ready. If your script needs ‌operational network devices, execute the netlab initial --ready command to ensure they are ready to be configured.

  • pre_initial_config and post_initial_config are executed before and after the initial device configuration

  • pre_reload_config and post_reload_config are executed before and after configuration reload. These commands are never executed in the same netlab up run as the initial device configuration hooks.

  • pre_tools_start and post_tools_start are executed before and after the external tools are started.

netlab up can also call provider-specific hooks:

For example, you could run netlab initial --ready after the containerlab has started the containers to ensure the network devices are ready (Vagrant waits for the device SSH server before declaring Mission Accomplished):

defaults.netlab.up.post_start_clab: netlab initial --ready

netlab down Hooks

You can define external programs to be executed at these points in the stop the lab process in the defaults.netlab.down dictionary:

  • pre_stop_lab – executed before the virtual machines and containers are stopped. You could use this script to deregister the licenses used by your network devices

  • post_stop_lab – executed after the virtual machines and containers have been stopped. You could use this command for further licensing processing that does not require access to network devices.

Tip

The ‌pre_stop_lab hook will be executed every time the ‌netlab down command is run. The ‌post_stop_lab hook will be executed only when the lab is successfully stopped.

  • pre_cleanup – executed before netlab down –cleanup starts deleting the lab configuration files.

  • post_cleanup – executed after the cleanup process has been completed.

Tip

You can use any of the cleanup hooks to delete additional files that might have been created by your external commands.

netlab down can also call provider-specific hooks: