- C 94%
- Makefile 6%
| locale | ||
| po | ||
| makefile | ||
| pihole.png | ||
| pihole_api.c | ||
| pihole_api.h | ||
| pihole_api_v5.c | ||
| pihole_api_v5.h | ||
| pihole_api_v6.c | ||
| pihole_api_v6.h | ||
| pihole_config.c | ||
| pihole_config.h | ||
| pihole_disabled.png | ||
| pihole_enabled.png | ||
| pihole_http.c | ||
| pihole_http.h | ||
| pihole_i18n.c | ||
| pihole_i18n.h | ||
| pihole_remote.c | ||
| pihole_remote.desktop | ||
| pihole_remote.h | ||
| pihole_secret.c | ||
| pihole_secret.h | ||
| pihole_types.c | ||
| pihole_types.h | ||
| pihole_ui.c | ||
| pihole_ui.h | ||
| README.en.md | ||
| README.md | ||
Pi-hole Remote — XFCE Panel Applet
XFCE4 panel plugin to control one or more Pi-hole instances from the taskbar: show status, enable/disable blocking, and receive notifications when the status changes.
Features
- Multiple Pi-hole instances in a single applet (e.g. home, office)
- Pi-hole v5 and v6 — API version selectable per instance
- Secure password storage via libsecret (GNOME Keyring / KWallet)
- Desktop notifications on status changes
- Automatic status polling at a configurable interval
- Multilingual UI (German, English — more languages via gettext)
Requirements
Build dependencies
sudo apt install \
build-essential \
pkg-config \
libxfce4panel-2.0-dev \
libxfce4ui-2-dev \
libgtk-3-dev \
libcurl4-openssl-dev \
libjson-glib-dev \
libnotify-dev \
libsecret-1-dev \
gettext \
imagemagick
libxfce4panel-2.0-dev depends on libxfce4ui-2 internally — without libxfce4ui-2-dev the build fails with “Package libxfce4ui-2 was not found”.
Runtime dependencies
The same libraries without the -dev suffix (libxfce4panel-2.0, libgtk-3-0, libcurl4, libjson-glib-1.0-0, libnotify4, libsecret-1-0).
Icons
Two source images are required in the project directory for the panel display:
| File | Usage |
|---|---|
pihole.png |
Pi-hole enabled |
pihole_disabled.png |
Pi-hole disabled |
During installation, ImageMagick scales these to the usual Freedesktop icon sizes.
Build and install
make
sudo make install
Reload the panel:
xfce4-panel -r
Or log out and back in.
Uninstall:
sudo make uninstall
Usage
- Right-click the XFCE panel → Panel → Add New Items
- Select Pi-hole Remote
- Left-click the applet icon → Configure…
- Add your Pi-hole instance(s)
Context menu
| Item | Action |
|---|---|
| Select Pi-hole | Switch the active instance (✓ = active) |
| Enable Pi-hole | Turn on blocking for the active instance |
| Disable Pi-hole | Turn off blocking (optionally with a timer) |
| Configure… | Manage instances and settings |
The panel icon shows the status of the active instance. All configured instances are polled in the background; changes on any instance trigger a notification.
Configuration
Configuration file
~/.config/pihole_remote/config.ini (mode 0600, contains no passwords)
[General]
ActiveInstance=<uuid>
PollInterval=30
DisableTimer=3600
[Instance:<uuid>]
Name=Home
ApiUrl=http://pi.hole/api
Version=6
PreviousStatus=1
Passwords are stored separately in the system keyring (libsecret).
API URLs
| Pi-hole version | Example URL | Note |
|---|---|---|
| v6 | http://pi.hole/api |
Password = web UI password |
| v5 | http://pi.hole/admin/api.php |
Password = web UI password |
HTTPS is recommended when Pi-hole is not only reachable on the local network.
Migration
If the old file ~/.config/pihole_remote.conf still exists, it is automatically migrated to the new format on first start. The password is moved to the keyring.
Dialog settings
| Option | Description | Default |
|---|---|---|
| Poll interval | Seconds between status checks | 30 |
| Disable timer | Seconds until Pi-hole is re-enabled (0 = indefinitely) |
3600 |
Translations
Translation files are in po/. To add a new language:
cp po/en.po po/fr.po
# edit po/fr.po
make
sudo make install
The display language follows the system locale.
Project structure
pihole_remote.c Plugin entry point
pihole_api_v5.c Pi-hole v5 API
pihole_api_v6.c Pi-hole v6 API
pihole_config.c Configuration and migration
pihole_secret.c Keyring integration (libsecret)
pihole_ui.c Menu, dialogs, icons
pihole_http.c HTTP client (libcurl)
po/ Translations (gettext)
License
Public Domain / Unlicense
This project is free — anyone may do whatever they want with the code: copy, modify, distribute, embed in other projects, use commercially. There is no warranty and no liability.
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that do not recognize the public domain, the author
grants a perpetual, irrevocable, worldwide, royalty-free, non-exclusive
license to do anything with this work.