Reverse Proxy & Web Secure Socket

This section will guide you in setting up a reverse proxy for serving nym-node HTTP requests and to set up a custom landing page for your node.

In later sections, you will be setting up secure websocket (wss) to add additional security and encrypt connections coming to your node. Follow this guide for installation.

ℹ️

Since SSL certificates can only be issued for a domain name and not an IP address, it is essential for you to register a new domain name and configure a domain record pointing to your node's IP address

ℹ️

Our documentation often refer to syntax annotated in <> brackets. We use this expression for variables that are unique to each user (like path, local moniker, versions etcetra). Any syntax in <> brackets needs to be substituted with your correct name or version, without the <> brackets. If you are unsure, please check our table of essential parameters and variables (opens in a new tab).

⚠️

The commands in this setup need to be run with root permission. Either add a prefix sudo or execute them from a root shell.

Reverse Proxy Setup

Operators running nodes facing open internet may benefit from having a landing page. This page serves as a source of useful information about Nym network and the node when they try to search node IP or hostname.

HTML File Customization

File for html configuration are by convention located at /var/www/<HOSTNAME> directory and it's sub-directories. We refer to this directory as <LANDING_PAGE_ASSETS_PATH>.

1. Start by creating your directory landing page directory:
mkdir -p /var/www/<HOSTNAME>
2. Create html landing page
3. If you used the template above - before you save and close the file, make sure to edit the email address:
  • Change the email address you're willing to use for being contacted.
<a href="mailto:><YOUR_EMAIL_ADDRESS>">maintainer</a>
  • Additionally you can add your own favicon logo on the line:
<link rel="icon" type="YOUR_FAVICON_IMAGE_PATH" href="">
4. Save and exit

Now your html page is configured.

nym-node Configuration

When done with the customization, you'll need to make sure your nym-node uploads the file and reference to it. This is done by opening your node configuration file located at ~/.nym/nym-nodes/<ID>/config/config.toml and changing the value of the line landing_page_assets_path on the [http] section:

landing_page_assets_path = '<LANDING_PAGE_ASSETS_PATH>'

Reverse Proxy Configuration

You may set up a reverse proxy (opens in a new tab) in order to serve this landing page with proper SSL and DNS management, i.e. to resolve it to https://<HOSTNAME>.

1. Configure Nginx and firewall
  • Install nginx:
sudo apt install nginx
  • Setup firewall with ufw. ufw has three profile pre-configured for nginx, we will need the first one for nym-node:

    • Nginx Full: This profile opens both port 80 (normal, unencrypted web traffic) and port 443 (TLS/SSL encrypted traffic)
    • Nginx HTTP: This profile opens only port 80 (normal, unencrypted web traffic)
    • Nginx HTTPS: This profile opens only port 443 (TLS/SSL encrypted traffic)
ufw allow 'Nginx Full'
 
# you can verify by
ufw status
 
# possibly reload ufw by
ufw reload
  • Disable the default Nginx landing page
systemctl status nginx
unlink /etc/nginx/sites-enabled/default
systemctl restart nginx
2. Add your endpoint configuration to Nginx by creating a config file
  • Open file in a text editor
nano /etc/nginx/sites-available/<HOSTNAME>
  • Paste the text below to the editor and change <HOSTNAME> occurrences to your domain name:
server {
    listen 80;
    listen [::]:80;
 
    # Replace <HOSTNAME> with your domain name
    server_name <HOSTNAME>;
 
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
  • Note: This guide assumes that the HTTP port used by you is 8080 (recommended default) . Adjust the configuration accordingly if you have defined a custom port for your nym-node HTTP connections
3. Activate and test Nginx configuration
  • Create a symlink to /etc/nginx/sites-enabled:
ln -s /etc/nginx/sites-available/<HOSTNAME> /etc/nginx/sites-enabled
  • Test your configuration syntax:
nginx -t

Nginx must report that the config is "ok" and the test was successful.

  • Restart nginx:
systemctl restart nginx
4. Get an SSL certificate using certbot and restart nym-node
apt install certbot python3-certbot-nginx
certbot --nginx --non-interactive --agree-tos --redirect -m <YOUR_EMAIL_ADDRESS> -d <HOSTNAME>
  • Restart your nym-node or if you're running your nym-node as a systemd service, restart your service:
systemctl daemon-reload && service nym-node restart
5. Verify that your page is working
  • Check for the page being served reading the service logs
journalctl -u  nym-node.service | grep 8080
# where you should see
... Started NymNodeHTTPServer on 0.0.0.0:8080

Now your nginx should be configured, up and running. Test it by inserting your <HOSTNAME> as a URL in a browser.

Web Secure Socket Setup

This section assumes that you have already configured a reverse proxy and have set it up to work over https. If not, head over to the reverse proxy section to configure it.

We strongly recommend node operators to configure secure web sockets on their nodes. This will provide clients a more secure way to connect to your node.

You can read more about Secure Socket Layer (SSL) in here (opens in a new tab).

Remember that there may be some unique variables and customization depending on the way your reverse proxy is setup which you may have to adjust when configuring WSS to ensure correct functionality.

💡

To see description of used variables (noted in <> brackets), visit Variables & Paramteres (opens in a new tab) page.

Firewall configuration

Make sure to open all needed ports, adding your <ANNOUNCE_WSS_PORT>:

ufw allow <WSS_PORT>/tcp
 
# for example
# ufw allow 9001/tcp

WSS configuration

This section assumes that you have already configured a reverse proxy and have set it up to work over https. If not, head over to the reverse proxy section to configure it.

1. Create a new Nginx configuration file called /etc/nginx/sites-available/wss-config-nym
  • Open text editor
nano /etc/nginx/sites-available/wss-config-nym
  • Paste the block below. Don't forget to insert your correct values.
#############################################################
# EXCHANGE ALL <HOSTNAME> & <ANNOUNCE_WSS_PORT> VARIABLES ! #
#############################################################
 
server {
    listen <ANNOUNCE_WSS_PORT> ssl http2;
    listen [::]:<ANNOUNCE_WSS_PORT> ssl http2;
 
    server_name <HOSTNAME>;
 
    ssl_certificate /etc/letsencrypt/live/<HOSTNAME>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<HOSTNAME>/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
 
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;
 
    # Ignore favicon requests
    location /favicon.ico {
        return 204;
        access_log     off;
        log_not_found  off;
    }
 
    location / {
 
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, HEAD';
        add_header 'Access-Control-Allow-Headers' '*';
 
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Forwarded-For $remote_addr;
 
        proxy_pass http://localhost:9000;
        proxy_intercept_errors on;
    }
}
2. Activate and test Nginx WSS configuration
  • Create a symlink to /etc/nginx/sites-enabled:
ln -s /etc/nginx/sites-available/wss-config-nym /etc/nginx/sites-enabled
  • Test your configuration syntax:
nginx -t
3. Restart nginx
systemctl restart nginx
4. Finally, configure your nym-node to announce the port and hostname of your WSS and restart the node
  • Open your node configuration file located at ~/.nym/nym-nodes/<ID>/config/config.toml
nano ~/.nym/nym-nodes/<ID>/config/config.toml
  • And change the values of announce_wss_port in the [entry_gateway] and hostname in the [host] section:
announce_wss_port =  <ANNOUNCE_WSS_PORT>
 
# example
# announce_wss_port = 9001
 
hostname = '<HOSTNAME>'
 
# example
# hostname = 'exit-gateway1.squad.nsl'
  • Restart your nym-node
systemctl daemon-reload && service nym-node restart

Your nym-node should be configured to run over WSS now. Test it using the steps in the chapter below.

Test WSS Setup

You can do a few quick checks to test that your installation worked out and your nym-node is running correctly using WSS:

  • Check out connection with wscat from another (local) machine:
# install
sudo apt install node-ws
 
# run
wscat -c wss://<HOSTNAME>:<WSS_PORT>
  • Check Swagger API of your node using the hostname: https://<HOSTNAME>/api/v1/swagger/#/