summaryrefslogtreecommitdiff
path: root/docs/platform
diff options
context:
space:
mode:
Diffstat (limited to 'docs/platform')
-rw-r--r--docs/platform/development.md7
-rw-r--r--docs/platform/guide.md42
-rw-r--r--docs/platform/known-issues.md11
-rw-r--r--docs/platform/quick-start.md35
-rw-r--r--docs/platform/troubleshooting.md79
5 files changed, 131 insertions, 43 deletions
diff --git a/docs/platform/development.md b/docs/platform/development.md
index 264c647..386b703 100644
--- a/docs/platform/development.md
+++ b/docs/platform/development.md
@@ -154,10 +154,11 @@ You can connect to your local nodes just like you do with normal LEAP nodes, by
However, if you cannot connect to your local node, because the networking is not setup properly, or you have deployed a firewall that locks you out, you may need to access the graphical console.
-In order to do that, you will need to configure Vagrant to launch a graphical console and then you can login as root there to diagnose the networking problem. To do this, add the following to you
-$HOME/.leaprc:
+In order to do that, you will need to configure Vagrant to launch a graphical console and then you can login as root there to diagnose the networking problem. To do this, add the following to your $HOME/.leaprc:
- @custom_vagrant_vm_line = 'config.vm.boot_mode = :gui'
+ @custom_vagrant_vm_line = 'config.vm.provider "virtualbox" do |v|
+ v.gui = true
+ end'
and then start, or restart, your local Vagrant node. You should get a VirtualBox graphical interface presented to you showing you the bootup and eventually the login.
diff --git a/docs/platform/guide.md b/docs/platform/guide.md
index 52c3b2f..99147a8 100644
--- a/docs/platform/guide.md
+++ b/docs/platform/guide.md
@@ -1,7 +1,7 @@
@title = "LEAP Platform Guide"
@nav_title = "Guide"
-Services
+Node types
================================
Every node has one or more services that determines the node's function within your provider's infrastructure.
@@ -24,6 +24,27 @@ Brief overview of the services:
* **tor**: Sets up a tor exit node, unconnected to any other service.
* **dns**: Not yet implemented.
+webapp
+-----------------------------------
+
+The webapp node is responsible for both the user face web application and the API that the client interacts with.
+
+Some users can be "admins" with special powers to answer tickets and close accounts. To make an account into an administrator, you need to configure the `webapp.admins` property with an array of user names.
+
+For example, to make users `alice` and `bob` into admins, create a file `services/webapp.json` with the following content:
+
+ {
+ "webapp": {
+ "admins": ["bob", "alice"]
+ }
+ }
+
+And then redeploy to all webapp nodes:
+
+ leap deploy webapp
+
+By putting this in `services/webapp.json`, you will ensure that all webapp nodes inherit the value for `webapp.admins`.
+
Locations
================================
@@ -264,3 +285,22 @@ There are a few cases when we must gather internal data from a node before we ca
Run `leap help facts update` for more information.
The file `facts.json` should be committed to source control. You might not have a `facts.json` if one is not required for your provider.
+
+Disabling Nodes
+=====================================
+
+There are two ways to temporarily disable a node:
+
+**Option 1: enabled == false**
+
+If a node has a property `enabled` set to false, then the `leap` command will skip over the node and pretend that it does not exist. For example:
+
+ {
+ "ip_address": "1.1.1.1",
+ "services": ["openvpn"],
+ "enabled": false
+ }
+
+**Options 2: no-deploy**
+
+If the file `/etc/leap/no-deploy` exists on a node, then when you run the commmand `leap deploy` it will halt and prevent a deploy from going through (if the node was going to be included in the deploy).
diff --git a/docs/platform/known-issues.md b/docs/platform/known-issues.md
index 90515e3..46a77de 100644
--- a/docs/platform/known-issues.md
+++ b/docs/platform/known-issues.md
@@ -5,6 +5,15 @@
Here you can find documentation about known issues and potential work-arounds in the current Leap Platform release.
+0.5.0rc1
+========
+
+Service separation
+------------------
+
+. You can't deploy all services to one single node. You need at least to seperate the mx and the webapp node. The reason is because they both use haproxy to query the couch db, and haproxy still doesn't have a way to split up its config files in a .d directory (see: https://leap.se/code/issues/3839)
+
+
0.2.2
=====
@@ -56,8 +65,6 @@ Deploying
. When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them
-. Currently, the Webapp node needs to be deployed *after* the couchdb node (see https://leap.se/code/issues/3599)
-
Special Environments
--------------------
diff --git a/docs/platform/quick-start.md b/docs/platform/quick-start.md
index 3b5f33c..3171674 100644
--- a/docs/platform/quick-start.md
+++ b/docs/platform/quick-start.md
@@ -74,9 +74,9 @@ 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 as a gem:
+Install the `leap` command from rubygems.org:
$ sudo gem install leap_cli
@@ -85,38 +85,27 @@ Alternately, you can install `leap` from source:
$ git clone https://leap.se/git/leap_cli
$ cd leap_cli
$ rake build
--->
-
-Install `leap` command from source:
-
- $ git clone https://leap.se/git/leap_cli
- $ cd leap_cli
- $ rake build
-
-Then, install as root user (recommended):
-
$ sudo rake install
-Or, install as unprivileged user:
+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 both methods, you can use now /usr/local/bin/leap, which in most cases will be in your $PATH.
+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 cli, then you should be able to do the following:
+If you have successfully installed the `leap` command, then you should be able to do the following:
$ leap --help
-and be presented with 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.
-
+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.
-Until we have a up to date stable release we recommend using the `develop` branch of the platform for all features of LEAP.
+Until we have a up to date stable release we recommend using the `develop` branch of the platform for all features of LEAP.
First we'll create a directory for LEAP things, and then we'll check out the platform code and initalize the modules:
@@ -138,12 +127,12 @@ A provider instance is a directory tree, usually stored in git, that contains ev
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.
+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:
+NOTES:
. make sure you include that trailing dot!
The `leap new` command will ask you for several required values:
@@ -288,7 +277,7 @@ Note that currently, nodes must be deployed in a certain order. The underlying c
$ leap deploy couch1
-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.
+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:
@@ -319,7 +308,7 @@ You can run `leap -v2 deploy` to see exactly what commands are being executed.
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.
+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.
Access the web application
diff --git a/docs/platform/troubleshooting.md b/docs/platform/troubleshooting.md
index 61149a0..1d1234b 100644
--- a/docs/platform/troubleshooting.md
+++ b/docs/platform/troubleshooting.md
@@ -8,8 +8,8 @@ General
* Please increase verbosity when debugging / filing issues in our issue tracker. You can do this with adding i.e. `-v 5` after the `leap` cmd, i.e. `leap -v 2 deploy`.
-Webapp node
-===========
+Webapp
+======
Places to look for errors
-------------------------
@@ -27,12 +27,17 @@ Is haproxy ok ?
Is couchdb accessible through stunnel ?
---------------------------------------
+* Depending on how many couch nodes you have, increase the port for every test
+ (see /etc/haproxy/haproxy.cfg for the server/port mapping):
+
curl -s -X GET "http://127.0.0.1:4000"
+ curl -s -X GET "http://127.0.0.1:4001"
+ ...
-Check couchdb acl
------------------
+Check couchdb acl as admin
+--------------------------
mkdir /etc/couchdb
cat /srv/leap/webapp/config/couchdb.yml.admin # see username and password
@@ -41,6 +46,17 @@ Check couchdb acl
curl -s --netrc-file /etc/couchdb/couchdb-admin.netrc -X GET "http://127.0.0.1:4096"
curl -s --netrc-file /etc/couchdb/couchdb-admin.netrc -X GET "http://127.0.0.1:4096/_all_dbs"
+
+Check couchdb acl as unpriviledged user
+---------------------------------------
+
+ cat /srv/leap/webapp/config/couchdb.yml # see username and password
+ echo "machine 127.0.0.1 login webapp password <PASSWORD>" > /etc/couchdb/couchdb-webapp.netrc
+ chmod 600 /etc/couchdb/couchdb-webapp.netrc
+
+ curl -s --netrc-file /etc/couchdb/couchdb-webapp.netrc -X GET "http://127.0.0.1:4096"
+ curl -s --netrc-file /etc/couchdb/couchdb-webapp.netrc -X GET "http://127.0.0.1:4096/_all_dbs"
+
Check client config files
-------------------------
@@ -51,8 +67,14 @@ Check client config files
https://example.net/1/config/eip-service.json
-Couchdb node
-============
+Soledad
+=======
+
+ /var/log/soledad.log
+
+
+Couchdb
+=======
Places to look for errors
-------------------------
@@ -67,14 +89,17 @@ Bigcouch membership
* All nodes configured for the provider should appear here:
-
+<pre>
curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET 'http://127.0.0.1:5986/nodes/_all_docs'
+</pre>
* All configured nodes should show up under "cluster_nodes", and the ones online and communicating with each other should appear under "all_nodes". This example output shows the configured cluster nodes `couch1.bitmask.net` and `couch2.bitmask.net`, but `couch2.bitmask.net` is currently not accessible from `couch1.bitmask.net`
+<pre>
curl -s --netrc-file /etc/couchdb/couchdb.netrc 'http://127.0.0.1:5984/_membership'
{"all_nodes":["bigcouch@couch1.bitmask.net"],"cluster_nodes":["bigcouch@couch1.bitmask.net","bigcouch@couch2.bitmask.net"]}
+</pre>
* Sometimes a `/etc/init.d/bigcouch restart` on all nodes is needed, to register new nodes
@@ -83,9 +108,11 @@ Databases
* Following output shows all neccessary DBs that should be present. Note that the `user-0123456....` DBs are the data stores for a particular user.
-
+<pre>
curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET 'http://127.0.0.1:5984/_all_dbs'
["customers","identities","sessions","shared","tickets","tokens","user-0","user-9d34680b01074c75c2ec58c7321f540c","user-9d34680b01074c75c2ec58c7325fb7ff","users"]
+</pre>
+
@@ -95,12 +122,14 @@ Design Documents
* Is User `_design doc` available ?
+<pre>
curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET "http://127.0.0.1:5984/users/_design/User"
+</pre>
-MX node
-=======
+MX
+==
Places to look for errors
-------------------------
@@ -116,15 +145,18 @@ Query leap-mx
* for useraccount
+<pre>
postmap -v -q "joe@dev.bitmask.net" tcp:localhost:2244
...
postmap: dict_tcp_lookup: send: get jow@dev.bitmask.net
postmap: dict_tcp_lookup: recv: 200
...
+</pre>
* for mailalias
+<pre>
postmap -v -q "joe@dev.bitmask.net" tcp:localhost:4242
...
postmap: dict_tcp_lookup: send: get joe@dev.bitmask.net
@@ -132,7 +164,23 @@ Query leap-mx
postmap: dict_tcp_lookup: found: f01bc1c70de7d7d80bc1ad77d987e73a
f01bc1c70de7d7d80bc1ad77d987e73a
...
+</pre>
+
+
+Check couchdb acl as unpriviledged user
+---------------------------------------
+
+
+ cat /etc/leap/mx.conf # see username and password
+ echo "machine 127.0.0.1 login leap_mx password <PASSWORD>" > /etc/couchdb/couchdb-leap_mx.netrc
+ chmod 600 /etc/couchdb/couchdb-leap_mx.netrc
+
+ curl -s --netrc-file /etc/couchdb/couchdb-leap_mx.netrc -X GET "http://127.0.0.1:4096/_all_dbs" # pick one "user-<hash>" db
+ curl -s --netrc-file /etc/couchdb/couchdb-leap_mx.netrc -X GET "http://127.0.0.1:4096/user-de9c77a3d7efbc779c6c20da88e8fb9c"
+
+
+* you may check multiple times, cause 127.0.0.1:4096 is haproxy load-balancing the different couchdb nodes
Mailspool
@@ -142,13 +190,16 @@ Mailspool
+<pre>
ls -la /var/mail/vmail/Maildir/cur/
+</pre>
* Any mails in postfix mailspool longer than a few seconds ?
-
-
+<pre>
mailq
+</pre>
+
Testing mail delivery
@@ -159,8 +210,8 @@ Testing mail delivery
swaks -f alice@example.org -t bob@example.net -s mx1.example.net --port 587 --tls
-VPN node
-========
+VPN
+===
Places to look for errors
-------------------------
generated by cgit v1.2.3 (git 2.25.1) at 2024-09-24 20:07:38 +0000