Quick Start CLI Guide

Enclave Documentation

Quick Start CLI Guide

Enclave is software which builds private, secure and directly connected computer networks.

Each system running Enclave gets issued a certificate. The operators of each system exchange the names on their respective certificates, and instantly get a secure, directly connected, and private network.

Setting up a connection between two or more systems requires mutual consent from all parties, and Enclave networks can only be established if all parties have exchanged their certificate names and agreed to cooperate with one another.

Installing Enclave using the CLI

  1. From the download section of the portal, select the appropriate installation script and run in your terminal. If sudo is required you will be prompted.

  2. On Linux-based systems, the Enclave binaries unpack to /opt/enclave/ and configuration and logs reside in the user’s directory ~/.config/enclave/. Once installed, the script will output the following message

    Installation finished.
    Run sudo enclave --request-certificate -t [LICENSE_KEY] to request a certificate.
        sudo enclave --start to start enclave, or sudo nohup enclave --start & to start as a background process.
        sudo enclave --a [PEER_NAME] to authorise a connection to another system running enclave.
        sudo enclave --status for status.
    

Licencing and running Enclave for the first time

  1. In order to use Enclave, the system will need to request a certificate. Navigate to the Certificate Issue Tokens screen in the portal. If you have a trial account, there will be a 30 day trial issue token automatically generated for you.

    Example Issue Token

  2. In order to use Enclave, you first need to obtain an certificate. Run Enclave with the --request-certificate argument to do this. If you have a license key, supply the key using the -t argument. This will generate profiles/Universe.profile which contains configuration information for the overlay network, an encrypted private key, and the newly issued certificate.

    In this example, the access token we’re passing is 4WPLF-4L6T9-FYCR2-9D342-K85TT. Keep the token safe, without it you cannot request certificates.

    $ enclave --request-certificate -t 4WPLF-4L6T9-FYCR2-9D342-K85TT
    

    Once the system has an certificate and a network definition profile, Enclave can be started.

  3. Enclave is presently unable to fork() or detach from the terminal to run in the background as a system daemon itself, so this process must be managed. The simplest way to do this is a combination of the nohup command and an ampersand & to background the process.

    $ sudo nohup enclave --start &
    

    Alternatively, Enclave can be run interactively using the –start argument.

    $ sudo enclave --start
    
  4. Checking the status

    When Enclave is running, the --status command provides a snapshot of peer connectivity.

    $ enclave --status
       
    Local Identity: WZG24
       
       Release Version . . : 0.2.0.6
       Profile Name. . . . : Universe
       Profile Location. . : /root/.config/enclave/profiles/Universe.profile
       Certificate . . . . : CN=WZG24 Expires=Never (Perpetual Issue)
       Adapter Index . . . : tap0 (#4)
       Binding Address . . : 0.0.0.0:36019
       Virtual Network . . : 100.64.0.0/10 (255.192.0.0)
       Virtual Address . . : 100.77.23.184
       
    Peer: discover.enclave.io
       
       Peer State. . . . . : Up
       Certificate . . . . : CN=discover.enclave.io Expires=08/06/2024 09:59:59
       Endpoint. . . . . . : Tcp/35.176.215.206:443
    

Setting up your first network

connection-establish

In order to establish a connection, both sides must agree that the connection should take place. This means Alice must authorise Bob, and Bob must authorise Alice. To do this, operators exchange their certificate names.

For example if Alice and Bob have the following certificate names;

Person Certificate Name
Alice 446D
Bob PNDR

Alice should authorise Bob’s certificate name using the -a argument, and describe in a familiar way that this name belongs to Bob using the -d argument

$ enclave -a PNDR -d "Bob"

Alice’s system will wait for Bob to makes a similar, counter assertion that he wants to connect back to Alice using his Enclave client. Until then, no connection is possible.

$ enclave -a 446D -d "Alice"

Once a mutual assertion is made by both parties, Enclave will setup the connection and establish a private, shared virtual network between the parties. Enclave can maintain multiple connections, but as with a traditional network, it is advised to keep the number of hosts in your broadcast proportional to the amount of bandwidth available at the slowest network participant.

In order to check on the status of the connection between Alice and Bob, either party may use the --status argument to produce a connection report.

$ enclave --status

Enclave traffic is subject to filtering by the local firewall. Pay particular attention to the local Windows firewall, Without explicitly permitting traffic to cross an Enclave virtual network port, peers may connect but fail to exchange network traffic.

Revoking a connection

All connections in Enclave require mutual consent from both parties. Either party may change their mind at any time and tear down the connection. This is done by removing the authorisation created in the previous section.

Bob may terminate his connection with Alice by removing the authorisation he made to her certificate name.

$ enclave -r 446D

Or, Alice may also terminate the connection with Bob by removing her authorisation for his certificate name.

$ enclave -r PNDR

Configure Enclave to run at boot

Consider if Enclave will run at boot for this system and configure an init.d script, a supervisord script or your preferred method of executing enclave --start at boot time.

The recommended way to run Enclave under Linux is to use a process control system like http://supervisord.org/. To do this, install supervisord and create a configuration file for Enclave.

$ sudo apt-get install supervisor
$ nano /etc/supervisor/conf.d/enclave.conf

Define the service for supervisord to control

[program:enclave]
command=mono /opt/enclave/enclave.exe
directory=/usr/bin/
user=ubuntu
stdout_logfile=/var/log/enclave.log
redirect_stderr=true
loglevel=debug

We suggest running Enclave either under a dedicated service account, or your own account. Avoid running as root where possible. Reload the supervisor configuration.

$ service supervisor reload

Use supervisorctl to start, and stop the Enclave service

$ supervisorctl stop enclave
$ supervisorctl start enclave