Configuration
==========================

Create a project
----------------

Start in a new directory and run the initialization wizard:

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: yaml

    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 :ref:`generator reference`.

.. code-block:: yaml

    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 <https://netboxlabs.com/docs/netbox/en/stable/>`_ as storage.

.. code-block:: yaml

    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.

.. code-block:: shell

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

File storage
----------------------

Uses local file as storage.

.. code-block:: yaml

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


``cat /path/to/file``:

.. code-block:: yaml

    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:

.. code-block:: yaml

    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:

.. code-block:: yaml

    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:

.. code-block:: yaml

    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:

.. code-block:: yaml

    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:

.. code-block:: bash

    # 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