In this document, you can find instructions for deploying the home automation system on a remote server. It is important to note that the user requires sudo privileges on the remote server and the server must have SSH access enabled.
Note: the following instructions are tested on a remote server running Armbian 21.08.1 Buster with Linux kernel 5.10.60-sunxi64. Different OS (e.g. Ubuntu) or Linux kernel versions may require slightly different configurations.
- 1.1.1. Define system parameters
- 1.1.2. Create a Zero Trust Tunnel on Cloudflare
- 1.1.3. Create an S3 bucket on AWS and configure AWS IAM
- 1.1.4. Create a Telegram bot
- 1.1.5. Install Armbian on the remote server
- 1.1.6. Clone the repository locally
- 1.1.7. Create .env file
- 1.2. Backup and Restore operations
- 1.3. Configuration file
The first step is to define the parameters of the system. The user must acquire the following information before starting the configuration process:
- Static IPv4 address of the Ethernet interface
- IPv4 address of the gateway
- Subnet mask
- DNS server address
- Internal domain name used by the internal services
- Email address of the DNS administrator
- Email address of the Cloudflare account
First of all, the user must create a Zero Trust Tunnel on Cloudflare. To do this, the user must have the following prerequisites:
- Domain name registered / managed by Cloudflare DNS
- Cloudflare account with the domain name configured
- Cloudflare Zero Trust account connected to the Cloudflare account
To create a Cloudflare Tunnel, follow the steps outlined in the official documentation.
After the Cloudflare Tunnel is created, the user must retrieve the Tunnel token from the Cloudflare dashboard to later configure the home automation system.
To store the backups, the user must create an S3 bucket on AWS with the correct permissions. As this project uses the restic backup tool, the user must follow the steps outlined in the official documentation to create an S3 bucket and configure the AWS IAM user.
This step is necessary to receive notifications from the alertmanager, uptime-kuma, watchtower and restic services. To create a Telegram bot, follow the steps outlined in the official documentation. After the bot is created, the user must retrieve the bot token and the chat ID to later configure the home automation system.
A more detailed guide is available in the paper.
This first step is necessary only if the user does not have a remote server with Armbian already installed. To install and configure Armbian on the remote server, perform the following steps:
- Download the Armbian image for your board from the official website
- Flash the image to an SD card using Balena Etcher
- Insert the SD card into the remote server and power it on
- Connect to the remote server via SSH using the default credentials:
- Username: root
- Password: 1234
- Complete the first boot wizard and reboot the system when prompted
Now, the remote server is ready to be configured to run the home automation system.
First, clone the repository locally to your machine and navigate to the project directory.
git clone [email protected]:lucadibello/zerotrust-your-home.git
cd zerotrust-your-homeThen, create a .env file and fill the variables with the correct values.
cp .env.example .envNote: the value of the variable ZIGBEE2MQTT_DEVICE must be the path to the mounted Zigbee adapter. To find the path, run the following command on the remote server:
ls /dev/serial/by-id
Note: the value of the variable IF must be the name of the Ethernet interface. To find the name of the Ethernet interface, run the following command on the remote server:
sudo nmcli device status
The following script deploys the project to a remote server using scp. The script copies the 'project' directory to the remote server.
./deploy.sh <USER> <IP_ADDRESS>With this configuration, the user is able to send the project files to a remote server without the need to configure Git SSH keys. After the deployment, the user can connect to the remote server via SSH and start the configuration script.
Note: the user must have sudo privileges to be able to perform the next steps.
To configure the Armbian-based server, the user must connect to the remote server via SSH and start the configuration script manually. The configuration script performs the following operations:
ssh <USER>@<IP_ADDRESS>
unzip project.zip
sudo ./configure.shNote: do not use root user to run the configuration script as root access from SSH will be disabled during the configuration process.
This configuration script performs the following operations:
- Install system dependencies using APT
- Starts required system services
- Performs additional system services configurations
- Overrides the default NTP servers (if necessary)
- Note: It is necessary only when the internal DNS server is configured as the sole DNS server of the system (no secondary external DNS servers)
- Prepares the Docker environment to run the home automation system by creating Docker networks, volumes and configuration files
- Generates TLS certificates for the internal services
- Configure the IPTables firewall rules to adhere to the Zero Trust model
- Performs system hardening operations
- Note: to learn more, refer to the paper
- Apply network configurations to the Ethernet interface
- Create a wireless hotspot (if enabled and supported by the hardware)
After the remote server is configured, the user can start the Docker containers by running the following command:
make startUnfortunately, due to breaking changes in the Home Assistant MQTT integration (view report here) it is necessary to manually configure the MQTT integration via the Home Assistant UI (configuration file configuration.yaml is not supported anymore). To perform this operation, the user must have on hand the certificate and the private key of the MQTT client generated by the configuration script. To retrieve the certificate and the private key, run the following command:
scp -O <USER>@<IP_ADDRESS>:~/composes/home-assistant/certs/certs.zip .Inside this zip file, there are three files:
- ca.crt: CA certificate
- hass-service.crt: client certificate
- hass-service.key: client private key
To install the MQTT integration, perform the following steps:
- Enable advanced mode in the Home Assistant UI (Profile -> Advanced Mode)
- Navigate to the integrations page (Settings -> Integrations)q
- Click on the "Add Integration" button
- Search for "MQTT" and select the "MQTT" integration
- From the list of available MQTT integrations, select the "MQTT" integration (top of the list)
Now, the user must fill the form with the following values:
- Broker: mosquitto
- Port: 8883
- Username: leave empty
- Password: leave empty
- Advanced options: true
Click on the "Submit" button and fill the next page with the following values:
- Client ID: home-assistant
- Keep-alive: 60
- Use a client certificate: true
- Upload the client certificate hass-service.crt (copied before)
- Upload the client private key hass-service.key (copied before)
- Broker certificate validation: custom
- Upload the CA certificate ca.crt (copied before)
- MQTT version: 5.0
- MQTT transport: TCP
- Enable discovery: true
- Prefix: homeassistant
- Enable birth message: true
- Topic: homeassistant/status
- Payload: online
- Birth message QoS: 0
- Birth message retain: false
- Enable last will and testament: true
- Topic: homeassistant/status
- Payload: offline
- Last will QoS: 0
- Will message retain: false
- Press the "Submit" button
To simplify the backup and restore operations, a Makefile is provided. In the following sections, you can find the available commands to perform management operations.
This command allows the user to view the available system backups stored in the S3 bucket.
make view-backupsThis command allows the user to perform a manual backup of the Docker volumes. The backup is encrypted and stored in the S3 bucket.
make backupNote: a backup is performed automatically every day at 00:00, this command is useful only if the user wants to perform a manual backup before critical operations.
With the following command, the user can restore the Docker volumes from a backup. The entire operation is guided via a wizard, the user must select the snapshot to restore from the list of available snapshots.
make restoreNote: this command is useful only if the user wants to restore the Docker volumes from a backup. It automatically stops all the running Docker containers, restores the volumes and starts the containers again to apply the changes.
The configuration file is a .env file that contains all the variables used by the configuration script. The following sections describe the variables that can be set in the configuration file.
The following variables are used to configure the Ethernet interface.
| Variable | Description |
|---|---|
IP_ADDRESS |
Static IPv4 address of the Ethernet interface |
IP_GATEWAY |
IPv4 address of the gateway |
The following variables are used to configure the wireless hotspot (if supported by the hardware)
| Variable | Description |
|---|---|
ENABLE_HOTSPOT |
Enable the wireless hotspot (true/false) |
HOTSPOT_SSID |
SSID of the wireless hotspot |
HOTSPOT_PASSWORD |
Password of the wireless hotspot |
The following variables are used to configure the Zero Trust Firewall. By adhering to the Zero Trust model, the firewall blocks all incoming connections by default and allows only connections from Cloudflare's Edge network.
These options are useful if the user wants to adhere as much as possible to the Zero Trust model, but keeping the possibility to access the server from the local network.
| Variable | Description |
|---|---|
IF |
Ethernet interface name (in Armbian by default is "end0") |
LOCAL_NETWORK |
Local network CIDR (e.g. 192.168.0.0/24) |
ALLOW_LOCAL_SSH_ACCESS |
Allow SSH access from the local network (true/false) |
ALLOW_LOCAL_SERVICES_ACCESS |
Allow access to local services from the local network (true/false) |
To adhere to the zero-trust security model, both variables
ALLOW_LOCAL_SSH_ACCESSandALLOW_LOCAL_SERVICES_ACCESSshould be set to false. The option is available for testing purposes to facilitate development.
The following variables are used to configure the credentials of the Cloudflare account. These credentials are used by Traefik reverse proxy to perform DNS challenges for the Let's Encrypt certificates.
| Variable | Description |
|---|---|
CLOUDFLARE_EMAIL |
Email address of the Cloudflare account |
CLOUDFLARE_API_KEY |
API key of the Cloudflare account |
The following variables are used to configure the backup and restore operations. These variables are used by the restic backup tool to perform the backup and restore operations.
| Variable | Description |
|---|---|
RESTIC_REPOSITORY |
S3 bucket path where the backups are stored |
RESTIC_PASSWORD |
Password used to encrypt the backups |
AWS_DEFAULT_REGION |
AWS region of the S3 bucket |
AWS_ACCESS_KEY_ID |
AWS access key ID |
AWS_SECRET_ACCESS_KEY |
AWS secret access key |
The following variables are used to configure the Telegram bot. These variables are used by the alertmanager, uptime-kuma, watchtower and restic to send notifications to the Telegram bot.
| Variable | Description |
|---|---|
TELEGRAM_BOT_TOKEN |
Telegram bot token |
TELEGRAM_CHAT_ID |
Telegram chat ID |
The following variables are used to configure the Cloudflare Tunnel. These variables are used by the cloudflared tool to create a secure tunnel between the local network and the Cloudflare Edge network.
| Variable | Description |
|---|---|
TUNNEL_TOKEN |
Cloudflare Zero Trust Tunnel token |
The following variables are used to configure the DNS server. These variables are used to configure the DNS server and the internal services domain names.
| Variable | Description |
|---|---|
DNS_DOMAIN |
Internal domain name used by the internal services |
DNS_EMAIL |
Email address of the DNS administrator |
The following variables are used to configure the Zigbee2MQTT adapter. These variables are used to configure the Zigbee2MQTT adapter and the Zigbee2MQTT gateway.
| Variable | Description |
|---|---|
ZIGBEE2MQTT_DEVICE |
Path to the mounted Zigbee2mqtt adapter |
ZIGBEE2MQTT_GATEWAY_ID |
ID of the Zigbee2mqtt gateway |