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

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