config.yaml reference

config.yaml lives in the project root and is optional.

A missing config.yaml fails silently

When config.yaml is absent, load_config returns built-in defaults with no warning (src/config.py:73). Those defaults name placeholder credential slots (network_1 through network_4) that will not match your real secrets files, so every device fails authentication. config.yaml is commonly git-ignored, which means this bites on fresh clones and new machines. Check it exists before debugging anything else.

Merging is one level deep: for each top-level key present in your file, dict.update() is applied over the defaults. A paths: block with one key keeps the other default paths. A credentials: block replaces sets wholesale, so a partial credentials block silently drops every set you didn’t list.

Full example, showing real defaults:

paths:
  config_dir: "config"
  backup_dir: "BACKUP"
  pre_check_dir: "PRE_CHECK"
  post_check_dir: "POST_CHECK"
  logs_dir: "LOGS"
  summary_dir: "SUMMARY"
  secrets_dir_linux: "/opt/automation/secrets_v3"
  secrets_dir_windows: "D:\\Prod_Automation\\env\\prod\\secrets_v3"

database:
  file: "network_inventory.db"

connection:
  ssh_client_id: "OpenSSH_9.5"
  banner_timeout: 60          # seconds
  auth_timeout: 60
  command_timeout: 30
  write_timeout: 120

backup:
  retention_days: 30          # 0 = keep forever
  include_monthly_archive: true

healthcheck:                  # percent; >= crit -> CRIT, >= warn -> WARN
  cpu_warn: 80
  cpu_crit: 90
  mem_warn: 85
  mem_crit: 95

execution:
  max_workers: 1              # raise this; 1 means fully sequential

logging:
  enabled: true
  level: "INFO"

notifications:
  telegram:
    enabled: false
    bot_token: ""             # or env TELEGRAM_BOT_TOKEN
    chat_id: ""               # or env TELEGRAM_CHAT_ID
  email:
    enabled: false
    smtp_host: ""             # or env SMTP_HOST
    smtp_port: 587
    smtp_user: ""             # or env SMTP_USER
    smtp_password: ""         # or env SMTP_PASSWORD
    from_address: ""          # defaults to smtp_user
    recipients: []

credentials:
  sets:                       # slot names, never passwords
    - user: "cisco_admin_user"
      password: "cisco_admin_pass"
    - user: "alcatel_admin_user"
      password: "alcatel_admin_pass"

vendors:                      # vendor -> Netmiko device_type
  cisco: "cisco_ios"
  cisco_wlc: "cisco_ios"
  nexus: "cisco_nxos"
  alcatel: "alcatel_aos"
  alcatel_wlc: "aruba_os"
  aruba: "aruba_os"
  wlc: "cisco_wlc"

validation:                   # substrings that must appear in a valid config
  cisco:
    - "interface"
    - "hostname"
  alcatel:
    - "system name"
    - "system contact"

execution

Key	Default	Description
max_workers	1	Parallel SSH connections. Override per run with --workers N.

Caution

The default really is 1, meaning every run is fully sequential. Three hundred devices at roughly 15 seconds each is over an hour at the default and about four minutes at --workers 30. Set this once and stop thinking about it.

connection

Key	Default	Description
ssh_client_id	"OpenSSH_9.5"	SSH client identification string announced to devices. Legacy OS SSH servers (Alcatel AOS6 on OpenSSH_5.0, Cisco IOS XR) hang up without a banner when they see paramiko’s own paramiko_<version> identifier. Set to "" to use paramiko’s default.
banner_timeout	60	Seconds to wait for the SSH banner during handshake.
auth_timeout	60	Seconds to wait for authentication to complete.
command_timeout	30	Seconds to wait for a command response.
write_timeout	120	Seconds to wait for a config write to complete.

backup

Key	Default	Description
retention_days	30	Delete backups older than this. 0 keeps all backups.
include_monthly_archive	true	Keep a monthly archive copy.

healthcheck

Thresholds (percent) for the --healthcheck report. A metric at or over warn reports WARN; at or over crit reports CRIT.

Key	Default	Description
cpu_warn	80	CPU % warning threshold.
cpu_crit	90	CPU % critical threshold.
mem_warn	85	Memory % warning threshold.
mem_crit	95	Memory % critical threshold.

paths

Key	Default	Description
config_dir	config	Command files and device inventory.
secrets_dir_windows	D:\Prod_Automation\env\prod\secrets_v3	DPAPI credential directory.
secrets_dir_linux	/opt/automation/secrets_v3	Credential directory on Linux.
logs_dir	LOGS	SSH session log output.
backup_dir	BACKUP	Full config backups.
summary_dir	SUMMARY	Per-run summary CSVs.
pre_check_dir	PRE_CHECK	Device state before each change.
post_check_dir	POST_CHECK	Device state after each change.

database

Key	Default	Description
file	network_inventory.db	SQLite inventory path. Export with --export FILE.

logging

Key	Default	Description
enabled	true	Write run logs.
level	INFO	Python logging level.

credentials

Lists credential slot names, tried in order until one authenticates. See Credential setup for how a slot resolves and which files the setup script creates. Never put real passwords here.

vendors

Maps a vendor column value to a Netmiko device_type. Override only if you need a different driver for a platform.

Environment variable overrides

Variable	Overrides
SECRETS_DIR	paths.secrets_dir_windows / paths.secrets_dir_linux
CRED_{SLOT}	The file for that credential slot
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID	Telegram notification settings
SMTP_HOST, SMTP_USER, SMTP_PASSWORD	Email notification settings