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