diff --git a/docs/maintain/maintain-guides-how-to-setup-a-validator-with-reverse-proxy.md b/docs/maintain/maintain-guides-how-to-setup-a-validator-with-reverse-proxy.md deleted file mode 100644 index 21797662a2b9..000000000000 --- a/docs/maintain/maintain-guides-how-to-setup-a-validator-with-reverse-proxy.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -id: maintain-guides-how-to-setup-a-validator-with-reverse-proxy -title: Set Up a Validator with NGINX Reverse Proxy -sidebar_label: Set Up a Validator with NGINX Reverse Proxy -description: Steps on setting up a reverse proxy for your validator node. -keywords: [reverse proxy, nginx, setup, secure] -slug: ../maintain-guides-how-to-setup-a-validator-with-reverse-proxy ---- - -This guide assumes that you have already configured your hardware with the appropriate specs. It has -the same configuration as the -[polkadot validator setup](https://github.com/w3f/polkadot-secure-validator). - -:::info - -Because validators of parachains need to have publicly accessible IP addresses and ports to receive -connections from parachain collators, adding a proxy may potentially reduce connectivity and result -in lower era points or the inability to validate parachain blocks. If using a proxy, it's -recommended to keep an eye out on networking metrics. - -::: - -We will walk you through how to configure a reverse proxy using NGINX in front of your validator -node. The validator uses the reverse proxy to filter traffic, whereby additional adjustments can be -made to respond to a DDoS attack. - -### 1. Firewall configuration - -We will configure the firewall with [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall). There -needs to be three main ports for this setup. - -- An SSH port, commonly ssh/tcp port `22`. -- A proxy port -- p2p port: must be denied at the firewall level. - -In this example, we will assign the port number `2435` to the proxy port and the port number `30333` -to the p2p port. To enable the firewall and the use of the ports, allow SSH access. - -:::note For parachains, you will need to allow for both inbound and outbound traffic on the p2p port - -Since the proxy port is the public-facing port, this will need to have inbound and outbound traffic -open, with the normal p2p port closed. - -::: - -```bash -ufw enable -# ssh port -ufw allow 22/tcp -# proxy port -ufw allow 2435/tcp -# libp2p port -ufw deny 30333/tcp -# default port for HTTP -ufw deny 9933 -# default port for WS -ufw deny 9944 -ufw reload -# double check the firewall rules -ufw verbose -``` - -The `verbose` option shows some extra information about the firewall's behavior. - -### 2. Basic log viewing - -We use [journald](https://www.loggly.com/blog/why-journald/) logs for basic log viewing. Create a -file called `journald.conf` file inside the `/etc/systemd/` directory with the following content: - -```bash -[Journal] -Storage=persistent -RateLimitIntervalSec=30s -RateLimitBurst=20000 -SystemMaxUse=50G -SystemMaxFileSize=512M -SystemMaxFiles=100 -``` - -Check out the -[example journald configuration file](https://github.com/w3f/polkadot-secure-validator/blob/master/ansible/roles/polkadot-validator/files/journald.conf) -for more available options. - -Finally, run the following command to restart the journald service: - -```bash -systemctl restart systemd-journald -``` - -### 3. NGINX reverse proxy setup - -First, install NGINX with the following command: - -``` -sudo apt-get install nginx -``` - -Next, create an NGINX configuration file called `nginx.conf` inside the `/etc/nginx/` directory with -the following content: - -```bash -user www-data www-data; - -load_module /usr/lib/nginx/modules/ngx_stream_module.so; - -stream { - include streams-enabled/*; -} - -http { - include sites-enabled/*; -} - -events{ -} -``` - -This will import and make use of the -[NGINX stream module](https://nginx.org/en/docs/stream/ngx_stream_core_module.html). In a nutshell, -this module allows for continuous streaming of data in or out of the validator machine with all the -benefits of having an optimized reverse proxy. - -Next, create a folder called `/streams-enabled/` inside the `/etc/nginx/` directory and remove the -default NGINX site. - -```bash -# Create the streams-enabled folder -mkdir /etc/nginx/streams-enabled -# Delete the default configuration -/etc/nginx/sites-enabled/default -``` - -Now, inside the newly created directory `/etc/nginx/streams-enabled/`, create the proxy service file -called `polkadot-proxy.conf` with the following content: - -:::info Use the previously defined ports: port `2435` for the proxy port & port number `30333` for -the p2p port - -::: - -```bash -server { - listen 0.0.0.0:2435; - location / { - proxy_pass http://localhost:30333; - } -} -``` - -Change the permissions of the file `polkadot-proxy.conf` accordingly: - -```bash -chmod 0600 polkadot-proxy.conf -``` - -Finally, restart NGINX with the following command: - -```bash -service nginx restart -``` - -### 4. Defining your proxy port and p2p port in the polkadot command - -These are some of the flags you are going to use when executing the command. - -`--public-addr , ` - This flag defines the validator's IP and the proxy -port that all other nodes in the network will connect to. - -`--listen-addr , ` - This flag defines the p2p port that the polkadot -application will use to connect to the NGINX reverse proxy. - -#### P2P Networking - -Nodes will use [libp2p](https://libp2p.io/) as the networking layer to establish peers and gossip -messages, but uses NGINX as a load balancer which acts as a _first listener_ of the streaming data -to help balance the load. - -Each host node maintains an ED25519 key pair which is used to identify the node. The public key is -shared with the rest of the network allowing the nodes to establish secure communication channels. - -The node uses various mechanisms to locate peers within the network and allows them to share this -information with one another. - -Nodes connect to peers by establishing a TCP connection. Once established, the node initiates a -handshake with the remote peers on the encryption layer. An additional layer on top of the -encryption layer, known as the multiplexing layer, allows a connection to be split into substreams, -as described by the [yamux specification](https://docs.libp2p.io/concepts/multiplex/), either by the -local or remote node. - -Nodes supports two types of substream protocols: - -- Request-Response substreams -- Notification substreams - -More technical details on the connection establishment can be found -[here](https://spec.polkadot.network/#sect-connection-establishment). - -The encryption layer leverages the libp2p Noise framework in order to establish encrypted -communication channels. The three following steps are required to complete the handshake process: - -1. The initiator generates a keypair and sends the public key to the responder. -2. The responder generates its own key pair and sends its public key back to the initiator. After - that, the responder derives a shared secret and uses it to encrypt all further communication. The - responder now sends its static Noise public key, its libp2p public key and a signature of the - static Noise public key signed with the libp2p public key. -3. The initiator derives a shared secret and uses it to encrypt all further communication. They also - send its static Noise public key, libp2p public key and signature to the responder. - -##### public-addr - -`public-addr` - a flexible encoding of multiple layers of protocols into a human-readable addressing -scheme. In our example, `/ip4//tcp/` is a valid `public-addr` that -specifies wanting the network to reach the validator IPv4 address with TCP packets on the -pre-defined proxy port. - -- `IP_ADDRESS` - the public IP address of the validator. - -- `PROXY_PORT` - the port that nodes will send p2p messages over the network and are read by the - NGINX reverse proxy. - -##### listen-addr - -`listen-addr` - the specification of what port the polkadot application will connect to the reverse -proxy. In our example, `/ip4/0.0.0.0/tcp/` specifies that you want to listen to NGINX on -the localhost address (`0.0.0.0`, or all interfaces), with TCP packets on the pre-defined p2p port. - -- `P2P_PORT` - the port that the polkadot application connects to NGINX. - -#### Starting the validator with the NGINX proxy - -After retrieving the appropriate `IP_ADDRESS`, `PROXY_PORT` and `P2P_PORT` of the validator node, we -can start the validator. - -Start your validator with the `--validator` flag: - -```bash -# Validator Node -polkadot \ - --name My_Validator_Name \ - --validator \ - --public-addr=/ip4/IP_ADDRESS/tcp/2435 \ - --listen-addr=/ip4/0.0.0.0/tcp/30333 \ - --rpc-methods=Unsafe \ - --chain=polkadot - -``` - -You should see your validator's peers, as well as the p2p port you are using to connect to NGINX. - -``` -2020-12-17 19:04:36 __ Imported #2940151 (0x14c5_f472) -2020-12-17 19:04:39 __ Idle (35 peers), best: #2940151 (0x14c5_f472), finalized #2940149 (0x6014_7806), _ 1.1MiB/s _ 1.1MiB/s -2020-12-17 19:04:43 __ Imported #2940152 (0xcce7_c192) -2020-12-17 19:04:44 __ Idle (35 peers), best: #2940152 (0xcce7_c192), finalized #2940150 (0x8e24_8e72), _ 1.4MiB/s _ 1.2MiB/s -2020-12-17 19:04:48 __ Imported #2940153 (0xc79b_0ae3) -2020-12-17 19:04:49 __ Idle (35 peers), best: #2940153 (0xc79b_0ae3), finalized #2940151 (0xc4b8_8fa1), _ 1.2MiB/s _ 1.2MiB/s -2020-12-17 19:04:54 __ Imported #2940154 (0x1419_56db) -2020-12-17 19:04:54 __ Idle (35 peers), best: #2940154 (0x1419_56db), finalized #2940151 (0xc4b8_8fa1), _ 1.2MiB/s _ 1002.5kiB/s -``` - -Congratulations! You have successfully set up a validator with NGINX and now have a more secure way -of running your validator. diff --git a/docs/maintain/maintain-guides-how-to-use-polkadot-validator-setup.md b/docs/maintain/maintain-guides-how-to-use-polkadot-validator-setup.md deleted file mode 100644 index 502debbeecf4..000000000000 --- a/docs/maintain/maintain-guides-how-to-use-polkadot-validator-setup.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -id: maintain-guides-how-to-use-polkadot-validator-setup -title: How to use Polkadot Validator Setup -sidebar_label: How to use Polkadot Validator Setup -description: Steps on Web3 Foundation's supported validator setup. -keywords: [validator setup, validator, configuration] -slug: ../maintain-guides-how-to-use-polkadot-validator-setup ---- - -# Polkadot Validator Setup - -The following guide will walk you through using Web3 Foundation's -[polkadot validator setup](https://github.com/w3f/polkadot-validator-setup) to offer a potential -setup for your validator that aims to prevent some types of potential attacks at the TCP layer and -layers below. This will work for Polkadot and Kusama out of the box, and, if you're using another -Substrate-based chain, it should work with some tweaks. - -:::tip This setup should not be assumed to include the best security practices - -It is up to you to add additional security hardening. - -Also, the current version of polkadot validator setup doesn't allow for the creation and -configuration of sentry nodes. - -There are two ways that the setup can be configured: - -1. **Platform & Application Layer** which allows for configuring the credentials for infrastructure - providers, then executes the Terraform process to automatically deploy the required machines - (Platform Layer) and setup the Application Layer. This configuration uses - [Terraform](https://www.terraform.io/) for defining and managing your infrastructure. - -2. **Application Layer** which allows for setting up Debian-based machines, where you only need - basic SSH access and configure those in an inventory. The Ansible scripts will setup the entire - Application Layer. This configuration uses [Ansible](https://www.ansible.com/) as an automation - tool for setting up the VPN, Firewall, and the validator node. It supports a few different cloud - providers such as AWS, Microsoft Azure, GCP, and Packet. - - :::note Please file an [issue](https://github.com/w3f/polkadot-validator-setup/issues) if you - would like to make a feature request or report a bug for this setup - - ::: - -::: - -## Dependencies - -The initial step is to install the software dependencies for running the validator setup scripts. We -will need to acquire NodeJS, Yarn, Terraform, and Ansible. Usually, these are readily available -using your operating system's package manager. Instructions may vary depending on which system you -are on; the instructions below demonstrate the commands for a user of a _Debian_ or _Ubuntu-based_ -system. - -### NodeJS - -We recommend using [nvm](https://github.com/nvm-sh/nvm) as a tool to manage different NodeJS -versions across projects. - -``` -sudo apt-get install curl -curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - -sudo apt-get install nodejs -node -v (Check your node version) -``` - -### Yarn - -``` -curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt update -sudo apt install yarn -``` - -### Terraform - -``` -sudo apt-get install unzip -wget https://releases.hashicorp.com/terraform/1.1.7/terraform_1.1.7_linux_amd64.zip -unzip terraform_1.1.7_linux_amd64.zip -sudo mv terraform /usr/local/bin/ -terraform --version (Check whether it is configured properly) -``` - -### Ansible - -``` -sudo apt-add-repository ppa:ansible/ansible -sudo apt-get update -sudo apt-get install ansible -y -sudo apt-get install python -y -``` - -## Deployment - -### Step One: Clone the repository - -The first step is to clone the `polkadot-validator-setup` guide locally. - -```zsh -$ git clone https://github.com/w3f/polkadot-validator-setup.git -``` - -Now you can `cd` into the `polkadot-validator-setup` directory and start to change the -configurations to match your custom deployment. However, before we start tweaking those, let's start -by creating two new SSH keys that we (or rather, the Ansible playbooks) will use to access the -machines. - -### Step Two: Generate the SSH keys - -We will use [SSH](https://en.wikipedia.org/wiki/Secure_Shell), a remote shell tool, to access our -validator. You will first use the `ssh-keygen` command to generate a key for your validator. - -```zsh -$ ssh-keygen -m pem -f id_rsa_validator -$ ssh-keygen -m pem -f id_rsa_public -``` - -Be sure to add these keys to your SSH agent. First make sure your SSH agent is evaluated, then add -the keys to them. - -```zsh -$ eval $(ssh-agent) -$ ssh-add id_rsa_validator -$ ssh-add id_rsa_public -``` - -For this tutorial we will not set a passphrase for the SSH key, although usually that would be -recommended. - -### Configuration - -After you have installed all the required software and made your ssh keys, you can start to -configure your infrastructure deployment by following the instructions. Start by cloning the -`polkadot-validator-setup` repository locally, and installing the package dependencies. Then -customize the configuration how you want it. - -First run yarn to install the NodeJS dependencies: - -```zsh -$ yarn -``` - -Now you can copy the configuration sample and start to customize it. - -```zsh -$ cp config/main.sample.json config/main.json -# now you should customize config/main.json -``` - -Under `validators` and `publicNodes`, specify which cloud provider you want to use, the type of -machine specification, the number of validators you are going to deploy, the machine location, and -the user to use for SSH. - -#### Getting the authorization keys - -The validator setup supports Google Cloud, AWS, Microsoft Azure, and Packet. For this tutorial we -will be using Google Cloud. - -##### Log in to the Google Cloud console - -You will need to log in to the google cloud console in order to access your authorization keys. - -In the IAM&Admin panel you will navigate to service accounts. Download JSON for service account key. - -Make sure to also auth into your account like so: - -```zsh -$ gcloud auth login -``` - -And don't forget to enable the compute engine! - -#### Configuration Options - -The other options can be mostly self explanatory. Here's some tips on what they are and how you can -use them: - -In the `additionalFlags` option, configure any of the additional flags you want to run for your -validator. If you want to run with a specific name, this is where you would enter it. - -Under the `polkadotBinary.url` field you can provide the release that is hosted in the -[W3F repository](https://github.com/w3f/polkadot/releases) or use an alternate one that you build -and publish yourself. - -By enabling the `nodeExporter`, Ansible will install and configure the -[node_exporter](https://github.com/prometheus/node_exporter), which will expose hardware-level -metrics of your node in a format compatible with Prometheus. - -The field `machineType:` will configure the machine's hardware specifications, check -[here](https://cloud.google.com/compute/docs/machine-types) for the configuration options for GCP. -The other hosting providers should have similar pages in their documentation. - -Under `provider` the option are `gcp` (Google Cloud Provider), `aws` (AWS), `azure` (Microsoft -Azure) and `packet` for Packet. - -The field `count` is the number of instances you would like to create. - -The `location` and `zone` fields are for the location of the machine, for GCP check -[here](https://cloud.google.com/compute/docs/regions-zones/), other cloud providers will have -similar documentation. - -The `telemetryUrl` field will send your node's information to a specific telemetry server. You could -send all your nodes' data (e.g. IP address) to the public endpoint, but it is highly recommended -that that you set up your own telemetry server to protect your validator’s data from being exposed -to the public. If you want to do that, see -[substrate telemetry source](https://github.com/paritytech/substrate-telemetry). - -:::note - -If you decided to send your node’s information to public telemetry, the name for your validator and -public node that is displayed on the telemetry would look something like `PROJECT_NAME-sv-public-0` -/ `PROJECT_NAME-sv-validator-0`. - -::: - -Configure `projectId` to be the name of the project you want to use in GCP. - -Configure `sshUser` to be the user that manages your machine. - -For different cloud providers, you need to set the corresponding credentials as environment -variables, for example, on GCP you only need to set `GOOGLE_APPLICATION_CREDENTIALS`. This variable -is the path to the JSON file containing the credentials of the service account you wish to use; this -service account needs to have write access to compute and network resources if you use GCP. For -others, you can check that by referring to the -[README](https://github.com/w3f/polkadot-validator-setup#prerequisites). - -:::info Environment variables for Ansible - -Besides that, you need two additional environment variables that will allow Ansible to connect to -the created machines. These values of these variables will be the keys that you generated at the -beginning of the guide. - -- `SSH_ID_RSA_PUBLIC` - Path to private SSH key you want to use for the public nodes -- `SSH_ID_RSA_VALIDATOR` - Path to private SSH key you want to use for the validator - -::: - -:::note - -You will need to configure the Compute Engine API and enable billing on your GCP accounts to -properly run these scripts. - -::: - -After everything is configured properly, you can start to run the deployment with: - -```zsh -$ scripts/deploy.sh -``` - -:::note - -Certain steps of the process may hang, however the scripts are idempotent so you simply need to -re-run them and when the deployment and configuration is completed, you should see some output that -looks like what's below. You are able to find the validator’s session keys by searching for "show -rotateKeys output". - -::: - -``` -TASK [polkadot-validator-session-info : retrieve session info] ***************** - -ok: [34.80.70.172] - - -PLAY RECAP ********************************************************************* - -34.80.224.231 : ok=41 changed=1 unreachable=0 failed=0 skipped=11 rescued=0 ignored=0 - -34.80.70.172 : ok=49 changed=1 unreachable=0 failed=0 skipped=14 rescued=0 ignored=0 - -35.189.183.66 : ok=41 changed=1 unreachable=0 failed=0 skipped=11 rescued=0 ignored=0 - -Done -Done in 131.85s. -``` - -Also you can use `sshUser` to access one of the created instances that shows above. - -``` -TASK [polkadot-validator : show rotateKeys output] ***************************** - -ok: [34.80.70.172] => { - "rotate_keys": { - "changed": false, - "connection": "close", - "content_length": "295", - "content_type": "application/json; charset=utf-8", - "cookies": {}, - "cookies_string": "", - "date": "Sun, 24 Nov 2019 12:13:42 GMT", - "elapsed": 0, - "failed": false, - "json": { - "id": 1, - "jsonrpc": "2.0", - "result": "0xf126b68841f51988b37780fa5b224b2aa86888a8d3962a63595dbc4d85baac2dee7c9900c8ddfad1991a8884e58273f06d5c1dbfc3dc6000c037185ccead9d692a3b3396cdd7e2def520682d65ad7e8ca234fb17630b428752e6150462998b4362a2b7e201657c8084ae8215bd142458ccd69506d08b18925dc897fb95f54249" - }, - "msg": "OK (295 bytes)", - "redirected": false, - "status": 200, - "url": "http://localhost:9933" - } -} -``` - -The result "0xf126b68841f5…..95f54249" is your session key. Set this to your controller account in -[Polkadot-JS Apps](https://polkadot.js.org/apps/#/staking/actions). - -After accessing one of the machines through SSH, you can keep track of the node’s status by running -`journalctl --follow -u polkadot`, which will show the latest synced block information. - -Every time you change something in `main.json`, you can simply run `./scripts/deploy.sh` to update -it. - -Congratulations! You have successfully deployed a secure validator. Free feel to open an issue if -you have any suggestions. diff --git a/polkadot-wiki/docusaurus.config.js b/polkadot-wiki/docusaurus.config.js index 0323f6561ff5..bfee11663650 100644 --- a/polkadot-wiki/docusaurus.config.js +++ b/polkadot-wiki/docusaurus.config.js @@ -115,6 +115,10 @@ module.exports = { to: '/docs/learn-redenomination', from: ['/docs/redenomination'] }, + { + to: '/docs/maintain-guides-how-to-validate-polkadot', + from: ['/docs/maintain-guides-how-to-use-polkadot-validator-setup','/docs/maintain-guides-how-to-setup-a-validator-with-reverse-proxy'] + }, { to: '/docs/learn-account-advanced', from: ['/docs/ens'] diff --git a/polkadot-wiki/sidebars.js b/polkadot-wiki/sidebars.js index e0ab8114ad52..76ec2c95b0e6 100644 --- a/polkadot-wiki/sidebars.js +++ b/polkadot-wiki/sidebars.js @@ -232,8 +232,6 @@ module.exports = { "maintain/maintain-guides-validator-payout", "maintain/maintain-guides-how-to-systemd", "maintain/maintain-guides-secure-validator", - "maintain/maintain-guides-how-to-use-polkadot-validator-setup", - "maintain/maintain-guides-how-to-setup-a-validator-with-reverse-proxy", "maintain/maintain-guides-how-to-upgrade", "maintain/maintain-guides-how-to-monitor-your-node", "maintain/maintain-guides-how-to-chill",