From 469d37b7bdc5a086b49730037380bc08c0f3a6a5 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 Jan 2025 08:26:53 -0500 Subject: [PATCH 1/2] add wss docs --- .../setup-secure-wss/apache2-config.md | 7 ++ .../setup-secure-wss/install-apache2.md | 5 ++ .../setup-secure-wss/install-openssl.md | 4 + .../setup-secure-wss/nginx-config.md | 14 +++ .../setup-secure-wss/nginx-rate-limit.md | 10 +++ infrastructure/running-a-node/.pages | 2 +- .../running-a-node/setup-secure-wss.md | 90 +++++++++++++++++++ 7 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 .snippets/code/infrastructure/setup-secure-wss/apache2-config.md create mode 100644 .snippets/code/infrastructure/setup-secure-wss/install-apache2.md create mode 100644 .snippets/code/infrastructure/setup-secure-wss/install-openssl.md create mode 100644 .snippets/code/infrastructure/setup-secure-wss/nginx-config.md create mode 100644 .snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md create mode 100644 infrastructure/running-a-node/setup-secure-wss.md diff --git a/.snippets/code/infrastructure/setup-secure-wss/apache2-config.md b/.snippets/code/infrastructure/setup-secure-wss/apache2-config.md new file mode 100644 index 000000000..5b838b87a --- /dev/null +++ b/.snippets/code/infrastructure/setup-secure-wss/apache2-config.md @@ -0,0 +1,7 @@ +```apacheconf +# (...) +SSLProxyEngine on +ProxyRequests off +ProxyPass / ws://localhost:9944 +ProxyPassReverse / ws://localhost:9944 +``` \ No newline at end of file diff --git a/.snippets/code/infrastructure/setup-secure-wss/install-apache2.md b/.snippets/code/infrastructure/setup-secure-wss/install-apache2.md new file mode 100644 index 000000000..dcc6dae2d --- /dev/null +++ b/.snippets/code/infrastructure/setup-secure-wss/install-apache2.md @@ -0,0 +1,5 @@ +```bash +apt install apache2 +a2dismod mpm_prefork +a2enmod mpm_event proxy proxy_html proxy_http proxy_wstunnel rewrite ssl +``` \ No newline at end of file diff --git a/.snippets/code/infrastructure/setup-secure-wss/install-openssl.md b/.snippets/code/infrastructure/setup-secure-wss/install-openssl.md new file mode 100644 index 000000000..3f47aadcc --- /dev/null +++ b/.snippets/code/infrastructure/setup-secure-wss/install-openssl.md @@ -0,0 +1,4 @@ +```bash +sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/selfsigned.key -out /etc/ssl/certs/selfsigned.crt +sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048 +``` \ No newline at end of file diff --git a/.snippets/code/infrastructure/setup-secure-wss/nginx-config.md b/.snippets/code/infrastructure/setup-secure-wss/nginx-config.md new file mode 100644 index 000000000..295d4d723 --- /dev/null +++ b/.snippets/code/infrastructure/setup-secure-wss/nginx-config.md @@ -0,0 +1,14 @@ +```conf +server { + (...) + location / { + proxy_buffers 16 4k; + proxy_buffer_size 2k; + proxy_pass http://localhost:9944; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header Host $host; + } +} +``` \ No newline at end of file diff --git a/.snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md b/.snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md new file mode 100644 index 000000000..26a1adeb2 --- /dev/null +++ b/.snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md @@ -0,0 +1,10 @@ +```conf +http { + limit_req_zone "$http_x_forwarded_for" zone=zone:10m rate=2r/s; + (...) +} +location / { + limit_req zone=zone burst=5; + (...) +} +``` \ No newline at end of file diff --git a/infrastructure/running-a-node/.pages b/infrastructure/running-a-node/.pages index 524ac6396..4cb64c1e5 100644 --- a/infrastructure/running-a-node/.pages +++ b/infrastructure/running-a-node/.pages @@ -3,4 +3,4 @@ nav: - index.md - 'Set Up a Full Node': setup-full-node.md - 'Set Up a Bootnode': setup-bootnode.md - # - 'Common Node Flags': common-node-flags.md \ No newline at end of file + - 'Setup Secure Websocket': setup-secure-wss.md \ No newline at end of file diff --git a/infrastructure/running-a-node/setup-secure-wss.md b/infrastructure/running-a-node/setup-secure-wss.md new file mode 100644 index 000000000..69a7214ce --- /dev/null +++ b/infrastructure/running-a-node/setup-secure-wss.md @@ -0,0 +1,90 @@ +--- +title: Setup Secure WebSocket +description: Instructions on enabling SSL for your node and setting up a secure WebSocket proxy server using nginx for remote connections. +--- + +# Setup Secure WebSocket + +## Introduction + +Ensuring secure WebSocket communication is crucial for maintaining the integrity and security of a Polkadot or Kusama node when interacting with remote clients. This guide walks you through setting up a secure WebSocket (WSS) connection for your node by leveraging SSL encryption with popular web server proxies like nginx or Apache. By the end of this guide, you'll be able to secure your node's WebSocket port, enabling safe remote connections without exposing your node to unnecessary risks. + +## Secure a WebSocket Port + +You can convert a non-secured WebSocket port to a secure WSS port by placing it behind an SSL-enabled proxy. This approach can be used to secure a bootnode or RPC server. The SSL-enabled apache2/nginx/other proxy server redirects requests to the internal WebSocket and converts it to a secure (WSS) connection. You can use a service like [LetsEncrypt](https://letsencrypt.org/){target=\_blank} to obtain an SSL certificate. + +### Obtain an SSL Certificate + +You can follow the LetsEncrypt instructions for your respective web server implementation to get a free SSL certificate: + +- [nginx](https://certbot.eff.org/instructions?ws=nginx&os=ubuntufocal){target=\_blank} +- [apache2](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal){target=\_blank} + +LetsEncrypt will auto-generate an SSL certificate and include it in your configuration. + +You can generate a self-signed certificate and rely on your node's raw IP address when connecting. However, self-signed certificates aren't optimal because you have to whitelist the certificate to access it from a browser. + +Use the following commmand to generate a self-signed certificate using OpenSSL: + +--8<-- 'code/infrastructure/setup-secure-wss/install-openssl.md' + +## Install a Proxy Server + +There are a lot of different implementations of a WebSocket proxy; some of the more widely used are [nginx](https://www.nginx.com/){target=\_blank} and [apache2](https://httpd.apache.org/){target=\_blank}, both of which are commonly used web server implementations. See the following section for configuration examples for both implementations. + +### Use nginx + +1. Install the `nginx` web server: + ```bash + apt install nginx + ``` + +2. In an SSL-enabled virtual host add: + --8<-- 'code/infrastructure/setup-secure-wss/nginx-config.md' + +3. Optionally, you can introduce some form of rate limiting: + --8<-- 'code/infrastructure/setup-secure-wss/nginx-rate-limit.md' + +### Use Apache2 + +Apache2 can run in various modes, including `prefork`, `worker`, and `event`. In this example, the [`event`](https://httpd.apache.org/docs/2.4/mod/event.html){target=\_blank} mode is recommended for handling higher traffic loads, as it is optimized for performance in such environments. However, depending on the specific requirements of your setup, other modes like `prefork` or `worker` may also be appropriate. + +1. Install the `apache2` web server: + --8<-- 'code/infrastructure/setup-secure-wss/install-apache2.md' + +2. The [`mod_proxy_wstunnel`](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html){target=\_blank} provides support for the tunneling of WebSocket connections to a backend WebSocket server. The connection is automatically upgraded to a WebSocket connection. In an SSL-enabled `virtualhost` add: + --8<-- 'code/infrastructure/setup-secure-wss/apache2-config.md' + + !!!warning + Older versions of `mod_proxy_wstunnel` don't upgrade the connection automatically and will need the following config added: + ```apacheconf + RewriteEngine on + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteRule /(.*) ws://localhost:9944/$1 [P,L] + RewriteRule /(.*) http://localhost:9944/$1 [P,L] + ``` + +3. Optionally, some form of rate limiting can be introduced: + + ```bash + apt install libapache2-mod-qos + a2enmod qos + ``` + + And edit `/etc/apache2/mods-available/qos.conf`: + + ```conf + # allows max 50 connections from a single ip address: + QS_SrvMaxConnPerIP 50 + ``` + +## Connect to the Node + +1. Open [Polkadot.js Apps interface](https://polkadot.js.org/apps){target=\_blank} and click the logo in the top left to switch the node +2. Activate the **Development** toggle and input your node's address - either the domain or the IP address. Remember to prefix with `wss://` and if you're using the 443 port, append `:443` as follows: + + ```bash + wss://example.com:443 + ``` + +![A sync-in-progress chain connected to Polkadot.js UI](/images/infrastructure/general/setup-secure-wss/secure-wss-01.webp) \ No newline at end of file From 9e20f8be86fa4cf5317eec805a2a03701e3860b8 Mon Sep 17 00:00:00 2001 From: Bader Youssef Date: Mon, 6 Jan 2025 11:35:50 -0500 Subject: [PATCH 2/2] address comments --- .../setup-secure-wss/apache2-config.md | 0 .../setup-secure-wss/install-apache2.md | 0 .../setup-secure-wss/install-openssl.md | 0 .../setup-secure-wss/nginx-config.md | 0 .../setup-secure-wss/nginx-rate-limit.md | 0 infrastructure/running-a-node/setup-secure-wss.md | 15 +++++++++------ 6 files changed, 9 insertions(+), 6 deletions(-) rename .snippets/code/infrastructure/{ => running-a-node}/setup-secure-wss/apache2-config.md (100%) rename .snippets/code/infrastructure/{ => running-a-node}/setup-secure-wss/install-apache2.md (100%) rename .snippets/code/infrastructure/{ => running-a-node}/setup-secure-wss/install-openssl.md (100%) rename .snippets/code/infrastructure/{ => running-a-node}/setup-secure-wss/nginx-config.md (100%) rename .snippets/code/infrastructure/{ => running-a-node}/setup-secure-wss/nginx-rate-limit.md (100%) diff --git a/.snippets/code/infrastructure/setup-secure-wss/apache2-config.md b/.snippets/code/infrastructure/running-a-node/setup-secure-wss/apache2-config.md similarity index 100% rename from .snippets/code/infrastructure/setup-secure-wss/apache2-config.md rename to .snippets/code/infrastructure/running-a-node/setup-secure-wss/apache2-config.md diff --git a/.snippets/code/infrastructure/setup-secure-wss/install-apache2.md b/.snippets/code/infrastructure/running-a-node/setup-secure-wss/install-apache2.md similarity index 100% rename from .snippets/code/infrastructure/setup-secure-wss/install-apache2.md rename to .snippets/code/infrastructure/running-a-node/setup-secure-wss/install-apache2.md diff --git a/.snippets/code/infrastructure/setup-secure-wss/install-openssl.md b/.snippets/code/infrastructure/running-a-node/setup-secure-wss/install-openssl.md similarity index 100% rename from .snippets/code/infrastructure/setup-secure-wss/install-openssl.md rename to .snippets/code/infrastructure/running-a-node/setup-secure-wss/install-openssl.md diff --git a/.snippets/code/infrastructure/setup-secure-wss/nginx-config.md b/.snippets/code/infrastructure/running-a-node/setup-secure-wss/nginx-config.md similarity index 100% rename from .snippets/code/infrastructure/setup-secure-wss/nginx-config.md rename to .snippets/code/infrastructure/running-a-node/setup-secure-wss/nginx-config.md diff --git a/.snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md b/.snippets/code/infrastructure/running-a-node/setup-secure-wss/nginx-rate-limit.md similarity index 100% rename from .snippets/code/infrastructure/setup-secure-wss/nginx-rate-limit.md rename to .snippets/code/infrastructure/running-a-node/setup-secure-wss/nginx-rate-limit.md diff --git a/infrastructure/running-a-node/setup-secure-wss.md b/infrastructure/running-a-node/setup-secure-wss.md index 69a7214ce..55775dbff 100644 --- a/infrastructure/running-a-node/setup-secure-wss.md +++ b/infrastructure/running-a-node/setup-secure-wss.md @@ -9,13 +9,16 @@ description: Instructions on enabling SSL for your node and setting up a secure Ensuring secure WebSocket communication is crucial for maintaining the integrity and security of a Polkadot or Kusama node when interacting with remote clients. This guide walks you through setting up a secure WebSocket (WSS) connection for your node by leveraging SSL encryption with popular web server proxies like nginx or Apache. By the end of this guide, you'll be able to secure your node's WebSocket port, enabling safe remote connections without exposing your node to unnecessary risks. +!!!info + The following instructions are for UNIX-based systems. + ## Secure a WebSocket Port You can convert a non-secured WebSocket port to a secure WSS port by placing it behind an SSL-enabled proxy. This approach can be used to secure a bootnode or RPC server. The SSL-enabled apache2/nginx/other proxy server redirects requests to the internal WebSocket and converts it to a secure (WSS) connection. You can use a service like [LetsEncrypt](https://letsencrypt.org/){target=\_blank} to obtain an SSL certificate. ### Obtain an SSL Certificate -You can follow the LetsEncrypt instructions for your respective web server implementation to get a free SSL certificate: +You can follow the [LetsEncrypt](https://letsencrypt.org/){target=\_blank} instructions for your respective web server implementation to get a free SSL certificate: - [nginx](https://certbot.eff.org/instructions?ws=nginx&os=ubuntufocal){target=\_blank} - [apache2](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal){target=\_blank} @@ -26,7 +29,7 @@ You can generate a self-signed certificate and rely on your node's raw IP addres Use the following commmand to generate a self-signed certificate using OpenSSL: ---8<-- 'code/infrastructure/setup-secure-wss/install-openssl.md' +--8<-- 'code/infrastructure/running-a-node/setup-secure-wss/install-openssl.md' ## Install a Proxy Server @@ -40,20 +43,20 @@ There are a lot of different implementations of a WebSocket proxy; some of the m ``` 2. In an SSL-enabled virtual host add: - --8<-- 'code/infrastructure/setup-secure-wss/nginx-config.md' + --8<-- 'code/infrastructure/running-a-node/setup-secure-wss/nginx-config.md' 3. Optionally, you can introduce some form of rate limiting: - --8<-- 'code/infrastructure/setup-secure-wss/nginx-rate-limit.md' + --8<-- 'code/infrastructure/running-a-node/setup-secure-wss/nginx-rate-limit.md' ### Use Apache2 Apache2 can run in various modes, including `prefork`, `worker`, and `event`. In this example, the [`event`](https://httpd.apache.org/docs/2.4/mod/event.html){target=\_blank} mode is recommended for handling higher traffic loads, as it is optimized for performance in such environments. However, depending on the specific requirements of your setup, other modes like `prefork` or `worker` may also be appropriate. 1. Install the `apache2` web server: - --8<-- 'code/infrastructure/setup-secure-wss/install-apache2.md' + --8<-- 'code/infrastructure/running-a-node/running-a-node/setup-secure-wss/install-apache2.md' 2. The [`mod_proxy_wstunnel`](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html){target=\_blank} provides support for the tunneling of WebSocket connections to a backend WebSocket server. The connection is automatically upgraded to a WebSocket connection. In an SSL-enabled `virtualhost` add: - --8<-- 'code/infrastructure/setup-secure-wss/apache2-config.md' + --8<-- 'code/infrastructure/running-a-node/setup-secure-wss/apache2-config.md' !!!warning Older versions of `mod_proxy_wstunnel` don't upgrade the connection automatically and will need the following config added: