code.grnet.gr Git - flowspy/blob - README.txt

   1 ===========
   2 1. Tool requirements
   3 Note: Depending on your setup each of the following
   4 may depend on other packages
   5
   6 * python-django
   7 * python-django-extensions
   8 * python-mysqldb
   9 * mysql-client-5.1
  10 * python-gevent
  11 * python-django-south
  12 * python-django-celery
  13 * python-yaml
  14 * python-paramiko (>= 1.7.7.1)
  15 * python-memcache
  16 * python-django-registration
  17 * ncclient (http://ncclient.grnet.gr/,  http://github.com/leopoul/ncclient)
  18 * nxpy (https://code.grnet.gr/projects/nxpy)
  19 * python-lxml
  20 * python-ipaddr
  21 * python-django-tinymce
  22 * apache2
  23 * apache2-mod-proxy
  24 * apache2-mod-rewrite
  25 * apache2-shibboleth : The server should be setup as a Shibboleth SP
  26 * The tool requires an event supporting web server. It is suggested to deploy gunicorn
  27 * If you wish to link your own db tables (peers, networks, etc) with the tool, prefer MySQL MyISAM db engine and use views.
  28
  29 ===========
  30 2. Tool architecture
  31
  32 Firewall on Demand applies, via Netconf, flow rules to a network device. These rules are then propagated via e-bgp to peering routers.
  33 Each user is authenticated against shibboleth. Authorization is performed via a combination of a Shibboleth attribute and the peer network
  34 address range that the user originates from.
  35 Components roles:
  36         - web server (gunicorn): server the tool to localhost:port and allows for events
  37         - memcached: Caches devices information and aids in syncing
  38         - gunicorn/beanstalk: Job queue that applies firewall rules in a serial manner to avoid locks
  39
  40 ===========
  41 3. Operational requirements
  42
  43 * Shibboleth authentication
  44     - Shibboleth attributes:
  45         - eduPersonPrincipalName: Provides a string that uniquely identifies an administrator in the management application.
  46                 - eduPersonEntitlement: A specific URN value must be provided to authorize an administrator: urn:mace:grnet.gr:fod:admin
  47                 - 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.
  48                 - givenName (optional): The person's first name.
  49                 - sn (optional): The person's last name.
  50
  51 ===========
  52 4. Installation Procedure
  53
  54 4.1 Pre-installation
  55 Configure and setup celeryd, memcached, beanstalkd, web server (gunicorn mode: django), apache
  56 Copy settings.py.dist to settings.py and urls.py.dist to urls.py.
  57 In settings.py set the following according to your configuration:
  58 * 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
  59 * STATIC_URL (static media directory)
  60 * TEMPLATE_DIRS
  61 * CACHE_BACKEND
  62 * NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work)
  63 * NETCONF_USER (enable ssh and netconf on device)
  64 * NETCONF_PASS
  65 * BROKER_HOST (beanstalk host)
  66 * BROKER_PORT (beanstalk port)
  67 * SERVER_EMAIL
  68 * EMAIL_SUBJECT_PREFIX
  69 * BROKER_URL (beanstalk url)
  70 * SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication)
  71 * NOTIFY_ADMIN_MAILS (bcc mail addresses)
  72 * PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS)
  73 * PRIMARY_WHOIS
  74 * ALTERNATE_WHOIS
  75
  76 4.2 Branding
  77
  78 4.2.1 Logos
  79
  80 Inside the static folder you will find two empty png files: fod_logo.xcf (Gimp file) and shib_login.dist.png.
  81 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
  82 other code changes. In case you want to incorporate images of different sizes you have to fine tune css and/or html as well.
  83
  84 4.2.2 Footer
  85
  86 Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc.
  87
  88 4.2.3 Welcome Page
  89
  90 Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc.
  91
  92 4.3 Configuration Examples
  93
  94 * Gunicorn configuration
  95         /etc/gunicorn.d/project:
  96         CONFIG = {
  97     'mode': 'django',
  98     'working_dir': '/path/to/flowspy',
  99    #'python': '/usr/bin/python',
 100     'args': (
 101         '--bind=localhost:port',
 102         '--workers=1',
 103         '--timeout=360',
 104         #'--keepalive=90',
 105         '--worker-class=egg:gunicorn#gevent',
 106         '--log-level=debug',
 107         '--log-file=/path/to/fod.log',
 108         'settings.py',
 109     ),
 110 }
 111
 112 * Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled.
 113 Depending on the setup the apache configuration may vary.
 114
 115
 116 * Celeryd example configuration:
 117         /etc/default/celeryd:
 118         # Name of nodes to start, here we have a single node
 119         CELERYD_NODES="w1"
 120         # or we could have three nodes:
 121         #CELERYD_NODES="w1 w2 w3"
 122
 123         # Where to chdir at start.
 124         CELERYD_CHDIR="/path/to/flowspy/"
 125         # How to call "manage.py celeryd_multi"
 126         CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi"
 127
 128         # How to call "manage.py celeryctl"
 129         CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl"
 130
 131         # Extra arguments to celeryd
 132         #CELERYD_OPTS="--time-limit=300 --concurrency=8"
 133         CELERYD_OPTS="-E -B"
 134         # Name of the celery config module.
 135         CELERY_CONFIG_MODULE="celeryconfig"
 136
 137         # %n will be replaced with the nodename.
 138         CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
 139         CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
 140
 141         # Workers should run as an unprivileged user.
 142         CELERYD_USER="user"
 143         CELERYD_GROUP="usergroup"
 144
 145         # Name of the projects settings module.
 146         export DJANGO_SETTINGS_MODULE="settings"
 147
 148
 149 4.4 Installation
 150
 151 * Run:
 152         ./manage.py syncdb
 153         to create all the necessary tables in the database. Enable the admin account to insert initial data for peers and their contact info.
 154 * Then to allow for south migrations:
 155         ./manage.py migration
 156 * Only if you wish to obtain info for your peers from a whois server:
 157   If you have properly set the primary and alternate whois servers you could go for:
 158         ./manage.py fetch_networks
 159         to automatically fill network info.
 160         Alternatively you could fill those info manually via the admin interface.
 161 * Via the admin interface, modify as required the existing (example.com) Site instance
 162 * Modify flatpages to suit your needs
 163 * 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.
 164
 165
 166 ** To share ideas and ask questions drop an email at: leopoul-at-noc(dot)grnet{dot}gr
 167