Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 6dd3e7c2

History | View | Annotate | Download (80.7 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 public IPs are "4.3.2.1" and
41
"4.3.2.2" respectively. It is important that the two machines are under the same domain name.
42
In case you choose to follow a private installation you will need to
43
set up a private dns server, using dnsmasq for example. See node1 below for more.
44

    
45
General Prerequisites
46
=====================
47

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

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

    
54
| ``deb http://apt.dev.grnet.gr squeeze/``
55
| ``deb-src http://apt.dev.grnet.gr squeeze/``
56

    
57
and import the repo's GPG key:
58

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

    
61
Also add the following line to enable the ``squeeze-backports`` repository,
62
which may provide more recent versions of certain packages. The repository
63
is deactivated by default and must be specified expicitly in ``apt-get``
64
operations:
65

    
66
| ``deb http://backports.debian.org/debian-backports squeeze-backports main``
67

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

    
76
Before starting the synnefo installation, you will need basic third party
77
software to be installed and configured on the physical nodes. We will describe
78
each node's general prerequisites separately. Any additional configuration,
79
specific to a synnefo service for each node, will be described at the service's
80
section.
81

    
82
Finally, it is required for Cyclades and Ganeti nodes to have synchronized
83
system clocks (e.g. by running ntpd).
84

    
85
Node1
86
-----
87

    
88

    
89
General Synnefo dependencies
90
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91

    
92
		* apache (http server)
93
		* public certificate
94
		* gunicorn (WSGI http server)
95
		* postgresql (database)
96
		* rabbitmq (message queue)
97
		* ntp (NTP daemon)
98
		* gevent
99
		* dns server
100

    
101
You can install apache2, postgresql and ntp by running:
102

    
103
.. code-block:: console
104

    
105
   # apt-get install apache2 postgresql ntp
106

    
107
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
108
the official debian backports:
109

    
110
.. code-block:: console
111

    
112
   # apt-get -t squeeze-backports install gunicorn
113

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

    
116
.. code-block:: console
117

    
118
   # apt-get -t squeeze-backports install python-gevent
119

    
120
On node1, we will create our databases, so you will also need the
121
python-psycopg2 package:
122

    
123
.. code-block:: console
124

    
125
   # apt-get install python-psycopg2
126

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

    
130
.. code-block:: console
131

    
132
    deb http://www.rabbitmq.com/debian testing main
133

    
134
Add RabbitMQ public key, to trusted key list:
135

    
136
.. code-block:: console
137

    
138
  # wget http://www.rabbitmq.com/rabbitmq-signing-key-public.asc
139
  # apt-key add rabbitmq-signing-key-public.asc
140

    
141
Finally, to install the package run:
142

    
143
.. code-block:: console
144

    
145
  # apt-get update
146
  # apt-get install rabbitmq-server
147

    
148
Database setup
149
~~~~~~~~~~~~~~
150

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

    
155
.. code-block:: console
156

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

    
163
We also create the database ``snf_pithos`` needed by the Pithos backend and
164
grant the ``synnefo`` user all privileges on the database. This database could
165
be created on node2 instead, but we do it on node1 for simplicity. We will
166
create all needed databases on node1 and then node2 will connect to them.
167

    
168
.. code-block:: console
169

    
170
    postgres=# CREATE DATABASE snf_pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
171
    postgres=# GRANT ALL PRIVILEGES ON DATABASE snf_pithos TO synnefo;
172

    
173
Configure the database to listen to all network interfaces. You can do this by
174
editting the file ``/etc/postgresql/8.4/main/postgresql.conf`` and change
175
``listen_addresses`` to ``'*'`` :
176

    
177
.. code-block:: console
178

    
179
    listen_addresses = '*'
180

    
181
Furthermore, edit ``/etc/postgresql/8.4/main/pg_hba.conf`` to allow node1 and
182
node2 to connect to the database. Add the following lines under ``#IPv4 local
183
connections:`` :
184

    
185
.. code-block:: console
186

    
187
    host		all	all	4.3.2.1/32	md5
188
    host		all	all	4.3.2.2/32	md5
189

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

    
193
.. code-block:: console
194

    
195
   # /etc/init.d/postgresql restart
196

    
197
Gunicorn setup
198
~~~~~~~~~~~~~~
199

    
200
Create the file ``/etc/gunicorn.d/synnefo`` containing the following:
201

    
202
.. code-block:: console
203

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

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

    
226
       # /etc/init.d/gunicorn stop
227

    
228
Certificate Creation
229
~~~~~~~~~~~~~~~~~~~~~
230

    
231
Node1 will host Cyclades. Cyclades should communicate with the other snf tools over a trusted connection.
232
In order for the connection to be trusted, the keys provided to apache below should be signed with a certificate.
233
This certificate should be added to all nodes. In case you don't have signed keys you can create a self-signed certificate
234
and sign your keys with this. To do so on node1 run
235

    
236
.. code-block:: console
237

    
238
		# aptitude install openvpn
239
		# mkdir /etc/openvpn/easy-rsa
240
		# cp -ai /usr/share/doc/openvpn/examples/easy-rsa/2.0/ /etc/openvpn/easy-rsa
241
		# cd /etc/openvpn/easy-rsa/2.0
242
		# vim vars
243

    
244
In vars you can set your own parameters such as KEY_COUNTRY
245

    
246
.. code-block:: console
247

    
248
	# . ./vars
249
	# ./clean-all
250

    
251
Now you can create the certificate
252

    
253
.. code-block:: console
254

    
255
		# ./build-ca
256

    
257
The previous will create a ``ca.crt`` file. Copy this file under
258
``/usr/local/share/ca-certificates/`` directory and run :
259

    
260
.. code-block:: console
261

    
262
		# update-ca-certificates
263

    
264
to update the records. You will have to do the following on node2 as well.
265

    
266
Now you can create the keys and sign them with the certificate
267

    
268
.. code-block:: console
269

    
270
		# ./build-key-server node1.example.com
271

    
272
This will create a .pem and a .key file in your current folder. Copy these in
273
``/etc/ssl/certs/`` and ``/etc/ssl/private/`` respectively and
274
use them in the apache2 configuration file below instead of the defaults.
275

    
276
Apache2 setup
277
~~~~~~~~~~~~~
278

    
279
Create the file ``/etc/apache2/sites-available/synnefo`` containing the
280
following:
281

    
282
.. code-block:: console
283

    
284
    <VirtualHost *:80>
285
        ServerName node1.example.com
286

    
287
        RewriteEngine On
288
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
289
        RewriteRule ^(.*)$ - [F,L]
290
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
291
    </VirtualHost>
292

    
293

    
294
Create the file ``/etc/apache2/sites-available/synnefo-ssl`` containing the
295
following:
296

    
297
.. code-block:: console
298

    
299
    <IfModule mod_ssl.c>
300
    <VirtualHost _default_:443>
301
        ServerName node1.example.com
302

    
303
        Alias /static "/usr/share/synnefo/static"
304

    
305
        #  SetEnv no-gzip
306
        #  SetEnv dont-vary
307

    
308
       AllowEncodedSlashes On
309

    
310
       RequestHeader set X-Forwarded-Protocol "https"
311

    
312
    <Proxy * >
313
        Order allow,deny
314
        Allow from all
315
    </Proxy>
316

    
317
        SetEnv                proxy-sendchunked
318
        SSLProxyEngine        off
319
        ProxyErrorOverride    off
320

    
321
        ProxyPass        /static !
322
        ProxyPass        / http://localhost:8080/ retry=0
323
        ProxyPassReverse / http://localhost:8080/
324

    
325
        RewriteEngine On
326
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
327
        RewriteRule ^(.*)$ - [F,L]
328

    
329
        SSLEngine on
330
        SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
331
        SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
332
    </VirtualHost>
333
    </IfModule>
334

    
335
Now enable sites and modules by running:
336

    
337
.. code-block:: console
338

    
339
   # a2enmod ssl
340
   # a2enmod rewrite
341
   # a2dissite default
342
   # a2ensite synnefo
343
   # a2ensite synnefo-ssl
344
   # a2enmod headers
345
   # a2enmod proxy_http
346

    
347
.. note:: This isn't really needed, but it's a good security practice to disable
348
    directory listing in apache::
349

    
350
        # a2dismod autoindex
351

    
352

    
353
.. warning:: Do NOT start/restart the server yet. If the server is running::
354

    
355
       # /etc/init.d/apache2 stop
356

    
357

    
358
.. _rabbitmq-setup:
359

    
360
Message Queue setup
361
~~~~~~~~~~~~~~~~~~~
362

    
363
The message queue will run on node1, so we need to create the appropriate
364
rabbitmq user. The user is named ``synnefo`` and gets full privileges on all
365
exchanges:
366

    
367
.. code-block:: console
368

    
369
   # rabbitmqctl add_user synnefo "example_rabbitmq_passw0rd"
370
   # rabbitmqctl set_permissions synnefo ".*" ".*" ".*"
371

    
372
We do not need to initialize the exchanges. This will be done automatically,
373
during the Cyclades setup.
374

    
375
Pithos data directory setup
376
~~~~~~~~~~~~~~~~~~~~~~~~~~~
377

    
378
As mentioned in the General Prerequisites section, there is a directory called
379
``/srv/pithos`` visible by both nodes. We create and setup the ``data``
380
directory inside it:
381

    
382
.. code-block:: console
383

    
384
   # cd /srv/pithos
385
   # mkdir data
386
   # chown www-data:www-data data
387
   # chmod g+ws data
388

    
389
DNS server setup
390
~~~~~~~~~~~~~~~~
391

    
392
If your machines are not under the same domain nameyou have to set up a dns server.
393
In order to set up a dns server using dnsmasq do the following
394

    
395
.. code-block:: console
396

    
397
				# apt-get install dnsmasq
398

    
399
Then edit you ``/etc/hosts/`` as follows
400

    
401
.. code-block:: console
402

    
403
		4.3.2.1     node1.example.com
404
		4.3.2.2     node2.example.com
405

    
406
Finally edit the ``/etc/dnsmasq.conf`` file and specify the ``listen-address`` and
407
the ``interface`` you would like to listen to.
408

    
409
Also add the following in your ``/etc/resolv.conf`` file
410

    
411
.. code-block:: console
412

    
413
		nameserver 4.3.2.1
414

    
415
You are now ready with all general prerequisites concerning node1. Let's go to
416
node2.
417

    
418
Node2
419
-----
420

    
421
General Synnefo dependencies
422
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423

    
424
    * apache (http server)
425
    * gunicorn (WSGI http server)
426
    * postgresql (database)
427
    * ntp (NTP daemon)
428
    * gevent
429
    * certificates
430
    * dns setup
431

    
432
You can install the above by running:
433

    
434
.. code-block:: console
435

    
436
   # apt-get install apache2 postgresql ntp
437

    
438
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
439
the official debian backports:
440

    
441
.. code-block:: console
442

    
443
   # apt-get -t squeeze-backports install gunicorn
444

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

    
447
.. code-block:: console
448

    
449
   # apt-get -t squeeze-backports install python-gevent
450

    
451
Node2 will connect to the databases on node1, so you will also need the
452
python-psycopg2 package:
453

    
454
.. code-block:: console
455

    
456
   # apt-get install python-psycopg2
457

    
458
Database setup
459
~~~~~~~~~~~~~~
460

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

    
467
Gunicorn setup
468
~~~~~~~~~~~~~~
469

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

    
473
.. code-block:: console
474

    
475
    CONFIG = {
476
     'mode': 'django',
477
     'environment': {
478
      'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
479
     },
480
     'working_dir': '/etc/synnefo',
481
     'user': 'www-data',
482
     'group': 'www-data',
483
     'args': (
484
       '--bind=127.0.0.1:8080',
485
       '--worker-class=gevent',
486
       '--workers=4',
487
       '--log-level=debug',
488
       '--timeout=43200'
489
     ),
490
    }
491

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

    
498
       # /etc/init.d/gunicorn stop
499

    
500
Apache2 setup
501
~~~~~~~~~~~~~
502

    
503
Create the file ``/etc/apache2/sites-available/synnefo`` containing the
504
following:
505

    
506
.. code-block:: console
507

    
508
    <VirtualHost *:80>
509
        ServerName node2.example.com
510

    
511
        RewriteEngine On
512
        RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
513
        RewriteRule ^(.*)$ - [F,L]
514
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
515
    </VirtualHost>
516

    
517
Create the file ``synnefo-ssl`` under ``/etc/apache2/sites-available/``
518
containing the following:
519

    
520
.. code-block:: console
521

    
522
    <IfModule mod_ssl.c>
523
    <VirtualHost _default_:443>
524
        ServerName node2.example.com
525

    
526
        Alias /static "/usr/share/synnefo/static"
527

    
528
        SetEnv no-gzip
529
        SetEnv dont-vary
530
        AllowEncodedSlashes On
531

    
532
        RequestHeader set X-Forwarded-Protocol "https"
533

    
534
        <Proxy * >
535
            Order allow,deny
536
            Allow from all
537
        </Proxy>
538

    
539
        SetEnv                proxy-sendchunked
540
        SSLProxyEngine        off
541
        ProxyErrorOverride    off
542

    
543
        ProxyPass        /static !
544
        ProxyPass        / http://localhost:8080/ retry=0
545
        ProxyPassReverse / http://localhost:8080/
546

    
547
        SSLEngine on
548
        SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
549
        SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
550
    </VirtualHost>
551
    </IfModule>
552

    
553
As in node1, enable sites and modules by running:
554

    
555
.. code-block:: console
556

    
557
   # a2enmod ssl
558
   # a2enmod rewrite
559
   # a2dissite default
560
   # a2ensite synnefo
561
   # a2ensite synnefo-ssl
562
   # a2enmod headers
563
   # a2enmod proxy_http
564

    
565
.. note:: This isn't really needed, but it's a good security practice to disable
566
    directory listing in apache::
567

    
568
        # a2dismod autoindex
569

    
570
.. warning:: Do NOT start/restart the server yet. If the server is running::
571

    
572
       # /etc/init.d/apache2 stop
573

    
574

    
575
Acquire certificate
576
~~~~~~~~~~~~~~~~~~~
577

    
578
Copy the certificate you created before on node1 (`ca.crt`) under the directory
579
``/usr/local/share/ca-certificate``
580

    
581
and run:
582

    
583
.. code-block:: console
584

    
585
		# update-ca-certificates
586

    
587
to update the records.
588

    
589

    
590
DNS Setup
591
~~~~~~~~~
592

    
593
Add the following line in ``/etc/resolv.conf`` file
594

    
595
.. code-block:: console
596

    
597
		nameserver 4.3.2.1
598

    
599
to inform the node about the new dns server.
600

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

    
605
Installation of Astakos on node1
606
================================
607

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

    
612
.. code-block:: console
613

    
614
   # apt-get install snf-astakos-app snf-pithos-backend
615

    
616
.. _conf-astakos:
617

    
618
Configuration of Astakos
619
========================
620

    
621
Conf Files
622
----------
623

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

    
631
After getting familiar with synnefo, you will be able to customize the software
632
as you wish and fits your needs. Many options are available, to empower the
633
administrator with extensively customizable setups.
634

    
635
For the snf-webproject component (installed as an astakos dependency), we
636
need the following:
637

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

    
641
.. code-block:: console
642

    
643
    DATABASES = {
644
     'default': {
645
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
646
         'ENGINE': 'postgresql_psycopg2',
647
         # ATTENTION: This *must* be the absolute path if using sqlite3.
648
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
649
         'NAME': 'snf_apps',
650
         'USER': 'synnefo',                      # Not used with sqlite3.
651
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
652
         # Set to empty string for localhost. Not used with sqlite3.
653
         'HOST': '4.3.2.1',
654
         # Set to empty string for default. Not used with sqlite3.
655
         'PORT': '5432',
656
     }
657
    }
658

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

    
664
.. code-block:: console
665

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

    
668
For astakos specific configuration, edit the following options in
669
``/etc/synnefo/20-snf-astakos-app-settings.conf`` :
670

    
671
.. code-block:: console
672

    
673
    ASTAKOS_COOKIE_DOMAIN = '.example.com'
674

    
675
    ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
676

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

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

    
685
    .. code-block:: console
686

    
687
        ASTAKOS_RECAPTCHA_PUBLIC_KEY = 'example_recaptcha_public_key!@#$%^&*('
688
        ASTAKOS_RECAPTCHA_PRIVATE_KEY = 'example_recaptcha_private_key!@#$%^&*('
689
        ASTAKOS_RECAPTCHA_USE_SSL = True
690
        ASTAKOS_RECAPTCHA_ENABLED = True
691

    
692
    For the ``ASTAKOS_RECAPTCHA_PUBLIC_KEY`` and ``ASTAKOS_RECAPTCHA_PRIVATE_KEY``
693
    go to https://www.google.com/recaptcha/admin/create and create your own pair.
694

    
695
Then edit ``/etc/synnefo/20-snf-astakos-app-cloudbar.conf`` :
696

    
697
.. code-block:: console
698

    
699
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
700

    
701
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
702

    
703
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
704

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

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

    
712
.. _email-configuration:
713

    
714
Email delivery configuration
715
----------------------------
716

    
717
Many of the ``astakos`` operations require server to notify service users and
718
administrators via email. e.g. right after the signup process the service sents
719
an email to the registered email address containing an email verification url,
720
after the user verifies the email address astakos once again needs to notify
721
administrators with a notice that a new account has just been verified.
722

    
723
More specifically astakos sends emails in the following cases
724

    
725
- An email containing a verification link after each signup process.
726
- An email to the people listed in ``ADMINS`` setting after each email
727
  verification if ``ASTAKOS_MODERATION`` setting is ``True``. The email
728
  notifies administrators that an additional action is required in order to
729
  activate the user.
730
- A welcome email to the user email and an admin notification to ``ADMINS``
731
  right after each account activation.
732
- Feedback messages submited from astakos contact view and astakos feedback
733
  API endpoint are sent to contacts listed in ``HELPDESK`` setting.
734
- Project application request notifications to people included in ``HELPDESK``
735
  and ``MANAGERS`` settings.
736
- Notifications after each project members action (join request, membership
737
  accepted/declinde etc.) to project members or project owners.
738

    
739
Astakos uses the Django internal email delivering mechanism to send email
740
notifications. A simple configuration, using an external smtp server to
741
deliver messages, is shown below. Alter the following example to meet your
742
smtp server characteristics. Notice that the smtp server is needed for a proper
743
installation
744

    
745
.. code-block:: python
746

    
747
    # /etc/synnefo/00-snf-common-admins.conf
748
    EMAIL_HOST = "mysmtp.server.synnefo.org"
749
    EMAIL_HOST_USER = "<smtpuser>"
750
    EMAIL_HOST_PASSWORD = "<smtppassword>"
751

    
752
    # this gets appended in all email subjects
753
    EMAIL_SUBJECT_PREFIX = "[example.synnefo.org] "
754

    
755
    # Address to use for outgoing emails
756
    DEFAULT_FROM_EMAIL = "server@example.synnefo.org"
757

    
758
    # Email where users can contact for support. This is used in html/email
759
    # templates.
760
    CONTACT_EMAIL = "server@example.synnefo.org"
761

    
762
    # The email address that error messages come from
763
    SERVER_EMAIL = "server-errors@example.synnefo.org"
764

    
765
Notice that since email settings might be required by applications other than
766
astakos they are defined in a different configuration file than the one
767
previously used to set astakos specific settings.
768

    
769
Refer to
770
`Django documentation <https://docs.djangoproject.com/en/1.2/topics/email/>`_
771
for additional information on available email settings.
772

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

    
779
.. code-block:: python
780

    
781
    ADMINS = (('Admin name', 'admin@example.synnefo.org'),
782
              ('Admin2 name', 'admin2@example.synnefo.org))
783
    MANAGERS = (('Manager name', 'manager@example.synnefo.org'),)
784
    HELPDESK = (('Helpdesk user name', 'helpdesk@example.synnefo.org'),)
785

    
786
Alternatively, it may be convenient to send e-mails to a file, instead of an actual smtp server, using the file backend. Do so by creating a configuration file ``/etc/synnefo/99-local.conf`` including the folowing:
787

    
788
.. code-block:: python
789

    
790
    EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
791
    EMAIL_FILE_PATH = '/tmp/app-messages' 
792
  
793

    
794

    
795
Enable Pooling
796
--------------
797

    
798
This section can be bypassed, but we strongly recommend you apply the following,
799
since they result in a significant performance boost.
800

    
801
Synnefo includes a pooling DBAPI driver for PostgreSQL, as a thin wrapper
802
around Psycopg2. This allows independent Django requests to reuse pooled DB
803
connections, with significant performance gains.
804

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

    
808
.. code-block:: console
809

    
810
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
811
    monkey_patch_psycopg2()
812

    
813
Since we are running with greenlets, we should modify psycopg2 behavior, so it
814
works properly in a greenlet context:
815

    
816
.. code-block:: console
817

    
818
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
819
    make_psycopg_green()
820

    
821
Use the Psycopg2 driver as usual. For Django, this means using
822
``django.db.backends.postgresql_psycopg2`` without any modifications. To enable
823
connection pooling, pass a nonzero ``synnefo_poolsize`` option to the DBAPI
824
driver, through ``DATABASES.OPTIONS`` in Django.
825

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

    
829
.. code-block:: console
830

    
831
    # Monkey-patch psycopg2
832
    from synnefo.lib.db.pooled_psycopg2 import monkey_patch_psycopg2
833
    monkey_patch_psycopg2()
834

    
835
    # If running with greenlets
836
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
837
    make_psycopg_green()
838

    
839
    DATABASES = {
840
     'default': {
841
         # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
842
         'ENGINE': 'postgresql_psycopg2',
843
         'OPTIONS': {'synnefo_poolsize': 8},
844

    
845
         # ATTENTION: This *must* be the absolute path if using sqlite3.
846
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
847
         'NAME': 'snf_apps',
848
         'USER': 'synnefo',                      # Not used with sqlite3.
849
         'PASSWORD': 'example_passw0rd',         # Not used with sqlite3.
850
         # Set to empty string for localhost. Not used with sqlite3.
851
         'HOST': '4.3.2.1',
852
         # Set to empty string for default. Not used with sqlite3.
853
         'PORT': '5432',
854
     }
855
    }
856

    
857
Database Initialization
858
-----------------------
859

    
860
After configuration is done, we initialize the database by running:
861

    
862
.. code-block:: console
863

    
864
    # snf-manage syncdb
865

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

    
870
.. code-block:: console
871

    
872
    # snf-manage migrate im
873
    # snf-manage migrate quotaholder_app
874

    
875
Then, we load the pre-defined user groups
876

    
877
.. code-block:: console
878

    
879
    # snf-manage loaddata groups
880

    
881
.. _services-reg:
882

    
883
Services Registration
884
---------------------
885

    
886
When the database is ready, we need to register the services. The following
887
command will ask you to register the standard Synnefo components (astakos,
888
cyclades, and pithos) along with the services they provide. Note that you
889
have to register at least astakos in order to have a usable authentication
890
system. For each component, you will be asked to provide two URLs: its base
891
URL and its UI URL.
892

    
893
The former is the location where the component resides; it should equal
894
the ``<component_name>_BASE_URL`` as specified in the respective component
895
settings. For example, the base URL for astakos would be
896
``https://node1.example.com/astakos``.
897

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

    
904
The command will also register automatically the resource definitions
905
offered by the services.
906

    
907
.. code-block:: console
908

    
909
    # snf-component-register
910

    
911
.. note::
912

    
913
   This command is equivalent to running the following series of commands;
914
   it registers the three components in astakos and then in each host it
915
   exports the respective service definitions, copies the exported json file
916
   to the astakos host, where it finally imports it:
917

    
918
    .. code-block:: console
919

    
920
       astakos-host$ snf-manage component-add astakos astakos_ui_url
921
       astakos-host$ snf-manage component-add cyclades cyclades_ui_url
922
       astakos-host$ snf-manage component-add pithos pithos_ui_url
923
       astakos-host$ snf-manage service-export-astakos > astakos.json
924
       astakos-host$ snf-manage service-import --json astakos.json
925
       cyclades-host$ snf-manage service-export-cyclades > cyclades.json
926
       # copy the file to astakos-host
927
       astakos-host$ snf-manage service-import --json cyclades.json
928
       pithos-host$ snf-manage service-export-pithos > pithos.json
929
       # copy the file to astakos-host
930
       astakos-host$ snf-manage service-import --json pithos.json
931

    
932
Notice that in this installation astakos and cyclades are in node1 and pithos is in node2
933

    
934
Setting Default Base Quota for Resources
935
----------------------------------------
936

    
937
We now have to specify the limit on resources that each user can employ
938
(exempting resources offered by projects).
939

    
940
.. code-block:: console
941

    
942
    # snf-manage resource-modify --limit-interactive
943

    
944

    
945
Servers Initialization
946
----------------------
947

    
948
Finally, we initialize the servers on node1:
949

    
950
.. code-block:: console
951

    
952
    root@node1:~ # /etc/init.d/gunicorn restart
953
    root@node1:~ # /etc/init.d/apache2 restart
954

    
955
We have now finished the Astakos setup. Let's test it now.
956

    
957

    
958
Testing of Astakos
959
==================
960

    
961
Open your favorite browser and go to:
962

    
963
``http://node1.example.com/astakos``
964

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

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

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

    
976
.. code-block:: console
977

    
978
    root@node1:~ # snf-manage user-list
979

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

    
984
.. code-block:: console
985

    
986
    root@node1:~ # snf-manage user-modify 1 --verify --accept
987

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

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

    
1001
Let's continue to install Pithos now.
1002

    
1003

    
1004
Installation of Pithos on node2
1005
===============================
1006

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

    
1011
.. code-block:: console
1012

    
1013
   # apt-get install snf-pithos-app snf-pithos-backend
1014

    
1015
Now, install the pithos web interface:
1016

    
1017
.. code-block:: console
1018

    
1019
   # apt-get install snf-pithos-webclient
1020

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

    
1025

    
1026
.. _conf-pithos:
1027

    
1028
Configuration of Pithos
1029
=======================
1030

    
1031
Conf Files
1032
----------
1033

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

    
1040
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
1041
this options:
1042

    
1043
.. code-block:: console
1044

    
1045
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
1046

    
1047
   PITHOS_BASE_URL = 'https://node2.example.com/pithos'
1048
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1049
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
1050

    
1051
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w'
1052

    
1053
   # Set to False if astakos & pithos are on the same host
1054
   PITHOS_PROXY_USER_SERVICES = True
1055

    
1056

    
1057
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the Pithos app where to
1058
find the Pithos backend database. Above we tell Pithos that its database is
1059
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
1060
``example_passw0rd``.  All those settings where setup during node1's "Database
1061
setup" section.
1062

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

    
1068
The ``ASTAKOS_BASE_URL`` option informs the Pithos app where Astakos is.
1069
The Astakos service is used for user management (authentication, quotas, etc.)
1070

    
1071
The ``PITHOS_BASE_URL`` setting must point to the top-level Pithos URL.
1072

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

    
1076
.. code-block:: console
1077

    
1078
   # snf-manage component-list
1079

    
1080
The token has been generated automatically during the :ref:`Pithos service
1081
registration <services-reg>`.
1082

    
1083
The ``PITHOS_UPDATE_MD5`` option by default disables the computation of the
1084
object checksums. This results to improved performance during object uploading.
1085
However, if compatibility with the OpenStack Object Storage API is important
1086
then it should be changed to ``True``.
1087

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

    
1091
.. code-block:: console
1092

    
1093
    CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1094
    CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
1095
    CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
1096

    
1097
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
1098
cloudbar.
1099

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

    
1104
Pooling and Greenlets
1105
---------------------
1106

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

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

    
1116
.. code-block:: console
1117

    
1118
    from synnefo.lib.db.psyco_gevent import make_psycopg_green
1119
    make_psycopg_green()
1120

    
1121
Furthermore, add the ``--worker-class=gevent`` (or ``--worker-class=sync`` as
1122
mentioned above, depending on your setup) argument on your
1123
``/etc/gunicorn.d/synnefo`` configuration file. The file should look something
1124
like this:
1125

    
1126
.. code-block:: console
1127

    
1128
    CONFIG = {
1129
     'mode': 'django',
1130
     'environment': {
1131
       'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
1132
     },
1133
     'working_dir': '/etc/synnefo',
1134
     'user': 'www-data',
1135
     'group': 'www-data',
1136
     'args': (
1137
       '--bind=127.0.0.1:8080',
1138
       '--workers=4',
1139
       '--worker-class=gevent',
1140
       '--log-level=debug',
1141
       '--timeout=43200'
1142
     ),
1143
    }
1144

    
1145
Stamp Database Revision
1146
-----------------------
1147

    
1148
Pithos uses the alembic_ database migrations tool.
1149

    
1150
.. _alembic: http://alembic.readthedocs.org
1151

    
1152
After a successful installation, we should stamp it at the most recent
1153
revision, so that future migrations know where to start upgrading in
1154
the migration history.
1155

    
1156
.. code-block:: console
1157

    
1158
    root@node2:~ # pithos-migrate stamp head
1159

    
1160
Servers Initialization
1161
----------------------
1162

    
1163
After configuration is done, we initialize the servers on node2:
1164

    
1165
.. code-block:: console
1166

    
1167
    root@node2:~ # /etc/init.d/gunicorn restart
1168
    root@node2:~ # /etc/init.d/apache2 restart
1169

    
1170
You have now finished the Pithos setup. Let's test it now.
1171

    
1172

    
1173
Testing of Pithos
1174
=================
1175

    
1176
Open your browser and go to the Astakos homepage:
1177

    
1178
``http://node1.example.com/astakos``
1179

    
1180
Login, and you will see your profile page. Now, click the "pithos" link on the
1181
top black cloudbar. If everything was setup correctly, this will redirect you
1182
to:
1183

    
1184

    
1185
and you will see the blue interface of the Pithos application.  Click the
1186
orange "Upload" button and upload your first file. If the file gets uploaded
1187
successfully, then this is your first sign of a successful Pithos installation.
1188
Go ahead and experiment with the interface to make sure everything works
1189
correctly.
1190

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

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

    
1196
If you would like to do more, such as:
1197

    
1198
    * Spawning VMs
1199
    * Spawning VMs from Images stored on Pithos
1200
    * Uploading your custom Images to Pithos
1201
    * Spawning VMs from those custom Images
1202
    * Registering existing Pithos files as Images
1203
    * Connect VMs to the Internet
1204
    * Create Private Networks
1205
    * Add VMs to Private Networks
1206

    
1207
please continue with the rest of the guide.
1208

    
1209

    
1210
Cyclades Prerequisites
1211
======================
1212

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

    
1218
Besides Astakos and Pithos, you will also need a number of additional working
1219
prerequisites, before you start the Cyclades installation.
1220

    
1221
Ganeti
1222
------
1223

    
1224
`Ganeti <http://code.google.com/p/ganeti/>`_ handles the low level VM management
1225
for Cyclades, so Cyclades requires a working Ganeti installation at the backend.
1226
Please refer to the
1227
`ganeti documentation <http://docs.ganeti.org/ganeti/2.6/html>`_ for all the
1228
gory details. A successful Ganeti installation concludes with a working
1229
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs
1230
<GANETI_NODES>`.
1231

    
1232
The above Ganeti cluster can run on different physical machines than node1 and
1233
node2 and can scale independently, according to your needs.
1234

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

    
1239
We highly recommend that you read the official Ganeti documentation, if you are
1240
not familiar with Ganeti.
1241

    
1242
Unfortunately, the current stable version of the stock Ganeti (v2.6.2) doesn't
1243
support IP pool management. This feature will be available in Ganeti >= 2.7.
1244
Synnefo depends on the IP pool functionality of Ganeti, so you have to use
1245
GRNET provided packages until stable 2.7 is out. These packages will also install
1246
the proper version of Ganeti. To do so:
1247

    
1248
.. code-block:: console
1249

    
1250
   # apt-get install snf-ganeti ganeti-htools
1251

    
1252
Ganeti will make use of drbd. To enable this and make the configuration pemanent
1253
you have to do the following :
1254

    
1255
.. code-block:: console
1256

    
1257
		# rmmod -f drbd && modprobe drbd minor_count=255 usermode_helper=/bin/true
1258
		# echo 'drbd minor_count=255 usermode_helper=/bin/true' >> /etc/modules
1259

    
1260

    
1261
We assume that Ganeti will use the KVM hypervisor. After installing Ganeti on
1262
both nodes, choose a domain name that resolves to a valid floating IP (let's
1263
say it's ``ganeti.node1.example.com``). This IP is needed to communicate with
1264
the Ganeti cluster. Make sure node1 and node2 have same dsa,rsa keys and authorised_keys
1265
for password-less root ssh between each other. If not then skip passing --no-ssh-init but be
1266
aware that it will replace /root/.ssh/* related files and you might lose access to master node.
1267
Also, Ganeti will need a volume to host your VMs' disks. So, make sure there is an lvm volume
1268
group named ``ganeti``. Finally, setup a bridge interface on the host machines (e.g: br0). This
1269
will be needed for the network configuration afterwards.
1270

    
1271
Then run on node1:
1272

    
1273
.. code-block:: console
1274

    
1275
    root@node1:~ # gnt-cluster init --enabled-hypervisors=kvm --no-ssh-init \
1276
                    --no-etc-hosts --vg-name=ganeti --nic-parameters link=br0 \
1277
                    --master-netdev eth0 ganeti.node1.example.com
1278
    root@node1:~ # gnt-cluster modify --default-iallocator hail
1279
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:kernel_path=
1280
    root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:vnc_bind_address=0.0.0.0
1281

    
1282
    root@node1:~ # gnt-node add --no-ssh-key-check --master-capable=yes \
1283
                    --vm-capable=yes node2.example.com
1284
    root@node1:~ # gnt-cluster modify --disk-parameters=drbd:metavg=ganeti
1285
    root@node1:~ # gnt-group modify --disk-parameters=drbd:metavg=ganeti default
1286

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

    
1291
.. _cyclades-install-snfimage:
1292

    
1293
snf-image
1294
---------
1295

    
1296
Installation
1297
~~~~~~~~~~~~
1298
For :ref:`Cyclades <cyclades>` to be able to launch VMs from specified Images,
1299
you need the :ref:`snf-image <snf-image>` OS Definition installed on *all*
1300
VM-capable Ganeti nodes. This means we need :ref:`snf-image <snf-image>` on
1301
node1 and node2. You can do this by running on *both* nodes:
1302

    
1303
.. code-block:: console
1304

    
1305
   # apt-get install snf-image snf-pithos-backend python-psycopg2
1306

    
1307
snf-image also needs the `snf-pithos-backend <snf-pithos-backend>`, to be able
1308
to handle image files stored on Pithos. It also needs `python-psycopg2` to be
1309
able to access the Pithos database. This is why, we also install them on *all*
1310
VM-capable Ganeti nodes.
1311

    
1312
.. warning::
1313
		snf-image uses ``curl`` for handling URLs. This means that it will
1314
		not  work out of the box if you try to use URLs served by servers which do
1315
		not have a valid certificate. In case you haven't followed the guide's
1316
		directions about the certificates,in order to circumvent this you should edit the file
1317
		``/etc/default/snf-image``. Change ``#CURL="curl"`` to ``CURL="curl -k"`` on every node.
1318

    
1319
After `snf-image` has been installed successfully, create the helper VM by
1320
running on *both* nodes:
1321

    
1322
.. code-block:: console
1323

    
1324
   # snf-image-update-helper
1325

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

    
1330
Configuration
1331
~~~~~~~~~~~~~
1332
snf-image supports native access to Images stored on Pithos. This means that
1333
it can talk directly to the Pithos backend, without the need of providing a
1334
public URL. More details, are described in the next section. For now, the only
1335
thing we need to do, is configure snf-image to access our Pithos backend.
1336

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

    
1340
.. code-block:: console
1341

    
1342
    PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
1343

    
1344
    PITHOS_DATA="/srv/pithos/data"
1345

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

    
1349
If you would like to use Images that are also/only stored locally, you need to
1350
save them under ``IMAGE_DIR``, however this guide targets Images stored only on
1351
Pithos.
1352

    
1353
Testing
1354
~~~~~~~
1355
You can test that snf-image is successfully installed by running on the
1356
:ref:`GANETI-MASTER <GANETI_NODES>` (in our case node1):
1357

    
1358
.. code-block:: console
1359

    
1360
   # gnt-os diagnose
1361

    
1362
This should return ``valid`` for snf-image.
1363

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

    
1370
.. _snf-image-images:
1371

    
1372
Actual Images for snf-image
1373
---------------------------
1374

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

    
1381
:ref:`snf-image <snf-image>` also supports three (3) different locations for the
1382
above Images to be stored:
1383

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

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

    
1394
To do so, do the following:
1395

    
1396
a) Download the Image from the official snf-image page.
1397

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

    
1402
Once the Image is uploaded successfully, download the Image's metadata file
1403
from the official snf-image page. You will need it, for spawning a VM from
1404
Ganeti, in the next section.
1405

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

    
1410
.. _ganeti-with-pithos-images:
1411

    
1412
Spawning a VM from a Pithos Image, using Ganeti
1413
-----------------------------------------------
1414

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

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

    
1423
.. code-block:: console
1424

    
1425
   # gnt-instance add -o snf-image+default --os-parameters \
1426
                      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"}' \
1427
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1428
                      testvm1
1429

    
1430
In the above command:
1431

    
1432
 * ``img_passwd``: the arbitrary root password of your new instance
1433
 * ``img_format``: set to ``diskdump`` to reflect the type of the uploaded Image
1434
 * ``img_id``: If you want to deploy an Image stored on Pithos (our case), this
1435
               should have the format ``pithos://<UUID>/<container>/<filename>``:
1436
               * ``UUID``: the username found in Cyclades Web UI under API access
1437
               * ``container``: ``pithos`` (default, if the Web UI was used)
1438
               * ``filename``: the name of file (visible also from the Web UI)
1439
 * ``img_properties``: taken from the metadata file. Used only the two mandatory
1440
                       properties ``OSFAMILY`` and ``ROOT_PARTITION``. `Learn more
1441
                       <https://code.grnet.gr/projects/snf-image/wiki/Image_Format#Image-Properties>`_
1442

    
1443
If the ``gnt-instance add`` command returns successfully, then run:
1444

    
1445
.. code-block:: console
1446

    
1447
   # gnt-instance info testvm1 | grep "console connection"
1448

    
1449
to find out where to connect using VNC. If you can connect successfully and can
1450
login to your new instance using the root password ``my_vm_example_passw0rd``,
1451
then everything works as expected and you have your new Debian Base VM up and
1452
running.
1453

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

    
1463
If everything works, you have successfully connected Ganeti with Pithos. Let's
1464
move on to networking now.
1465

    
1466
.. warning::
1467

    
1468
    You can bypass the networking sections and go straight to
1469
    :ref:`Cyclades Ganeti tools <cyclades-gtools>`, if you do not want to setup
1470
    the Cyclades Network Service, but only the Cyclades Compute Service
1471
    (recommended for now).
1472

    
1473
Networking Setup Overview
1474
-------------------------
1475

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

    
1482
Since synnefo 0.11 all network actions are managed with the snf-manage
1483
network-* commands. This needs the underlying setup (Ganeti, nfdhcpd,
1484
snf-network, bridges, vlans) to be already configured correctly. The only
1485
actions needed in this point are:
1486

    
1487
a) Have Ganeti with IP pool management support installed.
1488

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

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

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

    
1497
.. _snf-network:
1498

    
1499
snf-network
1500
~~~~~~~~~~~
1501

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

    
1507
Install snf-network on all Ganeti nodes:
1508

    
1509
.. code-block:: console
1510

    
1511
   # apt-get install snf-network
1512

    
1513
Then, in :file:`/etc/default/snf-network` set:
1514

    
1515
.. code-block:: console
1516

    
1517
   MAC_MASK=ff:ff:f0:00:00:00
1518

    
1519
.. _nfdhcpd:
1520

    
1521
nfdhcpd
1522
~~~~~~~
1523

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

    
1529
.. code-block:: console
1530

    
1531
   # apt-get install nfqueue-bindings-python=0.3+physindev-1
1532
   # apt-get install nfdhcpd
1533

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

    
1539
.. code-block:: console
1540

    
1541
   # /etc/init.d/nfdhcpd restart
1542

    
1543
If you are using ``ferm``, then you need to run the following:
1544

    
1545
.. code-block:: console
1546

    
1547
   # echo "@include 'nfdhcpd.ferm';" >> /etc/ferm/ferm.conf
1548
   # /etc/init.d/ferm restart
1549

    
1550
or make sure to run after boot:
1551

    
1552
.. code-block:: console
1553

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

    
1556
and if you have IPv6 enabled:
1557

    
1558
.. code-block:: console
1559

    
1560
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 133 -j NFQUEUE --queue-num 43
1561
   # ip6tables -t mangle -A PREROUTING -p ipv6-icmp -m icmp6 --icmpv6-type 135 -j NFQUEUE --queue-num 44
1562

    
1563
You can check which clients are currently served by nfdhcpd by running:
1564

    
1565
.. code-block:: console
1566

    
1567
   # kill -SIGUSR1 `cat /var/run/nfdhcpd/nfdhcpd.pid`
1568

    
1569
When you run the above, then check ``/var/log/nfdhcpd/nfdhcpd.log``.
1570

    
1571
Public Network Setup
1572
--------------------
1573

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

    
1580
Physical Host Setup
1581
~~~~~~~~~~~~~~~~~~~
1582

    
1583
Assuming ``eth0`` on both hosts is the public interface (directly connected
1584
to the router), run on every node:
1585

    
1586
.. code-block:: console
1587

    
1588
   # apt-get install vlan
1589
   # brctl addbr br0
1590
   # ip link set br0 up
1591
   # vconfig add eth0 100
1592
   # ip link set eth0.100 up
1593
   # brctl addif br0 eth0.100
1594

    
1595

    
1596
Testing a Public Network
1597
~~~~~~~~~~~~~~~~~~~~~~~~
1598

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

    
1603
.. code-block:: console
1604

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

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

    
1610
.. code-block:: console
1611

    
1612
   # gnt-network connect test-net-public default bridged br0
1613

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

    
1619
.. code-block:: console
1620

    
1621
   # gnt-instance add -o snf-image+default --os-parameters \
1622
                      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"}' \
1623
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1624
                      --net 0:ip=pool,network=test-net-public \
1625
                      testvm2
1626

    
1627
If the above returns successfully, connect to the new VM through VNC as before and run:
1628

    
1629
.. code-block:: console
1630

    
1631
   root@testvm2:~ # ip addr
1632
   root@testvm2:~ # ip route
1633
   root@testvm2:~ # cat /etc/resolv.conf
1634

    
1635
to check IP address (5.6.7.2), IP routes (default via 5.6.7.1) and DNS config
1636
(nameserver option in nfdhcpd.conf). This shows correct configuration of
1637
ganeti, snf-network and nfdhcpd.
1638

    
1639
Now ping the outside world. If this works too, then you have also configured
1640
correctly your physical host and router.
1641

    
1642
Make sure everything works as expected, before proceeding with the Private
1643
Networks setup.
1644

    
1645
.. _private-networks-setup:
1646

    
1647
Private Networks Setup
1648
----------------------
1649

    
1650
Synnefo supports two types of private networks:
1651

    
1652
 - based on MAC filtering
1653
 - based on physical VLANs
1654

    
1655
Both types provide Layer 2 isolation to the end-user.
1656

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

    
1663
Physical Host Setup
1664
~~~~~~~~~~~~~~~~~~~
1665

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

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

    
1673
.. code-block:: console
1674

    
1675
   # modprobe 8021q
1676
   # $iface=eth0
1677
   # for prv in $(seq 0 20); do
1678
        vlan=$prv
1679
        bridge=prv$prv
1680
        vconfig add $iface $vlan
1681
        ifconfig $iface.$vlan up
1682
        brctl addbr $bridge
1683
        brctl setfd $bridge 0
1684
        brctl addif $bridge $iface.$vlan
1685
        ifconfig $bridge up
1686
      done
1687

    
1688
The above will do the following :
1689

    
1690
 * provision 21 new bridges: ``prv0`` - ``prv20``
1691
 * provision 21 new vlans: ``eth0.0`` - ``eth0.20``
1692
 * add the corresponding vlan to the equivalent bridge
1693

    
1694
You can run ``brctl show`` on both nodes to see if everything was setup
1695
correctly.
1696

    
1697
Testing the Private Networks
1698
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1699

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

    
1705
We run the same command as in the Public Network testing section, but with one
1706
more argument for the second NIC:
1707

    
1708
.. code-block:: console
1709

    
1710
   # 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
1711
   # gnt-network connect test-net-prv-mac default bridged prv0
1712

    
1713
   # gnt-network add --network=10.0.0.0/24 --tags=nfdhcpd --network-type=private test-net-prv-vlan
1714
   # gnt-network connect test-net-prv-vlan default bridged prv1
1715

    
1716
   # gnt-instance add -o snf-image+default --os-parameters \
1717
                      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"}' \
1718
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1719
                      --net 0:ip=pool,network=test-net-public \
1720
                      --net 1:ip=pool,network=test-net-prv-mac \
1721
                      --net 2:ip=none,network=test-net-prv-vlan \
1722
                      testvm3
1723

    
1724
   # gnt-instance add -o snf-image+default --os-parameters \
1725
                      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"}' \
1726
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check \
1727
                      --net 0:ip=pool,network=test-net-public \
1728
                      --net 1:ip=pool,network=test-net-prv-mac \
1729
                      --net 2:ip=none,network=test-net-prv-vlan \
1730
                      testvm4
1731

    
1732
Above, we create two instances with first NIC connected to the internet, their
1733
second NIC connected to a MAC filtered private Network and their third NIC
1734
connected to the first Physical VLAN Private Network. Now, connect to the
1735
instances using VNC and make sure everything works as expected:
1736

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

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

    
1742
 c) ip link set ``eth1``/``eth2`` up
1743

    
1744
 d) dhclient ``eth1``/``eth2``
1745

    
1746
 e) On testvm3  ping 192.168.1.2/10.0.0.2
1747

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

    
1751
.. _cyclades-gtools:
1752

    
1753
Cyclades Ganeti tools
1754
---------------------
1755

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

    
1760
.. code-block:: console
1761

    
1762
   # apt-get install snf-cyclades-gtools
1763

    
1764
This will install the following:
1765

    
1766
 * ``snf-ganeti-eventd`` (daemon to publish Ganeti related messages on RabbitMQ)
1767
 * ``snf-ganeti-hook`` (all necessary hooks under ``/etc/ganeti/hooks``)
1768
 * ``snf-progress-monitor`` (used by ``snf-image`` to publish progress messages)
1769

    
1770
Configure ``snf-cyclades-gtools``
1771
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1772

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

    
1777
.. code-block:: console
1778

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

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

    
1784
Connect ``snf-image`` with ``snf-progress-monitor``
1785
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1786

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

    
1791
.. code-block:: console
1792

    
1793
   PROGRESS_MONITOR="snf-progress-monitor"
1794

    
1795
This file should be editted in all Ganeti nodes.
1796

    
1797
.. _rapi-user:
1798

    
1799
Synnefo RAPI user
1800
-----------------
1801

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

    
1807
.. code-block:: console
1808

    
1809
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1810

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

    
1813
.. code-block:: console
1814

    
1815
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1816

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

    
1820
You have now finished with all needed Prerequisites for Cyclades. Let's move on
1821
to the actual Cyclades installation.
1822

    
1823

    
1824
Installation of Cyclades on node1
1825
=================================
1826

    
1827
This section describes the installation of Cyclades. Cyclades is Synnefo's
1828
Compute service. The Image Service will get installed automatically along with
1829
Cyclades, because it is contained in the same Synnefo component.
1830

    
1831
We will install Cyclades on node1. To do so, we install the corresponding
1832
package by running on node1:
1833

    
1834
.. code-block:: console
1835

    
1836
   # apt-get install snf-cyclades-app memcached python-memcache
1837

    
1838
If all packages install successfully, then Cyclades are installed and we
1839
proceed with their configuration.
1840

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

    
1848
Configuration of Cyclades
1849
=========================
1850

    
1851
Conf files
1852
----------
1853

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

    
1861
Edit ``/etc/synnefo/20-snf-cyclades-app-api.conf``:
1862

    
1863
.. code-block:: console
1864

    
1865
   CYCLADES_BASE_URL = 'https://node1.example.com/cyclades'
1866
   ASTAKOS_BASE_URL = 'https://node1.example.com/astakos'
1867

    
1868
   # Set to False if astakos & cyclades are on the same host
1869
   CYCLADES_PROXY_USER_SERVICES = False
1870

    
1871
   CYCLADES_SERVICE_TOKEN = 'cyclades_service_token22w'
1872

    
1873
The ``ASTAKOS_BASE_URL`` denotes the Astakos endpoint for Cyclades,
1874
which is used for all user management, including authentication.
1875
Since our Astakos, Cyclades, and Pithos installations belong together,
1876
they should all have identical ``ASTAKOS_BASE_URL`` setting
1877
(see also, :ref:`previously <conf-pithos>`).
1878

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

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

    
1886
.. code-block:: console
1887

    
1888
   # snf-manage component-list
1889

    
1890
The token has been generated automatically during the :ref:`Cyclades service
1891
registration <services-reg>`.
1892

    
1893
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1894

    
1895
.. code-block:: console
1896

    
1897
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1898
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/astakos/ui/get_services'
1899
   CLOUDBAR_MENU_URL = 'https://node1.example.com/astakos/ui/get_menu'
1900

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

    
1909
Edit ``/etc/synnefo/20-snf-cyclades-app-plankton.conf``:
1910

    
1911
.. code-block:: console
1912

    
1913
   BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1914
   BACKEND_BLOCK_PATH = '/srv/pithos/data/'
1915

    
1916
In this file we configure the Image Service. ``BACKEND_DB_CONNECTION``
1917
denotes the Pithos database (where the Image files are stored). So we set that
1918
to point to our Pithos database. ``BACKEND_BLOCK_PATH`` denotes the actual
1919
Pithos data location.
1920

    
1921
Edit ``/etc/synnefo/20-snf-cyclades-app-queues.conf``:
1922

    
1923
.. code-block:: console
1924

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

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

    
1931
Edit ``/etc/synnefo/20-snf-cyclades-app-vmapi.conf``:
1932

    
1933
.. code-block:: console
1934

    
1935
   VMAPI_CACHE_BACKEND = "memcached://127.0.0.1:11211/?timeout=3600"
1936

    
1937
Edit ``/etc/default/vncauthproxy``:
1938

    
1939
.. code-block:: console
1940

    
1941
   CHUID="nobody:www-data"
1942

    
1943
We have now finished with the basic Cyclades configuration.
1944

    
1945
Database Initialization
1946
-----------------------
1947

    
1948
Once Cyclades is configured, we sync the database:
1949

    
1950
.. code-block:: console
1951

    
1952
   $ snf-manage syncdb
1953
   $ snf-manage migrate
1954

    
1955
and load the initial server flavors:
1956

    
1957
.. code-block:: console
1958

    
1959
   $ snf-manage loaddata flavors
1960

    
1961
If everything returns successfully, our database is ready.
1962

    
1963
Add the Ganeti backend
1964
----------------------
1965

    
1966
In our installation we assume that we only have one Ganeti cluster, the one we
1967
setup earlier.  At this point you have to add this backend (Ganeti cluster) to
1968
cyclades assuming that you have setup the :ref:`Rapi User <rapi-user>`
1969
correctly.
1970

    
1971
.. code-block:: console
1972

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

    
1975
You can see everything has been setup correctly by running:
1976

    
1977
.. code-block:: console
1978

    
1979
   $ snf-manage backend-list
1980

    
1981
Enable the new backend by running:
1982

    
1983
.. code-block::
1984

    
1985
   $ snf-manage backend-modify --drained False 1
1986

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

    
1993
If something is not set correctly, you can modify the backend with the
1994
``snf-manage backend-modify`` command. If something has gone wrong, you could
1995
modify the backend to reflect the Ganeti installation by running:
1996

    
1997
.. code-block:: console
1998

    
1999
   $ snf-manage backend-modify --clustername "ganeti.node1.example.com"
2000
                               --user=cyclades
2001
                               --pass=example_rapi_passw0rd
2002
                               1
2003

    
2004
``clustername`` denotes the Ganeti-cluster's name. We provide the corresponding
2005
domain that resolves to the master IP, than the IP itself, to ensure Cyclades
2006
can talk to Ganeti even after a Ganeti master-failover.
2007

    
2008
``user`` and ``pass`` denote the RAPI user's username and the RAPI user's
2009
password.  Once we setup the first backend to point at our Ganeti cluster, we
2010
update the Cyclades backends status by running:
2011

    
2012
.. code-block:: console
2013

    
2014
   $ snf-manage backend-update-status
2015

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

    
2020
Add a Public Network
2021
----------------------
2022

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

    
2029
.. code-block:: console
2030

    
2031
   $ snf-manage network-create --subnet=5.6.7.0/27 \
2032
                               --gateway=5.6.7.1 \
2033
                               --subnet6=2001:648:2FFC:1322::/64 \
2034
                               --gateway6=2001:648:2FFC:1322::1 \
2035
                               --public --dhcp --flavor=CUSTOM \
2036
                               --link=br0 --mode=bridged \
2037
                               --name=public_network \
2038
                               --backend-id=1
2039

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

    
2043
.. code-block:: console
2044

    
2045
   $ snf-manage reconcile-networks
2046

    
2047
You can see all available networks by running:
2048

    
2049
.. code-block:: console
2050

    
2051
   $ snf-manage network-list
2052

    
2053
and inspect each network's state by running:
2054

    
2055
.. code-block:: console
2056

    
2057
   $ snf-manage network-inspect <net_id>
2058

    
2059
Finally, you can see the networks from the Ganeti perspective by running on the
2060
Ganeti MASTER:
2061

    
2062
.. code-block:: console
2063

    
2064
   $ gnt-network list
2065
   $ gnt-network info <network_name>
2066

    
2067
Create pools for Private Networks
2068
---------------------------------
2069

    
2070
To prevent duplicate assignment of resources to different private networks,
2071
Cyclades supports two types of pools:
2072

    
2073
 - MAC prefix Pool
2074
 - Bridge Pool
2075

    
2076
As long as those resourses have been provisioned, admin has to define two
2077
these pools in Synnefo:
2078

    
2079

    
2080
.. code-block:: console
2081

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

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

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

    
2088
.. code-block:: console
2089

    
2090
   DEFAULT_MAC_FILTERED_BRIDGE = 'prv0'
2091

    
2092
Servers restart
2093
---------------
2094

    
2095
Restart gunicorn on node1:
2096

    
2097
.. code-block:: console
2098

    
2099
   # /etc/init.d/gunicorn restart
2100

    
2101
Now let's do the final connections of Cyclades with Ganeti.
2102

    
2103
``snf-dispatcher`` initialization
2104
---------------------------------
2105

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

    
2111
.. code-block:: console
2112

    
2113
   SNF_DSPTCH_ENABLE=true
2114

    
2115
and start the daemon:
2116

    
2117
.. code-block:: console
2118

    
2119
   # /etc/init.d/snf-dispatcher start
2120

    
2121
You can see that everything works correctly by tailing its log file
2122
``/var/log/synnefo/dispatcher.log``.
2123

    
2124
``snf-ganeti-eventd`` on GANETI MASTER
2125
--------------------------------------
2126

    
2127
The last step of the Cyclades setup is enabling the ``snf-ganeti-eventd``
2128
daemon (part of the :ref:`Cyclades Ganeti tools <cyclades-gtools>` package).
2129
The daemon is already installed on the GANETI MASTER (node1 in our case).
2130
``snf-ganeti-eventd`` is disabled by default during the ``snf-cyclades-gtools``
2131
installation, so we enable it in its configuration file
2132
``/etc/default/snf-ganeti-eventd``:
2133

    
2134
.. code-block:: console
2135

    
2136
   SNF_EVENTD_ENABLE=true
2137

    
2138
and start the daemon:
2139

    
2140
.. code-block:: console
2141

    
2142
   # /etc/init.d/snf-ganeti-eventd start
2143

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

    
2146
Apply Quota
2147
-----------
2148

    
2149
The following commands will check and fix the integrity of user quota.
2150
In a freshly installed system, these commands have no effect and can be
2151
skipped.
2152

    
2153
.. code-block:: console
2154

    
2155
   node1 # snf-manage quota --sync
2156
   node1 # snf-manage reconcile-resources-astakos --fix
2157
   node2 # snf-manage reconcile-resources-pithos --fix
2158
   node1 # snf-manage reconcile-resources-cyclades --fix
2159

    
2160

    
2161
If all the above return successfully, then you have finished with the Cyclades
2162
installation and setup.
2163

    
2164
Let's test our installation now.
2165

    
2166

    
2167
Testing of Cyclades
2168
===================
2169

    
2170
Cyclades Web UI
2171
---------------
2172

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

    
2177
 `http://node1.example.com/cyclades/ui/`
2178

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

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

    
2189
Cyclades Images
2190
---------------
2191

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

    
2197
 * Upload an Image file to Pithos
2198
 * Register that Image file to Cyclades
2199
 * Spawn a new VM from that Image from the Cyclades Web UI
2200

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

    
2204
Installation of `kamaki`
2205
~~~~~~~~~~~~~~~~~~~~~~~~
2206

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

    
2214
.. code-block:: console
2215

    
2216
   # apt-get install kamaki
2217

    
2218
Configuration of kamaki
2219
~~~~~~~~~~~~~~~~~~~~~~~
2220

    
2221
Now we need to setup kamaki, by adding the appropriate URLs and tokens of our
2222
installation. We do this by running:
2223

    
2224
.. code-block:: console
2225

    
2226
   $ kamaki config set cloud.default.url \
2227
       "https://node1.example.com/astakos/identity/v2.0"
2228
   $ kamaki config set cloud.default.token USER_TOKEN
2229

    
2230
Both the Authentication URL and the USER_TOKEN appear on the user's
2231
`API access` web page on the Astakos Web UI.
2232

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

    
2236
.. code-block:: console
2237

    
2238
   $ kamaki config list
2239

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

    
2243
.. code-block:: console
2244

    
2245
  $ kamaki user authenticate
2246

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

    
2250
Upload an Image file to Pithos
2251
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2252

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

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

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

    
2265
We create the new ``images`` container by running:
2266

    
2267
.. code-block:: console
2268

    
2269
   $ kamaki file create images
2270

    
2271
To check if the container has been created, list all containers of your
2272
account:
2273

    
2274
.. code-block:: console
2275

    
2276
  $ kamaki file list
2277

    
2278
Then, we upload the Image file to that container:
2279

    
2280
.. code-block:: console
2281

    
2282
   $ kamaki file upload /srv/images/debian_base-6.0-7-x86_64.diskdump images
2283

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

    
2287
.. code-block:: console
2288

    
2289
  $ kamaki file list images
2290

    
2291
Alternatively check if the new container and file appear on the Pithos Web UI.
2292

    
2293
Register an existing Image file to Cyclades
2294
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2295

    
2296
For the purposes of the following example, we assume that the user UUID is
2297
``u53r-un1qu3-1d``.
2298

    
2299
Once the Image file has been successfully uploaded on Pithos then we register
2300
it to Cyclades, by running:
2301

    
2302
.. code-block:: console
2303

    
2304
   $ kamaki image register "Debian Base" \
2305
                           pithos://u53r-un1qu3-1d/images/debian_base-6.0-11-x86_64.diskdump \
2306
                           --public \
2307
                           --disk-format=diskdump \
2308
                           --property OSFAMILY=linux --property ROOT_PARTITION=1 \
2309
                           --property description="Debian Squeeze Base System" \
2310
                           --property size=451 --property kernel=2.6.32 --property GUI="No GUI" \
2311
                           --property sortorder=1 --property USERS=root --property OS=debian
2312

    
2313
This command registers the Pithos file
2314
``pithos://u53r-un1qu3-1d/images/debian_base-6.0-11-x86_64.diskdump`` as an
2315
Image in Cyclades. This Image will be public (``--public``), so all users will
2316
be able to spawn VMs from it and is of type ``diskdump``. The first two
2317
properties (``OSFAMILY`` and ``ROOT_PARTITION``) are mandatory. All the rest
2318
properties are optional, but recommended, so that the Images appear nicely on
2319
the Cyclades Web UI. ``Debian Base`` will appear as the name of this Image. The
2320
``OS`` property's valid values may be found in the ``IMAGE_ICONS`` variable
2321
inside the ``20-snf-cyclades-app-ui.conf`` configuration file.
2322

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

    
2328
Spawn a VM from the Cyclades Web UI
2329
-----------------------------------
2330

    
2331
If the registration completes successfully, then go to the Cyclades Web UI from
2332
your browser at:
2333

    
2334
 `https://node1.example.com/cyclades/ui/`
2335

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

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

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

    
2352
Congratulations. You have successfully installed the whole Synnefo stack and
2353
connected all components. Go ahead in the next section to test the Network
2354
functionality from inside Cyclades and discover even more features.
2355

    
2356
General Testing
2357
===============
2358

    
2359
Notes
2360
=====
2361