Vicarian is a TLS-first reverse proxy server with built-in ACME support. It is currently targeted at self-hosting and SOHO installations; in particular it supports provisioning TLS certificates behind-the-firewall via ACME DNS-01 and the zone-update library.
Vicarian aims to have sensible defaults without additional configuration.
This software should be consider pre-alpha; the feature-set is MVP and is still in active development. It should not be considered production-ready and no warranty is expressed or implied. It is very-much a work-in-progress and virtually every part of it subject to change without notice.
Only Linux is currently supported (x86_64 and Arm64). Testing for other platforms is welcome.
- TLS-first: Port-80/HTTP can be enabled, but will always redirect to the configured TLS server. The exception to this is when the HTTP-01 ACME is enabled; Vicarian will serve any challenge responses directly.
- Native ACME Support: Vicarian has first-class support for
ACME/LetsEncrypt, including DNS-01. LetEncrypt certificate
profiles are supported;
tlsserveris the default. - Multiple DNS Providers: Multiple DNS providers are supported for DNS-01 via the zone-update sibling-project. See that project for a list of supported providers. (Contributions of provider support are very welcome.)
- Dynamic Certificate Loading: Where TLS certificates are maintained externally Vicarian will dynamically reload certificates when they are updated.
- Simple backend routing: Traffic can be routed to multiple backend services based on URL paths.
- Basic path rewriting: This may work with some simple apps that don't support contexts natively, but is likely to fail with more complex apps that have hardcoded paths.
- Virtual hosts: Hosting of multiple domains and domain aliases is supported, along with certificate generation for host aliases.
- Separated secrets: ACME DNS requires DNS-provider secrets to be configured. These can be placed in a separate secure file using systemd EnvironmentFile and corn environment injection (see vicarian-dns01.corn for an example).
- Wildcards: Wildcard ACME certificate generation.
-
Access & error logs
-
Happy Eyeballs support
-
Static file support. Pingora itself doesn't support static-files. There are 3rd-party crates that support this but they appear unmaintained at the moment and will need to be evaluated. If you wish to serve a static website one workaround is to use
static-web-serverto create a static backend:static-web-server \ --host 127.0.0.1 --port 8080 \ --security-headers true \ --log-level info \ --root .This is how vicarian.org and haltcondition.net are served currently.
-
Docker images.
The following may be implemented at some point depending on interest and resources.
- TLS-ALPN-01 ACME support.
- Other ACME providers (e.g. ZeroSSL)
- Prometheus stats.
- HTTP3/Quic support.
- h2c backend support (avoids a lot of proxy security corner-cases, but there's not much support in backend server software).
- Basic 12-factor-style configuration. This should be relatively easy due to corn's support for environment injection; however there is a known issue limiting this currently.
Vicarian is very opinionated and tries to do the sensible thing by
default. Ideally if a particular header or setting was usually required by, say,
nginx then it should be the default. e.g. X-Forwarded-For and
HSTS
are always set. Consequently there are no plans to add a large number of
features and settings.
Other notable non-features:
- Load-balancing, round-robin, complex rewrite rules, etc.
- Advanced connection tuning
Tarballs are available on the Github release page. These contain binaries, documentation, example configuration files, and an example systemd configuration:
├── bin
│ └── vicarian
├── CONFIGURATION.md
├── etc
│ ├── systemd
│ │ └── system
│ │ └── vicarian.service
│ └── vicarian
│ ├── examples
│ │ ├── vicarian-dns01.corn
│ │ ├── vicarian-http01.corn
│ │ └── vicarian-tls-files.corn
│ ├── secrets
│ └── vicarian.corn
├── LICENSE
└── README.md
cargo install vicarianThe binary will be available at
~/.crates/bin/vicarian. cargo-binstall
is also supported.
An example systemd service in provided in systemd/vicarian.service. The
systemd service sets the CAP_NET_BIND_SERVICE flag which allows binding to
ports 80/443 without root.
Vicarian currently uses the corn configuration
language. The default configuration file is located at
/etc/vicarian/vicarian.corn, but can be changed with the --config flag.
The full configuration structure is documented in
CONFIGURATION.md, and additional examples are available in
the examples directory, but a basic working configuration with HTTP-based
Let's Encrypt TLS would look like:
{
listen = {
addrs = [
"[::]" // Default; this covers IPv4 & IPv6
]
insecure_port = 80 // Disabled by default, this will redirect to HTTPS
tls_port = 443 // Default
}
vhosts = [
{
hostname = "example.com"
tls = {
acme = {
contact = "admin@example.com"
challenge.type = "http-01"
}
}
backends = [
{
context = "/"
url = "http://localhost:8080"
}
{
context = "/app2"
url = "https://localhost:8443"
trust = true
}
]
}
]
}
Contributions, bug reports, fixes, etc. are welcome.
Additionally, a useful contributions would be to add additional DNS provider APIs to the zone-update project.
The project follows the Rust Code of Conduct; this can be found online.
As well as the usual dependencies Vicarian also uses:
- Pingora for HTTP/TLS proxying.
- instant-acme for ACME/LetEncrypt support.
- path-tree for routing.
- corn for configuration.
This project will not accept runtime code generated by AI. Generation of draft documentation and test code is acceptable, but should be reviewed by the submitter before raising a PR.
- Vicarian binds to ports 80 and 443 by default, requiring appropriate permissions
- The systemd service uses
CAP_NET_BIND_SERVICEto bind to privileged ports without full root privileges - Private keys are stored in PEM format and should be properly secured
- When using ACME with DNS-01 challenges, ensure DNS provider API credentials are stored securely
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.