Sockets are the public endpoint that border0 creates on behalf of users. Each socket will come with a unique DNS name. There are four types of socket supported today:

  1. http/https. Use this when your local service is a http service.
  2. SSH. Used for handling ssh connections to remote systems
  3. Database. Use when working with mysql or postgres type databases.
  4. TCP/TLS. Use this when your local service is a non-http service.
    In this case the platform will proxy a encrypted tcp session. This is used for example for ssh or https services.
    Note that in this case border0 will, in addition to a unique DNS name, also create a TCP port number just for your

border0 socket

Displays all available socket specific commands and their flags

$ border0 socket
Manage your global sockets

  border0 socket [command]

Available Commands:
  connect     Connect a socket
  create      Create a new socket
  delete      Delete a socket
  ls          List your sockets
  policy      Manage your global Policies
  show        Show socket details

  -h, --help               help for socket
  -s, --socket_id string   Socket ID

Use "border0 socket [command] --help" for more information about a command.

border0 socket create

socket create sub-command allows for adding new sockets of types listed at the top.

$ border0 socket create
Create a new socket

  border0 socket create [flags]

  -r, --description string               Socket description
  -h, --help                             help for create
  -n, --name string                      Socket name
      --password string                  Password, required when protected set to true
  -p, --protected                        Protected, default no
  -t, --type string                      Socket type: http, https, ssh, tls, database (default "http")
      --upstream_http_hostname string    Upstream http hostname
  -k, --upstream_password string         Upstream password used to connect to upstream database
      --upstream_type string             Upstream type: http, https for http sockets or mysql, postgres for database sockets
  -j, --upstream_username string         Upstream username used to connect to upstream database
  -u, --username string                  Username, required when protected set to true

-t, --type

One of four supported types of a socket listed above. Allowed values are: "http", "ssh", "database", "tls"

$ border0 socket create  --type http

-n, --name

Name of the socket we are creating. Socket names must be RFC compliant DNS names.

$ border0 socket create  --type http --name "my-http-service" 


Minimal required input

At the very least one must supply:

  • type of socket(-t, --type)
  • name (-n, --name)
    eg: border0 socket create --type http --name "my-http-service"

-r, --description

Each socket can be given a description providing additional content on top of the name. The parameter takes alphanumeric string wrapped in quotes

$ border0 socket create  --type http --name "my-http-service" \
 --description "This is a socket my amazing HTTP server I am really proud of" 

-p, --protected

Protected sockets are extended HTTP sockets with support for basic authentication towards the server.
Say we want to expose our website but do not want to share the secret/pass with others. Protected sockets allows for border0 identity based access control hiding the origin server authentication.

$ border0 socket create  --type http --name "http-server-by-john" \
    --protected \
    --username john \
    --password MySecurePassword

Protected sockets require upstream(origin) username for basic HTTP authentication


Protected sockets require upstream(origin) password for basic HTTP authentication


HTTP sockets can be configured with custom hostname. In case the origin server implements vitrual hosts or requires specific "Host: " header set in the request.

$ border0 socket create  --type http --name "my-http-service" \
    --upstream_http_hostname ""


Where required, socket configuration allows to specify information about the origin. Just like the Host header example above we can specify upstream origin server type.

Types are : http, https for http sockets and mysql, postgres for database sockets

$ border0 socket create  --type http --name "my-http-service" \
    --upstream_type http


Database sockets

--upstream_username, --upstream_password

Where Databse sockets are concerned we must always supply upstream credential information for upstream database authentication.

$ border0 socket create  --type database --name "my-db-service" \
    --description "Super secret database only for the few" \
    --upstream_type mysql \
    --upstream_username my_bd_username \
    --upstream_password my_secure_db_password

border0 socket ls

Once we've created some sockets we can list them in easy to read table form.


Socket FQDNs

After creation your socket DNS are compiled from socket_name + org_name + dorder0_TLD

$ocket-server@xps15:~$ border0 socket ls
β”‚ SOCKET ID                            β”‚ DNS NAME                                      β”‚ PORT(S) β”‚ TYPE     β”‚ DESCRIPTION                                                  β”‚
β”‚ 6fb21ee7-e5db-4ff9-b54c-f9aebcbf6fd6 β”‚ β”‚ 80, 443 β”‚ http     β”‚ This is a socket my amazing HTTP server I am really proud of β”‚
β”‚ 0cc18cf2-c22f-412b-ba83-2a4cb468b210 β”‚   β”‚ 20844   β”‚ database β”‚ Super secret database only for the few                       β”‚

border0 socket show

Show command prints out information for given socket_id with -s, --socket_id flag

$ border0 socket show --socket_id 0cc18cf2-c22f-412b-ba83-2a4cb468b210
β”‚ SOCKET ID                            β”‚ DNS NAME                                    β”‚ PORT(S) β”‚ TYPE     β”‚ DESCRIPTION                            β”‚
β”‚ 0cc18cf2-c22f-412b-ba83-2a4cb468b210 β”‚ β”‚ 20844   β”‚ database β”‚ Super secret database only for the few β”‚

border0 socket connect

Once we have our socket created it is time to connect it and expose our resources to desired audience.

$ border0 socket connect
Connect a socket

  border0 socket connect [flags]

  -h, --help                    help for connect
      --host string             Target host: Control where inbound traffic goes. Default localhost (default "")
      --httpserver              Start a local http server to accept http connections on this host
      --httpserver_dir string   Directory to serve http connections on this host
  -i, --identity_file string    Identity File
  -p, --port int                Port number
      --proxy string            Proxy host used for connection to
  -s, --socket_id string        Socket ID
  -l, --sshserver               Start a local SSH server to accept SSH sessions on this host


Connecting your fist test socket

border0 socket connect my-http-socket --httpserver


Probably the fastest way to get full end to end connectivity through a socket is to use a built in HTTP server

$ border0 socket connect  my-http-socket --httpserver

Connecting to Server:

Welcome to
my-http-service -

======================================================= - - [07/Oct/2022:17:57:46 +0000] "GET / HTTP/1.1" 200 643 "-" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/ Safari/537.36" response_time="0.044 secs" - - [07/Oct/2022:17:57:47 +0000] "GET /favicon.ico HTTP/1.1" 200 643 "" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/ Safari/537.36" response_time="0.089 secs"


HOWTOs for connecting sockets

For more information on how to expose resource via sockets visit our HOWTO

border0 socket delete

Deletes a socket

$ border0 socket delete my-http-socket
Socket deleted

border0 socket policy

List all policies attached to the socket given the ID with -s, --socket_id flag

$ border0 socket policy --socket_id 0cc18cf2-c22f-412b-ba83-2a4cb468b210
Socket deleted