Contest Information for Ubiquiti Judges
=======================================
This page is here to serve as the 'view' part of the official contest submission rules.

Note: I haven't completed the full user documentation for PyCI yet but I think the docs are turning out well (so far).  The API docs are complete but I will be going back through all the docstrings to make the formatting better (and maybe clarify some texts).

Before You Begin Judging
------------------------
There are a few special features of PyCI I want to point out before you proceed to rip it apart =)

- PyCI now includes a Quake-style terminal application that can be accessed from any page.  Just hit the ESC key!  It doesn't do full-screen or constantly-running apps like "vi" and "ping" yet but it will soon.  I have them working in test code (with full 'screen'-like detach/reattach capability) but those features are currently WAY too buggy to include in the final submission.
- PyCI now listens on all addresses by default using HTTPS (see the note about pyOpenSSL below).  Works great!
- The following keyboard shortcuts work in both the universal terminal and the Quagga vty shells:  up/down arrows, control-u (cut), control-shift-y (paste), control-c (clear line), control-l (clear terminal).
- Just about every form has both client-side validation and server-side validation.  If you submit a form with, say, a bad IP address (e.g. "192.168.1.2b") it should notifiy you right there after you type it in as well as when you submit the form (denying the submission).
- OpenWRT (UCI) Firewall rules can be automatically converted into actual iptables commands on most of the Firewall pages.  I wrote a module (openwrt.py) that can convert them back and forth at-will.  It can also parse any iptables command and turn it into a Python object that can be easily manipulated or converted back into an iptables command.  I haven't had time to take advantage of this advanced functionality as much as I hoped but it is there.
- The l2sh daemon runs on boot when you initially start up the firmware image.  I named it 'l2sh' instead of 'l2telnet' because it technically isn't 'telnet' which, according to various standards, works only over TCP.  It does it's job (getting you in when you bork your TCP/IP config =).  For reference, l2sh will be its own separate project and I plan to turn it into 'l2ssh'.

General Notes
-------------
There are some things you should know...

- The included RouterStation firmware has everything working but just make sure you give it plenty of time after the flash for it to create the jffs2 filesystem and get PyCI and l2sh started up (the first time Python runs it has to compile a lot of .pyc files).  I'd say it takes 2 full minutes after the flash is complete before it is ready to go.
- To save time I copied & pasted a LOT of code.  The result of this is that the built code base of PyCI is about 2x larger than it will (eventually) be.  The PyCI ipk is 764k but after some work, combining (extremely) similar functions should cut that in half.  It shouldn't matter that much on a RouterStation though since there's plenty of free space even with PyCI, the dependencies, and all the contest required software.
- Also to save time I didn't spend a lot of time on CPU/memory optimizations.  PyCI runs pretty snappy on a RouterStation as it is but I know I can make it MUCH faster with a MUCH smaller memory footprint.  I've already done the preliminary work on porting PyCI to circuits.web (the hard metaprogramming parts are done) and this should result in a 2-4x cut in the amount of memory usage and make it a bit snappier at the same time.
- I didn't have enough time to fill out all the help texts.  There's complete help for the most things but some sections still need a lot of copying and pasting (Quagga, specifically).  Trivial work but non-trivial time consumption.
- Regarding the Network->Interfaces page:  I know it loads slowly and I know why it loads slowly...  The interface status box needs to be moved to a separate AJAX call that loads after everything else (requires a few hours of refactoring).  It worked__slowly, yes__but it worked so I put it aside as something to fix later.
- On the Speed Test page there's a link to download the command line version of the speed test client.  Obviously, this requires that Python be installed.  The GUI version of the speed test client is in the source directory.  It can be compiled ('frozen', really) for Windows but I don't have a Windows machine readily available to do that.
- Regarding the speed test client GUI:  When the project is public I'll put links to download the various versions (Linux, Windows, Mac OS X) from a public mirror on the Speed Test page (the statically-compiled versions are too big to include in the built version of PyCI).
- The French translation is incomplete and was created using Google Translate anyway.  Don't put it in front of a native French speaker and say, "Isn't this great?" hehe.  The important part is that the functionality is there.

Firmware Build Notes
--------------------
To build my OpenWRT firmware you need to perform the following:

- **Link the pyOpenSSL opkg:** Required if you want to run PyCI in SSL mode.  Note:  This is not the same as the 'python-openssl' package.  I've included a 'pyOpenSSL-0.9-opkg' directory in the source dir but to use it you'll have to make a link from the openwrt trunk/package directory to that directory.  It will auto-download the source just like any other OpenWRT package.
- **Link l2sh:**  In the source dir there's an l2sh directory.  In that directory is l2sh itself and an opkg directory containing a Makefile and a hard-link to l2sh.py.  Just like pyOpenSSL you'll need to put a symbolic link in the OpenWRT trunk/package directory to that 'opkg' dir.
- **Link PyCI:**  Just like the others, in the PyCI source directory there's an opkg directory.  Just put a link to it in the OpenWRT trunk/package directory.
- **Make sure Python is version 2.6+:**  The OpenWRT svn version that Ubiquiti uses in it's distributed source tree has Python 2.5.  Make sure you update to a newer release to get Python 2.6 (you might be able to get away with just doing a "./scripts/feeds update").  In my firmware I used revision 17124 which seemed pretty stable in my testing.
- **Copy my .config:**  My trunk/.config is in the source directory named, "pyci_firmware.config".

PyCI Build Notes
----------------
To build an embedded/compressed version of PyCI using the build.sh script you have to change some variables at the top to point to the correct filepaths on your system.  There's a big TODO in there that says, "Port this to Python and use a Makefile" =).  It requires the following be installed somewhere:

- yuicompressor.jar (and Java to run it) - http://developer.yahoo.com/yui/compressor/
- pybabel (for internationalization) - http://www.scripps.edu/~sanner/python/pybabel/index.html

Note:  The build.sh script will automatically build the ipk using your openwrt source directory.  It also updates the Packages.gz file with the latest md5sums and whatnot.

PyCI Screenshot Overview
========================
Here's the meat and potatoes.  Note that all these screenshots were taken from PyCI running on an actual RouterStation.

I left out the "boring" stuff...  Things like the raw text edit interfaces are all the same (for the most part).

PyCI Basics
-----------
PyCI login screen at 800x600 resolution:
________________________________________
    |screenshot1|

.. |screenshot1| image:: pyci_800x600_login.png

PyCI home page at 800x600 resolution:
_____________________________________
    |screenshot2|

.. |screenshot2| image:: pyci_800x600_home.png

**Note:** The rest of the screenshots are in 1024x768.

Escape From The Web
-------------------
PyCI Escape From The Web Terminal:
__________________________________
    |screenshot11|

.. |screenshot11| image:: pyci_1024x768_eftw1.png

PyCI Escape From The Web Terminal (after running some commands):
________________________________________________________________
    |screenshot12|

.. |screenshot12| image:: pyci_1024x768_eftw2.png

PyCI Settings
-------------
PyCI Language Configuration:
____________________________
    |screenshot13|

.. |screenshot13| image:: pyci_1024x768_language.png

PyCI Manage Plugins Interface (with context menu):
__________________________________________________
    |screenshot14|

.. |screenshot14| image:: pyci_1024x768_manage_plugins.png

PyCI Plugin Permissions Interface (with context menu):
______________________________________________________
    |screenshot15|

.. |screenshot15| image:: pyci_1024x768_plugin_permissions.png

PyCI Web Server Configuration (showing inline editing):
______________________________________________________-
    |screenshot16|

.. |screenshot16| image:: pyci_1024x768_web_server_settings.png

System Plugin
-------------
PyCI Backup/Restore Interface:
______________________________
    |screenshot17|

.. |screenshot17| image:: pyci_1024x768_backup_restore.png

PyCI Set Hostname:
__________________
    |screenshot18|

.. |screenshot18| image:: pyci_1024x768_hostname.png

PyCI Hosts File Configuration:
______________________________
    |screenshot19|

.. |screenshot19| image:: pyci_1024x768_hosts.png

PyCI Init Script Control/Configuration (stop/start/restart, edit, enable/disable, and re-order):
________________________________________________________________________________________________
    |screenshot20|

.. |screenshot20| image:: pyci_1024x768_init_scripts.png

PyCI Reboot Interface (Initiate):
________________________________-
    |screenshot21|

.. |screenshot21| image:: pyci_1024x768_reboot1.png

PyCI Reboot Interface (After Reboot):
____________________________________-
    |screenshot22|

.. |screenshot22| image:: pyci_1024x768_reboot2.png

PyCI System Log Interface/Configuration:
________________________________________
    |screenshot23|

.. |screenshot23| image:: pyci_1024x768_syslog1.png

PyCI System Log Interface/Configuration:
________________________________________
    |screenshot24|

.. |screenshot24| image:: pyci_1024x768_syslog2.png

PyCI System Log Interface/Configuration (showing form validation):
__________________________________________________________________
    |screenshot25|

.. |screenshot25| image:: pyci_1024x768_syslog3.png

PyCI Timezone Interface:
________________________
    |screenshot26|

.. |screenshot26| image:: pyci_1024x768_timezone.png

PyCI Users and Groups Interface (showing context menu):
_______________________________________________________
    |screenshot27|

.. |screenshot27| image:: pyci_1024x768_users_and_groups1.png

PyCI Users and Groups Interface (showing context menu):
_______________________________________________________
    |screenshot28|

.. |screenshot28| image:: pyci_1024x768_users_and_groups2.png

Utilities Plugin
----------------
PyCI Ping Interface:
____________________
    |screenshot29|

.. |screenshot29| image:: pyci_1024x768_ping.png

PyCI Traceroute Interface:
__________________________
    |screenshot30|

.. |screenshot30| image:: pyci_1024x768_traceroute.png

PyCI Tcpdump Interface:
______________________-
    |screenshot31|

.. |screenshot31| image:: pyci_1024x768_tcpdump.png

Services Plugin
---------------
PyCI Quagga Interface/Configuration(vty selection screen):
__________________________________________________________
    |screenshot32|

.. |screenshot32| image:: pyci_1024x768_quagga1.png

PyCI Quagga Interface/Configuration (logged into the zebra vty):
________________________________________________________________
    |screenshot33|

.. |screenshot33| image:: pyci_1024x768_quagga2.png

PyCI Quagga Configuration (those lines are drag n' drop enabled):
________________________________________________________________-
    |screenshot34|

.. |screenshot34| image:: pyci_1024x768_quagga3.png

PyCI Coova Chilli Interface/Configuration (showing jTip help):
______________________________________________________________
    |screenshot35|

.. |screenshot35| image:: pyci_1024x768_coova_chilli1.png
**Note:** I couldn't get Coova Chilli to start up properly on OpenWRT.  The ipkg is missing an init script.  If it was running I'd have a screenshot showing how you can authorize or logout a user via the status tab.

PyCI Cron Interface:
____________________
    |screenshot36|

.. |screenshot36| image:: pyci_1024x768_cron.png
Pretty basic, I know...  But that's how I like it.

PyCI SSH Server (dropbear) Configuration:
________________________________________-
    |screenshot37|

.. |screenshot37| image:: pyci_1024x768_dropbear.png

PyCI ntpclient Configuration:
____________________________-
    |screenshot38|

.. |screenshot38| image:: pyci_1024x768_ntpclient.png

PyCI snmpd Configuration:
________________________-
    |screenshot39|

.. |screenshot39| image:: pyci_1024x768_snmpd.png
Note:  I wrote this to configure the regular snmpd package but I later decided that mini_snmpd was probably better...  But I never got around to adding the complete interface for that.  Thus; we have an interface for a package that isn't installed in my firmware (easily correctable later).

Network Plugin
--------------
PyCI Interface Configuration:
_____________________________
    |screenshot40|

.. |screenshot40| image:: pyci_1024x768_dhcp1.png

PyCI DHCP Server Configuration:
_______________________________
    |screenshot41|

.. |screenshot41| image:: pyci_1024x768_dhcp2.png

PyCI DHCP Server Configuration (showing select menu help):
__________________________________________________________
    |screenshot42|

.. |screenshot42| image:: pyci_1024x768_dhcp3.png

PyCI DHCP Server Configuration (/etc/ethers interface):
_______________________________________________________
    |screenshot43|

.. |screenshot43| image:: pyci_1024x768_dhcp4.png

PyCI Dynamic DNS Configuration:
_______________________________
    |screenshot44|

.. |screenshot44| image:: pyci_1024x768_ddns.png

PyCI Firewall Configuration (adding a new rule via an Easy Button):
___________________________________________________________________
    |screenshot45|

.. |screenshot45| image:: pyci_1024x768_firewall1.png

PyCI Firewall Configuration (editing the rule I just created):
____________________________
    |screenshot46|

.. |screenshot46| image:: pyci_1024x768_firewall2.png
**Note:** The iptables command is clearly displayed.  The user can also click on the "See the iptables command" button to get an easy copy/paste pop-up dialog.

PyCI Firewall Configuration (creating a port forwarding rule):
______________________________________________________________
    |screenshot47|

.. |screenshot47| image:: pyci_1024x768_firewall3.png

PyCI Firewall Configuration (editing the rule I just created):
______________________________________________________________
    |screenshot48|

.. |screenshot48| image:: pyci_1024x768_firewall4.png

PyCI Interfaces Configuration:
______________________________
    |screenshot49|

.. |screenshot49| image:: pyci_1024x768_interfaces.png
**Note:** The status of each interface is displayed.

PyCI QOS Configuration (configure defaults):
____________________________________________
    |screenshot50|

.. |screenshot50| image:: pyci_1024x768_qos1.png

PyCI QOS Configuration (packet classification):
_______________________________________________
    |screenshot51|

.. |screenshot51| image:: pyci_1024x768_qos2.png

PyCI QOS Configuration (de-proritize all P2P easy button demonstration):
________________________________________________________________________
    |screenshot52|

.. |screenshot52| image:: pyci_1024x768_qos3.png

PyCI QOS Configuration (proritize Skype):
_________________________________________
    |screenshot53|

.. |screenshot53| image:: pyci_1024x768_qos4.png

PyCI QOS Configuration (reclassification):
__________________________________________
    |screenshot54|

.. |screenshot54| image:: pyci_1024x768_qos5.png

PyCI QOS Configuration (QOS interfaces):
________________________________________
    |screenshot55|

.. |screenshot55| image:: pyci_1024x768_qos6.png

PyCI Static Routes Configuration (showing select menu help):
____________________________________________________________
    |screenshot56|

.. |screenshot56| image:: pyci_1024x768_static_routes.png

PyCI Switch Configuration (showing valid VLANs in select menu):
_______________________________________________________________
    |screenshot57|

.. |screenshot57| image:: pyci_1024x778_switch.png

PyCI Wireless Configuration (showing select menu help):
_______________________________________________________
    |screenshot58|

.. |screenshot58| image:: pyci_1024x768_wireless1.png

PyCI Firewall Status Interface (same as draft but in new location):
___________________________________________________________________
    |screenshot59|

.. |screenshot59| image:: pyci_1024x768_firewall_status.png

PyCI Real-time System Monitoring Interface (all graphs simiultaneously):
________________________________________________________________________
    |screenshot60|

.. |screenshot60| image:: pyci_1024x768_monitors.png

PyCI Listening Processes (netstat) Interface:
_____________________________________________
    |screenshot61|

.. |screenshot61| image:: pyci_1024x768_netstat.png