72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# wireguard-admin
|
||
|
||
This repository contains the initial Rust package, startup boundary, validated
|
||
settings loader, client domain model, and a pure in-memory WireGuard server
|
||
configuration parser/editor. The terminal management interface, file
|
||
persistence, vault, client import workflow, backups, and VPN operations have not
|
||
been implemented yet.
|
||
|
||
The package requires Rust 1.97.1 or newer and uses the Rust 2024 edition. From
|
||
the repository root, run:
|
||
|
||
```sh
|
||
cargo run -- --help
|
||
cargo run -- --version
|
||
```
|
||
|
||
`--help` and `--version` work without root. Starting with no arguments requires
|
||
root; until the management interface is implemented, startup exits with an
|
||
error and does not read server configuration or vault files.
|
||
|
||
## Settings
|
||
|
||
Settings use TOML in the fixed file `wireguard-admin.toml` beside the
|
||
executable. Start from [`config/wireguard-admin.example.toml`](config/wireguard-admin.example.toml).
|
||
The required fields are:
|
||
|
||
- `interface_name`: existing WireGuard interface name (1–15 ASCII characters).
|
||
- `server_config_path`: path to the existing server configuration.
|
||
- `client_source_directory`: directory containing existing client files.
|
||
- `server_endpoint`: hostname or IPv4 address followed by `:port`, or IPv6 in
|
||
brackets followed by `:port` (for example, `[2001:db8::2]:51820`).
|
||
- `ipv4_allocation_range` and `ipv6_allocation_range`: CIDR ranges of the
|
||
matching address family.
|
||
- `dns_addresses`: non-empty list of IPv4 and/or IPv6 literal addresses.
|
||
- `systemd_unit`: service unit name ending in `.service`.
|
||
- `restart_timeout_seconds`: positive integer.
|
||
|
||
`data_root` is optional. It defaults to `Backup` beside the executable;
|
||
current internal data and the encrypted vault are under `data`, and archives
|
||
are under `archives`. Relative configured paths, including an explicit
|
||
`data_root`, resolve from the executable directory. Absolute paths remain
|
||
absolute. Settings validation checks syntax and values only; it does not
|
||
require the referenced files, directories, or service to exist and does not
|
||
perform DNS lookups.
|
||
|
||
## Library configuration API
|
||
|
||
The library exposes `wireguard_admin::wireguard::ConfigDocument` for UTF-8
|
||
configuration bytes supplied by the caller. It retains the source and renders
|
||
unmodified input byte-for-byte, including line endings and a missing final
|
||
newline. Peer inspection exposes public identities, parsed `AllowedIPs`, spans,
|
||
and redacted issues; arbitrary directive values are not included in the view.
|
||
The edit methods `add_client`, `delete_client`, `rename_client`, and
|
||
`insert_legacy_metadata` return new in-memory documents. They do not read or
|
||
write files, save changes, or alter the running VPN. See
|
||
[`docs/CONFIG_FORMAT.md`](docs/CONFIG_FORMAT.md) for the managed metadata block
|
||
format.
|
||
|
||
Example:
|
||
|
||
```rust,ignore
|
||
use wireguard_admin::wireguard::ConfigDocument;
|
||
|
||
let document = ConfigDocument::parse(config_bytes)?;
|
||
let updated = document.rename_client(&public_key, "office laptop")?;
|
||
let bytes_to_review = updated.render(); // no persistence or VPN operation
|
||
```
|
||
|
||
Management startup still exits with an explicit “not implemented” error after
|
||
its root check; the library APIs are not yet connected to a management session.
|
||
|