4 releases (breaking)
0.4.0 | Sep 11, 2019 |
---|---|
0.3.1 | Sep 7, 2019 |
0.2.0 | Aug 23, 2019 |
0.1.0 | Aug 22, 2019 |
#11 in #arp
39KB
829 lines
🐀 Houserat
A daemon that monitors network traffic for DHCP and ARP packets from known devices and sends a notification using Telegram when these devices connect or disconnect.
🚀 Usage
- Create a Telegram bot and save its token.
- Install using a package manager:
- Arch Linux: AUR, e.g.
yay -S houserat
- Cargo:
cargo install houserat
(note that you'll have to manually install the service and config files)
- Arch Linux: AUR, e.g.
- Edit configuration at
/etc/houserat/config.toml
with bot token, device and user information (example). - Enable and start service:
systemctl enable --now houserat
.
🤖 Bot Configuration
Once you have your bot token you'll need to get chat IDs for every user that subscribes to notifications. The easiest way to do that is:
- Have the user start a conversation with the bot or send any message to it.
- Open
https://api.telegram.org/bot<token>/getUpdates
in a browser (replacing<token>
with your bot token) and look for the chat ID, it should be inmessage.chat.id
in theresult
array. - Put the chat ID you found in the
chat_id
field for that user inconfig.toml
. - Optionally clearing the updates list by going back to the Telegram
getUpdates
API method and adding?offset=<update_id+1>
, where theupdate_id
is found in the result. This would make it easier to find other chat IDs when repeating this process.
💫 How It Works
Houserat detects devices connecting to the network when they send a DHCP request packet. It will then notify that device's subscriber and start polling this device to detect when it goes away. Since phones don't always respond to PING packets houserat uses ARP requests which all devices must respond to.
When several ARP requests go unanswered the device is considered disconnected and a notification is sent to the subscriber.
💤 Anti-Spam
Houserat has several features designed to reduce notification spam:
- Configurable cooldown during which no new notifications are sent, for example if a device reconnects soon after its initial connection only 1 notification is sent.
- Configurable quiet period during which messages are sent without sound notifications. This can be used to avoid having noisy Telegram notifications at night.
Dependencies
~25–36MB
~638K SLoC