| Name | routermonitor JSON |
| Version |
3.1
JSON |
| download |
| home_page | |
| Summary | Watch for new DHCP clients on your LAN |
| upload_time | 2024-01-06 23:27:19 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | MIT License Copyright (c) 2023 Chris Nelson Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# routermonitor
routermonitor logs/monitors DHCP clients (devices) managed by your dhcp server - either dd-wrt or pfSense.
I use pfSense as my home dhcp server and
find that over time that I've accumulated several devices on my network that I cannot readily identify. routermonitor
watches the DHCP leases and tracks changes in a sqlite3
database. Any new client found on the network result in a text message notification.
- Clients come and go over time, as family members come and visit, and as DHCP leases expire. The history of
known clients is tracked by MAC address. Clients may be manually deleted from the database (i.e., *That laptop went in the tub with kids!* (long gone)). No changes are ever made on the dhcp server.
- Some hostnames are ambiguous, such as '*' and 'android-2ab8700dff69dbfd'. Notes may be manually added
for each tracked client.
- The Organization Unique ID for for each devices' MAC address is looked up and added to the database, often providing enough info to identify strange devices.
Note: _router_ and _dhcp server_ are used somewhat interchangeable in this documentation. This utility was originally written for dd-wrt, which runs on routers. Newer versions also support pfSense as a dhcp server.
**NOTE:** Due to as-of-yet unsolved problems with Python 3.6 and import_resources, the `--setup-user` and `--setup-site` switches are not working on Py 3.6. Manually grab the files from the [github](https://github.com/cjnaz/routermonitor) `src/deployment_files directory` and place them in the `~\.config\routermonitor` directory. These command line switches work correctly on Python 3.7+.
<br/>
---
## Notable changes since prior release
V3.1:
- NOTE: This version supports pfsense+ 23.09-RELEASE using ONLY the ISC DHCP server. This version puts up a ISC DHCP EOL warning message on the DHCP Leases page, which shifts the table parsing. Since the new KEA DHCP server does not yet play nicely with the DNS Resolver, I'm currently staying with the ISC DHCP server.
- Adjusted for cjnfuncs V2.1 (module partitioning). SMTP params must be in the [SMTP] config file section.
- Fixed service mode exit when pfsense router is not accessible.
- Added retries to lookup_MAC().
<br/>
---
## Usage
```
$ routermonitor -h
usage: routermonitor [-h] [--update] [--list-db] [--list-dhcp-server] [--sort-by {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}]
[--create-db] [--note NOTE] [--delete] [--MAC MAC] [--config-file CONFIG_FILE] [--print-log] [--service]
[--setup-user] [--setup-site] [-V]
[SearchTerm]
Monitor for new devices/clients on the network.
The network dhcp server is queried for currently known DHCP clients.
Any new clients are identified and a notification is sent.
3.1
positional arguments:
SearchTerm Print database records containing this text.
options:
-h, --help show this help message and exit
--update, -u Check the dhcp server for new connections and update the database.
--list-db, -l Print known clients on the network from the database (default mode).
--list-dhcp-server, -r
Print known clients on the network from the dhcp server.
--sort-by {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}, -s {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}
Sort --list-db and --list-dhcp-server output. Overrides config SortBy. Default <hostname> if neither specified.
--create-db Create a fresh database and populate it with the current dhcp server clients.
--note NOTE, -n NOTE Add a note to the db for the specified --MAC.
--delete Delete from the db the specified --MAC.
--MAC MAC, -m MAC MAC address for --add-note or --delete.
--config-file CONFIG_FILE, -c CONFIG_FILE
Path to the config file (Default <routermonitor.cfg)> in user/site config directory.
--print-log, -p Print the tail end of the log file (default last 40 lines).
--service Run updates in an endless loop for use as a systemd service.
--setup-user Install starter files in user space.
--setup-site Install starter files in system-wide space. Run with root prev.
-V, --version Return version number and exit.
```
<br/>
---
## Example output
```
$ routermonitor --list-db
$ ./routermonitor
WARNING: ========== routermonitor (3.1) ==========
INFO: Config file </path/to/routermonitor.cfg>
Hostname First seen Current IP IP Expiry MAC MAC Org Unique ID Notes
Denon-AVR-X1600H 2020-05-22 18:23:30 192.168.1.112 2020-05-24 10:42:07 00:05:cd:8a:ab:8d Denon, Ltd. -
Galaxy-S10-jen 2020-05-22 18:23:33 192.168.1.114 2020-05-22 18:33:29 10:98:c3:80:cd:b2 Murata Manufacturing Co., Ltd. -
amazon-b6f1c2033 2020-05-23 06:45:05 192.168.1.118 2020-05-24 12:57:19 38:f7:3d:16:ef:40 Amazon Technologies Inc. Wife's Kindle Fire
espressif 2020-05-22 18:23:35 192.168.2.121 2020-05-24 11:45:03 44:67:55:02:01:7f Orbit Irrigation -
Flex5 2020-05-22 18:23:36 192.168.1.123 2020-05-24 11:59:32 50:5b:c2:e1:23:ef Liteon Technology Corporation -
* 2020-05-22 18:23:37 192.168.1.144 2020-05-24 15:21:31 64:52:99:90:45:aa The Chamberlain Group, Inc Liftmaster gateway 828LM in office
MyQ-F8C 2020-05-22 18:23:38 192.168.1.143 2020-05-24 11:07:13 64:52:99:91:67:51 The Chamberlain Group, Inc Garage door opener
ESP_48CEBF 2020-05-22 18:23:40 192.168.2.146 2020-05-24 08:51:01 80:7d:3a:48:89:bf Espressif Inc. Basement lights smartsocket
* 2020-05-22 18:23:41 192.168.2.133 2020-05-24 15:00:59 8c:85:80:1d:ab:69 Smart Innovation LLC Eufy doorbell
RPi1 2020-05-22 18:23:42 192.168.1.31 static lease b8:27:eb:25:cd:f7 Raspberry Pi Foundation -
FireStick4k 2020-05-22 18:23:44 192.168.1.40 static lease cc:9e:a2:56:ef:c9 Amazon Technologies Inc. -
...
<23> known clients.
```
<br/>
---
## Setup and Usage notes
- Install routermonitor from PyPI (`pip install routermonitor`)
- Install the initial configuration files (`routermonitor --setup-user` places files at `~/.config/routermonitor`).
- Edit/configure `routermonitor.cfg`, `creds_SMTP`, and `creds_routermonitor` as needed.
- If using a dd-wrt router, set up SSH access from your host machine to your router: Enable SSH access on your router, generate a local key (ssh-keygen), and add the content of the `~/.ssh/id_rsa.pub` file into the dd-wrt GUI ssh access config.
- Run `routermonitor` manually to build the devices/clients database.
- Do `routermonitor --add-note` runs to annotate client info, as desired. Example: `routermonitor --MAC 80:7d:3a:48:ce:bf --add-note "Basement lights smartsocket"`.
- `routermonitor --list-db` (equivalent to just `routermonitor`) provides a list of all known clients over time. `--sort-by hostname` may be useful. The report may be sorted by MAC, hostname, IP, first_seen, expiry, notes, or MACOUI. The default `SortBy` may be set in the config file.
- `routermonitor --list-dhcp-server` provides a list of the currently known DHCP clients on the server. `--sort-by` is supported with fields MAC, hostname, IP, and expiry (MACOUI is not reported by the DHCP server).
- `routermonitor amaz` provides a list of all clients in the database that have the string 'amaz' in any field (two in the above example output) while `routermonitor .2.` lists all clients on my Guest WiFi (192.168.2.*, three in the above example output).
- `routermonitor --update` finds any new clients on the network, adds them to the database, and sends a text message notification (see routermonitor.cfg). Any changes in IP address or IP Expiry time are logged to log_routermonitor.txt at the INFO level. See `LogLevel` in routermonitor.cfg.
- Optionally set up the routermonitor systemd service. A template .service file is provided in the config directory.
- When running in service mode (continuously looping) the config file may be edited and is reloaded when changed. This allows for changing settings without having to restart the service.
- Supported on Python3.6+ on Linux and Windows.
<br/>
---
## Version history
- 3.1 240106 - Fixed service mode exit when pfsense router is not accessible. Added retries to lookup_MAC().
- Adjusted for cjnfuncs V2.1 (module partitioning).
- Fixed service mode exit when pfsense router is not accessible.
- Added retries to lookup_MAC().
- Adjusted pfsense DHCP Leases table parsing (case changes in header) in 23.09-RELEASE.
- Adjusted pfsense DHCP Leases table parsing for ISC DHCP EOL header warning.
- 3.0.5 230226 - Fixed inclusion of deployment_files
- 3.0 230215 - Converted to package format, updated to cjnfuncs 2.0
- 2.0 221023 - Revamped, moved from mysql to sqlite3
- ...
- 0.1 200426 - New
Raw data
{
"_id": null,
"home_page": "",
"name": "routermonitor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Chris Nelson <github@cjnaz.com>",
"download_url": "https://files.pythonhosted.org/packages/22/d9/fe07e9ca2ee130b963f51e689c8a628abc69e09ed7870f83e835418a0ccd/routermonitor-3.1.tar.gz",
"platform": null,
"description": "# routermonitor\n\nroutermonitor logs/monitors DHCP clients (devices) managed by your dhcp server - either dd-wrt or pfSense.\nI use pfSense as my home dhcp server and \nfind that over time that I've accumulated several devices on my network that I cannot readily identify. routermonitor\nwatches the DHCP leases and tracks changes in a sqlite3\ndatabase. Any new client found on the network result in a text message notification. \n\n- Clients come and go over time, as family members come and visit, and as DHCP leases expire. The history of \nknown clients is tracked by MAC address. Clients may be manually deleted from the database (i.e., *That laptop went in the tub with kids!* (long gone)). No changes are ever made on the dhcp server.\n- Some hostnames are ambiguous, such as '*' and 'android-2ab8700dff69dbfd'. Notes may be manually added \nfor each tracked client. \n- The Organization Unique ID for for each devices' MAC address is looked up and added to the database, often providing enough info to identify strange devices.\n\nNote: _router_ and _dhcp server_ are used somewhat interchangeable in this documentation. This utility was originally written for dd-wrt, which runs on routers. Newer versions also support pfSense as a dhcp server.\n\n**NOTE:** Due to as-of-yet unsolved problems with Python 3.6 and import_resources, the `--setup-user` and `--setup-site` switches are not working on Py 3.6. Manually grab the files from the [github](https://github.com/cjnaz/routermonitor) `src/deployment_files directory` and place them in the `~\\.config\\routermonitor` directory. These command line switches work correctly on Python 3.7+.\n\n\n<br/>\n\n---\n\n## Notable changes since prior release\nV3.1:\n - NOTE: This version supports pfsense+ 23.09-RELEASE using ONLY the ISC DHCP server. This version puts up a ISC DHCP EOL warning message on the DHCP Leases page, which shifts the table parsing. Since the new KEA DHCP server does not yet play nicely with the DNS Resolver, I'm currently staying with the ISC DHCP server.\n - Adjusted for cjnfuncs V2.1 (module partitioning). SMTP params must be in the [SMTP] config file section.\n - Fixed service mode exit when pfsense router is not accessible.\n - Added retries to lookup_MAC().\n\n<br/>\n\n---\n\n## Usage\n```\n$ routermonitor -h\nusage: routermonitor [-h] [--update] [--list-db] [--list-dhcp-server] [--sort-by {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}]\n [--create-db] [--note NOTE] [--delete] [--MAC MAC] [--config-file CONFIG_FILE] [--print-log] [--service]\n [--setup-user] [--setup-site] [-V]\n [SearchTerm]\n\nMonitor for new devices/clients on the network.\n\nThe network dhcp server is queried for currently known DHCP clients.\nAny new clients are identified and a notification is sent. \n3.1\n\npositional arguments:\n SearchTerm Print database records containing this text.\n\noptions:\n -h, --help show this help message and exit\n --update, -u Check the dhcp server for new connections and update the database.\n --list-db, -l Print known clients on the network from the database (default mode).\n --list-dhcp-server, -r\n Print known clients on the network from the dhcp server.\n --sort-by {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}, -s {hostname,IP,first_seen,expiry,MAC,MACOUI,notes}\n Sort --list-db and --list-dhcp-server output. Overrides config SortBy. Default <hostname> if neither specified.\n --create-db Create a fresh database and populate it with the current dhcp server clients.\n --note NOTE, -n NOTE Add a note to the db for the specified --MAC.\n --delete Delete from the db the specified --MAC.\n --MAC MAC, -m MAC MAC address for --add-note or --delete.\n --config-file CONFIG_FILE, -c CONFIG_FILE\n Path to the config file (Default <routermonitor.cfg)> in user/site config directory.\n --print-log, -p Print the tail end of the log file (default last 40 lines).\n --service Run updates in an endless loop for use as a systemd service.\n --setup-user Install starter files in user space.\n --setup-site Install starter files in system-wide space. Run with root prev.\n -V, --version Return version number and exit.\n```\n\n<br/>\n\n---\n\n## Example output\n```\n$ routermonitor --list-db\n$ ./routermonitor\n WARNING: ========== routermonitor (3.1) ==========\n INFO: Config file </path/to/routermonitor.cfg>\nHostname First seen Current IP IP Expiry MAC MAC Org Unique ID Notes\nDenon-AVR-X1600H 2020-05-22 18:23:30 192.168.1.112 2020-05-24 10:42:07 00:05:cd:8a:ab:8d Denon, Ltd. -\nGalaxy-S10-jen 2020-05-22 18:23:33 192.168.1.114 2020-05-22 18:33:29 10:98:c3:80:cd:b2 Murata Manufacturing Co., Ltd. -\namazon-b6f1c2033 2020-05-23 06:45:05 192.168.1.118 2020-05-24 12:57:19 38:f7:3d:16:ef:40 Amazon Technologies Inc. Wife's Kindle Fire\nespressif 2020-05-22 18:23:35 192.168.2.121 2020-05-24 11:45:03 44:67:55:02:01:7f Orbit Irrigation -\nFlex5 2020-05-22 18:23:36 192.168.1.123 2020-05-24 11:59:32 50:5b:c2:e1:23:ef Liteon Technology Corporation -\n* 2020-05-22 18:23:37 192.168.1.144 2020-05-24 15:21:31 64:52:99:90:45:aa The Chamberlain Group, Inc Liftmaster gateway 828LM in office\nMyQ-F8C 2020-05-22 18:23:38 192.168.1.143 2020-05-24 11:07:13 64:52:99:91:67:51 The Chamberlain Group, Inc Garage door opener\nESP_48CEBF 2020-05-22 18:23:40 192.168.2.146 2020-05-24 08:51:01 80:7d:3a:48:89:bf Espressif Inc. Basement lights smartsocket\n* 2020-05-22 18:23:41 192.168.2.133 2020-05-24 15:00:59 8c:85:80:1d:ab:69 Smart Innovation LLC Eufy doorbell\nRPi1 2020-05-22 18:23:42 192.168.1.31 static lease b8:27:eb:25:cd:f7 Raspberry Pi Foundation -\nFireStick4k 2020-05-22 18:23:44 192.168.1.40 static lease cc:9e:a2:56:ef:c9 Amazon Technologies Inc. -\n...\n <23> known clients.\n```\n\n<br/>\n\n---\n\n## Setup and Usage notes\n- Install routermonitor from PyPI (`pip install routermonitor`)\n- Install the initial configuration files (`routermonitor --setup-user` places files at `~/.config/routermonitor`).\n- Edit/configure `routermonitor.cfg`, `creds_SMTP`, and `creds_routermonitor` as needed.\n - If using a dd-wrt router, set up SSH access from your host machine to your router: Enable SSH access on your router, generate a local key (ssh-keygen), and add the content of the `~/.ssh/id_rsa.pub` file into the dd-wrt GUI ssh access config.\n- Run `routermonitor` manually to build the devices/clients database.\n- Do `routermonitor --add-note` runs to annotate client info, as desired. Example: `routermonitor --MAC 80:7d:3a:48:ce:bf --add-note \"Basement lights smartsocket\"`.\n- `routermonitor --list-db` (equivalent to just `routermonitor`) provides a list of all known clients over time. `--sort-by hostname` may be useful. The report may be sorted by MAC, hostname, IP, first_seen, expiry, notes, or MACOUI. The default `SortBy` may be set in the config file.\n- `routermonitor --list-dhcp-server` provides a list of the currently known DHCP clients on the server. `--sort-by` is supported with fields MAC, hostname, IP, and expiry (MACOUI is not reported by the DHCP server).\n- `routermonitor amaz` provides a list of all clients in the database that have the string 'amaz' in any field (two in the above example output) while `routermonitor .2.` lists all clients on my Guest WiFi (192.168.2.*, three in the above example output).\n- `routermonitor --update` finds any new clients on the network, adds them to the database, and sends a text message notification (see routermonitor.cfg). Any changes in IP address or IP Expiry time are logged to log_routermonitor.txt at the INFO level. See `LogLevel` in routermonitor.cfg.\n- Optionally set up the routermonitor systemd service. A template .service file is provided in the config directory.\n- When running in service mode (continuously looping) the config file may be edited and is reloaded when changed. This allows for changing settings without having to restart the service.\n- Supported on Python3.6+ on Linux and Windows.\n\n<br/>\n\n---\n\n## Version history\n- 3.1 240106 - Fixed service mode exit when pfsense router is not accessible. Added retries to lookup_MAC().\n - Adjusted for cjnfuncs V2.1 (module partitioning).\n - Fixed service mode exit when pfsense router is not accessible.\n - Added retries to lookup_MAC().\n - Adjusted pfsense DHCP Leases table parsing (case changes in header) in 23.09-RELEASE.\n - Adjusted pfsense DHCP Leases table parsing for ISC DHCP EOL header warning.\n\n\n- 3.0.5 230226 - Fixed inclusion of deployment_files\n- 3.0 230215 - Converted to package format, updated to cjnfuncs 2.0\n- 2.0 221023 - Revamped, moved from mysql to sqlite3\n- ...\n- 0.1 200426 - New\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Chris Nelson Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Watch for new DHCP clients on your LAN",
"version": "3.1",
"project_urls": {
"repository": "https://github.com/cjnaz/routermonitor"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d45d956891c411af8bf948e51c9f174374ef9e3e4ed1f506702148281b936598",
"md5": "1b4f4506036664bb6de990454f449559",
"sha256": "3c41c399bc68030cdd13a3389bda569deaa7e2e45c701a30910e4938b7350087"
},
"downloads": -1,
"filename": "routermonitor-3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b4f4506036664bb6de990454f449559",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 16672,
"upload_time": "2024-01-06T23:27:17",
"upload_time_iso_8601": "2024-01-06T23:27:17.916228Z",
"url": "https://files.pythonhosted.org/packages/d4/5d/956891c411af8bf948e51c9f174374ef9e3e4ed1f506702148281b936598/routermonitor-3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22d9fe07e9ca2ee130b963f51e689c8a628abc69e09ed7870f83e835418a0ccd",
"md5": "81357ea56261758b465ccea605620d89",
"sha256": "1bf9742ab4b90b1d4aa69910662c38ac44c090b6def5a1c7114d1f71ce0b5baa"
},
"downloads": -1,
"filename": "routermonitor-3.1.tar.gz",
"has_sig": false,
"md5_digest": "81357ea56261758b465ccea605620d89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18988,
"upload_time": "2024-01-06T23:27:19",
"upload_time_iso_8601": "2024-01-06T23:27:19.373996Z",
"url": "https://files.pythonhosted.org/packages/22/d9/fe07e9ca2ee130b963f51e689c8a628abc69e09ed7870f83e835418a0ccd/routermonitor-3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-06 23:27:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cjnaz",
"github_project": "routermonitor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "routermonitor"
}
