Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 075b91de

History | View | Annotate | Download (76 kB)

1
.. _quick-install-admin-guide:
2

    
3
Administrator's Quick Installation Guide
4
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5

    
6
This is the Administrator's quick installation guide.
7

    
8
It describes how to install the whole synnefo stack on two (2) physical nodes,
9
with minimum configuration. It installs synnefo from Debian packages, and
10
assumes the nodes run Debian Squeeze. After successful installation, you will
11
have the following services running:
12

    
13
    * Identity Management (Astakos)
14
    * Object Storage Service (Pithos+)
15
    * Compute Service (Cyclades)
16
    * Image Registry Service (Plankton)
17

    
18
and a single unified Web UI to manage them all.
19

    
20
The Volume Storage Service (Archipelago) and the Billing Service (Aquarium) are
21
not released yet.
22

    
23
If you just want to install the Object Storage Service (Pithos+), follow the
24
guide and just stop after the "Testing of Pithos+" section.
25

    
26

    
27
Installation of Synnefo / Introduction
28
======================================
29

    
30
We will install the services with the above list's order. Cyclades and Plankton
31
will be installed in a single step (at the end), because at the moment they are
32
contained in the same software component. Furthermore, we will install all
33
services in the first physical node, except Pithos+ which will be installed in
34
the second, due to a conflict between the snf-pithos-app and snf-cyclades-app
35
component (scheduled to be fixed in the next version).
36

    
37
For the rest of the documentation we will refer to the first physical node as
38
"node1" and the second as "node2". We will also assume that their domain names
39
are "node1.example.com" and "node2.example.com" and their IPs are "4.3.2.1" and
40
"4.3.2.2" respectively.
41

    
42
.. note:: It is import that the two machines are under the same domain name.
43
    If they are not, you can do this by editting the file ``/etc/hosts``
44
    on both machines, and add the following lines:
45

    
46
    .. code-block:: console
47

    
48
        4.3.2.1     node1.example.com
49
        4.3.2.2     node2.example.com
50

    
51

    
52
General Prerequisites
53
=====================
54

    
55
These are the general synnefo prerequisites, that you need on node1 and node2
56
and are related to all the services (Astakos, Pithos+, Cyclades, Plankton).
57

    
58
To be able to download all synnefo components you need to add the following
59
lines in your ``/etc/apt/sources.list`` file:
60

    
61
| ``deb http://apt2.dev.grnet.gr stable/``
62
| ``deb-src http://apt2.dev.grnet.gr stable/``
63

    
64
and import the repo's GPG key:
65

    
66
| ``curl https://dev.grnet.gr/files/apt-grnetdev.pub | apt-key add -``
67

    
68
Also add the following line to enable the ``squeeze-backports`` repository,
69
which may provide more recent versions of certain packages. The repository
70
is deactivated by default and must be specified expicitly in ``apt-get``
71
operations:
72

    
73
| ``deb http://backports.debian.org/debian-backports squeeze-backports main``
74

    
75
You also need a shared directory visible by both nodes. Pithos+ will save all
76
data inside this directory. By 'all data', we mean files, images, and pithos
77
specific mapping data. If you plan to upload more than one basic image, this
78
directory should have at least 50GB of free space. During this guide, we will
79
assume that node1 acts as an NFS server and serves the directory ``/srv/pithos``
80
to node2 (be sure to set no_root_squash flag). Node2 has this directory
81
mounted under ``/srv/pithos``, too.
82

    
83
Before starting the synnefo installation, you will need basic third party
84
software to be installed and configured on the physical nodes. We will describe
85
each node's general prerequisites separately. Any additional configuration,
86
specific to a synnefo service for each node, will be described at the service's
87
section.
88

    
89
Finally, it is required for Cyclades and Ganeti nodes to have synchronized
90
system clocks (e.g. by running ntpd).
91

    
92
Node1
93
-----
94

    
95
General Synnefo dependencies
96
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97

    
98
    * apache (http server)
99
    * gunicorn (WSGI http server)
100
    * postgresql (database)
101
    * rabbitmq (message queue)
102
    * ntp (NTP daemon)
103
    * gevent
104

    
105
You can install apache2, progresql and ntp by running:
106

    
107
.. code-block:: console
108

    
109
   # apt-get install apache2 postgresql ntp
110

    
111
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
112
the official debian backports:
113

    
114
.. code-block:: console
115

    
116
   # apt-get -t squeeze-backports install gunicorn
117

    
118
Also, make sure to install gevent >= 0.13.6. Again from the debian backports:
119

    
120
.. code-block:: console
121

    
122
   # apt-get -t squeeze-backports install python-gevent
123

    
124
On node1, we will create our databases, so you will also need the
125
python-psycopg2 package:
126

    
127
.. code-block:: console
128

    
129
   # apt-get install python-psycopg2
130

    
131
To install RabbitMQ>=2.8.4, use the RabbitMQ APT repository by adding the
132
following line to ``/etc/apt/sources.list``:
133

    
134
.. code-block:: console
135

    
136
    deb http://www.rabbitmq.com/debian testing main
137

    
138
Add RabbitMQ public key, to trusted key list:
139

    
140
.. code-block:: console
141

    
142
  # wget http://www.rabbitmq.com/rabbitmq-signing-key-public.asc
143
  # apt-key add rabbitmq-signing-key-public.asc
144

    
145
Finally, to install the package run:
146

    
147
.. code-block:: console
148

    
149
  # apt-get update
150
  # apt-get install rabbitmq-server
151

    
152
Database setup
153
~~~~~~~~~~~~~~
154

    
155
On node1, we create a database called ``snf_apps``, that will host all django
156
apps related tables. We also create the user ``synnefo`` and grant him all
157
privileges on the database. We do this by running:
158

    
159
.. code-block:: console
160

    
161
    root@node1:~ # su - postgres
162
    postgres@node1:~ $ psql
163
    postgres=# CREATE DATABASE snf_apps WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
164
    postgres=# CREATE USER synnefo WITH PASSWORD 'example_passw0rd';
165
    postgres=# GRANT ALL PRIVILEGES ON DATABASE snf_apps TO synnefo;
166

    
167
We also create the database ``snf_pithos`` needed by the pithos+ backend and
168
grant the ``synnefo`` user all privileges on the database. This database could
169
be created on node2 instead, but we do it on node1 for simplicity. We will
170
create all needed databases on node1 and then node2 will connect to them.
171

    
172
.. code-block:: console
173

    
174
    postgres=# CREATE DATABASE snf_pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
175
    postgres=# GRANT ALL PRIVILEGES ON DATABASE snf_pithos TO synnefo;
176

    
177
Configure the database to listen to all network interfaces. You can do this by
178
editting the file ``/etc/postgresql/8.4/main/postgresql.conf`` and change
179
``listen_addresses`` to ``'*'`` :
180

    
181
.. code-block:: console
182

    
183
    listen_addresses = '*'
184

    
185
Furthermore, edit ``/etc/postgresql/8.4/main/pg_hba.conf`` to allow node1 and
186
node2 to connect to the database. Add the following lines under ``#IPv4 local
187
connections:`` :
188

    
189
.. code-block:: console
190

    
191
    host		all	all	4.3.2.1/32	md5
192
    host		all	all	4.3.2.2/32	md5
193

    
194
Make sure to substitute "4.3.2.1" and "4.3.2.2" with node1's and node2's
195
actual IPs. Now, restart the server to apply the changes:
196

    
197
.. code-block:: console
198

    
199
   # /etc/init.d/postgresql restart
200

    
201
Gunicorn setup
202
~~~~~~~~~~~~~~
203

    
204
Create the file ``/etc/gunicorn.d/synnefo`` containing the following:
205

    
206
.. code-block:: console
207

    
208
    CONFIG = {
209
     'mode': 'django',
210
     'environment': {
211
       'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
212
     },
213
     'working_dir': '/etc/synnefo',
214
     'user': 'www-data',
215
     'group': 'www-data',
216
     'args': (
217
       '--bind=127.0.0.1:8080',
218
       '--worker-class=gevent',
219
       '--workers=8',
220
       '--log-level=debug',
221
     ),
222
    }
223

    
224
.. warning:: Do NOT start the server yet, because it won't find the
225
    ``synnefo.settings`` module. Also, in case you are using ``/etc/hosts``
226
    instead of a DNS to get the hostnames, change ``--worker-class=gevent`` to
227
    ``--worker-class=sync``. We will start the server after successful
228
    installation of astakos. If the server is running::
229

    
230
       # /etc/init.d/gunicorn stop
231

    
232
Apache2 setup
233
~~~~~~~~~~~~~
234

    
235
Create the file ``/etc/apache2/sites-available/synnefo`` containing the
236
following:
237

    
238
.. code-block:: console
239

    
240
    <VirtualHost *:80>
241
        ServerName node1.example.com
242

    
243
        RewriteEngine On
244
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
245
        RewriteRule ^(.*)$ - [F,L]
246
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
247
    </VirtualHost>
248

    
249
Create the file ``/etc/apache2/sites-available/synnefo-ssl`` containing the
250
following:
251

    
252
.. code-block:: console
253

    
254
    <IfModule mod_ssl.c>
255
    <VirtualHost _default_:443>
256
        ServerName node1.example.com
257

    
258
        Alias /static "/usr/share/synnefo/static"
259

    
260
        #  SetEnv no-gzip
261
        #  SetEnv dont-vary
262

    
263
       AllowEncodedSlashes On
264

    
265
       RequestHeader set X-Forwarded-Protocol "https"
266

    
267
    <Proxy * >
268
        Order allow,deny
269
        Allow from all
270
    </Proxy>
271

    
272
        SetEnv                proxy-sendchunked
273
        SSLProxyEngine        off
274
        ProxyErrorOverride    off
275

    
276
        ProxyPass        /static !
277
        ProxyPass        / http://localhost:8080/ retry=0
278
        ProxyPassReverse / http://localhost:8080/
279

    
280
        RewriteEngine On
281
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
282
        RewriteRule ^(.*)$ - [F,L]
283

    
284
        SSLEngine on
285
        SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
286
        SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
287
    </VirtualHost>
288
    </IfModule>
289

    
290
Now enable sites and modules by running:
291

    
292
.. code-block:: console
293

    
294
   # a2enmod ssl
295
   # a2enmod rewrite
296
   # a2dissite default
297
   # a2ensite synnefo
298
   # a2ensite synnefo-ssl
299
   # a2enmod headers
300
   # a2enmod proxy_http
301

    
302
.. warning:: Do NOT start/restart the server yet. If the server is running::
303

    
304
       # /etc/init.d/apache2 stop
305

    
306
.. _rabbitmq-setup:
307

    
308
Message Queue setup
309
~~~~~~~~~~~~~~~~~~~
310

    
311
The message queue will run on node1, so we need to create the appropriate
312
rabbitmq user. The user is named ``synnefo`` and gets full privileges on all
313
exchanges:
314

    
315
.. code-block:: console
316

    
317
   # rabbitmqctl add_user synnefo "example_rabbitmq_passw0rd"
318
   # rabbitmqctl set_permissions synnefo ".*" ".*" ".*"
319

    
320
We do not need to initialize the exchanges. This will be done automatically,
321
during the Cyclades setup.
322

    
323
Pithos+ data directory setup
324
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
325

    
326
As mentioned in the General Prerequisites section, there is a directory called
327
``/srv/pithos`` visible by both nodes. We create and setup the ``data``
328
directory inside it:
329

    
330
.. code-block:: console
331

    
332
   # cd /srv/pithos
333
   # mkdir data
334
   # chown www-data:www-data data
335
   # chmod g+ws data
336

    
337
You are now ready with all general prerequisites concerning node1. Let's go to
338
node2.
339

    
340
Node2
341
-----
342

    
343
General Synnefo dependencies
344
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345

    
346
    * apache (http server)
347
    * gunicorn (WSGI http server)
348
    * postgresql (database)
349
    * ntp (NTP daemon)
350
    * gevent
351

    
352
You can install the above by running:
353

    
354
.. code-block:: console
355

    
356
   # apt-get install apache2 postgresql ntp
357

    
358
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
359
the official debian backports:
360

    
361
.. code-block:: console
362

    
363
   # apt-get -t squeeze-backports install gunicorn
364

    
365
Also, make sure to install gevent >= 0.13.6. Again from the debian backports:
366

    
367
.. code-block:: console
368

    
369
   # apt-get -t squeeze-backports install python-gevent
370

    
371
Node2 will connect to the databases on node1, so you will also need the
372
python-psycopg2 package:
373

    
374
.. code-block:: console
375

    
376
   # apt-get install python-psycopg2
377

    
378
Database setup
379
~~~~~~~~~~~~~~
380

    
381
All databases have been created and setup on node1, so we do not need to take
382
any action here. From node2, we will just connect to them. When you get familiar
383
with the software you may choose to run different databases on different nodes,
384
for performance/scalability/redundancy reasons, but those kind of setups are out
385
of the purpose of this guide.
386

    
387
Gunicorn setup
388
~~~~~~~~~~~~~~
389

    
390
Create the file ``/etc/gunicorn.d/synnefo`` containing the following
391
(same contents as in node1; you can just copy/paste the file):
392

    
393
.. code-block:: console
394

    
395
    CONFIG = {
396
     'mode': 'django',
397
     'environment': {
398
      'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
399
     },
400
     'working_dir': '/etc/synnefo',
401
     'user': 'www-data',
402
     'group': 'www-data',
403
     'args': (
404
       '--bind=127.0.0.1:8080',
405
       '--worker-class=gevent',
406
       '--workers=4',
407
       '--log-level=debug',
408
       '--timeout=43200'
409
     ),
410
    }
411

    
412
.. warning:: Do NOT start the server yet, because it won't find the
413
    ``synnefo.settings`` module. Also, in case you are using ``/etc/hosts``
414
    instead of a DNS to get the hostnames, change ``--worker-class=gevent`` to
415
    ``--worker-class=sync``. We will start the server after successful
416
    installation of astakos. If the server is running::
417

    
418
       # /etc/init.d/gunicorn stop
419

    
420
Apache2 setup
421
~~~~~~~~~~~~~
422

    
423
Create the file ``/etc/apache2/sites-available/synnefo`` containing the
424
following:
425

    
426
.. code-block:: console
427

    
428
    <VirtualHost *:80>
429
        ServerName node2.example.com
430

    
431
        RewriteEngine On
432
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
433
        RewriteRule ^(.*)$ - [F,L]
434
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
435
    </VirtualHost>
436

    
437
Create the file ``synnefo-ssl`` under ``/etc/apache2/sites-available/``
438
containing the following:
439

    
440
.. code-block:: console
441

    
442
    <IfModule mod_ssl.c>
443
    <VirtualHost _default_:443>
444
        ServerName node2.example.com
445

    
446
        Alias /static "/usr/share/synnefo/static"
447

    
448
        SetEnv no-gzip
449
        SetEnv dont-vary
450
        AllowEncodedSlashes On
451

    
452
        RequestHeader set X-Forwarded-Protocol "https"
453

    
454
        <Proxy * >
455
            Order allow,deny
456
            Allow from all
457
        </Proxy>
458

    
459
        SetEnv                proxy-sendchunked
460
        SSLProxyEngine        off
461
        ProxyErrorOverride    off
462

    
463
        ProxyPass        /static !
464
        ProxyPass        / http://localhost:8080/ retry=0
465
        ProxyPassReverse / http://localhost:8080/
466

    
467
        SSLEngine on
468
        SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
469
        SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
470
    </VirtualHost>
471
    </IfModule>
472

    
473
As in node1, enable sites and modules by running:
474

    
475
.. code-block:: console
476

    
477
   # a2enmod ssl
478
   # a2enmod rewrite
479
   # a2dissite default
480
   # a2ensite synnefo
481
   # a2ensite synnefo-ssl
482
   # a2enmod headers
483
   # a2enmod proxy_http
484

    
485
.. warning:: Do NOT start/restart the server yet. If the server is running::
486

    
487
       # /etc/init.d/apache2 stop
488

    
489
We are now ready with all general prerequisites for node2. Now that we have
490
finished with all general prerequisites for both nodes, we can start installing
491
the services. First, let's install Astakos on node1.
492

    
493

    
494
Installation of Astakos on node1
495
================================
496

    
497
To install astakos, grab the package from our repository (make sure  you made
498
the additions needed in your ``/etc/apt/sources.list`` file, as described
499
previously), by running:
500

    
501
.. code-block:: console
502

    
503
   # apt-get install snf-astakos-app snf-quotaholder-app snf-pithos-backend
504

    
505
After successful installation of snf-astakos-app, make sure that also
506
snf-webproject has been installed (marked as "Recommended" package). By default
507
Debian installs "Recommended" packages, but if you have changed your
508
configuration and the package didn't install automatically, you should
509
explicitly install it manually running:
510

    
511
.. code-block:: console
512

    
513
   # apt-get install snf-webproject
514

    
515
The reason snf-webproject is "Recommended" and not a hard dependency, is to give
516
the experienced administrator the ability to install Synnefo in a custom made
517
`Django <https://www.djangoproject.com/>`_ project. This corner case
518
concerns only very advanced users that know what they are doing and want to
519
experiment with synnefo.
520

    
521

    
522
.. _conf-astakos:
523

    
524
Configuration of Astakos
525
========================
526

    
527
Conf Files
528
----------
529

    
530
After astakos is successfully installed, you will find the directory
531
``/etc/synnefo`` and some configuration files inside it. The files contain
532
commented configuration options, which are the default options. While installing
533
new snf-* components, new configuration files will appear inside the directory.
534
In this guide (and for all services), we will edit only the minimum necessary
535
configuration options, to reflect our setup. Everything else will remain as is.
536

    
537
After getting familiar with synnefo, you will be able to customize the software
538
as you wish and fits your needs. Many options are available, to empower the
539
administrator with extensively customizable setups.
540

    
541
For the snf-webproject component (installed as an astakos dependency), we
542
need the following:
543

    
544
Edit ``/etc/synnefo/10-snf-webproject-database.conf``. You will need to
545
uncomment and edit the ``DATABASES`` block to reflect our database:
546

    
547
.. code-block:: console
548

    
549
    DATABASES = {
550
     'default': {
551
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
552
         'ENGINE': 'postgresql_psycopg2',
553
         # ATTENTION: This *must* be the absolute path if using sqlite3.
554
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
555
         'NAME': 'snf_apps',
556
         'USER': 'synnefo',                      # Not used with sqlite3.
557
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
558
         # Set to empty string for localhost. Not used with sqlite3.
559
         'HOST': '4.3.2.1',
560
         # Set to empty string for default. Not used with sqlite3.
561
         'PORT': '5432',
562
     }
563
    }
564

    
565
Edit ``/etc/synnefo/10-snf-webproject-deploy.conf``. Uncomment and edit
566
``SECRET_KEY``. This is a Django specific setting which is used to provide a
567
seed in secret-key hashing algorithms. Set this to a random string of your
568
choise and keep it private:
569

    
570
.. code-block:: console
571

    
572
    SECRET_KEY = 'sy6)mw6a7x%n)-example_secret_key#zzk4jo6f2=uqu!1o%)'
573

    
574
For astakos specific configuration, edit the following options in
575
``/etc/synnefo/20-snf-astakos-app-settings.conf`` :
576

    
577
.. code-block:: console
578

    
579
    ASTAKOS_DEFAULT_ADMIN_EMAIL = None
580

    
581
    ASTAKOS_COOKIE_DOMAIN = '.example.com'
582

    
583
    ASTAKOS_BASEURL = 'https://node1.example.com'
584

    
585
The ``ASTAKOS_COOKIE_DOMAIN`` should be the base url of our domain (for all
586
services). ``ASTAKOS_BASEURL`` is the astakos home page.
587

    
588
``ASTAKOS_DEFAULT_ADMIN_EMAIL`` refers to the administrator's email.
589
Every time a new account is created a notification is sent to this email.
590
For this we need access to a running mail server, so we have disabled
591
it for now by setting its value to None. For more informations on this,
592
read the relative :ref:`section <mail-server>`.
593

    
594
.. note:: For the purpose of this guide, we don't enable recaptcha authentication.
595
    If you would like to enable it, you have to edit the following options:
596

    
597
    .. code-block:: console
598

    
599
        ASTAKOS_RECAPTCHA_PUBLIC_KEY = 'example_recaptcha_public_key!@#$%^&*('
600
        ASTAKOS_RECAPTCHA_PRIVATE_KEY = 'example_recaptcha_private_key!@#$%^&*('
601
        ASTAKOS_RECAPTCHA_USE_SSL = True
602
        ASTAKOS_RECAPTCHA_ENABLED = True
603

    
604
    For the ``ASTAKOS_RECAPTCHA_PUBLIC_KEY`` and ``ASTAKOS_RECAPTCHA_PRIVATE_KEY``
605
    go to https://www.google.com/recaptcha/admin/create and create your own pair.
606

    
607
Then edit ``/etc/synnefo/20-snf-astakos-app-cloudbar.conf`` :
608

    
609
.. code-block:: console
610

    
611
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
612

    
613
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/api/get_services'
614

    
615
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/api/get_menu'
616

    
617
Those settings have to do with the black cloudbar endpoints and will be
618
described in more detail later on in this guide. For now, just edit the domain
619
to point at node1 which is where we have installed Astakos.
620

    
621
If you are an advanced user and want to use the Shibboleth Authentication
622
method, read the relative :ref:`section <shibboleth-auth>`.
623

    
624
.. note:: Because Cyclades and Astakos are running on the same machine
625
    in our example, we have to deactivate the CSRF verification. We can do so
626
    by adding to
627
    ``/etc/synnefo/99-local.conf``:
628

    
629
    .. code-block:: console
630

    
631
        MIDDLEWARE_CLASSES.remove('django.middleware.csrf.CsrfViewMiddleware')
632
        TEMPLATE_CONTEXT_PROCESSORS.remove('django.core.context_processors.csrf')
633

    
634
Since version 0.13 you need to configure some basic settings for the new *Quota*
635
feature.
636

    
637
Specifically:
638

    
639
Edit ``/etc/synnefo/20-snf-astakos-app-settings.conf``:
640

    
641
.. code-block:: console
642

    
643
    QUOTAHOLDER_URL = 'https://node1.example.com/quotaholder/v'
644
    QUOTAHOLDER_TOKEN = 'aExampleTokenJbFm12w'
645
    ASTAKOS_QUOTAHOLDER_TOKEN = 'aExampleTokenJbFm12w'
646
    ASTAKOS_QUOTAHOLDER_URL = 'https://node1.example.com/quotaholder/v'
647

    
648
Enable Pooling
649
--------------
650

    
651
This section can be bypassed, but we strongly recommend you apply the following,
652
since they result in a significant performance boost.
653

    
654
Synnefo includes a pooling DBAPI driver for PostgreSQL, as a thin wrapper
655
around Psycopg2. This allows independent Django requests to reuse pooled DB
656
connections, with significant performance gains.
657

    
658
To use, first monkey-patch psycopg2. For Django, run this before the
659
``DATABASES`` setting in ``/etc/synnefo/10-snf-webproject-database.conf``:
660

    
661
.. code-block:: console
662

    
663
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
664
    monkey_patch_psycopg2()
665

    
666
Since we are running with greenlets, we should modify psycopg2 behavior, so it
667
works properly in a greenlet context:
668

    
669
.. code-block:: console
670

    
671
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
672
    make_psycopg_green()
673

    
674
Use the Psycopg2 driver as usual. For Django, this means using
675
``django.db.backends.postgresql_psycopg2`` without any modifications. To enable
676
connection pooling, pass a nonzero ``synnefo_poolsize`` option to the DBAPI
677
driver, through ``DATABASES.OPTIONS`` in Django.
678

    
679
All the above will result in an ``/etc/synnefo/10-snf-webproject-database.conf``
680
file that looks like this:
681

    
682
.. code-block:: console
683

    
684
    # Monkey-patch psycopg2
685
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
686
    monkey_patch_psycopg2()
687

    
688
    # If running with greenlets
689
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
690
    make_psycopg_green()
691

    
692
    DATABASES = {
693
     'default': {
694
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
695
         'ENGINE': 'postgresql_psycopg2',
696
         'OPTIONS': {'synnefo_poolsize': 8},
697

    
698
         # ATTENTION: This *must* be the absolute path if using sqlite3.
699
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
700
         'NAME': 'snf_apps',
701
         'USER': 'synnefo',                      # Not used with sqlite3.
702
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
703
         # Set to empty string for localhost. Not used with sqlite3.
704
         'HOST': '4.3.2.1',
705
         # Set to empty string for default. Not used with sqlite3.
706
         'PORT': '5432',
707
     }
708
    }
709

    
710
Database Initialization
711
-----------------------
712

    
713
After configuration is done, we initialize the database by running:
714

    
715
.. code-block:: console
716

    
717
    # snf-manage syncdb
718

    
719
At this example we don't need to create a django superuser, so we select
720
``[no]`` to the question. After a successful sync, we run the migration needed
721
for astakos:
722

    
723
.. code-block:: console
724

    
725
    # snf-manage migrate im
726

    
727
Then, we load the pre-defined user groups
728

    
729
.. code-block:: console
730

    
731
    # snf-manage loaddata groups
732

    
733
.. _services-reg:
734

    
735
Services Registration
736
---------------------
737

    
738
When the database is ready, we configure the elements of the Astakos cloudbar,
739
to point to our future services:
740

    
741
.. code-block:: console
742

    
743
    # snf-manage service-add "~okeanos home" https://node1.example.com/im/ home-icon.png
744
    # snf-manage service-add "cyclades" https://node1.example.com/ui/
745
    # snf-manage service-add "pithos+" https://node2.example.com/ui/
746

    
747
Servers Initialization
748
----------------------
749

    
750
Finally, we initialize the servers on node1:
751

    
752
.. code-block:: console
753

    
754
    root@node1:~ # /etc/init.d/gunicorn restart
755
    root@node1:~ # /etc/init.d/apache2 restart
756

    
757
We have now finished the Astakos setup. Let's test it now.
758

    
759

    
760
Testing of Astakos
761
==================
762

    
763
Open your favorite browser and go to:
764

    
765
``http://node1.example.com/im``
766

    
767
If this redirects you to ``https://node1.example.com/im/`` and you can see
768
the "welcome" door of Astakos, then you have successfully setup Astakos.
769

    
770
Let's create our first user. At the homepage click the "CREATE ACCOUNT" button
771
and fill all your data at the sign up form. Then click "SUBMIT". You should now
772
see a green box on the top, which informs you that you made a successful request
773
and the request has been sent to the administrators. So far so good, let's
774
assume that you created the user with username ``user@example.com``.
775

    
776
Now we need to activate that user. Return to a command prompt at node1 and run:
777

    
778
.. code-block:: console
779

    
780
    root@node1:~ # snf-manage user-list
781

    
782
This command should show you a list with only one user; the one we just created.
783
This user should have an id with a value of ``1``. It should also have an
784
"active" status with the value of ``0`` (inactive). Now run:
785

    
786
.. code-block:: console
787

    
788
    root@node1:~ # snf-manage user-update --set-active 1
789

    
790
This modifies the active value to ``1``, and actually activates the user.
791
When running in production, the activation is done automatically with different
792
types of moderation, that Astakos supports. You can see the moderation methods
793
(by invitation, whitelists, matching regexp, etc.) at the Astakos specific
794
documentation. In production, you can also manually activate a user, by sending
795
him/her an activation email. See how to do this at the :ref:`User
796
activation <user_activation>` section.
797

    
798
Now let's go back to the homepage. Open ``http://node1.example.com/im/`` with
799
your browser again. Try to sign in using your new credentials. If the astakos
800
menu appears and you can see your profile, then you have successfully setup
801
Astakos.
802

    
803
Let's continue to install Pithos+ now.
804

    
805

    
806
Installation of Pithos+ on node2
807
================================
808

    
809
To install pithos+, grab the packages from our repository (make sure  you made
810
the additions needed in your ``/etc/apt/sources.list`` file, as described
811
previously), by running:
812

    
813
.. code-block:: console
814

    
815
   # apt-get install snf-pithos-app snf-pithos-backend
816

    
817
After successful installation of snf-pithos-app, make sure that also
818
snf-webproject has been installed (marked as "Recommended" package). Refer to
819
the "Installation of Astakos on node1" section, if you don't remember why this
820
should happen. Now, install the pithos web interface:
821

    
822
.. code-block:: console
823

    
824
   # apt-get install snf-pithos-webclient
825

    
826
This package provides the standalone pithos web client. The web client is the
827
web UI for pithos+ and will be accessible by clicking "pithos+" on the Astakos
828
interface's cloudbar, at the top of the Astakos homepage.
829

    
830

    
831
.. _conf-pithos:
832

    
833
Configuration of Pithos+
834
========================
835

    
836
Conf Files
837
----------
838

    
839
After pithos+ is successfully installed, you will find the directory
840
``/etc/synnefo`` and some configuration files inside it, as you did in node1
841
after installation of astakos. Here, you will not have to change anything that
842
has to do with snf-common or snf-webproject. Everything is set at node1. You
843
only need to change settings that have to do with pithos+. Specifically:
844

    
845
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
846
this options:
847

    
848
.. code-block:: console
849

    
850
   ASTAKOS_URL = 'https://node1.example.com/'
851

    
852
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
853
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
854

    
855

    
856
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w=='
857

    
858
   PITHOS_QUOTAHOLDER_URL = 'https://node1.example.com/quotaholder/v'
859
   PITHOS_QUOTAHOLDER_TOKEN = 'aExampleTokenJbFm12w'
860
   PITHOS_USE_QUOTAHOLDER = True
861

    
862
   # Set to False if astakos & pithos are on the same host
863
   #PITHOS_PROXY_USER_SERVICES = True
864

    
865

    
866
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the pithos+ app where to
867
find the pithos+ backend database. Above we tell pithos+ that its database is
868
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
869
``example_passw0rd``.  All those settings where setup during node1's "Database
870
setup" section.
871

    
872
The ``PITHOS_BACKEND_BLOCK_PATH`` option tells to the pithos+ app where to find
873
the pithos+ backend data. Above we tell pithos+ to store its data under
874
``/srv/pithos/data``, which is visible by both nodes. We have already setup this
875
directory at node1's "Pithos+ data directory setup" section.
876

    
877
The ``ASTAKOS_URL`` option tells to the pithos+ app in which URI
878
is available the astakos authentication api.
879

    
880
The ``PITHOS_SERVICE_TOKEN`` should be the Pithos+ token returned by running on
881
the Astakos node (node1 in our case):
882

    
883
.. code-block:: console
884

    
885
   # snf-manage service-list
886

    
887
The token has been generated automatically during the :ref:`Pithos+ service
888
registration <services-reg>`.
889

    
890
Then we need to setup the web UI and connect it to astakos. To do so, edit
891
``/etc/synnefo/20-snf-pithos-webclient-settings.conf``:
892

    
893
.. code-block:: console
894

    
895
    PITHOS_UI_LOGIN_URL = "https://node1.example.com/im/login?next="
896
    PITHOS_UI_FEEDBACK_URL = "https://node2.example.com/feedback"
897

    
898
The ``PITHOS_UI_LOGIN_URL`` option tells the client where to redirect you, if
899
you are not logged in. The ``PITHOS_UI_FEEDBACK_URL`` option points at the
900
pithos+ feedback form. Astakos already provides a generic feedback form for all
901
services, so we use this one.
902

    
903
The ``PITHOS_UPDATE_MD5`` option by default disables the computation of the
904
object checksums. This results to improved performance during object uploading.
905
However, if compatibility with the OpenStack Object Storage API is important
906
then it should be changed to ``True``.
907

    
908
Then edit ``/etc/synnefo/20-snf-pithos-webclient-cloudbar.conf``, to connect the
909
pithos+ web UI with the astakos web UI (through the top cloudbar):
910

    
911
.. code-block:: console
912

    
913
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
914
    PITHOS_UI_CLOUDBAR_ACTIVE_SERVICE = '3'
915
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/api/get_services'
916
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/api/get_menu'
917

    
918
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
919
cloudbar.
920

    
921
The ``PITHOS_UI_CLOUDBAR_ACTIVE_SERVICE`` points to an already registered
922
Astakos service. You can see all :ref:`registered services <services-reg>` by
923
running on the Astakos node (node1):
924

    
925
.. code-block:: console
926

    
927
   # snf-manage service-list
928

    
929
The value of ``PITHOS_UI_CLOUDBAR_ACTIVE_SERVICE`` should be the pithos
930
service's ``id`` as shown by the above command, in our case ``3``.
931

    
932
The ``CLOUDBAR_SERVICES_URL`` and ``CLOUDBAR_MENU_URL`` options are used by the
933
pithos+ web client to get from astakos all the information needed to fill its
934
own cloudbar. So we put our astakos deployment urls there.
935

    
936
Pooling and Greenlets
937
---------------------
938

    
939
Pithos is pooling-ready without the need of further configuration, because it
940
doesn't use a Django DB. It pools HTTP connections to Astakos and pithos
941
backend objects for access to the Pithos DB.
942

    
943
However, as in Astakos, since we are running with Greenlets, it is also
944
recommended to modify psycopg2 behavior so it works properly in a greenlet
945
context. This means adding the following lines at the top of your
946
``/etc/synnefo/10-snf-webproject-database.conf`` file:
947

    
948
.. code-block:: console
949

    
950
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
951
    make_psycopg_green()
952

    
953
Furthermore, add the ``--worker-class=gevent`` (or ``--worker-class=sync`` as
954
mentioned above, depending on your setup) argument on your
955
``/etc/gunicorn.d/synnefo`` configuration file. The file should look something
956
like this:
957

    
958
.. code-block:: console
959

    
960
    CONFIG = {
961
     'mode': 'django',
962
     'environment': {
963
       'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
964
     },
965
     'working_dir': '/etc/synnefo',
966
     'user': 'www-data',
967
     'group': 'www-data',
968
     'args': (
969
       '--bind=127.0.0.1:8080',
970
       '--workers=4',
971
       '--worker-class=gevent',
972
       '--log-level=debug',
973
       '--timeout=43200'
974
     ),
975
    }
976

    
977
Stamp Database Revision
978
-----------------------
979

    
980
Pithos uses the alembic_ database migrations tool.
981

    
982
.. _alembic: http://alembic.readthedocs.org
983

    
984
After a sucessful installation, we should stamp it at the most recent
985
revision, so that future migrations know where to start upgrading in
986
the migration history.
987

    
988
First, find the most recent revision in the migration history:
989

    
990
.. code-block:: console
991

    
992
    root@node2:~ # pithos-migrate history
993
    2a309a9a3438 -> 27381099d477 (head), alter public add column url
994
    165ba3fbfe53 -> 2a309a9a3438, fix statistics negative population
995
    3dd56e750a3 -> 165ba3fbfe53, update account in paths
996
    230f8ce9c90f -> 3dd56e750a3, Fix latest_version
997
    8320b1c62d9 -> 230f8ce9c90f, alter nodes add column latest version
998
    None -> 8320b1c62d9, create index nodes.parent
999

    
1000
Finally, we stamp it with the one found in the previous step:
1001

    
1002
.. code-block:: console
1003

    
1004
    root@node2:~ # pithos-migrate stamp 27381099d477
1005

    
1006
Servers Initialization
1007
----------------------
1008

    
1009
After configuration is done, we initialize the servers on node2:
1010

    
1011
.. code-block:: console
1012

    
1013
    root@node2:~ # /etc/init.d/gunicorn restart
1014
    root@node2:~ # /etc/init.d/apache2 restart
1015

    
1016
You have now finished the Pithos+ setup. Let's test it now.
1017

    
1018

    
1019
Testing of Pithos+
1020
==================
1021

    
1022
Open your browser and go to the Astakos homepage:
1023

    
1024
``http://node1.example.com/im``
1025

    
1026
Login, and you will see your profile page. Now, click the "pithos+" link on the
1027
top black cloudbar. If everything was setup correctly, this will redirect you
1028
to:
1029

    
1030

    
1031
and you will see the blue interface of the Pithos+ application.  Click the
1032
orange "Upload" button and upload your first file. If the file gets uploaded
1033
successfully, then this is your first sign of a successful Pithos+ installation.
1034
Go ahead and experiment with the interface to make sure everything works
1035
correctly.
1036

    
1037
You can also use the Pithos+ clients to sync data from your Windows PC or MAC.
1038

    
1039
If you don't stumble on any problems, then you have successfully installed
1040
Pithos+, which you can use as a standalone File Storage Service.
1041

    
1042
If you would like to do more, such as:
1043

    
1044
    * Spawning VMs
1045
    * Spawning VMs from Images stored on Pithos+
1046
    * Uploading your custom Images to Pithos+
1047
    * Spawning VMs from those custom Images
1048
    * Registering existing Pithos+ files as Images
1049
    * Connect VMs to the Internet
1050
    * Create Private Networks
1051
    * Add VMs to Private Networks
1052

    
1053
please continue with the rest of the guide.
1054

    
1055

    
1056
Cyclades (and Plankton) Prerequisites
1057
=====================================
1058

    
1059
Before proceeding with the Cyclades (and Plankton) installation, make sure you
1060
have successfully set up Astakos and Pithos+ first, because Cyclades depends
1061
on them. If you don't have a working Astakos and Pithos+ installation yet,
1062
please return to the :ref:`top <quick-install-admin-guide>` of this guide.
1063

    
1064
Besides Astakos and Pithos+, you will also need a number of additional working
1065
prerequisites, before you start the Cyclades installation.
1066

    
1067
Ganeti
1068
------
1069

    
1070
`Ganeti <http://code.google.com/p/ganeti/>`_ handles the low level VM management
1071
for Cyclades, so Cyclades requires a working Ganeti installation at the backend.
1072
Please refer to the
1073
`ganeti documentation <http://docs.ganeti.org/ganeti/2.5/html>`_ for all the
1074
gory details. A successful Ganeti installation concludes with a working
1075
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs
1076
<GANETI_NODES>`.
1077

    
1078
The above Ganeti cluster can run on different physical machines than node1 and
1079
node2 and can scale independently, according to your needs.
1080

    
1081
For the purpose of this guide, we will assume that the :ref:`GANETI-MASTER
1082
<GANETI_NODES>` runs on node1 and is VM-capable. Also, node2 is a
1083
:ref:`GANETI-NODE <GANETI_NODES>` and is Master-capable and VM-capable too.
1084

    
1085
We highly recommend that you read the official Ganeti documentation, if you are
1086
not familiar with Ganeti.
1087

    
1088
Unfortunatelly, the current stable version of the stock Ganeti (v2.6.2) doesn't
1089
support IP pool management. This feature will be available in Ganeti >= 2.7.
1090
Synnefo depends on the IP pool functionality of Ganeti, so you have to use
1091
GRNET provided packages until stable 2.7 is out. To do so:
1092

    
1093
.. code-block:: console
1094

    
1095
   # apt-get install snf-ganeti ganeti-htools
1096
   # rmmod -f drbd && modprobe drbd minor_count=255 usermode_helper=/bin/true
1097

    
1098
You should have:
1099

    
1100
Ganeti >= 2.6.2+ippool11+hotplug5+extstorage3+rdbfix1+kvmfix2-1
1101

    
1102
We assume that Ganeti will use the KVM hypervisor. After installing Ganeti on
1103
both nodes, choose a domain name that resolves to a valid floating IP (let's
1104
say it's ``ganeti.node1.example.com``). Make sure node1 and node2 have same
1105
dsa/rsa keys and authorised_keys for password-less root ssh between each other.
1106
If not then skip passing --no-ssh-init but be aware that it will replace
1107
/root/.ssh/* related files and you might lose access to master node. Also,
1108
make sure there is an lvm volume group named ``ganeti`` that will host your
1109
VMs' disks. Finally, setup a bridge interface on the host machines (e.g: br0).
1110
Then run on node1:
1111

    
1112
.. code-block:: console
1113

    
1114
    root@node1:~ # gnt-cluster init --enabled-hypervisors=kvm --no-ssh-init \
1115
                    --no-etc-hosts --vg-name=ganeti --nic-parameters link=br0 \
1116
                    --master-netdev eth0 ganeti.node1.example.com
1117
    root@node1:~ # gnt-cluster modify --default-iallocator hail
1118
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:kernel_path=
1119
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:vnc_bind_address=0.0.0.0
1120

    
1121
    root@node1:~ # gnt-node add --no-ssh-key-check --master-capable=yes \
1122
                    --vm-capable=yes node2.example.com
1123
    root@node1:~ # gnt-cluster modify --disk-parameters=drbd:metavg=ganeti
1124
    root@node1:~ # gnt-group modify --disk-parameters=drbd:metavg=ganeti default
1125

    
1126
For any problems you may stumble upon installing Ganeti, please refer to the
1127
`official documentation <http://docs.ganeti.org/ganeti/2.5/html>`_. Installation
1128
of Ganeti is out of the scope of this guide.
1129

    
1130
.. _cyclades-install-snfimage:
1131

    
1132
snf-image
1133
---------
1134

    
1135
Installation
1136
~~~~~~~~~~~~
1137
For :ref:`Cyclades <cyclades>` to be able to launch VMs from specified Images,
1138
you need the :ref:`snf-image <snf-image>` OS Definition installed on *all*
1139
VM-capable Ganeti nodes. This means we need :ref:`snf-image <snf-image>` on
1140
node1 and node2. You can do this by running on *both* nodes:
1141

    
1142
.. code-block:: console
1143

    
1144
   # apt-get install snf-image snf-pithos-backend python-psycopg2
1145

    
1146
snf-image also needs the `snf-pithos-backend <snf-pithos-backend>`, to be able
1147
to handle image files stored on Pithos+. It also needs `python-psycopg2` to be
1148
able to access the Pithos+ database. This is why, we also install them on *all*
1149
VM-capable Ganeti nodes.
1150

    
1151
.. warning:: snf-image uses ``curl`` for handling URLs. This means that it will
1152
    not  work out of the box if you try to use URLs served by servers which do
1153
    not have a valid certificate. To circumvent this you should edit the file
1154
    ``/etc/default/snf-image``. Change ``#CURL="curl"`` to ``CURL="curl -k"``.
1155

    
1156
After `snf-image` has been installed successfully, create the helper VM by
1157
running on *both* nodes:
1158

    
1159
.. code-block:: console
1160

    
1161
   # snf-image-update-helper
1162

    
1163
This will create all the needed files under ``/var/lib/snf-image/helper/`` for
1164
snf-image to run successfully, and it may take a few minutes depending on your
1165
Internet connection.
1166

    
1167
Configuration
1168
~~~~~~~~~~~~~
1169
snf-image supports native access to Images stored on Pithos+. This means that
1170
it can talk directly to the Pithos+ backend, without the need of providing a
1171
public URL. More details, are described in the next section. For now, the only
1172
thing we need to do, is configure snf-image to access our Pithos+ backend.
1173

    
1174
To do this, we need to set the corresponding variables in
1175
``/etc/default/snf-image``, to reflect our Pithos+ setup:
1176

    
1177
.. code-block:: console
1178

    
1179
    PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
1180

    
1181
    PITHOS_DATA="/srv/pithos/data"
1182

    
1183
If you have installed your Ganeti cluster on different nodes than node1 and
1184
node2 make sure that ``/srv/pithos/data`` is visible by all of them.
1185

    
1186
If you would like to use Images that are also/only stored locally, you need to
1187
save them under ``IMAGE_DIR``, however this guide targets Images stored only on
1188
Pithos+.
1189

    
1190
Testing
1191
~~~~~~~
1192
You can test that snf-image is successfully installed by running on the
1193
:ref:`GANETI-MASTER <GANETI_NODES>` (in our case node1):
1194

    
1195
.. code-block:: console
1196

    
1197
   # gnt-os diagnose
1198

    
1199
This should return ``valid`` for snf-image.
1200

    
1201
If you are interested to learn more about snf-image's internals (and even use
1202
it alongside Ganeti without Synnefo), please see
1203
`here <https://code.grnet.gr/projects/snf-image/wiki>`_ for information
1204
concerning installation instructions, documentation on the design and
1205
implementation, and supported Image formats.
1206

    
1207
.. _snf-image-images:
1208

    
1209
Actual Images for snf-image
1210
---------------------------
1211

    
1212
Now that snf-image is installed successfully we need to provide it with some
1213
Images. :ref:`snf-image <snf-image>` supports Images stored in ``extdump``,
1214
``ntfsdump`` or ``diskdump`` format. We recommend the use of the ``diskdump``
1215
format. For more information about snf-image Image formats see `here
1216
<https://code.grnet.gr/projects/snf-image/wiki/Image_Format>`_.
1217

    
1218
:ref:`snf-image <snf-image>` also supports three (3) different locations for the
1219
above Images to be stored:
1220

    
1221
    * Under a local folder (usually an NFS mount, configurable as ``IMAGE_DIR``
1222
      in :file:`/etc/default/snf-image`)
1223
    * On a remote host (accessible via public URL e.g: http://... or ftp://...)
1224
    * On Pithos+ (accessible natively, not only by its public URL)
1225

    
1226
For the purpose of this guide, we will use the Debian Squeeze Base Image found
1227
on the official `snf-image page
1228
<https://code.grnet.gr/projects/snf-image/wiki#Sample-Images>`_. The image is
1229
of type ``diskdump``. We will store it in our new Pithos+ installation.
1230

    
1231
To do so, do the following:
1232

    
1233
a) Download the Image from the official snf-image page.
1234

    
1235
b) Upload the Image to your Pithos+ installation, either using the Pithos+ Web
1236
   UI or the command line client `kamaki
1237
   <http://www.synnefo.org/docs/kamaki/latest/index.html>`_.
1238

    
1239
Once the Image is uploaded successfully, download the Image's metadata file
1240
from the official snf-image page. You will need it, for spawning a VM from
1241
Ganeti, in the next section.
1242

    
1243
Of course, you can repeat the procedure to upload more Images, available from
1244
the `official snf-image page
1245
<https://code.grnet.gr/projects/snf-image/wiki#Sample-Images>`_.
1246

    
1247
.. _ganeti-with-pithos-images:
1248

    
1249
Spawning a VM from a Pithos+ Image, using Ganeti
1250
------------------------------------------------
1251

    
1252
Now, it is time to test our installation so far. So, we have Astakos and
1253
Pithos+ installed, we have a working Ganeti installation, the snf-image
1254
definition installed on all VM-capable nodes and a Debian Squeeze Image on
1255
Pithos+. Make sure you also have the `metadata file
1256
<https://pithos.okeanos.grnet.gr/public/gwqcv>`_ for this image.
1257

    
1258
Run on the :ref:`GANETI-MASTER's <GANETI_NODES>` (node1) command line:
1259

    
1260
.. code-block:: console
1261

    
1262
   # gnt-instance add -o snf-image+default --os-parameters \
1263
                      img_passwd=my_vm_example_passw0rd,img_format=diskdump,img_id="pithos://UUID/pithos/debian_base-6.0-7-x86_64.diskdump",img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' \
1264
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1265
                      testvm1
1266

    
1267
In the above command:
1268

    
1269
 * ``img_passwd``: the arbitrary root password of your new instance
1270
 * ``img_format``: set to ``diskdump`` to reflect the type of the uploaded Image
1271
 * ``img_id``: If you want to deploy an Image stored on Pithos+ (our case), this
1272
               should have the format ``pithos://<UUID>/<container>/<filename>``:
1273
               * ``username``: ``user@example.com`` (defined during Astakos sign up)
1274
               * ``container``: ``pithos`` (default, if the Web UI was used)
1275
               * ``filename``: the name of file (visible also from the Web UI)
1276
 * ``img_properties``: taken from the metadata file. Used only the two mandatory
1277
                       properties ``OSFAMILY`` and ``ROOT_PARTITION``. `Learn more
1278
                       <https://code.grnet.gr/projects/snf-image/wiki/Image_Format#Image-Properties>`_
1279

    
1280
If the ``gnt-instance add`` command returns successfully, then run:
1281

    
1282
.. code-block:: console
1283

    
1284
   # gnt-instance info testvm1 | grep "console connection"
1285

    
1286
to find out where to connect using VNC. If you can connect successfully and can
1287
login to your new instance using the root password ``my_vm_example_passw0rd``,
1288
then everything works as expected and you have your new Debian Base VM up and
1289
running.
1290

    
1291
If ``gnt-instance add`` fails, make sure that snf-image is correctly configured
1292
to access the Pithos+ database and the Pithos+ backend data (newer versions
1293
require UUID instead of a username). Another issue you may encounter is that in
1294
relatively slow setups, you may need to raise the default HELPER_*_TIMEOUTS in
1295
/etc/default/snf-image. Also, make sure you gave the correct ``img_id`` and
1296
``img_properties``. If ``gnt-instance add`` succeeds but you cannot connect,
1297
again find out what went wrong. Do *NOT* proceed to the next steps unless you
1298
are sure everything works till this point.
1299

    
1300
If everything works, you have successfully connected Ganeti with Pithos+. Let's
1301
move on to networking now.
1302

    
1303
.. warning::
1304

    
1305
    You can bypass the networking sections and go straight to
1306
    :ref:`Cyclades Ganeti tools <cyclades-gtools>`, if you do not want to setup
1307
    the Cyclades Network Service, but only the Cyclades Compute Service
1308
    (recommended for now).
1309

    
1310
Networking Setup Overview
1311
-------------------------
1312

    
1313
This part is deployment-specific and must be customized based on the specific
1314
needs of the system administrator. However, to do so, the administrator needs
1315
to understand how each level handles Virtual Networks, to be able to setup the
1316
backend appropriately, before installing Cyclades. To do so, please read the
1317
:ref:`Network <networks>` section before proceeding.
1318

    
1319
Since synnefo 0.11 all network actions are managed with the snf-manage
1320
network-* commands. This needs the underlying setup (Ganeti, nfdhcpd,
1321
snf-network, bridges, vlans) to be already configured correctly. The only
1322
actions needed in this point are:
1323

    
1324
a) Have Ganeti with IP pool management support installed.
1325

    
1326
b) Install :ref:`snf-network <snf-network>`, which provides a synnefo specific kvm-ifup script, etc.
1327

    
1328
c) Install :ref:`nfdhcpd <nfdhcpd>`, which serves DHCP requests of the VMs.
1329

    
1330
In order to test that everything is setup correctly before installing Cyclades,
1331
we will make some testing actions in this section, and the actual setup will be
1332
done afterwards with snf-manage commands.
1333

    
1334
.. _snf-network:
1335

    
1336
snf-network
1337
~~~~~~~~~~~
1338

    
1339
snf-network includes `kvm-vif-bridge` script that is invoked every time
1340
a tap (a VM's NIC) is created. Based on environment variables passed by
1341
Ganeti it issues various commands depending on the network type the NIC is
1342
connected to and sets up a corresponding dhcp lease.
1343

    
1344
Install snf-network on all Ganeti nodes:
1345

    
1346
.. code-block:: console
1347

    
1348
   # apt-get install snf-network
1349

    
1350
Then, in :file:`/etc/default/snf-network` set:
1351

    
1352
.. code-block:: console
1353

    
1354
   MAC_MASK=ff:ff:f0:00:00:00
1355

    
1356
.. _nfdhcpd:
1357

    
1358
nfdhcpd
1359
~~~~~~~
1360

    
1361
Each NIC's IP is chosen by Ganeti (with IP pool management support).
1362
`kvm-vif-bridge` script sets up dhcp leases and when the VM boots and
1363
makes a dhcp request, iptables will mangle the packet and `nfdhcpd` will
1364
create a dhcp response.
1365

    
1366
.. code-block:: console
1367

    
1368
   # apt-get install nfqueue-bindings-python=0.3+physindev-1
1369
   # apt-get install nfdhcpd
1370

    
1371
Edit ``/etc/nfdhcpd/nfdhcpd.conf`` to reflect your network configuration. At
1372
least, set the ``dhcp_queue`` variable to ``42`` and the ``nameservers``
1373
variable to your DNS IP/s. Those IPs will be passed as the DNS IP/s of your new
1374
VMs. Once you are finished, restart the server on all nodes:
1375

    
1376
.. code-block:: console
1377

    
1378
   # /etc/init.d/nfdhcpd restart
1379

    
1380
If you are using ``ferm``, then you need to run the following:
1381

    
1382
.. code-block:: console
1383

    
1384
   # echo "@include 'nfdhcpd.ferm';" >> /etc/ferm/ferm.conf
1385
   # /etc/init.d/ferm restart
1386

    
1387
or make sure to run after boot:
1388

    
1389
.. code-block:: console
1390

    
1391
   # iptables -t mangle -A PREROUTING -p udp -m udp --dport 67 -j NFQUEUE --queue-num 42
1392

    
1393
and if you have IPv6 enabled:
1394

    
1395
.. code-block:: console
1396

    
1397
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 133 -j NFQUEUE --queue-num 43
1398
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 135 -j NFQUEUE --queue-num 44
1399

    
1400
You can check which clients are currently served by nfdhcpd by running:
1401

    
1402
.. code-block:: console
1403

    
1404
   # kill -SIGUSR1 `cat /var/run/nfdhcpd/nfdhcpd.pid`
1405

    
1406
When you run the above, then check ``/var/log/nfdhcpd/nfdhcpd.log``.
1407

    
1408
Public Network Setup
1409
--------------------
1410

    
1411
To achieve basic networking the simplest way is to have a common bridge (e.g.
1412
``br0``, on the same collision domain with the router) where all VMs will
1413
connect to. Packets will be "forwarded" to the router and then to the Internet.
1414
If you want a more advanced setup (ip-less routing and proxy-arp plese refer to
1415
:ref:`Network <networks>` section).
1416

    
1417
Physical Host Setup
1418
~~~~~~~~~~~~~~~~~~~
1419

    
1420
Assuming ``eth0`` on both hosts is the public interface (directly connected
1421
to the router), run on every node:
1422

    
1423
.. code-block:: console
1424

    
1425
   # apt-get install vlan
1426
   # brctl addbr br0
1427
   # ip link set br0 up
1428
   # vconfig add eth0 100
1429
   # ip link set eth0.100 up
1430
   # brctl addif br0 eth0.100
1431

    
1432

    
1433
Testing a Public Network
1434
~~~~~~~~~~~~~~~~~~~~~~~~
1435

    
1436
Let's assume, that you want to assign IPs from the ``5.6.7.0/27`` range to you
1437
new VMs, with ``5.6.7.1`` as the router's gateway. In Ganeti you can add the
1438
network by running:
1439

    
1440
.. code-block:: console
1441

    
1442
   # gnt-network add --network=5.6.7.0/27 --gateway=5.6.7.1 --network-type=public --tags=nfdhcpd test-net-public
1443

    
1444
Then, connect the network to all your nodegroups. We assume that we only have
1445
one nodegroup (``default``) in our Ganeti cluster:
1446

    
1447
.. code-block:: console
1448

    
1449
   # gnt-network connect test-net-public default bridged br0
1450

    
1451
Now, it is time to test that the backend infrastracture is correctly setup for
1452
the Public Network. We will add a new VM, the same way we did it on the
1453
previous testing section. However, now will also add one NIC, configured to be
1454
managed from our previously defined network. Run on the GANETI-MASTER (node1):
1455

    
1456
.. code-block:: console
1457

    
1458
   # gnt-instance add -o snf-image+default --os-parameters \
1459
                      img_passwd=my_vm_example_passw0rd,img_format=diskdump,img_id="pithos://UUID/pithos/debian_base-6.0-7-x86_64.diskdump",img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' \
1460
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1461
                      --net 0:ip=pool,network=test-net-public \
1462
                      testvm2
1463

    
1464
If the above returns successfully, connect to the new VM and run:
1465

    
1466
.. code-block:: console
1467

    
1468
   root@testvm2:~ # ip addr
1469
   root@testvm2:~ # ip route
1470
   root@testvm2:~ # cat /etc/resolv.conf
1471

    
1472
to check IP address (5.6.7.2), IP routes (default via 5.6.7.1) and DNS config
1473
(nameserver option in nfdhcpd.conf). This shows correct configuration of
1474
ganeti, snf-network and nfdhcpd.
1475

    
1476
Now ping the outside world. If this works too, then you have also configured
1477
correctly your physical host and router.
1478

    
1479
Make sure everything works as expected, before proceeding with the Private
1480
Networks setup.
1481

    
1482
.. _private-networks-setup:
1483

    
1484
Private Networks Setup
1485
----------------------
1486

    
1487
Synnefo supports two types of private networks:
1488

    
1489
 - based on MAC filtering
1490
 - based on physical VLANs
1491

    
1492
Both types provide Layer 2 isolation to the end-user.
1493

    
1494
For the first type a common bridge (e.g. ``prv0``) is needed while for the
1495
second a range of bridges (e.g. ``prv1..prv100``) each bridged on a different
1496
physical VLAN. To this end to assure isolation among end-users' private networks
1497
each has to have different MAC prefix (for the filtering to take place) or to be
1498
"connected" to a different bridge (VLAN actually).
1499

    
1500
Physical Host Setup
1501
~~~~~~~~~~~~~~~~~~~
1502

    
1503
In order to create the necessary VLAN/bridges, one for MAC filtered private
1504
networks and various (e.g. 20) for private networks based on physical VLANs,
1505
run on every node:
1506

    
1507
Assuming ``eth0`` of both hosts are somehow (via cable/switch with VLANs
1508
configured correctly) connected together, run on every node:
1509

    
1510
.. code-block:: console
1511

    
1512
   # modprobe 8021q
1513
   # $iface=eth0
1514
   # for prv in $(seq 0 20); do
1515
        vlan=$prv
1516
        bridge=prv$prv
1517
        vconfig add $iface $vlan
1518
        ifconfig $iface.$vlan up
1519
        brctl addbr $bridge
1520
        brctl setfd $bridge 0
1521
        brctl addif $bridge $iface.$vlan
1522
        ifconfig $bridge up
1523
      done
1524

    
1525
The above will do the following :
1526

    
1527
 * provision 21 new bridges: ``prv0`` - ``prv20``
1528
 * provision 21 new vlans: ``eth0.0`` - ``eth0.20``
1529
 * add the corresponding vlan to the equivalent bridge
1530

    
1531
You can run ``brctl show`` on both nodes to see if everything was setup
1532
correctly.
1533

    
1534
Testing the Private Networks
1535
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1536

    
1537
To test the Private Networks, we will create two instances and put them in the
1538
same Private Networks (one MAC Filtered and one Physical VLAN). This means
1539
that the instances will have a second NIC connected to the ``prv0``
1540
pre-provisioned bridge and a third to ``prv1``.
1541

    
1542
We run the same command as in the Public Network testing section, but with one
1543
more argument for the second NIC:
1544

    
1545
.. code-block:: console
1546

    
1547
   # gnt-network add --network=192.168.1.0/24 --mac-prefix=aa:00:55 --network-type=private --tags=nfdhcpd,private-filtered test-net-prv-mac
1548
   # gnt-network connect test-net-prv-mac default bridged prv0
1549

    
1550
   # gnt-network add --network=10.0.0.0/24 --tags=nfdhcpd --network-type=private test-net-prv-vlan
1551
   # gnt-network connect test-net-prv-vlan default bridged prv1
1552

    
1553
   # gnt-instance add -o snf-image+default --os-parameters \
1554
                      img_passwd=my_vm_example_passw0rd,img_format=diskdump,img_id="pithos://UUID/pithos/debian_base-6.0-7-x86_64.diskdump",img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' \
1555
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1556
                      --net 0:ip=pool,network=test-net-public \
1557
                      --net 1:ip=pool,network=test-net-prv-mac \
1558
                      --net 2:ip=none,network=test-net-prv-vlan \
1559
                      testvm3
1560

    
1561
   # gnt-instance add -o snf-image+default --os-parameters \
1562
                      img_passwd=my_vm_example_passw0rd,img_format=diskdump,img_id="pithos://UUID/pithos/debian_base-6.0-7-x86_64.diskdump",img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' \
1563
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1564
                      --net 0:ip=pool,network=test-net-public \
1565
                      --net 1:ip=pool,network=test-net-prv-mac \
1566
                      --net 2:ip=none,network=test-net-prv-vlan \
1567
                      testvm4
1568

    
1569
Above, we create two instances with first NIC connected to the internet, their
1570
second NIC connected to a MAC filtered private Network and their third NIC
1571
connected to the first Physical VLAN Private Network. Now, connect to the
1572
instances using VNC and make sure everything works as expected:
1573

    
1574
 a) The instances have access to the public internet through their first eth
1575
    interface (``eth0``), which has been automatically assigned a public IP.
1576

    
1577
 b) ``eth1`` will have mac prefix ``aa:00:55``, while ``eth2`` default one (``aa:00:00``)
1578

    
1579
 c) ip link set ``eth1``/``eth2`` up
1580

    
1581
 d) dhclient ``eth1``/``eth2``
1582

    
1583
 e) On testvm3  ping 192.168.1.2/10.0.0.2
1584

    
1585
If everything works as expected, then you have finished the Network Setup at the
1586
backend for both types of Networks (Public & Private).
1587

    
1588
.. _cyclades-gtools:
1589

    
1590
Cyclades Ganeti tools
1591
---------------------
1592

    
1593
In order for Ganeti to be connected with Cyclades later on, we need the
1594
`Cyclades Ganeti tools` available on all Ganeti nodes (node1 & node2 in our
1595
case). You can install them by running in both nodes:
1596

    
1597
.. code-block:: console
1598

    
1599
   # apt-get install snf-cyclades-gtools
1600

    
1601
This will install the following:
1602

    
1603
 * ``snf-ganeti-eventd`` (daemon to publish Ganeti related messages on RabbitMQ)
1604
 * ``snf-ganeti-hook`` (all necessary hooks under ``/etc/ganeti/hooks``)
1605
 * ``snf-progress-monitor`` (used by ``snf-image`` to publish progress messages)
1606

    
1607
Configure ``snf-cyclades-gtools``
1608
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1609

    
1610
The package will install the ``/etc/synnefo/20-snf-cyclades-gtools-backend.conf``
1611
configuration file. At least we need to set the RabbitMQ endpoint for all tools
1612
that need it:
1613

    
1614
.. code-block:: console
1615

    
1616
  AMQP_HOSTS=["amqp://synnefo:example_rabbitmq_passw0rd@node1.example.com:5672"]
1617

    
1618
The above variables should reflect your :ref:`Message Queue setup
1619
<rabbitmq-setup>`. This file should be editted in all Ganeti nodes.
1620

    
1621
Connect ``snf-image`` with ``snf-progress-monitor``
1622
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1623

    
1624
Finally, we need to configure ``snf-image`` to publish progress messages during
1625
the deployment of each Image. To do this, we edit ``/etc/default/snf-image`` and
1626
set the corresponding variable to ``snf-progress-monitor``:
1627

    
1628
.. code-block:: console
1629

    
1630
   PROGRESS_MONITOR="snf-progress-monitor"
1631

    
1632
This file should be editted in all Ganeti nodes.
1633

    
1634
.. _rapi-user:
1635

    
1636
Synnefo RAPI user
1637
-----------------
1638

    
1639
As a last step before installing Cyclades, create a new RAPI user that will
1640
have ``write`` access. Cyclades will use this user to issue commands to Ganeti,
1641
so we will call the user ``cyclades`` with password ``example_rapi_passw0rd``.
1642
You can do this, by first running:
1643

    
1644
.. code-block:: console
1645

    
1646
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1647

    
1648
and then putting the output in ``/var/lib/ganeti/rapi/users`` as follows:
1649

    
1650
.. code-block:: console
1651

    
1652
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1653

    
1654
More about Ganeti's RAPI users `here.
1655
<http://docs.ganeti.org/ganeti/2.5/html/rapi.html#introduction>`_
1656

    
1657
You have now finished with all needed Prerequisites for Cyclades (and
1658
Plankton). Let's move on to the actual Cyclades installation.
1659

    
1660

    
1661
Installation of Cyclades (and Plankton) on node1
1662
================================================
1663

    
1664
This section describes the installation of Cyclades. Cyclades is Synnefo's
1665
Compute service. Plankton (the Image Registry service) will get installed
1666
automatically along with Cyclades, because it is contained in the same Synnefo
1667
component right now.
1668

    
1669
We will install Cyclades (and Plankton) on node1. To do so, we install the
1670
corresponding package by running on node1:
1671

    
1672
.. code-block:: console
1673

    
1674
   # apt-get install snf-cyclades-app memcached python-memcache
1675

    
1676
If all packages install successfully, then Cyclades and Plankton are installed
1677
and we proceed with their configuration.
1678

    
1679
Since version 0.13, Synnefo uses the VMAPI in order to prevent sensitive data
1680
needed by 'snf-image' to be stored in Ganeti configuration (e.g. VM password).
1681
This is achieved by storing all sensitive information to a CACHE backend and
1682
exporting it via VMAPI. The cache entries are invalidated after the first
1683
request. Synnefo uses `memcached <http://memcached.org/>`_ as a
1684
`Django <https://www.djangoproject.com/>`_ cache backend.
1685

    
1686
Configuration of Cyclades (and Plankton)
1687
========================================
1688

    
1689
Conf files
1690
----------
1691

    
1692
After installing Cyclades, a number of new configuration files will appear under
1693
``/etc/synnefo/`` prefixed with ``20-snf-cyclades-app-``. We will describe here
1694
only the minimal needed changes to result with a working system. In general,
1695
sane defaults have been chosen for the most of the options, to cover most of the
1696
common scenarios. However, if you want to tweak Cyclades feel free to do so,
1697
once you get familiar with the different options.
1698

    
1699
Edit ``/etc/synnefo/20-snf-cyclades-app-api.conf``:
1700

    
1701
.. code-block:: console
1702

    
1703
   ASTAKOS_URL = 'https://node1.example.com/'
1704

    
1705
   # Set to False if astakos & cyclades are on the same host
1706
   CYCLADES_PROXY_USER_SERVICES = False
1707

    
1708
The ``ASTAKOS_URL`` denotes the authentication endpoint for Cyclades and is set
1709
to point to Astakos (this should have the same value with Pithos+'s
1710
``ASTAKOS_URL``, setup :ref:`previously <conf-pithos>`).
1711

    
1712
.. warning::
1713

    
1714
   All services must match the quotaholder token and url configured for
1715
   quotaholder.
1716

    
1717
TODO: Document the Network Options here
1718

    
1719
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1720

    
1721
.. code-block:: console
1722

    
1723
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1724
   CLOUDBAR_ACTIVE_SERVICE = '2'
1725
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/api/get_services'
1726
   CLOUDBAR_MENU_URL = 'https://account.node1.example.com/astakos/api/get_menu'
1727

    
1728
``CLOUDBAR_LOCATION`` tells the client where to find the Astakos common
1729
cloudbar. The ``CLOUDBAR_SERVICES_URL`` and ``CLOUDBAR_MENU_URL`` options are
1730
used by the Cyclades Web UI to get from Astakos all the information needed to
1731
fill its own cloudbar. So, we put our Astakos deployment urls there. All the
1732
above should have the same values we put in the corresponding variables in
1733
``/etc/synnefo/20-snf-pithos-webclient-cloudbar.conf`` on the previous
1734
:ref:`Pithos configuration <conf-pithos>` section.
1735

    
1736
The ``CLOUDBAR_ACTIVE_SERVICE`` points to an already registered Astakos
1737
service. You can see all :ref:`registered services <services-reg>` by running
1738
on the Astakos node (node1):
1739

    
1740
.. code-block:: console
1741

    
1742
   # snf-manage service-list
1743

    
1744
The value of ``CLOUDBAR_ACTIVE_SERVICE`` should be the cyclades service's
1745
``id`` as shown by the above command, in our case ``2``.
1746

    
1747
Edit ``/etc/synnefo/20-snf-cyclades-app-plankton.conf``:
1748

    
1749
.. code-block:: console
1750

    
1751
   BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1752
   BACKEND_BLOCK_PATH = '/srv/pithos/data/'
1753

    
1754
In this file we configure the Plankton Service. ``BACKEND_DB_CONNECTION``
1755
denotes the Pithos+ database (where the Image files are stored). So we set that
1756
to point to our Pithos+ database. ``BACKEND_BLOCK_PATH`` denotes the actual
1757
Pithos+ data location.
1758

    
1759
Edit ``/etc/synnefo/20-snf-cyclades-app-queues.conf``:
1760

    
1761
.. code-block:: console
1762

    
1763
   AMQP_HOSTS=["amqp://synnefo:example_rabbitmq_passw0rd@node1.example.com:5672"]
1764

    
1765
The above settings denote the Message Queue. Those settings should have the same
1766
values as in ``/etc/synnefo/10-snf-cyclades-gtools-backend.conf`` file, and
1767
reflect our :ref:`Message Queue setup <rabbitmq-setup>`.
1768

    
1769
Edit ``/etc/synnefo/20-snf-cyclades-app-ui.conf``:
1770

    
1771
.. code-block:: console
1772

    
1773
   UI_LOGIN_URL = "https://node1.example.com/im/login"
1774
   UI_LOGOUT_URL = "https://node1.example.com/im/logout"
1775

    
1776
The ``UI_LOGIN_URL`` option tells the Cyclades Web UI where to redirect users,
1777
if they are not logged in. We point that to Astakos.
1778

    
1779
The ``UI_LOGOUT_URL`` option tells the Cyclades Web UI where to redirect the
1780
user when he/she logs out. We point that to Astakos, too.
1781

    
1782
Edit ``/etc/synnefo/20-snf-cyclades-app-vmapi.conf``:
1783

    
1784
.. code-block:: console
1785

    
1786
   VMAPI_CACHE_BACKEND = "memcached://127.0.0.1:11211/?timeout=3600"
1787
   VMAPI_BASE_URL = "https://node1.example.com"
1788

    
1789
Edit ``/etc/default/vncauthproxy``:
1790

    
1791
.. code-block:: console
1792

    
1793
   CHUID="nobody:www-data"
1794

    
1795
We have now finished with the basic Cyclades and Plankton configuration.
1796

    
1797
Database Initialization
1798
-----------------------
1799

    
1800
Once Cyclades is configured, we sync the database:
1801

    
1802
.. code-block:: console
1803

    
1804
   $ snf-manage syncdb
1805
   $ snf-manage migrate
1806

    
1807
and load the initial server flavors:
1808

    
1809
.. code-block:: console
1810

    
1811
   $ snf-manage loaddata flavors
1812

    
1813
If everything returns successfully, our database is ready.
1814

    
1815
Add the Ganeti backend
1816
----------------------
1817

    
1818
In our installation we assume that we only have one Ganeti cluster, the one we
1819
setup earlier.  At this point you have to add this backend (Ganeti cluster) to
1820
cyclades assuming that you have setup the :ref:`Rapi User <rapi-user>`
1821
correctly.
1822

    
1823
.. code-block:: console
1824

    
1825
   $ snf-manage backend-add --clustername=ganeti.node1.example.com --user=cyclades --pass=example_rapi_passw0rd
1826

    
1827
You can see everything has been setup correctly by running:
1828

    
1829
.. code-block:: console
1830

    
1831
   $ snf-manage backend-list
1832

    
1833
Enable the new backend by running:
1834

    
1835
.. code-block::
1836

    
1837
   $ snf-manage backend-modify --drained False 1
1838

    
1839
.. warning:: Since version 0.13, the backend is set to "drained" by default.
1840
    This means that you cannot add VMs to it. The reason for this is that the
1841
    nodes should be unavailable to Synnefo until the Administrator explicitly
1842
    releases them. To change this setting, use ``snf-manage backend-modify
1843
    --drained False <backend-id>``.
1844

    
1845
If something is not set correctly, you can modify the backend with the
1846
``snf-manage backend-modify`` command. If something has gone wrong, you could
1847
modify the backend to reflect the Ganeti installation by running:
1848

    
1849
.. code-block:: console
1850

    
1851
   $ snf-manage backend-modify --clustername "ganeti.node1.example.com"
1852
                               --user=cyclades
1853
                               --pass=example_rapi_passw0rd
1854
                               1
1855

    
1856
``clustername`` denotes the Ganeti-cluster's name. We provide the corresponding
1857
domain that resolves to the master IP, than the IP itself, to ensure Cyclades
1858
can talk to Ganeti even after a Ganeti master-failover.
1859

    
1860
``user`` and ``pass`` denote the RAPI user's username and the RAPI user's
1861
password.  Once we setup the first backend to point at our Ganeti cluster, we
1862
update the Cyclades backends status by running:
1863

    
1864
.. code-block:: console
1865

    
1866
   $ snf-manage backend-update-status
1867

    
1868
Cyclades can manage multiple Ganeti backends, but for the purpose of this
1869
guide,we won't get into more detail regarding mulitple backends. If you want to
1870
learn more please see /*TODO*/.
1871

    
1872
Add a Public Network
1873
----------------------
1874

    
1875
Cyclades supports different Public Networks on different Ganeti backends.
1876
After connecting Cyclades with our Ganeti cluster, we need to setup a Public
1877
Network for this Ganeti backend (`id = 1`). The basic setup is to bridge every
1878
created NIC on a bridge. After having a bridge (e.g. br0) created in every
1879
backend node edit Synnefo setting CUSTOM_BRIDGED_BRIDGE to 'br0':
1880

    
1881
.. code-block:: console
1882

    
1883
   $ snf-manage network-create --subnet=5.6.7.0/27 \
1884
                               --gateway=5.6.7.1 \
1885
                               --subnet6=2001:648:2FFC:1322::/64 \
1886
                               --gateway6=2001:648:2FFC:1322::1 \
1887
                               --public --dhcp --flavor=CUSTOM \
1888
                               --link=br0 --mode=bridged \
1889
                               --name=public_network \
1890
                               --backend-id=1
1891

    
1892
This will create the Public Network on both Cyclades and the Ganeti backend. To
1893
make sure everything was setup correctly, also run:
1894

    
1895
.. code-block:: console
1896

    
1897
   $ snf-manage reconcile-networks
1898

    
1899
You can see all available networks by running:
1900

    
1901
.. code-block:: console
1902

    
1903
   $ snf-manage network-list
1904

    
1905
and inspect each network's state by running:
1906

    
1907
.. code-block:: console
1908

    
1909
   $ snf-manage network-inspect <net_id>
1910

    
1911
Finally, you can see the networks from the Ganeti perspective by running on the
1912
Ganeti MASTER:
1913

    
1914
.. code-block:: console
1915

    
1916
   $ gnt-network list
1917
   $ gnt-network info <network_name>
1918

    
1919
Create pools for Private Networks
1920
---------------------------------
1921

    
1922
To prevent duplicate assignment of resources to different private networks,
1923
Cyclades supports two types of pools:
1924

    
1925
 - MAC prefix Pool
1926
 - Bridge Pool
1927

    
1928
As long as those resourses have been provisioned, admin has to define two
1929
these pools in Synnefo:
1930

    
1931

    
1932
.. code-block:: console
1933

    
1934
   root@testvm1:~ # snf-manage pool-create --type=mac-prefix --base=aa:00:0 --size=65536
1935

    
1936
   root@testvm1:~ # snf-manage pool-create --type=bridge --base=prv --size=20
1937

    
1938
Also, change the Synnefo setting in :file:`20-snf-cyclades-app-api.conf`:
1939

    
1940
.. code-block:: console
1941

    
1942
   DEFAULT_MAC_FILTERED_BRIDGE = 'prv0'
1943

    
1944
Servers restart
1945
---------------
1946

    
1947
Restart gunicorn on node1:
1948

    
1949
.. code-block:: console
1950

    
1951
   # /etc/init.d/gunicorn restart
1952

    
1953
Now let's do the final connections of Cyclades with Ganeti.
1954

    
1955
``snf-dispatcher`` initialization
1956
---------------------------------
1957

    
1958
``snf-dispatcher`` dispatches all messages published to the Message Queue and
1959
manages the Cyclades database accordingly. It also initializes all exchanges. By
1960
default it is not enabled during installation of Cyclades, so let's enable it in
1961
its configuration file ``/etc/default/snf-dispatcher``:
1962

    
1963
.. code-block:: console
1964

    
1965
   SNF_DSPTCH_ENABLE=true
1966

    
1967
and start the daemon:
1968

    
1969
.. code-block:: console
1970

    
1971
   # /etc/init.d/snf-dispatcher start
1972

    
1973
You can see that everything works correctly by tailing its log file
1974
``/var/log/synnefo/dispatcher.log``.
1975

    
1976
``snf-ganeti-eventd`` on GANETI MASTER
1977
--------------------------------------
1978

    
1979
The last step of the Cyclades setup is enabling the ``snf-ganeti-eventd``
1980
daemon (part of the :ref:`Cyclades Ganeti tools <cyclades-gtools>` package).
1981
The daemon is already installed on the GANETI MASTER (node1 in our case).
1982
``snf-ganeti-eventd`` is disabled by default during the ``snf-cyclades-gtools``
1983
installation, so we enable it in its configuration file
1984
``/etc/default/snf-ganeti-eventd``:
1985

    
1986
.. code-block:: console
1987

    
1988
   SNF_EVENTD_ENABLE=true
1989

    
1990
and start the daemon:
1991

    
1992
.. code-block:: console
1993

    
1994
   # /etc/init.d/snf-ganeti-eventd start
1995

    
1996
.. warning:: Make sure you start ``snf-ganeti-eventd`` *ONLY* on GANETI MASTER
1997

    
1998
Apply Quotas
1999
------------
2000

    
2001
.. code-block:: console
2002

    
2003
   node1 # snf-manage astakos-init --load-service-resources
2004
   node1 # snf-manage quota --verify
2005
   node1 # snf-manage quota --sync
2006
   node2 # snf-manage pithos-reset-usage
2007
   node1 # snf-manage reconcile-resources-cyclades --fix
2008

    
2009
If all the above return successfully, then you have finished with the Cyclades
2010
and Plankton installation and setup.
2011

    
2012
Let's test our installation now.
2013

    
2014

    
2015
Testing of Cyclades (and Plankton)
2016
==================================
2017

    
2018
Cyclades Web UI
2019
---------------
2020

    
2021
First of all we need to test that our Cyclades Web UI works correctly. Open your
2022
browser and go to the Astakos home page. Login and then click 'cyclades' on the
2023
top cloud bar. This should redirect you to:
2024

    
2025
 `http://node1.example.com/ui/`
2026

    
2027
and the Cyclades home page should appear. If not, please go back and find what
2028
went wrong. Do not proceed if you don't see the Cyclades home page.
2029

    
2030
If the Cyclades home page appears, click on the orange button 'New machine'. The
2031
first step of the 'New machine wizard' will appear. This step shows all the
2032
available Images from which you can spawn new VMs. The list should be currently
2033
empty, as we haven't registered any Images yet. Close the wizard and browse the
2034
interface (not many things to see yet). If everything seems to work, let's
2035
register our first Image file.
2036

    
2037
Cyclades Images
2038
---------------
2039

    
2040
To test our Cyclades (and Plankton) installation, we will use an Image stored on
2041
Pithos+ to spawn a new VM from the Cyclades interface. We will describe all
2042
steps, even though you may already have uploaded an Image on Pithos+ from a
2043
:ref:`previous <snf-image-images>` section:
2044

    
2045
 * Upload an Image file to Pithos+
2046
 * Register that Image file to Plankton
2047
 * Spawn a new VM from that Image from the Cyclades Web UI
2048

    
2049
We will use the `kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_
2050
command line client to do the uploading and registering of the Image.
2051

    
2052
Installation of `kamaki`
2053
~~~~~~~~~~~~~~~~~~~~~~~~
2054

    
2055
You can install `kamaki` anywhere you like, since it is a standalone client of
2056
the APIs and talks to the installation over `http`. For the purpose of this
2057
guide we will assume that we have downloaded the `Debian Squeeze Base Image
2058
<https://pithos.okeanos.grnet.gr/public/9epgb>`_ and stored it under node1's
2059
``/srv/images`` directory. For that reason we will install `kamaki` on node1,
2060
too. We do this by running:
2061

    
2062
.. code-block:: console
2063

    
2064
   # apt-get install kamaki
2065

    
2066
Configuration of kamaki
2067
~~~~~~~~~~~~~~~~~~~~~~~
2068

    
2069
Now we need to setup kamaki, by adding the appropriate URLs and tokens of our
2070
installation. We do this by running:
2071

    
2072
.. code-block:: console
2073

    
2074
   $ kamaki config set user.url "https://node1.example.com"
2075
   $ kamaki config set compute.url "https://node1.example.com/api/v1.1"
2076
   $ kamaki config set image.url "https://node1.example.com/plankton"
2077
   $ kamaki config set file.url "https://node2.example.com/v1"
2078
   $ kamaki config set token USER_TOKEN
2079

    
2080
The USER_TOKEN appears on the user's `Profile` web page on the Astakos Web UI.
2081

    
2082
You can see that the new configuration options have been applied correctly,
2083
either by checking the editable file ``~/.kamakirc`` or by running:
2084

    
2085
.. code-block:: console
2086

    
2087
   $ kamaki config list
2088

    
2089
A quick test to check that kamaki is configured correctly, is to try to
2090
authenticate a user based on his/her token (in this case the user is you):
2091

    
2092
.. code-block:: console
2093

    
2094
  $ kamaki user authenticate
2095

    
2096
The above operation provides various user information, e.g. UUID (the unique
2097
user id) which might prove useful in some operations.
2098

    
2099
Upload an Image file to Pithos+
2100
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2101

    
2102
Now, that we have set up `kamaki` we will upload the Image that we have
2103
downloaded and stored under ``/srv/images/``. Although we can upload the Image
2104
under the root ``Pithos`` container (as you may have done when uploading the
2105
Image from the Pithos+ Web UI), we will create a new container called ``images``
2106
and store the Image under that container. We do this for two reasons:
2107

    
2108
a) To demonstrate how to create containers other than the default ``Pithos``.
2109
   This can be done only with the `kamaki` client and not through the Web UI.
2110

    
2111
b) As a best organization practise, so that you won't have your Image files
2112
   tangled along with all your other Pithos+ files and directory structures.
2113

    
2114
We create the new ``images`` container by running:
2115

    
2116
.. code-block:: console
2117

    
2118
   $ kamaki file create images
2119

    
2120
To check if the container has been created, list all containers of your
2121
account:
2122

    
2123
.. code-block:: console
2124

    
2125
  $ kamaki file list
2126

    
2127
Then, we upload the Image file to that container:
2128

    
2129
.. code-block:: console
2130

    
2131
   $ kamaki file upload /srv/images/debian_base-6.0-7-x86_64.diskdump images
2132

    
2133
The first is the local path and the second is the remote container on Pithos+.
2134
Check if the file has been uploaded, by listing the container contents:
2135

    
2136
.. code-block:: console
2137

    
2138
  $ kamaki file list images
2139

    
2140
Alternatively check if the new container and file appear on the Pithos+ Web UI.
2141

    
2142
Register an existing Image file to Plankton
2143
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2144

    
2145
For the purposes of the following example, we assume that the user UUID is
2146
``u53r-un1qu3-1d``.
2147

    
2148
Once the Image file has been successfully uploaded on Pithos+ then we register
2149
it to Plankton (so that it becomes visible to Cyclades), by running:
2150

    
2151
.. code-block:: console
2152

    
2153
   $ kamaki image register "Debian Base" \
2154
                           pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump \
2155
                           --public \
2156
                           --disk-format=diskdump \
2157
                           --property OSFAMILY=linux --property ROOT_PARTITION=1 \
2158
                           --property description="Debian Squeeze Base System" \
2159
                           --property size=451 --property kernel=2.6.32 --property GUI="No GUI" \
2160
                           --property sortorder=1 --property USERS=root --property OS=debian
2161

    
2162
This command registers the Pithos+ file
2163
``pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump`` as an
2164
Image in Plankton. This Image will be public (``--public``), so all users will
2165
be able to spawn VMs from it and is of type ``diskdump``. The first two
2166
properties (``OSFAMILY`` and ``ROOT_PARTITION``) are mandatory. All the rest
2167
properties are optional, but recommended, so that the Images appear nicely on
2168
the Cyclades Web UI. ``Debian Base`` will appear as the name of this Image. The
2169
``OS`` property's valid values may be found in the ``IMAGE_ICONS`` variable
2170
inside the ``20-snf-cyclades-app-ui.conf`` configuration file.
2171

    
2172
``OSFAMILY`` and ``ROOT_PARTITION`` are mandatory because they will be passed
2173
from Plankton to Cyclades and then to Ganeti and `snf-image` (also see
2174
:ref:`previous section <ganeti-with-pithos-images>`). All other properties are
2175
used to show information on the Cyclades UI.
2176

    
2177
Spawn a VM from the Cyclades Web UI
2178
-----------------------------------
2179

    
2180
If the registration completes successfully, then go to the Cyclades Web UI from
2181
your browser at:
2182

    
2183
 `https://node1.example.com/ui/`
2184

    
2185
Click on the 'New Machine' button and the first step of the wizard will appear.
2186
Click on 'My Images' (right after 'System' Images) on the left pane of the
2187
wizard. Your previously registered Image "Debian Base" should appear under
2188
'Available Images'. If not, something has gone wrong with the registration. Make
2189
sure you can see your Image file on the Pithos+ Web UI and ``kamaki image
2190
register`` returns successfully with all options and properties as shown above.
2191

    
2192
If the Image appears on the list, select it and complete the wizard by selecting
2193
a flavor and a name for your VM. Then finish by clicking 'Create'. Make sure you
2194
write down your password, because you *WON'T* be able to retrieve it later.
2195

    
2196
If everything was setup correctly, after a few minutes your new machine will go
2197
to state 'Running' and you will be able to use it. Click 'Console' to connect
2198
through VNC out of band, or click on the machine's icon to connect directly via
2199
SSH or RDP (for windows machines).
2200

    
2201
Congratulations. You have successfully installed the whole Synnefo stack and
2202
connected all components. Go ahead in the next section to test the Network
2203
functionality from inside Cyclades and discover even more features.
2204

    
2205
General Testing
2206
===============
2207

    
2208
Notes
2209
=====
2210