{"id":196,"date":"2026-07-28T06:16:47","date_gmt":"2026-07-28T06:16:47","guid":{"rendered":"https:\/\/www.miniamju.com\/index.php\/apache-guacamole-part-2-publishing-the-gateway-through-nginx\/"},"modified":"2026-07-28T06:16:47","modified_gmt":"2026-07-28T06:16:47","slug":"apache-guacamole-part-2-publishing-the-gateway-through-nginx","status":"publish","type":"post","link":"https:\/\/www.miniamju.com\/index.php\/apache-guacamole-part-2-publishing-the-gateway-through-nginx\/","title":{"rendered":"Apache Guacamole Part 2: Publishing the Gateway through Nginx"},"content":{"rendered":"

Part 2 of 3: public DNS, TLS termination, WebSocket proxying, and backend
\nisolation.<\/em><\/p>\n

Part 1<\/a>
\nbuilt a private Guacamole gateway with PostgreSQL authentication, TOTP, and a
\nLAN-bound HTTP listener. This part publishes that listener through an existing
\nNginx reverse proxy without making the Docker backend directly available to
\nthe rest of the network.<\/p>\n

The finished request path is:<\/p>\n

browser\n   |\nHTTPS 443\n   v\nNginx reverse proxy\n   |\nprivate HTTP 8080\n   v\nGuacamole container\n<\/code><\/pre>\n
Nginx terminates TLS, supports Guacamole's long-lived WebSocket tunnel, and
\nforwards the original client address. A firewall rule then permits only Nginx
\nto reach the private Guacamole listener.<\/p>\n
All hostnames and addresses below are generic examples. Replace them with
\nvalues suitable for the local environment.<\/p>\n
\n
Why not expose port 8080 directly?<\/strong> The application listener is plain HTTP
\nand does not need to be reachable by users. Restricting it to the reverse
\nproxy creates one controlled public entry point for TLS, security headers,
\nlogging, certificate renewal, and later framing policy.<\/p>\n<\/blockquote>\n
Environment Used in This Guide<\/h2>\n\n\n\n\n\n\n\n\n\n\n
Item<\/th>\nExample<\/th>\n<\/tr>\n<\/thead>\n
Guacamole version<\/td>\n1.6.0<\/td>\n<\/tr>\n
Guacamole backend<\/td>\n10.20.30.223:8080<\/code><\/td>\n<\/tr>\n
Nginx reverse proxy<\/td>\n10.20.30.220<\/code><\/td>\n<\/tr>\n
Public hostname<\/td>\nremote.example.com<\/code><\/td>\n<\/tr>\n
Parent website allowed to frame Guacamole<\/td>\nhttps:\/\/www.example.com<\/code><\/td>\n<\/tr>\n
Certificate authority client<\/td>\nCertbot<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Before continuing, confirm that:<\/p>\n
    \n
  • the Part 1 containers are healthy;<\/li>\n
  • the private Guacamole listener returns HTTP 200;<\/li>\n
  • the replacement administrator and TOTP login have been tested;<\/li>\n
  • public DNS can be pointed to the Nginx edge;<\/li>\n
  • TCP 80 and 443 already reach Nginx from the internet.<\/li>\n<\/ul>\n
    1. Make Guacamole Reverse-Proxy Aware<\/h2>\n
    Guacamole runs in Tomcat. Without Tomcat's Remote IP Valve, application logs,
    \nlogin banning, and audit history can record the Nginx address instead of the
    \nreal browser address. The valve also tells Tomcat that the original request
    \nused HTTPS.<\/p>\n
    In the guacamole<\/code> service within \/opt\/guacamole\/compose.yaml<\/code>, confirm these
    \nenvironment values are present:<\/p>\n
          REMOTE_IP_VALVE_ENABLED: "true"\n      REMOTE_IP_VALVE_REMOTE_IP_HEADER: x-forwarded-for\n      REMOTE_IP_VALVE_PROTOCOL_HEADER: x-forwarded-proto\n      REMOTE_IP_VALVE_PROTOCOL_HEADER_HTTPS_VALUE: https\n      REMOTE_IP_VALVE_HTTP_SERVER_PORT: "80"\n      REMOTE_IP_VALVE_HTTPS_SERVER_PORT: "443"\n<\/code><\/pre>\n
    Do not override REMOTE_IP_VALVE_INTERNAL_PROXIES<\/code> unless the actual Docker
    \nnetwork path has first been inspected. Tomcat's default internal-proxy pattern
    \nalready covers the usual private Docker bridge ranges.<\/p>\n
    Validate Compose and recreate only the web application:<\/p>\n
    cd \/opt\/guacamole\n\ndocker compose config\ndocker compose up -d --force-recreate guacamole\ndocker compose ps\n<\/code><\/pre>\n
    Expected:<\/p>\n
    guacamole-postgres   Up and healthy\nguacamole-guacd      Up\nguacamole-web        Up\n<\/code><\/pre>\n
    Inspect the generated Tomcat configuration:<\/p>\n
    docker compose exec -T guacamole sh -c '\ngrep -n "RemoteIpValve" \/tmp\/catalina-base.*\/conf\/server.xml\n'\n<\/code><\/pre>\n
    Expected attributes include:<\/p>\n
    remoteIpHeader="x-forwarded-for"\nprotocolHeader="x-forwarded-proto"\nprotocolHeaderHttpsValue="https"\nhttpServerPort="80"\nhttpsServerPort="443"\n<\/code><\/pre>\n
    Check startup logs and the private listener:<\/p>\n
    docker compose logs --since=3m guacamole |\n  grep -iE 'error|exception|fatal' ||\n  echo "No Guacamole startup errors"\n\ncurl -sS -o \/dev\/null -w 'HTTP %{http_code}\\n' \\\n  http:\/\/10.20.30.223:8080\/\n<\/code><\/pre>\n
    Expected:<\/p>\n
    No Guacamole startup errors\nHTTP 200\n<\/code><\/pre>\n
    2. Create Public DNS<\/h2>\n
    Create an A<\/code> or AAAA<\/code> record for the chosen Guacamole hostname and point it
    \nto the public address that forwards TCP 80 and 443 to Nginx.<\/p>\n
    From a system using public DNS:<\/p>\n
    getent ahostsv4 remote.example.com\n<\/code><\/pre>\n
    Confirm the result is the intended public edge address. DNS does not need to
    \npoint directly to the Guacamole container.<\/p>\n
    3. Prepare the ACME Webroot<\/h2>\n
    On the Nginx reverse proxy:<\/p>\n
    install -d -o www-data -g www-data -m 0755 \\\n  \/var\/www\/letsencrypt\/.well-known\/acme-challenge\n<\/code><\/pre>\n
    Create an HTTP-only site before requesting the certificate:<\/p>\n
    cat > \/etc\/nginx\/sites-available\/remote.example.com <<'EOF'\nserver {\n    listen 80;\n    listen [::]:80;\n    server_name remote.example.com;\n\n    location ^~ \/.well-known\/acme-challenge\/ {\n        root \/var\/www\/letsencrypt;\n        default_type text\/plain;\n        try_files $uri =404;\n    }\n\n    location \/ {\n        return 301 https:\/\/$host$request_uri;\n    }\n}\nEOF\n\nln -sfn \/etc\/nginx\/sites-available\/remote.example.com \\\n  \/etc\/nginx\/sites-enabled\/remote.example.com\n\nnginx -t\nsystemctl reload nginx\n<\/code><\/pre>\n
    Expected:<\/p>\n
    syntax is ok\ntest is successful\n<\/code><\/pre>\n
    The HTTP redirect will not yet produce a working HTTPS page because the
    \ncertificate and TLS server block have not been created. The ACME challenge
    \npath remains available over HTTP.<\/p>\n
    4. Obtain a Dedicated TLS Certificate<\/h2>\n
    A separate certificate lineage keeps Guacamole certificate changes independent
    \nfrom unrelated services.<\/p>\n
    Install Certbot if it is not already present:<\/p>\n
    apt update\napt install -y certbot\n<\/code><\/pre>\n
    Request the certificate, replacing the example email address:<\/p>\n
    certbot certonly \\\n  --webroot \\\n  --webroot-path \/var\/www\/letsencrypt \\\n  --domain remote.example.com \\\n  --email administrator@example.com \\\n  --agree-tos \\\n  --no-eff-email \\\n  --key-type ecdsa\n<\/code><\/pre>\n
    Expected certificate paths:<\/p>\n
    \/etc\/letsencrypt\/live\/remote.example.com\/fullchain.pem\n\/etc\/letsencrypt\/live\/remote.example.com\/privkey.pem\n<\/code><\/pre>\n
    Inspect the result:<\/p>\n
    certbot certificates\n<\/code><\/pre>\n
    Do not copy the private key into the Guacamole container. TLS terminates only
    \nat Nginx.<\/p>\n
    5. Configure the Nginx Reverse Proxy<\/h2>\n
    Replace the temporary HTTP-only site with the complete configuration:<\/p>\n
    cat > \/etc\/nginx\/sites-available\/remote.example.com <<'EOF'\nserver {\n    listen 80;\n    listen [::]:80;\n    server_name remote.example.com;\n\n    location ^~ \/.well-known\/acme-challenge\/ {\n        root \/var\/www\/letsencrypt;\n        default_type text\/plain;\n        try_files $uri =404;\n    }\n\n    location \/ {\n        return 301 https:\/\/$host$request_uri;\n    }\n}\n\nserver {\n    listen 443 ssl;\n    listen [::]:443 ssl;\n    server_name remote.example.com;\n\n    ssl_certificate\n        \/etc\/letsencrypt\/live\/remote.example.com\/fullchain.pem;\n    ssl_certificate_key\n        \/etc\/letsencrypt\/live\/remote.example.com\/privkey.pem;\n\n    include \/etc\/letsencrypt\/options-ssl-nginx.conf;\n    ssl_dhparam \/etc\/letsencrypt\/ssl-dhparams.pem;\n\n    location \/ {\n        proxy_pass http:\/\/10.20.30.223:8080;\n        proxy_http_version 1.1;\n\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_set_header X-Forwarded-Port $server_port;\n\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection "upgrade";\n\n        proxy_buffering off;\n        proxy_request_buffering off;\n        proxy_read_timeout 3600s;\n        proxy_send_timeout 3600s;\n    }\n\n    add_header Strict-Transport-Security "max-age=15552000" always;\n    add_header X-Content-Type-Options "nosniff" always;\n    add_header Referrer-Policy "strict-origin-when-cross-origin" always;\n    add_header Content-Security-Policy\n        "frame-ancestors 'self' https:\/\/www.example.com" always;\n}\nEOF\n\nnginx -t\nsystemctl reload nginx\n<\/code><\/pre>\n
    The important Guacamole-specific settings are:<\/p>\n
      \n
    • HTTP\/1.1 for WebSocket upgrades;<\/li>\n
    • Upgrade<\/code> and Connection<\/code> headers for the interactive tunnel;<\/li>\n
    • disabled response and request buffering;<\/li>\n
    • long read and send timeouts;<\/li>\n
    • forwarded host, client address, protocol, and port.<\/li>\n<\/ul>\n
      The frame-ancestors<\/code> policy allows only Guacamole itself and the nominated
      \nparent website to embed the interface. Remove the external origin if embedding
      \nis not required. Do not use *<\/code>.<\/p>\n
      6. Validate the Public Endpoint<\/h2>\n
      From the Nginx host:<\/p>\n
      curl -sS -o \/dev\/null \\\n  -w 'HTTP %{http_code} redirect=%{redirect_url}\\n' \\\n  http:\/\/remote.example.com\/\n\ncurl -sS -D - -o \/dev\/null \\\n  https:\/\/remote.example.com\/\n<\/code><\/pre>\n
      Expected:<\/p>\n
      HTTP 301 redirect=https:\/\/remote.example.com\/\nHTTP\/1.1 200\n<\/code><\/pre>\n
      The HTTPS response should also contain:<\/p>\n
      Strict-Transport-Security: max-age=15552000\nX-Content-Type-Options: nosniff\nReferrer-Policy: strict-origin-when-cross-origin\nContent-Security-Policy: frame-ancestors 'self' https:\/\/www.example.com\n<\/code><\/pre>\n
      At this stage the browser should show the Guacamole login page through HTTPS.
      \nThe first actual remote-display WebSocket tunnel cannot be validated until
      \nPart 3 creates a connection.<\/p>\n
      7. Test the Backend Restriction Temporarily<\/h2>\n
      Publishing a Docker port creates forwarding rules outside a normal host
      \nINPUT<\/code> chain. Place the restriction in Docker's DOCKER-USER<\/code> chain so it is
      \nevaluated before Docker accepts forwarded traffic.<\/p>\n
      On the Guacamole container, add temporary rules:<\/p>\n
      iptables -I DOCKER-USER 1 \\\n  -i eth0 -p tcp -s 10.20.30.220 --dport 8080 \\\n  -j ACCEPT\n\niptables -I DOCKER-USER 2 \\\n  -i eth0 -p tcp --dport 8080 \\\n  -j DROP\n\niptables -nvL DOCKER-USER --line-numbers\n<\/code><\/pre>\n
      Expected order:<\/p>\n
      1 ACCEPT tcp from 10.20.30.220 to destination port 8080\n2 DROP   tcp from all sources to destination port 8080\n<\/code><\/pre>\n
      From the Nginx reverse proxy:<\/p>\n
      curl -sS -o \/dev\/null -w 'HTTP %{http_code}\\n' \\\n  http:\/\/10.20.30.223:8080\/\n<\/code><\/pre>\n
      Expected:<\/p>\n
      HTTP 200\n<\/code><\/pre>\n
      From another LAN system:<\/p>\n
      curl --connect-timeout 5 -sS -o \/dev\/null \\\n  -w 'HTTP %{http_code}\\n' \\\n  http:\/\/10.20.30.223:8080\/\n<\/code><\/pre>\n
      Expected:<\/p>\n
      connection timeout\nHTTP 000\n<\/code><\/pre>\n
      Confirm that the intended public route still works:<\/p>\n
      curl -sS -o \/dev\/null -w 'HTTP %{http_code}\\n' \\\n  https:\/\/remote.example.com\/\n<\/code><\/pre>\n
      Expected:<\/p>\n
      HTTP 200\n<\/code><\/pre>\n
      8. Make the Backend Restriction Persistent<\/h2>\n
      Docker recreates its own firewall rules when it restarts. A small systemd
      \nservice can recreate only the locally owned Guacamole policy afterward.<\/p>\n
      Create the script:<\/p>\n
      cat > \/usr\/local\/sbin\/guacamole-firewall <<'EOF'\n#!\/bin\/sh\nset -eu\n\nPATH=\/usr\/sbin:\/usr\/bin:\/sbin:\/bin\nPARENT_CHAIN="DOCKER-USER"\nWEB_CHAIN="GUAC-WEB"\nPROXY_IP="10.20.30.220"\nBACKEND_PORT="8080"\nLAN_INTERFACE="eth0"\n\nwait_for_docker_chain() {\n    attempts=0\n\n    until iptables -nL "$PARENT_CHAIN" >\/dev\/null 2>&1; do\n        attempts=$((attempts + 1))\n\n        if [ "$attempts" -ge 30 ]; then\n            echo "Timed out waiting for $PARENT_CHAIN" >&2\n            exit 1\n        fi\n\n        sleep 1\n    done\n}\n\nstart_rules() {\n    wait_for_docker_chain\n\n    iptables -N "$WEB_CHAIN" 2>\/dev\/null || true\n    iptables -F "$WEB_CHAIN"\n\n    iptables -A "$WEB_CHAIN" \\\n        -p tcp -s "$PROXY_IP" --dport "$BACKEND_PORT" \\\n        -j ACCEPT\n\n    iptables -A "$WEB_CHAIN" \\\n        -p tcp --dport "$BACKEND_PORT" \\\n        -j DROP\n\n    if ! iptables -C "$PARENT_CHAIN" \\\n        -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n        -j "$WEB_CHAIN" 2>\/dev\/null; then\n\n        iptables -I "$PARENT_CHAIN" 1 \\\n            -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n            -j "$WEB_CHAIN"\n    fi\n\n    while iptables -C "$PARENT_CHAIN" \\\n        -i "$LAN_INTERFACE" -p tcp -s "$PROXY_IP" \\\n        --dport "$BACKEND_PORT" -j ACCEPT 2>\/dev\/null; do\n\n        iptables -D "$PARENT_CHAIN" \\\n            -i "$LAN_INTERFACE" -p tcp -s "$PROXY_IP" \\\n            --dport "$BACKEND_PORT" -j ACCEPT\n    done\n\n    while iptables -C "$PARENT_CHAIN" \\\n        -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n        -j DROP 2>\/dev\/null; do\n\n        iptables -D "$PARENT_CHAIN" \\\n            -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n            -j DROP\n    done\n}\n\nstop_rules() {\n    if iptables -nL "$PARENT_CHAIN" >\/dev\/null 2>&1; then\n        while iptables -C "$PARENT_CHAIN" \\\n            -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n            -j "$WEB_CHAIN" 2>\/dev\/null; do\n\n            iptables -D "$PARENT_CHAIN" \\\n                -i "$LAN_INTERFACE" -p tcp --dport "$BACKEND_PORT" \\\n                -j "$WEB_CHAIN"\n        done\n    fi\n\n    if iptables -nL "$WEB_CHAIN" >\/dev\/null 2>&1; then\n        iptables -F "$WEB_CHAIN"\n        iptables -X "$WEB_CHAIN"\n    fi\n}\n\ncase "${1:-}" in\n    start)\n        start_rules\n        ;;\n    stop)\n        stop_rules\n        ;;\n    *)\n        echo "Usage: $0 {start|stop}" >&2\n        exit 2\n        ;;\nesac\nEOF\n\nchmod 0750 \/usr\/local\/sbin\/guacamole-firewall\n<\/code><\/pre>\n
      Create the systemd unit:<\/p>\n
      cat > \/etc\/systemd\/system\/guacamole-firewall.service <<'EOF'\n[Unit]\nDescription=Restrict Guacamole backend to the Nginx reverse proxy\nRequires=docker.service\nAfter=docker.service\nPartOf=docker.service\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=\/usr\/local\/sbin\/guacamole-firewall start\nExecStop=\/usr\/local\/sbin\/guacamole-firewall stop\nTimeoutStartSec=45\nTimeoutStopSec=15\n\n[Install]\nWantedBy=multi-user.target\nEOF\n<\/code><\/pre>\n
      Enable and inspect it:<\/p>\n
      systemctl daemon-reload\nsystemctl enable --now guacamole-firewall.service\n\nsystemctl is-enabled guacamole-firewall.service\nsystemctl is-active guacamole-firewall.service\nsystemctl status --no-pager guacamole-firewall.service\n\niptables -nvL DOCKER-USER --line-numbers\niptables -nvL GUAC-WEB --line-numbers\n<\/code><\/pre>\n
      Expected:<\/p>\n
      enabled\nactive\nDOCKER-USER rule 1 delegates eth0 TCP\/8080 to GUAC-WEB\nGUAC-WEB rule 1 accepts 10.20.30.220\nGUAC-WEB rule 2 drops all other TCP\/8080 sources\n<\/code><\/pre>\n
      Restart Docker to test persistence:<\/p>\n
      systemctl restart docker\n\nsystemctl is-active docker\nsystemctl is-active guacamole-firewall.service\n\ncd \/opt\/guacamole\ndocker compose ps\n\niptables -nvL DOCKER-USER --line-numbers\niptables -nvL GUAC-WEB --line-numbers\n<\/code><\/pre>\n
      Repeat the three access tests:<\/p>\n
      Nginx -> private backend: HTTP 200\nanother LAN host -> private backend: timeout \/ HTTP 000\npublic HTTPS -> Nginx -> private backend: HTTP 200\n<\/code><\/pre>\n
      9. Validate Authentication and Client Addressing<\/h2>\n
      Open https:\/\/remote.example.com\/<\/code> in a browser and complete:<\/p>\n
        \n
      1. the Guacamole username and password;<\/li>\n
      2. the TOTP challenge;<\/li>\n
      3. loading the authenticated dashboard.<\/li>\n<\/ol>\n
        Check the application logs during the test:<\/p>\n
        cd \/opt\/guacamole\n\ndocker compose logs --since=10m guacamole |\n  grep -iE 'error|exception|fatal' ||\n  echo "No Guacamole authentication errors"\n<\/code><\/pre>\n
        The Guacamole user-history entry should contain the actual browser address, not
        \nthe Nginx private address. Avoid publishing that address or the administrator
        \nusername in screenshots or articles.<\/p>\n
        Also test certificate renewal:<\/p>\n
        systemctl status --no-pager certbot.timer\ncertbot renew --dry-run\n<\/code><\/pre>\n
        Expected:<\/p>\n
        the renewal timer is active\nthe dry run completes successfully\n<\/code><\/pre>\n
        Completion Checks<\/h2>\n
        Part 2 is complete when:<\/p>\n