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
    service.

border0 socket

Displays all available socket specific commands and their flags

$ border0 socket
Manage your global sockets

Usage:
  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

Flags:
  -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

Usage:
  border0 socket create [flags]

Flags:
  -e, --allowed_email_addresses string   Comma separated list of allowed Email addresses when using cloudauth
  -d, --allowed_email_domains string     Comma separated list of allowed Email domain (i.e. 'example.com', when using cloudauth
  -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" 

-e, --allowed_email_addresses

A string of comma separated correctly formatted email addresses of people we are granting access to the socket

$ border0 socket create  --type http --name "my-http-service" \
 --description "This is a socket my amazing HTTP server I am really proud of" \
 --allowed_email_addresses [email protected],[email protected]order0.io,[email protected]

-d, --allowed_email_domains

Similarly to the email parameter, domain flag is also a string of comma separated correctly formatted domains we are granting access to the socket

$ border0 socket create  --type http --name "my-http-service" \
 --description "This is a socket my amazing HTTP server I am really proud of" \
 --allowed_email_addresses [email protected],[email protected],[email protected] \
 --allowed_email_domains border0.com,border0.io,somedomain.com

-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
--username

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

--password

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

--upstream_http_hostname

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 "my-http-service.awesome-domain.com"

--upstream_type

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" \
    --allowed_email_addresses [email protected] \
    --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

[email protected]:~$ border0 socket ls
┌──────────────────────────────────────┬───────────────────────────────────────────────┬─────────┬──────────┬──────────────────────────────────────────────────────────────┐
│ SOCKET ID                            │ DNS NAME                                      │ PORT(S) │ TYPE     │ DESCRIPTION                                                  │
├──────────────────────────────────────┼───────────────────────────────────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ 6fb21ee7-e5db-4ff9-b54c-f9aebcbf6fd6 │ my-http-service-the-greg-rnd.border0.io │ 80, 443 │ http     │ This is a socket my amazing HTTP server I am really proud of │
│ 0cc18cf2-c22f-412b-ba83-2a4cb468b210 │ my-db-service-the-greg-rnd.border0.io   │ 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 │ my-db-service-the-greg-rnd.border0.io │ 20844   │ database │ Super secret database only for the few │
└──────────────────────────────────────┴─────────────────────────────────────────────┴─────────┴──────────┴────────────────────────────────────────┘

Cloud Authentication, login details:
┌─────────────────────────┬───────────────────────┐
│ ALLOWED EMAIL ADDRESSES │ ALLOWED EMAIL DOMAINS │
├─────────────────────────┼───────────────────────┤
│ [email protected]       │                       │
└─────────────────────────┴───────────────────────┘

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

Usage:
  border0 socket connect [flags]

Flags:
  -h, --help                    help for connect
      --host string             Target host: Control where inbound traffic goes. Default localhost (default "127.0.0.1")
      --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 border0.com
  -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 --socket_id 6fb21ee7-e5db-4ff9-b54c-f9aebcbf6fd6 --httpserver

-s, --socket_id

In order to initiate socket connection we must supply ID of the socket to use

--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  --socket_id 6fb21ee7-e5db-4ff9-b54c-f9aebcbf6fd6 --httpserver

Connecting to Server: tunnel.border0.com

Welcome to Border0.io
my-http-service - https://my-http-service-the-greg-rnd.border0.io

=======================================================
Logs
=======================================================
216.xxx.xxx.152 - - [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/106.0.0.0 Safari/537.36" response_time="0.044 secs"
216.xxx.xxx.152 - - [07/Oct/2022:17:57:47 +0000] "GET /favicon.ico HTTP/1.1" 200 643 "https://my-http-service-the-greg-rnd.border0.io/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 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 given the ID with -s, --socket_id flag

$ border0 socket delete --socket_id 0cc18cf2-c22f-412b-ba83-2a4cb468b210
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