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
  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-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    cd flowspy
  65         cp settings.py.dist settings.py
  66
  67 Edit settings.py file and set the following according to your configuration::
  68
  69         ADMINS: set your admin name and email (assuming that your server can send notifications)
  70         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
  71         SECRET_KEY : Make this unique, and don't share it with anybody
  72    STATIC_ROOT: /srv/flowspy/static (or your installation directory)
  73         STATIC_URL (static media directory) . If you have followed the above this should be: /srv/flowspy/static
  74         TEMPLATE_DIRS : If you have followed the above this should be: /srv/flowspy/templates
  75         CACHE_BACKEND:  Enable Memcached for production or leave to DummyCache for development environments
  76         Alternatively you could go for redis with the corresponding Django client lib.
  77         NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work). This is the flowspec capable device
  78         NETCONF_USER (enable ssh and netconf on device)
  79         NETCONF_PASS
  80         If beanstalk is selected the following should be left intact.
  81         BROKER_HOST (beanstalk host)
  82         BROKER_PORT (beanstalk port)
  83         SERVER_EMAIL
  84         EMAIL_SUBJECT_PREFIX
  85         If beanstalk is selected the following should be left intact.
  86         BROKER_URL (beanstalk url)
  87         SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication)
  88         NOTIFY_ADMIN_MAILS (bcc mail addresses)
  89         PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS)
  90         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.
  91         PRIMARY_WHOIS
  92         ALTERNATE_WHOIS
  93         If you wish to deploy FoD with Shibboleth change the following attributes according to your setup:
  94         SHIB_AUTH_ENTITLEMENT = 'urn:mace'
  95         SHIB_ADMIN_DOMAIN = 'example.com'
  96         SHIB_LOGOUT_URL = 'https://example.com/Shibboleth.sso/Logout'
  97         SHIB_USERNAME = ['HTTP_EPPN']
  98         SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL']
  99         SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME']
 100         SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME']
 101         SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT']
 102
 103 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::
 104
 105         EMAIL_USE_TLS = True #(or False)
 106         EMAIL_HOST = 'smtp.example.com'
 107         EMAIL_HOST_USER = 'username'
 108         EMAIL_HOST_PASSWORD = 'yourpassword'
 109         EMAIL_PORT = 587 #(outgoing)
 110
 111
 112 .. note::
 113         Soon we will release a version with django-registration as a means to add users and Shibboleth will become an alternative
 114
 115 Let's move on with some copies and dir creations::
 116
 117         cp urls.py.dist urls.py
 118    cd ..
 119         mkdir log
 120         chown -R root:www-data log/
 121         chmod -R g+w log
 122
 123 System configuration
 124 ====================
 125 Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled.
 126 Depending on the setup the apache configuration may vary::
 127
 128         a2enmod rewrite
 129         a2enmod proxy
 130         a2enmod ssl
 131         a2enmod proxy_http
 132
 133 If shibboleth is to be used::
 134
 135         apt-get install libapache2-mod-shib2
 136         a2enmod shib2
 137
 138 Now it is time to configure beanstalk, gunicorn, celery and apache.
 139
 140 beanstalkd
 141 ----------
 142
 143 Enable beanstalk by editting /etc/default/beanstalkd::
 144
 145         vim /etc/default/beanstalkd
 146
 147 Uncomment the line **START=yes** to enable beanstalk
 148
 149 Start beanstalkd::
 150
 151         service beanstalkd start
 152
 153 gunicorn.d
 154 ----------
 155
 156 create and edit /etc/gunicorn.d/fod::
 157
 158         vim /etc/gunicorn.d/fod
 159
 160 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::
 161
 162    CONFIG = {
 163        'mode': 'django',
 164        'working_dir': '/srv/flowspy',
 165        'args': (
 166            '--bind=127.0.0.1:8081',
 167            '--workers=1',
 168            '--worker-class=egg:gunicorn#gevent',
 169            '--timeout=360',
 170            '--log-level=debug',
 171            '--log-file=/tmp/fod.log',
 172        ),
 173    }
 174
 175
 176 celery.d
 177 --------
 178
 179 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.
 180
 181 celeryd requires a /etc/default/celeryd file to be in place.
 182 Thus we are going to create this file (/etc/default/celeryd)::
 183
 184         vim /etc/default/celeryd
 185
 186 Again if the directory conventions have been followed the file is (pay attention to the CELERYD_USER, CELERYD_GROUP and change accordingly)  ::
 187
 188    # Default: false
 189    ENABLED="true"
 190
 191    # Name of nodes to start, here we have a single node
 192    CELERYD_NODES="w1"
 193    # or we could have three nodes:
 194    #CELERYD_NODES="w1 w2 w3"
 195
 196    # Where to chdir at start.
 197    CELERYD_CHDIR="/srv/flowspy"
 198    # How to call "manage.py celeryd_multi"
 199    CELERYD_MULTI="python $CELERYD_CHDIR/manage.py celeryd_multi"
 200
 201    # How to call "manage.py celeryctl"
 202    CELERYCTL="python $CELERYD_CHDIR/manage.py celeryctl"
 203
 204    # Extra arguments to celeryd
 205    #CELERYD_OPTS="--time-limit=300 --concurrency=8"
 206    CELERYD_OPTS="-E -B"
 207    # Name of the celery config module.
 208    CELERY_CONFIG_MODULE="celeryconfig"
 209
 210    # %n will be replaced with the nodename.
 211    CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log"
 212    CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid"
 213
 214    # Workers should run as an unprivileged user.
 215    CELERYD_USER="user"
 216    CELERYD_GROUP="users"
 217
 218    # Name of the projects settings module.
 219    export DJANGO_SETTINGS_MODULE="flowspy.settings"
 220
 221
 222 Apache
 223 ------
 224 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** ::
 225
 226         vim /etc/apache2/sites-available/fod
 227
 228 Again if the directory conventions have been followed the file should be::
 229
 230    <VirtualHost *:80>
 231       ServerAdmin webmaster@localhost
 232       ServerName  fod.example.com
 233       DocumentRoot /var/www
 234
 235       ErrorLog ${APACHE_LOG_DIR}/fod_error.log
 236
 237       # Possible values include: debug, info, notice, warn, error, crit,
 238       # alert, emerg.
 239       LogLevel debug
 240
 241       CustomLog ${APACHE_LOG_DIR}/fod_access.log combined
 242
 243       Alias /static     /srv/flowspy/static
 244        RewriteEngine On
 245        RewriteCond %{HTTPS} off
 246        RewriteRule ^/(.*) https://fod.example.com/$1 [L,R]
 247    </VirtualHost>
 248
 249    <VirtualHost *:443>
 250       ServerName   fod.example.com
 251       ServerAdmin    webmaster@localhost
 252       ServerSignature      On
 253
 254       SSLEngine on
 255       SSLCertificateFile   /etc/ssl/certs/fod.example.com.crt
 256       SSLCertificateChainFile /etc/ssl/certs/example-chain.pem
 257       SSLCertificateKeyFile   /etc/ssl/private/fod.example.com.key
 258
 259       AddDefaultCharset UTF-8
 260       IndexOptions      +Charset=UTF-8
 261
 262       ShibConfig     /etc/shibboleth/shibboleth2.xml
 263       Alias       /shibboleth-sp /usr/share/shibboleth
 264
 265
 266       <Location /login>
 267          AuthType shibboleth
 268          ShibRequireSession On
 269          ShibUseHeaders On
 270          ShibRequestSetting entityID https://idp.example.com/idp/shibboleth
 271          require valid-user
 272       </Location>
 273
 274       # Shibboleth debugging CGI script
 275       ScriptAlias /shibboleth/test /usr/lib/cgi-bin/shibtest.cgi
 276       <Location /shibboleth/test>
 277          AuthType shibboleth
 278          ShibRequireSession On
 279          ShibUseHeaders On
 280          require valid-user
 281       </Location>
 282
 283       <Location /Shibboleth.sso>
 284          SetHandler shib
 285       </Location>
 286
 287       # Shibboleth SP configuration
 288
 289       #SetEnv                proxy-sendchunked
 290
 291           <Proxy *>
 292            Order allow,deny
 293            Allow from all
 294            </Proxy>
 295
 296            SSLProxyEngine        off
 297            ProxyErrorOverride    off
 298        ProxyTimeout    28800
 299          ProxyPass      /static !
 300          ProxyPass       /shibboleth !
 301          ProxyPass      /Shibboleth.sso !
 302
 303            ProxyPass        / http://localhost:8081/ retry=0
 304            ProxyPassReverse / http://localhost:8081/
 305
 306        Alias /static       /srv/flowspy/static
 307
 308       LogLevel warn
 309
 310       ErrorLog ${APACHE_LOG_DIR}/fod_error.log
 311        CustomLog ${APACHE_LOG_DIR}/fod_access.log combined
 312
 313    </VirtualHost>
 314
 315 Now, enable your site. You might want to disable the default site if fod is the only site you host on your server::
 316
 317         a2dissite default
 318         a2ensite fod
 319
 320 You are not far away from deploying FoD. When asked for a super user, create one::
 321
 322         cd /srv/flowspy
 323         python manage.py syncdb
 324         python manage.py migrate
 325
 326 Restart, gunicorn and apache::
 327
 328         service gunicorn restart && service apache2 restart
 329
 330 Testing the platform
 331 ====================
 332 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
 333 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.
 334 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 for Shibboleth. Go to https://<hostname>/ and create a new rule. Your rule should be applied on the flowspec capable device after aprox. 10 seconds.
 335
 336 Branding
 337 ========
 338 Via the admin interface you can modify flatpages to suit your needs
 339
 340 Footer
 341 ------
 342 Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc.
 343
 344 Welcome Page
 345 ------------
 346 Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc.