From 22c3233245584dd4b20a8b654f421d766688f3d1 Mon Sep 17 00:00:00 2001 From: ficus Date: Sat, 15 Sep 2012 21:51:21 +0200 Subject: docs --- README | 4 +++- helpers/netif.py | 20 +++++++++++++++++++- helpers/sysstatus.py | 30 ++++++++++++++++++++++++++++++ helpers/tor.py | 4 ++++ helpers/util.py | 4 ++++ torouterui.py | 33 ++++++++++++++++++++++++--------- 6 files changed, 84 insertions(+), 11 deletions(-) diff --git a/README b/README index 7c5f604..cfa23be 100644 --- a/README +++ b/README @@ -30,6 +30,8 @@ services and daemons. It is writen in python. - procfs - iw +The bundled CSS and image files are Twitter Bootstrap. + ### Development To resolve dependancies on debian-based systems (wheezy or newer?): @@ -39,5 +41,5 @@ To resolve dependancies on debian-based systems (wheezy or newer?): You can run try running the UI on any old Linux machine, just don't submit any forms unless you want your network configuration clobbered: - $ ./torouterui.py + $ ./torouterui.py --debug diff --git a/helpers/netif.py b/helpers/netif.py index 77f710c..529444d 100644 --- a/helpers/netif.py +++ b/helpers/netif.py @@ -1,3 +1,7 @@ +""" +Helper functions for working with network interfaces and network configuration +(including WiFi). +""" import os import augeas @@ -6,7 +10,14 @@ from util import * def parse_ip(ifname): """ - Example ip link show string: + Calls the ``ip`` command and parse the output to collect current status + information about a given network interface (specified by ifname argument). + + Returns a dictionary, notably always including a 'state' string value. + + If the interface can not be found at all, raises a KeyError. + + Example ``ip link show`` string: 2: eth0: mtu 1500 qdisc pfifo_fast state DOWN mode DEFAULT qlen 1000 link/ether 00:12:34:56:78:90 brd ff:ff:ff:ff:ff:ff @@ -47,6 +58,13 @@ def parse_ip(ifname): def parse_iw(ifname): """ + Calls the ``iw`` command and parse the output to collect current status + information about a given network interface (specified by ifname argument). + + Returns a dictionary, notably always including a 'state' string value. + + If the interface can not be found at all, raises a KeyError. + Example `iw dev wlan0 link` string (sic): Connected to c0:25:06:51:22:9b (on wlan0) diff --git a/helpers/sysstatus.py b/helpers/sysstatus.py index 933f625..99c209b 100644 --- a/helpers/sysstatus.py +++ b/helpers/sysstatus.py @@ -1,3 +1,7 @@ +""" +Helper code for agregating general system status information, and for reading +in system log files. +""" import os @@ -13,6 +17,23 @@ def get_system_status(): return d def get_resources_status(): + """ + Example ``df -h /home`` output: + + Filesystem Size Used Avail Use% Mounted on + /dev/mapper/xxxxx-root 231G 184G 35G 85% / + + Example ``free -m`` output: + + total used free shared buffers cached + Mem: 3862 2292 1570 0 104 689 + -/+ buffers/cache: 1498 2364 + Swap: 7983 202 7781 + + Example ``uptime`` output: + + 21:38:55 up 7 days, 5:43, 11 users, load average: 0.60, 0.63, 0.63 + """ d = dict() disk_info = cli_read_lines('df -h /home')[1].split() d['disk_used'] = disk_info[2] @@ -55,6 +76,15 @@ def get_syslog(): return None def get_process_list(): + """ + Example ``ps aux`` output: + + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 1 0.0 0.0 10636 676 ? Ss Sep08 0:05 init [2] + root 2 0.0 0.0 0 0 ? S Sep08 0:00 [kthreadd] + root 3 0.0 0.0 0 0 ? S Sep08 0:40 [ksoftirqd/0] + root 6 0.0 0.0 0 0 ? S Sep08 0:00 [migration/0] + """ plist = list() first = True for l in cli_read_lines('ps aux --sort -%mem')[1:]: diff --git a/helpers/tor.py b/helpers/tor.py index 438cb5d..d639ce2 100644 --- a/helpers/tor.py +++ b/helpers/tor.py @@ -1,3 +1,7 @@ +""" +Helper code for interacting with Tor and modifying the Tor system +configuration. +""" def get_tor_status(): d = dict() diff --git a/helpers/util.py b/helpers/util.py index 229d975..dc3b6c0 100644 --- a/helpers/util.py +++ b/helpers/util.py @@ -1,3 +1,7 @@ +""" +Utility functions used by helper code to crudely grab the output of simple UNIX +command line programs, plus a couple misc other functions. +""" import os diff --git a/torouterui.py b/torouterui.py index 5e8f346..4ef37fb 100755 --- a/torouterui.py +++ b/torouterui.py @@ -1,4 +1,18 @@ #!/usr/bin/env python +""" +Main Flask web application code for the torouter user interface. See also +README and TODO. + +Run ``./torouterui.py --help`` for command line argument options; see bottom of +this file for that code. + +The code that actually interacts with the operating system is the /helpers +directory. + +This code under a BSD license; see LICENSE file included with this code. + + +""" from flask import Flask, render_template, send_from_directory, request import argparse @@ -7,7 +21,6 @@ import os from helpers import sysstatus from helpers import netif from helpers import tor -import config app = Flask(__name__) @@ -23,21 +36,18 @@ def status(): status['tor'] = tor.get_tor_status() return render_template('home.html', settings=None, status=status) -@app.route('/administer/', methods=['GET', 'POST']) -def administer(): - return render_template('administer.html', settings=None, status=None) - @app.route('/reboot/', methods=['GET', 'POST']) def administer(): + msg = list() if request.method == 'GET': return render_template('reboot.html', status=None) elif request.form.has_key('confirm'): - # XXX: execute reboot + # TODO: actually execute reboot + #os.system('reboot &') return render_template('reboot.html', status='rebooting') else: - # XXX: flashing introduces cookies - #flash("Didn't confirm, not rebooting", "warning") - return render_template('reboot.html', status=None) + msg.append(("error", "Didn't confirm, not rebooting",),) + return render_template('reboot.html', status=None, messages=msg) @app.route('/wan/', methods=['GET', 'POST']) def wan(): @@ -177,6 +187,7 @@ def wifi(): @app.route('/tor/', methods=['GET', 'POST']) def torpage(): + # TODO: unimplemented msg = list() return render_template('tor.html', settings=None, status=None, form=request.form, formerr=None, messages=msg) @@ -196,16 +207,20 @@ def processes(): @app.route('/favicon.ico') def favicon(): + """ Simple static redirect """ return send_from_directory(os.path.join(app.root_path, 'static'), 'favicon.ico', mimetype='image/vnd.microsoft.icon') @app.route('/robots.txt') def robots(): + """ "Just in case?" """ return send_from_directory(os.path.join(app.root_path, 'static'), 'robots.txt', mimetype='text/plain') +############################################################################## + if __name__ == '__main__': parser = argparse.ArgumentParser() parser.add_argument('--debug', action='store_true', -- cgit v1.2.3