6 Ubuntu 12.04.3 (64) - Django 1.3.x
7 ==================================
9 This guide assumes that installation is carried out in /srv/flowspy
10 directory. If other directory is to be used, please change the
11 corresponding configuration files. It is also assumed that the root
12 user will perform every action.
15 Required system packages
16 ------------------------
18 Update and install the required packages:
22 apt-get install mysql-server apache2 memcached libapache2-mod-proxy-html gunicorn beanstalkd python-django python-django-extensions python-django-south python-django-tinymce tinymce python-mysqldb python-yaml python-memcache python-django-registration python-ipaddr python-lxml mysql-client git python-django-celery python-paramiko python-gevent vim
24 Note: Set username and password for mysql if used
26 Note: If you wish to deploy an outgoing mail server, now it is time to do
27 it. Otherwise you could set FoD to send out mails via a third party
31 Required application packages
32 -----------------------------
34 Get the required packages and install them
36 * ncclient: NETCONF python client:
39 git clone https://github.com/leopoul/ncclient.git
41 python setup.py install
43 * nxpy: Python Objects from/to XML proxy:
46 git clone https://code.grnet.gr/git/nxpy
48 python setup.py install
50 * flowspy: core application. Installation is done at /srv/flowspy:
53 git clone https://code.grnet.gr/git/flowspy
57 Application configuration
58 =========================
60 Copy settings.py.dist to settings.py:
62 cp settings.py.dist settings.py
64 Edit settings.py file and set the following according to your
67 ADMINS: set your admin name and email (assuming that your server can send notifications)
68 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
69 SECRET_KEY : Make this unique, and don't share it with anybody
70 STATIC_URL (static media directory) . If you have followed the above this should be: /srv/flowspy/static
71 TEMPLATE_DIRS : If you have followed the above this should be: /srv/flowspy/templates
72 CACHE_BACKEND: If you have followed the above this should be: memcached://127.0.0.1:11211/?timeout=3600
73 Alternatively you could go for redis with the corresponding Django client lib.
74 NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work). This is the flowspec capable device
75 NETCONF_USER (enable ssh and netconf on device)
77 If beanstalk is selected the following should be left intact.
78 BROKER_HOST (beanstalk host)
79 BROKER_PORT (beanstalk port)
82 If beanstalk is selected the following should be left intact.
83 BROKER_URL (beanstalk url)
84 SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication)
85 NOTIFY_ADMIN_MAILS (bcc mail addresses)
86 PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS)
87 The whois client is meant to be used in case you have inserted peers with their ASes in the peers table and wish to get network info for each one in an automated manner.
90 If you wish to deploy FoD with Shibboleth change the following attributes according to your setup:
91 SHIB_AUTH_ENTITLEMENT = 'urn:mace'
92 SHIB_ADMIN_DOMAIN = 'example.com'
93 SHIB_LOGOUT_URL = 'https://example.com/Shibboleth.sso/Logout'
94 SHIB_USERNAME = ['HTTP_EPPN']
95 SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL']
96 SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME']
97 SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME']
98 SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT']
100 If you have not installed an outgoing mail server you can always use
101 your own account (either corporate or gmail, hotmail ,etc) by adding
102 the following lines in settings.py:
104 EMAIL_USE_TLS = True #(or False)
105 EMAIL_HOST = 'smtp.example.com'
106 EMAIL_HOST_USER = 'username'
107 EMAIL_HOST_PASSWORD = 'yourpassword'
108 EMAIL_PORT = 587 #(outgoing)
110 Note: Soon we will release a version with django-registration as a means
111 to add users and Shibboleth as an alternative
113 Let's move on with some copies and dir creations:
115 cp urls.py.dist urls.py
117 chown -R root:www-data log/
124 Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules
125 enabled. Depending on the setup the apache configuration may vary:
132 If shibboleth is to be used:
134 apt-get install libapache2-mod-shib2
137 Now it is time to configure beanstalk, gunicorn, celery and apache.
143 Enable beanstalk by editting /etc/default/beanstalkd:
145 vim /etc/default/beanstalkd
147 Uncomment the line **START=yes** to enable beanstalk
151 service beanstalkd start
157 create and edit /etc/gunicorn.d/fod:
159 vim /etc/gunicorn.d/fod
161 FoD is served via gunicorn and is then proxied by Apache. If the above
162 directory conventions have been followed so far, then your
163 configuration should be:
167 'working_dir': '/srv/flowspy',
169 '--bind=127.0.0.1:8081',
172 '--worker-class=egg:gunicorn#gevent',
182 Celery is used over beanstalkd to apply firewall rules in a serial
183 manner so that locks are avoided on the flowspec capable device. In
184 our setup celery runs via django. That is why the python-django-celery
185 package was installed.
187 Note: Make sure that /etc/init.d/celeryd exists.
189 celeryd requires a /etc/default/celeryd file to be in place. Thus we
190 are going to create this file (/etc/default/celeryd):
192 vim /etc/default/celeryd
194 Again if the directory conventions have been followed the file should
197 # Name of nodes to start, here we have a single node
199 # or we could have three nodes:
200 #CELERYD_NODES="w1 w2 w3"
202 # Where to chdir at start.
203 CELERYD_CHDIR="/srv/flowspy/"
204 # How to call "manage.py celeryd_multi"
205 CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi"
207 # How to call "manage.py celeryctl"
208 CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl"
210 # Extra arguments to celeryd
211 #CELERYD_OPTS="--time-limit=300 --concurrency=8"
213 # Name of the celery config module.
214 CELERY_CONFIG_MODULE="celeryconfig"
216 # %n will be replaced with the nodename.
217 CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
218 CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
220 # Workers should run as an unprivileged user.
224 # Name of the projects settings module.
225 export DJANGO_SETTINGS_MODULE="settings"
231 Apache proxies gunicorn. Things are more flexible here as you may
232 follow your own configuration and conventions. Create and edit
233 /etc/apache2/sites-available/fod. You should set <server_name> and
234 <admin_mail> along with your certificates. If under testing
235 environment, you can use the provided snakeoil certs. If you do not
236 intent to use Shibboleth delete or comment the corresponding
237 configuration parts inside **Shibboleth configuration**
239 vim /etc/apache2/sites-available/fod
241 Again if the directory conventions have been followed the file should
245 ServerAdmin webmaster@localhost
246 ServerName <server_name>
247 DocumentRoot /var/www
249 Options FollowSymLinks
252 <Directory /var/www/>
253 Options Indexes FollowSymLinks MultiViews
259 ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
260 <Directory "/usr/lib/cgi-bin">
262 Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
267 ErrorLog ${APACHE_LOG_DIR}/error.log
269 # Possible values include: debug, info, notice, warn, error, crit,
273 CustomLog ${APACHE_LOG_DIR}/access.log combined
275 Alias /doc/ "/usr/share/doc/"
276 <Directory "/usr/share/doc/">
277 Options Indexes MultiViews FollowSymLinks
281 Allow from 127.0.0.0/255.0.0.0 ::1/128
285 RewriteCond %{HTTPS} off
286 RewriteRule ^/(.*) https://<server_name>/$1 [L,R]
290 ServerName <server_name>
291 ServerAdmin <admin_mail>
295 SSLCertificateFile /etc/ssl/certs/example.com.crt
296 SSLCertificateChainFile /etc/ssl/certs/example.com.crt
297 SSLCertificateKeyFile /etc/ssl/private/example.com.key
299 AddDefaultCharset UTF-8
300 IndexOptions +Charset=UTF-8
302 # Shibboleth configuration
303 ShibConfig /etc/shibboleth/shibboleth2.xml
304 Alias /shibboleth-sp /usr/share/shibboleth
306 <Location /fod/login>
308 ShibRequireSession On
313 # Shibboleth debugging CGI script
314 ScriptAlias /shibboleth/test /usr/lib/cgi-bin/shibtest.cgi
315 <Location /shibboleth/test>
317 ShibRequireSession On
322 <Location /Shibboleth.sso>
326 # End of Shibboleth configuration
328 <Location /admin/media/>
332 Alias /admin/media /usr/share/pyshared/django/contrib/admin/media
333 Alias /media /usr/share/pyshared/django/contrib/admin/media
334 DocumentRoot /var/www
335 <Directory /var/www/>
336 Options Indexes FollowSymLinks MultiViews
350 ProxyErrorOverride off
352 ProxyPass /fod http://localhost:8081/fod retry=0
353 ProxyPassReverse /fod http://localhost:8081/fod
356 ErrorLog /var/log/apache2/ssl-error.log
357 CustomLog /var/log/apache2/ssl-access.log combined
362 Alias /fodstatic /srv/flowspy/static
366 You are not far away from deploying FoD. When asked for a super user,
370 python manage.py syncdb
371 python manage.py migrate
373 Restart, gunicorn and apache:
375 service gunicorn restart && service apache2 restart
381 Log in to the admin interface via https://<your ip>/fod/admin. Go to
382 Peer ranges and add a new range (part of/or a complete subnet), eg.
383 83.212.0.0/19 Go to Peers and add a new peer, eg. id: 1, name: Test,
384 AS: 16503, tag: TEST and move the network you have crteated from
385 Avalable to Chosen. From the admin front, go to User, and edit your
386 user. From the bottom of the page, select the TEST peer and save. Last
387 but not least, modify as required the existing (example.com) Site
388 instance. You are done. As you are logged-n via the admin, there is no
389 need for Shibboleth. Go to https://<your ip>/fod/ and create a new
390 rule. Your rule should be applied on the flowspec capable device after
397 Via the admin interface you can modify flatpages to suit your needs
403 Inside the static folder you will find two empty png files:
404 fod_logo.xcf (Gimp file) and shib_login.dist.png. Edit those two with
405 your favourite image processing software and save them as fod_logo.png
406 (under static/img/) and shib_login.png (under static/). Image sizes
407 are optimized to operate without any other code changes. In case you
408 want to incorporate images of different sizes you have to fine tune
409 css and/or html as well.
415 Under the templates folder (templates), you can alter the footer.html
416 file to include your own footer messages, badges, etc.
422 Under the templates folder (templates), you can alter the welcome page
423 - welcome.html with your own images, carousel, videos, etc.