Quick Start Tutorial
Introduction
Our goal
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
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
- A workstation: This is your local machine that you will run commands on.
- A server: This is the machine that you will deploy to. The server can be either:
- A local Vagrant virtual machine: a Vagrant machine can only be useful for testing.
- A real or paravirtualized server: The server must 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. Proxmox has an known issue when changing the resolver
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 workstation
In order to be able to manage your servers, you need to setup the LEAP Platform on your desktop. This consists of three parts: the platform recipes, the leap
command, and your provider instance. We will go over these step-by-step below, you can find more details in the platform introduction.
Install pre-requisites
Install core prerequisites on your workstation.
Debian Unstable (sid)
workstation$ sudo apt-get install git rsync openssh-client openssl zlib1g-dev
Other Debian & Ubuntu
workstation$ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make bzip2 zlib1g-dev
Mac OS
workstation$ brew install ruby-install
workstation$ ruby-install ruby
The platform recipes
The LEAP platform recipes are a set modules designed to work together to provide you everything you need to manage your provider. You typically do not need to modify these, but do need them available for deploying your provider.
To obtain the platform recipes, simply clone the git repository, and then check out the most recent stable release branch:
workstation$ git clone -b version/0.9.x https://leap.se/git/leap_platform
If you want to get the latest development branch (Beware: it could be unstable !) you could simply use the master branch instead by:
workstation$ git clone https://leap.se/git/leap_platform
Install the LEAP command-line utility
The leap
command line tool is what you use to manage everything about your provider.
Keep these rules in mind:
leap
is run on your workstation: Theleap
command is always run locally on your workstation, never on a server you are deploying to.leap
is run from within a provider instance: Theleap
command requires that the current working directory is a valid provider instance, except when runningleap new
to create a new provider instance.
If on Debian Unstable (sid), simply do this:
workstation$ sudo apt install leap-cli
Otherwise, you will need to do this:
workstation$ sudo gem install leap_cli
Alternately, you can install leap
locally without root privileges:
workstation$ gem install --user-install leap_cli
workstation$ PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
If you choose a local install, you probably want to permanently add the –user-install directory to your PATH by adding this to your ~/.profile
file (requires logout):
[ $(which ruby) ] && PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
To confirm that you installed leap
correctly, try running leap --version
.
Create a provider instance
A provider instance is a directory tree, residing on your workstation, 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’.
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. If the platform directory does not yet exist, theleap_platform
will be downloaded and placed in that directory.
You could also have passed these configuration options on the command-line, like so:
workstation$ leap new --contacts your@email.here --domain example.org --name Example --platform=~/leap/leap_platform .
You should now have the following files:
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:
workstation$ cd example
workstation$ leap add-user louise --self
Replace “louise” with whatever you want your sysadmin username to be.
NOTE: Make sure you change directories so that the leap
command is run from within the provider instance directory. Most leap
commands only work when run from a provider instance.
Now create the necessary keys and certificates:
workstation$ leap cert ca
workstation$ leap cert csr
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 two “dummy” files for you to use temporarily:
files/cert/example.org.crt
– This is a “dummy” certificate for your domain that can be used temporarily for testing. Once you get a real certificate from a CA, you should replace this file.files/cert/commercial_ca.crt
– This is “dummy” CA cert the corresponds to the dummy domain certificate. Once you replace the domain certificate, also replace this file with the CA cert from the real Certificate Authority.
If you plan to run a real service provider, see important information on managing keys and certificates.
Add a node to the provider
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”.
You have two choices for node type: a real node or a local node.
- 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. If you have a real server available, we suggest you try this tutorial with a real node first.
Option A: Add a real node
Note: Installing LEAP Platform on this server will potentially destroy anything you have previously installed on this machine.
Create a node, with the services “webapp” and “couchdb”:
workstation$ leap node add wildebeest ip_address:x.x.x.w services:webapp,couchdb
NOTE: replace x.x.x.x with the actual IP address of this server.
Option B: Add a local node
Create a node, with the services “webapp”, “soledad” and “couchdb”, and then start the local virtual machine:
workstation$ leap node add --local wildebeest services:webapp,couchdb,soledad
workstation$ leap local start wildebeest
It will take a while to download the Virtualbox base box and create the virtual machine.
Option C: Add a virtual machine in the cloud
In order to create a provider using the cloud, please follow this instructions.
Deploy your provider
Initialize the node
Node initialization only needs to be done once, but there is no harm in doing it multiple times:
workstation$ leap node init wildebeest
This will initialize the node wildebeest
.
For non-local nodes, 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 to the node
The next step is to deploy the LEAP platform to your node. Deployment can take a while to run, especially on the first run, as it needs to update the packages on the new machine.
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.
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:
workstation$ leap compile hosts
Alternately, if you have access to modify the DNS zone entries for your domain:
workstation$ leap compile zone
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. Also, the compile zone
output will always exclude mention of local nodes.
The DNS method will not work for local nodes created with Vagrant.
Test that things worked correctly
To run troubleshooting tests:
workstation$ leap test
Alternately, you can run these same tests from the server itself:
workstation$ leap ssh wildebeest
wildebeest# run_tests
Create an administrator
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).
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.
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:
{
"webapp": {
"admins": ["kangaroo"]
}
}
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.
What is next?
Add an end-user service
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:
Learn more
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 Command Line Reference for a list of possible commands.