Skip to content

Instantly share code, notes, and snippets.

@meineerde

meineerde/Use Let's Encrypt on Homematic | RaspberryMatic.md

Last active August 17, 2025 10:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save meineerde/6cc3c7ec01e7ebb2aa5be4eecfefeddf to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save meineerde/6cc3c7ec01e7ebb2aa5be4eecfefeddf to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Use Let's Encrypt on Homematic | RaspberryMatic.md

For the used SSL certificate to be valid, we need to use the externally visible hostname when accessing the RaspberryMatic GUI. Thus, we need to configure this external hostname as the server's hostname, even if the server is only available on our internal network.

Be careful when exposing your actual RaspberryMatic instance to the outside world without further safe-guards. Usually, it should only be accessible on the internal network.

Create a self-signed certificate

Go to Einstellungen -> Systemsteuerung -> Netzwerkeinstellungen. There, you can create a self-signed certificate. Enter the hostname, your email address, and your country. The latter two values are rather unimportant here.

We need this certificate so that the web server is configured correctly and we have a template file which we can later overwrite with our actual SSL certificate from Let's Encrypt.

Enable SSH in Homematic

Go to Einstellungen -> Systemsteuerung -> Sicherheit. There, you can enable the SSH service and set a password for the root user.

Install acme.sh

Now, connect to the SSH-server as root with your chosen password.

We need to manually install acme.sh since the root filesystem of our RaspberryMatic installation is mounted readonly (only /usr/local is writable). We want to preserve this basic setup to still allow simple updates of RaspberryMatic.

mkdir /usr/local/.acme.sh
curl https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh > /usr/local/.acme.sh/acme.sh
chmod +x /usr/local/.acme.sh/acme.sh

Now we install the cronjob to automatically renew our certificates:

crontab -c /usr/local/crontabs -e

Add the following line:

0 0 * * * /usr/local/.acme.sh/acme.sh --cron --home /usr/local/.acme.sh > /dev/null

Obtain and install our certificate

/usr/local/.acme.sh/acme.sh --issue -d MYHOSTNAME.EXAMPLE.COM --standalone --httpport 8000 --home /usr/local/.acme.sh --fullchain-file /etc/config/server.crt --key-file /etc/config/server.key --reloadcmd "cat /etc/config/server.key /etc/config/server.crt > /etc/config/server.pem && chmod 600 /etc/config/server.pem && /etc/init.d/S50lighttpd reload"

Here, we use acme.sh's standalone mode to confirm the domain ownership which uses the builtin HTTP server of acme.sh on port 8000. For that to work, we need to:

  • Add the hostname to the external DNS, e.g. as a CNAME to our router
  • Configure the router to accept HTTP requests to the hostname (on port 80) and to forward them to port 8000 of our internal RaspberryMatic box. When using pfSense or OPNsense on the router, you could e.g. use the HAProxy package for that.

We leave this configuration as an exercise to the user.

If this is not possible, we could also use the DNS mode of acme.sh to avoid the HTTP negotiation (and accompanying setup of our router). For that, it is necessary that the external domain is hosted on one of the supported providers. See https://github.com/Neilpang/acme.sh/tree/master/dnsapi#how-to-use-dns-api for details on how to use this with acme.sh.

@jens-maus
Copy link

jens-maus commented Aug 16, 2025 •
edited
Loading

I’m sorry, but I must strongly advise against following the instructions in this GIST. As the lead developer behind RaspberryMatic/CCU, I believe it’s crucial to emphasise the significant security risks involved.

The GIST suggests that it’s acceptable to directly connect a CCU/RaspberryMatic to the internet via router-based port forwarding. However, even with Let’s Encrypt-based SSL certificates and port 443 as the target port, this approach poses a severe security vulnerability.

While the CCU/RaspberryMatic WebUI has its own user authentication interface, it is known to be highly insecure. Multiple attack vectors exist that allow unauthorised access to the WebUI without even a login or password, granting complete admin privileges.

Therefore, anyone considering creating a port forwarding rule to directly access the CCU/RaspberryMatic WebUI even via a Let’s Encrypt „secured“ port forwarding rule setup in their home router should strongly reconsider. Any such port forwarding, regardless of whether it’s SSL/HTTPS „secured“ or not, represents a significant security risk. The only way to really securely get a RaspberryMatic / CCU accessible from the internet is through usage of VPN-based connections. That means: Setup a VPN connection to your home router (preferably via WireGuard) or use the RaspberryMatic provided Tailscale-VPN connectivity and then connect your roadwarrior device (laptop or smartphone) via this VPN to your home network and then connect to the WebUI via simple http or https.

Therefore I kindly request that you disregard this GIST and that the author, @meineerde, delete or remove it entirely.

@FSeidinger
Copy link

FSeidinger commented Aug 16, 2025

As I already mentioned in the ongoing homematic forum discussion regarding this topic, one can agree or disagree with your opinion. I also noted, that I can see your concerns and do not take them lightly or disregard them.

Therefore I kindly request that you disregard this GIST and that the author, @meineerde, delete or remove it entirely.

But his requirement is from my point of with way out of line. This is still a free platform for discussing options, hacks and solutions about open source software. Or did I got this wrong?

@meineerde
Copy link
Author

meineerde commented Aug 17, 2025

@jens-maus wrote:

The GIST suggests that it’s acceptable to directly connect a CCU/RaspberryMatic to the internet via router-based port forwarding.

It does not though. I suggest to forward HTTP requests to port 8000 (which is otherwise unused) in order to be able to confirm the ACME HTTP challenge. Here, we use the standalone server of acme.sh which is only active for a few seconds during the challenge. The rest of the time, nothing listens on this port which thus does not pose a security issue.

Therefore, anyone considering creating a port forwarding rule to directly access the CCU/RaspberryMatic WebUI even via a Let’s Encrypt „secured“ port forwarding rule setup in their home router should strongly reconsider. Any such port forwarding, regardless of whether it’s SSL/HTTPS „secured“ or not, represents a significant security risk.

If you read the gist again, you will notice that I do not encourage anything like that. Specifically, please refer to the warning in the second paragraph of the gist which explicitly warns users from exposing their Homematic interface to the internet without further precautions.

In any case, the Homematic software (including RaspberryMatic) supports the setup and use of HTTPS with custom certificates out-of-the-box. The steps documented here (almost 7 years ago) just describe how to automate this existing functionality with Let's Encrypt. This should not change the existing security considerations of this feature at all.

While it's still certainly a good idea NOT to expose the Homematic interface to the entire internet, even with TLS certificates, I at least try to use TLS even in my local networks as much as possible. In today's times (which quickly moves towards HTTPS-by-default), I believe using plain HTTP or even self-signed certificates here rather HTTPS with certificates signed by a trusted CA would result in an overall less secure system.

Additionally, the local network is not an entirely safe haven anymore (?) given the increasing number of "smart" components people use there. Thus, it would certainly be a good idea to improve the security of Homematic / RaspberryMatic and to fix its security issues to improve the overall security.

Therefore I kindly request that you disregard this GIST and that the author, @meineerde, delete or remove it entirely.

As explained above, there are valid use-cases for TLS and trusted certificates and I do not share your concerns here. As I believe the approach shown here to be a net-improvement for security, I will continue to use it. I'm quite okay with us agreeing to disagree here though.

In any case, thanks for your work on RaspberryMatic over all those years!

@meineerde
Copy link
Author

meineerde commented Aug 17, 2025

@FSeidinger wrote:

The crontab for root lies in the read only partition of RaspberryMatic and thus does not survive a reboot/restart. But it is merged with the crontabs in /usr/local/crontabs on RaspberryMatic.

Hmmm, if I remember correctly, crontab -e did the right thing here automatically. This may have changed though... I have updated the gist with your proposal for specifying the path. Even if it may not be strictly necessary, it shouldn't hurt either :)

If you wanna pick up the altered configuration without rebooting you can use:

/etc/init.d/S98crond restart

Homematic / RaspberryMatic uses the cron daemon from Busybox. This cron (and about all others) should automatically pick up changes to crontab files without any special intervention. In the case of Busybox it checks once per hour at least. Thus, I don't believe that the restart is necessary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment