SSL configuration in Hive

Important!

Right after the installation of the Hive Platform WebUI is available only on HTTP.

You can configure SSL by one of the following methods:

  • upload your SSL certificates to the Platform and configure HTTP/HTTPs;
  • configure HTTP or TCP Reverse proxy with SSL termination.

Upload SSL certificates to Hive

Upload SSL certificates in the PEM format to the directory /opt/hw-bw/ssl. Please note that uploaded files will not be overwritten when upgrading to the next version, so feel free to store them in this directory.

You can change default directory if it does not suit you:

  1. Open the file /opt/hw-bw/config/user.ini (root privileges required);

  2. Add the b.ssl.dir option to the [main] section and indicate new path:

    [main]
b.ssl.dir = /my/certs/dir

  3. To apply changes, run the command:

    /opt/hw-bw/bin/reconfig

Configure HTTP/HTTPs

To configure HTTP to HTTPs redirect add the following properties to the [main] section of /opt/hw-bw/config/user.ini file (root privileges required):

[main]
b.ssl.enabled = ssl_redirect
b.deck.ip.expose = 0.0.0.0
b.deck.port.expose = 80
b.deck.https.ip.expose = 0.0.0.0
b.deck.https.port.expose = 443

where,

  • b.ssl.enabled - option, which enables SSL. Possible values:

    • no_ssl - only insecure HTTP-connection is used (default value);
    • ssl_both - both insecure HTTP-connection and secure HTTPs-connection are used;
    • ssl_redirect - redirection from insecure connection HTTP-connection to secure HTTPs-connection;
    • ssl_only - only secure HTTPs-connection is used.

  • b.deck.ip.expose - IP address for insecure HTTP-connection (0.0.0.0 - public IP address, 127.0.0.1 - local IP address). Required for no_ssl, ssl_both and ssl_redirect.

  • b.deck.port.expose - Port number for insecure HTTP-connection (default value - 80). Required for no_ssl, ssl_both and ssl_redirect.
  • b.deck.https.ip.expose - IP address for secure HTTPs-connection (0.0.0.0 - public IP address, 127.0.0.1 - local IP address). Required for ssl_only, ssl_both and ssl_redirect.
  • b.deck.https.port.expose - Port number for secure HTTPs-connection. Required for ssl_only, ssl_both and ssl_redirect.

To apply changes, run the command:

/opt/hw-bw/bin/reconfig

Configure HTTP or TCP Reverse proxy with SSL termination

If necessary, you can run Hive behind your own reverse proxy. For example, configure nginx, which will proxy all requests for Hive.

To use your proxy server on the same machine, change the following parameters in /opt/hw-bw/config/user.ini:

[main]
b.ssl.enabled = no_ssl
b.deck.ip.expose = 127.0.0.0
b.deck.port.expose = 10001

To apply changes, run the command (root privileges required):

/opt/hw-bw/bin/reconfig

Example of nginx configuration as HTTP Reverse proxy

  1. Example of nginx configuration:

    server {
  server_name yourhive.example.com;
  access_log /var/log/nginx/yourhive.example.com-access.log full_log;
  error_log /var/log/nginx/yourhive.example.com-error.log;

  client_max_body_size 0;

  location / {
      proxy_pass http://localhost:10001;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Real-IP $remote_addr;
  }

  listen 443 ssl;
  ssl_certificate /path/to-your/certs/fullchain.pem;
  ssl_certificate_key /path/to-your/certs/privkey.pem;
}

server {
  if ($host = yourhive.example.com) {
      return 301 https://$host$request_uri;
  }

  listen 80;
  server_name yourhive.example.com;
  return 404;
}

    where,

  • 10001 - port number you set to b.deck.port.expose in user.ini file;
  • yourhive.example.com - hostname or IP address of your virtual machine.

  1. Example of Let's Encrypt with certbot configuration. You should set this configuration before you issue certificates using certbot.

    server {
  listen 80;
  server_name yourhive.example.com;
  access_log /var/log/nginx/yourhive.example.com-access.log full_log;
  error_log /var/log/nginx/yourhive.example.com-error.log;

  client_max_body_size 0;

  location / {
      proxy_pass http://localhost:10001;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Real-IP $remote_addr;
  }
}

    where,

  • 10001 - port number you set to b.deck.port.expose in user.ini file;
  • yourhive.example.com - hostname or IP address of your virtual machine.

Convert CA-certificate from .PFX

You may need to convert CA from .pfx if: * it is necessary to transfer issues between Hive and Apiary via secure channel; * it is impossible to use global valid certificates; * it is necessary to use local Certificate Authority to issue certificates.

  1. Create SSL key:

    openssl pkcs12 -in your_file.pfx -nocerts -nodes -out key.pem

  2. Create SSL certificate:

    openssl pkcs12 -in your_file.pfx -clcerts -nokeys -out domain.pem

    Note: remove the -out option from the commands and the key with other information will be displayed on the screen. In this case, copy everything from the lines BEGIN PRIVATE KEY / BEGIN CERTIFICATE to END PRIVATE KEY / END CERTIFICATE and save it to a file.

  3. Create a root certificate:

    openssl pkcs12 -in your_file.pfx -cacerts -nokeys -chain -out ca.pem

    Note: you will get a chain of root certificates. You will need only last one certificate in this chain. For example, you can open file for editing and delete everything except the last one.

  4. Concatenate files into one certificate:

    cat domain.pem ca.pem > cert.pem

  5. Copy SSL certificates to a virtual machine with installed Platform to a directory with SSL certificates:

    cp cert.pem /opt/hw-bw/ssl/
cp key.pem /opt/hw-bw/ssl/

  6. Copy root certificate to a Platform directory with root certificates:

    cp ca.pem /opt/certs

    Note: in this case, it is necessary to specify path to directory with root certificates in /opt/hw-bw/config/user.ini file custom.root.certs.path = /opt/certs.

  7. Restart the Platform (systemctl restart hw-bw) or do /opt/hw-bw/bin/reconfig if you have changed the /opt/hw-bw/config/user.ini file.

See also