From 9229b401efff8b19ffe4d57eb4f867c3f8df6f10 Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Fri, 20 Oct 2017 16:36:24 +0300 Subject: [PATCH 1/6] Added TLS cluster how to --- docs/howtos.md | 198 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs/howtos.md diff --git a/docs/howtos.md b/docs/howtos.md new file mode 100644 index 000000000..eef3b1fd3 --- /dev/null +++ b/docs/howtos.md @@ -0,0 +1,198 @@ ++++ +title = "How Tos" +weight = 4 +nav = [ + "how-to-setup-a-secure-pilosa-cluster" +] ++++ + +## How Tos + +### How To Setup a Secure Pilosa Cluster + +#### Introduction + +Pilosa supports encrypting the communication between and to nodes in a cluster using TLS. In this tutorial, we will be setting up a three node Pilosa cluster running on the same computer. The same steps can be used for a multi-computer cluster but that requires setting up firewalls and other platform-specific setup which is out of the scope of this tutorial. + +This tutorial assumes that you are using a UNIX-like system, such as Linux or MacOS. [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/en-us/commandline/wsl/about) works equally well on Windows 10 systems. + +#### Installing Pilosa and Creating the Directory Structure + +If you haven't already done so, install Pilosa server on your computer. For Linux and WSL (Windows Subsystem for Linux) use the [Installing on Linux](https://www.pilosa.com/docs/latest/installation/#installing-on-linux) instructions. For MacOS use the [Installing on MacOS](https://www.pilosa.com/docs/latest/installation/#installing-on-macos). We do not support precompiled releases for other platforms, but you can always compile it yourself from source. See [Build from Source](https://www.pilosa.com/docs/latest/installation/#build-from-source). + +After installing Pilosa, you may have to add it to your `$PATH`. Check that you can run Pilosa from the command line: +``` +pilosa --help +``` + +Let's create a directory for the tutorial to put all of our files and switch to that directory: +``` +mkdir $HOME/pilosa-tls-tutorial && cd $_ +``` + +#### Creating the TLS Certificate and Gossip Key + +Securing a Pilosa cluster consists of securing the communication between nodes using TLS and Gossip encryption. [Pilosa Enterprise](https://www.pilosa.com/enterprise/) additionally supports authentication and other security features, but those are not covered in this tutorial. + +The first step is acquiring an SSL certificate. You can buy a commercial certificate or retrieve a Let's Encrypt certificiate but we will be using a self signed certificate for practical reasons. Using self-signed certificates is not recommended in production, since that makes man in the middle attacks easy. + +The following command creates a 2048bit self-signed wildcard certificate for `*.pilosa.local` which expires 10 years later. + +``` +openssl req -x509 -newkey rsa:2048 -keyout pilosa.local.key -out pilosa.local.crt -days 3650 -nodes -subj "/C=US/ST=Texas/L=Austin/O=Pilosa/OU=Com/CN=*.pilosa.local" +``` + +The command above creates two files in the current directory: +* `pilosa.local.crt` is the SSL certificate. +* `pilosa.local.key` is the private key file which must be kept as secret. + +Having created the SSL certificate, we can now create the gossip encryption key. Gossip encryption key file must be exactly 16, 24, or 32 bytes to select one of AES-128, AES-192, or AES-256 encryption. Reading random bytes from cryptographically secure `/dev/random` serves our purpose very well: +``` +head -c 32 /dev/random > pilosa.local.gossip32 +``` + +We now should have `pilosa.local.gossip32` in the current directory with 32 random bytes. + +#### Creating the Configuration Files + +Pilosa supports passing configuration items using the command line, environment variables or a configuration file. We will use the last option in this tutorial and create three configuration files for our three nodes. + +Create `node1.config.toml` in the project directory and paste the following in it: + +```toml +# node1.config.toml + +data-dir = "node1_data" +bind = "https://01.pilosa.local:10501" + +[cluster] +hosts = ["https://01.pilosa.local:10501", "https://02.pilosa.local:10502", "https://03.pilosa.local:10503"] + +[tls] +certificate = "pilosa.local.crt" +key = "pilosa.local.key" +skip-verify = true + +[gossip] +seed = "01.pilosa.local:15000" +port = 15000 +key = "pilosa.local.gossip32" +``` + +Create `node2.config.toml` in the project directory and paste the following in it: + +```toml +# node2.config.toml + +data-dir = "node2_data" +bind = "https://02.pilosa.local:10502" + +[cluster] +hosts = ["https://01.pilosa.local:10501", "https://02.pilosa.local:10502", "https://03.pilosa.local:10503"] + +[tls] +certificate = "pilosa.local.crt" +key = "pilosa.local.key" +skip-verify = true + +[gossip] +seed = "01.pilosa.local:15000" +port = 16000 +key = "pilosa.local.gossip32" +``` + +Create `node3.config.toml` in the project directory and paste the following in it: + +```toml +# node3.config.toml + +data-dir = "node3_data" +bind = "https://01.pilosa.local:10503" + +[cluster] +hosts = ["https://01.pilosa.local:10501", "https://02.pilosa.local:10502", "https://03.pilosa.local:10503"] + +[tls] +certificate = "pilosa.local.crt" +key = "pilosa.local.key" +skip-verify = true + +[gossip] +seed = "01.pilosa.local:15000" +port = 17000 +key = "pilosa.local.gossip32" +``` + +Here is some explanation of the configuration items: +* `data-dir` points to the directory where the Pilosa server writes its data. If it doesn't exist, the server will created it. +* `bind` is the address which the server listenes to for incoming requests. The address is composed of three parts, the scheme, host and port. The default scheme is `http` so we explicitly specify `https` to use the HTTPS protocol for communication between nodes. +* `[cluster]` section contains the settings for a cluster. `hosts` field is the most important, which contains the list of addresses of other nodes. See [Cluster Configuration](https://www.pilosa.com/docs/latest/configuration/#cluster-hosts) for other settings. +* `[tls]` section contains the TLS settings, including the path to the SSL certificate and the corresponding key. Set `skip-verify` to `true` in order to disable host name verification and other security measures. Do not set `skip-verify` to `true` on production servers. +* `[gossip]` section contains settings for the Gossip protocol. `seed` is the host and port for the main gossip node which coordinates other nodes. The `port` setting is the gossip listen address for the node. It should be different for each node, if the cluster is running on the same computer, otherwise you can set it to the same value. Finally, the `key` points to the gossip encryption key we created before. + +#### Final Touches Before Running the Cluster + +Before running the cluster, let's make sure `01.pilosa.local`, `02.pilosa.local` and `03.pilosa.local` resolves to an IP address. If you are running the cluster on your computer, it is adequate to add them to your `/etc/hosts`. Below is one of the many ways of doing that (mind the `>>`): +``` +sudo sh -c 'printf "\n127.0.0.1 01.pilosa.local 02.pilosa.local 03.pilosa.local\n" >> /etc/hosts' +``` + +#### Running the Cluster + +Let's open three terminal windows and run each node in its window. This will enable us to better observe what's happening on which node. + +Switch to the first terminal window, change to the project directory and start the first node: +``` +cd $HOME/pilosa-tls-tutorial +pilosa -c node1.config.toml +``` + +Switch to the second terminal window, change to the project directory and start the second node: +``` +cd $HOME/pilosa-tls-tutorial +pilosa -c node2.config.toml +``` + +Switch to the third terminal window, change to the project directory and start the third node: +``` +cd $HOME/pilosa-tls-tutorial +pilosa -c node3.config.toml +``` + +Let's ensure that all three Pilosa servers are runnning and they are connected: +``` +curl -k --ipv4 https://01.pilosa.local:10501/status +``` + +The `-k` flag is used to tell curl that it shouldn't bother with checking the certificate the server provides and `--ipv4` workarounds an issue on MacOS where the curl requests take a long time if the address resolves to `127.0.0.1`. You can leave it out on Linux and WSL. + +The output to the command above should show that all nodes are `UP`. + +#### Running Queries + +Having confirmed that our cluster is running OK, let's run a few queries. But before that, we need to create an index and a frame: +``` +curl -k --ipv4 https://01.pilosa.local:10501/index/sample-index -d '' +``` + +This will create index `sample-index` with default options. Let's create the frame now: +``` +curl -k --ipv4 https://01.pilosa.local:10501/index/sample-index/frame/sample-frame -d '' +``` + +We just created frame `sample-frame` with default options. + +Let's run a `SetBit` query: +``` +curl -k --ipv4 https://01.pilosa.local:10501/index/sample-index/query -d 'SetBit(frame="sample-frame", rowID=1, columnID=100)' +``` + +Confirm that the bit was indeed set: +``` +curl -k --ipv4 https://01.pilosa.local:10501/index/sample-index/query -d 'Bitmap(frame="sample-frame", rowID=1)' +``` + +The same response should be returned when querying other nodes in the cluster: +``` +curl -k --ipv4 https://02.pilosa.local:10502/index/sample-index/query -d 'Bitmap(frame="sample-frame", rowID=1)' +``` From 9686edbca517883e4d8b10c8d081c76e535fcc2c Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Sat, 21 Oct 2017 00:41:27 +0300 Subject: [PATCH 2/6] pilosa server runs the server --- docs/howtos.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/howtos.md b/docs/howtos.md index eef3b1fd3..81e4879b3 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -144,19 +144,19 @@ Let's open three terminal windows and run each node in its window. This will ena Switch to the first terminal window, change to the project directory and start the first node: ``` cd $HOME/pilosa-tls-tutorial -pilosa -c node1.config.toml +pilosa server -c node1.config.toml ``` Switch to the second terminal window, change to the project directory and start the second node: ``` cd $HOME/pilosa-tls-tutorial -pilosa -c node2.config.toml +pilosa server -c node2.config.toml ``` Switch to the third terminal window, change to the project directory and start the third node: ``` cd $HOME/pilosa-tls-tutorial -pilosa -c node3.config.toml +pilosa server -c node3.config.toml ``` Let's ensure that all three Pilosa servers are runnning and they are connected: From e74aa43dd018e560e8eaa89957a02113e289be3e Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Sat, 21 Oct 2017 01:41:28 +0300 Subject: [PATCH 3/6] fix node3 config; ensure hosts can be accessed; /status output --- docs/howtos.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/howtos.md b/docs/howtos.md index 81e4879b3..f32960220 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -107,7 +107,7 @@ Create `node3.config.toml` in the project directory and paste the following in i # node3.config.toml data-dir = "node3_data" -bind = "https://01.pilosa.local:10503" +bind = "https://03.pilosa.local:10503" [cluster] hosts = ["https://01.pilosa.local:10501", "https://02.pilosa.local:10502", "https://03.pilosa.local:10503"] @@ -137,6 +137,15 @@ Before running the cluster, let's make sure `01.pilosa.local`, `02.pilosa.local` sudo sh -c 'printf "\n127.0.0.1 01.pilosa.local 02.pilosa.local 03.pilosa.local\n" >> /etc/hosts' ``` +Ensure we can access the hosts in the cluster: +``` +ping -c 1 01.pilosa.local +ping -c 1 02.pilosa.local +ping -c 1 03.pilosa.local +``` + +If any of the commands above return `ping: unknown host`, check your `/etc/hosts` contains the failed hostname. + #### Running the Cluster Let's open three terminal windows and run each node in its window. This will enable us to better observe what's happening on which node. @@ -166,7 +175,10 @@ curl -k --ipv4 https://01.pilosa.local:10501/status The `-k` flag is used to tell curl that it shouldn't bother with checking the certificate the server provides and `--ipv4` workarounds an issue on MacOS where the curl requests take a long time if the address resolves to `127.0.0.1`. You can leave it out on Linux and WSL. -The output to the command above should show that all nodes are `UP`. +All nodes should be in the `UP` state: +``` +{"status":{"Nodes":[{"Host":"01.pilosa.local:10501","State":"UP"},{"Host":"02.pilosa.local:10502","State":"UP"},{"Host":"03.pilosa.local:10503","State":"UP"}]}} +``` #### Running Queries From 0690c5259ae1022d02b230b9227d303375524226 Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Mon, 23 Oct 2017 07:05:32 +0300 Subject: [PATCH 4/6] Added What's Next section --- docs/howtos.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/howtos.md b/docs/howtos.md index f32960220..db3866e71 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -208,3 +208,7 @@ The same response should be returned when querying other nodes in the cluster: ``` curl -k --ipv4 https://02.pilosa.local:10502/index/sample-index/query -d 'Bitmap(frame="sample-frame", rowID=1)' ``` + +#### What's Next? + +Check out our [Administration Guide](https://www.pilosa.com/docs/latest/administration/) to learn more about making the most of your Pilosa cluster and [Configuration Documentation](https://www.pilosa.com/docs/latest/configuration/) to see the available options to configure Pilosa. From b7443b042fd31df4e4dc79ebad0b2a09b1833e21 Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Mon, 23 Oct 2017 19:31:33 +0300 Subject: [PATCH 5/6] fixed howtos text --- docs/howtos.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/howtos.md b/docs/howtos.md index db3866e71..2538a7363 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -12,7 +12,7 @@ nav = [ #### Introduction -Pilosa supports encrypting the communication between and to nodes in a cluster using TLS. In this tutorial, we will be setting up a three node Pilosa cluster running on the same computer. The same steps can be used for a multi-computer cluster but that requires setting up firewalls and other platform-specific setup which is out of the scope of this tutorial. +Pilosa supports encrypting the communication between and to nodes in a cluster using TLS. In this tutorial, we will be setting up a three node Pilosa cluster running on the same computer. The same steps can be used for a multi-computer cluster but that requires setting up firewalls and other platform-specific configuration which is out of the scope of this tutorial. This tutorial assumes that you are using a UNIX-like system, such as Linux or MacOS. [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/en-us/commandline/wsl/about) works equally well on Windows 10 systems. @@ -34,7 +34,7 @@ mkdir $HOME/pilosa-tls-tutorial && cd $_ Securing a Pilosa cluster consists of securing the communication between nodes using TLS and Gossip encryption. [Pilosa Enterprise](https://www.pilosa.com/enterprise/) additionally supports authentication and other security features, but those are not covered in this tutorial. -The first step is acquiring an SSL certificate. You can buy a commercial certificate or retrieve a Let's Encrypt certificiate but we will be using a self signed certificate for practical reasons. Using self-signed certificates is not recommended in production, since that makes man in the middle attacks easy. +The first step is acquiring an SSL certificate. You can buy a commercial certificate or retrieve a Let's Encrypt certificiate but we will be using a self signed certificate for practical reasons. Using self-signed certificates is not recommended in production, since it makes man in the middle attacks easy. The following command creates a 2048bit self-signed wildcard certificate for `*.pilosa.local` which expires 10 years later. @@ -124,15 +124,15 @@ key = "pilosa.local.gossip32" ``` Here is some explanation of the configuration items: -* `data-dir` points to the directory where the Pilosa server writes its data. If it doesn't exist, the server will created it. -* `bind` is the address which the server listenes to for incoming requests. The address is composed of three parts, the scheme, host and port. The default scheme is `http` so we explicitly specify `https` to use the HTTPS protocol for communication between nodes. +* `data-dir` points to the directory where the Pilosa server writes its data. If it doesn't exist, the server will create it. +* `bind` is the address which the server listenes to for incoming requests. The address is composed of three parts, the scheme, host, and port. The default scheme is `http` so we explicitly specify `https` to use the HTTPS protocol for communication between nodes. * `[cluster]` section contains the settings for a cluster. `hosts` field is the most important, which contains the list of addresses of other nodes. See [Cluster Configuration](https://www.pilosa.com/docs/latest/configuration/#cluster-hosts) for other settings. * `[tls]` section contains the TLS settings, including the path to the SSL certificate and the corresponding key. Set `skip-verify` to `true` in order to disable host name verification and other security measures. Do not set `skip-verify` to `true` on production servers. * `[gossip]` section contains settings for the Gossip protocol. `seed` is the host and port for the main gossip node which coordinates other nodes. The `port` setting is the gossip listen address for the node. It should be different for each node, if the cluster is running on the same computer, otherwise you can set it to the same value. Finally, the `key` points to the gossip encryption key we created before. #### Final Touches Before Running the Cluster -Before running the cluster, let's make sure `01.pilosa.local`, `02.pilosa.local` and `03.pilosa.local` resolves to an IP address. If you are running the cluster on your computer, it is adequate to add them to your `/etc/hosts`. Below is one of the many ways of doing that (mind the `>>`): +Before running the cluster, let's make sure that `01.pilosa.local`, `02.pilosa.local` and `03.pilosa.local` resolve to an IP address. If you are running the cluster on your computer, it is adequate to add them to your `/etc/hosts`. Below is one of the many ways of doing that (mind the `>>`): ``` sudo sh -c 'printf "\n127.0.0.1 01.pilosa.local 02.pilosa.local 03.pilosa.local\n" >> /etc/hosts' ``` @@ -144,7 +144,7 @@ ping -c 1 02.pilosa.local ping -c 1 03.pilosa.local ``` -If any of the commands above return `ping: unknown host`, check your `/etc/hosts` contains the failed hostname. +If any of the commands above return `ping: unknown host`, make sure your `/etc/hosts` contains the failed hostname. #### Running the Cluster From 137c4724afa0b0f44547201a8ec3b332bea4741d Mon Sep 17 00:00:00 2001 From: Yuce Tekol Date: Mon, 23 Oct 2017 19:51:58 +0300 Subject: [PATCH 6/6] more tls howto updates --- docs/howtos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howtos.md b/docs/howtos.md index 2538a7363..7809b7091 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -125,7 +125,7 @@ key = "pilosa.local.gossip32" Here is some explanation of the configuration items: * `data-dir` points to the directory where the Pilosa server writes its data. If it doesn't exist, the server will create it. -* `bind` is the address which the server listenes to for incoming requests. The address is composed of three parts, the scheme, host, and port. The default scheme is `http` so we explicitly specify `https` to use the HTTPS protocol for communication between nodes. +* `bind` is the address to which the server listens for incoming requests. The address is composed of three parts: scheme, host, and port. The default scheme is `http` so we explicitly specify `https` to use the HTTPS protocol for communication between nodes. * `[cluster]` section contains the settings for a cluster. `hosts` field is the most important, which contains the list of addresses of other nodes. See [Cluster Configuration](https://www.pilosa.com/docs/latest/configuration/#cluster-hosts) for other settings. * `[tls]` section contains the TLS settings, including the path to the SSL certificate and the corresponding key. Set `skip-verify` to `true` in order to disable host name verification and other security measures. Do not set `skip-verify` to `true` on production servers. * `[gossip]` section contains settings for the Gossip protocol. `seed` is the host and port for the main gossip node which coordinates other nodes. The `port` setting is the gossip listen address for the node. It should be different for each node, if the cluster is running on the same computer, otherwise you can set it to the same value. Finally, the `key` points to the gossip encryption key we created before.