diff --git a/docs/makerspace-switch-fieldguide.md b/docs/makerspace-switch-fieldguide.md new file mode 100644 index 0000000..54999d2 --- /dev/null +++ b/docs/makerspace-switch-fieldguide.md @@ -0,0 +1,165 @@ +# Makerspace Field Guide — Preparing the CRS310 Switch + +**Print this and bring it.** This is the exact, on-site procedure to get the MikroTik +**CRS310-8G+2S+IN** ready so Ansible can take over. Total time: ~30–45 min (most of it +the firmware upgrade). Work on a **bench/isolated network** — do **not** plug the switch +into the live makerspace network until VLANs are configured later (avoids loops and +DHCP/IP conflicts). + +When you're done, you'll have: the switch on a known firmware, wiped to a clean slate, +reachable over SSH at a temporary IP, and a few facts written down for me to drop into +`host_vars`. + +--- + +## Bring with you + +- [ ] The CRS310 + its PSU. +- [ ] A laptop with **WinBox** (download from mikrotik.com/download) — or just a browser for WebFig. +- [ ] One Ethernet cable (laptop ↔ a 2.5G port). +- [ ] Internet for the switch during the upgrade (a cable from an existing LAN/uplink, **temporarily**, with DHCP — unplug it again before the final steps). +- [ ] The **SFP+ module or DAC** for the 10G uplink (to fit physically; we don't cable the real uplink yet). +- [ ] This guide + something to write the recorded facts on (or a phone note). + +--- + +## Step 1 — Power on and get in + +1. Power the switch. Wait ~1 min for it to boot RouterOS. +2. Connect your laptop to **ether1** (a 2.5G port). +3. Open **WinBox → Neighbors tab**. The switch appears (by IP `192.168.88.1` and/or by MAC). + - **Tip:** click the **MAC address** (not the IP) to connect — this works even when the + switch has no IP, which matters in Step 5. +4. Log in: user `admin`, password **blank** (just press Enter). RouterOS 7 may ask you to + set a password — you can set a temporary one or skip; Ansible will set the real one later. + +> No WinBox? Browse to `http://192.168.88.1` (WebFig) instead. The CLI commands below are +> typed in **WinBox/WebFig → New Terminal**. + +--- + +## Step 2 — Confirm it's running RouterOS (not SwOS) + +The CRS310 can dual-boot SwOS, but we need **RouterOS** for VLAN filtering + Ansible. + +- In terminal: `/system/routerboard/print` +- It should report RouterOS. If the device booted **SwOS** (different, simpler web UI), + switch the boot OS: in SwOS go to the **System** page and set boot to RouterOS, or use + the reset/boot-OS toggle, then reboot. (You want the full RouterOS interface.) + +--- + +## Step 3 — Upgrade and pin the firmware + +This needs internet for the switch. Plug a DHCP uplink into **ether8** temporarily. + +1. Give the switch internet briefly: it should pull a DHCP lease on the uplink port, or in + terminal: `/ip/dhcp-client/add interface=ether8 disabled=no` +2. Update RouterOS: + ``` + /system/package/update/set channel=stable + /system/package/update/check-for-updates + /system/package/update/download + /system/reboot + ``` + (Or WinBox: **System → Packages → Check For Updates → Download & Install**.) +3. After reboot, upgrade the bootloader (RouterBOOT) to match: + ``` + /system/routerboard/upgrade + /system/reboot + ``` +4. **Write down the final version:** `/system/resource/print` → the `version` line. + ➜ **Record as `RouterOS version: ______`** (this becomes `switch_firmware_target`). +5. **Unplug the temporary internet uplink** and remove the DHCP client: + `/ip/dhcp-client/remove [find]` + +--- + +## Step 4 — Record the device facts + +Run `/system/routerboard/print` and `/system/resource/print` and write down: + +- [ ] **Model:** ____________________ (should be CRS310-8G+2S+IN) +- [ ] **Serial:** ____________________ (also on the sticker underneath) +- [ ] **Base MAC:** ____________________ +- [ ] **RouterOS version:** ____________________ (from Step 3.4) + +--- + +## Step 5 — Wipe to a clean slate (no default config) + +This makes Ansible the single owner of the whole configuration. + +1. In terminal: + ``` + /system/reset-configuration no-defaults=yes skip-backup=yes + ``` + (Or WinBox: **System → Reset Configuration** → tick **No Default Configuration** and + **Do Not Backup** → **Reset**.) +2. The switch reboots. It now has **no IP and no services** — WinBox-by-IP won't find it. +3. Reconnect using **WinBox → Neighbors → click the MAC address** (this is why we use MAC). + Log in as `admin` with a **blank** password. + +--- + +## Step 6 — Give it a temporary IP + enable SSH (so Ansible can reach it) + +In the terminal (laptop still on **ether1**): + +``` +/ip/address/add address=192.168.88.1/24 interface=ether1 +/ip/service/enable ssh +/ip/service/print +``` + +Then on your laptop, set a static IP `192.168.88.2` / `255.255.255.0` and confirm SSH: + +``` +ssh admin@192.168.88.1 +``` + +If that logs in, **you're done** — leave the switch powered and on the bench. + +> ⚠️ Keep a **WinBox MAC session** open as your lifeline whenever you change network +> settings. If you ever lock yourself out, MAC-telnet/WinBox-by-MAC still works; a full +> **Netinstall** (mikrotik.com/download) is the last-resort recovery. + +--- + +## Step 7 — Decide the real addressing (write it down for me) + +I need these to fill in `host_vars/crs310-maker.yml`. Decide with whatever the makerspace +network plan is (or we can finalize together): + +- [ ] **Management IP + mask** (real, not the temp one): ____________________ +- [ ] **Management VLAN ID:** ____________________ +- [ ] **Default gateway:** ____________________ +- [ ] **Upstream uplink port** (which SFP+ / port goes to the OPNsense/router): ____________________ +- [ ] **DNS / NTP server IP** (usually the gateway): ____________________ + +(If the makerspace VLAN plan isn't settled yet, that's fine — we ship a placeholder and +fill these in later. The switch just needs to be reachable per Step 6.) + +--- + +## Step 8 — Physical finish + +- [ ] Fit the **SFP+ module/DAC** into `sfp-sfpplus1` (don't cable the live uplink yet). +- [ ] Mount/label the switch. + +--- + +## When you're back + +Bring me: +1. The recorded facts (Step 4) and addressing decisions (Step 7). +2. Confirmation that `ssh admin@192.168.88.1` (or your temp IP) works. + +Then I'll: create the empty `MakerFLOSS_Mikrotik` repo on `forgejo.makerfloss.eu`, drop +your facts into `host_vars`, and run **`play_bootstrap.yml`** — which creates your named +admin user, imports your SSH key, and hands the switch over to Ansible. After that, +`play_switch.yml` configures identity, services, VLANs, and backups. + +> **Do not connect the switch to the live makerspace network** until VLANs are configured +> (Task 7 in the implementation plan) — an unconfigured switch on the live net can cause +> loops or hand out the wrong VLAN.