Configuration¶

Create a project¶

Start in a new directory and run the initialization wizard:

mkdir my-network
cd my-network
annet init

Choose file or netbox. For NetBox, the wizard asks for its URL and prompts for a token without echoing it. Initialization creates context.yml with permissions 0600 and generators/__init__.py; file storage also gets an example inventory.yml. Existing target files or a generators directory are never overwritten. No network connection is made during initialization.

For non-interactive initialization, select the storage explicitly:

annet init --storage file
# Alternative, in another directory:
annet init --storage netbox --netbox-url https://netbox.example.org

Non-interactive NetBox initialization reads NETBOX_TOKEN from the environment or writes a placeholder. Keep the generated context private and out of version control. Replace credential placeholders and adapt the example Cisco IOS generator to your devices. NetBox access requires the annet[netbox] extra.

Select the new context explicitly; initialization does not change your global configuration or the context lookup order:

export ANN_CONTEXT_CONFIG_PATH="$PWD/context.yml"
annet gen switch.example.test

The example device is available only with file storage; for NetBox supply a real device query after configuring the URL and token. Run commands from the project directory because its generator and inventory paths are relative. annet-docker init runs the same command and writes into the directory mounted at /work; the image already selects /work/context.yml.

Context selection¶

The path to the configuration file is searched in following order:

ANN_CONTEXT_CONFIG_PATH env.
~/.annet/context.yml.
annet/configs/context.yml.

Config example:

generators:
  default:
    - my_annet_generators.example

storage:
  default:
    adapter: file
    params:
      path: /path/to/file

context:
  default:
    fetcher: default
    deployer: default
    generators: default
    storage: default

selected_context: default

Environment variable ANN_SELECTED_CONTEXT can be used to override selected_context parameter.

generators¶

See Generator.

generators:
  default:
    - /path/to/my_annet_generators/__init__.py
    - my_annet_generators  # relative import from sys.path

Storages¶

Storages provide information about devices like FQDN, interface and so on.

Netbox storage¶

Uses NetBox as storage.

storage:
  default:
    adapter: netbox
    params:
      url: http://127.0.0.1:8000
      token: 1234567890abcdef01234567890abcdef0123456
      insecure: true # skip SSL verification
      exact_host_filter: true # for setup where hostname used instead of fqdn

URL and token may be provided using NETBOX_URL, NETBOX_TOKEN, NETBOX_EXACT_HOST_FILTER and NETBOX_INSECURE environment variable.

export NETBOX_URL="https://demo.netbox.dev"
export NETBOX_TOKEN="1234567890abcdef01234567890abcdef0123456"

File storage¶

Uses local file as storage.

storage:
  default:
    adapter: file
    params:
      path: /path/to/file

cat /path/to/file:

devices:
  - fqdn: myhost.yndx.net
    vendor: mikrotik
    interfaces:
      - name: eth0
        description: test

Fetcher Configuration¶

The fetcher is responsible for connecting to devices and retrieving their configurations. Annet supports multiple connection methods including SSH (default), SSH on custom ports, and Telnet.

SSH with default port¶

Default SSH connection on port 22:

fetcher:
  default:
    adapter: gnetcli
    params:
      dev_login: username
      dev_password: password

SSH with custom port¶

To connect to devices using a non-standard SSH port:

fetcher:
  ssh-custom:
    adapter: gnetcli
    params:
      dev_login: username
      dev_password: password
      dev_port: 10022
      streamer_type: ssh

Telnet support¶

To connect to legacy devices using Telnet:

fetcher:
  telnet:
    adapter: gnetcli
    params:
      dev_login: username
      dev_password: password
      dev_port: 23
      streamer_type: telnet

Warning

Telnet transmits data in clear text. Use SSH whenever possible for security reasons.

Multiple Contexts¶

You can define multiple contexts to work with different device groups that require different connection methods:

context:
  default:
    fetcher: default
    deployer: default
    generators: default
    storage: default

  ssh-10022:
    fetcher: ssh-custom
    deployer: default
    generators: default
    storage: default

  telnet:
    fetcher: telnet
    deployer: default
    generators: default
    storage: default

selected_context: default

Switching between contexts:

# Use default SSH context
annet context set-context default
annet diff -g hostname mydevice.example.com

# Switch to telnet context for legacy devices
annet context set-context telnet
annet diff -g hostname legacy-switch.example.com

# Use custom SSH port context
annet context set-context ssh-10022
annet diff -g hostname custom-ssh-device.example.com