Readme update.
This commit is contained in:
parent
380b0f3734
commit
0093827fe6
1 changed files with 184 additions and 1 deletions
185
README.md
185
README.md
|
|
@ -1,3 +1,186 @@
|
|||
# uplink -is a tool to monitor the uplink status of AVM FRITZ!Box Cable and DSL based routers.
|
||||
|
||||
Go to [https://hanez.org/uplink.html](https://hanez.org/uplink.html) to view the latest documentation...
|
||||
## About
|
||||
|
||||
uplink is a tool to monitor the uplink status of AVM FRITZ!Box Cable and DSL based routers. It uses the
|
||||
<a href="https://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/AVM_TR-064_first_steps.pdf"
|
||||
class="ext">TR-064 protocol</a> over UPnP (I think it is only used by AVM in Germany).
|
||||
|
||||
*This site is related to version 0.8 of uplink (current version: 0.8.3.2).*
|
||||
|
||||
## Features
|
||||
|
||||
For now, I can say that uplink can monitor the status of you FRITZ!Box uplinks. It can log to a file and
|
||||
writes results to a MariaDB/MySQL database. With some editing of the code you can you use SQLite too but this feature
|
||||
is not active at the moment. This will change in the future. I switched to MariaDB because I run uplink on a
|
||||
RaspberryPi and are evaluating results on my workstation. I am working on a Gtk+ frontend to generate statistics...
|
||||
|
||||
## Requirements
|
||||
|
||||
### Basic tools
|
||||
|
||||
- A Linux based operating system (I don't test any other OS's but Linux and Raspbian is fine and a good target)
|
||||
- Git (only for installing from Git repository)
|
||||
- Python3 (running for me using 3.7.3, 3.8.5, 3.9.7 and 3.10.6 on Linux)
|
||||
|
||||
### Python libraries
|
||||
|
||||
- fritzconnection >= 1.5.0
|
||||
- pymysql >= 0.10.1
|
||||
|
||||
Just install 3rd party Python libraries using "pip":
|
||||
|
||||
<pre class="clean language-plaintext">pip install $PACKAGE</pre>
|
||||
|
||||
Maybe the package is available in your OS package manager, then install it from there or set up a virtual environment!
|
||||
|
||||
## Installation
|
||||
|
||||
<pre class="clean language-plaintext">cd
|
||||
git clone https://github.com/linspector/uplink.git
|
||||
cd uplink</pre>
|
||||
|
||||
### Create Database
|
||||
|
||||
For now there is only the file uplink.sql which will create the tables in your MariaDB/MySQL database.
|
||||
|
||||
The file is under ./files/uplink.sql
|
||||
|
||||
## Configuration
|
||||
|
||||
Edit ./etc/config.json to your needs.
|
||||
|
||||
### Example
|
||||
|
||||
This example contains comments which will make the JSON file broken when copying and pasting, so it is only for
|
||||
showing the features of uplink. Use the example in ./etc/ or remove the comments when you want to run uplink without
|
||||
errors.
|
||||
|
||||
<pre class="code language-json">{
|
||||
"database_host": "127.0.0.1",
|
||||
"database_name": "uplink",
|
||||
"database_password": "PASSWORD",
|
||||
"database_port": 3306, (OPTIONAL)
|
||||
"database_type": "mariadb", (CURRENTLY NOT IN USE)
|
||||
"database_user": "uplink",
|
||||
"notification_gammu": true, (OPTIONAL)
|
||||
"notification_gammu_configuration": "~/uplink/etc/gammurc", (OPTIONAL)
|
||||
"notification_gammu_receiver": "+4900000000",
|
||||
"httpserver": true, (OPTIONAL)
|
||||
"httpserver_host": "127.0.0.1", (OPTIONAL)
|
||||
"httpserver_port": 1042, (OPTIONAL)
|
||||
"interval": 60, (OPTIONAL)
|
||||
"log_file": "~/uplink/log/uplink.log", (OPTIONAL)
|
||||
"log_level": "verbose", (OPTIONAL)
|
||||
"log_count": 5, (OPTIONAL)
|
||||
"log_size": 10485760, (OPTIONAL)
|
||||
"pid_file": "/var/run/user/1000/uplink.pid", (OPTIONAL)
|
||||
"run_mode": "cron", (NOT IN USE)
|
||||
"speedtest": true, (OPTIONAL)
|
||||
"speedtest_interval": 3600, (OPTIONAL)
|
||||
"speedtest_url": "https://unixpeople.org/uplink.test", (OPTIONAL)
|
||||
"uplinks": [
|
||||
{
|
||||
"identifier": "cable",
|
||||
"primary": true, (OPTIONAL, CURRENTLY NOT IN USE)
|
||||
"ip": "192.168.0.1",,
|
||||
"password": "PASSWORD",
|
||||
"provider": "Cable Provider" (OPTIONAL)
|
||||
},
|
||||
{
|
||||
"identifier": "dsl",
|
||||
"ip": "192.168.1.1",
|
||||
"password": "PASSWORD",
|
||||
"provider": "DSL Provider" (OPTIONAL)
|
||||
}
|
||||
]
|
||||
}</pre>
|
||||
|
||||
<p>Some optional values are set to default values in the sourcecode. You can find them at the top of
|
||||
./uplink/configuration.py in the root of the uplink source diretory.</p>
|
||||
|
||||
<p>A configuration file without comments is found at ./etc/uplink.json.example. Just execute the following command and
|
||||
edit etc/config.json.</p>
|
||||
|
||||
<pre class="clean language-plaintext">cp ./etc/config.json.example ./etc/config.json</pre>
|
||||
|
||||
## Usage
|
||||
|
||||
<pre class="clean language-bash">PYTHONPATH=$(pwd) ./bin/uplink [-c | -d | -f] ./etc/config.json</pre>
|
||||
|
||||
You need at least set -c, -d or -f as the run mode (there is no default) and a valid configuration file to make it
|
||||
possible to run uplink.
|
||||
|
||||
### Help
|
||||
|
||||
<pre class="clean language-bash">PYTHONPATH=$(pwd) ./bin/uplink --help</pre>
|
||||
|
||||
<pre class="clean language-plaintext">usage: uplink [-h] [-c] [-d] [-k] [-r] [-f] [--httpserver] [-i INTERVAL] [-l LOGFILE] [-s]
|
||||
[--version]
|
||||
CONFIGFILE
|
||||
|
||||
uplink is a tool to monitor the link status of AVM FRITZ!Box Cable and DSL based routers.
|
||||
|
||||
positional arguments:
|
||||
CONFIGFILE the configuration file to use
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
-c, --cron cron mode executes the script only once without loop (default: false)
|
||||
-d, --daemon run as native daemon (default: false)
|
||||
-k, --kill kill the daemon if it is running (default: false)
|
||||
-r, --restart restart the daemon if it is running(default: false)
|
||||
-f, --foreground run looped in foreground (default: false)
|
||||
--httpserver enable the http server for status information and statistics
|
||||
-i INTERVAL, --interval INTERVAL
|
||||
poll interval in seconds. this overrides config file settings (default:
|
||||
60)
|
||||
-l LOGFILE, --logfile LOGFILE
|
||||
logfile to use. this overrides config file settings
|
||||
-s, --stdout log to stdout
|
||||
--version show program's version number and exit
|
||||
|
||||
uplink is not some program expecting uplinks to work!
|
||||
</pre>
|
||||
|
||||
## View collected data
|
||||
|
||||
I actually use "[DBeaver](https://dbeaver.io/)" for taking a look at the data uplink is collecting.
|
||||
|
||||
There will be a Gtk+ frontend to uplink at some time but this project is at a very early stage of development,
|
||||
so I wanted to write the collector first. Even support for other SQL databases is planned in conjunction with a
|
||||
Gtk+ frontend. I use MariaDB because I can move on fast-forward.
|
||||
|
||||
## Planned features
|
||||
|
||||
- A lot... :)
|
||||
- Make all config vars as ARGS and vice versa. ARGS have higher priority. Chain: default -> config -> ARGS.
|
||||
- Bring back SQLite support.
|
||||
- Switch to ORM (peewee, sqlalchemy?) to support PostgreSQL, MariaDB/MySQL, SQLite and maybe more databases.
|
||||
- Gtk+/urwid frontend for visualizing the collected data. wxGlade?
|
||||
- A tool to generate reports for showing to your uplink provider.
|
||||
- Always keep platform independence in mind but not if uplink looses nice features on Linux.
|
||||
- Implement a speedtest feature to regularly run speedtest but independent to uptime checks with different interval.
|
||||
- A small embedded webserver to view what is going on.
|
||||
|
||||
## License
|
||||
|
||||
uplink is licensed under the terms of the MIT License.
|
||||
|
||||
<pre class="clean language-plaintext">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 (including the next
|
||||
paragraph) 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.</pre>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue