first commit

docs/switchos.md

@@ -0,0 +1,46 @@
+# SwOS backup support
+
+SwOS/SwOS Lite devices are handled through their HTTP/HTTPS web interface rather than RouterOS SSH.
+
+## Backup flow
+
+The adapter:
+
+1. normalizes the configured device URL;
+2. probes the web interface;
+3. obtains the authentication challenge when required;
+4. attempts HTTP Digest authentication, then Basic authentication as fallback;
+5. follows bounded same-device redirects and re-authenticates for the final URI when needed;
+6. downloads `GET /backup.swb`;
+7. rejects empty responses and obvious HTML/login/error pages before saving the `.swb` file.
+
+Digest challenge responses are fully consumed and challenge cookies are preserved before retrying. `/backup.swb` starts with a fresh authentication state instead of reusing an unrelated homepage nonce.
+
+## Connection test
+
+The connection test reports web reachability separately from backup availability. A device can therefore be online while `/backup.swb` is unavailable or rejected.
+
+## Credentials
+
+A SwOS device may use either:
+
+- global SwOS credentials from Settings; or
+- credentials saved specifically for that device.
+
+Legacy imported records retain the previous fallback behavior until an explicit source is selected.
+
+## Troubleshooting HTML instead of `.swb`
+
+If the application reports that SwOS returned HTML instead of `/backup.swb`:
+
+- verify the configured scheme/host/port;
+- verify the selected credential source and credentials;
+- confirm that **Save Backup** works in the device web interface;
+- confirm `/backup.swb` works with the same account/firmware;
+- inspect the returned status/content type/title included in the application diagnostic.
+
+Do not treat an HTTP `200` login page as a valid backup.
+
+## Scope
+
+Version 0.0.1 downloads SwOS backups. It does not restore/upload a SwOS configuration or reboot a switch.