-===========
-1. Tool requirements
-Note: Depending on your setup each of the following
-may depend on other packages
-
-* 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
-* ncclient (http://ncclient.grnet.gr/, http://github.com/leopoul/ncclient)
-* nxpy (https://code.grnet.gr/projects/nxpy)
-* python-lxml
-* python-ipaddr
-* python-django-tinymce
-* 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
+******************
-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
- - Shibboleth attributes:
- - eduPersonPrincipalName: Provides a string that uniquely identifies an administrator in the management application.
- - eduPersonEntitlement: A specific URN value must be provided to authorize an administrator: urn:mace:grnet.gr:fod:admin
- - mail: The e-mail address (one or more) of the administrator. It is used for notifications from the management application. It may also be used for further communication, with prior consent.
- - givenName (optional): The person's first name.
- - sn (optional): The person's last name.
-
+Description
===========
-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
-
-4.2 Branding
-
-4.2.1 Logos
-
-Inside the static folder you will find two empty png files: fod_logo.xcf (Gimp file) and shib_login.dist.png.
-Edit those two with your favourite image processing software and save them as fod_logo.png (under static/img/) and shib_login.png (under static/). 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.2.3 Welcome Page
-
-Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc.
-
-4.3 Configuration Examples
-
-* Gunicorn configuration
- /etc/gunicorn.d/project:
- CONFIG = {
- 'mode': 'django',
- 'working_dir': '/path/to/flowspy',
- #'python': '/usr/bin/python',
- 'args': (
- '--bind=localhost:port',
- '--workers=1',
- '--timeout=360',
- #'--keepalive=90',
- '--worker-class=egg:gunicorn#gevent',
- '--log-level=debug',
- '--log-file=/path/to/fod.log',
- 'settings.py',
- ),
-}
-
-* Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled.
-Depending on the setup the apache configuration may vary.
-
-
-* Celeryd example configuration:
- /etc/default/celeryd:
- # Name of nodes to start, here we have a single node
- CELERYD_NODES="w1"
- # or we could have three nodes:
- #CELERYD_NODES="w1 w2 w3"
-
- # Where to chdir at start.
- CELERYD_CHDIR="/path/to/flowspy/"
- # How to call "manage.py celeryd_multi"
- CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi"
-
- # How to call "manage.py celeryctl"
- CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl"
-
- # Extra arguments to celeryd
- #CELERYD_OPTS="--time-limit=300 --concurrency=8"
- CELERYD_OPTS="-E -B"
- # Name of the celery config module.
- CELERY_CONFIG_MODULE="celeryconfig"
-
- # %n will be replaced with the nodename.
- CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
- CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
-
- # Workers should run as an unprivileged user.
- CELERYD_USER="user"
- CELERYD_GROUP="usergroup"
-
- # Name of the projects settings module.
- export DJANGO_SETTINGS_MODULE="settings"
-
-
-4.4 Installation
-
-* 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
-* Only if you wish to obtain info for your peers from a whois server:
- 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.
-
-
-** To share ideas and ask questions drop an email at: leopoul-at-noc(dot)grnet{dot}gr
+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. FoD is meant to
+operate over this architecture:
+
+ +-----------+ +------------+ +------------+
+ | FoD | NETCONF | flowspec | ebgp | router |
+ | web app +----------> device +--------> |
+ +-----------+ +------+-----+ +------------+
+ | ebgp
+ |
+ +------v-----+
+ | router |
+ | |
+ +------------+
+
+NETCONF is chosen as the mgmt protocol to apply rules to a single
+flowspec capable device. Rules are then propagated via igbp to all
+flowspec capable routers. Of course FoD could apply rules directly
+(via NETCONF always) to a router and then ibgp would do the rest. In
+GRNET's case the flowspec capable device is an EX4200.
+
+Attention: Make sure your FoD server has ssh access to your flowspec device.
+
+
+Installation Considerations
+===========================
+
+You can find the installation instructions for Ubuntu 12.04.3 (64)
+with Django 1.3.x in install.txt file. FoD depends on a bunch of
+packages. Installing in Debian Squeeze proved to be really tough as
+the majority of the required packages are not provided by any repos
+and need to be installed manually. This guide presents the
+installation procedures for Ubuntu 12.04.3 (64) with Django 1.3.x.
+Really soon, we will provide a guide for Debian Wheezy. However, users
+who wish to go for Wheezy, need to read the Django 1.4 changelist. One
+of the most significant changes in Django 1.4 is that the application
+dir layout has to be restructured. Also bear in mind that Django 1.4
+introduces new aspects when it comes to application library
+inclussions.
+
+Soon we will post a branch of FoD tailored for Django 1.4.
+
+
+Contact
+=======
+
+You can find more about FoD or raise your issues at GRNET FoD
+repository: https://code.grnet.gr/fod.
+
+You can contactus directly at leopoul{at}noc[dot]grnet(.)gr