Using the Border0 Connector
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
andborder0 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.
Updated 3 months ago