veeam-aiops

Veeam AIops

Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by Veeam Software. "Veeam" is a trademark of its owner. Source code is publicly auditable at github.com/AIops-tools/Veeam-AIops under the MIT license.

Governed Veeam Backup & Replication operations — 25 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.veeam-aiops/, policy engine, token/runaway budget guard, undo-token recording, and descriptive risk tiers. Credentials are stored encrypted (~/.veeam-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk.

Standalone: the governance harness is bundled in the package (veeam_aiops.governance) — veeam-aiops has no external skill-family dependency. Coverage focuses on common Veeam operations and is not yet exhaustive.

What This Skill Does

Quick Install

uv tool install veeam-aiops
veeam-aiops init       # interactive wizard: connection + encrypted password
veeam-aiops doctor

When to Use This Skill

• List/inspect Veeam backup jobs and their last result
• Start or stop a backup job on demand
• Enable or disable a job's schedule
• List available restore points and start a VM restore
• List backup repositories and stored backups
• Poll async sessions to follow job/restore progress

Do NOT use when the target is not Veeam Backup & Replication (other backup products, hypervisor VM lifecycle, Kubernetes, or cloud providers are out of scope for this skill).

Related Skills — Skill Routing

Common Workflows

Diagnose why last night's backups failed

1. veeam-aiops diagnose job-failures → worst-first table of Failed/Warning sessions, each with the categorized cause (repository full / source unreachable / credential-VSS / retry exhaustion) and the cited failing log line
2. If a finding says repository full, confirm with veeam-aiops diagnose repo-capacity → the flagged repo's measured free% and free bytes
3. Fix the root cause (extend/offload the repository, restore source connectivity, or repair guest credentials/VSS), then veeam-aiops job retry to re-run only the failed objects
4. veeam-aiops session list → veeam-aiops session get to confirm the retry completes — do not tight-loop session get (the runaway budget guard will trip it)

Run a backup job and follow it to completion

1. veeam-aiops job list → find the job id and confirm lastResult
2. veeam-aiops job start → starts the job (records an inverse job_stop undo descriptor)
3. veeam-aiops session list → find the running session; veeam-aiops session get → check state / progressPercent
4. Failure branch: if session get shows the session Failed, inspect result, then re-run job start after fixing the cause — do not loop session get rapidly (the runaway budget guard will trip a tight poll loop).

Restore a VM from a restore point

1. veeam-aiops restore list-points → identify the correct restore point id
2. veeam-aiops restore start --restore-point-id --dry-run → preview the exact API call and the VM name + creation time the id resolves to — never approve a restore from a GUID
3. veeam-aiops restore start --restore-point-id → double confirmation required; this is IRREVERSIBLE (overwrites/creates a VM) and records no undo token. Refused outright if the VM name matches the configured VBR host (an in-place overwrite of the backup server itself) — a name-based safety net, not a proof, so confirm the target yourself
4. Failure branch: if doctor shows the VBR server unreachable or the password env var is missing, fix ~/.veeam-aiops/.env (chmod 600) before retrying — the restore is never issued against an unauthenticated session.

Usage Mode

MCP Tools (25 — 17 read, 8 write)

Harness features that light up: write tools with a clean inverse (job_start↔job_stop, job_retry→job_stop, job_enable↔job_disable) pass an undo= lambda so the harness records an inverse descriptor (with _undo_id) to the undo store. The irreversible start_vm_restore and session_stop declare no undo; start_vm_restore is tagged risk_level=high. All 25 tools are audit-logged under ~/.veeam-aiops/ and pass through the budget/runaway guard, each row carrying a descriptive risk tier. Veeam jobs/restores run as async sessions — poll with session_get / session_log instead of re-issuing (the runaway breaker backs this up). Start any triage with overview (jobs by last result, repos near full, running sessions), then drill in with job_failure_rca (categorizes failing sessions with cited error substrings) and repository_capacity_rca (cited free%).

CLI Quick Reference

veeam-aiops init                                      # onboarding wizard (encrypted password)
veeam-aiops overview [--target ]                   # health summary
veeam-aiops diagnose job-failures [--target ]      # RCA: triage failed job sessions
veeam-aiops diagnose repo-capacity [--target ]     # RCA: repos low on free space
veeam-aiops job list [--target ]
veeam-aiops job get 
veeam-aiops job start 
veeam-aiops job stop  [--dry-run]              # double confirm
veeam-aiops job retry 
veeam-aiops job enable 
veeam-aiops job disable 
veeam-aiops restore list-points [--backup-id ]
veeam-aiops restore start --restore-point-id  [--dry-run]   # double confirm
veeam-aiops repository list
veeam-aiops repository get 
veeam-aiops repository state                           # capacity / free / used%
veeam-aiops session list
veeam-aiops session get 
veeam-aiops session log 
veeam-aiops session stop  [--dry-run]     # double confirm
veeam-aiops backup list
veeam-aiops backup objects 
veeam-aiops infra servers
veeam-aiops infra proxies
veeam-aiops secret set                         # store password encrypted
veeam-aiops secret list                               # names only
veeam-aiops secret migrate                            # import legacy plaintext .env
veeam-aiops secret rotate-password
veeam-aiops doctor
veeam-aiops mcp                                        # start MCP server (stdio)

See references/cli-reference.md for the full command list.

Troubleshooting

"Config file not found"

Run veeam-aiops init to set up your first target (writes ~/.veeam-aiops/config.yaml and stores the password encrypted).

"No password for target ''"

Add it to the encrypted store: veeam-aiops secret set (prompts hidden), or run veeam-aiops init. For non-interactive use (MCP/CI), also export VEEAM_AIOPS_MASTER_PASSWORD so the store can be unlocked without a prompt.

"Master password not set" / "Wrong master password"

The encrypted store ~/.veeam-aiops/secrets.enc is unlocked by VEEAM_AIOPS_MASTER_PASSWORD (or an interactive prompt). If you forgot it, delete secrets.enc and re-run veeam-aiops init. Rotate it with veeam-aiops secret rotate-password.

"Authentication/authorization failed (401)"

The username/password is wrong, or the account lacks a Veeam role. Veeam usernames are typically DOMAIN\\user or a local Windows account on the VBR server. Confirm the account can log in to the Veeam console.

"Could not reach Veeam server … check the host/port"

The default REST API port is 9419 — confirm the Veeam Backup & Replication REST API service is running and the port is open. For self-signed certificates set verify_ssl: false on the target (lab only).

"Resource not found (404)"

The job/session/restore-point id is stale. List the parent collection first (job list, session list, restore list-points) to get a current id.

Governance & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the Veeam account you connect it with (a read-only or restricted role on the VBR server — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

• Credentials stored encrypted in ~/.veeam-aiops/secrets.enc (Fernet/AES-128 + scrypt key derivation; chmod 600) — never plaintext on disk; the master password is never stored, only a per-store salt + ciphertext
• Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.veeam-aiops/audit.db (relocatable via VEEAM_AIOPS_HOME): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
• VEEAM_AUDIT_APPROVED_BY / VEEAM_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
• Runaway guard — a safety backstop, not authorization: cumulative tool calls and wall-time are capped, and the same call looped in a tight session-poll/retry window trips a circuit breaker.
• Writes support --dry-run / dry_run=True and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.
• Reversible writes (job start/stop/retry, enable/disable) record an inverse undo descriptor; the irreversible start_vm_restore and session_stop record none.

The harness is bundled in the package — no external dependency, no manual setup. See references/setup-guide.md for security details.

Contributing & feature requests

Coverage is intentionally focused. Missing a device, action, or feature you need? Open an issue or pull request at github.com/AIops-tools/Veeam-AIops — feature requests, contributions, and comments are all welcome.

License

MIT — github.com/AIops-tools/Veeam-AIops