phptelemeter

phptelemeter v1.36-beta3 - Copyright (c) 2004 - 2012 by Jan De Luyck What is it? ~~~~~~~~~~~ - phptelemeter is a script that can read the webpages for the webbased 'quota' monitor made available by ISP's. These pages can contain both the actual status, and the status since the last 'reset', which happens on a date set by the ISP. This is what makes up the used quota. What can it do? ~~~~~~~~~~~~~~~ - This script was designed from the ground up to be usable both by humans and by machines. The output code can be in human-readable format, in a no-nonsense script parsable format (CSV) or in HTML format. - It can also send a warning-email every time phptelemeter is run to notify that a certain percentage has been crossed. Which ISP's are supported? ~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------------------------- | ISP | Parser | Reset Date | Quota | History | ---------------------------------------------------------------------- | Telenet | telemeter_web | X | X | X | | | telemeter4tools | X | X | X | | Dommel | dommel_web | X | X | | | Skynet | skynet_web | X | X | | | Scarlet | scarlet_web | X | X | X | | EDPNet | edpnet_web | | X | | | UPC CZ | upccz_web | X | X | | | Mobile Vikings | mobilevikings_api | | X | | ---------------------------------------------------------------------- Requirements ~~~~~~~~~~~~ - It requires PHP >= 5.0.0 and the PHP CURL extension, compiled with SSL support! - For the encryption, you also need the mcrypt extension - For the imgbar publisher, you need the gd extension - For Telemeter4Tools it requires the soap extension - It requires allow_url_fopen to be set to 'On' in php.ini Howto ~~~~~ - First off, to actually run this script you must tell it where the php binary is. Edit phptelemeter.php and modify the first line to #!/path/to/php -q. On Debian Sid, this is /usr/bin/php4 (or php5). - To create the initial configuration file, just run the script. It will notice the absence of ~/.phptelemeterrc, and create a dummy version. Next, configure this file (usually you'll just want to change username and password to the information for your account), and rerun phptelemeter - you'll get the output you want instantly. - Alternatively, you can also run phptelemeter with --new-config, which will create a new dummy config file in your current directory. Command line options ~~~~~~~~~~~~~~~~~~~~ - There are several options (you can view them with --help): General options: -c, --check-version Checks if your phptelemeter is the latest ** -D, --debug Shows lots of debugging info ** -h, --help Shows this help message -i, --ignore-errors Ignores any errors that might occur and continue ** -n, --new-config Makes a new dummy config file in the current dir -N, --no-config Don't create a config file if none exists -t, --add-option <section> <key> <value> Adds the key=value to the [section] of the configuration ** -V, --version Shows the version and exits Encryption/decryption: -e, --encrypt <password> Encrypts the supplied password -x, --decrypt <password> Decrypts the supplied password Cache file: -C, --cache-file <name> Where to look for the cache file ** -a, --enable-cache Enables the cache file ** -o, --disable-cache Disables the cache file Output modifiers: -d, --daily Shows statistics for current period ** -f, --file-output Activates file output instead of screen output ** -g, --graph Shows the usage graphs ** -p, --publisher <name> Uses the supplied publisher ** -r, --remaining Shows your max traffic allotment for today ** -z, --resetdate Shows the quota reset date ** (Options market with '**' override the configuration file) - Notes on commandline use: * When --debug is used, --file-output is automatically disabled. Notes on the version check ~~~~~~~~~~~~~~~~~~~~~~~~~~ - For all you paranoid people: the only thing phptelemeter does is load an URL when it's started. The url is: http://www.kcore.org/software/phptelemeter/VERSION which contains nothing but the version number of the latest upstream version. - If you set check_version=false, it won't bother doing that and as such won't do anything. Configuration ~~~~~~~~~~~~~ - Please see the supplied documentation file, titled "Configuration". Running on a webserver ~~~~~~~~~~~~~~~~~~~~~~ - Should you want to run phptelemeter from a webserver, you have to create the configuration file with the --new-config parameter, and put it in the /etc directory. Don't forget to set the publisher to html. - Furthermore, you should remove the first line from the phptelemeter.php file, because otherwise you'll see it in the webpage output. Running on windows ~~~~~~~~~~~~~~~~~~ - This script has only preliminary been tested on windows. In version 1.10 I implemented specific support for the windows platform, and I guess it _should_ work. Should you run it, and it works, please let me know. If it doesn't, feel free to file any and all bugs. Running on Mac OS X ~~~~~~~~~~~~~~~~~~~ - This script has been thoroughly tested on Mac OS X 10.4.8 and higher, and works without any problems. - On Mac OS X 10.6 (Snow Leopard), you need to set the timezone in php.ini. for more info, check http://www.macosxhints.com/article.php?story=20090831101932728 Database publishers ~~~~~~~~~~~~~~~~~~~ - The database publishers will try to create the table if it doesn't exist. Where to get it ~~~~~~~~~~~~~~~ - There's only one place: http://phptelemeter.kcore.org/ Known issues ~~~~~~~~~~~~ - dommel_web parser: * it will only take the first xDSL account it finds in your "My Packages" page. - upccz_web, scarlet_web and edpnet_web parsers: * I have no accounts with these ISP's. If it breaks, please drop me a mail with a debug log so I can investigate. - password encryption: * The encryption used in phptelemeter is easily reversable, as the key is embedded in the code. Do not rely on this as your only way of protecting your login credentials! * To change the key, modify the _key value at the top of phptelemeter.inc.php. Extending phptelemeter ~~~~~~~~~~~~~~~~~~~~~~ - Extending phptelemeter is fairly easy. If you want to write a new parser, take a look at the existing parser_web_ files in the modules directory. - For publishers, look at the publisher_ files. - For ease of use, I've included two 'simulating' parsers: parser_simulator_single, which simulates a single-quota ISP, and parser_simulator_separate, which simulates a separate-quota ISP. Both are written with very little checks, so sometimes the output is a bit strange. Just re-run, and you should get more usable data ;) Bugs ~~~~ - What? Bugs? Nooo... can't be. I'm infallible. Or smthing. ;p Just file them with the Bugtracker on the Sourceforge page, at http://sourceforge.net/tracker/?group_id=149435&atid=774600 New features ~~~~~~~~~~~~ - Got a great idea? File it with feature requests at Sourceforge. http://sourceforge.net/tracker/?group_id=149435&atid=774603