Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 0d87ef78

History | View | Annotate | Download (75.5 kB)

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

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

    
6
This is the Administrator's 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 Service (part of Cyclades)
17
    * Network Service (part of Cyclades)
18

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

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

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

    
27

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

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

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

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

    
47
    .. code-block:: console
48

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

    
52

    
53
General Prerequisites
54
=====================
55

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

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

    
62
| ``deb http://apt.dev.grnet.gr squeeze/``
63
| ``deb-src http://apt.dev.grnet.gr squeeze/``
64

    
65
and import the repo's GPG key:
66

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

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

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

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

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

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

    
93
Node1
94
-----
95

    
96
General Synnefo dependencies
97
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98

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

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

    
108
.. code-block:: console
109

    
110
   # apt-get install apache2 postgresql ntp
111

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

    
115
.. code-block:: console
116

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

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

    
121
.. code-block:: console
122

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

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

    
128
.. code-block:: console
129

    
130
   # apt-get install python-psycopg2
131

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

    
135
.. code-block:: console
136

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

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

    
141
.. code-block:: console
142

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

    
146
Finally, to install the package run:
147

    
148
.. code-block:: console
149

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

    
153
Database setup
154
~~~~~~~~~~~~~~
155

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

    
160
.. code-block:: console
161

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

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

    
173
.. code-block:: console
174

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

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

    
182
.. code-block:: console
183

    
184
    listen_addresses = '*'
185

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

    
190
.. code-block:: console
191

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

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

    
198
.. code-block:: console
199

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

    
202
Gunicorn setup
203
~~~~~~~~~~~~~~
204

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

    
207
.. code-block:: console
208

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

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

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

    
233
Apache2 setup
234
~~~~~~~~~~~~~
235

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

    
239
.. code-block:: console
240

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

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

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

    
253
.. code-block:: console
254

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

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

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

    
264
       AllowEncodedSlashes On
265

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

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

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

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

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

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

    
291
Now enable sites and modules by running:
292

    
293
.. code-block:: console
294

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

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

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

    
307
.. _rabbitmq-setup:
308

    
309
Message Queue setup
310
~~~~~~~~~~~~~~~~~~~
311

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

    
316
.. code-block:: console
317

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

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

    
324
Pithos data directory setup
325
~~~~~~~~~~~~~~~~~~~~~~~~~~~
326

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

    
331
.. code-block:: console
332

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

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

    
341
Node2
342
-----
343

    
344
General Synnefo dependencies
345
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
346

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

    
353
You can install the above by running:
354

    
355
.. code-block:: console
356

    
357
   # apt-get install apache2 postgresql ntp
358

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

    
362
.. code-block:: console
363

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

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

    
368
.. code-block:: console
369

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

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

    
375
.. code-block:: console
376

    
377
   # apt-get install python-psycopg2
378

    
379
Database setup
380
~~~~~~~~~~~~~~
381

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

    
388
Gunicorn setup
389
~~~~~~~~~~~~~~
390

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

    
394
.. code-block:: console
395

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

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

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

    
421
Apache2 setup
422
~~~~~~~~~~~~~
423

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

    
427
.. code-block:: console
428

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

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

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

    
441
.. code-block:: console
442

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

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

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

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

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

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

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

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

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

    
476
.. code-block:: console
477

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

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

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

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

    
494

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

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

    
502
.. code-block:: console
503

    
504
   # apt-get install snf-astakos-app snf-pithos-backend
505

    
506
.. _conf-astakos:
507

    
508
Configuration of Astakos
509
========================
510

    
511
Conf Files
512
----------
513

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

    
521
After getting familiar with synnefo, you will be able to customize the software
522
as you wish and fits your needs. Many options are available, to empower the
523
administrator with extensively customizable setups.
524

    
525
For the snf-webproject component (installed as an astakos dependency), we
526
need the following:
527

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

    
531
.. code-block:: console
532

    
533
    DATABASES = {
534
     'default': {
535
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
536
         'ENGINE': 'postgresql_psycopg2',
537
         # ATTENTION: This *must* be the absolute path if using sqlite3.
538
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
539
         'NAME': 'snf_apps',
540
         'USER': 'synnefo',                      # Not used with sqlite3.
541
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
542
         # Set to empty string for localhost. Not used with sqlite3.
543
         'HOST': '4.3.2.1',
544
         # Set to empty string for default. Not used with sqlite3.
545
         'PORT': '5432',
546
     }
547
    }
548

    
549
Edit ``/etc/synnefo/10-snf-webproject-deploy.conf``. Uncomment and edit
550
``SECRET_KEY``. This is a Django specific setting which is used to provide a
551
seed in secret-key hashing algorithms. Set this to a random string of your
552
choice and keep it private:
553

    
554
.. code-block:: console
555

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

    
558
For astakos specific configuration, edit the following options in
559
``/etc/synnefo/20-snf-astakos-app-settings.conf`` :
560

    
561
.. code-block:: console
562

    
563
    ASTAKOS_DEFAULT_ADMIN_EMAIL = None
564

    
565
    ASTAKOS_COOKIE_DOMAIN = '.example.com'
566

    
567
    ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
568

    
569
The ``ASTAKOS_COOKIE_DOMAIN`` should be the base url of our domain (for all
570
services). ``ASTAKOS_BASE_URL`` is the astakos top-level URL. Appending an
571
extra path (``/astakos`` here) is recommended in order to distinguish
572
components, if more than one are installed on the same machine.
573

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

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

    
583
    .. code-block:: console
584

    
585
        ASTAKOS_RECAPTCHA_PUBLIC_KEY = 'example_recaptcha_public_key!@#$%^&*('
586
        ASTAKOS_RECAPTCHA_PRIVATE_KEY = 'example_recaptcha_private_key!@#$%^&*('
587
        ASTAKOS_RECAPTCHA_USE_SSL = True
588
        ASTAKOS_RECAPTCHA_ENABLED = True
589

    
590
    For the ``ASTAKOS_RECAPTCHA_PUBLIC_KEY`` and ``ASTAKOS_RECAPTCHA_PRIVATE_KEY``
591
    go to https://www.google.com/recaptcha/admin/create and create your own pair.
592

    
593
Then edit ``/etc/synnefo/20-snf-astakos-app-cloudbar.conf`` :
594

    
595
.. code-block:: console
596

    
597
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
598

    
599
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
600

    
601
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
602

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

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

    
610
Enable Pooling
611
--------------
612

    
613
This section can be bypassed, but we strongly recommend you apply the following,
614
since they result in a significant performance boost.
615

    
616
Synnefo includes a pooling DBAPI driver for PostgreSQL, as a thin wrapper
617
around Psycopg2. This allows independent Django requests to reuse pooled DB
618
connections, with significant performance gains.
619

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

    
623
.. code-block:: console
624

    
625
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
626
    monkey_patch_psycopg2()
627

    
628
Since we are running with greenlets, we should modify psycopg2 behavior, so it
629
works properly in a greenlet context:
630

    
631
.. code-block:: console
632

    
633
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
634
    make_psycopg_green()
635

    
636
Use the Psycopg2 driver as usual. For Django, this means using
637
``django.db.backends.postgresql_psycopg2`` without any modifications. To enable
638
connection pooling, pass a nonzero ``synnefo_poolsize`` option to the DBAPI
639
driver, through ``DATABASES.OPTIONS`` in Django.
640

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

    
644
.. code-block:: console
645

    
646
    # Monkey-patch psycopg2
647
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
648
    monkey_patch_psycopg2()
649

    
650
    # If running with greenlets
651
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
652
    make_psycopg_green()
653

    
654
    DATABASES = {
655
     'default': {
656
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
657
         'ENGINE': 'postgresql_psycopg2',
658
         'OPTIONS': {'synnefo_poolsize': 8},
659

    
660
         # ATTENTION: This *must* be the absolute path if using sqlite3.
661
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
662
         'NAME': 'snf_apps',
663
         'USER': 'synnefo',                      # Not used with sqlite3.
664
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
665
         # Set to empty string for localhost. Not used with sqlite3.
666
         'HOST': '4.3.2.1',
667
         # Set to empty string for default. Not used with sqlite3.
668
         'PORT': '5432',
669
     }
670
    }
671

    
672
Database Initialization
673
-----------------------
674

    
675
After configuration is done, we initialize the database by running:
676

    
677
.. code-block:: console
678

    
679
    # snf-manage syncdb
680

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

    
685
.. code-block:: console
686

    
687
    # snf-manage migrate im
688
    # snf-manage migrate quotaholder_app
689

    
690
Then, we load the pre-defined user groups
691

    
692
.. code-block:: console
693

    
694
    # snf-manage loaddata groups
695

    
696
.. _services-reg:
697

    
698
Services Registration
699
---------------------
700

    
701
When the database is ready, we need to register the services. The following
702
command will ask you to register the standard Synnefo components (astakos,
703
cyclades, and pithos) along with the services they provide. Note that you
704
have to register at least astakos in order to have a usable authentication
705
system. For each component, you will be asked to provide two URLs: its base
706
URL and its UI URL.
707

    
708
The former is the location where the component resides; it should equal
709
the ``<component_name>_BASE_URL`` as specified in the respective component
710
settings. For example, the base URL for astakos would be
711
``https://node1.example.com/astakos``.
712

    
713
The latter is the URL that appears in the Cloudbar and leads to the
714
component UI. If you want to follow the default setup, set
715
the UI URL to ``<base_url>/ui/`` where ``base_url`` the component's base
716
URL as explained before. (You can later change the UI URL with
717
``snf-manage component-modify <component_name> --url new_ui_url``.)
718

    
719
The command will also register automatically the resource definitions
720
offered by the services.
721

    
722
.. code-block:: console
723

    
724
    # snf-component-register
725

    
726
.. note::
727

    
728
   This command is equivalent to running the following series of commands;
729
   it registers the three components in astakos and then in each host it
730
   exports the respective service definitions, copies the exported json file
731
   to the astakos host, where it finally imports it:
732

    
733
    .. code-block:: console
734

    
735
       astakos-host$ snf-manage component-add astakos astakos_ui_url
736
       astakos-host$ snf-manage component-add cyclades cyclades_ui_url
737
       astakos-host$ snf-manage component-add pithos pithos_ui_url
738
       astakos-host$ snf-manage service-export-astakos > astakos.json
739
       astakos-host$ snf-manage service-import --json astakos.json
740
       cyclades-host$ snf-manage service-export-cyclades > cyclades.json
741
       # copy the file to astakos-host
742
       astakos-host$ snf-manage service-import --json cyclades.json
743
       pithos-host$ snf-manage service-export-pithos > pithos.json
744
       # copy the file to astakos-host
745
       astakos-host$ snf-manage service-import --json pithos.json
746

    
747
Setting Default Base Quota for Resources
748
----------------------------------------
749

    
750
We now have to specify the limit on resources that each user can employ
751
(exempting resources offered by projects).
752

    
753
.. code-block:: console
754

    
755
    # snf-manage resource-modify --limit-interactive
756

    
757

    
758
Servers Initialization
759
----------------------
760

    
761
Finally, we initialize the servers on node1:
762

    
763
.. code-block:: console
764

    
765
    root@node1:~ # /etc/init.d/gunicorn restart
766
    root@node1:~ # /etc/init.d/apache2 restart
767

    
768
We have now finished the Astakos setup. Let's test it now.
769

    
770

    
771
Testing of Astakos
772
==================
773

    
774
Open your favorite browser and go to:
775

    
776
``http://node1.example.com/astakos``
777

    
778
If this redirects you to ``https://node1.example.com/astakos/ui/`` and you can see
779
the "welcome" door of Astakos, then you have successfully setup Astakos.
780

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

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

    
789
.. code-block:: console
790

    
791
    root@node1:~ # snf-manage user-list
792

    
793
This command should show you a list with only one user; the one we just created.
794
This user should have an id with a value of ``1`` and flag "active" and
795
"verified" set to False. Now run:
796

    
797
.. code-block:: console
798

    
799
    root@node1:~ # snf-manage user-modify 1 --verify --accept
800

    
801
This verifies the user email and activates the user.
802
When running in production, the activation is done automatically with different
803
types of moderation, that Astakos supports. You can see the moderation methods
804
(by invitation, whitelists, matching regexp, etc.) at the Astakos specific
805
documentation. In production, you can also manually activate a user, by sending
806
him/her an activation email. See how to do this at the :ref:`User
807
activation <user_activation>` section.
808

    
809
Now let's go back to the homepage. Open ``http://node1.example.com/astkos/ui/`` with
810
your browser again. Try to sign in using your new credentials. If the astakos
811
menu appears and you can see your profile, then you have successfully setup
812
Astakos.
813

    
814
Let's continue to install Pithos now.
815

    
816

    
817
Installation of Pithos on node2
818
===============================
819

    
820
To install Pithos, grab the packages from our repository (make sure  you made
821
the additions needed in your ``/etc/apt/sources.list`` file, as described
822
previously), by running:
823

    
824
.. code-block:: console
825

    
826
   # apt-get install snf-pithos-app snf-pithos-backend
827

    
828
Now, install the pithos web interface:
829

    
830
.. code-block:: console
831

    
832
   # apt-get install snf-pithos-webclient
833

    
834
This package provides the standalone pithos web client. The web client is the
835
web UI for Pithos and will be accessible by clicking "pithos" on the Astakos
836
interface's cloudbar, at the top of the Astakos homepage.
837

    
838

    
839
.. _conf-pithos:
840

    
841
Configuration of Pithos
842
=======================
843

    
844
Conf Files
845
----------
846

    
847
After Pithos is successfully installed, you will find the directory
848
``/etc/synnefo`` and some configuration files inside it, as you did in node1
849
after installation of astakos. Here, you will not have to change anything that
850
has to do with snf-common or snf-webproject. Everything is set at node1. You
851
only need to change settings that have to do with Pithos. Specifically:
852

    
853
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
854
this options:
855

    
856
.. code-block:: console
857

    
858
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
859

    
860
   PITHOS_BASE_URL = 'https://node2.example.com/pithos'
861
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
862
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
863

    
864
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w'
865

    
866
   # Set to False if astakos & pithos are on the same host
867
   PITHOS_PROXY_USER_SERVICES = True
868

    
869

    
870
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the Pithos app where to
871
find the Pithos backend database. Above we tell Pithos that its database is
872
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
873
``example_passw0rd``.  All those settings where setup during node1's "Database
874
setup" section.
875

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

    
881
The ``ASTAKOS_BASE_URL`` option informs the Pithos app where Astakos is.
882
The Astakos service is used for user management (authentication, quotas, etc.)
883

    
884
The ``PITHOS_BASE_URL`` setting must point to the top-level Pithos URL.
885

    
886
The ``PITHOS_SERVICE_TOKEN`` is the token used for authentication with astakos.
887
It can be retrieved by running on the Astakos node (node1 in our case):
888

    
889
.. code-block:: console
890

    
891
   # snf-manage component-list
892

    
893
The token has been generated automatically during the :ref:`Pithos service
894
registration <services-reg>`.
895

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

    
899
.. code-block:: console
900

    
901
    PITHOS_UI_LOGIN_URL = "https://node1.example.com/ui/login?next="
902
    PITHOS_UI_FEEDBACK_URL = "https://node2.example.com/feedback"
903

    
904
The ``PITHOS_UI_LOGIN_URL`` option tells the client where to redirect you, if
905
you are not logged in. The ``PITHOS_UI_FEEDBACK_URL`` option points at the
906
Pithos feedback form. Astakos already provides a generic feedback form for all
907
services, so we use this one.
908

    
909
The ``PITHOS_UPDATE_MD5`` option by default disables the computation of the
910
object checksums. This results to improved performance during object uploading.
911
However, if compatibility with the OpenStack Object Storage API is important
912
then it should be changed to ``True``.
913

    
914
Then edit ``/etc/synnefo/20-snf-pithos-webclient-cloudbar.conf``, to connect the
915
Pithos web UI with the astakos web UI (through the top cloudbar):
916

    
917
.. code-block:: console
918

    
919
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
920
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
921
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
922

    
923
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
924
cloudbar.
925

    
926
The ``CLOUDBAR_SERVICES_URL`` and ``CLOUDBAR_MENU_URL`` options are used by the
927
Pithos web client to get from astakos all the information needed to fill its
928
own cloudbar. So we put our astakos deployment urls there.
929

    
930
Pooling and Greenlets
931
---------------------
932

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

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

    
942
.. code-block:: console
943

    
944
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
945
    make_psycopg_green()
946

    
947
Furthermore, add the ``--worker-class=gevent`` (or ``--worker-class=sync`` as
948
mentioned above, depending on your setup) argument on your
949
``/etc/gunicorn.d/synnefo`` configuration file. The file should look something
950
like this:
951

    
952
.. code-block:: console
953

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

    
971
Stamp Database Revision
972
-----------------------
973

    
974
Pithos uses the alembic_ database migrations tool.
975

    
976
.. _alembic: http://alembic.readthedocs.org
977

    
978
After a successful installation, we should stamp it at the most recent
979
revision, so that future migrations know where to start upgrading in
980
the migration history.
981

    
982
.. code-block:: console
983

    
984
    root@node2:~ # pithos-migrate stamp head
985

    
986
Servers Initialization
987
----------------------
988

    
989
After configuration is done, we initialize the servers on node2:
990

    
991
.. code-block:: console
992

    
993
    root@node2:~ # /etc/init.d/gunicorn restart
994
    root@node2:~ # /etc/init.d/apache2 restart
995

    
996
You have now finished the Pithos setup. Let's test it now.
997

    
998

    
999
Testing of Pithos
1000
=================
1001

    
1002
Open your browser and go to the Astakos homepage:
1003

    
1004
``http://node1.example.com/astakos``
1005

    
1006
Login, and you will see your profile page. Now, click the "pithos" link on the
1007
top black cloudbar. If everything was setup correctly, this will redirect you
1008
to:
1009

    
1010

    
1011
and you will see the blue interface of the Pithos application.  Click the
1012
orange "Upload" button and upload your first file. If the file gets uploaded
1013
successfully, then this is your first sign of a successful Pithos installation.
1014
Go ahead and experiment with the interface to make sure everything works
1015
correctly.
1016

    
1017
You can also use the Pithos clients to sync data from your Windows PC or MAC.
1018

    
1019
If you don't stumble on any problems, then you have successfully installed
1020
Pithos, which you can use as a standalone File Storage Service.
1021

    
1022
If you would like to do more, such as:
1023

    
1024
    * Spawning VMs
1025
    * Spawning VMs from Images stored on Pithos
1026
    * Uploading your custom Images to Pithos
1027
    * Spawning VMs from those custom Images
1028
    * Registering existing Pithos files as Images
1029
    * Connect VMs to the Internet
1030
    * Create Private Networks
1031
    * Add VMs to Private Networks
1032

    
1033
please continue with the rest of the guide.
1034

    
1035

    
1036
Cyclades Prerequisites
1037
======================
1038

    
1039
Before proceeding with the Cyclades installation, make sure you have
1040
successfully set up Astakos and Pithos first, because Cyclades depends on
1041
them. If you don't have a working Astakos and Pithos installation yet, please
1042
return to the :ref:`top <quick-install-admin-guide>` of this guide.
1043

    
1044
Besides Astakos and Pithos, you will also need a number of additional working
1045
prerequisites, before you start the Cyclades installation.
1046

    
1047
Ganeti
1048
------
1049

    
1050
`Ganeti <http://code.google.com/p/ganeti/>`_ handles the low level VM management
1051
for Cyclades, so Cyclades requires a working Ganeti installation at the backend.
1052
Please refer to the
1053
`ganeti documentation <http://docs.ganeti.org/ganeti/2.5/html>`_ for all the
1054
gory details. A successful Ganeti installation concludes with a working
1055
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs
1056
<GANETI_NODES>`.
1057

    
1058
The above Ganeti cluster can run on different physical machines than node1 and
1059
node2 and can scale independently, according to your needs.
1060

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

    
1065
We highly recommend that you read the official Ganeti documentation, if you are
1066
not familiar with Ganeti.
1067

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

    
1073
.. code-block:: console
1074

    
1075
   # apt-get install snf-ganeti ganeti-htools
1076
   # rmmod -f drbd && modprobe drbd minor_count=255 usermode_helper=/bin/true
1077

    
1078
You should have:
1079

    
1080
Ganeti >= 2.6.2+ippool11+hotplug5+extstorage3+rdbfix1+kvmfix2-1
1081

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

    
1092
.. code-block:: console
1093

    
1094
    root@node1:~ # gnt-cluster init --enabled-hypervisors=kvm --no-ssh-init \
1095
                    --no-etc-hosts --vg-name=ganeti --nic-parameters link=br0 \
1096
                    --master-netdev eth0 ganeti.node1.example.com
1097
    root@node1:~ # gnt-cluster modify --default-iallocator hail
1098
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:kernel_path=
1099
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:vnc_bind_address=0.0.0.0
1100

    
1101
    root@node1:~ # gnt-node add --no-ssh-key-check --master-capable=yes \
1102
                    --vm-capable=yes node2.example.com
1103
    root@node1:~ # gnt-cluster modify --disk-parameters=drbd:metavg=ganeti
1104
    root@node1:~ # gnt-group modify --disk-parameters=drbd:metavg=ganeti default
1105

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

    
1110
.. _cyclades-install-snfimage:
1111

    
1112
snf-image
1113
---------
1114

    
1115
Installation
1116
~~~~~~~~~~~~
1117
For :ref:`Cyclades <cyclades>` to be able to launch VMs from specified Images,
1118
you need the :ref:`snf-image <snf-image>` OS Definition installed on *all*
1119
VM-capable Ganeti nodes. This means we need :ref:`snf-image <snf-image>` on
1120
node1 and node2. You can do this by running on *both* nodes:
1121

    
1122
.. code-block:: console
1123

    
1124
   # apt-get install snf-image snf-pithos-backend python-psycopg2
1125

    
1126
snf-image also needs the `snf-pithos-backend <snf-pithos-backend>`, to be able
1127
to handle image files stored on Pithos. It also needs `python-psycopg2` to be
1128
able to access the Pithos database. This is why, we also install them on *all*
1129
VM-capable Ganeti nodes.
1130

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

    
1136
After `snf-image` has been installed successfully, create the helper VM by
1137
running on *both* nodes:
1138

    
1139
.. code-block:: console
1140

    
1141
   # snf-image-update-helper
1142

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

    
1147
Configuration
1148
~~~~~~~~~~~~~
1149
snf-image supports native access to Images stored on Pithos. This means that
1150
it can talk directly to the Pithos backend, without the need of providing a
1151
public URL. More details, are described in the next section. For now, the only
1152
thing we need to do, is configure snf-image to access our Pithos backend.
1153

    
1154
To do this, we need to set the corresponding variables in
1155
``/etc/default/snf-image``, to reflect our Pithos setup:
1156

    
1157
.. code-block:: console
1158

    
1159
    PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
1160

    
1161
    PITHOS_DATA="/srv/pithos/data"
1162

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

    
1166
If you would like to use Images that are also/only stored locally, you need to
1167
save them under ``IMAGE_DIR``, however this guide targets Images stored only on
1168
Pithos.
1169

    
1170
Testing
1171
~~~~~~~
1172
You can test that snf-image is successfully installed by running on the
1173
:ref:`GANETI-MASTER <GANETI_NODES>` (in our case node1):
1174

    
1175
.. code-block:: console
1176

    
1177
   # gnt-os diagnose
1178

    
1179
This should return ``valid`` for snf-image.
1180

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

    
1187
.. _snf-image-images:
1188

    
1189
Actual Images for snf-image
1190
---------------------------
1191

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

    
1198
:ref:`snf-image <snf-image>` also supports three (3) different locations for the
1199
above Images to be stored:
1200

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

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

    
1211
To do so, do the following:
1212

    
1213
a) Download the Image from the official snf-image page.
1214

    
1215
b) Upload the Image to your Pithos installation, either using the Pithos Web
1216
   UI or the command line client `kamaki
1217
   <http://www.synnefo.org/docs/kamaki/latest/index.html>`_.
1218

    
1219
Once the Image is uploaded successfully, download the Image's metadata file
1220
from the official snf-image page. You will need it, for spawning a VM from
1221
Ganeti, in the next section.
1222

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

    
1227
.. _ganeti-with-pithos-images:
1228

    
1229
Spawning a VM from a Pithos Image, using Ganeti
1230
-----------------------------------------------
1231

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

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

    
1240
.. code-block:: console
1241

    
1242
   # gnt-instance add -o snf-image+default --os-parameters \
1243
                      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"}' \
1244
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1245
                      testvm1
1246

    
1247
In the above command:
1248

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

    
1260
If the ``gnt-instance add`` command returns successfully, then run:
1261

    
1262
.. code-block:: console
1263

    
1264
   # gnt-instance info testvm1 | grep "console connection"
1265

    
1266
to find out where to connect using VNC. If you can connect successfully and can
1267
login to your new instance using the root password ``my_vm_example_passw0rd``,
1268
then everything works as expected and you have your new Debian Base VM up and
1269
running.
1270

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

    
1280
If everything works, you have successfully connected Ganeti with Pithos. Let's
1281
move on to networking now.
1282

    
1283
.. warning::
1284

    
1285
    You can bypass the networking sections and go straight to
1286
    :ref:`Cyclades Ganeti tools <cyclades-gtools>`, if you do not want to setup
1287
    the Cyclades Network Service, but only the Cyclades Compute Service
1288
    (recommended for now).
1289

    
1290
Networking Setup Overview
1291
-------------------------
1292

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

    
1299
Since synnefo 0.11 all network actions are managed with the snf-manage
1300
network-* commands. This needs the underlying setup (Ganeti, nfdhcpd,
1301
snf-network, bridges, vlans) to be already configured correctly. The only
1302
actions needed in this point are:
1303

    
1304
a) Have Ganeti with IP pool management support installed.
1305

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

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

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

    
1314
.. _snf-network:
1315

    
1316
snf-network
1317
~~~~~~~~~~~
1318

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

    
1324
Install snf-network on all Ganeti nodes:
1325

    
1326
.. code-block:: console
1327

    
1328
   # apt-get install snf-network
1329

    
1330
Then, in :file:`/etc/default/snf-network` set:
1331

    
1332
.. code-block:: console
1333

    
1334
   MAC_MASK=ff:ff:f0:00:00:00
1335

    
1336
.. _nfdhcpd:
1337

    
1338
nfdhcpd
1339
~~~~~~~
1340

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

    
1346
.. code-block:: console
1347

    
1348
   # apt-get install nfqueue-bindings-python=0.3+physindev-1
1349
   # apt-get install nfdhcpd
1350

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

    
1356
.. code-block:: console
1357

    
1358
   # /etc/init.d/nfdhcpd restart
1359

    
1360
If you are using ``ferm``, then you need to run the following:
1361

    
1362
.. code-block:: console
1363

    
1364
   # echo "@include 'nfdhcpd.ferm';" >> /etc/ferm/ferm.conf
1365
   # /etc/init.d/ferm restart
1366

    
1367
or make sure to run after boot:
1368

    
1369
.. code-block:: console
1370

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

    
1373
and if you have IPv6 enabled:
1374

    
1375
.. code-block:: console
1376

    
1377
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 133 -j NFQUEUE --queue-num 43
1378
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 135 -j NFQUEUE --queue-num 44
1379

    
1380
You can check which clients are currently served by nfdhcpd by running:
1381

    
1382
.. code-block:: console
1383

    
1384
   # kill -SIGUSR1 `cat /var/run/nfdhcpd/nfdhcpd.pid`
1385

    
1386
When you run the above, then check ``/var/log/nfdhcpd/nfdhcpd.log``.
1387

    
1388
Public Network Setup
1389
--------------------
1390

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

    
1397
Physical Host Setup
1398
~~~~~~~~~~~~~~~~~~~
1399

    
1400
Assuming ``eth0`` on both hosts is the public interface (directly connected
1401
to the router), run on every node:
1402

    
1403
.. code-block:: console
1404

    
1405
   # apt-get install vlan
1406
   # brctl addbr br0
1407
   # ip link set br0 up
1408
   # vconfig add eth0 100
1409
   # ip link set eth0.100 up
1410
   # brctl addif br0 eth0.100
1411

    
1412

    
1413
Testing a Public Network
1414
~~~~~~~~~~~~~~~~~~~~~~~~
1415

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

    
1420
.. code-block:: console
1421

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

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

    
1427
.. code-block:: console
1428

    
1429
   # gnt-network connect test-net-public default bridged br0
1430

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

    
1436
.. code-block:: console
1437

    
1438
   # gnt-instance add -o snf-image+default --os-parameters \
1439
                      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"}' \
1440
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1441
                      --net 0:ip=pool,network=test-net-public \
1442
                      testvm2
1443

    
1444
If the above returns successfully, connect to the new VM and run:
1445

    
1446
.. code-block:: console
1447

    
1448
   root@testvm2:~ # ip addr
1449
   root@testvm2:~ # ip route
1450
   root@testvm2:~ # cat /etc/resolv.conf
1451

    
1452
to check IP address (5.6.7.2), IP routes (default via 5.6.7.1) and DNS config
1453
(nameserver option in nfdhcpd.conf). This shows correct configuration of
1454
ganeti, snf-network and nfdhcpd.
1455

    
1456
Now ping the outside world. If this works too, then you have also configured
1457
correctly your physical host and router.
1458

    
1459
Make sure everything works as expected, before proceeding with the Private
1460
Networks setup.
1461

    
1462
.. _private-networks-setup:
1463

    
1464
Private Networks Setup
1465
----------------------
1466

    
1467
Synnefo supports two types of private networks:
1468

    
1469
 - based on MAC filtering
1470
 - based on physical VLANs
1471

    
1472
Both types provide Layer 2 isolation to the end-user.
1473

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

    
1480
Physical Host Setup
1481
~~~~~~~~~~~~~~~~~~~
1482

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

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

    
1490
.. code-block:: console
1491

    
1492
   # modprobe 8021q
1493
   # $iface=eth0
1494
   # for prv in $(seq 0 20); do
1495
        vlan=$prv
1496
        bridge=prv$prv
1497
        vconfig add $iface $vlan
1498
        ifconfig $iface.$vlan up
1499
        brctl addbr $bridge
1500
        brctl setfd $bridge 0
1501
        brctl addif $bridge $iface.$vlan
1502
        ifconfig $bridge up
1503
      done
1504

    
1505
The above will do the following :
1506

    
1507
 * provision 21 new bridges: ``prv0`` - ``prv20``
1508
 * provision 21 new vlans: ``eth0.0`` - ``eth0.20``
1509
 * add the corresponding vlan to the equivalent bridge
1510

    
1511
You can run ``brctl show`` on both nodes to see if everything was setup
1512
correctly.
1513

    
1514
Testing the Private Networks
1515
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1516

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

    
1522
We run the same command as in the Public Network testing section, but with one
1523
more argument for the second NIC:
1524

    
1525
.. code-block:: console
1526

    
1527
   # 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
1528
   # gnt-network connect test-net-prv-mac default bridged prv0
1529

    
1530
   # gnt-network add --network=10.0.0.0/24 --tags=nfdhcpd --network-type=private test-net-prv-vlan
1531
   # gnt-network connect test-net-prv-vlan default bridged prv1
1532

    
1533
   # gnt-instance add -o snf-image+default --os-parameters \
1534
                      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"}' \
1535
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1536
                      --net 0:ip=pool,network=test-net-public \
1537
                      --net 1:ip=pool,network=test-net-prv-mac \
1538
                      --net 2:ip=none,network=test-net-prv-vlan \
1539
                      testvm3
1540

    
1541
   # gnt-instance add -o snf-image+default --os-parameters \
1542
                      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"}' \
1543
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1544
                      --net 0:ip=pool,network=test-net-public \
1545
                      --net 1:ip=pool,network=test-net-prv-mac \
1546
                      --net 2:ip=none,network=test-net-prv-vlan \
1547
                      testvm4
1548

    
1549
Above, we create two instances with first NIC connected to the internet, their
1550
second NIC connected to a MAC filtered private Network and their third NIC
1551
connected to the first Physical VLAN Private Network. Now, connect to the
1552
instances using VNC and make sure everything works as expected:
1553

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

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

    
1559
 c) ip link set ``eth1``/``eth2`` up
1560

    
1561
 d) dhclient ``eth1``/``eth2``
1562

    
1563
 e) On testvm3  ping 192.168.1.2/10.0.0.2
1564

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

    
1568
.. _cyclades-gtools:
1569

    
1570
Cyclades Ganeti tools
1571
---------------------
1572

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

    
1577
.. code-block:: console
1578

    
1579
   # apt-get install snf-cyclades-gtools
1580

    
1581
This will install the following:
1582

    
1583
 * ``snf-ganeti-eventd`` (daemon to publish Ganeti related messages on RabbitMQ)
1584
 * ``snf-ganeti-hook`` (all necessary hooks under ``/etc/ganeti/hooks``)
1585
 * ``snf-progress-monitor`` (used by ``snf-image`` to publish progress messages)
1586

    
1587
Configure ``snf-cyclades-gtools``
1588
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1589

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

    
1594
.. code-block:: console
1595

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

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

    
1601
Connect ``snf-image`` with ``snf-progress-monitor``
1602
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1603

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

    
1608
.. code-block:: console
1609

    
1610
   PROGRESS_MONITOR="snf-progress-monitor"
1611

    
1612
This file should be editted in all Ganeti nodes.
1613

    
1614
.. _rapi-user:
1615

    
1616
Synnefo RAPI user
1617
-----------------
1618

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

    
1624
.. code-block:: console
1625

    
1626
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1627

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

    
1630
.. code-block:: console
1631

    
1632
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1633

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

    
1637
You have now finished with all needed Prerequisites for Cyclades. Let's move on
1638
to the actual Cyclades installation.
1639

    
1640

    
1641
Installation of Cyclades on node1
1642
=================================
1643

    
1644
This section describes the installation of Cyclades. Cyclades is Synnefo's
1645
Compute service. The Image Service will get installed automatically along with
1646
Cyclades, because it is contained in the same Synnefo component.
1647

    
1648
We will install Cyclades on node1. To do so, we install the corresponding
1649
package by running on node1:
1650

    
1651
.. code-block:: console
1652

    
1653
   # apt-get install snf-cyclades-app memcached python-memcache
1654

    
1655
If all packages install successfully, then Cyclades are installed and we
1656
proceed with their configuration.
1657

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

    
1665
Configuration of Cyclades
1666
=========================
1667

    
1668
Conf files
1669
----------
1670

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

    
1678
Edit ``/etc/synnefo/20-snf-cyclades-app-api.conf``:
1679

    
1680
.. code-block:: console
1681

    
1682
   CYCLADES_BASE_URL = 'https://node1.example.com/cyclades'
1683
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
1684

    
1685
   # Set to False if astakos & cyclades are on the same host
1686
   CYCLADES_PROXY_USER_SERVICES = False
1687

    
1688
   CYCLADES_SERVICE_TOKEN = 'cyclades_service_token22w'
1689

    
1690
The ``ASTAKOS_BASE_URL`` denotes the Astakos endpoint for Cyclades,
1691
which is used for all user management, including authentication.
1692
Since our Astakos, Cyclades, and Pithos installations belong together,
1693
they should all have identical ``ASTAKOS_BASE_URL`` setting
1694
(see also, :ref:`previously <conf-pithos>`).
1695

    
1696
The ``CYCLADES_BASE_URL`` setting must point to the top-level Cyclades URL.
1697
Appending an extra path (``/cyclades`` here) is recommended in order to
1698
distinguish components, if more than one are installed on the same machine.
1699

    
1700
The ``CYCLADES_SERVICE_TOKEN`` is the token used for authentication with astakos.
1701
It can be retrieved by running on the Astakos node (node1 in our case):
1702

    
1703
.. code-block:: console
1704

    
1705
   # snf-manage component-list
1706

    
1707
The token has been generated automatically during the :ref:`Cyclades service
1708
registration <services-reg>`.
1709

    
1710
TODO: Document the Network Options here
1711

    
1712
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1713

    
1714
.. code-block:: console
1715

    
1716
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1717
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
1718
   CLOUDBAR_MENU_URL = 'https://account.node1.example.com/astakos/ui/get_menu'
1719

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

    
1728
Edit ``/etc/synnefo/20-snf-cyclades-app-plankton.conf``:
1729

    
1730
.. code-block:: console
1731

    
1732
   BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1733
   BACKEND_BLOCK_PATH = '/srv/pithos/data/'
1734

    
1735
In this file we configure the Image Service. ``BACKEND_DB_CONNECTION``
1736
denotes the Pithos database (where the Image files are stored). So we set that
1737
to point to our Pithos database. ``BACKEND_BLOCK_PATH`` denotes the actual
1738
Pithos data location.
1739

    
1740
Edit ``/etc/synnefo/20-snf-cyclades-app-queues.conf``:
1741

    
1742
.. code-block:: console
1743

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

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

    
1750
Edit ``/etc/synnefo/20-snf-cyclades-app-ui.conf``:
1751

    
1752
.. code-block:: console
1753

    
1754
   UI_LOGIN_URL = "https://node1.example.com/ui/login"
1755
   UI_LOGOUT_URL = "https://node1.example.com/ui/logout"
1756

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

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

    
1763
Edit ``/etc/synnefo/20-snf-cyclades-app-vmapi.conf``:
1764

    
1765
.. code-block:: console
1766

    
1767
   VMAPI_CACHE_BACKEND = "memcached://127.0.0.1:11211/?timeout=3600"
1768

    
1769
Edit ``/etc/default/vncauthproxy``:
1770

    
1771
.. code-block:: console
1772

    
1773
   CHUID="nobody:www-data"
1774

    
1775
We have now finished with the basic Cyclades configuration.
1776

    
1777
Database Initialization
1778
-----------------------
1779

    
1780
Once Cyclades is configured, we sync the database:
1781

    
1782
.. code-block:: console
1783

    
1784
   $ snf-manage syncdb
1785
   $ snf-manage migrate
1786

    
1787
and load the initial server flavors:
1788

    
1789
.. code-block:: console
1790

    
1791
   $ snf-manage loaddata flavors
1792

    
1793
If everything returns successfully, our database is ready.
1794

    
1795
Add the Ganeti backend
1796
----------------------
1797

    
1798
In our installation we assume that we only have one Ganeti cluster, the one we
1799
setup earlier.  At this point you have to add this backend (Ganeti cluster) to
1800
cyclades assuming that you have setup the :ref:`Rapi User <rapi-user>`
1801
correctly.
1802

    
1803
.. code-block:: console
1804

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

    
1807
You can see everything has been setup correctly by running:
1808

    
1809
.. code-block:: console
1810

    
1811
   $ snf-manage backend-list
1812

    
1813
Enable the new backend by running:
1814

    
1815
.. code-block::
1816

    
1817
   $ snf-manage backend-modify --drained False 1
1818

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

    
1825
If something is not set correctly, you can modify the backend with the
1826
``snf-manage backend-modify`` command. If something has gone wrong, you could
1827
modify the backend to reflect the Ganeti installation by running:
1828

    
1829
.. code-block:: console
1830

    
1831
   $ snf-manage backend-modify --clustername "ganeti.node1.example.com"
1832
                               --user=cyclades
1833
                               --pass=example_rapi_passw0rd
1834
                               1
1835

    
1836
``clustername`` denotes the Ganeti-cluster's name. We provide the corresponding
1837
domain that resolves to the master IP, than the IP itself, to ensure Cyclades
1838
can talk to Ganeti even after a Ganeti master-failover.
1839

    
1840
``user`` and ``pass`` denote the RAPI user's username and the RAPI user's
1841
password.  Once we setup the first backend to point at our Ganeti cluster, we
1842
update the Cyclades backends status by running:
1843

    
1844
.. code-block:: console
1845

    
1846
   $ snf-manage backend-update-status
1847

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

    
1852
Add a Public Network
1853
----------------------
1854

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

    
1861
.. code-block:: console
1862

    
1863
   $ snf-manage network-create --subnet=5.6.7.0/27 \
1864
                               --gateway=5.6.7.1 \
1865
                               --subnet6=2001:648:2FFC:1322::/64 \
1866
                               --gateway6=2001:648:2FFC:1322::1 \
1867
                               --public --dhcp --flavor=CUSTOM \
1868
                               --link=br0 --mode=bridged \
1869
                               --name=public_network \
1870
                               --backend-id=1
1871

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

    
1875
.. code-block:: console
1876

    
1877
   $ snf-manage reconcile-networks
1878

    
1879
You can see all available networks by running:
1880

    
1881
.. code-block:: console
1882

    
1883
   $ snf-manage network-list
1884

    
1885
and inspect each network's state by running:
1886

    
1887
.. code-block:: console
1888

    
1889
   $ snf-manage network-inspect <net_id>
1890

    
1891
Finally, you can see the networks from the Ganeti perspective by running on the
1892
Ganeti MASTER:
1893

    
1894
.. code-block:: console
1895

    
1896
   $ gnt-network list
1897
   $ gnt-network info <network_name>
1898

    
1899
Create pools for Private Networks
1900
---------------------------------
1901

    
1902
To prevent duplicate assignment of resources to different private networks,
1903
Cyclades supports two types of pools:
1904

    
1905
 - MAC prefix Pool
1906
 - Bridge Pool
1907

    
1908
As long as those resourses have been provisioned, admin has to define two
1909
these pools in Synnefo:
1910

    
1911

    
1912
.. code-block:: console
1913

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

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

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

    
1920
.. code-block:: console
1921

    
1922
   DEFAULT_MAC_FILTERED_BRIDGE = 'prv0'
1923

    
1924
Servers restart
1925
---------------
1926

    
1927
Restart gunicorn on node1:
1928

    
1929
.. code-block:: console
1930

    
1931
   # /etc/init.d/gunicorn restart
1932

    
1933
Now let's do the final connections of Cyclades with Ganeti.
1934

    
1935
``snf-dispatcher`` initialization
1936
---------------------------------
1937

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

    
1943
.. code-block:: console
1944

    
1945
   SNF_DSPTCH_ENABLE=true
1946

    
1947
and start the daemon:
1948

    
1949
.. code-block:: console
1950

    
1951
   # /etc/init.d/snf-dispatcher start
1952

    
1953
You can see that everything works correctly by tailing its log file
1954
``/var/log/synnefo/dispatcher.log``.
1955

    
1956
``snf-ganeti-eventd`` on GANETI MASTER
1957
--------------------------------------
1958

    
1959
The last step of the Cyclades setup is enabling the ``snf-ganeti-eventd``
1960
daemon (part of the :ref:`Cyclades Ganeti tools <cyclades-gtools>` package).
1961
The daemon is already installed on the GANETI MASTER (node1 in our case).
1962
``snf-ganeti-eventd`` is disabled by default during the ``snf-cyclades-gtools``
1963
installation, so we enable it in its configuration file
1964
``/etc/default/snf-ganeti-eventd``:
1965

    
1966
.. code-block:: console
1967

    
1968
   SNF_EVENTD_ENABLE=true
1969

    
1970
and start the daemon:
1971

    
1972
.. code-block:: console
1973

    
1974
   # /etc/init.d/snf-ganeti-eventd start
1975

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

    
1978
Apply Quota
1979
-----------
1980

    
1981
The following commands will check and fix the integrity of user quota.
1982
In a freshly installed system, these commands have no effect and can be
1983
skipped.
1984

    
1985
.. code-block:: console
1986

    
1987
   node1 # snf-manage quota --sync
1988
   node1 # snf-manage reconcile-resources-astakos --fix
1989
   node2 # snf-manage reconcile-resources-pithos --fix
1990
   node1 # snf-manage reconcile-resources-cyclades --fix
1991

    
1992
If all the above return successfully, then you have finished with the Cyclades
1993
installation and setup.
1994

    
1995
Let's test our installation now.
1996

    
1997

    
1998
Testing of Cyclades
1999
===================
2000

    
2001
Cyclades Web UI
2002
---------------
2003

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

    
2008
 `http://node1.example.com/cyclades/ui/`
2009

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

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

    
2020
Cyclades Images
2021
---------------
2022

    
2023
To test our Cyclades installation, we will use an Image stored on Pithos to
2024
spawn a new VM from the Cyclades interface. We will describe all steps, even
2025
though you may already have uploaded an Image on Pithos from a :ref:`previous
2026
<snf-image-images>` section:
2027

    
2028
 * Upload an Image file to Pithos
2029
 * Register that Image file to Cyclades
2030
 * Spawn a new VM from that Image from the Cyclades Web UI
2031

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

    
2035
Installation of `kamaki`
2036
~~~~~~~~~~~~~~~~~~~~~~~~
2037

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

    
2045
.. code-block:: console
2046

    
2047
   # apt-get install kamaki
2048

    
2049
Configuration of kamaki
2050
~~~~~~~~~~~~~~~~~~~~~~~
2051

    
2052
Now we need to setup kamaki, by adding the appropriate URLs and tokens of our
2053
installation. We do this by running:
2054

    
2055
.. code-block:: console
2056

    
2057
   $ kamaki config set user.url "https://node1.example.com"
2058
   $ kamaki config set compute.url "https://node1.example.com/api/v1.1"
2059
   $ kamaki config set image.url "https://node1.example.com/image"
2060
   $ kamaki config set file.url "https://node2.example.com/v1"
2061
   $ kamaki config set token USER_TOKEN
2062

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

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

    
2068
.. code-block:: console
2069

    
2070
   $ kamaki config list
2071

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

    
2075
.. code-block:: console
2076

    
2077
  $ kamaki user authenticate
2078

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

    
2082
Upload an Image file to Pithos
2083
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2084

    
2085
Now, that we have set up `kamaki` we will upload the Image that we have
2086
downloaded and stored under ``/srv/images/``. Although we can upload the Image
2087
under the root ``Pithos`` container (as you may have done when uploading the
2088
Image from the Pithos Web UI), we will create a new container called ``images``
2089
and store the Image under that container. We do this for two reasons:
2090

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

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

    
2097
We create the new ``images`` container by running:
2098

    
2099
.. code-block:: console
2100

    
2101
   $ kamaki file create images
2102

    
2103
To check if the container has been created, list all containers of your
2104
account:
2105

    
2106
.. code-block:: console
2107

    
2108
  $ kamaki file list
2109

    
2110
Then, we upload the Image file to that container:
2111

    
2112
.. code-block:: console
2113

    
2114
   $ kamaki file upload /srv/images/debian_base-6.0-7-x86_64.diskdump images
2115

    
2116
The first is the local path and the second is the remote container on Pithos.
2117
Check if the file has been uploaded, by listing the container contents:
2118

    
2119
.. code-block:: console
2120

    
2121
  $ kamaki file list images
2122

    
2123
Alternatively check if the new container and file appear on the Pithos Web UI.
2124

    
2125
Register an existing Image file to Cyclades
2126
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2127

    
2128
For the purposes of the following example, we assume that the user UUID is
2129
``u53r-un1qu3-1d``.
2130

    
2131
Once the Image file has been successfully uploaded on Pithos then we register
2132
it to Cyclades, by running:
2133

    
2134
.. code-block:: console
2135

    
2136
   $ kamaki image register "Debian Base" \
2137
                           pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump \
2138
                           --public \
2139
                           --disk-format=diskdump \
2140
                           --property OSFAMILY=linux --property ROOT_PARTITION=1 \
2141
                           --property description="Debian Squeeze Base System" \
2142
                           --property size=451 --property kernel=2.6.32 --property GUI="No GUI" \
2143
                           --property sortorder=1 --property USERS=root --property OS=debian
2144

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

    
2155
``OSFAMILY`` and ``ROOT_PARTITION`` are mandatory because they will be passed
2156
from Cyclades to Ganeti and then `snf-image` (also see
2157
:ref:`previous section <ganeti-with-pithos-images>`). All other properties are
2158
used to show information on the Cyclades UI.
2159

    
2160
Spawn a VM from the Cyclades Web UI
2161
-----------------------------------
2162

    
2163
If the registration completes successfully, then go to the Cyclades Web UI from
2164
your browser at:
2165

    
2166
 `https://node1.example.com/cyclades/ui/`
2167

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

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

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

    
2184
Congratulations. You have successfully installed the whole Synnefo stack and
2185
connected all components. Go ahead in the next section to test the Network
2186
functionality from inside Cyclades and discover even more features.
2187

    
2188
General Testing
2189
===============
2190

    
2191
Notes
2192
=====
2193