gru/PostfixAdminRS
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.0

Browse Source
This commit is contained in:
Mateusz Gruszczyński committed 2026-11-04 08:55:53 +01:00
1 parent cdca612a59
commit eb25f8de4a
56 files changed
+7848 -4345
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+120 -173
View File
@@ -1,194 +1,141 @@
# PostfixAdmin-RS
Rustowy panel administracyjny dla Postfix/Dovecot, rozwijany jako zamiennik runtime PHP PostfixAdmin i zgodny z jego istniejaca baza danych.
Panel administracyjny serwera poczty Postfix/Dovecot napisany w Rust — zamiennik
PHP-owego [PostfixAdmin](https://github.com/postfixadmin/postfixadmin), działający
na **tej samej bazie danych** (MySQL/MariaDB, PostgreSQL, SQLite). Postfix, Dovecot,
`vacation.pl` i `fetchmail.pl` korzystają z tabel dokładnie tak jak przy PHP-owym
PostfixAdminie, więc panel można podmienić bez migracji danych.
Aktualna linia developerska: **0.0.3**. Projekt jest przypiety do **Rust 1.99.1**, edition 2024. Frontend jest osadzony w pojedynczym binarnym pliku; bundlowanie assetow, sprite SVG i workflow developerski sa wzorowane na przekazanym RustBox. Stary wyglad PostfixAdmin nie jest kopiowany.
Wersja: **0.1.0** · referencja logiki: PostfixAdmin 4.0.5 + gałąź `master` (schemat bazy 1857).
## Development bez produkcyjnej bazy
Jeden statyczny plik binarny z wbudowanym interfejsem (EN/PL, jasny/ciemny motyw,
działa na telefonie), bez PHP, bez serwera aplikacji, bez zależności w runtime.
Domyslny `dev.sh` nie potrzebuje MySQL/PostgreSQL. Uzywa izolowanego SQLite w `.dev/postfixadmin-rs.sqlite` i przy pierwszym starcie tworzy mock schematu PostfixAdmin z danymi testowymi:
## Funkcje
| Obszar | Zachowanie |
|---|---|
| Domeny | limity aliasów/skrzynek (`-1` = wyłączone, `0` = bez limitu), quota domeny i maks. quota skrzynki, transport, backup MX, wygasanie haseł, status DNS, domyślne aliasy przy tworzeniu, kasowanie domeny z wszystkimi danymi |
| Lista wirtualna | widok domeny jak `list-virtual.php`: domeny aliasowe, aliasy, skrzynki, wyszukiwanie, stronicowanie, filtr aktywne/nieaktywne, przełączanie aktywności jednym kliknięciem, „usuń nieaktywne”, statusy (niedostarczalny, zewnętrzny, autoresponder, wyłączona, hasło wygasło, POP/IMAP) |
| Skrzynki | reguły quota identyczne z `MailboxHandler::check_quota()`/`allowed_quota()` (podpowiedź „maks. N MB” w formularzu), generowanie hasła, potwierdzenie hasła, SMTP on/off, e-mail do odzyskiwania, wiadomość powitalna (w tle), maildir zgodny z `domain_path`/`domain_in_mailbox`, hooki po utworzeniu/edycji/usunięciu/zmianie hasła |
| Przekierowania | alias skrzynki („przekaż i zachowaj”), z uprawnieniami `alias_control` / `alias_control_admin` / `edit_alias` jak w PostfixAdminie |
| Aliasy | catch-all (`*` → `@domena`), przekierowanie całej domeny, konto lokalne (`root`), blokada aliasu wskazującego na siebie, `emailcheck_localaliasonly`, chronione aliasy domyślne (`special_alias_control`), zapamiętany domyślny cel |
| Domeny aliasowe | z ochroną przed łańcuchami i pętlami |
| Administratorzy | globalni i domenowi, przypisanie domen, aktywacja, reset hasła |
| Autoresponder | tabela `vacation` + alias transportu `user#domena@vacation_domain`, data i godzina od/do, `vacation_choice_of_reply`, czyszczenie `vacation_notification` |
| Panel użytkownika | podgląd skrzynki i quota, przekierowania, autoresponder, zmiana hasła, zmiana nazwy (`edit_mailbox_name`), 2FA, hasła aplikacji, filtry Sieve |
| Bezpieczeństwo | TOTP + wyjątki IP, hasła aplikacji, odzyskiwanie hasła e-mailem, limit prób logowania per IP/konto, CSRF, ciasteczka `HttpOnly`/`SameSite=Strict`/`Secure`, nagłówki CSP/HSTS, wylogowanie innych sesji po zmianie hasła, rewalidacja sesji (wyłączone konto lub odebrane uprawnienia działają natychmiast) |
| Inne | fetchmail (hasło base64 jak w PostfixAdmin), dziennik zmian z filtrem domen i stronicowaniem, wysyłanie poczty / wiadomość do wszystkich, kopia zapasowa bazy, DKIM (tabele PostfixAdmin/OpenDKIM oraz Rspamd), ManageSieve |
| Hasła | wszystkie formaty PostfixAdmin (ARGON2ID/I, BLF-CRYPT, SHA512-CRYPT, MD5-CRYPT, `php_crypt:*`, `md5crypt`, SSHA, Courier, Authlib, `dovecot:*` …) — format zapisany w rekordzie ma pierwszeństwo, więc stare i nowe hashe mogą współistnieć |
Szczegółowe porównanie z PHP: [PORT-PARITY.md](PORT-PARITY.md).
## Instalacja produkcyjna
### 1. Budowanie
```bash
bash dev.sh
cargo build --release --locked # wynik: target/release/postfixadmin-rs
# albo pakiet Debiana (w Dockerze):
./scripts/build-deb.sh # wynik: packages/postfixadmin-rs_*.deb
```
Konta testowe:
```text
admin@example.test / admin123 # global-admin
domain-admin@example.test / domain123 # admin example.test
user@example.test / user123 # mailbox user
```
Reset mock DB oraz developerskiego mocka Rspamd DKIM:
### 2. Konfiguracja
```bash
install -d -m 0750 -g postfixadmin /etc/postfixadmin-rs
install -m 0640 -g postfixadmin config.example.toml /etc/postfixadmin-rs/config.toml
$EDITOR /etc/postfixadmin-rs/config.toml
```
Najważniejsze ustawienia:
- `[database]` – dane bazy używanej przez Postfix/Dovecot. Hasło można podać w
`/etc/default/postfixadmin-rs` jako `POSTFIXADMIN_RS__DATABASE__PASSWORD=...`.
- `[password] scheme` – **musi** odpowiadać temu, co obsługuje Dovecot
(`default_pass_scheme`). Dla nowych instalacji: `ARGON2ID` lub `SHA512-CRYPT`.
- `[defaults] vacation_domain` – domena transportu autorespondera z `master.cf`.
- `[security]` – za nginx ustaw `trusted_proxies = ["127.0.0.1", "::1"]`,
`cookie_secure = true`, `hsts = true`.
### 3. Baza danych
```bash
export POSTFIXADMIN_RS_CONFIG=/etc/postfixadmin-rs/config.toml
postfixadmin-rs --init-schema --dry-run # co zostałoby zmienione
postfixadmin-rs --init-schema # tworzy brakujące tabele/kolumny/indeksy
postfixadmin-rs --create-superadmin admin@example.com # hasło ze stdin lub POSTFIXADMIN_RS_ADMIN_PASSWORD
postfixadmin-rs --check-config
```
`--init-schema` zastępuje `setup.php`/`upgrade.php`: na pustej bazie tworzy pełny
schemat PostfixAdmin (wersja 1857), na istniejącej tylko dodaje brakujące elementy —
nigdy niczego nie usuwa. Jest idempotentne.
### 4. Usługa i reverse proxy
```bash
install -m 0644 packaging/postfixadmin-rs.service /etc/systemd/system/
systemctl daemon-reload && systemctl enable --now postfixadmin-rs
```
Przykład nginx z TLS, HSTS i limitem logowań: [packaging/nginx.conf.example](packaging/nginx.conf.example).
Aplikacja nasłuchuje tylko na `127.0.0.1:8080`; publicznie wystawiony jest wyłącznie nginx.
### 5. Zadania okresowe (opcjonalnie)
```cron
# odświeżanie statusu DNS domen (odpowiednik scripts/domain-dns-check.php)
17 3 * * * postfixadmin POSTFIXADMIN_RS_CONFIG=/etc/postfixadmin-rs/config.toml /usr/bin/postfixadmin-rs --refresh-dns
```
## Migracja z PHP PostfixAdmin
1. Kopia zapasowa bazy oraz konfiguracji Postfix/Dovecot/PostfixAdmin.
2. Przenieś ustawienia z `config.local.php` do `config.toml`
(`$CONF['encrypt']` → `password.scheme`, `$CONF['vacation_domain']`, `default_aliases`, limity, `quota_multiplier` …).
Przykład odwzorowania: [config.from-user.toml](config.from-user.toml).
3. `postfixadmin-rs --init-schema --dry-run`, a potem bez `--dry-run`
(dodaje tylko brakujące kolumny nowszych wersji PostfixAdmin).
4. Uruchom panel równolegle (inny vhost), sprawdź logowanie, listy i jedną domenę testową.
5. Przełącz reverse proxy, a PHP/FPM wyłącz na końcu.
Konta administratorów i skrzynek oraz ich hasła działają bez zmian.
## Polecenia
```
postfixadmin-rs uruchamia serwer
postfixadmin-rs --check-config sprawdza konfigurację, połączenie i schemat
postfixadmin-rs --init-schema tworzy/aktualizuje schemat (--dry-run: tylko raport)
postfixadmin-rs --integrity-check osierocone rekordy (tylko odczyt)
postfixadmin-rs --create-superadmin EMAIL
postfixadmin-rs --refresh-dns odświeża status DNS wszystkich domen
postfixadmin-rs --version | --help
```
## Rozwój
```bash
bash dev.sh # izolowana baza SQLite z danymi testowymi
POSTFIXADMIN_RS_DEV_RESET=1 bash dev.sh
```
`database.dev_mock=true` jest dozwolone tylko z `environment="development"` i backendem SQLite. Produkcyjna baza nie jest potrzebna do pracy nad UI/API.
Konta testowe: `admin@example.test / admin123` (globalny), `domain-admin@example.test / domain123`
(admin `example.test`), `user@example.test / user123` (skrzynka). Tryb SSH do prawdziwej bazy
(domyślnie tylko do odczytu) opisuje `.env.example`.
Jesli chcesz testowac bezposrednio na produkcyjnej bazie przez SSH, `dev.sh` moze zestawic lokalny tunnel. Domyslnie taka sesja jest **read-only**. Najprosciej skopiowac gotowy przyklad dla `host.linuxiarz.pl`:
Testy:
```bash
cp .env.example .env
$EDITOR .env
bash dev.sh
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
python3 scripts/api-smoke.py http://127.0.0.1:8080 admin@example.test admin123 # test API na działającej instancji
python3 scripts/i18n/build.py # przebudowa katalogu PL + kontrola brakujących tłumaczeń
```
W `.env` uzupelnij co najmniej `POSTFIXADMIN_RS_DEV_DB_PASSWORD`. Przyklad jest dopasowany do testowego hosta: `root@host.linuxiarz.pl:11922`, MySQL/MariaDB, baza `postfix`, uzytkownik DB `postfix` i lokalny port tunelu `13306`.
Interfejs jest w `src/web` (zwykły JS/CSS, wbudowywany przez `build.rs`); teksty źródłowe
są po angielsku, tłumaczenia polskie w `scripts/i18n/pl_messages.py`.
Domyslny forward dla MySQL to `127.0.0.1:13306 -> 127.0.0.1:3306`, a dla PostgreSQL `127.0.0.1:15432 -> 127.0.0.1:5432`. Mozesz zmienic host/port po stronie serwera przez `POSTFIXADMIN_RS_DEV_DB_HOST` i `POSTFIXADMIN_RS_DEV_DB_PORT`. Weryfikacja host key SSH pozostaje wlaczona. Tunel uzywa `BatchMode=yes`, wiec przygotuj klucz/ssh-agent; opcjonalnie ustaw `POSTFIXADMIN_RS_SSH_IDENTITY` lub `POSTFIXADMIN_RS_SSH_KNOWN_HOSTS`.
Zapisy na produkcyjnej bazie wymagaja dodatkowego, jawnego opt-in:
```bash
POSTFIXADMIN_RS_DEV_DB_MODE=ssh POSTFIXADMIN_RS_DEV_DB_WRITES=1 bash dev.sh
```
W tym trybie aplikacja moze modyfikowac realne skrzynki/aliasy. Do zwyklych testow UI i odczytu schematu nie ustawiaj `POSTFIXADMIN_RS_DEV_DB_WRITES=1`.
## Co jest gotowe
- logowanie admin/mailbox, sesje HttpOnly/SameSite, CSRF i rate limit,
- global-admin, domain-admin i mailbox user,
- domeny, skrzynki, aliasy, alias-domains i masowe usuwanie nieaktywnych forwardow,
- limity domen, quota/domain quota, transport, backup MX i self-alias,
- fetchmail, vacation/autoreply zgodny z tabela `vacation`, log, sendmail/broadcast i backup DB,
- panel mailbox-user: wlasna quota/usage z DB, dane skrzynki, self-alias, bez odczytu IMAP,
- opcjonalny ManageSieve dla mailbox-user: lista/edycja/walidacja/aktywacja skryptow filtrow, prosty wizualny builder reguly + edytor raw, bez IMAP,
- admin preferences (m.in. domyslny cel aliasu),
- DKIM keys/signing, TOTP, TOTP exceptions, application passwords,
- Rspamd DKIM: generowanie kluczy, selector/path maps, configtest, podpinanie istniejacych kluczy i opcjonalny reload,
- `smtp_active`, password expiration i DNS status, gdy schema je udostepnia,
- bezpieczny natywny `maildir_template` zamiast PHP `maildir_name_hook`,
- automatyczne subfoldery przez `doveadm mailbox create`, jesli lista jest skonfigurowana,
- MySQL/MariaDB, PostgreSQL i SQLite przez SQLx Any,
- hooki wykonywane jako program + argumenty, bez `sh -c`,
- UI EN/PL z English jako domyslnym jezykiem; wybor z interfejsu jest zapamietywany w przegladarce, API pozostaje po angielsku.
Pelna macierz: [COMPATIBILITY.md](COMPATIBILITY.md). Audyt 1:1 wobec dostarczonego PHP 4.0.1: [PORT-PARITY.md](PORT-PARITY.md).
## Mailbox user, Vacation i ManageSieve
Panel zwyklego uzytkownika nie pokazuje administracyjnej listy modulow ani cudzych skrzynek. Overview pobiera tylko rekord zalogowanej skrzynki i jej self-alias. Quota/usage pochodzi z tabel PostfixAdmin/Dovecot (`mailbox`, opcjonalnie `quota`/`quota2`); aplikacja nie loguje sie do IMAP, zeby zbudowac ten widok.
Vacation pozostaje zgodny z PostfixAdmin: korzysta z tabeli `vacation` i ustawien `features.vacation` / `features.vacation_control`. Samo wlaczenie UI nie konfiguruje transportu/autorespondera po stronie Postfix/Dovecot, dlatego na istniejacym serwerze wlacz te flagi tylko wtedy, gdy mechanizm Vacation jest faktycznie skonfigurowany.
ManageSieve jest dodatkiem niezaleznym od mechanizmu Vacation PA. Konfiguracja:
```toml
[sieve]
enabled = true
host = "127.0.0.1"
port = 4190
tls_mode = "starttls" # starttls | implicit | none
allow_insecure_auth = false
timeout_secs = 10
read_only = false
```
Haslo mailbox-user jest przechowywane tylko w pamieci jego sesji, i tylko gdy Sieve jest wlaczone; nie trafia do JSON API ani logow. Po zmianie hasla credential sesji jest aktualizowany. Dla developerskiego testu przez SSH mozna wlaczyc drugi forward tym samym `dev.sh`:
```bash
POSTFIXADMIN_RS_DEV_SIEVE_ENABLED=true bash dev.sh
```
Domyslnie zewnetrzny ManageSieve przez dev tunnel jest read-only. Zapis wymaga osobnego `POSTFIXADMIN_RS_DEV_SIEVE_WRITES=1`; jest to niezalezne od `POSTFIXADMIN_RS_DEV_DB_WRITES`.
## Hasla zgodne z PostfixAdmin
Weryfikacja najpierw rozpoznaje format juz zapisany w rekordzie. Dzieki temu jedna baza moze zawierac stare i nowe hashe podczas migracji, bez masowego przepisywania kont.
Obslugiwane sa m.in.:
- `ARGON2ID`, `ARGON2ID.B64`, `ARGON2I`, `ARGON2I.B64`,
- `BLF-CRYPT`, `BLF-CRYPT.B64`, `CRYPT`,
- `SHA512-CRYPT`, `SHA512-CRYPT.B64`, legacy `SHA512.B64`, `SHA512`,
- `SHA256-CRYPT`, `SHA256-CRYPT.B64`, `SHA256`,
- `SHA1-CRYPT`, `SHA1`, `SHA1.B64`, `SHA`, `SSHA`,
- `MD5-CRYPT`, legacy `md5crypt`, `PLAIN-MD5`, `MD5`, `MD5RAW`,
- `AUTHLIB` (`md5raw`, `md5`, `SHA`, `crypt`),
- `courier:md5`, `courier:md5raw`, `courier:sha1`, `courier:ssha`, `courier:sha256`,
- `php_crypt:DES|MD5|BLOWFISH|SHA256|SHA512` z kompatybilnym difficulty/prefix,
- `dovecot:METHOD` jako kontrolowany fallback do `doveadm pw`, bez shella i bez hasla w argv,
- `PLAIN`, `CLEAR`, `cleartext` tylko dla zgodnosci/testow.
Testy zawieraja referencyjne wektory z dostarczonego `tests/PacryptTest.php`. Slabe formaty pozostaja tylko dla kompatybilnosci; nowych kont nie nalezy na nie migrowac bez potrzeby.
Dla przekazanego configu produkcyjnego pozostaje `php_crypt:MD5`, dopoki konfiguracja Dovecot/Postfix SASL nie zostanie zmieniona razem z panelem.
## Konfiguracja przekazanego serwera
`config.from-user.toml` odwzorowuje przekazany config PostfixAdmin, ale nie zawiera hasla bazy. Sekret podaj przez ENV:
```bash
export POSTFIXADMIN_RS_CONFIG="$PWD/config.from-user.toml"
export POSTFIXADMIN_RS__DATABASE__PASSWORD='...'
```
## Jezyki interfejsu
Frontend ma katalogi `src/web/i18n/en.json` i `src/web/i18n/pl.json`. `default_language = "en"` ustawia English jako pierwszy jezyk, a przelacznik w loginie i gornej belce zapisuje wybor w `localStorage`. Lokalizacja dotyczy tylko UI; endpointy, JSON i kody bledow API pozostaja angielskie.
## Build / release gate
```bash
./scripts/build-release.sh
```
Gate wykonuje walidacje statyczna, `cargo fmt --check`, testy, Clippy z `-D warnings` i release build z `Cargo.lock`.
## Migracja z PHP
1. Zrob backup bazy i konfiguracji Postfix/Dovecot/PostfixAdmin.
2. Najpierw testuj na kopii DB lub na mocku developerskim.
3. Na realnej DB uruchom `--check-config`, sprawdz logowanie i CRUD na domenie testowej.
4. Nie zmieniaj `password.scheme`, dopoki Dovecot/Postfix SASL nie obsluguje tego samego formatu.
5. Reverse proxy przelacz dopiero po testach regresyjnych; PHP/FPM usun na koncu.
## Status 0.0.3
To nadal wersja developerska, nie deklaruje jeszcze 100% parity PostfixAdmin 4.x. Pozostale luki to przede wszystkim webowy setup/upgrade schematu, XML-RPC, SMS provider, update checker oraz generic IMAP/Courier do tworzenia folderow. Dynamiczne hooki PHP (`*_struct_hook`, `language_hook`) nie beda uruchamiane jako PHP — wymagaja natywnego mechanizmu rozszerzen.
W tym srodowisku nie ma `cargo`/`rustc`; proba pobrania toolchaina 1.99.1 jest dodatkowo blokowana przez brak DNS/network, wiec realny `cargo check/test/clippy` nie mogl zostac wykonany tutaj. Statyczny gate jest uruchamiany przed spakowaniem, ale developerski build trzeba ostatecznie zweryfikowac przez `bash dev.sh` na maszynie z Rust 1.99.1. Checklista testowa: [TESTING.md](TESTING.md).
## Rspamd DKIM
Integracja Rspamd nie rozbudowuje recznie `domain { ... }`. Uzywa map `selector_map` i `path_map`, generuje klucze przez `rspamadm`, wykonuje `rspamadm configtest` przed zaakceptowaniem zmian i moze wykonac jawnie skonfigurowany argv-only reload. Instrukcja: [docs/RSPAMD_DKIM.md](docs/RSPAMD_DKIM.md).
### DKIM backends
The UI exposes PostfixAdmin database DKIM and Rspamd DKIM as separate backends. They can be enabled independently:
```toml
[features]
dkim = true
[dkim]
default_backend = "postfixadmin" # postfixadmin | rspamd
[rspamd_dkim]
enabled = true
```
When both are enabled, `dkim.default_backend` selects the tab opened first. Disabling one backend removes that tab from the UI.
Mailbox users can optionally see DKIM as a **read-only DNS view** for their own domain (`[dkim].user_read_only = true`). The view merges only public records from the PostfixAdmin DKIM tables and Rspamd. `default_backend` is only a UI preference for administrators; there is no shared/global DKIM key in this project. Every key/selector remains associated with a concrete domain.
When development uses the SSH database mode, `dev.sh` also forwards ManageSieve (`14190 -> 4190`) and, by default, builds a public-only Rspamd DKIM cache over SSH. The helper reads mapping/config metadata and derives the public key on the mail host; it never downloads private-key bytes. Disable this with `POSTFIXADMIN_RS_DEV_RSPAMD_PUBLIC_SYNC=false`.
### Domain-focused UI
`Domains` is the main entry point for domain administration. Clicking a domain opens a workspace with mailbox and alias usage, quota progress, mailboxes, aliases and alias-domain relationships. The standalone Mailboxes and Aliases pages show one domain at a time instead of rendering all domains at once.
## Local Debian package
For Debian-like systems, build a development `.deb` inside Docker:
```bash
./scripts/build-deb.sh
```
The builder uses Debian 12 as the compatibility baseline, installs the Rust toolchain pinned by `rust-toolchain.toml`, runs static validation, `cargo fmt --check`, tests and clippy, then writes the package and SHA256 file to `./packages/`. The resulting package installs the binary, a systemd service, `/etc/postfixadmin-rs/config.toml` and `/etc/default/postfixadmin-rs`. During installation it creates the unprivileged system user/group `postfixadmin`, runs the service as that identity, keeps `/etc/postfixadmin-rs` root-owned with group-read access for `postfixadmin`, and creates `/var/lib/postfixadmin-rs` for runtime state. It does not start the service automatically because database/Rspamd permissions must be configured first. Rspamd DKIM integration must be granted narrowly scoped write access to the configured key/map/config paths; do not run the whole service as root.
## Licencja
GPL-2.0-or-later, jak PostfixAdmin. Zob. [LICENSE](LICENSE) i [NOTICE.md](NOTICE.md).