Local configuration

Environment variables

How to set?

Docker

Environment variables can be set in the shell where you start the Crosser node, in the docker-compose.yml file or in a separate file referenced from docker-compose.yml, e.g edgenode.env.

Windows

On Windows you need to set the environment variables from PowerShell, before starting the Crosser service:

$env:some_variable = some_value

Available environment variables

Security

See Node Installation for information on when to set each setting.

General

Proxy settings: Nodes version 2.6+

Example edgenode.env with proxy settings:

# Proxy Section
>https_proxy=user:pw@192.168.102.10:1234

Proxy settings: Nodes version < 2.6

Example edgenode.env with proxy settings:

# Proxy Section
https_user=user
https_password=password
https_proxy_certificate=certificate.cer

Securing HTTP and MQTT endpoints

By default the integrated HTTP server and MQTT broker in the Node use unencrypted communication without authentication. In this article we will explain how you can configure your nodes with encryption and/or authentication.

TLS & Certificates

To enable encrypted communication (TLS) you need a certificate file that can be used by the node.

Good links for reading about certs

• https://letsencrypt.org/docs/certificates-for-localhost/
• https://github.com/Azure/azure-xplat-cli/wiki/Getting-Self-Signed-SSL-Certificates-(.pem-and-.pfx)
• http://paulstovell.com/blog/x509certificate2

Create certificates for test

In a production environment we recommend using a trusted certificate. For testing purposes you can create a self-signed certificate by following the below steps.

A great tool for creating test certificates is openssl:

# Generate a private key and self-signed certificate for edgenode.local

openssl req -x509 -out edgenode.crt -keyout edgenode.key   -newkey rsa:2048 -nodes -sha256   -subj '/CN=edgenode.local' -extensions EXT -config <( \
printf "[dn]\nCN=edgenode.local\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:edgenode.local\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

# Generate a edgenode.pfx cert

openssl pkcs12 -export -in edgenode.crt -inkey edgenode.key -out edgenode.pfx

Register the cert

On the clients attaching to the node you should add the edgenode.crt file as a root cert in your cert store and change the cert to always be trusted.

Edit hosts

Edit your hosts file so that egdenode.local targets 127.0.0.1.

Configure Cert for HTTPS/MQTT

Note: We show HTTP here, but MQTT works the same way.

When starting the server all files will be created with default values, so make sure you have done that. Under the data/ folder you will find all configuration files. The httpconfiguration.json/mqttconfiguration.json files will look something like:

{
  "HttpConfiguration": {
    "HttpEndpoints": [
      {
        "Address": "0.0.0.0",
        "Port": 9090,
        "Name": "---",
        "AuthenticationType": "None",
        "AuthenticationEncryption": "MD5",
        "AuthenticationFolder": "authentication",
        "AuthenticationFile": "httpAccess9090.config",
        "CertificateType": "None",
       "StoreCertificate": {
          "Subject": "",
          "StoreName": "My",
          "StoreLocation": "LocalMachine",
          "AllowValidOnly": true,
          "SslProtocols": "Tls12"
        },
        "FileCertificate": {
          "CertificatePath": "",
          "CertificatePassword": "",
          "SslProtocols": "Tls12"
        }
      }
    ]
  }
}

Use cert from file

Below we have changed to configuration to have:

• CertificateType = FileCertificate
• FileCertificate.CertififcatePath = edgenode.pfx
• FileCertificate.CertififcatePassword = !4U2know

The certificate must be stored in /data/certificates. If the folder does not exist, create it on your own. CertificatePassword should be whatever you used as password when creating the cert.

{
  "HttpConfiguration": {
    "HttpEndpoints": [
      {
        "Address": "0.0.0.0",
        "Port": 9090,
        "Name": "---",
        "AuthenticationType": "None",
        "AuthenticationEncryption": "MD5",
        "AuthenticationFolder": "authentication",
        "AuthenticationFile": "httpAccess9090.config",
        "CertificateType": "FileCertificate",
        "StoreCertificate": {
          "Subject": "",
          "StoreName": "My",
          "StoreLocation": "LocalMachine",
          "AllowValidOnly": true,
          "SslProtocols": "Tls12"
        },
        "FileCertificate": {
          "CertificatePath": "edgenode.pfx",
          "CertificatePassword": "!4U2know",
          "SslProtocols": "Tls12"
        }
      }
    ]
  }
}

Start the Node, then open a browser and navigate to https://edgenode.local:9090. The certificate should be valid and you are now accessing the Node over HTTPS with a file certificate.

Users

When the server is started it will create default configuration files for HTTP and MQTT if they do not exist: httpconfiguration.json and mqttconfiguration.json

Each file contains an array of endpoints to start and each endpoint can have its own security settings. The files will be located in the data folder.

Configuration Example

{
  "MqttConfiguration": {
    "MqttEndpoints": [
      {
        "Address": "0.0.0.0", // The address to bind to
        "Port": 1883, // The port to use
        "Name": "---", // A custom name for the endpoint (optional)
        "AuthenticationType": "Basic", // None or Basic are current options
        "AuthenticationEncryption": "MD5", // None or MD5 are current options
        "AuthenticationFolder": "authentication", // folder to store access config in
        "AuthenticationFile": "mqttAccess1883.config" // the name of the access file for the endpoint
      }
    ]
  }
}

By default the AuthenticationType is set to Nonebut if we change to Basic and restart the server we will see that we get new files in the folder data/authentication. We will see 2 files if we change the configuration above to use Basic authentication.

• mqttAccess1883.config - Contains all encrypted passwords. Do not edit this file.
• new_mqttAccess1883.config - Enter new users into this file in the format username:password in clear text. Separate users with new lines

When the server is started it will encrypt the password using the AuthenticationEncryption chosen in the endpoint configuration.

Example

If you enter uffe:foo into the file new_mqttAccess1883.config the server will encrypt the password into something like

uffe:$MD5$eTtZYr8vuDnBnQL/o2IM2ayZRnvhGC3lChmi8X98N2QOhzdNDII8mGhrv9bUZIPu1+pclAYohitAY9FpfY5IB+TsZiH79yCTxLpHr+z91jgacfA3YiOP8PZpcFTy1PIRLbMcOnTChzsdYYOlhMWv3LYm/iobDxq6ccX3uEL5+lo=$ITVf94re52wCB2lQqF2NeQ==

and store the information in the mqttAccess1883.config file. The content that was saved in clear text in new_mqttAccess1883.config will be removed.

Note that if you use Noneas AuthenticationEncryption the password will be stored in clear text.

Usage

When using MQTT you can use the Username/Pasword feature of the protocol. So that you can connect to the Crosser MQTT Broker with client credentials.

When using HTTP you can use this to get Basic Authentication. ​

Example for encryption and user authentication with docker-compose file

If you prefer to specify the endpoint configuration within your docker-compose file, you can use the example for MQTT below.

Keep in mind that all requirements still apply:

• Certificates for endpoint must be available in ./data/certificates

• edgenode.local 127.0.0.1 must be added to /etc/hosts (depending on the Operating System)

• file which holds the new users, in this case new_mqttAccess8883.config, must be available in ./data/authentication/

Note: You could specify multiple MQTT endpoints, therefore you have to specify the index __0__

version: '3.5'
services:
  edgenode:
    image: docker.crosser.io/crosser/edgenode:latest
    container_name: crosser-edgenode
    restart: always
    environment:
      - SecurityConfiguration__Credentials__NodeId=ENTER-YOUR-NODEID-HERE
      - SecurityConfiguration__Credentials__AccessKey=ENTER-YOUR-ACCESS-KEY-HERE
      - MqttConfiguration__MqttEndpoints__0__Address=0.0.0.0
      - MqttConfiguration__MqttEndpoints__0__Port=8883
      - MqttConfiguration__MqttEndpoints__0__AuthenticationType=Basic
      - MqttConfiguration__MqttEndpoints__0__AuthenticationEncryption=MD5
      - MqttConfiguration__MqttEndpoints__0__AuthenticationFolder=authentication
      - MqttConfiguration__MqttEndpoints__0__AuthenticationFile=mqttAccess8883.config
      - MqttConfiguration__MqttEndpoints__0__CertificateType=FileCertificate
      - MqttConfiguration__MqttEndpoints__0__clientCertificateRequired=false
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__StoreName=My
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__StoreLocation=LocalMachine
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__AllowValidOnly=true
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__SslProtocols=Tls12
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__CertificatePath=edgenode.pfx
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__CertificatePassword=ENTER-YOUR-CERTIFICATE-PASSWORD-HERE
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__SslProtocols=Tls12
    ports:
      - 9090:9090
      - 9191:9191
      - 8883:8883
    volumes:
      - "./data:/application/data"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "2"
 

Limitations

• You should only use one settings file per endpoint. Do not try to use one file for several endpoints

• Only Basic authentication is currently supported.