From 811deee9e5b8cc42a3ea424ef873e9d69eb50cba Mon Sep 17 00:00:00 2001 From: elijah Date: Wed, 14 Sep 2016 15:09:32 -0700 Subject: updated docs --- docs/en/guide/commands.html | 253 ++++++++++++++++++++++--- docs/en/guide/commands/index.html | 253 ++++++++++++++++++++++--- docs/en/guide/keys-and-certificates.html | 115 +++++------ docs/en/guide/keys-and-certificates/index.html | 115 +++++------ docs/en/services/couchdb.html | 2 +- docs/en/services/couchdb/index.html | 2 +- docs/en/services/mx.html | 4 +- docs/en/services/mx/index.html | 4 +- 8 files changed, 538 insertions(+), 210 deletions(-) (limited to 'docs') diff --git a/docs/en/guide/commands.html b/docs/en/guide/commands.html index bccbaf50..8685c6dc 100644 --- a/docs/en/guide/commands.html +++ b/docs/en/guide/commands.html @@ -127,7 +127,7 @@ Command Line Reference - LEAP Platform Documentation Global Options
  • - leap add-user USERNAME + leap add-user
  • leap cert @@ -136,11 +136,17 @@ Command Line Reference - LEAP Platform Documentation leap cert ca
  • - leap cert csr + leap cert csr DOMAIN
  • leap cert dh
    • +
  • + leap cert register +
    • +
  • + leap cert renew DOMAIN +
  • leap cert update FILTER
    • @@ -177,9 +183,6 @@ Command Line Reference - LEAP Platform Documentation -
  • - leap debug FILTER -
  • leap deploy FILTER
    • @@ -211,6 +214,9 @@ Command Line Reference - LEAP Platform Documentation
  • leap history FILTER
    • +
  • + leap info FILTER +
  • leap inspect FILE
    • @@ -221,19 +227,19 @@ Command Line Reference - LEAP Platform Documentation leap local
    1. - leap local destroy [FILTER] + leap local ls [FILTER]
    2. leap local reset [FILTER]
    3. - leap local save [FILTER] + leap local rm [FILTER]
    4. - leap local start [FILTER] + leap local save [FILTER]
    5. - leap local status [FILTER] + leap local start [FILTER]
    6. leap local stop [FILTER] @@ -263,6 +269,12 @@ Command Line Reference - LEAP Platform Documentation
    +
  • + leap open NAME +
    • +
  • + leap run COMMAND FILTER +
  • leap scp FILE1 FILE2
    • @@ -283,6 +295,49 @@ Command Line Reference - LEAP Platform Documentation
  • leap tunnel [LOCAL_PORT:]NAME:REMOTE_PORT
    • +
  • + leap user +
      +
    1. + leap user add USERNAME +
      2. +
    2. + leap user ls +
      3. +
    3. + leap user rm USERNAME +
      4. +
    +
    • +
  • + leap vm +
      +
    1. + leap vm add NODE_NAME [SEED] +
      2. +
    2. + leap vm bind NODE_NAME INSTANCE_ID +
      3. +
    3. + leap vm key-list +
      4. +
    4. + leap vm key-register +
      5. +
    5. + leap vm rm [FILTER] +
      6. +
    6. + leap vm start [FILTER] +
      7. +
    7. + leap vm status [FILTER] +
      8. +
    8. + leap vm stop [FILTER] +
      9. +
    +

    • The command “leap” can be used to manage a bevy of servers running the LEAP platform from the comfort of your own home.

    @@ -311,9 +366,11 @@ Skip prompts and assume “yes”.

    -

    leap add-user USERNAME

    +

    leap add-user

    + +

    Manage trusted sysadmins (DEPRECATED)

    -

    Adds a new trusted sysadmin by adding public keys to the “users” directory.

    +

    Use leap user add instead

    Options

    @@ -339,7 +396,7 @@ Add yourself as a trusted sysadmin by choosing among the public keys available f

    See see what values are used in the generation of the certificates (like name and key size), run leap inspect provider and look for the “ca” property. To see the details of the created certs, run leap inspect <file>.

    -

    leap cert csr

    +

    leap cert csr DOMAIN

    Creates a CSR for use in buying a commercial X.509 certificate.

    @@ -383,6 +440,16 @@ Default Value: None

    Creates a Diffie-Hellman parameter file, needed for forward secret OpenVPN ciphers.

    +

    leap cert register

    + +

    Register an authorization key with the CA letsencrypt.org

    + +

    This only needs to be done once.

    + +

    leap cert renew DOMAIN

    + +

    Renews a certificate using the CA letsencrypt.org

    +

    leap cert update FILTER

    Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed.

    @@ -447,12 +514,6 @@ Default Value: None

    -

    leap debug FILTER

    - -

    Output debug information.

    - -

    The FILTER can be the name of a node, service, or tag.

    -

    leap deploy FILTER

    Apply recipes to a node or set of nodes.

    @@ -548,6 +609,12 @@ Show last deploy only

    +

    leap info FILTER

    + +

    Prints information regarding facts, history, and running processes for a node or nodes.

    + +

    The FILTER can be the name of a node, service, or tag.

    +

    leap inspect FILE

    Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag.

    @@ -585,16 +652,20 @@ Include disabled nodes in the list.

    Manage local virtual machines.

    -

    This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in ‘test/Vagrantfile’. If you want to run vagrant commands manually, cd to ‘test’.

    +

    This command provides a convenient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in ‘test/Vagrantfile’. If you want to run vagrant commands manually, cd to ‘test’.

    -

    leap local destroy [FILTER]

    +

    leap local ls [FILTER]

    -

    Destroys the virtual machine(s), reclaiming the disk space

    +

    Print the status of local virtual machine(s)

    leap local reset [FILTER]

    Resets virtual machine(s) to the last saved snapshot

    +

    leap local rm [FILTER]

    + +

    Destroys the virtual machine(s), reclaiming the disk space

    +

    leap local save [FILTER]

    Saves the current state of the virtual machine as a new snapshot

    @@ -612,10 +683,6 @@ Default Value: LEAP/jessie -

    leap local status [FILTER]

    - -

    Print the status of local virtual machine(s)

    -

    leap local stop [FILTER]

    Shuts down the virtual machine(s)

    @@ -674,13 +741,15 @@ Default Value: None

    To set nested properties, property name can contain ‘.’, like so: leap node add web1 ssh.port:44

    -

    Separeate multiple values for a single property with a comma, like so: leap node add mynode services:webapp,dns

    +

    Separate multiple values for a single property with a comma, like so: leap node add mynode services:webapp,dns

    Options

    @@ -698,9 +767,8 @@ Override the default SSH IP address. Default Value: None

  • --port PORT Override the default SSH port. +This command prepares a server to be used with the LEAP Platform by saving the server’s SSH host key, copying the authorized_keys file, installing packages that are required for deploying, and registering important facts. Node init must be run before deploying to a server, and the server must be running and available via the network. This command only needs to be run once, but there is no harm in running it multiple times. Default Value: None

    • -

  • --echo -If set, passwords are visible as you type them (default is hidden)

    • @@ -712,6 +780,40 @@ If set, passwords are visible as you type them (default is hidden)

    Removes all the files related to the node named NAME.

    +

    leap open NAME

    + +

    Opens useful URLs in a web browser.

    + +

    NAME can be one or more of: monitor, web, docs, bug

    + +

    Options

    + + + + +

    leap run COMMAND FILTER

    + +

    Run a shell command remotely

    + +

    Runs the specified command COMMAND on each node in the FILTER set. For example, leap run 'uname -a' webapp

    + +

    Options

    + + + +

    leap scp FILE1 FILE2

    Secure copy from FILE1 to FILE2. Files are specified as NODE_NAME:FILE_PATH. For local paths, omit “NODE_NAME:”.

    @@ -778,6 +880,97 @@ Default Value: None

    +

    leap user

    + +

    Manage trusted sysadmins

    + +

    Manage the trusted sysadmins that are configured in the ‘users’ directory.

    + +

    leap user add USERNAME

    + +

    Adds a new trusted sysadmin

    + +

    Options

    + + + + +

    leap user ls

    + +

    Lists the configured sysadmins

    + +

    leap user rm USERNAME

    + +

    Removes a trusted sysadmin

    + +

    leap vm

    + +

    Manage remote virtual machines (VMs).

    + +

    This command provides a convenient way to manage virtual machines. FILTER may be a node filter or the ID of a virtual machine.

    + +

    Options

    + + + + +

    leap vm add NODE_NAME [SEED]

    + +

    Allocates a new VM and/or associates it with node NAME.

    + +

    If node configuration file does not yet exist, it is created with the optional SEED values. You can run this command when the virtual machine already exists in order to update the node’s vm.id property.

    + +

    leap vm bind NODE_NAME INSTANCE_ID

    + +

    Binds a running VM instance to a node configuration.

    + +

    Afterwards, the VM will be assigned a label matching the node name, and the node config will be updated with the instance ID.

    + +

    leap vm key-list

    + +

    Lists the registered SSH public keys for a particular VM provider.

    + +

    leap vm key-register

    + +

    Registers a SSH public key for use when creating new VMs.

    + +

    Note that only people who are creating new VM instances need to have their key registered.

    + +

    leap vm rm [FILTER]

    + +

    Destroys one or more VMs

    + +

    leap vm start [FILTER]

    + +

    Starts one or more VMs

    + +

    leap vm status [FILTER]

    + +

    Print the status of all VMs

    + +

    leap vm stop [FILTER]

    + +

    Shuts down one or more VMs

    + +

    This keeps the storage allocated. To save resources, run leap vm rm instead.

    + diff --git a/docs/en/guide/commands/index.html b/docs/en/guide/commands/index.html index ec1785f8..fbb77d87 100644 --- a/docs/en/guide/commands/index.html +++ b/docs/en/guide/commands/index.html @@ -127,7 +127,7 @@ Command Line Reference - LEAP Platform Documentation Global Options
  • - leap add-user USERNAME + leap add-user
  • leap cert @@ -136,11 +136,17 @@ Command Line Reference - LEAP Platform Documentation leap cert ca
  • - leap cert csr + leap cert csr DOMAIN
  • leap cert dh
    • +
  • + leap cert register +
    • +
  • + leap cert renew DOMAIN +
  • leap cert update FILTER
    • @@ -177,9 +183,6 @@ Command Line Reference - LEAP Platform Documentation -
  • - leap debug FILTER -
  • leap deploy FILTER
    • @@ -211,6 +214,9 @@ Command Line Reference - LEAP Platform Documentation
  • leap history FILTER
    • +
  • + leap info FILTER +
  • leap inspect FILE
    • @@ -221,19 +227,19 @@ Command Line Reference - LEAP Platform Documentation leap local
    1. - leap local destroy [FILTER] + leap local ls [FILTER]
    2. leap local reset [FILTER]
    3. - leap local save [FILTER] + leap local rm [FILTER]
    4. - leap local start [FILTER] + leap local save [FILTER]
    5. - leap local status [FILTER] + leap local start [FILTER]
    6. leap local stop [FILTER] @@ -263,6 +269,12 @@ Command Line Reference - LEAP Platform Documentation
    +
  • + leap open NAME +
    • +
  • + leap run COMMAND FILTER +
  • leap scp FILE1 FILE2
    • @@ -283,6 +295,49 @@ Command Line Reference - LEAP Platform Documentation
  • leap tunnel [LOCAL_PORT:]NAME:REMOTE_PORT
    • +
  • + leap user +
      +
    1. + leap user add USERNAME +
      2. +
    2. + leap user ls +
      3. +
    3. + leap user rm USERNAME +
      4. +
    +
    • +
  • + leap vm +
      +
    1. + leap vm add NODE_NAME [SEED] +
      2. +
    2. + leap vm bind NODE_NAME INSTANCE_ID +
      3. +
    3. + leap vm key-list +
      4. +
    4. + leap vm key-register +
      5. +
    5. + leap vm rm [FILTER] +
      6. +
    6. + leap vm start [FILTER] +
      7. +
    7. + leap vm status [FILTER] +
      8. +
    8. + leap vm stop [FILTER] +
      9. +
    +

    • The command “leap” can be used to manage a bevy of servers running the LEAP platform from the comfort of your own home.

    @@ -311,9 +366,11 @@ Skip prompts and assume “yes”.

    -

    leap add-user USERNAME

    +

    leap add-user

    + +

    Manage trusted sysadmins (DEPRECATED)

    -

    Adds a new trusted sysadmin by adding public keys to the “users” directory.

    +

    Use leap user add instead

    Options

    @@ -339,7 +396,7 @@ Add yourself as a trusted sysadmin by choosing among the public keys available f

    See see what values are used in the generation of the certificates (like name and key size), run leap inspect provider and look for the “ca” property. To see the details of the created certs, run leap inspect <file>.

    -

    leap cert csr

    +

    leap cert csr DOMAIN

    Creates a CSR for use in buying a commercial X.509 certificate.

    @@ -383,6 +440,16 @@ Default Value: None

    Creates a Diffie-Hellman parameter file, needed for forward secret OpenVPN ciphers.

    +

    leap cert register

    + +

    Register an authorization key with the CA letsencrypt.org

    + +

    This only needs to be done once.

    + +

    leap cert renew DOMAIN

    + +

    Renews a certificate using the CA letsencrypt.org

    +

    leap cert update FILTER

    Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed.

    @@ -447,12 +514,6 @@ Default Value: None

    -

    leap debug FILTER

    - -

    Output debug information.

    - -

    The FILTER can be the name of a node, service, or tag.

    -

    leap deploy FILTER

    Apply recipes to a node or set of nodes.

    @@ -548,6 +609,12 @@ Show last deploy only

    +

    leap info FILTER

    + +

    Prints information regarding facts, history, and running processes for a node or nodes.

    + +

    The FILTER can be the name of a node, service, or tag.

    +

    leap inspect FILE

    Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag.

    @@ -585,16 +652,20 @@ Include disabled nodes in the list.

    Manage local virtual machines.

    -

    This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in ‘test/Vagrantfile’. If you want to run vagrant commands manually, cd to ‘test’.

    +

    This command provides a convenient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in ‘test/Vagrantfile’. If you want to run vagrant commands manually, cd to ‘test’.

    -

    leap local destroy [FILTER]

    +

    leap local ls [FILTER]

    -

    Destroys the virtual machine(s), reclaiming the disk space

    +

    Print the status of local virtual machine(s)

    leap local reset [FILTER]

    Resets virtual machine(s) to the last saved snapshot

    +

    leap local rm [FILTER]

    + +

    Destroys the virtual machine(s), reclaiming the disk space

    +

    leap local save [FILTER]

    Saves the current state of the virtual machine as a new snapshot

    @@ -612,10 +683,6 @@ Default Value: LEAP/jessie -

    leap local status [FILTER]

    - -

    Print the status of local virtual machine(s)

    -

    leap local stop [FILTER]

    Shuts down the virtual machine(s)

    @@ -674,13 +741,15 @@ Default Value: None

    To set nested properties, property name can contain ‘.’, like so: leap node add web1 ssh.port:44

    -

    Separeate multiple values for a single property with a comma, like so: leap node add mynode services:webapp,dns

    +

    Separate multiple values for a single property with a comma, like so: leap node add mynode services:webapp,dns

    Options

    @@ -698,9 +767,8 @@ Override the default SSH IP address. Default Value: None

  • --port PORT Override the default SSH port. +This command prepares a server to be used with the LEAP Platform by saving the server’s SSH host key, copying the authorized_keys file, installing packages that are required for deploying, and registering important facts. Node init must be run before deploying to a server, and the server must be running and available via the network. This command only needs to be run once, but there is no harm in running it multiple times. Default Value: None

    • -

  • --echo -If set, passwords are visible as you type them (default is hidden)

    • @@ -712,6 +780,40 @@ If set, passwords are visible as you type them (default is hidden)

    Removes all the files related to the node named NAME.

    +

    leap open NAME

    + +

    Opens useful URLs in a web browser.

    + +

    NAME can be one or more of: monitor, web, docs, bug

    + +

    Options

    + + + + +

    leap run COMMAND FILTER

    + +

    Run a shell command remotely

    + +

    Runs the specified command COMMAND on each node in the FILTER set. For example, leap run 'uname -a' webapp

    + +

    Options

    + + + +

    leap scp FILE1 FILE2

    Secure copy from FILE1 to FILE2. Files are specified as NODE_NAME:FILE_PATH. For local paths, omit “NODE_NAME:”.

    @@ -778,6 +880,97 @@ Default Value: None

    +

    leap user

    + +

    Manage trusted sysadmins

    + +

    Manage the trusted sysadmins that are configured in the ‘users’ directory.

    + +

    leap user add USERNAME

    + +

    Adds a new trusted sysadmin

    + +

    Options

    + + + + +

    leap user ls

    + +

    Lists the configured sysadmins

    + +

    leap user rm USERNAME

    + +

    Removes a trusted sysadmin

    + +

    leap vm

    + +

    Manage remote virtual machines (VMs).

    + +

    This command provides a convenient way to manage virtual machines. FILTER may be a node filter or the ID of a virtual machine.

    + +

    Options

    + + + + +

    leap vm add NODE_NAME [SEED]

    + +

    Allocates a new VM and/or associates it with node NAME.

    + +

    If node configuration file does not yet exist, it is created with the optional SEED values. You can run this command when the virtual machine already exists in order to update the node’s vm.id property.

    + +

    leap vm bind NODE_NAME INSTANCE_ID

    + +

    Binds a running VM instance to a node configuration.

    + +

    Afterwards, the VM will be assigned a label matching the node name, and the node config will be updated with the instance ID.

    + +

    leap vm key-list

    + +

    Lists the registered SSH public keys for a particular VM provider.

    + +

    leap vm key-register

    + +

    Registers a SSH public key for use when creating new VMs.

    + +

    Note that only people who are creating new VM instances need to have their key registered.

    + +

    leap vm rm [FILTER]

    + +

    Destroys one or more VMs

    + +

    leap vm start [FILTER]

    + +

    Starts one or more VMs

    + +

    leap vm status [FILTER]

    + +

    Print the status of all VMs

    + +

    leap vm stop [FILTER]

    + +

    Shuts down one or more VMs

    + +

    This keeps the storage allocated. To save resources, run leap vm rm instead.

    + diff --git a/docs/en/guide/keys-and-certificates.html b/docs/en/guide/keys-and-certificates.html index ee7d2699..f5f83066 100644 --- a/docs/en/guide/keys-and-certificates.html +++ b/docs/en/guide/keys-and-certificates.html @@ -165,7 +165,7 @@ Keys and Certificates - LEAP Platform Documentation Client certificates
  • - Commercial certificates + Signed certificates
  • Examine Certs @@ -173,16 +173,13 @@ Keys and Certificates - LEAP Platform Documentation
  • - Let’s Encrypt certificate + Let’s Encrypt
    1. - Install the official acme client + Creating a certificate
    2. - Fetch cert -
      3. -
    3. - Deploy the certs + Renewing a certificate
    • @@ -351,9 +348,9 @@ leap deploy

    There are two types of client certificates: limited and unlimited. A client using a limited cert will have its bandwidth limited to the rate specified by provider.service.bandwidth_limit (in Bytes per second). An unlimited cert is given to the user if they authenticate and the user’s service level matches one configured in provider.service.levels without bandwidth limits. Otherwise, the user is given a limited client cert.

    -

    Commercial certificates

    +

    Signed certificates

    -

    We strongly recommend that you use a commercial signed server certificate for your primary domain (in other words, a certificate with a common name matching whatever you have configured for provider.domain). This provides several benefits:

    +

    We strongly recommend that the primary domain for your provider has a certificate signed by a “trusted CA” (e.g. A Certificate Authority that is trusted by the web browsers and in the Debian ca-certificates package). This provides several benefits:

    1. When users visit your website, they don’t get a scary notice that something is wrong.
      2. @@ -362,28 +359,38 @@ leap deploy
    -

    The LEAP platform is designed so that it assumes you are using a commercial cert for the primary domain of your provider, but all other servers are assumed to use non-commercial certs signed by the Server CA you create.

    +

    The LEAP platform is designed so that it assumes you are using a certificate signed by a “trusted CA” for the primary domain of your provider, but all other servers are assumed to use certs signed by the Server CA you create.

    To generate a CSR, run:

    -
    leap cert csr
+
    leap cert csr [DOMAIN]
 
    
 
-
    This command will generate the CSR and private key matching provider.domain (you can change the domain with --domain=DOMAIN switch). It also generates a server certificate signed with the Server CA. You should delete this certificate and replace it with a real one once it is created by your commercial CA.
    
+
    This command will generate the CSR and private key matching provider.domain or use DOMAIN. It also generates a server certificate signed with the Server CA. You should delete this certificate and replace it with a real one you get back from a “trusted CA”.
    
 
 
    The related commercial cert files are:
    
 
 
    files/
   cert/
-    domain.org.crt    # Server certificate for domain.org, obtained by commercial CA.
-    domain.org.csr    # Certificate signing request
-    domain.org.key    # Private key for you certificate
-    commercial_ca.crt # The CA cert obtained from the commercial CA.
+    domain.org.crt    # Server certificate for domain.org, obtained from
+                      # the trusted CA (this file is initially signed with
+                      # the Server CA, but you should replace it).
+    domain.org.csr    # Certificate signing request (PEM format)
+    domain.org.key    # Private key for you certificate (PEM format)
+    commercial_ca.crt # DEPRECATED: The certificate chain obtained from
+                      # the trusted CA (PEM format)
 
    
 
 
    The private key file is extremely sensitive and care should be taken with its provenance.
    
 
-
    If your commercial CA has a chained CA cert, you should be OK if you just put the last cert in the chain into the commercial_ca.crt file. This only works if the other CAs in the chain have certs in the debian package ca-certificates, which is the case for almost all CAs.
    
+
    A few notes on the certificate chain:
    
+
+
      
+
    • A certificate is basically just a key signed by another key. In x.509, the signing key might be signed by yet another key, and so on, all the way to a ‘root’ key. It is the root key that a browser trusts or is in the Debian ca-certificates package. The chain is the set of all the keys from the root to the end certificate.
      • 
+
    • For TLS, both the server and the client need the full chain from the certificate to the CA’s root.
      • 
+
    • The full chain should be appended in the file domain.org.crt after the server certificate. The chain can also live in commercial_ca.crt, but this is deprecated.
      • 
+
    
+
 
 
    If you want to add additional fields to the CSR, like country, city, or locality, you can configure these values in provider.json like so:
    
 
@@ -405,74 +412,38 @@ leap deploy
 
    $ leap inspect files/ca/ca.crt
 
    
 
-
    Let’s Encrypt certificate
    
-
-
    LEAP plans to integrate Let’s Encrypt support, so it will be even easier to receive X.509 certificates that are accepted by all browsers.
-Until we achieve this, here’s a guide how to do this manually.
    
-
-
    Install the official acme client
    
-
-
    Log in to your webapp node
    
-
-
    server$ git clone https://github.com/certbot/certbot
-server$ cd certbot
-server$ ./certbot-auto --help
-
    
-
-
    Fetch cert
    
-
-
    Stop apache so the letsencrypt client can bind to port 80:
    
-
-
    server$ systemctl stop apache2
-
    
-
-
    Fetch the certs
    
+
    Let’s Encrypt
    
 
-
    server$ ./certbot-auto certonly --standalone --email admin@$(hostname -d) -d $(hostname -d) -d api.$(hostname -d) -d $(hostname -f) -d nicknym.$(hostname -d)
-
    
-
-
    This will put the certs and keys into /etc/letsencrypt/live/DOMAIN/.
    
+
    Let’s Encrypt is a free “trusted CA”. You can obtain signed certificates from Let’s Encrypt very easily using the LEAP command line, so long as you have first set up DNS correctly.
    
 
-
    Now, go to your workstation’s provider configuration directory and copy the newly created files from the server to your local config. You will override existing files so please make a backup before proceeding, or use a version control system to track changes.
    
-
-
    workstation$ cd PATH_TO_PROVIDER_CONFIG
-
    
+
    Creating a certificate
    
 
-
    Copy the Certificate
    
+
    For example:
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/cert.pem files/cert/dev.pixelated-project.org.crt
+
    workstation$ leap cert register
+workstation$ leap cert csr demo.bitmask.net
+workstation$ leap cert renew demo.bitmask.net
+workstation$ leap deploy
 
    
 
-
    Copy the private key
    
+
    Some notes:
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/privkey.pem files/cert/DOMAIN.key
-
    
-
-
    Copy the CA chain cert
    
+
      
+
    1. You only need to run leap cert register once. Registering will save the Let’s Encrypt account key to files/ca/lets-encrypt-account.key. If you delete this file, just run leap cert register again.
      2. 
+
    2. Let’s Encrypt support requires that you have already platform 0.9 or later.
      3. 
+
    3. This requires that the DNS records are correct for the domain.
      4. 
+
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/fullchain.pem files/cert/commercial_ca.crt
-
    
 
-
    Deploy the certs
    
+
    Renewing a certificate
    
 
-
    Now you only need to deploy the certs
    
+
    Let’s Encrypt validations are short lived. You will need to renew the certificate at least once every three months. There is no harm in doing it more regularly, however. You can renew your cert every day if you wanted.
    
 
-
    workstation$ leap deploy
+
    workstation$ leap cert renew demo.bitmask.net
+workstation$ leap deploy
 
    
 
-
    This will put them into the right locations which are:
    
-
-
      
-
    • /etc/x509/certs/leap_commercial.crt for the certificate
      • 
-
    • /etc/x509/./keys/leap_commercial.key for the private key
      • 
-
    • /usr/local/share/ca-certificates/leap_commercial_ca.crt for the CA chain cert.
      • 
-
    
-
-
-
    Start apache2 again
    
-
-
    server$ systemctl start apache2
-
    
+
    There is no need to create a new CSR: renewing will reuse the old private key and the old CSR. It is especially important to not create a new CSR if you have advertised public key pins using HPKP.
    
 
 
 
diff --git a/docs/en/guide/keys-and-certificates/index.html b/docs/en/guide/keys-and-certificates/index.html
index 4775de5a..016a03a7 100644
--- a/docs/en/guide/keys-and-certificates/index.html
+++ b/docs/en/guide/keys-and-certificates/index.html
@@ -165,7 +165,7 @@ Keys and Certificates - LEAP Platform Documentation
         Client certificates
       
       
  • 
-        Commercial certificates
+        Signed certificates
       
    • 
       
  • 
         Examine Certs
@@ -173,16 +173,13 @@ Keys and Certificates - LEAP Platform Documentation
     
   
    • 
   
  • 
-    Let’s Encrypt certificate
+    Let’s Encrypt
     
      
       
    1. 
-        Install the official acme client
+        Creating a certificate
       
      2. 
       
    2. 
-        Fetch cert
-      
      3. 
-      
    3. 
-        Deploy the certs
+        Renewing a certificate
       
      4. 
     
    
   
    • 
@@ -351,9 +348,9 @@ leap deploy
 
 
    There are two types of client certificates: limited and unlimited. A client using a limited cert will have its bandwidth limited to the rate specified by provider.service.bandwidth_limit (in Bytes per second). An unlimited cert is given to the user if they authenticate and the user’s service level matches one configured in provider.service.levels without bandwidth limits. Otherwise, the user is given a limited client cert.
    
 
-
    Commercial certificates
    
+
    Signed certificates
    
 
-
    We strongly recommend that you use a commercial signed server certificate for your primary domain (in other words, a certificate with a common name matching whatever you have configured for provider.domain). This provides several benefits:
    
+
    We strongly recommend that the primary domain for your provider has a certificate signed by a “trusted CA” (e.g. A Certificate Authority that is trusted by the web browsers and in the Debian ca-certificates package). This provides several benefits:
    
 
 
      
 
    1. When users visit your website, they don’t get a scary notice that something is wrong.
      2. 
@@ -362,28 +359,38 @@ leap deploy
 
    
 
 
-
    The LEAP platform is designed so that it assumes you are using a commercial cert for the primary domain of your provider, but all other servers are assumed to use non-commercial certs signed by the Server CA you create.
    
+
    The LEAP platform is designed so that it assumes you are using a certificate signed by a “trusted CA” for the primary domain of your provider, but all other servers are assumed to use certs signed by the Server CA you create.
    
 
 
    To generate a CSR, run:
    
 
-
    leap cert csr
+
    leap cert csr [DOMAIN]
 
    
 
-
    This command will generate the CSR and private key matching provider.domain (you can change the domain with --domain=DOMAIN switch). It also generates a server certificate signed with the Server CA. You should delete this certificate and replace it with a real one once it is created by your commercial CA.
    
+
    This command will generate the CSR and private key matching provider.domain or use DOMAIN. It also generates a server certificate signed with the Server CA. You should delete this certificate and replace it with a real one you get back from a “trusted CA”.
    
 
 
    The related commercial cert files are:
    
 
 
    files/
   cert/
-    domain.org.crt    # Server certificate for domain.org, obtained by commercial CA.
-    domain.org.csr    # Certificate signing request
-    domain.org.key    # Private key for you certificate
-    commercial_ca.crt # The CA cert obtained from the commercial CA.
+    domain.org.crt    # Server certificate for domain.org, obtained from
+                      # the trusted CA (this file is initially signed with
+                      # the Server CA, but you should replace it).
+    domain.org.csr    # Certificate signing request (PEM format)
+    domain.org.key    # Private key for you certificate (PEM format)
+    commercial_ca.crt # DEPRECATED: The certificate chain obtained from
+                      # the trusted CA (PEM format)
 
    
 
 
    The private key file is extremely sensitive and care should be taken with its provenance.
    
 
-
    If your commercial CA has a chained CA cert, you should be OK if you just put the last cert in the chain into the commercial_ca.crt file. This only works if the other CAs in the chain have certs in the debian package ca-certificates, which is the case for almost all CAs.
    
+
    A few notes on the certificate chain:
    
+
+
      
+
    • A certificate is basically just a key signed by another key. In x.509, the signing key might be signed by yet another key, and so on, all the way to a ‘root’ key. It is the root key that a browser trusts or is in the Debian ca-certificates package. The chain is the set of all the keys from the root to the end certificate.
      • 
+
    • For TLS, both the server and the client need the full chain from the certificate to the CA’s root.
      • 
+
    • The full chain should be appended in the file domain.org.crt after the server certificate. The chain can also live in commercial_ca.crt, but this is deprecated.
      • 
+
    
+
 
 
    If you want to add additional fields to the CSR, like country, city, or locality, you can configure these values in provider.json like so:
    
 
@@ -405,74 +412,38 @@ leap deploy
 
    $ leap inspect files/ca/ca.crt
 
    
 
-
    Let’s Encrypt certificate
    
-
-
    LEAP plans to integrate Let’s Encrypt support, so it will be even easier to receive X.509 certificates that are accepted by all browsers.
-Until we achieve this, here’s a guide how to do this manually.
    
-
-
    Install the official acme client
    
-
-
    Log in to your webapp node
    
-
-
    server$ git clone https://github.com/certbot/certbot
-server$ cd certbot
-server$ ./certbot-auto --help
-
    
-
-
    Fetch cert
    
-
-
    Stop apache so the letsencrypt client can bind to port 80:
    
-
-
    server$ systemctl stop apache2
-
    
-
-
    Fetch the certs
    
+
    Let’s Encrypt
    
 
-
    server$ ./certbot-auto certonly --standalone --email admin@$(hostname -d) -d $(hostname -d) -d api.$(hostname -d) -d $(hostname -f) -d nicknym.$(hostname -d)
-
    
-
-
    This will put the certs and keys into /etc/letsencrypt/live/DOMAIN/.
    
+
    Let’s Encrypt is a free “trusted CA”. You can obtain signed certificates from Let’s Encrypt very easily using the LEAP command line, so long as you have first set up DNS correctly.
    
 
-
    Now, go to your workstation’s provider configuration directory and copy the newly created files from the server to your local config. You will override existing files so please make a backup before proceeding, or use a version control system to track changes.
    
-
-
    workstation$ cd PATH_TO_PROVIDER_CONFIG
-
    
+
    Creating a certificate
    
 
-
    Copy the Certificate
    
+
    For example:
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/cert.pem files/cert/dev.pixelated-project.org.crt
+
    workstation$ leap cert register
+workstation$ leap cert csr demo.bitmask.net
+workstation$ leap cert renew demo.bitmask.net
+workstation$ leap deploy
 
    
 
-
    Copy the private key
    
+
    Some notes:
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/privkey.pem files/cert/DOMAIN.key
-
    
-
-
    Copy the CA chain cert
    
+
      
+
    1. You only need to run leap cert register once. Registering will save the Let’s Encrypt account key to files/ca/lets-encrypt-account.key. If you delete this file, just run leap cert register again.
      2. 
+
    2. Let’s Encrypt support requires that you have already platform 0.9 or later.
      3. 
+
    3. This requires that the DNS records are correct for the domain.
      4. 
+
    
 
-
    workstation$ scp root@SERVER:/etc/letsencrypt/live/DOMAIN/fullchain.pem files/cert/commercial_ca.crt
-
    
 
-
    Deploy the certs
    
+
    Renewing a certificate
    
 
-
    Now you only need to deploy the certs
    
+
    Let’s Encrypt validations are short lived. You will need to renew the certificate at least once every three months. There is no harm in doing it more regularly, however. You can renew your cert every day if you wanted.
    
 
-
    workstation$ leap deploy
+
    workstation$ leap cert renew demo.bitmask.net
+workstation$ leap deploy
 
    
 
-
    This will put them into the right locations which are:
    
-
-
      
-
    • /etc/x509/certs/leap_commercial.crt for the certificate
      • 
-
    • /etc/x509/./keys/leap_commercial.key for the private key
      • 
-
    • /usr/local/share/ca-certificates/leap_commercial_ca.crt for the CA chain cert.
      • 
-
    
-
-
-
    Start apache2 again
    
-
-
    server$ systemctl start apache2
-
    
+
    There is no need to create a new CSR: renewing will reuse the old private key and the old CSR. It is especially important to not create a new CSR if you have advertised public key pins using HPKP.
    
 
 
 
diff --git a/docs/en/services/couchdb.html b/docs/en/services/couchdb.html
index 3dde5a3c..d8bc8553 100644
--- a/docs/en/services/couchdb.html
+++ b/docs/en/services/couchdb.html
@@ -215,7 +215,7 @@ couchdb - LEAP Platform Documentation
 
 
      
 
    • search for the “user_id” field
      • 
-
    • in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb
      • 
+
    • in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb
      • 
 
    
 
 
diff --git a/docs/en/services/couchdb/index.html b/docs/en/services/couchdb/index.html
index 7fa6b951..3aaa4162 100644
--- a/docs/en/services/couchdb/index.html
+++ b/docs/en/services/couchdb/index.html
@@ -215,7 +215,7 @@ couchdb - LEAP Platform Documentation
 
 
      
 
    • search for the “user_id” field
      • 
-
    • in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb
      • 
+
    • in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb
      • 
 
    
 
 
diff --git a/docs/en/services/mx.html b/docs/en/services/mx.html
index 0d693204..a15ff88c 100644
--- a/docs/en/services/mx.html
+++ b/docs/en/services/mx.html
@@ -156,8 +156,8 @@ mx - LEAP Platform Documentation
 
 
      
 
    1. alias lists: by specifying an array of destination addresses, as in the case of “flock”, the single email will get copied to each address.
      2. 
-
    2. chained resolution: alias resolution will recursively continue until there are no more matching aliases. For example, “flock” is resolved to “robin”, which then gets resolved to “robin@bird.org”.
      3. 
-
    3. virtual domains: by specifying the full domain, as in the case of “chickadee@avian.org”, the alias will work for any domain you want. Of course, the MX record for that domain must point to appropriate MX servers, but otherwise you don’t need to do any additional configuration.
      4. 
+
    4. chained resolution: alias resolution will recursively continue until there are no more matching aliases. For example, “flock” is resolved to “robin”, which then gets resolved to “robin@bird.org”.
      5. 
+
    5. virtual domains: by specifying the full domain, as in the case of “chickadee@avian.org”, the alias will work for any domain you want. Of course, the MX record for that domain must point to appropriate MX servers, but otherwise you don’t need to do any additional configuration.
      6. 
 
    6. local delivery: for testing purposes, it is often useful to copy all incoming mail for a particular address and send those copies to another address. You can do this by adding “@deliver.local” as one of the destination addresses. When “@local.delivery” is found, alias resolution stops and the mail is delivered to that username.
      7. 
 
    
 
diff --git a/docs/en/services/mx/index.html b/docs/en/services/mx/index.html
index 639d9039..6922b319 100644
--- a/docs/en/services/mx/index.html
+++ b/docs/en/services/mx/index.html
@@ -156,8 +156,8 @@ mx - LEAP Platform Documentation
 
 
      
 
    1. alias lists: by specifying an array of destination addresses, as in the case of “flock”, the single email will get copied to each address.
      2. 
-
    2. chained resolution: alias resolution will recursively continue until there are no more matching aliases. For example, “flock” is resolved to “robin”, which then gets resolved to “robin@bird.org”.
      3. 
-
    3. virtual domains: by specifying the full domain, as in the case of “chickadee@avian.org”, the alias will work for any domain you want. Of course, the MX record for that domain must point to appropriate MX servers, but otherwise you don’t need to do any additional configuration.
      4. 
+
    4. chained resolution: alias resolution will recursively continue until there are no more matching aliases. For example, “flock” is resolved to “robin”, which then gets resolved to “robin@bird.org”.
      5. 
+
    5. virtual domains: by specifying the full domain, as in the case of “chickadee@avian.org”, the alias will work for any domain you want. Of course, the MX record for that domain must point to appropriate MX servers, but otherwise you don’t need to do any additional configuration.
      6. 
 
    6. local delivery: for testing purposes, it is often useful to copy all incoming mail for a particular address and send those copies to another address. You can do this by adding “@deliver.local” as one of the destination addresses. When “@local.delivery” is found, alias resolution stops and the mail is delivered to that username.
      7. 
 
    
 
-- 
cgit v1.2.3