code.grnet.gr Git - flowspy/blob - doc/source/install.rst

   1 ************
   2 Installation
   3 ************
   4
   5 .. toctree::
   6    :maxdepth: 2
   7
   8 Ubuntu 12.04.3 (64) - Django 1.3.x
   9 ==================================
  10
  11 This guide assumes that installation is carried out in /srv/flowspy directory. If other directory is to be used, please change the corresponding configuration files. It is also assumed that the root user will perform every action.
  12
  13 Required system packages
  14 ------------------------
  15
  16 Update and install the required packages::
  17
  18         apt-get update
  19         apt-get upgrade
  20         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
  21
  22 .. note::
  23  Set username and password for mysql if used
  24
  25 .. note::
  26         If you wish to deploy an outgoing mail server, now it is time to do it. Otherwise you could set FoD to send out mails via a third party account
  27
  28 Create a database
  29 -----------------
  30 If you are using mysql, you should create a database::
  31
  32         mysql -u root -p -e 'create database fod'
  33
  34
  35 Required application packages
  36 -----------------------------
  37 Get the required packages and install them
  38
  39 - ncclient: NETCONF python client::
  40
  41         cd ~
  42         git clone https://github.com/leopoul/ncclient.git
  43         cd ncclient
  44         python setup.py install
  45
  46 - nxpy: Python Objects from/to XML proxy::
  47
  48         cd ~
  49         git clone https://code.grnet.gr/git/nxpy
  50         cd nxpy
  51         python setup.py install
  52
  53 - flowspy: core application. Installation is done at /srv/flowspy::
  54
  55         cd /srv
  56         git clone https://code.grnet.gr/git/flowspy
  57         cd flowspy
  58
  59 Application configuration
  60 =========================
  61
  62 Copy settings.py.dist to settings.py::
  63
  64         cp settings.py.dist settings.py
  65
  66 Edit settings.py file and set the following according to your configuration::
  67
  68         ADMINS: set your admin name and email (assuming that your server can send notifications)
  69         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
  70         SECRET_KEY : Make this unique, and don't share it with anybody
  71         STATIC_URL (static media directory) . If you have followed the above this should be: /srv/flowspy/static
  72         TEMPLATE_DIRS : If you have followed the above this should be: /srv/flowspy/templates
  73         CACHE_BACKEND:  If you have followed the above this should be: memcached://127.0.0.1:11211/?timeout=3600
  74         Alternatively you could go for redis with the corresponding Django client lib.
  75         NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work). This is the flowspec capable device
  76         NETCONF_USER (enable ssh and netconf on device)
  77         NETCONF_PASS
  78         If beanstalk is selected the following should be left intact.
  79         BROKER_HOST (beanstalk host)
  80         BROKER_PORT (beanstalk port)
  81         SERVER_EMAIL
  82         EMAIL_SUBJECT_PREFIX
  83         If beanstalk is selected the following should be left intact.
  84         BROKER_URL (beanstalk url)
  85         SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication)
  86         NOTIFY_ADMIN_MAILS (bcc mail addresses)
  87         PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS)
  88         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.
  89         PRIMARY_WHOIS
  90         ALTERNATE_WHOIS
  91         If you wish to deploy FoD with Shibboleth change the following attributes according to your setup:
  92         SHIB_AUTH_ENTITLEMENT = 'urn:mace'
  93         SHIB_ADMIN_DOMAIN = 'example.com'
  94         SHIB_LOGOUT_URL = 'https://example.com/Shibboleth.sso/Logout'
  95         SHIB_USERNAME = ['HTTP_EPPN']
  96         SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL']
  97         SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME']
  98         SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME']
  99         SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT']
 100
 101 If you have not installed an outgoing mail server you can always use your own account (either corporate or gmail, hotmail ,etc) by adding the following lines in settings.py::
 102
 103         EMAIL_USE_TLS = True #(or False)
 104         EMAIL_HOST = 'smtp.example.com'
 105         EMAIL_HOST_USER = 'username'
 106         EMAIL_HOST_PASSWORD = 'yourpassword'
 107         EMAIL_PORT = 587 #(outgoing)
 108
 109
 110 .. note::
 111         Soon we will release a version with django-registration as a means to add users and Shibboleth as an alternative
 112
 113 Let's move on with some copies and dir creations::
 114
 115         cp urls.py.dist urls.py
 116         mkdir log
 117         chown -R root:www-data log/
 118         chmod -R g+w log
 119
 120 System configuration
 121 ====================
 122 Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled.
 123 Depending on the setup the apache configuration may vary::
 124
 125         a2enmod rewrite
 126         a2enmod proxy
 127         a2enmod ssl
 128         a2enmod proxy_http
 129
 130 If shibboleth is to be used::
 131
 132         apt-get install libapache2-mod-shib2
 133         a2enmod shib2
 134
 135 Now it is time to configure beanstalk, gunicorn, celery and apache.
 136
 137 beanstalkd
 138 ----------
 139
 140 Enable beanstalk by editting /etc/default/beanstalkd::
 141
 142         vim /etc/default/beanstalkd
 143
 144 Uncomment the line **START=yes** to enable beanstalk
 145
 146 Start beanstalkd::
 147
 148         service beanstalkd start
 149
 150 gunicorn.d
 151 ----------
 152
 153 create and edit /etc/gunicorn.d/fod::
 154
 155         vim /etc/gunicorn.d/fod
 156
 157 FoD is served via gunicorn and is then proxied by Apache. If the above directory conventions have been followed so far, then your configuration should be::
 158
 159         CONFIG = {
 160             'mode': 'django',
 161             'working_dir': '/srv/flowspy',
 162             'args': (
 163                 '--bind=127.0.0.1:8081',
 164                 '--workers=1',
 165                 '--timeout=360',
 166                 '--worker-class=egg:gunicorn#gevent',
 167                 '--log-level=debug',
 168                 'settings.py',
 169             ),
 170         }
 171
 172 celery.d
 173 --------
 174
 175 Celery is used over beanstalkd to apply firewall rules in a serial manner so that locks are avoided on the flowspec capable device. In our setup celery runs via django. That is why the python-django-celery package was installed.
 176
 177 Create the celeryd daemon at /etc/init.d/celeryd::
 178         #!/bin/sh -e
 179         # ============================================
 180         #  celeryd - Starts the Celery worker daemon.
 181         # ============================================
 182         #
 183         # :Usage: /etc/init.d/celeryd {start|stop|force-reload|restart|try-restart|status}
 184         # :Configuration file: /etc/default/celeryd
 185         #
 186         # See http://docs.celeryq.org/en/latest/cookbook/daemonizing.html#init-script-celeryd
 187
 188
 189         ### BEGIN INIT INFO
 190         # Provides:          celeryd
 191         # Required-Start:    $network $local_fs $remote_fs
 192         # Required-Stop:     $network $local_fs $remote_fs
 193         # Default-Start:     2 3 4 5
 194         # Default-Stop:      0 1 6
 195         # Short-Description: celery task worker daemon
 196         ### END INIT INFO
 197
 198         #set -e
 199
 200         DEFAULT_PID_FILE="/var/run/celeryd@%n.pid"
 201         DEFAULT_LOG_FILE="/var/log/celeryd@%n.log"
 202         DEFAULT_LOG_LEVEL="INFO"
 203         DEFAULT_NODES="celery"
 204         DEFAULT_CELERYD="-m celery.bin.celeryd_detach"
 205
 206         # /etc/init.d/celeryd: start and stop the celery task worker daemon.
 207
 208         CELERY_DEFAULTS=${CELERY_DEFAULTS:-"/etc/default/celeryd"}
 209
 210         test -f "$CELERY_DEFAULTS" && . "$CELERY_DEFAULTS"
 211         if [ -f "/etc/default/celeryd" ]; then
 212             . /etc/default/celeryd
 213         fi
 214
 215         CELERYD_PID_FILE=${CELERYD_PID_FILE:-${CELERYD_PIDFILE:-$DEFAULT_PID_FILE}}
 216         CELERYD_LOG_FILE=${CELERYD_LOG_FILE:-${CELERYD_LOGFILE:-$DEFAULT_LOG_FILE}}
 217         CELERYD_LOG_LEVEL=${CELERYD_LOG_LEVEL:-${CELERYD_LOGLEVEL:-$DEFAULT_LOG_LEVEL}}
 218         CELERYD_MULTI=${CELERYD_MULTI:-"celeryd-multi"}
 219         CELERYD=${CELERYD:-$DEFAULT_CELERYD}
 220         CELERYCTL=${CELERYCTL:="celeryctl"}
 221         CELERYD_NODES=${CELERYD_NODES:-$DEFAULT_NODES}
 222
 223         export CELERY_LOADER
 224
 225         if [ -n "$2" ]; then
 226             CELERYD_OPTS="$CELERYD_OPTS $2"
 227         fi
 228
 229         CELERYD_LOG_DIR=`dirname $CELERYD_LOG_FILE`
 230         CELERYD_PID_DIR=`dirname $CELERYD_PID_FILE`
 231         if [ ! -d "$CELERYD_LOG_DIR" ]; then
 232             mkdir -p $CELERYD_LOG_DIR
 233         fi
 234         if [ ! -d "$CELERYD_PID_DIR" ]; then
 235             mkdir -p $CELERYD_PID_DIR
 236         fi
 237
 238         # Extra start-stop-daemon options, like user/group.
 239         if [ -n "$CELERYD_USER" ]; then
 240             DAEMON_OPTS="$DAEMON_OPTS --uid=$CELERYD_USER"
 241             chown "$CELERYD_USER" $CELERYD_LOG_DIR $CELERYD_PID_DIR
 242         fi
 243         if [ -n "$CELERYD_GROUP" ]; then
 244             DAEMON_OPTS="$DAEMON_OPTS --gid=$CELERYD_GROUP"
 245             chgrp "$CELERYD_GROUP" $CELERYD_LOG_DIR $CELERYD_PID_DIR
 246         fi
 247
 248         if [ -n "$CELERYD_CHDIR" ]; then
 249             DAEMON_OPTS="$DAEMON_OPTS --workdir=\"$CELERYD_CHDIR\""
 250         fi
 251
 252
 253         check_dev_null() {
 254             if [ ! -c /dev/null ]; then
 255                 echo "/dev/null is not a character device!"
 256                 exit 1
 257             fi
 258         }
 259
 260
 261         export PATH="${PATH:+$PATH:}/usr/sbin:/sbin"
 262
 263
 264         stop_workers () {
 265             $CELERYD_MULTI stop $CELERYD_NODES --pidfile="$CELERYD_PID_FILE"
 266         }
 267
 268
 269         start_workers () {
 270             $CELERYD_MULTI start $CELERYD_NODES $DAEMON_OPTS        \
 271                                  --pidfile="$CELERYD_PID_FILE"      \
 272                                  --logfile="$CELERYD_LOG_FILE"      \
 273                                  --loglevel="$CELERYD_LOG_LEVEL"    \
 274                                  --cmd="$CELERYD"                   \
 275                                  $CELERYD_OPTS
 276         }
 277
 278
 279         restart_workers () {
 280             $CELERYD_MULTI restart $CELERYD_NODES $DAEMON_OPTS      \
 281                                    --pidfile="$CELERYD_PID_FILE"    \
 282                                    --logfile="$CELERYD_LOG_FILE"    \
 283                                    --loglevel="$CELERYD_LOG_LEVEL"  \
 284                                    --cmd="$CELERYD"                 \
 285                                    $CELERYD_OPTS
 286         }
 287
 288
 289
 290         case "$1" in
 291             start)
 292                 check_dev_null
 293                 start_workers
 294             ;;
 295
 296             stop)
 297                 check_dev_null
 298                 stop_workers
 299             ;;
 300
 301             reload|force-reload)
 302                 echo "Use restart"
 303             ;;
 304
 305             status)
 306                 $CELERYCTL status $CELERYCTL_OPTS
 307             ;;
 308
 309             restart)
 310                 check_dev_null
 311                 restart_workers
 312             ;;
 313
 314             try-restart)
 315                 check_dev_null
 316                 restart_workers
 317             ;;
 318
 319             *)
 320                 echo "Usage: /etc/init.d/celeryd {start|stop|restart|try-restart|kill}"
 321                 exit 1
 322             ;;
 323         esac
 324
 325         exit 0
 326
 327 and make it executable::
 328
 329         chmod +x /etc/init.d/celeryd
 330
 331 celeryd requires a /etc/default/celeryd file to be in place.
 332 Thus we are going to create this file (/etc/default/celeryd)::
 333
 334         vim /etc/default/celeryd
 335
 336 Again if the directory conventions have been followed the file should be::
 337
 338         # Name of nodes to start, here we have a single node
 339         CELERYD_NODES="w1"
 340         # or we could have three nodes:
 341         #CELERYD_NODES="w1 w2 w3"
 342
 343         # Where to chdir at start.
 344         CELERYD_CHDIR="/srv/flowspy/"
 345         # How to call "manage.py celeryd_multi"
 346         CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi"
 347
 348         # How to call "manage.py celeryctl"
 349         CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl"
 350
 351         # Extra arguments to celeryd
 352         #CELERYD_OPTS="--time-limit=300 --concurrency=8"
 353         CELERYD_OPTS="-E -B"
 354         # Name of the celery config module.
 355         CELERY_CONFIG_MODULE="celeryconfig"
 356
 357         # %n will be replaced with the nodename.
 358         CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
 359         CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
 360
 361         # Workers should run as an unprivileged user.
 362         CELERYD_USER="root"
 363         CELERYD_GROUP="root"
 364
 365         # Name of the projects settings module.
 366         export DJANGO_SETTINGS_MODULE="settings"
 367
 368 Apache
 369 ------
 370 Apache proxies gunicorn. Things are more flexible here as you may follow your own configuration and conventions. Create and edit /etc/apache2/sites-available/fod. You should set <server_name> and <admin_mail> along with your certificates. If under testing environment, you can use the provided snakeoil certs. If you do not intent to use Shibboleth delete or comment the corresponding configuration parts inside **Shibboleth configuration** ::
 371
 372         vim /etc/apache2/sites-available/fod
 373
 374 Again if the directory conventions have been followed the file should be::
 375
 376         <VirtualHost *:80>
 377                 ServerAdmin webmaster@localhost
 378                 ServerName      <server_name>
 379                 DocumentRoot /var/www
 380                 <Directory />
 381                         Options FollowSymLinks
 382                         AllowOverride None
 383                 </Directory>
 384                 <Directory /var/www/>
 385                         Options Indexes FollowSymLinks MultiViews
 386                         AllowOverride None
 387                         Order allow,deny
 388                         allow from all
 389                 </Directory>
 390
 391                 ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
 392                 <Directory "/usr/lib/cgi-bin">
 393                         AllowOverride None
 394                         Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
 395                         Order allow,deny
 396                         Allow from all
 397                 </Directory>
 398
 399                 ErrorLog ${APACHE_LOG_DIR}/error.log
 400
 401                 # Possible values include: debug, info, notice, warn, error, crit,
 402                 # alert, emerg.
 403                 LogLevel warn
 404
 405                 CustomLog ${APACHE_LOG_DIR}/access.log combined
 406
 407             Alias /doc/ "/usr/share/doc/"
 408             <Directory "/usr/share/doc/">
 409                 Options Indexes MultiViews FollowSymLinks
 410                 AllowOverride None
 411                 Order deny,allow
 412                 Deny from all
 413                 Allow from 127.0.0.0/255.0.0.0 ::1/128
 414             </Directory>
 415
 416                 RewriteEngine On
 417                 RewriteCond %{HTTPS} off
 418                 RewriteRule ^/(.*) https://<server_name>/$1 [L,R]
 419
 420         </VirtualHost>
 421         <VirtualHost *:443>
 422                 ServerName       <server_name>
 423                 ServerAdmin             <admin_mail>
 424                 ServerSignature         On
 425
 426                 SSLEngine on
 427                 SSLCertificateFile      /etc/ssl/certs/example.com.crt
 428                 SSLCertificateChainFile /etc/ssl/certs/example.com.crt
 429                 SSLCertificateKeyFile   /etc/ssl/private/example.com.key
 430
 431                 AddDefaultCharset       UTF-8
 432                 IndexOptions            +Charset=UTF-8
 433
 434                 # Shibboleth configuration
 435                 ShibConfig              /etc/shibboleth/shibboleth2.xml
 436                 Alias                   /shibboleth-sp  /usr/share/shibboleth
 437
 438                 <Location /fod/login>
 439                 AuthType shibboleth
 440                 ShibRequireSession On
 441                 ShibUseHeaders On
 442                 require valid-user
 443             </Location>
 444
 445                 # Shibboleth debugging CGI script
 446                 ScriptAlias /shibboleth/test /usr/lib/cgi-bin/shibtest.cgi
 447                 <Location /shibboleth/test>
 448                         AuthType shibboleth
 449                         ShibRequireSession On
 450                         ShibUseHeaders On
 451                         require valid-user
 452                 </Location>
 453
 454                 <Location /Shibboleth.sso>
 455                         SetHandler shib
 456                 </Location>
 457
 458                 # End of Shibboleth configuration
 459
 460                 <Location /admin/media/>
 461                         SetHandler      None
 462                 </Location>
 463
 464                 Alias /admin/media      /usr/share/pyshared/django/contrib/admin/media
 465                 Alias /media  /usr/share/pyshared/django/contrib/admin/media
 466                         DocumentRoot /var/www
 467                 <Directory /var/www/>
 468                         Options Indexes FollowSymLinks MultiViews
 469                         AllowOverride None
 470                         Order allow,deny
 471                         allow from all
 472                 </Directory>
 473
 474
 475
 476                 <Proxy *>
 477                 Order allow,deny
 478                 Allow from all
 479                 </Proxy>
 480
 481                 SSLProxyEngine        off
 482                 ProxyErrorOverride    off
 483             ProxyTimeout    28800
 484                 ProxyPass        /fod http://localhost:8081/fod retry=0
 485                 ProxyPassReverse /fod http://localhost:8081/fod
 486
 487                 LogLevel warn
 488                 ErrorLog /var/log/apache2/ssl-error.log
 489                 CustomLog /var/log/apache2/ssl-access.log combined
 490
 491
 492
 493
 494                 Alias /fodstatic        /srv/flowspy/static
 495
 496         </VirtualHost>
 497
 498 You are not far away from deploying FoD. When asked for a super user, create one::
 499
 500         cd /srv/flowspy
 501         python manage.py syncdb
 502         python manage.py migrate
 503
 504 Restart, gunicorn and apache::
 505
 506         service gunicorn restart && service apache2 restart
 507
 508 Testing the platform
 509 ====================
 510 Log in to the admin interface via https://<your ip>/fod/admin. Go to Peer ranges and add a new range (part of/or a complete subnet), eg. 83.212.0.0/19
 511 Go to Peers and add a new peer, eg. id: 1, name: Test, AS: 16503, tag: TEST and move the network you have crteated from Avalable to Chosen. From the admin front, go to User, and edit your user. From the bottom of the page, select the TEST peer and save.
 512 Last but not least, modify as required the existing (example.com) Site instance. You are done. As you are logged-n via the admin, there is no need for Shibboleth. Go to https://<your ip>/fod/ and create a new rule. Your rule should be applied on the flowspec capable device after aprox. 10 seconds.
 513
 514 Branding
 515 ========
 516 Via the admin interface you can modify flatpages to suit your needs
 517
 518 Logos
 519 -----
 520 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.
 521
 522 Footer
 523 ------
 524 Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc.
 525
 526 Welcome Page
 527 ------------
 528 Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc.