sophie/nuke
1
0
Fork 0
Code Packages 1 Activity Actions

docs/admin/installation: Apache documentation (#290)

Browse source 
* docs/admin/installation: Apache documentation

Closes #277

This adds step by step documentation for setting up Anubis in Apache.

* docs/admin/installation: add selinux troubleshooting

Signed-off-by: Xe Iaso <me@xeiaso.net>

---------

Signed-off-by: Xe Iaso <me@xeiaso.net>
This commit is contained in:
Xe Iaso 2025-04-19 10:23:56 -04:00 • committed by GitHub
parent a40c5e99fc
commit f5827721c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 143 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

142
docs/docs/admin/installation.mdx
View file

@ -4,6 +4,9 @@ title: Setting up Anubis
import RandomKey from "@site/src/components/RandomKey";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Anubis is meant to sit between your reverse proxy (such as Nginx or Caddy) and your target service. One instance of Anubis must be used per service you are protecting.
<center>
@ -76,6 +79,143 @@ Alternatively here is a key generated by your browser:
<RandomKey />
## Apache
Anubis is intended to be a filter proxy. The way to integrate this with nginx is to break your configuration up into two parts: TLS termination and then HTTP routing. Consider this diagram:
```mermaid
flowchart LR
T(User Traffic)
subgraph Apache 2
TCP(TCP 80/443)
US(TCP 3001)
end
An(Anubis)
B(Backend)
T --> |TLS termination| TCP
TCP --> |Traffic filtering| An
An --> |Happy traffic| US
US --> |whatever you're doing| B
```
Effectively you have one trip through Apache to do TLS termination, a detour through Anubis for traffic scrubbing, and then going to the backend directly. This final socket is what will do HTTP routing.
:::note
These examples assume that you are using a setup where your nginx configuration is made up of a bunch of files in `/etc/httpd/conf.d/*.conf`. This is not true for all deployments of Apache. If you are not in such an environment, append these snippets to your `/etc/httpd/conf/httpd.conf` file.
:::
Install the following dependencies:
<Tabs>
<TabItem value="rpm" label="Red Hat / RPM" default>
```text
dnf -y install mod_proxy_html
```
</TabItem>
<TabItem value="deb" label="Debian / Ubuntu / apt">
```text
apt-get install -y libapache2-mod-proxy-html libxml2-dev
```
</TabItem>
</Tabs>
Assuming you are protecting `anubistest.techaro.lol`, you need the following server configuration blocks:
1. A block on port 80 that forwards HTTP to HTTPS
2. A block on port 443 that terminates TLS and forwards to Anubis
3. A block on port 3001 that actually serves your websites
```text
# Plain HTTP redirect to HTTPS
<VirtualHost *:80>
ServerAdmin your@email.here
ServerName anubistest.techaro.lol
DocumentRoot /var/www/anubistest.techaro.lol
ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
RewriteEngine on
RewriteCond %{SERVER_NAME} =anubistest.techaro.lol
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
# HTTPS listener that forwards to Anubis
<VirtualHost *:443>
ServerAdmin your@email.here
ServerName anubistest.techaro.lol
DocumentRoot /var/www/anubistest.techaro.lol
ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
SSLCertificateFile /etc/letsencrypt/live/anubistest.techaro.lol/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/anubistest.techaro.lol/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
# These headers need to be set or else Anubis will
# throw an "admin misconfiguration" error.
RequestHeader set "X-Real-Ip" expr=%{REMOTE_ADDR}
RequestHeader set X-Forwarded-Proto "https"
ProxyPreserveHost On
ProxyRequests Off
ProxyVia Off
# Replace 9000 with the port Anubis listens on
ProxyPass / http://[::1]:9000/
ProxyPassReverse / http://[::1]:9000/
</VirtualHost>
</IfModule>
# Actual website config
<VirtualHost *:3001>
ServerAdmin your@email.here
ServerName anubistest.techaro.lol
DocumentRoot /var/www/anubistest.techaro.lol
ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
</VirtualHost>
```
Make sure to add a separate configuration file for the listener on port 3001:
```text
# /etc/httpd/conf.d/listener-3001.conf
Listen 3001
```
This can be repeated for multiple sites. Anubis does not care about the HTTP `Host` header and will happily cope with multiple websites via the same instance.
Then reload your Apache config and load your website. You should see Anubis protecting your apps!
```text
sudo systemctl reload httpd.service
```
### I'm running on a Red Hat distribution and Apache is saying "service unavailable" for every page load
If you see a "Service unavailable" error on every page load and run a Red Hat derived distribution, you are missing a `selinux` setting. The exact command will be in a log message like this:
```text
***** Plugin catchall_boolean (89.3 confidence) suggests ******************
If you want to allow HTTPD scripts and modules to connect to the network using TCP.
Then you must tell SELinux about this by enabling the 'httpd_can_network_connect' boolean.
Do
setsebool -P httpd_can_network_connect 1
```
This will fix the error immediately.
## Docker compose
Add Anubis to your compose file pointed at your service:
@ -342,6 +482,8 @@ upstream anubis {
}
```
This can be repeated for multiple sites. Anubis does not care about the HTTP `Host` header and will happily cope with multiple websites via the same instance.
Then reload your nginx config and load your website. You should see Anubis protecting your apps!
```text