wanstatus

Name	wanstatus JSON
Version	3.1 JSON
	download
home_page
Summary	Monitor WAN-side internet access and WAN IP address changes on a home network
upload_time	2024-01-04 22:14:17
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.

# wanstatus - Monitoring the health of the WAN connection

Monitors WAN-side internet access and WAN IP address changes on a home network. Sends email and/or text notifications for internet outages (after restored) and WAN IP changes. The tool is highly configurable for which modem and router you may be using. Configurations for dd-wrt and pfSense routers, and Motorola and Technicolor/Cox gateway modems are included.

Supported on Python3.6+ on Linux and Windows.

`wanstatus --service` enters an infinite loop, periodically checking the status of internet access and the WAN IP address. `wanstatus` interactively checks status.

- Internet access is detected by contacting an external DNS server (faster) such as the Google public DNS server at 8.8.8.8. Alternately, web addresses may be pinged to detect internet access (slower).
- If there is NO internet access then the outage time is captured and logged, and wanstatus enters a tight loop checking for recovery of internet access. Once restored, wanstatus sends email and/or text notifications that internet access was lost and now restored, and how long the outage was.
- If there IS access to the internet, then wanstatus reads and logs the modem status page (typically at 192.168.100.1).
- wanstatus then reads the pfSense or dd-wrt router status page for the WAN IP address, and if changed then sends email and/or notification messages of the change.
- Finally, wanstatus periodically checks with an external web page for the reported WAN IP address.

All parameters are set in the `wanstatus.cfg` config file. On each loop in service mode the config file is checked for changes, and reloaded as needed. This allows for on-the-fly configuration changes.

wanstatus may be started manually, or may be configured to start at system boot. An example systemd unit file is included. See systemd documentation for how to set it up.

**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/wanstatus) `src/deployment_files` directory and place them in the `~\.config\wanstatus` directory. These command line switches work correctly on Python 3.7+.

---

## Notable changes since prior release

V3.1 - Adjusted for cjnfuncs V2.1 (module partitioning).
.SMTP params must be in the [SMTP] config file section.

---

## Usage
```
$ wanstatus -h
usage: wanstatus [-h] [--config-file CONFIG_FILE] [--log-file LOG_FILE] [--print-log] [--service] [--setup-user] [--setup-site] [-V]

Check internet access and WAN IP address. Send notification/email after outage is over and
on WAN IP change.
3.1

options:
-h, --help show this help message and exit
--config-file CONFIG_FILE, -c CONFIG_FILE
Path to the config file (Default <wanstatus.cfg)> in user/site config directory.
--log-file LOG_FILE, -l LOG_FILE
Path to the log file.
--print-log, -p Print the tail end of the log file (default last 40 lines).
--service Enter 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.
```

---

## Example output
```
$$ wanstatus
WARNING: ========== wanstatus (3.1) ==========
WARNING: Config file </home/me/.config/wanstatus/wanstatus.cfg>
INFO: Internet access: Working (DNS server 72.105.29.22, command run time 11.3 ms)
INFO: Modem status: Locked (command run time 6550.7 ms)
INFO: Router reported WANIP: 27.177.61.124 (command run time 2300.2 ms)
INFO: Externally reported WANIP: 27.177.61.124 (command run time 350.1 ms)
```

---

## Setup and Usage notes
- Install wanstatus from PyPI (pip install wanstatus).
- Install the initial configuration files (`wanstatus --setup-user` places files at ~/.config/wanstatus).
- Edit/configure `wanstatus.cfg`, `creds_SMTP`, and `creds_wanstatus` as needed.
- Run manually as `./wanstatus`, or install the systemd service.
- 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.

---

## Customization notes
- Logging in interactive mode goes to the console per the `ConsoleLogFormat` param in the config file. Logging in `--service`
mode goes to `log_wanstatus.txt` in the configuration directory.
- Checking the modem status, checking the router reported WAN IP, and checking the external WAN IP address features are optional. To disable, comment out `ModemStatusPage`, `RouterStatusPage`, and/or `WANIPWebpage` parameters, respectively. If all three are disabled then only internet access checking and outage notification is still active.
- Configuration examples are provided for dd-wrt and pfSense routers, and certain Cisco, Motorola, and Technicolor/Vantiva modems.
- Checking for internet access can be done by either pinging internet servers (slower) or by doing connections to DNS servers (faster). The internet access check method is selected via the `IACheckMethod` config parameter. Multiple target addresses may be specified as a whitespace separated list of ping addresses or DNS server addresses. The first server in the list is tried, and if access should fail (after `nRetries` attempts) then the next server in the list is tried, and so on.
- For developing and debugging the regular expressions for your needs, do a View Page Source in your browser and look for the specific phrase in the html that has the desired info. I recommend https://regexr.com/ for developing your regular expressions for extracting the modem status and WAN IP address.
- The external WAN IP check servers may not tolerate too frequent requests. Set `ExternalWANRecheckPeriod` to a big value, such as 1 hour, to avoid being blacklisted.

The modem and router ('device') access configurations use a common set of parameters, with `xxx` replaced by `Modem` and `Router`, respectively. Notably:
- If logging into a device is not needed in order to access the `xxxStatusPage`, then don't specify the `xxxLoginUsernameField` parameter.
- If login for a device is required (`xxxLoginUsernameField` specified), but a specific login page is not used then don't specify `xxxLoginPage`. The username and password will be passed to the `xxxStatusPage`. This method is used by pfSense routers.
- To disable the device status check completely, don't specify (or comment out) the `xxxStatusPage` parameter (as noted above).
- csrf security access mode is supported, such as used by pfSense routers. This feature is enabled in the `xxxLoginAdditionalKeys`. logging.debug statements are commented out in the code to avoid leaking login credentials.

Modem and Router config parameters:
```
Config parameters using 'xxx' as a placeholder prefix (with examples):
xxxLoginPage http://routerurl.lan/login
If login on a specific page is required. Optional. If not given then login attempt
at the xxxStatusPage.
xxxLoginRequiredText <title>CSRF Error</title>
Unique text found on the page returned by the device that indicates that a login is needed.
xxxLoginUsernameField usernamefld
Name of the username field on the login page. Optional. If not given then username and
password parameters are not used. EG dd-wrt router doesn't need a password to access status.
xxx_USER
Login Username
xxxLoginPasswordField passwordfld
Name of the password field on the login page.
xxx_PASS
Login Password
xxxLoginAdditionalKeys login : Login, '__csrf_magic' : "None"
Any other needed keys related to login. All, including username and password, are
passed on all posts to the xxxLoginPage and xxxStatusPage.
Csrf token parsing and updating is done if 'csrf' is found in these additional keys.
xxxCsrfRE csrfMagicToken = "(.*)";var
RE for parsing the csrf token out of pages returned from xxxLoginPage and xxxStatusPage.
xxxStatusPage http://routerurl.lan/index.php
Page for extracting info from using the xxxStatusRE.
xxxStatusRE <td.+title="via.dhcp">\s+([\d]+\.[\d]+\.[\d]+\.[\d]+)
RE for extracting modem status or router WAN IP from the xxxRouterStatusPage.
xxxTimeout
Max time allowed for response from the device.
```

---

## Version history
- 3.1 240104 - Adjusted for cjnfuncs 2.1
- 3.0.1 230226 - Fixed inclusion of deployment_files
- 3.0 230215 - Converted to package format, updated to cjnfuncs 2.0
- ...
- 0.1 201028 - New

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "wanstatus",
    "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/99/66/b3a6b5b4377b064af75a805bdd3d92a40f2fea7dc8f74a8e75c322765ec8/wanstatus-3.1.tar.gz",
    "platform": null,
    "description": "# wanstatus - Monitoring the health of the WAN connection\n\nMonitors WAN-side internet access and WAN IP address changes on a home network.  Sends email and/or text notifications for internet outages (after restored) and WAN IP changes.  The tool is highly configurable for which modem and router you may be using.  Configurations for dd-wrt and pfSense routers, and Motorola and Technicolor/Cox gateway modems are included.\n\nSupported on Python3.6+ on Linux and Windows.\n\n`wanstatus --service` enters an infinite loop, periodically checking the status of internet access and the WAN IP address.  `wanstatus` interactively checks status.\n\n- Internet access is detected by contacting an external DNS server (faster) such as the Google public DNS server at 8.8.8.8.  Alternately, web addresses may be pinged to detect internet access (slower).\n- If there is NO internet access then the outage time is captured and logged, and wanstatus enters a tight loop checking for recovery of internet access.  Once restored, wanstatus sends email and/or text notifications that internet access was lost and now restored, and how long the outage was.\n- If there IS access to the internet, then wanstatus reads and logs the modem status page (typically at 192.168.100.1).\n- wanstatus then reads the pfSense or dd-wrt router status page for the WAN IP address, and if changed then sends email and/or notification messages of the change.\n- Finally, wanstatus periodically checks with an external web page for the reported WAN IP address.  \n\n\nAll parameters are set in the `wanstatus.cfg` config file.  On each loop in service mode the config file is checked for changes, and reloaded as needed.  This allows for on-the-fly configuration changes.\n\nwanstatus may be started manually, or may be configured to start at system boot.  An example systemd unit file is included.  See systemd documentation for how to set it up.\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/wanstatus) `src/deployment_files` directory and place them in the `~\\.config\\wanstatus` directory.  These command line switches work correctly on Python 3.7+.\n\n\n<br/>\n\n---\n\n## Notable changes since prior release\n\nV3.1 - Adjusted for cjnfuncs V2.1 (module partitioning).\n.SMTP params must be in the [SMTP] config file section.\n\n<br/>\n\n---\n\n## Usage\n```\n$ wanstatus -h\nusage: wanstatus [-h] [--config-file CONFIG_FILE] [--log-file LOG_FILE] [--print-log] [--service] [--setup-user] [--setup-site] [-V]\n\nCheck internet access and WAN IP address.  Send notification/email after outage is over and\non WAN IP change.\n3.1\n\noptions:\n  -h, --help            show this help message and exit\n  --config-file CONFIG_FILE, -c CONFIG_FILE\n                        Path to the config file (Default <wanstatus.cfg)> in user/site config directory.\n  --log-file LOG_FILE, -l LOG_FILE\n                        Path to the log file.\n  --print-log, -p       Print the tail end of the log file (default last 40 lines).\n  --service             Enter 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$$ wanstatus \n WARNING:  ========== wanstatus (3.1) ==========\n WARNING:  Config file </home/me/.config/wanstatus/wanstatus.cfg>\n    INFO:  Internet access:             Working          (DNS server 72.105.29.22, command run time   11.3 ms)\n    INFO:  Modem status:                Locked           (command run time 6550.7 ms)\n    INFO:  Router reported WANIP:       27.177.61.124    (command run time 2300.2 ms)\n    INFO:  Externally reported WANIP:   27.177.61.124    (command run time  350.1 ms)\n```\n\n<br/>\n\n---\n\n## Setup and Usage notes\n- Install wanstatus from PyPI (pip install wanstatus).\n- Install the initial configuration files (`wanstatus --setup-user` places files at ~/.config/wanstatus).\n- Edit/configure `wanstatus.cfg`, `creds_SMTP`, and `creds_wanstatus` as needed.\n- Run manually as `./wanstatus`, or install the systemd service.\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\n\n<br/>\n\n---\n\n## Customization notes\n- Logging in interactive mode goes to the console per the `ConsoleLogFormat` param in the config file.  Logging in `--service`\nmode goes to `log_wanstatus.txt` in the configuration directory. \n- Checking the modem status, checking the router reported WAN IP, and checking the external WAN IP address features are optional.  To disable, comment out `ModemStatusPage`, `RouterStatusPage`, and/or `WANIPWebpage` parameters, respectively.  If all three are disabled then only internet access checking and outage notification is still active.\n- Configuration examples are provided for dd-wrt and pfSense routers, and certain Cisco, Motorola, and Technicolor/Vantiva modems.\n- Checking for internet access can be done by either pinging internet servers (slower) or by doing connections to DNS servers (faster).  The internet access check method is selected via the  `IACheckMethod` config parameter.  Multiple target addresses may be specified as a whitespace separated list of ping addresses or DNS server addresses.  The first server in the list is tried, and if access should fail (after `nRetries` attempts) then the next server in the list is tried, and so on.\n- For developing and debugging the regular expressions for your needs, do a View Page Source in your browser and look for the specific phrase in the html that has the desired info.  I recommend https://regexr.com/ for developing your regular expressions for extracting the modem status and WAN IP address. \n- The external WAN IP check servers may not tolerate too frequent requests.  Set `ExternalWANRecheckPeriod` to a big value, such as 1 hour, to avoid being blacklisted.\n\nThe modem and router ('device') access configurations use a common set of parameters, with `xxx` replaced by `Modem` and `Router`, respectively.  Notably:\n- If logging into a device is not needed in order to access the `xxxStatusPage`, then don't specify the `xxxLoginUsernameField` parameter.\n- If login for a device is required (`xxxLoginUsernameField` specified), but a specific login page is not used then don't specify `xxxLoginPage`.  The username and password will be passed to the `xxxStatusPage`.  This method is used by pfSense routers.\n- To disable the device status check completely, don't specify (or comment out) the `xxxStatusPage` parameter (as noted above).\n- csrf security access mode is supported, such as used by pfSense routers.  This feature is enabled in the `xxxLoginAdditionalKeys`.  logging.debug statements are commented out in the code to avoid leaking login credentials.\n\nModem and Router config parameters:\n```\n    Config parameters using 'xxx' as a placeholder prefix (with examples):\n        xxxLoginPage               http://routerurl.lan/login\n            If login on a specific page is required.  Optional.  If not given then login attempt \n            at the xxxStatusPage.\n        xxxLoginRequiredText   <title>CSRF Error</title>\n            Unique text found on the page returned by the device that indicates that a login is needed.\n        xxxLoginUsernameField      usernamefld\n            Name of the username field on the login page.  Optional.  If not given then username and \n            password parameters are not used.  EG dd-wrt router doesn't need a password to access status.\n        xxx_USER\n            Login Username\n        xxxLoginPasswordField      passwordfld\n            Name of the password field on the login page.\n        xxx_PASS\n            Login Password\n        xxxLoginAdditionalKeys     login : Login, '__csrf_magic' : \"None\"\n            Any other needed keys related to login. All, including username and password, are\n            passed on all posts to the xxxLoginPage and xxxStatusPage.  \n            Csrf token parsing and updating is done if 'csrf' is found in these additional keys.\n        xxxCsrfRE                  csrfMagicToken = \"(.*)\";var\n            RE for parsing the csrf token out of pages returned from xxxLoginPage and xxxStatusPage.\n        xxxStatusPage              http://routerurl.lan/index.php\n            Page for extracting info from using the xxxStatusRE.\n        xxxStatusRE                <td.+title=\"via.dhcp\">\\s+([\\d]+\\.[\\d]+\\.[\\d]+\\.[\\d]+)\n            RE for extracting modem status or router WAN IP from the xxxRouterStatusPage.\n        xxxTimeout\n            Max time allowed for response from the device.\n```\n\n<br/>\n\n---\n\n## Version history\n- 3.1 240104 - Adjusted for cjnfuncs 2.1\n- 3.0.1 230226 - Fixed inclusion of deployment_files\n- 3.0 230215 - Converted to package format, updated to cjnfuncs 2.0\n- ...\n- 0.1 201028 - 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": "Monitor WAN-side internet access and WAN IP address changes on a home network",
    "version": "3.1",
    "project_urls": {
        "repository": "https://github.com/cjnaz/wanstatus"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "12b2cb5dafa34ada2bcdf081f0eee21d016695de2a4406aaf818bf26d1b46272",
                "md5": "cf49b7077e291a57de58c795e32fcfbd",
                "sha256": "1d6dd3e461cedbb6d012dea3834cb4abae84aa5e6b6b4929a29bf1284d0cacb6"
            },
            "downloads": -1,
            "filename": "wanstatus-3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cf49b7077e291a57de58c795e32fcfbd",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 16098,
            "upload_time": "2024-01-04T22:14:15",
            "upload_time_iso_8601": "2024-01-04T22:14:15.692421Z",
            "url": "https://files.pythonhosted.org/packages/12/b2/cb5dafa34ada2bcdf081f0eee21d016695de2a4406aaf818bf26d1b46272/wanstatus-3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9966b3a6b5b4377b064af75a805bdd3d92a40f2fea7dc8f74a8e75c322765ec8",
                "md5": "7527458873581f7b75074fd9bda420e3",
                "sha256": "122e2275c9817f399179a87c0da4128384abe265275d152b351099e9d8cabaa4"
            },
            "downloads": -1,
            "filename": "wanstatus-3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "7527458873581f7b75074fd9bda420e3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 17813,
            "upload_time": "2024-01-04T22:14:17",
            "upload_time_iso_8601": "2024-01-04T22:14:17.347475Z",
            "url": "https://files.pythonhosted.org/packages/99/66/b3a6b5b4377b064af75a805bdd3d92a40f2fea7dc8f74a8e75c322765ec8/wanstatus-3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-04 22:14:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cjnaz",
    "github_project": "wanstatus",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "wanstatus"
}