https://github.com/karrots/mikrotik-certbot
Deploy hook for use with certbot allowing deployment of certificates to RouterOS devices.
https://github.com/karrots/mikrotik-certbot
Last synced: 5 months ago
JSON representation
Deploy hook for use with certbot allowing deployment of certificates to RouterOS devices.
- Host: GitHub
- URL: https://github.com/karrots/mikrotik-certbot
- Owner: karrots
- License: mit
- Created: 2025-10-04T01:06:14.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-20T04:14:47.000Z (8 months ago)
- Last Synced: 2025-12-01T16:27:08.453Z (7 months ago)
- Language: Python
- Homepage:
- Size: 75.2 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# mikrotik-certbot
A Certbot deploy-hook tool that uploads renewed Let’s Encrypt certificates to MikroTik RouterOS devices and applies them to services. It is idempotent and non‑destructive: imports under a versioned name, applies to targets, then prunes older unreferenced certificates.
Why not just use the built in ACME support?
- EAB authentication is broken in ROS 7.20 and lower.
- Router may not have access to the Internet
- Renewal of services like hotspot not supported by the built in ACME service.
## Contents
- [mikrotik-certbot](#mikrotik-certbot)
- [Contents](#contents)
- [Highlights](#highlights)
- [Prerequisites](#prerequisites)
- [Initial Setup (Certbot deploy hook)](#initial-setup-certbot-deploy-hook)
- [Application Flow](#application-flow)
- [More Documentation](#more-documentation)
- [Developer Workflows](#developer-workflows)
- [License \& Authors](#license--authors)
## Highlights
- Versioned, collision‑safe certificate naming (UTC `YYYYMMDDThhmm`, `_SEQ` suffix when needed)
- REST upload on RouterOS ≥ 7.17; SFTP fallback otherwise, then REST import
- Applies to `www-ssl`, `api-ssl`, and optional Hotspot profiles
- Strict gating (`MIKROTIK_DOMAIN` must be in `RENEWED_DOMAINS`), `DRY_RUN` support
## Prerequisites
- Python `3.11+` and `uv` installed
- Certbot on the host that renews the certificate
- MikroTik RouterOS reachable over HTTPS (REST); SFTP enabled only if supporting fallback
- A RouterOS user with access to files/certificates/services
## Initial Setup (Certbot deploy hook)
1) Install `uv` if needed: `curl -LsSf https://astral.sh/uv/install.sh | sh`
2) Download the hook directly (no repository clone required). Replace the example URL with the raw file URL for this repo:
```sh
sudo curl -fsSL "https://raw.githubusercontent.com/karrots/mikrotik-certbot/refs/heads/main/deploy-hook.sh" -o /etc/letsencrypt/renewal-hooks/deploy/mikrotik-certbot.sh
```
3) Edit the following variables in the downloaded `/etc/letsencrypt/renewal-hooks/deploy/mikrotik-certbot.sh` file:
- `MIKROTIK_DOMAIN`: your FQDN (must appear in `RENEWED_DOMAINS`)
- `ROUTER_HOST`: e.g., `router.example.net:8443`
- `ROUTER_USER` / `ROUTER_PASS`: least‑privilege credentials for RouterOS access
4) Verify with a dry‑run: `sudo certbot renew --dry-run --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/mikrotik-certbot.sh`
5) If multiple hosts need certificates duplicate the `deploy-hook.sh` as needed.
See `docs/config.md` for all configuration options and behavior toggles.
## Application Flow
The hook exits early unless `MIKROTIK_DOMAIN` is present in `RENEWED_DOMAINS`. It derives a versioned, collision‑safe certificate name and detects RouterOS capabilities to pick REST upload or SFTP fallback. The combined PEM (privkey + fullchain) is uploaded, then imported without removing any existing same‑name certificate first. The new certificate is applied to `www-ssl`, `api-ssl`, and any configured Hotspot profiles. After a real import completes, older unreferenced certificates are pruned, keeping the newest two.
## More Documentation
- Configuration: `docs/config.md`
- Usage: `docs/usage.md`
- RouterOS Permissions: `docs/permissions.md`
## Developer Workflows
- Sync dev deps: `uv sync --group dev`
- Run: `uv run mikrotik-certbot`
- Lint: `uv run --group dev ruff check .`
- Types: `uv run --group dev mypy .`
- Tests: `uv run --group dev pytest`
- Build: `uv build`
## License & Authors
- License: MIT (see `LICENSE`)
- Author: Jonathan Karras