From f5827721c372a0d1775b7b2095cde17b59495cc3 Mon Sep 17 00:00:00 2001 From: Xe Iaso Date: Sat, 19 Apr 2025 10:23:56 -0400 Subject: docs/admin/installation: Apache documentation (#290) * 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 --------- Signed-off-by: Xe Iaso --- docs/docs/CHANGELOG.md | 1 + docs/docs/admin/installation.mdx | 142 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+) (limited to 'docs') diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index 94cf468..f2ff353 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added FreeBSD rc.d script so can be run as a FreeBSD daemon. - Allow requests from the Internet Archive - Added example nginx configuration to documentation +- Added example Apache configuration to the documentation [#277](https://github.com/TecharoHQ/anubis/issues/277) ## v1.16.0 diff --git a/docs/docs/admin/installation.mdx b/docs/docs/admin/installation.mdx index 8a608b9..2b12d76 100644 --- a/docs/docs/admin/installation.mdx +++ b/docs/docs/admin/installation.mdx @@ -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.
@@ -76,6 +79,143 @@ Alternatively here is a key generated by your browser: +## 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: + + + + +```text +dnf -y install mod_proxy_html +``` + + + + +```text +apt-get install -y libapache2-mod-proxy-html libxml2-dev +``` + + + + +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 + + 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] + + +# HTTPS listener that forwards to Anubis + + 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/ + + + +# Actual website config + + 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 + +``` + +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 -- cgit v1.2.3