In this tutorial, we will be showing you how to set up PiAlert on your Raspberry Pi.
PiAlert is a Network Security Scanner and notification framework that can run off of a Pi. While originally developed by Pucherot, this project is now actively maintained by jokob-sk.
Using this scanner, it can immediately notify you about any network changes, whether a new network device or a port change.
This software also features a web interface that lets you easily visualize your entire network and view information such as their open ports.
The Raspberry Pi makes a great device to install PiAlert as it is relatively cheap to run 24/7 with more than enough power to process your network.
Equipment
Below is a list of the equipment we used for setting up PiAlert on our Raspberry Pi.
Recommended
Optional
We last tested this tutorial on a Raspberry Pi 5 running the latest version of Raspberry Pi OS Bookworm.
Setting up PiAlert on the Raspberry Pi
Over the following sections, we will show you how to set up the PiAlert network scanner on your Raspberry Pi.
Since we are using Docker, this process is relatively straightforward, especially if you have Docker installed already.
Preparing your Raspberry Pi for PiAlert
1. Before installing PiAlert, we must ensure our Raspberry Pi is up-to-date.
The easiest way to do this is to utilize the following two commands within the terminal.
sudo apt update
sudo apt upgrade -y2. After updating your Raspberry Pi, you must now install Docker.
We will be using Docker to run the PiAlert Network scanner on our Pi. The guide we linked above will have Docker running on your Pi in a few short steps.
https://pimylifeup.com/raspberry-pi-docker/3. Our next step is to create a directory to store the Compose file for PiAlert. We will store PiAlert and its data in the “/opt/stacks/pialert” directory.
We can create this directory by using the command below. We use the “-p” option to ensure the full directory is created.
sudo mkdir -p /opt/stacks/pialert4. After creating the directory, we must change into it by utilizing the cd command.
cd /opt/stacks/pialertWriting the Compose File for PiAlert
5. We can finally move on to writing the Compose file for PiAlert on the Raspberry Pi. This Compose file is like a set of instructions for Docker to follow.
You can begin writing this file using the nano text editor using the command below in the terminal.
sudo nano compose.yaml6. Within this file, you will want to type in the following lines.
- “
For example, we would use “
Australia/Hobart” for our region.
version: "3"
services:
pialert:
container_name: pialert
image: "jokobsk/pi.alert:latest"
network_mode: "host"
restart: unless-stopped
volumes:
- ./data/config:/home/pi/pialert/config
- ./data/db:/home/pi/pialert/db
- ./data/logs:/home/pi/pialert/front/log
environment:
- TZ=
- PORT=20211 7. After adding the lines above, you can save and quit by pressing CTRL + X, followed by Y, and then the ENTER key.
Starting the PiAlert Container
8. Once the Compose file has been written, we can start up the PiAlert Network scanner on our Raspberry Pi.
To start this software, we must use the following command in the terminal. By using the “-d” option, we are telling Docker to detach once the container has been started.
docker compose up -dImproving the PiAlert Configuration on the Raspberry Pi
9. The default configuration for PiAlert has it listening on the “192.168.1.0/24” subnet using the “eth1” adapter.
If your setup is anything like ours, you must adjust this to listen on the “192.168.0.0/24” subnet instead and switch it to using the “eth0” adapter.
Luckily, the PiAlert network scanner can monitor multiple subnets simultaneously; we only need to modify its configuration.
sudo nano /opt/stacks/pialert/data/config/pialert.conf10. Once you open the config file, you will want to find the line that starts with “SCAN_SUBNETS“.
By default, it should look similar to what we have shown below.
SCAN_SUBNETS=['192.168.1.0/24 --interface=eth1']To add a new subnet, we need to add a comma after the current one, followed by the subnet and then the interface you want to scan.
For example, if we wanted to scan the subnet “192.168.0.0/24” and the interface “eth0“, we would change the line to look like the following.
SCAN_SUBNETS=['192.168.1.0/24 --interface=eth1','192.168.0.1/24 --interface=eth0']11. After making the above changes, you can save and quit by pressing CTRL + X, followed by Y, and then ENTER.
The PiAlert software will automatically detect any changes to this configuration and update to use the new settings.
Accessing the PiAlert Web Interface
12. To access the PiAlert web interface, you must know the IP address of your Raspberry Pi.
If you are unsure what the local IP address of your Raspberry Pi is, you can utilize the hostname command as shown below.
hostname -I13. Once you know the IP address of your Raspberry Pi, you will want to go to the following address in your favourite web browser.
Ensure you replace “
http://:20211 14. You should now be greeted by the PiAlert dashboard. You can now take your time to navigate and learn how to use this software.
You can check out the official documentation to learn more about this software.
Updating PiAlert on the Raspberry Pi
Running PiAlert as a Docker container on our Raspberry Pi makes updating straightforward.
We can update the container using a few straightforward commands in the terminal.
1. Before we can update PiAlert, we must ensure that we are in the same directory in which we wrote the Compose file earlier.
You can change to this directory by utilizing the command below.
cd /opt/stacks/pialert2. Once we are in the correct directory, you can tell Docker to pull the new version of PiAlert by using the following command.
Docker will only pull parts of the container that have changed since it last downloaded the image.
docker compose pull3. Finally, after downloading a new version of PiAlert, we must get our container to utilize it.
The easiest way is to run the command you used to start PiAlert. Docker will detect that the container is running and restart it using the new image.
docker compose up -dConclusion
You should now have the PiAlert network scanner up and running on your Raspberry Pi.
Once the software starts, it will automatically begin to scan your network for all devices.
Using the web interface, you can see the visualization of your network while being able to configure the software.
Please feel free to leave a comment below if you have any questions about running the PiAlert software.
If you found this tutorial to be helpful, we highly recommend checking out our other Raspberry Pi projects.
