diff options
| -rw-r--r-- | amber/menu.txt | 2 | ||||
| -rw-r--r-- | pages/docs/platform/details/development.md | 78 | ||||
| -rw-r--r-- | pages/docs/platform/en.md | 31 | ||||
| -rw-r--r-- | pages/docs/platform/guide/getting-started.md | 145 | ||||
| -rw-r--r-- | pages/docs/platform/tutorials/quick-start.md | 388 | ||||
| -rw-r--r-- | pages/docs/platform/tutorials/single-node-email.md | 281 | ||||
| -rw-r--r-- | pages/docs/platform/tutorials/single-node-vpn.md | 100 |
7 files changed, 476 insertions, 549 deletions
diff --git a/amber/menu.txt b/amber/menu.txt index 12c94db..e9f40b4 100644 --- a/amber/menu.txt +++ b/amber/menu.txt @@ -32,6 +32,7 @@ docs soledad platform guide + getting-started config nodes keys-and-certificates @@ -58,7 +59,6 @@ docs troubleshooting tests known-issues - vagrant where-to-look details faq diff --git a/pages/docs/platform/details/development.md b/pages/docs/platform/details/development.md new file mode 100644 index 0000000..78915ad --- /dev/null +++ b/pages/docs/platform/details/development.md @@ -0,0 +1,78 @@ +@title = 'Development' +@summary = "Getting started with making changes to the LEAP platform" + +Installing leap_cli +------------------------------------------------ + +### From gem, for a single user + +Install the latest: + + gem install leap_cli --install-dir ~/leap + export PATH=$PATH:~/leap/bin + +Install a particular version: + + gem install leap_cli --version 1.8 --install-dir ~/leap + export PATH=$PATH:~/leap/bin + +### From gem, system wide + +Install the latest: + + sudo gem install leap_cli + +Install a particular version: + + sudo gem install leap_cli --version 1.8 + +### As a gem, built from source + + sudo apt-get install ruby ruby-dev rake + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop + rake build + sudo rake install + +### The "develop" branch from source, for a single user + + sudo apt-get install ruby ruby-dev rake + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop + +Then do one of the following to be able to run `leap` command: + + cd leap_cli + export PATH=$PATH:`pwd`/bin + alias leap="`pwd`/bin/leap" + ln -s `pwd`/bin/leap ~/bin/leap + +In practice, of course, you would put aliases or PATH modifications in a shell startup file. + +You can also clone from https://github.com/leap/leap_cli + +Running different leap_cli versions +--------------------------------------------- + +### If installed as a gem + +With rubygems, you can always specify the gem version as the first argument to any executable installed by rubygems. For example: + + sudo gem install leap_cli --version 1.7.2 + sudo gem install leap_cli --version 1.8 + leap _1.7.2_ --version + => leap 1.7.2, ruby 2.1.2 + leap _1.8_ --version + => leap 1.8, ruby 2.1.2 + +### If running from source + +Alternately, if you are running from source, you can alias different commands: + + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop + alias leap_develop="`pwd`/bin/leap` + diff --git a/pages/docs/platform/en.md b/pages/docs/platform/en.md index 2029093..098aacb 100644 --- a/pages/docs/platform/en.md +++ b/pages/docs/platform/en.md @@ -7,7 +7,7 @@ Its goal is to make it as painless as possible for sysadmins to deploy and maint **REQUIREMENTS** -- Before you begin, make sure you meet these requirements: -* *Debian Servers*: Servers that you deploy to must be running Debian Wheezy, and no other distribution or version. +* *Debian Servers*: Servers that you deploy to must be running **Debian Jessie**, and no other distribution or version. * *Real or Paravirtualized Servers*: Servers must be real machines or paravirtualized VMs (e.g. KVM, Xen, OpenStack, AWS, Google Compute). OS level virtualization is not supported (e.g. OpenVZ, Linux-VServer, etc), nor are system emulators (VirtualBox, QEMU, etc). * *Your Workstation*: You must have a Linux or Mac computer to deploy from (this can be a headless machine with no GUI). Windows is not supported (Cygwin would probably work, but is untested). * *Your Own Domain*: You must own a domain name. Before your provider can be put into production, you will need to make modifications to the DNS for the provider's domain. @@ -69,31 +69,14 @@ The `leap` command line has many capabilities, including: * Manage keys and certificates. * Query information about the node configurations. -Traditional system configuration automation systems, like [Puppet](https://puppetlabs.com/puppet/puppet-open-source/) or [Chef](http://www.opscode.com/chef/), deploy changes to servers using a pull method. Each server pulls a manifest from a central master server and uses this to alter the state of the server. +Everything about your provider is managed by editing JSON configuration files and running `leap` commands. -Instead, the `leap` tool uses a masterless push method: The sysadmin runs `leap deploy` from the provider instance directory on their desktop machine to push the changes out to every server (or a subset of servers). LEAP still uses Puppet, but there is no central master server that each node must pull from. - -One other significant difference between LEAP and typical system automation is how interactions among servers are handled. Rather than store a central database of information about each server that can be queried when a recipe is applied, the `leap` command compiles static representation of all the information a particular server will need in order to apply the recipes. In compiling this static representation, `leap` can use arbitrary programming logic to query and manipulate information about other servers. - -These two approaches, masterless push and pre-compiled static configuration, allow the sysadmin to manage a set of LEAP servers using traditional software development techniques of branching and merging, to more easily create local testing environments using virtual servers, and to deploy without the added complexity and failure potential of a master server. - -The `leap` command line tool is distributed as a git repository: `https://leap.se/git/leap_cli`. It can be installed with `sudo gem install leap_cli`. - -Tip: With rubygems, you can always specify the gem version as the first argument to any executable installed by rubygems. For example: - - sudo gem install leap_cli --version 1.7.2 - sudo gem install leap_cli --version 1.8 - leap _1.7.2_ --version - => leap 1.7.2, ruby 2.1.2 - leap _1.8_ --version - => leap 1.8, ruby 2.1.2 - -Getting started +What is next? ---------------------------------- We recommend reading the platform documentation in the following order: -1. [[Quick start tutorial => tutorials/quick-start]]. -2. [[Platform Guide => guide]]. -3. [[Configuration format => platform/config]]. -4. The `leap` [[command reference => platform/commands]]. +1. [[quick-start]] +2. [[getting-started]] +3. [[platform/guide]] + diff --git a/pages/docs/platform/guide/getting-started.md b/pages/docs/platform/guide/getting-started.md new file mode 100644 index 0000000..6236cba --- /dev/null +++ b/pages/docs/platform/guide/getting-started.md @@ -0,0 +1,145 @@ +@title = 'Getting Started' +@summary = 'An overview of the LEAP Platform' +@toc = true + + +Sensitive files +---------------------------------------------- + +Some files in your provider directory are very sensitive. Leaking these files will compromise your provider. + +Super sensitive and irreplaceable: + +* `files/ca/*.key` -- the private keys for the client and server CAs. +* `files/cert/*.key` -- the private key(s) for the commercial certificate for your domain(s). + +Sensitive, but can be erased and regenerated automatically: + +* `secrets.json` -- various random secrets, such as passwords for databases. +* `files/nodes/*/*.key` -- the private key for each node. +* `hiera/*.yaml` -- hiera file contains a copy of the private key of the node. + +Also, each sysadmin has one or more public ssh keys in `users/*/*_ssh.pub`. Typically, you will want to keep these public keys secure as well. + +See [[keys-and-certificates]] for more information. + +Useful commands +------------------------------------------- + +Here are a few useful `leap` commands: + +* `leap help [COMMAND]` -- get help on COMMAND. +* `leap history [FILTER]` -- show the recent deployment history for the selected nodes. +* `leap ssh web1` -- SSH into node web1 (requires `leap node init web1` first). +* `leap list [FILTER]` -- list the selected nodes. + * `leap list production` -- list only those nodes with the tag 'production' + * `leap list --print ip_address` -- list a particular attribute of all nodes. + +See the full [[commands]] for more information. + +Node filters +------------------------------------------- + +Many of the `leap` commands take a "node filter". You can use a node filter to target a command at one or more nodes. + +A node filter consists of one or more keywords, with an optional "+" before each keyword. + +* keywords can be a node name, a service type, or a tag. +* the "+" before the keyword constructs an AND condition +* otherwise, multiple keywords together construct an OR condition + +Examples: + +* `leap list openvpn` -- list all nodes with service openvpn. +* `leap list openvpn +production` -- only nodes of service type openvpn AND tag production. +* `leap deploy webapp openvpn` -- deploy to all webapp OR openvpn nodes. +* `leap node init ostrich` -- just init the node named ostrich. + +See the full [[commands]] for more information. + +Tracking the provider directory in git +------------------------------------------ + +You should commit your provider changes to your favorite VCS whenever things change. This way you can share your configurations with other admins, all they have to do is to pull the changes to stay up to date. Every time you make a change to your provider, such as adding nodes, services, generating certificates, etc. you should add those to your VCS, commit them and push them to where your repository is hosted. + +Note that your provider directory contains secrets, such as private key material and passwords. You do not want to have those passwords readable by the world, so make sure that wherever you are hosting your repository, it is not public for the world to read. + +If you have a post-commit hook that emails the changes to contributors, you may want to exclude diffs for files that might have sensitive secrets. For example, create a `.gitattributes` file with: + + # No diff, no email for key files + *.key -diff + *.pem -diff + + # Discard diff for secrets.json + secrets.json -diff + + # No diff for hiera files, they contain passwords + hiera/* -diff + + +Editing JSON configuration files +-------------------------------------- + +All the settings that compose your provider are stored in JSON files. + +At a minimum, you will need at least two configuration files: + +* `provider.json` -- general settings for you provider. +* `nodes/NAME.json` -- configuration file for node called "NAME". + +There are a few required properties in provider.json: + + { + "domain": "example.org", + "name": "Example", + "contacts": { + "default": "email1@example.org" + } + } + +See [[provider-configuration]] for more details. + +For node configuration files, there are two required properties: + + { + "ip_address": "1.1.1.1", + "services": ["openvpn"] + } + +See [[services]] for details on what servers are available, and see [[config]] details on how configuration files work. + +How does it work under the hood? +-------------------------------------------- + +You don't need to know any of the details of what happens "under the hood" in order to use the LEAP platform. However, if you are curious as to what is going on, here is a quick primer. + +First, some background terminology: + +* **puppet**: Puppet is a system for automating deployment and management of servers (called nodes). +* **hiera files**: In puppet, you can use something called a 'hiera file' to seed a node with a few configuration values. In LEAP, we go all out and put *every* configuration value needed for a node in the hiera file, and automatically compile a custom hiera file for each node. + +When you run `leap deploy`, a bunch of things happen, in this order: + +1. **Compile hiera files**: The hiera configuration file for each node is compiled in YAML format and saved in the directory `hiera`. The source material for this hiera file consists of all the JSON configuration files imported or inherited by the node's JSON config file. +* **Copy required files to node**: All the files needed for puppet to run are rsync'ed to each node. This includes the entire leap_platform directory, as well as the node's hiera file and other files needed by puppet to set up the node (keys, binary files, etc). +* **Puppet is run**: Once the node is ready, leap connects to the node via ssh and runs `puppet apply`. Puppet is applied locally on the node, without a daemon or puppetmaster. + +You can run `leap -v2 deploy` to see exactly what commands are being executed. + +This mode of operation is fundamentally different from how puppet is normally used: + +* There is no puppetmaster that all the servers take orders from, and there is no puppetd running in the background. +* Servers cannot dynamically query the puppetmaster for information about the other servers. +* There is a static representation for the state of every server that can be committed to git. + +There are advantages and disadvantages to the model that LEAP uses. We have found it very useful for our goal of having a common LEAP platform that many different providers can all use while still allowing providers to configure their unique infrastructure. + +We also find it very beneficial to be able to track the state of your infrastructure in git. + +Traditional system configuration automation systems, like [Puppet](https://puppetlabs.com/puppet/puppet-open-source/) or [Chef](http://www.opscode.com/chef/), deploy changes to servers using a pull method. Each server pulls a manifest from a central master server and uses this to alter the state of the server. + +Instead, the `leap` tool uses a masterless push method: The sysadmin runs `leap deploy` from the provider instance directory on their desktop machine to push the changes out to every server (or a subset of servers). LEAP still uses Puppet, but there is no central master server that each node must pull from. + +One other significant difference between LEAP and typical system automation is how interactions among servers are handled. Rather than store a central database of information about each server that can be queried when a recipe is applied, the `leap` command compiles static representation of all the information a particular server will need in order to apply the recipes. In compiling this static representation, `leap` can use arbitrary programming logic to query and manipulate information about other servers. + +These two approaches, masterless push and pre-compiled static configuration, allow the sysadmin to manage a set of LEAP servers using traditional software development techniques of branching and merging, to more easily create local testing environments using virtual servers, and to deploy without the added complexity and failure potential of a master server. diff --git a/pages/docs/platform/tutorials/quick-start.md b/pages/docs/platform/tutorials/quick-start.md index 83d224c..af4b719 100644 --- a/pages/docs/platform/tutorials/quick-start.md +++ b/pages/docs/platform/tutorials/quick-start.md @@ -1,385 +1,219 @@ @title = 'Quick Start Tutorial' @nav_title = 'Quick Start Tutorial' -@summary = 'This tutorial walks you through the initial process of creating and deploying a minimal service provider running the LEAP Platform. This Quick Start guide will guide you through building a three node OpenVPN provider.' +@summary = 'This tutorial walks you through the initial process of creating and deploying a minimal service provider running the LEAP Platform.' +Introduction +==================================== -Our goal ------------------- +### 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 geographical diversity, or more webapp nodes to increase availability (at the moment, a single couchdb and single webapp server are all that is supported, and performance wise, are more than enough for most usage, since they are only lightly used). At the moment, we strongly advise only have one couchdb server for stability purposes. +We are going to create a minimal LEAP provider, but one that does not offer any actual services. Check out the other tutorials for adding VPN or email services. Our goal is something like this: $ leap list - NODES SERVICES TAGS - cheetah couchdb production - wildebeest webapp production - ostrich openvpn production + NODES SERVICES TAGS + wildebeest couchdb, webapp NOTE: You won't be able to run that `leap list` command yet, not until we actually create the node configurations. -Requirements ------------- +### Requirements -In order to complete this Quick Start, you will need a few things: +1. A workstation: This is your local machine that you will run commands on. +1. A server: This is the machine that you will deploy to. The server can be either: + 1. A local Vagrant virtual machine: a Vagrant machine can only be useful for testing. + 1. A real or paravirtualized server: The server much have Debian Jessie installed, and you must be able to SSH into the machine as root. Paravirtualization includes KVM, Xen, OpenStack, Amazon, but not VirtualBox or OpenVZ. -* You will need three real or paravirtualized virtual machines (KVM, Xen, Openstack, Amazon, but not Vagrant - sorry) that have a basic Debian Wheezy installed (sorry, we don't support Jessie at the moment). If you allocate 20G of disk space to each node for the system, after this process is completed, you will have used less than 10% of that disk space. If you allocate 2 CPUs and 8G of memory to each node, that should be more than enough to begin with. -* You should be able to SSH into them remotely, and know their root password, IP addresses and their SSH host keys -* You will need four different IPs. Each node gets a primary IP, and the OpenVPN gateway additionally needs a gateway IP. -* The ability to create/modify DNS entries for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`. -* You need to be aware that this process will make changes to your systems, so please be sure that these machines are a basic install with nothing configured or running for other purposes -* Your machines will need to be connected to the internet, and not behind a restrictive firewall. -* You should work locally on your laptop/workstation (one that you trust and that is ideally full-disk encrypted) while going through this guide. This is important because the provider configurations you are creating contain sensitive data that should not reside on a remote machine. The `leap` command will login to your servers and configure the services. -* You should do everything described below as an unprivileged user, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly. - -All the commands in this tutorial are run on your sysadmin machine. In order to complete the tutorial, the sysadmin will do the following: - -* Install pre-requisites -* Install the LEAP command-line utility -* Check out the LEAP platform -* Create a provider and its certificates -* Setup the provider's nodes and the services that will reside on those nodes -* Initialize the nodes -* Deploy the LEAP platform to the nodes -* Test that things worked correctly -* Some additional commands - -We will walk you through each of these steps. +Other things to keep in mind: +* The ability to create/modify DNS entries for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`. +* You need to be aware that this process will make changes to your servers, so please be sure that these machines are a basic install with nothing configured or running for other purposes. +* Your servers will need to be connected to the internet, and not behind a restrictive firewall. -Prepare your environment +Prepare your workstation ======================== -There are a few things you need to setup before you can get going. Just some packages, the LEAP cli and the platform. +In order to be able to manage your servers, you need to install the `leap` command on your workstation: -Install pre-requisites --------------------------------- +### Install pre-requisites -*Debian & Ubuntu* +Install core prerequisites on your workstation. -Install core prerequisites: +*Debian & Ubuntu* - $ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make bzip2 + workstation$ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make bzip2 -<!-- *Mac OS* -1. Install rubygems from https://rubygems.org/pages/download (unless the `gem` command is already installed). ---> - -NOTE: leap_cli requires ruby 1.9 or later. + workstation$ brew install ruby-install + workstation$ ruby-install ruby - -Install the LEAP command-line utility -------------------------------------------------- +### Install the LEAP command-line utility Install the `leap` command from rubygems.org: - $ sudo gem install leap_cli - -Alternately, you can install `leap` from source: - - $ git clone https://leap.se/git/leap_cli - $ cd leap_cli - $ rake build - $ sudo rake install - -You can also install from source as an unprivileged user, if you want. For example, instead of `sudo rake install` you can do something like this: - - $ rake install - # watch out for the directory leap is installed to, then i.e. - $ sudo ln -s ~/.gem/ruby/1.9.1/bin/leap /usr/local/bin/leap - -With either `rake install` or `sudo rake install`, you can use now /usr/local/bin/leap, which in most cases will be in your $PATH. - -If you have successfully installed the `leap` command, then you should be able to do the following: - - $ leap --help - -This will list the command-line help options. If you receive an error when doing this, please read through the README.md in the `leap_cli` source to try and resolve any problems before going forwards. - -Check out the platform --------------------------- - -The LEAP Platform is a series of puppet recipes and modules that will be used to configure your provider. You will need a local copy of the platform that will be used to setup your nodes and manage your services. To begin with, you will not need to modify the LEAP Platform. + workstation$ gem install leap_cli --install-dir ~/leap + workstation$ export PATH=$PATH:~/leap/bin -First we'll create a directory for LEAP things, and then we'll check out the platform code and initalize the modules: +Alternately, you can install `leap` system wide: - $ mkdir ~/leap - $ cd ~/leap - $ git clone https://leap.se/git/leap_platform.git - $ cd leap_platform - $ git submodule sync; git submodule update --init + workstation$ sudo gem install leap_cli +To confirm that you installed `leap` correctly, try running `leap help`. -Provider Setup -============== +Create a provider instance +============================================= -A provider instance is a directory tree, usually stored in git, that contains everything you need to manage an infrastructure for a service provider. In this case, we create one for example.org and call the instance directory 'example'. +A provider instance is a directory tree, residing on your workstation, that contains everything you need to manage an infrastructure for a service provider. - $ mkdir -p ~/leap/example +In this case, we create one for example.org and call the instance directory 'example'. -Bootstrap the provider ------------------------ - -Now, we will initialize this directory to make it a provider instance. Your provider instance will need to know where it can find the local copy of the git repository leap_platform, which we setup in the previous step. - - $ cd ~/leap/example - $ leap new . - -NOTES: - . make sure you include that trailing dot! + workstation$ leap new ~/example The `leap new` command will ask you for several required values: * domain: The primary domain name of your service provider. In this tutorial, we will be using "example.org". * name: The name of your service provider (we use "Example"). * contact emails: A comma separated list of email addresses that should be used for important service provider contacts (for things like postmaster aliases, Tor contact emails, etc). -* platform: The directory where you have a copy of the `leap_platform` git repository checked out. +* platform: The directory where you have a copy of the `leap_platform` git repository checked out. If the platform directory does not yet exist, the `leap_platform` will be downloaded and placed in that directory. You could also have passed these configuration options on the command-line, like so: - $ leap new --contacts your@email.here --domain leap.example.org --name Example --platform=~/leap/leap_platform . - -You may want to poke around and see what is in the files we just created. For example: - - $ cat provider.json + workstation$ leap new --contacts your@email.here --domain example.org --name Example --platform=~/leap/leap_platform . -Optionally, commit your provider directory using the version control software you fancy. For example: +You should now have the following files: - $ git init - $ git add . - $ git commit -m "initial provider commit" + workstation$ tree example + example + ├── common.json + ├── Leapfile + ├── nodes/ + ├── provider.json + ├── services/ + └── tags/ Now add yourself as a privileged sysadmin who will have access to deploy to servers: - $ leap add-user --self - -NOTE: in most cases, `leap` must be run from within a provider instance directory tree (e.g. ~/leap/example). - -Create provider certificates ----------------------------- - -Create two certificate authorities, one for server certs and one for client -certs (note: you only need to run this one command to get both): - - $ 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 - -To see details about the keys and certs that the prior two commands created, you can use `leap inspect` like so: - - $ leap inspect files/ca/ca.crt - -Create the Diffie-Hellman parameters file, needed for forward secret OpenVPN ciphers: - - $ leap cert dh - -NOTE: the files `files/ca/*.key` are extremely sensitive and must be carefully protected. The other key files are much less sensitive and can simply be regenerated if needed. - - -Edit provider.json configuration --------------------------------------- - -There are a few required settings in provider.json. At a minimum, you must have: + workstation$ cd example + workstation$ leap add-user --self - { - "domain": "example.org", - "name": "Example", - "contacts": { - "default": "email1@example.org" - } - } - -For a full list of possible settings, you can use `leap inspect` to see how provider.json is evaluated after including the inherited defaults: - - $ leap inspect provider.json - - -Setup the provider's nodes and services ---------------------------------------- - -A "node" is a server that is part of your infrastructure. Every node can have one or more services associated with it. Some nodes are "local" and used only for testing, see [[Development -> platform/details/development]] for more information. - -Create a node, with the service "webapp": - - $ leap node add wildebeest ip_address:x.x.x.w services:webapp tags:production - -NOTE: replace x.x.x.w with the actual IP address of this node +Now create the necessary keys and certificates: -This created a node configuration file in `nodes/wildebeest.json`, but it did not do anything else. It also added the 'tag' called 'production' to this node. Tags allow us to conveniently group nodes together. When creating nodes, you should give them the tag 'production' if the node is to be used in your production infrastructure. + workstation$ leap cert ca + workstation$ leap cert csr -The web application and the VPN nodes require a database, so lets create the database server node: +What do these commands do? The first command will create two Certificate Authorities, one that clients will use to authenticate with the servers and one for backend servers to authenticate with each other. The second command creates a Certificate Signing Request suitable for submission to a commercial CA. It also creates a self-signed certificate for your domain that can be used temporarily for testing. - $ leap node add cheetah ip_address:x.x.x.x services:couchdb tags:production +If you plan to run a real service provider, see important information on [[managing keys and certificates => keys-and-certificates]]. -NOTE: replace x.x.x.x with the actual IP address of this node +Add a node to the provider +================================================== -Now we need the OpenVPN gateway, so lets create that node: +A "node" is a server that is part of your infrastructure. Every node can have one or more services associated with it. We will now add a single node with two services, "webapp" and "couchdb". - $ leap node add ostrich ip_address:x.x.x.y openvpn.gateway_address:x.x.x.z services:openvpn tags:production +You have two choices for node type: a real node or a local node. -NOTE: replace x.x.x.y with the IP address of the machine, and x.x.x.z with the second IP. 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. +* Real Node: A real node is any physical or paravirtualized server, including KVM, Xen, OpenStack Compute, Amazon EC2, but not VirtualBox or OpenVZ (VirtualBox and OpenVZ use a more limited form of virtualization). The server must be running Debian Jessie. +* Local Node: A local node is a virtual machine created by Vagrant, useful for local testing on your workstation. +Getting Vagrant working can be a pain and is [[covered in other tutorials => vagrant]]. If you have a real server available, we suggest you try this tutorial with a real node first. -Setup DNS ---------- +### Option A: Add a real node -Now that you have the nodes configured, you should create the DNS entries for these nodes. +Note: Installing LEAP Platform on this server will potentially destroy anything you have previously installed on this machine. -Set up your DNS with these hostnames: +Create a node, with the services "webapp" and "couchdb": - $ leap list --print ip_address,domain.full,dns.aliases - cheetah x.x.x.w, cheetah.example.org, null - wildebeest x.x.x.x, wildebeest.example.org, api.example.org - ostrich x.x.x.y, ostrich.example.org, null + workstation$ leap node add wildebeest ip_address:x.x.x.w services:webapp,couchdb -Alternately, you can adapt this zone file snippet: +NOTE: replace x.x.x.x with the actual IP address of this server. - $ leap compile zone +### Option B: Add a local node -If you cannot edit your DNS zone file, you can still test your provider by adding entries to your local resolver hosts file (`/etc/hosts` for linux): +Create a node, with the services "webapp" and "couchdb", and then start the local virtual machine: - x.x.x.w cheetah.example.org - x.x.x.x wildebeest.example.org api.example.org example.org - x.x.x.y ostrich.example.org + workstation$ leap node add --local wildebeest services:webapp,couchdb + workstation$ leap local start wildebeest -Please don't forget about these entries, they will override DNS queries if you setup your DNS later. +Deploy your provider +========================================= - -Initialize the nodes --------------------- +### Initialize the node Node initialization only needs to be done once, but there is no harm in doing it multiple times: - $ leap node init production - -This will initialize all nodes with the tag "production". When `leap node init` is run, you will be prompted to verify the fingerprint of the SSH host key and to provide the root password of the server(s). You should only need to do this once. - -If you prefer, you can initalize each node, one at a time: + workstation$ leap node init wildebeest - $ leap node init wildebeest - $ leap node init cheetah - $ leap node init ostrich +This will initialize the node `wildebeest`. When `leap node init` is run, you will be prompted to verify the fingerprint of the SSH host key and to provide the root password of the server(s). You should only need to do this once. -Deploy the LEAP platform to the nodes --------------------- +### Deploy to the node -Now you should deploy the platform recipes to the nodes. [Deployment can take a while to run](https://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine. +The next step is to deploy the LEAP platform to your node. [Deployment can take a while to run](https://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine. -*Important notes:* currently nodes must be deployed in a certain order. The underlying couch database node(s) must be deployed first, and then all other nodes. - - $ leap deploy cheetah + workstation$ leap deploy wildebeest Watch the output for any errors (in red), if everything worked fine, you should now have your first running node. If you do have errors, try doing the deploy again. -However, to deploy our three-node openvpn setup, we need the database and LEAP web application requires a database to run, so let's deploy to the couchdb and openvpn nodes: - - $ leap deploy wildebeest - $ leap deploy ostrich +### Setup DNS +The next step is to configure the DNS for your provider. For testing purposes, you can just modify your `/etc/hosts` file. Please don't forget about these entries, they will override DNS queries if you setup your DNS later. For a list of what entries to add to `/etc/hosts`, run this command: -What is going on here? --------------------------------------------- + workstation$ leap compile hosts -First, some background terminology: +Alternately, if you have access to modify the DNS zone entries for your domain: -* **puppet**: Puppet is a system for automating deployment and management of servers (called nodes). -* **hiera files**: In puppet, you can use something called a 'hiera file' to seed a node with a few configuration values. In LEAP, we go all out and put *every* configuration value needed for a node in the hiera file, and automatically compile a custom hiera file for each node. + workstation$ leap compile zone -When you run `leap deploy`, a bunch of things happen, in this order: - -1. **Compile hiera files**: The hiera configuration file for each node is compiled in YAML format and saved in the directory `hiera`. The source material for this hiera file consists of all the JSON configuration files imported or inherited by the node's JSON config file. -* **Copy required files to node**: All the files needed for puppet to run are rsync'ed to each node. This includes the entire leap_platform directory, as well as the node's hiera file and other files needed by puppet to set up the node (keys, binary files, etc). -* **Puppet is run**: Once the node is ready, leap connects to the node via ssh and runs `puppet apply`. Puppet is applied locally on the node, without a daemon or puppetmaster. - -You can run `leap -v2 deploy` to see exactly what commands are being executed. +NOTE: The resulting zone file is incomplete because it is missing a serial number. Use the output of `leap compile zone` as a guide, but do not just copy and paste the output. +The DNS method will not work for local nodes created with Vagrant. Test that things worked correctly ================================= -You should now have three machines with the LEAP platform deployed to them, one for the web application, one for the database and one for the OpenVPN gateway. - To run troubleshooting tests: - leap test - -If you want to confirm for yourself that things are working, you can perform the following manual tests. + workstation$ leap test -### Access the web application +Alternately, you can run these same tests from the server itself: -In order to connect to the web application in your browser, you need to point your domain at the IP address of the web application node (named wildebeest in this example). + workstation$ leap ssh wildebeest + wildebeest# run_tests -There are a lot of different ways to do this, but one easy way is to modify your `/etc/hosts` file. First, find the IP address of the webapp node: +Create an administrator +=============================== - $ leap list webapp --print ip_address +Assuming that you set up your DNS or `/etc/hosts` file, you should be able to load `https://example.org` in your web browser (where example.org is whatever domain name you actually used). -Then modify `/etc/hosts` like so: +Your browser will complain about an untrusted cert, but for now just bypass this. From there, you should be able to register a new user and login. - x.x.x.w leap.example.org +Once you have created a user, you can now make this user an administrator. For example, if you created a user `kangaroo`, you would create the file `services/webapp.json` with the following content: -Replacing 'leap.example.org' with whatever you specified as the `domain` in the `leap new` command. - -Next, you can connect to the web application either using a web browser or via the API using the LEAP client. To use a browser, connect to https://leap.example.org (replacing that with your domain). Your browser will complain about an untrusted cert, but for now just bypass this. From there, you should be able to register a new user and login. - -### Use the VPN - -You should be able to simply test that the OpenVPN gateway works properly by doing the following: - - $ leap test init - $ sudo openvpn test/openvpn/production_unlimited.ovpn + { + "webapp": { + "admins": ["kangaroo"] + } + } -Or, you can use the LEAP client (called "bitmask") to connect to your new provider, create a user and then connect to the VPN. +Save that file and run `leap deploy` again. When you next log on to the web application, the user kangaroo will now be an admin. +If you want to restrict who can register a new user, see [[webapp]] for configuration options. -Additional information +What is next? ====================== -It is useful to know a few additional things. - -Useful commands ---------------- - -Here are a few useful commands you can run on your new local nodes: - -* `leap ssh wildebeest` -- SSH into node wildebeest (requires `leap node init wildebeest` first). -* `leap list` -- list all nodes. -* `leap list production` -- list only those nodes with the tag 'production' -* `leap list --print ip_address` -- list a particular attribute of all nodes. -* `leap cert update` -- generate new certificates if needed. +Add an end-user service +------------------------------- -See the full command reference for more information. +You should now have a minimal service provider with a single node. This service provider is pointless at the moment, because it does not include any end-user services like VPN or email. To add one of these services, continue with one of the following tutorials: -Node filters -------------------------------------------- +* [[single-node-email]] +* [[single-node-vpn]] -Many of the `leap` commands take a "node filter". You can use a node filter to target a command at one or more nodes. - -A node filter consists of one or more keywords, with an optional "+" before each keyword. - -* keywords can be a node name, a service type, or a tag. -* the "+" before the keyword constructs an AND condition -* otherwise, multiple keywords together construct an OR condition - -Examples: - -* `leap list openvpn` -- list all nodes with service openvpn. -* `leap list openvpn +production` -- only nodes of service type openvpn AND tag production. -* `leap deploy webapp openvpn` -- deploy to all webapp OR openvpn nodes. -* `leap node init ostrich` -- just init the node named ostrich. - -Keep track of your provider configurations ------------------------------------------- - -You should commit your provider changes to your favorite VCS whenever things change. This way you can share your configurations with other admins, all they have to do is to pull the changes to stay up to date. Every time you make a change to your provider, such as adding nodes, services, generating certificates, etc. you should add those to your VCS, commit them and push them to where your repository is hosted. - -Note that your provider directory contains secrets! Those secrets include passwords for various services. You do not want to have those passwords readable by the world, so make sure that wherever you are hosting your repository, it is not public for the world to read. - -What's next ------------------------------------ +Learn more +--------------- -Read the [LEAP platform guide](guide) to learn about planning and securing your infrastructure. +We have only just scratched the surface of the possible ways to configure and deploy your service provider. Your next step should be: +* Read [[getting-started]] for more details on using the LEAP platform. +* See [[commands]] for a list of possible commands. diff --git a/pages/docs/platform/tutorials/single-node-email.md b/pages/docs/platform/tutorials/single-node-email.md index a8407bd..0a73e6e 100644 --- a/pages/docs/platform/tutorials/single-node-email.md +++ b/pages/docs/platform/tutorials/single-node-email.md @@ -1,282 +1,69 @@ @title = 'Single node email tutorial' -@nav_title = 'Single node email' -@summary = 'A single node email provider.' +@nav_title = 'Quick email' +@summary = 'Tutorial for setting up a simple email provider.' -Quick Start - Single node setup -=============================== - -This tutorial walks you through the initial process of creating and deploying a minimal service provider running the [LEAP platform](platform). -We will guide you through building a single node mail provider. +This tutorial walks you through the initial process of creating and deploying a minimal email service provider. Please first complete the [[quick-start]]. This tutorial will pick up where that one left off. Our goal ------------------ -We are going to create a minimal LEAP provider offering Email service. This basic setup can be expanded by adding 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). Please note: currently it is not possible to safely add additional couchdb nodes at a later point. They should all be added in the beginning, so please consider carefully if you would like more before proceeding. +We are going to create a minimal LEAP provider offering email service. Our goal is something like this: $ leap list - NODES SERVICES TAGS - node1 couchdb, mx, soledad, webapp local - -NOTE: You won't be able to run that `leap list` command yet, not until we actually create the node configurations. - -Requirements ------------- - -In order to complete this Quick Start, you will need a few things: - -* You will need `one real or paravirtualized virtual machine` (Vagrant, KVM, Xen, Openstack, Amazon, …) that have a basic Debian Wheezy installed (sorry, we don't support Jessie at the moment). -* You should be able to `SSH into them` remotely, and know their root password, IP addresses and their SSH host keys -* The ability to `create/modify DNS entries` for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`. -* You need to be aware that this process will make changes to your machines, so please be sure that these machines are a basic install with nothing configured or running for other purposes -* Your machines will need to be connected to the internet, and not behind a restrictive firewall. -* You should `work locally on your laptop/workstation` (one that you trust and that is ideally full-disk encrypted) while going through this guide. This is important because the provider configurations you are creating contain sensitive data that should not reside on a remote machine. The leap cli utility will login to your servers and configure the services. -* You should do everything described below as an `unprivileged user`, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly. - -All the commands in this tutorial are run on your sysadmin machine. In order to complete the tutorial, the sysadmin will do the following: - -* Install pre-requisites -* Install the LEAP command-line utility -* Check out the LEAP platform -* Create a provider and its certificates -* Setup the provider's node and the services that will reside on it -* Initialize the node -* Deploy the LEAP platform to the node -* Test that things worked correctly -* Some additional commands - -We will walk you through each of these steps. - - -Prepare your environment -======================== - -There are a few things you need to setup before you can get going. Just some packages, the LEAP cli and the platform. - -Install pre-requisites --------------------------------- - -*Debian & Ubuntu* - -Install core prerequisites: - - $ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make bzip2 - -*Mac OS* - -Install rubygems from https://rubygems.org/pages/download (unless the `gem` command is already installed). - - -NOTE: leap_cli should work with ruby1.8, but has only been tested using ruby1.9. - - -Install the LEAP command-line utility -------------------------------------------------- - -Install the LEAP command-line utility (leap_cli) from rubygems.org: - - $ sudo gem install leap_cli - -Alternately, you can install `leap_cli` from source, please refer to https://leap.se/git/leap_cli/README.md. - -If you have successfully installed `leap_cli`, then you should be able to do the following: - - $ leap --help - -This will list the command-line help options. If you receive an error when doing this, please read through the README.md in the `leap_cli` source to try and resolve any problems before going forwards. - - -Provider Setup -============== - -A provider instance is a directory tree that contains everything you need to manage an infrastructure for a service provider. In this case, we create one for example.org and call the instance directory 'example'. - - $ mkdir -p ~/leap/example - -Bootstrap the provider ------------------------ - -Now, we will initialize this directory to make it a provider instance. Your provider instance will need to know where it can find the local copy of the git repository leap_platform, which we setup in the previous step. - - $ cd ~/leap/example - $ leap new . - -NOTES: - . make sure you include that trailing dot! - -The `leap new` command will ask you for several required values: - -* domain: The primary domain name of your service provider. In this tutorial, we will be using "example.org". -* name: The name of your service provider (we use "Example"). -* contact emails: A comma separated list of email addresses that should be used for important service provider contacts (for things like postmaster aliases, Tor contact emails, etc). -* platform: The directory where you either have a copy of the `leap_platform` git repository already checked out, or where `leap_cli` should download it too. You could just accept the suggested path for this example. - The LEAP Platform is a series of puppet recipes and modules that will be used to configure your provider. You will need a local copy of the platform that will be used to setup your nodes and manage your services. To begin with, you will not need to modify the LEAP Platform. - -These steps should be sufficient for this example. If you want to configure your provider further or like to examine the files, please refer to the [Configure Provider](configure-provider) section. - -Add Users who will have administrative access ---------------------------------------------- - -Now add yourself as a privileged sysadmin who will have access to deploy to servers: - - $ leap add-user --self - -NOTE: in most cases, `leap` must be run from within a provider instance directory tree (e.g. ~/leap/example). - - -Create provider certificates ----------------------------- - -Create two certificate authorities, one for server certs and one for client -certs (note: you only need to run this one command to get both): + NODES SERVICES TAGS + wildebeest couchdb, mx, soledad, webapp - $ leap cert ca +Where 'wildebeest' is whatever name you chose for your node in the [[quick-start]]. -Create a temporary cert for your main domain (you should replace with a real commercial cert at some point) - - $ leap cert csr - - -Setup the provider's node and services +Add email services to the node -------------------------------------- -A "node" is a server that is part of your infrastructure. Every node can have one or more services associated with it. Some nodes are "local" and used only for testing, see [[ development -> platform/details/development]] for more information. - -Create a node, with `all the services needed for Email: "couchdb", "mx", "soledad" and "webapp"` - - $ leap node add node1 ip_address:x.x.x.w services:couchdb,mx,soledad,webapp - -NOTE: replace x.x.x.w with the actual IP address of this node +In order to add [[services => services]] to a node, edit the node's JSON configuration file. -This created a node configuration file in `nodes/node1.json`, but it did not do anything else. It also added the 'tag' called 'production' to this node. Tags allow us to conveniently group nodes together. When creating nodes, you should give them the tag 'production' if the node is to be used in your production infrastructure. +In our example, we would edit `nodes/wildebeest.json`: -Initialize the nodes --------------------- - -Node initialization only needs to be done once, but there is no harm in doing it multiple times: + { + "ip_address": "1.1.1.1", + "services": ["couchdb", "webapp", "mx", "soledad"] + } - $ leap node init node1 +Here, we added `mx` and `soledad` to the node's `services` list. Briefly: -This will initialize the node "node1". When `leap node init` is run, you will be prompted to verify the fingerprint of the SSH host key and to provide the root password of the server. You should only need to do this once. +* **mx**: nodes with the **mx** service will run postfix mail transfer agent, and are able to receive and relay email on behalf of your domain. You can have as many as you want, spread out over as many nodes as you want. +* **soledad**: nodes with **soledad** service run the server-side daemon that allows the client to synchronize a user's personal data store among their devices. Currently, **soledad** only runs on nodes that are also **couchdb** nodes. +For more details, see the [[services]] overview, or the individual pages for the [[mx]] and [[soledad]] services. -Deploy the LEAP platform to the nodes +Deploy to the node -------------------- -Now you should deploy the platform recipes to the node. [Deployment can take a while to run](https://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine. - - $ leap deploy - -Watch the output for any errors (in red), if everything worked fine, you should now have your first running node. If you do have errors, try doing the deploy again. +Now you should deploy to your node. + workstation$ leap deploy Setup DNS ---------- - -Now that you have the node configured, you should create the DNS entrie for this node. - -Set up your DNS with these hostnames: - - $ leap list --print ip_address,domain.full,dns.aliases - node1 x.x.x.w, node1.example.org, example.org, api.example.org, nicknym.example.org - -Alternately, you can adapt this zone file snippet: - - $ leap compile zone - -If you cannot edit your DNS zone file, you can still test your provider by adding this entry to your local resolver hosts file (`/etc/hosts` for linux): - - x.x.x.w node1.example.org example.org api.example.org nicknym.example.org - -Please don't forget about these entries, they will override DNS queries if you setup your DNS later. - - -What is going on here? --------------------------------------------- - -First, some background terminology: - -* **puppet**: Puppet is a system for automating deployment and management of servers (called nodes). -* **hiera files**: In puppet, you can use something called a 'hiera file' to seed a node with a few configuration values. In LEAP, we go all out and put *every* configuration value needed for a node in the hiera file, and automatically compile a custom hiera file for each node. - -When you run `leap deploy`, a bunch of things happen, in this order: - -1. **Compile hiera files**: The hiera configuration file for each node is compiled in YAML format and saved in the directory `hiera`. The source material for this hiera file consists of all the JSON configuration files imported or inherited by the node's JSON config file. -* **Copy required files to node**: All the files needed for puppet to run are rsync'ed to each node. This includes the entire leap_platform directory, as well as the node's hiera file and other files needed by puppet to set up the node (keys, binary files, etc). -* **Puppet is run**: Once the node is ready, leap connects to the node via ssh and runs `puppet apply`. Puppet is applied locally on the node, without a daemon or puppetmaster. - -You can run `leap -v2 deploy` to see exactly what commands are being executed. - -<!-- See [under the hood](under-the-hood) for more details. --> - - -Test that things worked correctly -================================= - -You should now one machine with the LEAP platform email service deployed to it. - - -Access the web application --------------------------------------------- - -In order to connect to the web application in your browser, you need to point your domain at the IP address of your new node. - -Next, you can connect to the web application either using a web browser or via the API using the LEAP client. To use a browser, connect to https://example.org (replacing that with your domain). Your browser will complain about an untrusted cert, but for now just bypass this. From there, you should be able to register a new user and login. - -Testing with leap_cli ---------------------- - -Use the test command to run a set of different tests: - - leap test - - -Additional information -====================== - -It is useful to know a few additional things. - -Useful commands ---------------- - -Here are a few useful commands you can run on your new local nodes: - -* `leap ssh web1` -- SSH into node web1 (requires `leap node init web1` first). -* `leap list` -- list all nodes. -* `leap list production` -- list only those nodes with the tag 'production' -* `leap list --print ip_address` -- list a particular attribute of all nodes. -* `leap cert update` -- generate new certificates if needed. - -See the full command reference for more information. - -Node filters -------------------------------------------- - -Many of the `leap` commands take a "node filter". You can use a node filter to target a command at one or more nodes. +---------------------------- -A node filter consists of one or more keywords, with an optional "+" before each keyword. +There are several important DNS entries that all email providers should have: -* keywords can be a node name, a service type, or a tag. -* the "+" before the keyword constructs an AND condition -* otherwise, multiple keywords together construct an OR condition +* SPF (Sender Policy Framework): With SPF, an email provider advertises in their DNS which servers should be allowed to relay email on behalf of your domain. +* DKIM (DomainKey Identified Mail): With DKIM, an email provider is able to vouch for the validity of certain headers in outgoing mail, allowing the receiving provider to have more confidence in these values when processing the message for spam or abuse. -Examples: +In order to take advantage of SPF and DKIM, run this command: -* `leap list openvpn` -- list all nodes with service openvpn. -* `leap list openvpn +production` -- only nodes of service type openvpn AND tag production. -* `leap deploy webapp openvpn` -- deploy to all webapp OR openvpn nodes. -* `leap node init vpn1` -- just init the node named vpn1. + workstation$ leap compile zone -Keep track of your provider configurations ------------------------------------------- +Then take the output of that command and merge it with the DNS zone file for your domain. -You should commit your provider changes to your favorite VCS whenever things change. This way you can share your configurations with other admins, all they have to do is to pull the changes to stay up to date. Every time you make a change to your provider, such as adding nodes, services, generating certificates, etc. you should add those to your VCS, commit them and push them to where your repository is hosted. +CAUTION: the output of `leap compile zone` is not a complete zone file since it is missing a serial number. You will need to manually merge it with your existing zone file. -Note that your provider directory contains secrets! Those secrets include passwords for various services. You do not want to have those passwords readable by the world, so make sure that wherever you are hosting your repository, it is not public for the world to read. +Test it out +--------------------------------- -What's next ------------------------------------ +First, run: -Read the [LEAP platform guide](guide) to learn about planning and securing your infrastructure. + workstation# leap test +Then fire up the bitmask client, register a new user with your provider, and try sending and receiving email. diff --git a/pages/docs/platform/tutorials/single-node-vpn.md b/pages/docs/platform/tutorials/single-node-vpn.md new file mode 100644 index 0000000..42e61a1 --- /dev/null +++ b/pages/docs/platform/tutorials/single-node-vpn.md @@ -0,0 +1,100 @@ +@title = "Single node VPN tutorial" +@nav_title = "Quick VPN" +@summary = 'Tutorial for setting up a simple VPN provider.' + +This tutorial walks you through the initial process of creating and deploying a minimal VPN service provider. Please first complete the [[quick-start]]. This tutorial will pick up where that one left off. + +NOTE: For the VPN to work, you must use a real or paravirtualized node, not a local Vagrant node. + +Our goal +------------------ + +We are going to create a minimal LEAP provider offering VPN service. + +Our goal is something like this: + + $ leap list + NODES SERVICES TAGS + wildebeest couchdb, webapp, openvpn, tor + +Where 'wildebeest' is whatever name you chose for your node in the [[quick-start]]. + +Add VPN service to the node +-------------------------------------- + +In order to add [[services => services]] to a node, edit the node's JSON configuration file. + +In our example, we would edit `nodes/wildebeest.json`: + + { + "ip_address": "1.1.1.1", + "services": ["couchdb", "webapp", "openvpn", "tor"] + } + +Here, we added `openvpn` and `tor` to the node's `services` list. Briefly: + +* **openvpn**: nodes with the **openvpn** service will become OpenVPN gateways that clients connect to in order to proxy their internet connection. You can have as many as you want, spread out over as many nodes as you want. +* **tor**: nodes with **tor** service become Tor exit nodes. This is entirely optional, and will add additional bandwidth to your node. If you don't have many VPN users, the added traffic will help create cover traffic for your users. On the down side, this VPN gateway will get flagged as an anonymous proxy and some sites may block traffic from it. + +For more details, see the [[services]] overview, or the individual pages for the [[openvpn]] and [[tor]] services. + +Add gateway_address to the node +---------------------------------------- + +VPN gateways require two different IP addresses: + +* `ip_address`: This property is used for VPN traffic **egress**. In other words, all VPN traffic appears to come from this IP address. This is also the main IP of the server. +* `openvpn.gateway_address`: This property is used for VPN traffic **ingress**. In other words, clients will connect to this IP address. + +The node configuration file should now look like this: + + { + "ip_address": "1.1.1.1", + "services": ["couchdb", "webapp", "openvpn", "tor"], + "openvpn": { + "gateway_address": "2.2.2.2" + } + } + +Why two different addresses? Without this, the traffic from one VPN user to another would not be encrypted. This is because the routing table of VPN clients must ensure that packets with a destination of the VPN gateway are sent unmodified and don't get passed through the VPN's encryption. + +Deploy to the node +-------------------- + +Now you should deploy to your node. + + workstation$ leap deploy + +Test it out +--------------------------------- + +First, run: + + workstation$ leap test + +Then fire up the Bitmask client, register a new user with your provider, and turn on the VPN connection. + +Alternately, you can also manually connect to your VPN gateway using OpenVPN on the command line: + + workstation$ leap test init + workstation$ sudo openvpn --config test/openvpn/default_unlimited.ovpn + +Make sure that Bitmask is not connected to the VPN when you run that command. + +The name of the test configuration might differ depending on your setup. The test configuration created by `leap test init` includes a client certificate that will expire, so you may need to re-run `leap test init` if it has been a while since you last generated the test configuration. + +What do do next +-------------------------------- + +A VPN provider with a single gateway is kind of limited. You can add as many nodes with service [[openvpn]] as you like. There is no communication among the VPN gateways or with the [[webapp]] or [[couchdb]] nodes, so there is no issue with scaling out the number of gateways. + +For example, add some more nodes: + + workstation$ leap node add giraffe ip_address:1.1.1.2 services:openvpn openvpn.gateway_address:2.2.2.3 + workstation$ leap node add rhino ip_address:1.1.1.3 services:openvpn openvpn.gateway_address:2.2.2.4 + workstation$ leap node init giraffe rhino + workstation$ leap deploy + +Now you have three VPN gateways. + +One consideration is that you should tag each VPN gateway with a [[location => nodes#locations]]. This helps the client determine which VPN gateway it should connect to by default and will allow the user to choose among gateways based on location. |