Integration of External Services

Setup and security

A few actions must be taken to finish the initial setup.

 1. Make a special user

# groupadd -r 'carbonio-gateway'
# useradd -r -M -g 'carbonio-gateway' -s /sbin/nologin 'carbonio-gateway'

 2. Establish policies. The Carbonio Files database, carbonio-files-db, is the service that has to  be routed in our case, hence Carbonio Mesh must be informed of this. Create a directory to house all of the configuration first.

# mkdir -p /etc/carbonio/gateway/service-discover/

After that, paste this text into the file  /etc/carbonio/gateway/service-discover/policies.json.

{
  "key_prefix": [
    {
      "carbonio-gateway/": {
        "policy": "read"
      }
    }
  ],
  "node_prefix": [
    {
      "": {
        "policy": "read"
      }
    }
  ],
  "service": [
    {
      "carbonio-gateway": {
        "policy": "write"
      },
      "carbonio-files-db": {
        "policy": "write"
      }
    }
  ]
}

Let the consul finally pick up the new policy.

# consul acl policy create -name "carbonio-gateway-policy" -description "Policy for carbonio-gateway" -rules  @/etc/carbonio/gateway/service-discover/policies.json

3. Export a fresh bootstrap token, which enables access to consul’s APIs and the ability to run commands. Run the following command and then provide the cluster credential password to retrieve the bootstrap token.

# export CONSUL_HTTP_TOKEN=$(service-discover bootstrap-token --setup)

4. Create a new token that will be the only one required to interface with the external database and is linked to the policy.

# consul acl token create -format json -policy-name carbonio-gateway-policy -description "Token for carbonio-gateway" | jq -r '.SecretID' > /etc/carbonio/gateway/service-discover/token

# chown carbonio-gateway:carbonio-gateway -R /etc/carbonio/gateway

What the External Service Means

We describe both the external service and how the terminating gateway may access it and grant Carbonio Files nodes access to it since the terminating gateway has to be aware of the precise location of the remote service in order to function properly.

Although there is currently no CLI command for this, we can use the APIs instead. Make a file called  /etc/carbonio/gateway/service-discover/carbonio-files-db-external.json.

{
  "Address": "external-database.example.com",
  "Node": "external-files-db-node",
  "NodeMeta": {
    "external-node": "true",
    "external-probe": "true"
  },
  "Service": {
    "ID": "carbonio-gateway",
    "Port": 5432,
    "Service": "carbonio-files-db"
  }
}

the external service should then be registered by sending a curl request.

Services Scheduling

It is time to inform Carbonio Mesh of the list of services that can utilise the terminating gateway now that the terminating gateway and the service have been defined and registered.

Put the following code, which designates a carbonio-gateway as a terminating gateway for the carbonio-files-db service, in the file /etc/carbonio/gateway/service-discover/gateway-config.hcl to do this.

The file mentioned above has two items that are commented; these entries are optional and need not be supplied at all in the setup.

CAFile

an SSL certificate that is particular to the service. In most cases, unless a highly specific and complicated situation is set up, this is not essential. Consul is responsible for encrypting all communication between nodes and with external resources; since services and clients communicate with it through localhost, it is secure for them to do so. Before leaving the node, all data received from consul on localhost are instantly SSL-encrypted.

SNI

In order to avoid name mismatch, the Server Name Indication is an extra security measure on top of TLS. When a client request is received, the web server might not yet know which specific domain the client is trying to access because the HTTPS TSL/SSL handshake takes place before the client sends the actual HTTP request for the domain in the typical scenario where a single web server hosts multiple domains, each with its own SSL certificate. The client can end up receiving the incorrect certificate as a result, breaking the secure connection. This issue may be avoided by using an SNI since it enables the domain name to be sent during the SSL/TSL handshake.

Make sure to write the configuration, by issuing the following command.

# consul config write /etc/carbonio/gateway/service-discover/gateway-config.hcl

[Unit]
Description=Carbonio gateway for external services
Documentation=https://docs.zextras.com/
Requires=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/consul connect envoy \
    -token-file /etc/carbonio/gateway/service-discover/token \
    -admin-bind localhost:0 \
    -gateway=terminating \
    -register -service carbonio-gateway
Restart=on-failure
RestartSec=15
User=carbonio-gateway
KillMode=process
KillSignal=SIGKILL
LimitNOFILE=65536
TimeoutSec=120
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

ExecStart=/usr/bin/consul connect envoy \
  -token-file /etc/carbonio/gateway/service-discover/token \
  -admin-bind localhost:0 \
  -gateway=terminating \
  -register -service carbonio-gateway -- -l debug

# sudo -u postgres psql

# CREATE ROLE "carbonio-files-adm" WITH LOGIN SUPERUSER encrypted password 'ScrtPsw987^2'; CREATE DATABASE "carbonio-files-adm" owner "carbonio-files-adm";

# \q