README.txt 4.12 KB
Newer Older
Leonidas Poulopoulos's avatar
Leonidas Poulopoulos committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
===========
1. Tool requirements

* python-django
* python-django-extensions
* python-mysqldb
* mysql-client-5.1
* python-gevent
* python-django-south
* python-django-celery
* python-yaml
* python-paramiko (>= 1.7.7.1)
* python-memcache
* python-django-registration
* python-ncclient
* python-nxpy
* python-lxml
* python-ipaddr
19
* python-django-tinymce
Leonidas Poulopoulos's avatar
Leonidas Poulopoulos committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
* apache2
* apache2-mod-proxy
* apache2-mod-rewrite
* apache2-shibboleth : The server should be setup as a Shibboleth SP
* The tool requires an event supporting web server. It is suggested to deploy gunicorn
* If you wish to link your own db tables (peers, networks, etc) with the tool, prefer MySQL MyISAM db engine and use views.

===========
2. Tool architecture

Firewall on Demand applies, via Netconf, flow rules to a network device. These rules are then propagated via e-bgp to peering routers.
Each user is authenticated against shibboleth. Authorization is performed via a combination of a Shibboleth attribute and the peer network
address range that the user originates from.
Components roles:
	- web server (gunicorn): server the tool to localhost:port and allows for events
	- memcached: Caches devices information and aids in syncing
	- gunicorn/beanstalk: Job queue that applies firewall rules in a serial manner to avoid locks

===========
3. Operational requirements

* Shibboleth authentication
    - Required shibboleth attributes:
        - HTTP_EPPN
        - HTTP_SHIB_INETORGPERSON_MAIL
        - An appropriate HTTP_SHIB_EP_ENTITLEMENT
    - Optional Attributes:
        - HTTP_SHIB_INETORGPERSON_GIVENNAME
        - HTTP_SHIB_PERSON_SURNAME
* A valid domain name in peer table (passed through HTTP_SHIB_HOMEORGANIZATION)

===========
4. Installation Procedure

4.1 Pre-installation
Configure and setup celeryd, memcached, beanstalkd, web server (gunicorn mode: django), apache
Copy settings.py.dist to settings.py and urls.py.dist to urls.py.
In settings.py set the following according to your configuration:
* DATABASES (to point to your local database). You could use views instead of tables for models: peer, peercontacts, peernetworks. For this to work we suggest MySQL with MyISAM db engine
* STATIC_URL (static media directory) 
* TEMPLATE_DIRS
* CACHE_BACKEND
* NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work)
* NETCONF_USER (enable ssh and netconf on device)
* NETCONF_PASS
* BROKER_HOST (beanstalk host)
* BROKER_PORT (beanstalk port)
* SERVER_EMAIL
* EMAIL_SUBJECT_PREFIX
* BROKER_URL (beanstalk url)
* SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication)
* NOTIFY_ADMIN_MAILS (bcc mail addresses)
* PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS)
* PRIMARY_WHOIS
* ALTERNATE_WHOIS

76 77 78 79 80 81 82 83 84 85 86 87 88
4.2 Branding

4.2.1 Logos

Inside the static folder you will find two empty png files: logo.dist.png (172x80) and shib_login.dist.png (98x80).
Edit those two with your favourite image processing software and save them as logo.png and shib_login.png under the same folder. Image sizes are optimized to operate without any
other code changes. In case you want to incorporate images of different sizes you have to fine tune css and/or html as well.

4.2.2 Footer

Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc.

4.3 Installation
Leonidas Poulopoulos's avatar
Leonidas Poulopoulos committed
89 90 91 92 93 94 95 96 97 98 99 100 101 102

* Run:
	./manage.py syncdb
	to create all the necessary tables in the database. Enable the admin account to insert initial data for peers and their contact info.
* Then to allow for south migrations:
	./manage.py migration
* If you have properly set the primary and alternate whois servers you could go for:
	./manage.py fetch_networks
	to automatically fill network info.
	Alternatively you could fill those info manually via the admin interface.
* Via the admin interface, modify as required the existing (example.com) Site instance
* Modify flatpages to suit your needs 
* Once Apache proxying and shibboleth modules are properly setup, login to the tool. If shibboleth SP is properly setup you should see a user pending activation message and an activation email should arrive at the NOTIFY_ADMIN_MAILS accounts.