How To: HTTPS
By default, the Reactor UI and API are served on unencrypted connections. If you prefer to use encrypted connections, this document describes how to configure Reactor to do that.
You will, of course, need a server certificate. You can either use a self-signed certificate, or a "real" certificate sourced from a known issuer (these often come at a cost, but there are issuers of no-cost certificates like letsencrypt.org).
-
If you exclusively access the Reactor UI using an IP address in the URL (i.e. within your network or over a VPN connection), a self-signed certificate will likely work best for you. There are a number of ways to generate a self-signed certificate. One way, using the ubiquitous OpenSSL package, is described below. One side-effect of using self-signed certificates is that browsers will warn that your connection is "not secure." This is not entirely true, as explained below — it will still deliver the necessary encryption of data in transit. Please read the full description in the section below.
-
If you are, for example, going to open a NAT port in your firewall to access Reactor, so it can be opened from outside your network using a well-known host name instead of an IP address (e.g.
https://reactor.myhouse.com/
), then you could use a certificate from an official issuer, but it's not required. If you go with an official issuer, make sure you get your certificate in PEM format. In most cases, self-signed certificates are adequate and much easier to manage.
Your certificate will come in two parts: the certificate and the private key. The certificate is the public portion of a two-part symmetrical encryption key pair. Data will be encrypted using this public part, and then (reputedly) can only be decrypted using the private part. It is important that you keep the private key safe and private, as its name says. Since it's typically in a separate file, make sure the file's owner and access permissions restrict access so that only the user under which Reactor runs can read the file.
To install your certificate:
-
Place your certificate and private key files in any directory accessible to Reactor at runtime. For bare-metal installs, this can be any accessible (to the runtime user) directory in the filesystem. For docker container users, you must locate the files in your Reactor
config
subdirectory. -
In your
reactor.yaml
configuration file, change thebaseurl
protocol fromhttp:
tohttps:
. -
In your
reactor.yaml
configuration file, add the following two lines after thebaseurl
line (and indented to the same level with spaces):baseurl: "https://...:8554" pki_certfile: certificate-filename pki_keyfile: private-key-filename
If simple filenames are given above, the files are assumed to be in the
config
subdirectory. Otherwise, they are assumed to be full pathnames to another filesystem location. If the certificate and private key are in the same file, you can omit thepki_keyfile
line above. -
Restart Reactor.
-
Open the Reactor UI using the new HTTPS URL (from
baseurl
in step 2 above).
baseurl
Port Overrides
Please notice that the recommended default port for Reactor HTTPS connections (8554) is different from the default port for HTTP connections (8111). However, if your environment sets the PORT environment variable (which is often done for docker containers), the port specified by the environment variable will be used, overriding that in baseurl
. Additionally, if port
is specified in reactor.yaml
, that will also override any port specified in baseurl
.
If Reactor does not start, check the reactor.log
file for messages. The most likely problem is that your certificate and private key files are not accessible (check the path and permissions), or that the certificate and private key files are not in the correct (PEM) format. You may also be on the wrong port (see caution above) — the log will tell you what port Reactor is actually using. If you still can't resolve the issue, simply restore the baseurl
by undoing the edit done in step 2 above.
If you're interested in using HTTPS for the Reactor UI, you may also be interested in configuring access control. Do not make Reactor available on any publicly-accessible address or port without enabling and configuring access control.
If the HTTPS port is other than 8111, Reactor's default port for (unencrypted) HTTP requests, Reactor will start an HTTP service of port 8111 to redirect requests to HTTPS. You can disable this feature by setting redirect_http
to false
in the reactor
section of config/reactor.yaml
.
Creating a Self-Signed Certificate using OpenSSL
You can create a self-signed certificate by issuing the following command on most Linux systems that have OpenSSL installed:
openssl req -x509 -nodes -newkey rsa:2048 -days 365 -keyout reactor.key -out reactor.crt
The certificate generated from this command will be valid for 365 days (-days
option). You can make it longer or shorter, as you wish.
Self-Signed Certificate Warnings
Your browser and other tools that may connect to Reactor and its API will likely complain about your certificate being invalid. This is because the certificate you have created is not issued by a trusted authority — you just made it up, so browsers and tools that connect can't know for sure they are talking to the right server (the trust of having been issued by known authority reduces the possibility of a "man in the middle" attack on connections). However, your self-signed certificate still contains all of the necessary keys to perform the encryption of the connection and protect the data in transit. You may need to instruct your browser or other tool to "ignore certificate warnings" (or similar) before it will proceed and complete the request. If this is too much of a problem for you or your household, get a letsencrypt certificate as described above. The only downside is that you'll have to renew the letsencrypt certificate periodically (about every 90 days), but that's easy.
Updated: 2024-Apr-29