diff options
| -rw-r--r-- | docs/platform/examples.md | 113 | ||||
| -rw-r--r-- | menu.txt | 1 |
2 files changed, 114 insertions, 0 deletions
diff --git a/docs/platform/examples.md b/docs/platform/examples.md new file mode 100644 index 0000000..1fd4c87 --- /dev/null +++ b/docs/platform/examples.md @@ -0,0 +1,113 @@ +@title = 'Examples' +@summary = 'Example provider setups using the LEAP platform.' +# @toc = true + +A minimal three node OpenVPN provider +======================================= + +Our goal +------------------ + +We are going to create a minimal LEAP provider offering OpenVPN service. This basic setup can be expanded by adding more OpenVPN nodes to increase capacity, or more webapp and couchdb nodes to increase availability (performance wise, a single couchdb and a single webapp are more than enough for most usage, since they are only lightly used, but you might want redundancy). + +Our goal is something like this: + +> leap list + + NODES SERVICES TAGS + clam couchdb + elephant webapp + snail openvpn + +NOTE: You won't be able to run those `leap list` commands yet, not until we actually create the node configurations. + +Create configuration files +-------------------------------- + +Create the provider directory: + + leap new bitmask --domain bitmask.net --name bitmask --contacts root@bitmask.net + +Add you ssh key: + + leap add-user --self + +Add some nodes: + + leap node add clam ip_address:176.53.69.22 services:couchdb + leap node add elephant ip_address:176.53.69.13 services:webapp + leap node add snail ip_address:176.53.69.14 openvpn.gateway_address:176.53.69.15 services:openvpn + +NOTE: openvpn gateways must be assigned two IP addresses, one for the host itself and one for the openvpn gateway. We do this to prevent incoming and outgoing VPN traffic on the same IP. Without this, the client might send some traffic to other VPN users in the clear, bypassing the VPN. + +Now that you have the nodes configured, you should create the DNS entries for these nodes. + +Set up your DNS with these hostnames: + +> leap list --print ip_address,domain.full,dns.aliases + + clam 176.53.69.22, clam.bitmask.net, null + elephant 176.53.69.13, elephant.bitmask.net, api.bitmask.net, nicknym.bitmask.net + snail 176.53.69.14, snail.bitmask.net, null + +Alternately, you can adapt this zone file snippet: + +> leap compile zone + +Create certificates +------------------------------------ + +Create two certificate authorities, one for server certs and one for client certs: + + leap cert ca + +Create a temporary cert for your main domain (you should replace with a real commercial cert at some point) + + leap cert csr + +Create the Diffie-Hellman parameters file, needed for forward secret OpenVPN ciphers: + + leap cert dh + +Create server certificates for all the nodes you have added: + + leap cert update + +NOTE: the file `files/ca/ca.key` is extremely sensitive and must be carefully protected. The other key files are much less sensitive and can simply be regenerated if needed. + +Deploy to nodes +------------------------ + +Initialize all nodes (only needs to be done once for each node): + + leap node init + +Deploy to all nodes: + + leap deploy + +Those two commands create pretty busy output, so it may be more clear to initial and deploy each node one by one: + + leap node init clam + leap deploy clam + leap node init elephant + leap deploy elephant + leap node init snail + leap deploy snail + +Testing +-------------------------- + +Automated testing is in the works, but for now you manually test to see if the OpenVPN gateways and the webapp are working like so. + +OpenVPN: + + leap test init + sudo openvpn test/openvpn/unlimited.ovpn + +Webapp: + +* run `leap list --print ip_address webapp` to remind yourself the ip address(es) of the webapp. +* edit your local `/etc/hosts` to add entries like `176.53.69.13 example.org`, for whatever domain is appropriate in your case. +* open your browser to `https://example.org` + @@ -13,6 +13,7 @@ docs quick-start guide config + examples commands under-the-hood known-issues |