Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 7ae4668e

History | View | Annotate | Download (77.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
.. _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_COOKIE_DOMAIN = '.example.com'
564

    
565
    ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
566

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

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

    
575
    .. code-block:: console
576

    
577
        ASTAKOS_RECAPTCHA_PUBLIC_KEY = 'example_recaptcha_public_key!@#$%^&*('
578
        ASTAKOS_RECAPTCHA_PRIVATE_KEY = 'example_recaptcha_private_key!@#$%^&*('
579
        ASTAKOS_RECAPTCHA_USE_SSL = True
580
        ASTAKOS_RECAPTCHA_ENABLED = True
581

    
582
    For the ``ASTAKOS_RECAPTCHA_PUBLIC_KEY`` and ``ASTAKOS_RECAPTCHA_PRIVATE_KEY``
583
    go to https://www.google.com/recaptcha/admin/create and create your own pair.
584

    
585
Then edit ``/etc/synnefo/20-snf-astakos-app-cloudbar.conf`` :
586

    
587
.. code-block:: console
588

    
589
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
590

    
591
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
592

    
593
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
594

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

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

    
602
.. _email-configuration:
603

    
604
Email delivery configuration
605
----------------------------
606

    
607
Many of the ``astakos`` operations require server to notify service users and 
608
administrators via email. e.g. right after the signup process the service sents 
609
an email to the registered email address containing an email verification url, 
610
after the user verifies the email address astakos once again needs to notify 
611
administrators with a notice that a new account has just been verified.
612

    
613
More specifically astakos sends emails in the following cases
614

    
615
- An email containing a verification link after each signup process.
616
- An email to the people listed in ``ADMINS`` setting after each email 
617
  verification if ``ASTAKOS_MODERATION`` setting is ``True``. The email 
618
  notifies administrators that an additional action is required in order to 
619
  activate the user.
620
- A welcome email to the user email and an admin notification to ``ADMINS`` 
621
  right after each account activation.
622
- Feedback messages submited from astakos contact view and astakos feedback 
623
  API endpoint are sent to contacts listed in ``HELPDESK`` setting.
624
- Project application request notifications to people included in ``HELPDESK`` 
625
  and ``MANAGERS`` settings.
626
- Notifications after each project members action (join request, membership 
627
  accepted/declinde etc.) to project members or project owners.
628

    
629
Astakos uses the Django internal email delivering mechanism to send email 
630
notifications. A simple configuration, using an external smtp server to 
631
deliver messages, is shown below. 
632

    
633
.. code-block:: python
634
    
635
    # /etc/synnefo/10-snf-common-admins.conf
636
    EMAIL_HOST = "mysmtp.server.synnefo.org"
637
    EMAIL_HOST_USER = "<smtpuser>"
638
    EMAIL_HOST_PASSWORD = "<smtppassword>"
639

    
640
    # this gets appended in all email subjects
641
    EMAIL_SUBJECT_PREFIX = "[example.synnefo.org] "
642
    
643
    # Address to use for outgoing emails
644
    DEFAULT_FROM_EMAIL = "server@example.synnefo.org"
645

    
646
    # Email where users can contact for support. This is used in html/email 
647
    # templates.
648
    CONTACT_EMAIL = "server@example.synnefo.org"
649

    
650
    # The email address that error messages come from
651
    SERVER_EMAIL = "server-errors@example.synnefo.org"
652

    
653
Notice that since email settings might be required by applications other than
654
astakos they are defined in a different configuration file than the one
655
previously used to set astakos specific settings. 
656

    
657
Refer to 
658
`Django documentation <https://docs.djangoproject.com/en/1.2/topics/email/>`_
659
for additional information on available email settings.
660

    
661
As refered in the previous section, based on the operation that triggers 
662
an email notification, the recipients list differs. Specifically for 
663
emails whose recipients include contacts from your service team 
664
(administrators, managers, helpdesk etc) synnefo provides the following 
665
settings located in ``10-snf-common-admins.conf``:
666

    
667
.. code-block:: python
668

    
669
    ADMINS = (('Admin name', 'admin@example.synnefo.org'), 
670
              ('Admin2 name', 'admin2@example.synnefo.org))
671
    MANAGERS = (('Manager name', 'manager@example.synnefo.org'),)
672
    HELPDESK = (('Helpdesk user name', 'helpdesk@example.synnefo.org'),)
673

    
674

    
675

    
676
Enable Pooling
677
--------------
678

    
679
This section can be bypassed, but we strongly recommend you apply the following,
680
since they result in a significant performance boost.
681

    
682
Synnefo includes a pooling DBAPI driver for PostgreSQL, as a thin wrapper
683
around Psycopg2. This allows independent Django requests to reuse pooled DB
684
connections, with significant performance gains.
685

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

    
689
.. code-block:: console
690

    
691
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
692
    monkey_patch_psycopg2()
693

    
694
Since we are running with greenlets, we should modify psycopg2 behavior, so it
695
works properly in a greenlet context:
696

    
697
.. code-block:: console
698

    
699
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
700
    make_psycopg_green()
701

    
702
Use the Psycopg2 driver as usual. For Django, this means using
703
``django.db.backends.postgresql_psycopg2`` without any modifications. To enable
704
connection pooling, pass a nonzero ``synnefo_poolsize`` option to the DBAPI
705
driver, through ``DATABASES.OPTIONS`` in Django.
706

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

    
710
.. code-block:: console
711

    
712
    # Monkey-patch psycopg2
713
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
714
    monkey_patch_psycopg2()
715

    
716
    # If running with greenlets
717
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
718
    make_psycopg_green()
719

    
720
    DATABASES = {
721
     'default': {
722
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
723
         'ENGINE': 'postgresql_psycopg2',
724
         'OPTIONS': {'synnefo_poolsize': 8},
725

    
726
         # ATTENTION: This *must* be the absolute path if using sqlite3.
727
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
728
         'NAME': 'snf_apps',
729
         'USER': 'synnefo',                      # Not used with sqlite3.
730
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
731
         # Set to empty string for localhost. Not used with sqlite3.
732
         'HOST': '4.3.2.1',
733
         # Set to empty string for default. Not used with sqlite3.
734
         'PORT': '5432',
735
     }
736
    }
737

    
738
Database Initialization
739
-----------------------
740

    
741
After configuration is done, we initialize the database by running:
742

    
743
.. code-block:: console
744

    
745
    # snf-manage syncdb
746

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

    
751
.. code-block:: console
752

    
753
    # snf-manage migrate im
754
    # snf-manage migrate quotaholder_app
755

    
756
Then, we load the pre-defined user groups
757

    
758
.. code-block:: console
759

    
760
    # snf-manage loaddata groups
761

    
762
.. _services-reg:
763

    
764
Services Registration
765
---------------------
766

    
767
When the database is ready, we need to register the services. The following
768
command will ask you to register the standard Synnefo components (astakos,
769
cyclades, and pithos) along with the services they provide. Note that you
770
have to register at least astakos in order to have a usable authentication
771
system. For each component, you will be asked to provide two URLs: its base
772
URL and its UI URL.
773

    
774
The former is the location where the component resides; it should equal
775
the ``<component_name>_BASE_URL`` as specified in the respective component
776
settings. For example, the base URL for astakos would be
777
``https://node1.example.com/astakos``.
778

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

    
785
The command will also register automatically the resource definitions
786
offered by the services.
787

    
788
.. code-block:: console
789

    
790
    # snf-component-register
791

    
792
.. note::
793

    
794
   This command is equivalent to running the following series of commands;
795
   it registers the three components in astakos and then in each host it
796
   exports the respective service definitions, copies the exported json file
797
   to the astakos host, where it finally imports it:
798

    
799
    .. code-block:: console
800

    
801
       astakos-host$ snf-manage component-add astakos astakos_ui_url
802
       astakos-host$ snf-manage component-add cyclades cyclades_ui_url
803
       astakos-host$ snf-manage component-add pithos pithos_ui_url
804
       astakos-host$ snf-manage service-export-astakos > astakos.json
805
       astakos-host$ snf-manage service-import --json astakos.json
806
       cyclades-host$ snf-manage service-export-cyclades > cyclades.json
807
       # copy the file to astakos-host
808
       astakos-host$ snf-manage service-import --json cyclades.json
809
       pithos-host$ snf-manage service-export-pithos > pithos.json
810
       # copy the file to astakos-host
811
       astakos-host$ snf-manage service-import --json pithos.json
812

    
813
Setting Default Base Quota for Resources
814
----------------------------------------
815

    
816
We now have to specify the limit on resources that each user can employ
817
(exempting resources offered by projects).
818

    
819
.. code-block:: console
820

    
821
    # snf-manage resource-modify --limit-interactive
822

    
823

    
824
Servers Initialization
825
----------------------
826

    
827
Finally, we initialize the servers on node1:
828

    
829
.. code-block:: console
830

    
831
    root@node1:~ # /etc/init.d/gunicorn restart
832
    root@node1:~ # /etc/init.d/apache2 restart
833

    
834
We have now finished the Astakos setup. Let's test it now.
835

    
836

    
837
Testing of Astakos
838
==================
839

    
840
Open your favorite browser and go to:
841

    
842
``http://node1.example.com/astakos``
843

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

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

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

    
855
.. code-block:: console
856

    
857
    root@node1:~ # snf-manage user-list
858

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

    
863
.. code-block:: console
864

    
865
    root@node1:~ # snf-manage user-modify 1 --verify --accept
866

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

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

    
880
Let's continue to install Pithos now.
881

    
882

    
883
Installation of Pithos on node2
884
===============================
885

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

    
890
.. code-block:: console
891

    
892
   # apt-get install snf-pithos-app snf-pithos-backend
893

    
894
Now, install the pithos web interface:
895

    
896
.. code-block:: console
897

    
898
   # apt-get install snf-pithos-webclient
899

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

    
904

    
905
.. _conf-pithos:
906

    
907
Configuration of Pithos
908
=======================
909

    
910
Conf Files
911
----------
912

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

    
919
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
920
this options:
921

    
922
.. code-block:: console
923

    
924
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
925

    
926
   PITHOS_BASE_URL = 'https://node2.example.com/pithos'
927
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
928
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
929

    
930
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w'
931

    
932
   # Set to False if astakos & pithos are on the same host
933
   PITHOS_PROXY_USER_SERVICES = True
934

    
935

    
936
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the Pithos app where to
937
find the Pithos backend database. Above we tell Pithos that its database is
938
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
939
``example_passw0rd``.  All those settings where setup during node1's "Database
940
setup" section.
941

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

    
947
The ``ASTAKOS_BASE_URL`` option informs the Pithos app where Astakos is.
948
The Astakos service is used for user management (authentication, quotas, etc.)
949

    
950
The ``PITHOS_BASE_URL`` setting must point to the top-level Pithos URL.
951

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

    
955
.. code-block:: console
956

    
957
   # snf-manage component-list
958

    
959
The token has been generated automatically during the :ref:`Pithos service
960
registration <services-reg>`.
961

    
962
The ``PITHOS_UPDATE_MD5`` option by default disables the computation of the
963
object checksums. This results to improved performance during object uploading.
964
However, if compatibility with the OpenStack Object Storage API is important
965
then it should be changed to ``True``.
966

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

    
970
.. code-block:: console
971

    
972
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
973
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
974
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
975

    
976
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
977
cloudbar.
978

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

    
983
Pooling and Greenlets
984
---------------------
985

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

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

    
995
.. code-block:: console
996

    
997
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
998
    make_psycopg_green()
999

    
1000
Furthermore, add the ``--worker-class=gevent`` (or ``--worker-class=sync`` as
1001
mentioned above, depending on your setup) argument on your
1002
``/etc/gunicorn.d/synnefo`` configuration file. The file should look something
1003
like this:
1004

    
1005
.. code-block:: console
1006

    
1007
    CONFIG = {
1008
     'mode': 'django',
1009
     'environment': {
1010
       'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
1011
     },
1012
     'working_dir': '/etc/synnefo',
1013
     'user': 'www-data',
1014
     'group': 'www-data',
1015
     'args': (
1016
       '--bind=127.0.0.1:8080',
1017
       '--workers=4',
1018
       '--worker-class=gevent',
1019
       '--log-level=debug',
1020
       '--timeout=43200'
1021
     ),
1022
    }
1023

    
1024
Stamp Database Revision
1025
-----------------------
1026

    
1027
Pithos uses the alembic_ database migrations tool.
1028

    
1029
.. _alembic: http://alembic.readthedocs.org
1030

    
1031
After a successful installation, we should stamp it at the most recent
1032
revision, so that future migrations know where to start upgrading in
1033
the migration history.
1034

    
1035
.. code-block:: console
1036

    
1037
    root@node2:~ # pithos-migrate stamp head
1038

    
1039
Servers Initialization
1040
----------------------
1041

    
1042
After configuration is done, we initialize the servers on node2:
1043

    
1044
.. code-block:: console
1045

    
1046
    root@node2:~ # /etc/init.d/gunicorn restart
1047
    root@node2:~ # /etc/init.d/apache2 restart
1048

    
1049
You have now finished the Pithos setup. Let's test it now.
1050

    
1051

    
1052
Testing of Pithos
1053
=================
1054

    
1055
Open your browser and go to the Astakos homepage:
1056

    
1057
``http://node1.example.com/astakos``
1058

    
1059
Login, and you will see your profile page. Now, click the "pithos" link on the
1060
top black cloudbar. If everything was setup correctly, this will redirect you
1061
to:
1062

    
1063

    
1064
and you will see the blue interface of the Pithos application.  Click the
1065
orange "Upload" button and upload your first file. If the file gets uploaded
1066
successfully, then this is your first sign of a successful Pithos installation.
1067
Go ahead and experiment with the interface to make sure everything works
1068
correctly.
1069

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

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

    
1075
If you would like to do more, such as:
1076

    
1077
    * Spawning VMs
1078
    * Spawning VMs from Images stored on Pithos
1079
    * Uploading your custom Images to Pithos
1080
    * Spawning VMs from those custom Images
1081
    * Registering existing Pithos files as Images
1082
    * Connect VMs to the Internet
1083
    * Create Private Networks
1084
    * Add VMs to Private Networks
1085

    
1086
please continue with the rest of the guide.
1087

    
1088

    
1089
Cyclades Prerequisites
1090
======================
1091

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

    
1097
Besides Astakos and Pithos, you will also need a number of additional working
1098
prerequisites, before you start the Cyclades installation.
1099

    
1100
Ganeti
1101
------
1102

    
1103
`Ganeti <http://code.google.com/p/ganeti/>`_ handles the low level VM management
1104
for Cyclades, so Cyclades requires a working Ganeti installation at the backend.
1105
Please refer to the
1106
`ganeti documentation <http://docs.ganeti.org/ganeti/2.6/html>`_ for all the
1107
gory details. A successful Ganeti installation concludes with a working
1108
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs
1109
<GANETI_NODES>`.
1110

    
1111
The above Ganeti cluster can run on different physical machines than node1 and
1112
node2 and can scale independently, according to your needs.
1113

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

    
1118
We highly recommend that you read the official Ganeti documentation, if you are
1119
not familiar with Ganeti.
1120

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

    
1126
.. code-block:: console
1127

    
1128
   # apt-get install snf-ganeti ganeti-htools
1129
   # rmmod -f drbd && modprobe drbd minor_count=255 usermode_helper=/bin/true
1130

    
1131
You should have:
1132

    
1133
Ganeti >= 2.6.2+ippool11+hotplug5+extstorage3+rdbfix1+kvmfix2-1
1134

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

    
1145
.. code-block:: console
1146

    
1147
    root@node1:~ # gnt-cluster init --enabled-hypervisors=kvm --no-ssh-init \
1148
                    --no-etc-hosts --vg-name=ganeti --nic-parameters link=br0 \
1149
                    --master-netdev eth0 ganeti.node1.example.com
1150
    root@node1:~ # gnt-cluster modify --default-iallocator hail
1151
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:kernel_path=
1152
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:vnc_bind_address=0.0.0.0
1153

    
1154
    root@node1:~ # gnt-node add --no-ssh-key-check --master-capable=yes \
1155
                    --vm-capable=yes node2.example.com
1156
    root@node1:~ # gnt-cluster modify --disk-parameters=drbd:metavg=ganeti
1157
    root@node1:~ # gnt-group modify --disk-parameters=drbd:metavg=ganeti default
1158

    
1159
For any problems you may stumble upon installing Ganeti, please refer to the
1160
`official documentation <http://docs.ganeti.org/ganeti/2.6/html>`_. Installation
1161
of Ganeti is out of the scope of this guide.
1162

    
1163
.. _cyclades-install-snfimage:
1164

    
1165
snf-image
1166
---------
1167

    
1168
Installation
1169
~~~~~~~~~~~~
1170
For :ref:`Cyclades <cyclades>` to be able to launch VMs from specified Images,
1171
you need the :ref:`snf-image <snf-image>` OS Definition installed on *all*
1172
VM-capable Ganeti nodes. This means we need :ref:`snf-image <snf-image>` on
1173
node1 and node2. You can do this by running on *both* nodes:
1174

    
1175
.. code-block:: console
1176

    
1177
   # apt-get install snf-image snf-pithos-backend python-psycopg2
1178

    
1179
snf-image also needs the `snf-pithos-backend <snf-pithos-backend>`, to be able
1180
to handle image files stored on Pithos. It also needs `python-psycopg2` to be
1181
able to access the Pithos database. This is why, we also install them on *all*
1182
VM-capable Ganeti nodes.
1183

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

    
1189
After `snf-image` has been installed successfully, create the helper VM by
1190
running on *both* nodes:
1191

    
1192
.. code-block:: console
1193

    
1194
   # snf-image-update-helper
1195

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

    
1200
Configuration
1201
~~~~~~~~~~~~~
1202
snf-image supports native access to Images stored on Pithos. This means that
1203
it can talk directly to the Pithos backend, without the need of providing a
1204
public URL. More details, are described in the next section. For now, the only
1205
thing we need to do, is configure snf-image to access our Pithos backend.
1206

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

    
1210
.. code-block:: console
1211

    
1212
    PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
1213

    
1214
    PITHOS_DATA="/srv/pithos/data"
1215

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

    
1219
If you would like to use Images that are also/only stored locally, you need to
1220
save them under ``IMAGE_DIR``, however this guide targets Images stored only on
1221
Pithos.
1222

    
1223
Testing
1224
~~~~~~~
1225
You can test that snf-image is successfully installed by running on the
1226
:ref:`GANETI-MASTER <GANETI_NODES>` (in our case node1):
1227

    
1228
.. code-block:: console
1229

    
1230
   # gnt-os diagnose
1231

    
1232
This should return ``valid`` for snf-image.
1233

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

    
1240
.. _snf-image-images:
1241

    
1242
Actual Images for snf-image
1243
---------------------------
1244

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

    
1251
:ref:`snf-image <snf-image>` also supports three (3) different locations for the
1252
above Images to be stored:
1253

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

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

    
1264
To do so, do the following:
1265

    
1266
a) Download the Image from the official snf-image page.
1267

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

    
1272
Once the Image is uploaded successfully, download the Image's metadata file
1273
from the official snf-image page. You will need it, for spawning a VM from
1274
Ganeti, in the next section.
1275

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

    
1280
.. _ganeti-with-pithos-images:
1281

    
1282
Spawning a VM from a Pithos Image, using Ganeti
1283
-----------------------------------------------
1284

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

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

    
1293
.. code-block:: console
1294

    
1295
   # gnt-instance add -o snf-image+default --os-parameters \
1296
                      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"}' \
1297
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1298
                      testvm1
1299

    
1300
In the above command:
1301

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

    
1313
If the ``gnt-instance add`` command returns successfully, then run:
1314

    
1315
.. code-block:: console
1316

    
1317
   # gnt-instance info testvm1 | grep "console connection"
1318

    
1319
to find out where to connect using VNC. If you can connect successfully and can
1320
login to your new instance using the root password ``my_vm_example_passw0rd``,
1321
then everything works as expected and you have your new Debian Base VM up and
1322
running.
1323

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

    
1333
If everything works, you have successfully connected Ganeti with Pithos. Let's
1334
move on to networking now.
1335

    
1336
.. warning::
1337

    
1338
    You can bypass the networking sections and go straight to
1339
    :ref:`Cyclades Ganeti tools <cyclades-gtools>`, if you do not want to setup
1340
    the Cyclades Network Service, but only the Cyclades Compute Service
1341
    (recommended for now).
1342

    
1343
Networking Setup Overview
1344
-------------------------
1345

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

    
1352
Since synnefo 0.11 all network actions are managed with the snf-manage
1353
network-* commands. This needs the underlying setup (Ganeti, nfdhcpd,
1354
snf-network, bridges, vlans) to be already configured correctly. The only
1355
actions needed in this point are:
1356

    
1357
a) Have Ganeti with IP pool management support installed.
1358

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

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

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

    
1367
.. _snf-network:
1368

    
1369
snf-network
1370
~~~~~~~~~~~
1371

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

    
1377
Install snf-network on all Ganeti nodes:
1378

    
1379
.. code-block:: console
1380

    
1381
   # apt-get install snf-network
1382

    
1383
Then, in :file:`/etc/default/snf-network` set:
1384

    
1385
.. code-block:: console
1386

    
1387
   MAC_MASK=ff:ff:f0:00:00:00
1388

    
1389
.. _nfdhcpd:
1390

    
1391
nfdhcpd
1392
~~~~~~~
1393

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

    
1399
.. code-block:: console
1400

    
1401
   # apt-get install nfqueue-bindings-python=0.3+physindev-1
1402
   # apt-get install nfdhcpd
1403

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

    
1409
.. code-block:: console
1410

    
1411
   # /etc/init.d/nfdhcpd restart
1412

    
1413
If you are using ``ferm``, then you need to run the following:
1414

    
1415
.. code-block:: console
1416

    
1417
   # echo "@include 'nfdhcpd.ferm';" >> /etc/ferm/ferm.conf
1418
   # /etc/init.d/ferm restart
1419

    
1420
or make sure to run after boot:
1421

    
1422
.. code-block:: console
1423

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

    
1426
and if you have IPv6 enabled:
1427

    
1428
.. code-block:: console
1429

    
1430
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 133 -j NFQUEUE --queue-num 43
1431
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 135 -j NFQUEUE --queue-num 44
1432

    
1433
You can check which clients are currently served by nfdhcpd by running:
1434

    
1435
.. code-block:: console
1436

    
1437
   # kill -SIGUSR1 `cat /var/run/nfdhcpd/nfdhcpd.pid`
1438

    
1439
When you run the above, then check ``/var/log/nfdhcpd/nfdhcpd.log``.
1440

    
1441
Public Network Setup
1442
--------------------
1443

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

    
1450
Physical Host Setup
1451
~~~~~~~~~~~~~~~~~~~
1452

    
1453
Assuming ``eth0`` on both hosts is the public interface (directly connected
1454
to the router), run on every node:
1455

    
1456
.. code-block:: console
1457

    
1458
   # apt-get install vlan
1459
   # brctl addbr br0
1460
   # ip link set br0 up
1461
   # vconfig add eth0 100
1462
   # ip link set eth0.100 up
1463
   # brctl addif br0 eth0.100
1464

    
1465

    
1466
Testing a Public Network
1467
~~~~~~~~~~~~~~~~~~~~~~~~
1468

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

    
1473
.. code-block:: console
1474

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

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

    
1480
.. code-block:: console
1481

    
1482
   # gnt-network connect test-net-public default bridged br0
1483

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

    
1489
.. code-block:: console
1490

    
1491
   # gnt-instance add -o snf-image+default --os-parameters \
1492
                      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"}' \
1493
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1494
                      --net 0:ip=pool,network=test-net-public \
1495
                      testvm2
1496

    
1497
If the above returns successfully, connect to the new VM and run:
1498

    
1499
.. code-block:: console
1500

    
1501
   root@testvm2:~ # ip addr
1502
   root@testvm2:~ # ip route
1503
   root@testvm2:~ # cat /etc/resolv.conf
1504

    
1505
to check IP address (5.6.7.2), IP routes (default via 5.6.7.1) and DNS config
1506
(nameserver option in nfdhcpd.conf). This shows correct configuration of
1507
ganeti, snf-network and nfdhcpd.
1508

    
1509
Now ping the outside world. If this works too, then you have also configured
1510
correctly your physical host and router.
1511

    
1512
Make sure everything works as expected, before proceeding with the Private
1513
Networks setup.
1514

    
1515
.. _private-networks-setup:
1516

    
1517
Private Networks Setup
1518
----------------------
1519

    
1520
Synnefo supports two types of private networks:
1521

    
1522
 - based on MAC filtering
1523
 - based on physical VLANs
1524

    
1525
Both types provide Layer 2 isolation to the end-user.
1526

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

    
1533
Physical Host Setup
1534
~~~~~~~~~~~~~~~~~~~
1535

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

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

    
1543
.. code-block:: console
1544

    
1545
   # modprobe 8021q
1546
   # $iface=eth0
1547
   # for prv in $(seq 0 20); do
1548
        vlan=$prv
1549
        bridge=prv$prv
1550
        vconfig add $iface $vlan
1551
        ifconfig $iface.$vlan up
1552
        brctl addbr $bridge
1553
        brctl setfd $bridge 0
1554
        brctl addif $bridge $iface.$vlan
1555
        ifconfig $bridge up
1556
      done
1557

    
1558
The above will do the following :
1559

    
1560
 * provision 21 new bridges: ``prv0`` - ``prv20``
1561
 * provision 21 new vlans: ``eth0.0`` - ``eth0.20``
1562
 * add the corresponding vlan to the equivalent bridge
1563

    
1564
You can run ``brctl show`` on both nodes to see if everything was setup
1565
correctly.
1566

    
1567
Testing the Private Networks
1568
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1569

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

    
1575
We run the same command as in the Public Network testing section, but with one
1576
more argument for the second NIC:
1577

    
1578
.. code-block:: console
1579

    
1580
   # 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
1581
   # gnt-network connect test-net-prv-mac default bridged prv0
1582

    
1583
   # gnt-network add --network=10.0.0.0/24 --tags=nfdhcpd --network-type=private test-net-prv-vlan
1584
   # gnt-network connect test-net-prv-vlan default bridged prv1
1585

    
1586
   # gnt-instance add -o snf-image+default --os-parameters \
1587
                      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"}' \
1588
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1589
                      --net 0:ip=pool,network=test-net-public \
1590
                      --net 1:ip=pool,network=test-net-prv-mac \
1591
                      --net 2:ip=none,network=test-net-prv-vlan \
1592
                      testvm3
1593

    
1594
   # gnt-instance add -o snf-image+default --os-parameters \
1595
                      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"}' \
1596
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1597
                      --net 0:ip=pool,network=test-net-public \
1598
                      --net 1:ip=pool,network=test-net-prv-mac \
1599
                      --net 2:ip=none,network=test-net-prv-vlan \
1600
                      testvm4
1601

    
1602
Above, we create two instances with first NIC connected to the internet, their
1603
second NIC connected to a MAC filtered private Network and their third NIC
1604
connected to the first Physical VLAN Private Network. Now, connect to the
1605
instances using VNC and make sure everything works as expected:
1606

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

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

    
1612
 c) ip link set ``eth1``/``eth2`` up
1613

    
1614
 d) dhclient ``eth1``/``eth2``
1615

    
1616
 e) On testvm3  ping 192.168.1.2/10.0.0.2
1617

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

    
1621
.. _cyclades-gtools:
1622

    
1623
Cyclades Ganeti tools
1624
---------------------
1625

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

    
1630
.. code-block:: console
1631

    
1632
   # apt-get install snf-cyclades-gtools
1633

    
1634
This will install the following:
1635

    
1636
 * ``snf-ganeti-eventd`` (daemon to publish Ganeti related messages on RabbitMQ)
1637
 * ``snf-ganeti-hook`` (all necessary hooks under ``/etc/ganeti/hooks``)
1638
 * ``snf-progress-monitor`` (used by ``snf-image`` to publish progress messages)
1639

    
1640
Configure ``snf-cyclades-gtools``
1641
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1642

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

    
1647
.. code-block:: console
1648

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

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

    
1654
Connect ``snf-image`` with ``snf-progress-monitor``
1655
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1656

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

    
1661
.. code-block:: console
1662

    
1663
   PROGRESS_MONITOR="snf-progress-monitor"
1664

    
1665
This file should be editted in all Ganeti nodes.
1666

    
1667
.. _rapi-user:
1668

    
1669
Synnefo RAPI user
1670
-----------------
1671

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

    
1677
.. code-block:: console
1678

    
1679
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1680

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

    
1683
.. code-block:: console
1684

    
1685
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1686

    
1687
More about Ganeti's RAPI users `here.
1688
<http://docs.ganeti.org/ganeti/2.6/html/rapi.html#introduction>`_
1689

    
1690
You have now finished with all needed Prerequisites for Cyclades. Let's move on
1691
to the actual Cyclades installation.
1692

    
1693

    
1694
Installation of Cyclades on node1
1695
=================================
1696

    
1697
This section describes the installation of Cyclades. Cyclades is Synnefo's
1698
Compute service. The Image Service will get installed automatically along with
1699
Cyclades, because it is contained in the same Synnefo component.
1700

    
1701
We will install Cyclades on node1. To do so, we install the corresponding
1702
package by running on node1:
1703

    
1704
.. code-block:: console
1705

    
1706
   # apt-get install snf-cyclades-app memcached python-memcache
1707

    
1708
If all packages install successfully, then Cyclades are installed and we
1709
proceed with their configuration.
1710

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

    
1718
Configuration of Cyclades
1719
=========================
1720

    
1721
Conf files
1722
----------
1723

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

    
1731
Edit ``/etc/synnefo/20-snf-cyclades-app-api.conf``:
1732

    
1733
.. code-block:: console
1734

    
1735
   CYCLADES_BASE_URL = 'https://node1.example.com/cyclades'
1736
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
1737

    
1738
   # Set to False if astakos & cyclades are on the same host
1739
   CYCLADES_PROXY_USER_SERVICES = False
1740

    
1741
   CYCLADES_SERVICE_TOKEN = 'cyclades_service_token22w'
1742

    
1743
The ``ASTAKOS_BASE_URL`` denotes the Astakos endpoint for Cyclades,
1744
which is used for all user management, including authentication.
1745
Since our Astakos, Cyclades, and Pithos installations belong together,
1746
they should all have identical ``ASTAKOS_BASE_URL`` setting
1747
(see also, :ref:`previously <conf-pithos>`).
1748

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

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

    
1756
.. code-block:: console
1757

    
1758
   # snf-manage component-list
1759

    
1760
The token has been generated automatically during the :ref:`Cyclades service
1761
registration <services-reg>`.
1762

    
1763
TODO: Document the Network Options here
1764

    
1765
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1766

    
1767
.. code-block:: console
1768

    
1769
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1770
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
1771
   CLOUDBAR_MENU_URL = 'https://account.node1.example.com/astakos/ui/get_menu'
1772

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

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

    
1783
.. code-block:: console
1784

    
1785
   BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1786
   BACKEND_BLOCK_PATH = '/srv/pithos/data/'
1787

    
1788
In this file we configure the Image Service. ``BACKEND_DB_CONNECTION``
1789
denotes the Pithos database (where the Image files are stored). So we set that
1790
to point to our Pithos database. ``BACKEND_BLOCK_PATH`` denotes the actual
1791
Pithos data location.
1792

    
1793
Edit ``/etc/synnefo/20-snf-cyclades-app-queues.conf``:
1794

    
1795
.. code-block:: console
1796

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

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

    
1803
Edit ``/etc/synnefo/20-snf-cyclades-app-vmapi.conf``:
1804

    
1805
.. code-block:: console
1806

    
1807
   VMAPI_CACHE_BACKEND = "memcached://127.0.0.1:11211/?timeout=3600"
1808

    
1809
Edit ``/etc/default/vncauthproxy``:
1810

    
1811
.. code-block:: console
1812

    
1813
   CHUID="nobody:www-data"
1814

    
1815
We have now finished with the basic Cyclades configuration.
1816

    
1817
Database Initialization
1818
-----------------------
1819

    
1820
Once Cyclades is configured, we sync the database:
1821

    
1822
.. code-block:: console
1823

    
1824
   $ snf-manage syncdb
1825
   $ snf-manage migrate
1826

    
1827
and load the initial server flavors:
1828

    
1829
.. code-block:: console
1830

    
1831
   $ snf-manage loaddata flavors
1832

    
1833
If everything returns successfully, our database is ready.
1834

    
1835
Add the Ganeti backend
1836
----------------------
1837

    
1838
In our installation we assume that we only have one Ganeti cluster, the one we
1839
setup earlier.  At this point you have to add this backend (Ganeti cluster) to
1840
cyclades assuming that you have setup the :ref:`Rapi User <rapi-user>`
1841
correctly.
1842

    
1843
.. code-block:: console
1844

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

    
1847
You can see everything has been setup correctly by running:
1848

    
1849
.. code-block:: console
1850

    
1851
   $ snf-manage backend-list
1852

    
1853
Enable the new backend by running:
1854

    
1855
.. code-block::
1856

    
1857
   $ snf-manage backend-modify --drained False 1
1858

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

    
1865
If something is not set correctly, you can modify the backend with the
1866
``snf-manage backend-modify`` command. If something has gone wrong, you could
1867
modify the backend to reflect the Ganeti installation by running:
1868

    
1869
.. code-block:: console
1870

    
1871
   $ snf-manage backend-modify --clustername "ganeti.node1.example.com"
1872
                               --user=cyclades
1873
                               --pass=example_rapi_passw0rd
1874
                               1
1875

    
1876
``clustername`` denotes the Ganeti-cluster's name. We provide the corresponding
1877
domain that resolves to the master IP, than the IP itself, to ensure Cyclades
1878
can talk to Ganeti even after a Ganeti master-failover.
1879

    
1880
``user`` and ``pass`` denote the RAPI user's username and the RAPI user's
1881
password.  Once we setup the first backend to point at our Ganeti cluster, we
1882
update the Cyclades backends status by running:
1883

    
1884
.. code-block:: console
1885

    
1886
   $ snf-manage backend-update-status
1887

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

    
1892
Add a Public Network
1893
----------------------
1894

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

    
1901
.. code-block:: console
1902

    
1903
   $ snf-manage network-create --subnet=5.6.7.0/27 \
1904
                               --gateway=5.6.7.1 \
1905
                               --subnet6=2001:648:2FFC:1322::/64 \
1906
                               --gateway6=2001:648:2FFC:1322::1 \
1907
                               --public --dhcp --flavor=CUSTOM \
1908
                               --link=br0 --mode=bridged \
1909
                               --name=public_network \
1910
                               --backend-id=1
1911

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

    
1915
.. code-block:: console
1916

    
1917
   $ snf-manage reconcile-networks
1918

    
1919
You can see all available networks by running:
1920

    
1921
.. code-block:: console
1922

    
1923
   $ snf-manage network-list
1924

    
1925
and inspect each network's state by running:
1926

    
1927
.. code-block:: console
1928

    
1929
   $ snf-manage network-inspect <net_id>
1930

    
1931
Finally, you can see the networks from the Ganeti perspective by running on the
1932
Ganeti MASTER:
1933

    
1934
.. code-block:: console
1935

    
1936
   $ gnt-network list
1937
   $ gnt-network info <network_name>
1938

    
1939
Create pools for Private Networks
1940
---------------------------------
1941

    
1942
To prevent duplicate assignment of resources to different private networks,
1943
Cyclades supports two types of pools:
1944

    
1945
 - MAC prefix Pool
1946
 - Bridge Pool
1947

    
1948
As long as those resourses have been provisioned, admin has to define two
1949
these pools in Synnefo:
1950

    
1951

    
1952
.. code-block:: console
1953

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

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

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

    
1960
.. code-block:: console
1961

    
1962
   DEFAULT_MAC_FILTERED_BRIDGE = 'prv0'
1963

    
1964
Servers restart
1965
---------------
1966

    
1967
Restart gunicorn on node1:
1968

    
1969
.. code-block:: console
1970

    
1971
   # /etc/init.d/gunicorn restart
1972

    
1973
Now let's do the final connections of Cyclades with Ganeti.
1974

    
1975
``snf-dispatcher`` initialization
1976
---------------------------------
1977

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

    
1983
.. code-block:: console
1984

    
1985
   SNF_DSPTCH_ENABLE=true
1986

    
1987
and start the daemon:
1988

    
1989
.. code-block:: console
1990

    
1991
   # /etc/init.d/snf-dispatcher start
1992

    
1993
You can see that everything works correctly by tailing its log file
1994
``/var/log/synnefo/dispatcher.log``.
1995

    
1996
``snf-ganeti-eventd`` on GANETI MASTER
1997
--------------------------------------
1998

    
1999
The last step of the Cyclades setup is enabling the ``snf-ganeti-eventd``
2000
daemon (part of the :ref:`Cyclades Ganeti tools <cyclades-gtools>` package).
2001
The daemon is already installed on the GANETI MASTER (node1 in our case).
2002
``snf-ganeti-eventd`` is disabled by default during the ``snf-cyclades-gtools``
2003
installation, so we enable it in its configuration file
2004
``/etc/default/snf-ganeti-eventd``:
2005

    
2006
.. code-block:: console
2007

    
2008
   SNF_EVENTD_ENABLE=true
2009

    
2010
and start the daemon:
2011

    
2012
.. code-block:: console
2013

    
2014
   # /etc/init.d/snf-ganeti-eventd start
2015

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

    
2018
Apply Quota
2019
-----------
2020

    
2021
The following commands will check and fix the integrity of user quota.
2022
In a freshly installed system, these commands have no effect and can be
2023
skipped.
2024

    
2025
.. code-block:: console
2026

    
2027
   node1 # snf-manage quota --sync
2028
   node1 # snf-manage reconcile-resources-astakos --fix
2029
   node2 # snf-manage reconcile-resources-pithos --fix
2030
   node1 # snf-manage reconcile-resources-cyclades --fix
2031

    
2032
If all the above return successfully, then you have finished with the Cyclades
2033
installation and setup.
2034

    
2035
Let's test our installation now.
2036

    
2037

    
2038
Testing of Cyclades
2039
===================
2040

    
2041
Cyclades Web UI
2042
---------------
2043

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

    
2048
 `http://node1.example.com/cyclades/ui/`
2049

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

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

    
2060
Cyclades Images
2061
---------------
2062

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

    
2068
 * Upload an Image file to Pithos
2069
 * Register that Image file to Cyclades
2070
 * Spawn a new VM from that Image from the Cyclades Web UI
2071

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

    
2075
Installation of `kamaki`
2076
~~~~~~~~~~~~~~~~~~~~~~~~
2077

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

    
2085
.. code-block:: console
2086

    
2087
   # apt-get install kamaki
2088

    
2089
Configuration of kamaki
2090
~~~~~~~~~~~~~~~~~~~~~~~
2091

    
2092
Now we need to setup kamaki, by adding the appropriate URLs and tokens of our
2093
installation. We do this by running:
2094

    
2095
.. code-block:: console
2096

    
2097
   $ kamaki config set user.url "https://node1.example.com"
2098
   $ kamaki config set compute.url "https://node1.example.com/api/v1.1"
2099
   $ kamaki config set image.url "https://node1.example.com/image"
2100
   $ kamaki config set file.url "https://node2.example.com/v1"
2101
   $ kamaki config set token USER_TOKEN
2102

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

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

    
2108
.. code-block:: console
2109

    
2110
   $ kamaki config list
2111

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

    
2115
.. code-block:: console
2116

    
2117
  $ kamaki user authenticate
2118

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

    
2122
Upload an Image file to Pithos
2123
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2124

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

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

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

    
2137
We create the new ``images`` container by running:
2138

    
2139
.. code-block:: console
2140

    
2141
   $ kamaki file create images
2142

    
2143
To check if the container has been created, list all containers of your
2144
account:
2145

    
2146
.. code-block:: console
2147

    
2148
  $ kamaki file list
2149

    
2150
Then, we upload the Image file to that container:
2151

    
2152
.. code-block:: console
2153

    
2154
   $ kamaki file upload /srv/images/debian_base-6.0-7-x86_64.diskdump images
2155

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

    
2159
.. code-block:: console
2160

    
2161
  $ kamaki file list images
2162

    
2163
Alternatively check if the new container and file appear on the Pithos Web UI.
2164

    
2165
Register an existing Image file to Cyclades
2166
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2167

    
2168
For the purposes of the following example, we assume that the user UUID is
2169
``u53r-un1qu3-1d``.
2170

    
2171
Once the Image file has been successfully uploaded on Pithos then we register
2172
it to Cyclades, by running:
2173

    
2174
.. code-block:: console
2175

    
2176
   $ kamaki image register "Debian Base" \
2177
                           pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump \
2178
                           --public \
2179
                           --disk-format=diskdump \
2180
                           --property OSFAMILY=linux --property ROOT_PARTITION=1 \
2181
                           --property description="Debian Squeeze Base System" \
2182
                           --property size=451 --property kernel=2.6.32 --property GUI="No GUI" \
2183
                           --property sortorder=1 --property USERS=root --property OS=debian
2184

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

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

    
2200
Spawn a VM from the Cyclades Web UI
2201
-----------------------------------
2202

    
2203
If the registration completes successfully, then go to the Cyclades Web UI from
2204
your browser at:
2205

    
2206
 `https://node1.example.com/cyclades/ui/`
2207

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

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

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

    
2224
Congratulations. You have successfully installed the whole Synnefo stack and
2225
connected all components. Go ahead in the next section to test the Network
2226
functionality from inside Cyclades and discover even more features.
2227

    
2228
General Testing
2229
===============
2230

    
2231
Notes
2232
=====
2233