Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 26498848

History | View | Annotate | Download (76.2 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
After successful installation of snf-astakos-app, make sure that also
507
snf-webproject has been installed (marked as "Recommended" package). By default
508
Debian installs "Recommended" packages, but if you have changed your
509
configuration and the package didn't install automatically, you should
510
explicitly install it manually running:
511

    
512
.. code-block:: console
513

    
514
   # apt-get install snf-webproject
515

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

    
522

    
523
.. _conf-astakos:
524

    
525
Configuration of Astakos
526
========================
527

    
528
Conf Files
529
----------
530

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

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

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

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

    
548
.. code-block:: console
549

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

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

    
571
.. code-block:: console
572

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

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

    
578
.. code-block:: console
579

    
580
    ASTAKOS_DEFAULT_ADMIN_EMAIL = None
581

    
582
    ASTAKOS_COOKIE_DOMAIN = '.example.com'
583

    
584
    ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
585

    
586
The ``ASTAKOS_COOKIE_DOMAIN`` should be the base url of our domain (for all
587
services). ``ASTAKOS_BASE_URL`` is the astakos top-level URL.
588

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

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

    
598
    .. code-block:: console
599

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

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

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

    
610
.. code-block:: console
611

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

    
614
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
615

    
616
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
617

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

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

    
625
Enable Pooling
626
--------------
627

    
628
This section can be bypassed, but we strongly recommend you apply the following,
629
since they result in a significant performance boost.
630

    
631
Synnefo includes a pooling DBAPI driver for PostgreSQL, as a thin wrapper
632
around Psycopg2. This allows independent Django requests to reuse pooled DB
633
connections, with significant performance gains.
634

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

    
638
.. code-block:: console
639

    
640
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
641
    monkey_patch_psycopg2()
642

    
643
Since we are running with greenlets, we should modify psycopg2 behavior, so it
644
works properly in a greenlet context:
645

    
646
.. code-block:: console
647

    
648
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
649
    make_psycopg_green()
650

    
651
Use the Psycopg2 driver as usual. For Django, this means using
652
``django.db.backends.postgresql_psycopg2`` without any modifications. To enable
653
connection pooling, pass a nonzero ``synnefo_poolsize`` option to the DBAPI
654
driver, through ``DATABASES.OPTIONS`` in Django.
655

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

    
659
.. code-block:: console
660

    
661
    # Monkey-patch psycopg2
662
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
663
    monkey_patch_psycopg2()
664

    
665
    # If running with greenlets
666
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
667
    make_psycopg_green()
668

    
669
    DATABASES = {
670
     'default': {
671
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
672
         'ENGINE': 'postgresql_psycopg2',
673
         'OPTIONS': {'synnefo_poolsize': 8},
674

    
675
         # ATTENTION: This *must* be the absolute path if using sqlite3.
676
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
677
         'NAME': 'snf_apps',
678
         'USER': 'synnefo',                      # Not used with sqlite3.
679
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
680
         # Set to empty string for localhost. Not used with sqlite3.
681
         'HOST': '4.3.2.1',
682
         # Set to empty string for default. Not used with sqlite3.
683
         'PORT': '5432',
684
     }
685
    }
686

    
687
Database Initialization
688
-----------------------
689

    
690
After configuration is done, we initialize the database by running:
691

    
692
.. code-block:: console
693

    
694
    # snf-manage syncdb
695

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

    
700
.. code-block:: console
701

    
702
    # snf-manage migrate im
703
    # snf-manage migrate quotaholder_app
704

    
705
Then, we load the pre-defined user groups
706

    
707
.. code-block:: console
708

    
709
    # snf-manage loaddata groups
710

    
711
.. _services-reg:
712

    
713
Services Registration
714
---------------------
715

    
716
When the database is ready, we need to register the services. The following
717
command will ask you to register the standard Synnefo components (astakos,
718
cyclades, and pithos) along with the services they provide. Note that you
719
have to register at least astakos in order to have a usable authentication
720
system. For each component, you will be asked to provide its base
721
installation URL as well as the UI URL (to appear in the Cloudbar).
722
Moreover, the command will automatically register the resource definitions
723
offered by the services.
724

    
725
.. code-block:: console
726

    
727
    # snf-register-components
728

    
729
.. note::
730

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

    
736
    .. code-block:: console
737

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

    
750
Setting Default Base Quota for Resources
751
----------------------------------------
752

    
753
We now have to specify the limit on resources that each user can employ
754
(exempting resources offered by projects).
755

    
756
.. code-block:: console
757

    
758
    # snf-manage resource-modify --limit-interactive
759

    
760

    
761
Servers Initialization
762
----------------------
763

    
764
Finally, we initialize the servers on node1:
765

    
766
.. code-block:: console
767

    
768
    root@node1:~ # /etc/init.d/gunicorn restart
769
    root@node1:~ # /etc/init.d/apache2 restart
770

    
771
We have now finished the Astakos setup. Let's test it now.
772

    
773

    
774
Testing of Astakos
775
==================
776

    
777
Open your favorite browser and go to:
778

    
779
``http://node1.example.com/astakos``
780

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

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

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

    
792
.. code-block:: console
793

    
794
    root@node1:~ # snf-manage user-list
795

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

    
800
.. code-block:: console
801

    
802
    root@node1:~ # snf-manage user-modify 1 --verify --accept
803

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

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

    
817
Let's continue to install Pithos now.
818

    
819

    
820
Installation of Pithos on node2
821
===============================
822

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

    
827
.. code-block:: console
828

    
829
   # apt-get install snf-pithos-app snf-pithos-backend
830

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

    
836
.. code-block:: console
837

    
838
   # apt-get install snf-pithos-webclient
839

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

    
844

    
845
.. _conf-pithos:
846

    
847
Configuration of Pithos
848
=======================
849

    
850
Conf Files
851
----------
852

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

    
859
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
860
this options:
861

    
862
.. code-block:: console
863

    
864
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
865

    
866
   PITHOS_BASE_URL = 'https://node2.example.com/pithos'
867
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
868
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
869

    
870
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w'
871

    
872
   # Set to False if astakos & pithos are on the same host
873
   #PITHOS_PROXY_USER_SERVICES = True
874

    
875

    
876
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the Pithos app where to
877
find the Pithos backend database. Above we tell Pithos that its database is
878
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
879
``example_passw0rd``.  All those settings where setup during node1's "Database
880
setup" section.
881

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

    
887
The ``ASTAKOS_BASE_URL`` option informs the Pithos app where Astakos is.
888
The Astakos service is used for user management (authentication, quotas, etc.)
889

    
890
The ``PITHOS_BASE_URL`` setting must point to the top-level Pithos URL.
891

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

    
895
.. code-block:: console
896

    
897
   # snf-manage component-list
898

    
899
The token has been generated automatically during the :ref:`Pithos service
900
registration <services-reg>`.
901

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

    
905
.. code-block:: console
906

    
907
    PITHOS_UI_LOGIN_URL = "https://node1.example.com/ui/login?next="
908
    PITHOS_UI_FEEDBACK_URL = "https://node2.example.com/feedback"
909

    
910
The ``PITHOS_UI_LOGIN_URL`` option tells the client where to redirect you, if
911
you are not logged in. The ``PITHOS_UI_FEEDBACK_URL`` option points at the
912
Pithos feedback form. Astakos already provides a generic feedback form for all
913
services, so we use this one.
914

    
915
The ``PITHOS_UPDATE_MD5`` option by default disables the computation of the
916
object checksums. This results to improved performance during object uploading.
917
However, if compatibility with the OpenStack Object Storage API is important
918
then it should be changed to ``True``.
919

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

    
923
.. code-block:: console
924

    
925
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
926
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
927
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
928

    
929
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
930
cloudbar.
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

    
994
    27381099d477 -> 4c8ccdc58192 (head), add attributes domain index
995
    2a309a9a3438 -> 27381099d477, alter public add column url
996
    165ba3fbfe53 -> 2a309a9a3438, fix statistics negative population
997
    3dd56e750a3 -> 165ba3fbfe53, update account in paths
998
    230f8ce9c90f -> 3dd56e750a3, Fix latest_version
999
    8320b1c62d9 -> 230f8ce9c90f, alter nodes add column latest version
1000
    None -> 8320b1c62d9, create index nodes.parent
1001

    
1002
Finally, we stamp it with the head found in the previous step:
1003

    
1004
.. code-block:: console
1005

    
1006
    root@node2:~ # pithos-migrate stamp 4c8ccdc58192
1007

    
1008
Servers Initialization
1009
----------------------
1010

    
1011
After configuration is done, we initialize the servers on node2:
1012

    
1013
.. code-block:: console
1014

    
1015
    root@node2:~ # /etc/init.d/gunicorn restart
1016
    root@node2:~ # /etc/init.d/apache2 restart
1017

    
1018
You have now finished the Pithos setup. Let's test it now.
1019

    
1020

    
1021
Testing of Pithos
1022
=================
1023

    
1024
Open your browser and go to the Astakos homepage:
1025

    
1026
``http://node1.example.com/astakos``
1027

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

    
1032

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

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

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

    
1044
If you would like to do more, such as:
1045

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

    
1055
please continue with the rest of the guide.
1056

    
1057

    
1058
Cyclades Prerequisites
1059
======================
1060

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

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

    
1069
Ganeti
1070
------
1071

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

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

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

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

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

    
1095
.. code-block:: console
1096

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

    
1100
You should have:
1101

    
1102
Ganeti >= 2.6.2+ippool11+hotplug5+extstorage3+rdbfix1+kvmfix2-1
1103

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

    
1114
.. code-block:: console
1115

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

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

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

    
1132
.. _cyclades-install-snfimage:
1133

    
1134
snf-image
1135
---------
1136

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

    
1144
.. code-block:: console
1145

    
1146
   # apt-get install snf-image snf-pithos-backend python-psycopg2
1147

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

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

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

    
1161
.. code-block:: console
1162

    
1163
   # snf-image-update-helper
1164

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

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

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

    
1179
.. code-block:: console
1180

    
1181
    PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
1182

    
1183
    PITHOS_DATA="/srv/pithos/data"
1184

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

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

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

    
1197
.. code-block:: console
1198

    
1199
   # gnt-os diagnose
1200

    
1201
This should return ``valid`` for snf-image.
1202

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

    
1209
.. _snf-image-images:
1210

    
1211
Actual Images for snf-image
1212
---------------------------
1213

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

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

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

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

    
1233
To do so, do the following:
1234

    
1235
a) Download the Image from the official snf-image page.
1236

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

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

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

    
1249
.. _ganeti-with-pithos-images:
1250

    
1251
Spawning a VM from a Pithos Image, using Ganeti
1252
-----------------------------------------------
1253

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

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

    
1262
.. code-block:: console
1263

    
1264
   # gnt-instance add -o snf-image+default --os-parameters \
1265
                      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"}' \
1266
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1267
                      testvm1
1268

    
1269
In the above command:
1270

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

    
1282
If the ``gnt-instance add`` command returns successfully, then run:
1283

    
1284
.. code-block:: console
1285

    
1286
   # gnt-instance info testvm1 | grep "console connection"
1287

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

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

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

    
1305
.. warning::
1306

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

    
1312
Networking Setup Overview
1313
-------------------------
1314

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

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

    
1326
a) Have Ganeti with IP pool management support installed.
1327

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

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

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

    
1336
.. _snf-network:
1337

    
1338
snf-network
1339
~~~~~~~~~~~
1340

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

    
1346
Install snf-network on all Ganeti nodes:
1347

    
1348
.. code-block:: console
1349

    
1350
   # apt-get install snf-network
1351

    
1352
Then, in :file:`/etc/default/snf-network` set:
1353

    
1354
.. code-block:: console
1355

    
1356
   MAC_MASK=ff:ff:f0:00:00:00
1357

    
1358
.. _nfdhcpd:
1359

    
1360
nfdhcpd
1361
~~~~~~~
1362

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

    
1368
.. code-block:: console
1369

    
1370
   # apt-get install nfqueue-bindings-python=0.3+physindev-1
1371
   # apt-get install nfdhcpd
1372

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

    
1378
.. code-block:: console
1379

    
1380
   # /etc/init.d/nfdhcpd restart
1381

    
1382
If you are using ``ferm``, then you need to run the following:
1383

    
1384
.. code-block:: console
1385

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

    
1389
or make sure to run after boot:
1390

    
1391
.. code-block:: console
1392

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

    
1395
and if you have IPv6 enabled:
1396

    
1397
.. code-block:: console
1398

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

    
1402
You can check which clients are currently served by nfdhcpd by running:
1403

    
1404
.. code-block:: console
1405

    
1406
   # kill -SIGUSR1 `cat /var/run/nfdhcpd/nfdhcpd.pid`
1407

    
1408
When you run the above, then check ``/var/log/nfdhcpd/nfdhcpd.log``.
1409

    
1410
Public Network Setup
1411
--------------------
1412

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

    
1419
Physical Host Setup
1420
~~~~~~~~~~~~~~~~~~~
1421

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

    
1425
.. code-block:: console
1426

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

    
1434

    
1435
Testing a Public Network
1436
~~~~~~~~~~~~~~~~~~~~~~~~
1437

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

    
1442
.. code-block:: console
1443

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

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

    
1449
.. code-block:: console
1450

    
1451
   # gnt-network connect test-net-public default bridged br0
1452

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

    
1458
.. code-block:: console
1459

    
1460
   # gnt-instance add -o snf-image+default --os-parameters \
1461
                      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"}' \
1462
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1463
                      --net 0:ip=pool,network=test-net-public \
1464
                      testvm2
1465

    
1466
If the above returns successfully, connect to the new VM and run:
1467

    
1468
.. code-block:: console
1469

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

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

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

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

    
1484
.. _private-networks-setup:
1485

    
1486
Private Networks Setup
1487
----------------------
1488

    
1489
Synnefo supports two types of private networks:
1490

    
1491
 - based on MAC filtering
1492
 - based on physical VLANs
1493

    
1494
Both types provide Layer 2 isolation to the end-user.
1495

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

    
1502
Physical Host Setup
1503
~~~~~~~~~~~~~~~~~~~
1504

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

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

    
1512
.. code-block:: console
1513

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

    
1527
The above will do the following :
1528

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

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

    
1536
Testing the Private Networks
1537
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1538

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

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

    
1547
.. code-block:: console
1548

    
1549
   # 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
1550
   # gnt-network connect test-net-prv-mac default bridged prv0
1551

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

    
1555
   # gnt-instance add -o snf-image+default --os-parameters \
1556
                      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"}' \
1557
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1558
                      --net 0:ip=pool,network=test-net-public \
1559
                      --net 1:ip=pool,network=test-net-prv-mac \
1560
                      --net 2:ip=none,network=test-net-prv-vlan \
1561
                      testvm3
1562

    
1563
   # gnt-instance add -o snf-image+default --os-parameters \
1564
                      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"}' \
1565
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1566
                      --net 0:ip=pool,network=test-net-public \
1567
                      --net 1:ip=pool,network=test-net-prv-mac \
1568
                      --net 2:ip=none,network=test-net-prv-vlan \
1569
                      testvm4
1570

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

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

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

    
1581
 c) ip link set ``eth1``/``eth2`` up
1582

    
1583
 d) dhclient ``eth1``/``eth2``
1584

    
1585
 e) On testvm3  ping 192.168.1.2/10.0.0.2
1586

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

    
1590
.. _cyclades-gtools:
1591

    
1592
Cyclades Ganeti tools
1593
---------------------
1594

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

    
1599
.. code-block:: console
1600

    
1601
   # apt-get install snf-cyclades-gtools
1602

    
1603
This will install the following:
1604

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

    
1609
Configure ``snf-cyclades-gtools``
1610
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1611

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

    
1616
.. code-block:: console
1617

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

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

    
1623
Connect ``snf-image`` with ``snf-progress-monitor``
1624
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1625

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

    
1630
.. code-block:: console
1631

    
1632
   PROGRESS_MONITOR="snf-progress-monitor"
1633

    
1634
This file should be editted in all Ganeti nodes.
1635

    
1636
.. _rapi-user:
1637

    
1638
Synnefo RAPI user
1639
-----------------
1640

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

    
1646
.. code-block:: console
1647

    
1648
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1649

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

    
1652
.. code-block:: console
1653

    
1654
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1655

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

    
1659
You have now finished with all needed Prerequisites for Cyclades. Let's move on
1660
to the actual Cyclades installation.
1661

    
1662

    
1663
Installation of Cyclades on node1
1664
=================================
1665

    
1666
This section describes the installation of Cyclades. Cyclades is Synnefo's
1667
Compute service. The Image Service will get installed automatically along with
1668
Cyclades, because it is contained in the same Synnefo component.
1669

    
1670
We will install Cyclades on node1. To do so, we install the corresponding
1671
package by running on node1:
1672

    
1673
.. code-block:: console
1674

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

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

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

    
1687
Configuration of Cyclades
1688
=========================
1689

    
1690
Conf files
1691
----------
1692

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

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

    
1702
.. code-block:: console
1703

    
1704
   CYCLADES_BASE_URL = 'https://node1.example.com/cyclades'
1705
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
1706

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

    
1710
   CYCLADES_SERVICE_TOKEN = 'cyclades_service_token22w'
1711

    
1712
The ``ASTAKOS_BASE_URL`` denotes the Astakos endpoint for Cyclades,
1713
which is used for all user management, including authentication.
1714
Since our Astakos, Cyclades, and Pithos installations belong together,
1715
they should all have identical ``ASTAKOS_BASE_URL`` setting
1716
(see also, :ref:`previously <conf-pithos>`).
1717

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

    
1721
.. code-block:: console
1722

    
1723
   # snf-manage component-list
1724

    
1725
The token has been generated automatically during the :ref:`Cyclades service
1726
registration <services-reg>`.
1727

    
1728
TODO: Document the Network Options here
1729

    
1730
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1731

    
1732
.. code-block:: console
1733

    
1734
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1735
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
1736
   CLOUDBAR_MENU_URL = 'https://account.node1.example.com/astakos/ui/get_menu'
1737

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

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

    
1748
.. code-block:: console
1749

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

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

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

    
1760
.. code-block:: console
1761

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

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

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

    
1770
.. code-block:: console
1771

    
1772
   UI_LOGIN_URL = "https://node1.example.com/ui/login"
1773
   UI_LOGOUT_URL = "https://node1.example.com/ui/logout"
1774

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

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

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

    
1783
.. code-block:: console
1784

    
1785
   VMAPI_CACHE_BACKEND = "memcached://127.0.0.1:11211/?timeout=3600"
1786

    
1787
Edit ``/etc/default/vncauthproxy``:
1788

    
1789
.. code-block:: console
1790

    
1791
   CHUID="nobody:www-data"
1792

    
1793
We have now finished with the basic Cyclades configuration.
1794

    
1795
Database Initialization
1796
-----------------------
1797

    
1798
Once Cyclades is configured, we sync the database:
1799

    
1800
.. code-block:: console
1801

    
1802
   $ snf-manage syncdb
1803
   $ snf-manage migrate
1804

    
1805
and load the initial server flavors:
1806

    
1807
.. code-block:: console
1808

    
1809
   $ snf-manage loaddata flavors
1810

    
1811
If everything returns successfully, our database is ready.
1812

    
1813
Add the Ganeti backend
1814
----------------------
1815

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

    
1821
.. code-block:: console
1822

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

    
1825
You can see everything has been setup correctly by running:
1826

    
1827
.. code-block:: console
1828

    
1829
   $ snf-manage backend-list
1830

    
1831
Enable the new backend by running:
1832

    
1833
.. code-block::
1834

    
1835
   $ snf-manage backend-modify --drained False 1
1836

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

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

    
1847
.. code-block:: console
1848

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

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

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

    
1862
.. code-block:: console
1863

    
1864
   $ snf-manage backend-update-status
1865

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

    
1870
Add a Public Network
1871
----------------------
1872

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

    
1879
.. code-block:: console
1880

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

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

    
1893
.. code-block:: console
1894

    
1895
   $ snf-manage reconcile-networks
1896

    
1897
You can see all available networks by running:
1898

    
1899
.. code-block:: console
1900

    
1901
   $ snf-manage network-list
1902

    
1903
and inspect each network's state by running:
1904

    
1905
.. code-block:: console
1906

    
1907
   $ snf-manage network-inspect <net_id>
1908

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

    
1912
.. code-block:: console
1913

    
1914
   $ gnt-network list
1915
   $ gnt-network info <network_name>
1916

    
1917
Create pools for Private Networks
1918
---------------------------------
1919

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

    
1923
 - MAC prefix Pool
1924
 - Bridge Pool
1925

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

    
1929

    
1930
.. code-block:: console
1931

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

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

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

    
1938
.. code-block:: console
1939

    
1940
   DEFAULT_MAC_FILTERED_BRIDGE = 'prv0'
1941

    
1942
Servers restart
1943
---------------
1944

    
1945
Restart gunicorn on node1:
1946

    
1947
.. code-block:: console
1948

    
1949
   # /etc/init.d/gunicorn restart
1950

    
1951
Now let's do the final connections of Cyclades with Ganeti.
1952

    
1953
``snf-dispatcher`` initialization
1954
---------------------------------
1955

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

    
1961
.. code-block:: console
1962

    
1963
   SNF_DSPTCH_ENABLE=true
1964

    
1965
and start the daemon:
1966

    
1967
.. code-block:: console
1968

    
1969
   # /etc/init.d/snf-dispatcher start
1970

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

    
1974
``snf-ganeti-eventd`` on GANETI MASTER
1975
--------------------------------------
1976

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

    
1984
.. code-block:: console
1985

    
1986
   SNF_EVENTD_ENABLE=true
1987

    
1988
and start the daemon:
1989

    
1990
.. code-block:: console
1991

    
1992
   # /etc/init.d/snf-ganeti-eventd start
1993

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

    
1996
Apply Quota
1997
-----------
1998

    
1999
The following commands will check and fix the integrity of user quota.
2000
In a freshly installed system, these commands have no effect and can be
2001
skipped.
2002

    
2003
.. code-block:: console
2004

    
2005
   node1 # snf-manage quota --sync
2006
   node1 # snf-manage reconcile-resources-astakos --fix
2007
   node2 # snf-manage reconcile-resources-pithos --fix
2008
   node1 # snf-manage reconcile-resources-cyclades --fix
2009

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

    
2013
Let's test our installation now.
2014

    
2015

    
2016
Testing of Cyclades
2017
===================
2018

    
2019
Cyclades Web UI
2020
---------------
2021

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

    
2026
 `http://node1.example.com/cyclades/ui/`
2027

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

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

    
2038
Cyclades Images
2039
---------------
2040

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

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

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

    
2053
Installation of `kamaki`
2054
~~~~~~~~~~~~~~~~~~~~~~~~
2055

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

    
2063
.. code-block:: console
2064

    
2065
   # apt-get install kamaki
2066

    
2067
Configuration of kamaki
2068
~~~~~~~~~~~~~~~~~~~~~~~
2069

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

    
2073
.. code-block:: console
2074

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

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

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

    
2086
.. code-block:: console
2087

    
2088
   $ kamaki config list
2089

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

    
2093
.. code-block:: console
2094

    
2095
  $ kamaki user authenticate
2096

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

    
2100
Upload an Image file to Pithos
2101
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2102

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

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

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

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

    
2117
.. code-block:: console
2118

    
2119
   $ kamaki file create images
2120

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

    
2124
.. code-block:: console
2125

    
2126
  $ kamaki file list
2127

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

    
2130
.. code-block:: console
2131

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

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

    
2137
.. code-block:: console
2138

    
2139
  $ kamaki file list images
2140

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

    
2143
Register an existing Image file to Cyclades
2144
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2145

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

    
2149
Once the Image file has been successfully uploaded on Pithos then we register
2150
it to Cyclades, by running:
2151

    
2152
.. code-block:: console
2153

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

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

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

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

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

    
2184
 `https://node1.example.com/cyclades/ui/`
2185

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

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

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

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

    
2206
General Testing
2207
===============
2208

    
2209
Notes
2210
=====
2211