From 0a09a6e6f247729457d15480f8d2b9bb0b89ae5e Mon Sep 17 00:00:00 2001 From: elijah Date: Mon, 29 Aug 2016 22:55:41 -0700 Subject: Updated (very out of date) docs and README.md --- docs/en/details/development.html | 226 ++++++++++++++++++++++++++++++ docs/en/details/development/index.html | 226 ++++++++++++++++++++++++++++++ docs/en/details/faq.html | 213 ++++++++++++++++++++++++++++ docs/en/details/faq/index.html | 213 ++++++++++++++++++++++++++++ docs/en/details/ports.html | 209 +++++++++++++++++++++++++++ docs/en/details/ports/index.html | 209 +++++++++++++++++++++++++++ docs/en/details/under-the-hood.html | 168 ++++++++++++++++++++++ docs/en/details/under-the-hood/index.html | 168 ++++++++++++++++++++++ 8 files changed, 1632 insertions(+) create mode 100644 docs/en/details/development.html create mode 100644 docs/en/details/development/index.html create mode 100644 docs/en/details/faq.html create mode 100644 docs/en/details/faq/index.html create mode 100644 docs/en/details/ports.html create mode 100644 docs/en/details/ports/index.html create mode 100644 docs/en/details/under-the-hood.html create mode 100644 docs/en/details/under-the-hood/index.html (limited to 'docs/en/details') diff --git a/docs/en/details/development.html b/docs/en/details/development.html new file mode 100644 index 00000000..a21d426b --- /dev/null +++ b/docs/en/details/development.html @@ -0,0 +1,226 @@ + + + + +Development - LEAP Platform Documentation + + + + + + + + +
+
+

Development

+ +
Getting started with making changes to the LEAP platform
+
+
+ + +

Installing leap_cli

+ +

From gem, for a single user

+ +

Install the latest:

+ +
gem install --user-install leap_cli
+
+ +

Or install a particular version:

+ +
gem install --version 1.8 --user-install leap_cli
+
+ +

Add the –user-install directory to your path:

+ +
[ $(which ruby) ] && PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/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
+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/docs/en/details/development/index.html b/docs/en/details/development/index.html new file mode 100644 index 00000000..92506b09 --- /dev/null +++ b/docs/en/details/development/index.html @@ -0,0 +1,226 @@ + + + + +Development - LEAP Platform Documentation + + + + + + + + +
+
+

Development

+ +
Getting started with making changes to the LEAP platform
+
+
+ + +

Installing leap_cli

+ +

From gem, for a single user

+ +

Install the latest:

+ +
gem install --user-install leap_cli
+
+ +

Or install a particular version:

+ +
gem install --version 1.8 --user-install leap_cli
+
+ +

Add the –user-install directory to your path:

+ +
[ $(which ruby) ] && PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/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
+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/docs/en/details/faq.html b/docs/en/details/faq.html new file mode 100644 index 00000000..331e1968 --- /dev/null +++ b/docs/en/details/faq.html @@ -0,0 +1,213 @@ + + + + +FAQ - LEAP Platform Documentation + + + + + + + + +
+
+

Frequently asked questions

+ +
Frequently Asked Questions
+
+
+ + +

APT

+ +

What do I do when unattended upgrades fail?

+ +

When you receive notification e-mails with a subject of ‘unattended-upgrades result for $machinename’, that means that some package couldn’t be automatically upgraded and needs manual interaction. The reasons vary, so you have to be careful. Most often you can simply login to the affected machine and run apt-get dist-upgrade.

+ +

Puppet

+ +

Where do i find the time a server was last deployed ?

+ +

Run:

+ +
leap history FILTER
+
+ +

This will tail the log file /var/log/leap/deploy-summary.log.

+ +

If that command fails, you can manually check the puppet state file on the node indicates the last puppetrun:

+ +
ls -la /var/lib/puppet/state/state.yaml
+
+ +

What resources are touched by puppet/leap_platform (services/packages/files etc.) ?

+ +

Log into your server and issue:

+ +
grep -v '!ruby/sym' /var/lib/puppet/state/state.yaml | sed 's/\"//' | sort
+
+ +

How can i customize the leap_platform puppet manifests ?

+ +

You can create custom puppet modules under files/puppet. +The custom puppet entry point is in class ‘custom’ which can be put into +files/puppet/modules/custom/manifests/init.pp. This class gets automatically included +by site_config::default, which is applied to all nodes.

+ +

Of cause you can also create a different git branch and change whatever you want, if you are +familiar wit git.

+ +

Facter

+ +

How can i see custom facts distributed by leap_platform on a node ?

+ +

On the server, export the FACTERLIB env. variable to include the path of the custom fact in question:

+ +
export FACTERLIB=/var/lib/puppet/lib/facter:/srv/leap/puppet/modules/stdlib/lib/facter/
+facter
+
+ +

Etc

+ +

How do i change the domain of my provider ?

+ +
    +
  • First of all, you need to have access to the nameserver config of your new domain.
    • +
  • Update domain in provider.json
    • +
  • remove all ca and cert files: rm files/cert/* files/ca/*
    • +
  • create ca, csr and certs : leap cert ca; leap cert csr; leap cert dh; leap cert update
    • +
  • deploy
    • +
+ + +
+
+ + diff --git a/docs/en/details/faq/index.html b/docs/en/details/faq/index.html new file mode 100644 index 00000000..9db1398e --- /dev/null +++ b/docs/en/details/faq/index.html @@ -0,0 +1,213 @@ + + + + +FAQ - LEAP Platform Documentation + + + + + + + + +
+
+

Frequently asked questions

+ +
Frequently Asked Questions
+
+
+ + +

APT

+ +

What do I do when unattended upgrades fail?

+ +

When you receive notification e-mails with a subject of ‘unattended-upgrades result for $machinename’, that means that some package couldn’t be automatically upgraded and needs manual interaction. The reasons vary, so you have to be careful. Most often you can simply login to the affected machine and run apt-get dist-upgrade.

+ +

Puppet

+ +

Where do i find the time a server was last deployed ?

+ +

Run:

+ +
leap history FILTER
+
+ +

This will tail the log file /var/log/leap/deploy-summary.log.

+ +

If that command fails, you can manually check the puppet state file on the node indicates the last puppetrun:

+ +
ls -la /var/lib/puppet/state/state.yaml
+
+ +

What resources are touched by puppet/leap_platform (services/packages/files etc.) ?

+ +

Log into your server and issue:

+ +
grep -v '!ruby/sym' /var/lib/puppet/state/state.yaml | sed 's/\"//' | sort
+
+ +

How can i customize the leap_platform puppet manifests ?

+ +

You can create custom puppet modules under files/puppet. +The custom puppet entry point is in class ‘custom’ which can be put into +files/puppet/modules/custom/manifests/init.pp. This class gets automatically included +by site_config::default, which is applied to all nodes.

+ +

Of cause you can also create a different git branch and change whatever you want, if you are +familiar wit git.

+ +

Facter

+ +

How can i see custom facts distributed by leap_platform on a node ?

+ +

On the server, export the FACTERLIB env. variable to include the path of the custom fact in question:

+ +
export FACTERLIB=/var/lib/puppet/lib/facter:/srv/leap/puppet/modules/stdlib/lib/facter/
+facter
+
+ +

Etc

+ +

How do i change the domain of my provider ?

+ +
    +
  • First of all, you need to have access to the nameserver config of your new domain.
    • +
  • Update domain in provider.json
    • +
  • remove all ca and cert files: rm files/cert/* files/ca/*
    • +
  • create ca, csr and certs : leap cert ca; leap cert csr; leap cert dh; leap cert update
    • +
  • deploy
    • +
+ + +
+
+ + diff --git a/docs/en/details/ports.html b/docs/en/details/ports.html new file mode 100644 index 00000000..273781e0 --- /dev/null +++ b/docs/en/details/ports.html @@ -0,0 +1,209 @@ + + + + +Ports - LEAP Platform Documentation + + + + + + + + +
+
+

Ports

+ +
The required open ports for different services.
+
+
+ + +

There are many different ports that must be open in order for the LEAP platform to work. Some ports must be publicly open, meaning that these should be accessible from the public internet. Other ports are privately open, meaning that they must be accessible to sysadmins or to the other nodes in the provider’s infrastructure.

+ +

Every node already includes a host-based firewall. However, if your network has its own firewall, you need to make sure that these ports are not blocked.

+ +

Publicly open ports

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameNode TypeDefaultNotes
SMTPmx25This is required for all server-to-server SMTP email relay. This is not configurable.
HTTPwebapp80Although no actual services are available over port 80, it should be unblocked so that the web app can redirect to port 443. This is not configurable.
HTTPSwebapp443The web application is available over this port. This is not configurable.
SMTPSmx465The client uses this port to submit outgoing email messages via SMTP over TLS. There is no easy way to change this, although you can create a custom files/service-definitions/v1/smtp-service.json.erb to do so. This will be changed to port 443 in the future.
Soledadsoledad2323The client uses this port to synchronize its storage data. This can be changed via the configuration property soledad.port. This will be changed to port 443 in the future.
Nicknymwebapp6425The client uses this port for discovering public keys. This can be changed via the configuration property nickserver.port. This will be changed to port 443 in the future.
OpenVPNopenvpn80, 443, 53, 1194By default, OpenVPN gateways will listen on all those ports. This can be changed via the configuration property openvpn.ports. Note that these ports must be open for openvpn.gateway_address, not for ip_address.
APIwebapp4430Currently, the provider API is accessible via this port. In the future, the default will be changed to 443. For now, this can be changed via the configuration property api.port.
+ + +

Privately open ports

+ + + + + + + + + + + + + + + + + + + + +
NameNode TypeDefaultNotes
SSHall22This is the port that the sshd is bound to for the node. You can modify this using the configuration property ssh.port. It is important that this port is never blocked, or you will lose access to deploy to this node.
Stunnelall10000-20000This is the range of ports that might be used for the encrypted stunnel connections between two nodes. These port numbers are automatically generated, but will fall somewhere in the specified range.
+ + + + +
+
+ + diff --git a/docs/en/details/ports/index.html b/docs/en/details/ports/index.html new file mode 100644 index 00000000..8f738e77 --- /dev/null +++ b/docs/en/details/ports/index.html @@ -0,0 +1,209 @@ + + + + +Ports - LEAP Platform Documentation + + + + + + + + +
+
+

Ports

+ +
The required open ports for different services.
+
+
+ + +

There are many different ports that must be open in order for the LEAP platform to work. Some ports must be publicly open, meaning that these should be accessible from the public internet. Other ports are privately open, meaning that they must be accessible to sysadmins or to the other nodes in the provider’s infrastructure.

+ +

Every node already includes a host-based firewall. However, if your network has its own firewall, you need to make sure that these ports are not blocked.

+ +

Publicly open ports

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameNode TypeDefaultNotes
SMTPmx25This is required for all server-to-server SMTP email relay. This is not configurable.
HTTPwebapp80Although no actual services are available over port 80, it should be unblocked so that the web app can redirect to port 443. This is not configurable.
HTTPSwebapp443The web application is available over this port. This is not configurable.
SMTPSmx465The client uses this port to submit outgoing email messages via SMTP over TLS. There is no easy way to change this, although you can create a custom files/service-definitions/v1/smtp-service.json.erb to do so. This will be changed to port 443 in the future.
Soledadsoledad2323The client uses this port to synchronize its storage data. This can be changed via the configuration property soledad.port. This will be changed to port 443 in the future.
Nicknymwebapp6425The client uses this port for discovering public keys. This can be changed via the configuration property nickserver.port. This will be changed to port 443 in the future.
OpenVPNopenvpn80, 443, 53, 1194By default, OpenVPN gateways will listen on all those ports. This can be changed via the configuration property openvpn.ports. Note that these ports must be open for openvpn.gateway_address, not for ip_address.
APIwebapp4430Currently, the provider API is accessible via this port. In the future, the default will be changed to 443. For now, this can be changed via the configuration property api.port.
+ + +

Privately open ports

+ + + + + + + + + + + + + + + + + + + + +
NameNode TypeDefaultNotes
SSHall22This is the port that the sshd is bound to for the node. You can modify this using the configuration property ssh.port. It is important that this port is never blocked, or you will lose access to deploy to this node.
Stunnelall10000-20000This is the range of ports that might be used for the encrypted stunnel connections between two nodes. These port numbers are automatically generated, but will fall somewhere in the specified range.
+ + + + +
+
+ + diff --git a/docs/en/details/under-the-hood.html b/docs/en/details/under-the-hood.html new file mode 100644 index 00000000..9b7853e3 --- /dev/null +++ b/docs/en/details/under-the-hood.html @@ -0,0 +1,168 @@ + + + + +Under the hood - LEAP Platform Documentation + + + + + + + + +
+
+

Under the hood

+ +
Various implementation details.
+
+
+
    +
  1. + Puppet Details +
      +
    1. + Tags +
        +
      1. + Doing faster partial deploys +
        2. +
      +
      2. +
    +
    2. +
+ +

This page contains various details on the how the platform is implemented. You can safely ignore this page, although it may be useful if you plan to make modifications to the platform.

+ +

Puppet Details

+ +

Tags

+ +

Tags are beeing used to deploy different classes.

+ +
    +
  • leap_base: site_config::default (configure hostname + resolver, sshd, )
    • +
  • leap_slow: site_config::slow (slow: apt-get update, apt-get dist-upgrade)
    • +
  • leap_service: cofigure platform service (openvpn, couchdb, etc.)
    • +
+ + +

You can pass any combination of tags, i.e. use

+ +
    +
  • “–tags leap_base,leap_slow,leap_service” (DEFAULT): Deploy all
    • +
  • “–tags leap_service”: Only deploy service(s) (useful for debugging/development)
    • +
  • “–tags leap_base”: Only deploy basic configuration (again, useful for debugging/development)
    • +
+ + +

Doing faster partial deploys

+ +

If you only change a tiny bit on the platform puppet recipes, you could achieve a +much faster deploy specifying the resource tag you changed. +i.e. you changed the way rsyslog config snippets for LEAP logfiles are created +in puppet/modules/leap/manifests/logfile.pp. This define resource will get tagged +automatically with leap::logfile and you can deploy the change with:

+ +
leap deploy *NODE* --fast --tags=leap::logfile
+
+ +

or, if you just want

+ +
leap deploy --tags=dist_upgrade
+
+ +

See http://docs.puppetlabs.com/puppet/2.7/reference/lang_tags.html for puppet tag usage.

+ +
+
+ + diff --git a/docs/en/details/under-the-hood/index.html b/docs/en/details/under-the-hood/index.html new file mode 100644 index 00000000..e75503f5 --- /dev/null +++ b/docs/en/details/under-the-hood/index.html @@ -0,0 +1,168 @@ + + + + +Under the hood - LEAP Platform Documentation + + + + + + + + +
+
+

Under the hood

+ +
Various implementation details.
+
+
+
    +
  1. + Puppet Details +
      +
    1. + Tags +
        +
      1. + Doing faster partial deploys +
        2. +
      +
      2. +
    +
    2. +
+ +

This page contains various details on the how the platform is implemented. You can safely ignore this page, although it may be useful if you plan to make modifications to the platform.

+ +

Puppet Details

+ +

Tags

+ +

Tags are beeing used to deploy different classes.

+ +
    +
  • leap_base: site_config::default (configure hostname + resolver, sshd, )
    • +
  • leap_slow: site_config::slow (slow: apt-get update, apt-get dist-upgrade)
    • +
  • leap_service: cofigure platform service (openvpn, couchdb, etc.)
    • +
+ + +

You can pass any combination of tags, i.e. use

+ +
    +
  • “–tags leap_base,leap_slow,leap_service” (DEFAULT): Deploy all
    • +
  • “–tags leap_service”: Only deploy service(s) (useful for debugging/development)
    • +
  • “–tags leap_base”: Only deploy basic configuration (again, useful for debugging/development)
    • +
+ + +

Doing faster partial deploys

+ +

If you only change a tiny bit on the platform puppet recipes, you could achieve a +much faster deploy specifying the resource tag you changed. +i.e. you changed the way rsyslog config snippets for LEAP logfiles are created +in puppet/modules/leap/manifests/logfile.pp. This define resource will get tagged +automatically with leap::logfile and you can deploy the change with:

+ +
leap deploy *NODE* --fast --tags=leap::logfile
+
+ +

or, if you just want

+ +
leap deploy --tags=dist_upgrade
+
+ +

See http://docs.puppetlabs.com/puppet/2.7/reference/lang_tags.html for puppet tag usage.

+ +
+
+ + -- cgit v1.2.3