The Connector intends to be a flexible point of interconnection and management for your sockets. Through simple yaml definitions you will be able to automatically create and run multiple sockets of different types or configurations.

Assumptions

As a base for this guide we assume you have basic knowledge of Linux command line, openssh and yaml.

Requirements

Linux based system with internet connectivity accessible via SSH(root access/sudo). This can be a container, VM or physical box. We will use Ubuntu VM for the purpose of this doc

Installation

For the basic Installation procedure we will need:

Install required Software

Connector code, config and requirements files
Border0 account credentials
Border0 connector binary from https://download.border0.com Alternatively we publish docker image alongside our binary toolkit release, you can pull it from GitHub registry

wget https://download.border0.com/linux_amd64/border0
sudo mv border0 /usr/local/bin/
chmod +x /usr/local/bin/border0

docker pull ghcr.io/borderzero/border0

Border0 System Service

Once we have our border0 binary we can use built in connector service install feature.

user@my-host:~$ border0 connector 
Border0 Connector commands section, we can manage our connector functionality here

Usage:
  border0 connector [command]

Available Commands:
  install        install the connector service on the machine
  start          start ad-hoc connector
  status         display the connector service status
  stop           stop ad-hoc connector process
  uninstall      uninstall the connector service from the machine

Flags:
  -h, --help   help for connector

🚧
Service installation required escalated privileges
The install feature streamlines the process described below in single command.

user@my-host:~$ sudo border0 connector install
Please navigate to the URL below in order to complete the login process:
https://portal.border0.com/login?device_identifier=Ijc1OWQyNmZhLTE0MWQtNDc0NC04ZDViLTI2Zjc1YjllOWVkNiI.ZGKrNg.qwCGbntIHDxf0s1HgdJoqI9Qjis
Login successful

 Install border0.com Service:					[  OK  ]
Starting border0.com Service:					[  OK  ]
Waiting for socket to be created...

🚀 Service started successfully.
You can now connect to this machine using the following url: 
https://client.border0.com/#/ssh/my-host.examples.border0.io
user@my-host:~$

📘
Automatic SSH socket
Installation process creates SSH socket and enabled built in SSH server, this allows for remote acces with no external inbound connectivity.

📘
Service status
Once installed we can inspect Border0 service

user@my-host:~$ systemctl status border0.service 
● border0.service - border0.com Service
     Loaded: loaded (/etc/systemd/system/border0.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2023-05-15 14:59:37 PDT; 1min 27s ago
    Process: 295464 ExecStartPre=/bin/rm -f /var/run/border0.pid (code=exited, status=0/SUCCESS)
   Main PID: 295465 (border0)
      Tasks: 18 (limit: 38041)
     Memory: 16.6M
        CPU: 455ms
     CGroup: /system.slice/border0.service
             └─295465 /usr/local/bin/border0 connector start --config /etc/border0/border0.yaml

May 15 14:59:37 my-host systemd[1]: Starting border0.com Service...
May 15 14:59:37 my-host systemd[1]: Started border0.com Service.
May 15 14:59:37 my-host border0[295465]: 2023/05/15 14:59:37 starting the connector service
May 15 14:59:37 my-host border0[295465]: 2023/05/15 14:59:37 creating a socket: my-host
May 15 14:59:39 my-host border0[295465]: Welcome to Border0.com
May 15 14:59:39 my-host border0[295465]: my-host - ssh://my-host.examples.border0.io
May 15 14:59:39 my-host border0[295465]: =======================================================
May 15 14:59:39 my-host border0[295465]: Logs
May 15 14:59:39 my-host border0[295465]: =======================================================
user@my-host:~$

Manual install (optional)

Alternative to border0 connector install is outlined below.

We will walk through main steps and details of authentication, logging, configuration and all required components.

Authentication and cache directory

Our toolkit caches tokens and config files in .border0 directory under User's HOME path ($HOME/.border0)

The binary creates the directory by default during first run but if we use docker image only we can use volumes for persistent storage and handle the $HOME/.border0 across your containers:

First of all, in the home path of the user we create our cache directory mkdir .border0 (you can use any other name and path, but using $HOME/.border0 keeps it compatible with border0 binary and makes it way easier to start with)

Login

We can then login to our Organization using the binary toolkit or our docker image.

border0 login

Please navigate to the URL below in order to complete the login process:
https://portal.border0.com/login?device_identifier=IjZiYmJjMTkwLTBkNDktNGNmYi05NzMyLWZhY2FjMDM5NDVjYiI.ZxIdzE.61HPzXmOuH7ezyLQlG3RuFAMQS0

docker run -ti --rm -v ~/.border0:/root/.border0:rw \
 ghcr.io/borderzero/border0 login

Please navigate to the URL below in order to complete the login process:
https://portal.border0.com/login?device_identifier=IjZiYmJjMTkwLTBkNDktNGNmYi05NzMyLWZhY2FjMDM5NDVjYiI.ZxIdzE.61HPzXmOuH7ezyLQlG3RuFAMQS0

Prepare basic configuration via yaml file:

Using your favourite text editor, open border0.yaml file
Following is the minimal basic configuration for the connector to run:

ubuntu@connector01:~$ cat border0.yaml 
connector:
   name: "my-awesome-connector"

credentials:
   user: [email protected]
   password: AVeryLongAndSecurePassword
   # token: AVeryLongAndSecurePasswordThingyTokenLikeStuffGeneratedInThePortal

We can now test the config:

ubuntu@connector01:~$  border0 connector start
2022/08/03 17:51:29 starting the connector service

docker run -ti --rm --network=host \
--mount type=bind,source=./border0.yaml,target=/border0.yaml,readonly \
-v ~/.border0:/root/.border0:ro \
 ghcr.io/borderzero/border0 connector start
 2022/08/03 17:55:27 starting the connector service

📘
Default config file
By default the connector module will look for border0.yaml file current path

Optionally you can specify the configuration file:
border0 connector start --config some_other_border0_connector_config.yaml

At this point we should have a working connector service.

🚧
All sockets require authentication by default
We believe in secure access; that's why an access policy protects all sockets. By default, your organization will have a default organization-wide policy that will apply to all your services (sockets) in your organization. By default, it will only have the email address of the person that created the organization as an allowed email address.
To see what policy is applied to your service:
border0 socket -s <socket_id> policy ls
Also see:
border0 policy ls and border0 policy show -n <policy_name>

📘
More documentation about policies
Detail information about policies can be found in https://docs.border0.com/docs/policies

Plugins

The core functionality of the connector can be easily expanded with the use of plugins. Plugins can be enabled or disabled simply by adding or removing relevant YAML configuration sections.