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

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