Versions Compared

Version Old Version 65 New Version Current
Changes made by

Charles Wernicke

Charles Wernicke

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • This tool will configure your REST API proxy to the standard, well-known port 443.

  • Port 443 is the standard TLS/SSL port exposed used by secure (HTTPS) websites.

Note
Prerequisites before

BEFORE using install-reverse-proxy

:

  1. Open port 80 (HTTP) in UFW to

...

  1. expose the Let’s Encrypt certbot domain-control-check.

    1. See: Configuring Server Firewalls

  2. Open port 443 in UFW to expose

...

  1. HTTPS.

    1. See: Configuring Server Firewalls

  2. You must own and control a valid DNS domain,

    1. for example,

...

    1. yourcasdomain.com must resolve (to your CAS public IP).

    2. See below: Create an “A” record

    3. The script will fail if you cannot supply a valid DNS domain. If the script fails for this reason, then:

      1. add the domain (e.g

...

      1. . yourcasdomain.com) to your DNS records, and

      2. add the subdomain (e.g. agent86.yourcasdomain.com), and

      3. run sudo certbot --nginx to try again.

  2. The /batm/config/hostname file must point to that valid domain to be used.

    1. See: https://generalbytes.atlassian.net/wiki/x/CICpz

    2. The batm-manage script will fail if this file is missing. If the file is missing:

      1. create the file (with the correct contents),

      2. restart CAS, and

      3. run install-reverse-proxy again.

  3. Disable version reporting in NGINX to improve security:

    1. Edit the file: sudo nano /etc/nginx/nginx.conf

    2. Find the line: # server_tokens off;

    3. Delete the leading hashtag “#" (only the hashtag) to disable version reporting.

    4. Exit & save the file (Ctrl+X, then “y”).

    5. Test the configuration and restart NGINX: sudo nginx -t && sudo systemctl reload nginx

...

Testing

Enter one of the following testing URLs into a browser.

...

These instructions are provided for finer control over your installation, modification of the installation, and troubleshooting. The automated instructions are recommended for most situations.

Install NGINX

Warning

DO NOT use your CAS host as a web server.

Although NGINX is a web server, it’s used (in this context) as a proxy server only. Web services are notorious for being hackable (and hacked) - and knowingly exposing your CAS server to attack is irresponsible. Keep web content off your CAS host.

Partial source (and more info): https://www.digitalocean.com/community/tutorials/how-to-configure-nginx-as-a-reverse-proxy-on-ubuntu-22-04

1. Install the APT 1. Install the APT package NGINX:

Code Block
sudo apt update && sudo apt install nginx

...

  • Replace "yourcasdomain.com" with your registered (and active) domain name.

  • The subdomain “agent86” can be replaced with any RFC 952 compliant text.

  • Modify the example master service bound IP “10.3.2.1" as needed.

    • This example presents a typical case and 10.3.2.1 is usually correct.

    • Port 7743 always remains the same.

  • Press CTRL-X to save the file and exit (leave the filename unchanged).

...

Note

If you use a Cloudflare tunnel, do not conflict this DNS entry with the tunnel name. You do not need to use both NGINX and the cloudflared tunnel (they serve the same purpose) anyway.

...

If you already have certificates from a CA, then you should install those certificates as instructed by the provider. This article does not address that topic.

Example Certificate Authority: https://www.digicert.com/tls-ssl/compare-certificates

For this example we’ll install certbot from Let’s Encrypt to do the work for us.

...

  • Enter your email & agree to the terms (if offered).

  • When NGINX is properly configured, the “agent86” subdomain (in this example) will should be automatically suggested by Let’s Encrypt (and the proper server block thus modified).

  • (warning) If the challenge fails, check your firewall and DNS records.

...

b) Restart NGINX:

...

    • Any subdomain(s) may also be specified in the Let’s Encrypt certification process,

      • e.g. sudo certbot --nginx -d yourcasdomain.com - d agent86.yourcasdomain.com

      • or to add a subdomain after certification:

        • sudo certbot certonly --expand -d yourcasdomain.com - d agent86.yourcasdomain.com

  • (warning) If the challenge fails, check your firewall and DNS records.

...

b) Restart NGINX:

Code Block
sudo nginx -t && sudo systemctl restart nginx

...

Using a Cloudflare Certificate and Key

Cloudflare offers free site origin certificates when using their DNS services. These certificates are valid for up to 15 years. After following Let’s Encrypt instructions, replace with Cloudflare files to enable “Full (strict) - SSL/TLS” encryption modes with Cloudflare.

First, create the certificate and key(at Cloudflare), then download them to: /etc/ssl/private/

Edit the NGINX server block:

Code Block
sudo nano /etc/nginx/conf.d/cas-rest-api.conf

Then add 2 lines to the NGINX server block to point to the 2 files:

Code Block
ssl_certificate /etc/ssl/private/whatever.cloudflare.pem;
ssl_certificate_key /etc/ssl/private/whatever.cloudflare.key;

Disable the existing “ssl_certificate“ and “ssl_certificate_key“ by placing a hashtag “#” at the beginning of the each line, like this:

Code Block
ssl_certificate /etc/ssl/private/whatever.cloudflare.pem;
ssl_certificate_key /etc/ssl/private/whatever.cloudflare.key;

# ssl_certificate /etc/letsencrypt/live/agent86.yourcasdomain.com/fullchain.pem; # managed by Certbot
# ssl_certificate_key /etc/letsencrypt/live/agent86.yourcasdomain.com/privkey.pem; # managed by Certbot

  • Save & exit (Ctrl+X, “y”)

After replacing the Let’s Encrypt certificates, certbot can be disabled (or uninstalled).

Uninstall certbot:

Code Block
sudo snap remove certbot

...

...

CAS Admin

Note

While possible, we strongly discourage exposing the Admin service.

Use the VPN to access CAS over the Internet: Admin OpenVPN (using batm-manage)

or: https://generalbytes.atlassian.net/wiki/x/AYCxsw

  • Using a proxy server to access CAS Admin increases risk and is no longer suggesteddiscouraged.

  • Protecting the Admin interface behind a VPN is far stronger protection for your operation.

...