Secure Openhab deployment in 7 minutes

Openhab, unlike HomeAssistant, doesn’t offer a lot of security features or deployment prebuilt options for hardening out of the box. Through these steps you can deploy in minutes an Openhab instance in your home lab in a safe way, with automatic HTTPS and authentication for users outside the LAN.

1 Target

After few steps you will have a full working Openhab instance in your home lab, secured with a rock-stable reverse proxy, a simple way to obtain and maintain secure HTTPS connections and username-password authentication for users outside the LAN.

2 Prerequisites

• A local server, just like an old pc, a blade server or an Intel Nuc, that you can use on your local subnet H24.
  Note

  I assume that you will use an x86 or amd64 architecture on Linux-based OS, but if you have an ARM (Raspberry…) or a Windows OS you can easily adapt the following steps to reach the target.
• Port 80 and 443 must be free on the server and the local ip of the server should be static.
• Ip connection to internet (static or dynamic ip). Expose though port-forwarding the tcp ports 80 and 443 of the home lab server.
• docker and docker-compose installed on your home lab server. A good set of documentation is available directly on docker web pages.
• A dynamic DNS name (just like NoIP or dyn.com ones) or a static dns name in case you have a connection with a static ip. Remember to allow all subdomains with a wildcard “*.”. Replace “YourPersonalHomeLabSite.dyndns.org” with your own DNS name.
• Optionally - you can work through ssh, directly on the server or using a kvm, but I suggest you to use Visual Studio Code with Docker extension or Remote Development plugin, it’s insanely efficient!

3 What is a reverse proxy and why we need it?

The Nginx Proxy Manager is composed by a reverse Nginx proxy and a web gui management console, that helps you to setup the proxy. The reverse proxy is, approximately, a web server where each page or content is retrieved from other servers. When I ask something to my reverse proxy he doesn’t have the content I want, and he synchronously ask for that content to other “host”.

A reverse proxy is in the middle of http/s communications between clients and servers. The adoption of this layer allows the server to fully dedicate on his task, while the reverse proxy in the middle is providing the security of the communication channel or directly an authentication. Nginx is one of the most used reverse proxy in the world thanks to his stability and security.

The Nginx Proxy Manager is composed by a reverse Nginx proxy and a web gui management console, that helps you to setup all the redirections.

4 Let’s deploy the containers

On your home lab server choose a path and make a directory for your proxied-openhab environment. I usually create a main directory for all my containers in /opt/homelab or /homelab. Now we need 2 folders, one for the proxy and the other for the openhab instance:

• /opt/homelab/openhab
• /opt/homelab/nginxproxymanager

Create /opt/homelab/nginxproxymanager/docker-compose.yaml where we can prepare nginx proxy manager deployment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

version: '3.2'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    deploy:
      mode: global
    restart: always
    network_mode: host # with network_mode: host all ports are potentially exposed. if you want to select only few of them comment this line and uncomments "ports" chapter.
    #ports: 
    #  - target: 80
    #    published: 80 # Public HTTP Port
    #    protocol: tcp
    #    mode: host
    #  - target: 443
    #    published: 443 # Public HTTPS Port
    #    protocol: tcp
    #    mode: host
    #  - '81:81' # Admin Web Port - This port will be exposed only in the LAN
    volumes:
      - /opt/homelab/nginxproxymanager/config.json:/app/config/production.json
      - /opt/homelab/nginxproxymanager/data:/data
      - /opt/homelab/nginxproxymanager/letsencrypt:/etc/letsencrypt
    dns:
      - 8.8.8.8

  dns:
    restart: always
    image: strm/dnsmasq
    volumes:
      - /opt/homelab/nginxproxymanager/dnsmasq.conf:/etc/dnsmasq.conf
    ports:
      - "53:53/udp"
    cap_add:
      - NET_ADMIN

You are ready to turn on your Nginx, launch on a terminal of the server:

1
2

cd /opt/homelab/nginxproxymanager
sudo docker-compose up -d

In the same way, we have to configure the Openhab instance. Move to /opt/homelab/openhab and create docker-compose.yaml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

version: '2.2'

services:
  openhab:
    image: "openhab/openhab"
    restart: always
    network_mode: host # Openhab should need the map of a lot of ports
    volumes:
      - "/opt/homelab/openhab/addons:/openhab/addons"
      - "/opt/homelab/openhab/conf:/openhab/conf"
      - "/opt/homelab/openhab/userdata:/openhab/userdata"
    environment:
      OPENHAB_HTTP_PORT: "8081" # just in LAN
      OPENHAB_HTTPS_PORT: "8444" # just in LAN
      TZ: "Europe/Rome" # put your timezone here
      EXTRA_JAVA_OPTS: "-Duser.timezone=Europe/Rome" # put your timezone here

Ladies and Gentlemen, start your engines:

1
2

cd /opt/homelab/openhab
sudo docker-compose up -d

5 Setup of the Nginx Reverse Proxy

From a pc on the LAN navigate to nginx proxy manager UI page:

http://IP_OF_THE_HOMELAB_SERVER:81

As first task, we have to create 2 useful access list (“LAN” and “LAN or Password”) under tab “Access List”.

And Access List “LAN or password”. The difference with “LAN” is the flag “Pass authentication to host” and the username-password compiled list in tab Authorization.

Perfect, we can now come back to Hosts->Proxy Host->Add Proxy Host. We will setup the main hosted service: Openhab. If you have an homepage (take a look of my home lab dashboard) or other hosts you can integrate the setup in the same way.

1
2
3
4
5
6
7
8
9

# Cross-Origin Resource Sharing.
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow_Credentials' 'true' always;
add_header 'Access-Control-Allow-Headers' 'Authorization,Accept,Origin,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range' always;
add_header 'Access-Control-Allow-Methods' 'GET,POST,OPTIONS,PUT,DELETE,PATCH' always;

# openHAB 3 api authentication
add_header Set-Cookie X-OPENHAB-AUTH-HEADER=1;

Save, wait and BOOM, you can browse to https://openhab.YourPersonalHomeLabSite.dyndns.org to access your Openhab instance, from your lan and from internet (if you have already enabled the port forwarding of port 80 and 443).

6 Setup local DNS

To use access lists with sender ip we have to handle local requests directly from the lan. If you are sending a request from internet, a dns server will point you to public ip of your router. But you are inside the lan, you have to directly point the reverse proxy, otherwise your request could go to your gateway and then comes back with an “external sender ip”. You have to setup a mini internal dns server. Just create a file /opt/homelab/proxy_dashboard/dns/dnsmasq.conf:

1
2
3
4
5
6

server=1.1.1.1
server=8.8.8.8
#explicitly define host-ip mappings
address=/YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER
address=/.YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER
address=/#.YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER

Now you must use the IP_OF_THE_HOMELAB_SERVER as primary DNS of the devices (or configure it from your dhcp server - router).

7 Boom, you made it

Now it’s your time to play with Openhab instance.

8 Do you want more?

• Tired of having dozens of different ip, port, url for your services? take a look of my home lab dashboard.
• A good idea when exposing web servers to internet is to use a Web Application Firewall, to control traffic to and from the hosted service.

9 Alerts

Basically, you are exposing the reverse proxy and all the hosts to internet, and this could be risky for your privacy and cybersecurity if you don’t handle it properly.

If you navigate from internet to your public ip you will get an http error page, because of reverse proxy will not respond to public ip requests. The proxy will respond just for urls listed on “hosts” tab of the proxy manager gui. If you just want to have https on your services, you can set all the “access list” options of the hosts to LAN.

Another thing… Google Chrome and Google-devices are using internal DNS instead of system dns. This can create some troubles to your new internal dns server. If you have a firewall you can block dns requests to google dns ip, or from the advanced settings of chrome/edge you have to toggle off “use secure dns”. If the problem still persists, you have to disable the flag #use-dns-https-svcb-alpn in edge://flags/ and chrome://flags/.

11 Need help?

If something doesn’t work as it should do, calm down, you’ve just found another way that won’t work. Please, double check for the prerequisites and make sure you have a clean environment to start with the right foot. Still have problems? leave a comment and me or someone could help you.