67554c0b38
Implements Task 10 doc updates. README/CLAUDE/role-README now reflect that all task files + play_bootstrap/play_backup are implemented and idempotency-verified, that vlans is built+validated but its device run is deferred (placeholder topology, on-site recovery needed), and that the bootstrap/backup plays exist. Corrects the bootstrap invocation example (-e ansible_user=admin --ask-pass). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# makerfloss.mikrotik_switch
|
|
|
|
Configure a MikroTik RouterOS switch (CRS310) over SSH with `community.routeros`.
|
|
The role provides the *mechanism*; real values live in `host_vars`. Each domain is
|
|
gated by an enable-flag (defined in `group_vars/mikrotik.yml`) so you can apply a
|
|
subset with `--tags`.
|
|
|
|
## Domains (enable-flags)
|
|
|
|
| Flag | Task file | Tag | Does |
|
|
|---|---|---|---|
|
|
| `switch_identity_enabled` | `identity.yml` | `identity` | identity, mgmt IP, DNS/NTP, SSH on, disable unused services |
|
|
| `switch_users_enabled` | `users.yml` | `users` | named admin user, import SSH key, disable default `admin` |
|
|
| `switch_vlans_enabled` | `vlans.yml` | `vlans` | VLAN-aware bridge, access/trunk ports, mgmt VLAN iface |
|
|
| `switch_backup_enabled` | `backup.yml` | `backup` | `/export` + binary backup, fetched into the repo |
|
|
| `switch_firmware_enabled` | `firmware.yml` | `firmware` | RouterOS + RouterBOOT upgrade to `switch_firmware_target` (opt-in) |
|
|
|
|
> All per-domain task files are implemented. `identity`, `users`, `backup` and
|
|
> `firmware` are idempotency-verified against the device; `vlans` is implemented and
|
|
> Jinja-validated but its device run is deferred until the real topology is in
|
|
> `host_vars` and an on-site recovery channel is available (it enables
|
|
> `vlan-filtering` last, which can strand management if the mgmt path is wrong).
|
|
|
|
## Variables (`defaults/main.yml`)
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `switch_identity_name` | `{{ inventory_hostname }}` | system identity |
|
|
| `switch_mgmt_vlan_id` | `99` | management VLAN id |
|
|
| `switch_mgmt_address` | placeholder | mgmt IP `addr/cidr` (override in host_vars) |
|
|
| `switch_mgmt_gateway` | placeholder | default gateway |
|
|
| `switch_dns_servers` | placeholder | DNS server(s) |
|
|
| `switch_ntp_servers` | placeholder | NTP server(s) |
|
|
| `switch_disabled_services` | telnet,ftp,www,www-ssl,api,api-ssl | services to disable (winbox kept for recovery) |
|
|
| `switch_ssh_port` | `22` | SSH service port |
|
|
| `switch_admin_user` | `sjat` | named admin user |
|
|
| `switch_admin_group` | `full` | RouterOS group for the admin user |
|
|
| `switch_admin_ssh_pubkey_file` | `~/.ssh/id_ed25519.pub` | operator public key to import |
|
|
| `switch_disable_default_admin` | `true` | disable the built-in `admin` after key login works |
|
|
| `switch_bridge_name` | `bridge` | bridge to manage |
|
|
| `switch_vlans` | example | list of `{id, name}` |
|
|
| `switch_bridge_ports` | example | list of port definitions (see below) |
|
|
| `switch_firmware_target` | `""` | RouterOS version to pin/upgrade to |
|
|
|
|
### Data shapes
|
|
|
|
```yaml
|
|
switch_vlans:
|
|
- {id: 99, name: "mgmt"}
|
|
- {id: 10, name: "members"}
|
|
|
|
switch_bridge_ports:
|
|
# access port: untagged member of one VLAN (pvid)
|
|
- {interface: "ether1", pvid: 10, mode: access}
|
|
# trunk port: carries tagged VLANs; pvid sets the untagged/native VLAN
|
|
- {interface: "sfp-sfpplus1", pvid: 1, mode: trunk, tagged_vlans: [99, 10]}
|
|
```
|
|
|
|
## Idempotency
|
|
|
|
RouterOS has no rich declarative module set over `network_cli`, so tasks use
|
|
`community.routeros.command` with `:if ([:len [... find ...]] = 0) do={ ... }` guards.
|
|
Always run twice and confirm the second run is a no-op.
|