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.
As a base for this guide we assume you have basic knowledge of Linux command line, openssh and yaml.
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
For the basic Installation procedure we will need:
- 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
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.
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: Starting border0.com Service... May 15 14:59:37 my-host systemd: Started border0.com Service. May 15 14:59:37 my-host border0: 2023/05/15 14:59:37 starting the connector service May 15 14:59:37 my-host border0: 2023/05/15 14:59:37 creating a socket: my-host May 15 14:59:39 my-host border0: Welcome to Border0.com May 15 14:59:39 my-host border0: my-host - ssh://my-host.examples.border0.io May 15 14:59:39 my-host border0: ======================================================= May 15 14:59:39 my-host border0: Logs May 15 14:59:39 my-host border0: ======================================================= user@my-host:~$
border0 connector install is outlined below.
We will walk through main steps and details of authentication, logging, configuration and all required components.
Our toolkit caches tokens and config files in
.border0 directory under User's HOME path (
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)
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
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
border0 policy lsand
border0 policy show -n <policy_name>
More documentation about policies
Detail information about policies can be found in https://docs.border0.com/docs/policies
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