Statistics
| Branch: | Tag: | Revision:

root / docs / quick-install-admin-guide.rst @ 62b10e3f

History | View | Annotate | Download (65.2 kB)

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

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

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

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

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

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

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

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

    
26

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

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

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

    
42

    
43
General Prerequisites
44
=====================
45

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

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

    
52
| ``deb http://apt.dev.grnet.gr squeeze main``
53
| ``deb-src http://apt.dev.grnet.gr squeeze main``
54

    
55
Also add the following line to enable the ``squeeze-backports`` repository,
56
which may provide more recent versions of certain packages. The repository
57
is deactivated by default and must be specified expicitly in ``apt-get``
58
operations:
59

    
60
| ``deb http://backports.debian.org/debian-backports squeeze-backports main``
61

    
62
You also need a shared directory visible by both nodes. Pithos+ will save all
63
data inside this directory. By 'all data', we mean files, images, and pithos
64
specific mapping data. If you plan to upload more than one basic image, this
65
directory should have at least 50GB of free space. During this guide, we will
66
assume that node1 acts as an NFS server and serves the directory ``/srv/pithos``
67
to node2. Node2 has this directory mounted under ``/srv/pithos``, too.
68

    
69
Before starting the synnefo installation, you will need basic third party
70
software to be installed and configured on the physical nodes. We will describe
71
each node's general prerequisites separately. Any additional configuration,
72
specific to a synnefo service for each node, will be described at the service's
73
section.
74

    
75
Node1
76
-----
77

    
78
General Synnefo dependencies
79
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80

    
81
 * apache (http server)
82
 * gunicorn (WSGI http server)
83
 * postgresql (database)
84
 * rabbitmq (message queue)
85

    
86
You can install the above by running:
87

    
88
.. code-block:: console
89

    
90
   # apt-get install apache2 postgresql rabbitmq-server
91

    
92
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
93
the official debian backports:
94

    
95
.. code-block:: console
96

    
97
   # apt-get -t squeeze-backports install gunicorn
98

    
99
On node1, we will create our databases, so you will also need the
100
python-psycopg2 package:
101

    
102
.. code-block:: console
103

    
104
   # apt-get install python-psycopg2
105

    
106
Database setup
107
~~~~~~~~~~~~~~
108

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

    
113
.. code-block:: console
114

    
115
   root@node1:~ # su - postgres
116
   postgres@node1:~ $ psql
117
   postgres=# CREATE DATABASE snf_apps WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
118
   postgres=# CREATE USER synnefo WITH PASSWORD 'example_passw0rd';
119
   postgres=# GRANT ALL PRIVILEGES ON DATABASE snf_apps TO synnefo;
120

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

    
126
.. code-block:: console
127

    
128
   postgres=# CREATE DATABASE snf_pithos WITH ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0;
129
   postgres=# GRANT ALL PRIVILEGES ON DATABASE snf_pithos TO synnefo;
130

    
131
Configure the database to listen to all network interfaces. You can do this by
132
editting the file ``/etc/postgresql/8.4/main/postgresql.conf`` and change
133
``listen_addresses`` to ``'*'`` :
134

    
135
.. code-block:: console
136

    
137
   listen_addresses = '*'
138

    
139
Furthermore, edit ``/etc/postgresql/8.4/main/pg_hba.conf`` to allow node1 and
140
node2 to connect to the database. Add the following lines under ``#IPv4 local
141
connections:`` :
142

    
143
.. code-block:: console
144

    
145
   host		all	all	4.3.2.1/32	md5
146
   host		all	all	4.3.2.2/32	md5
147

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

    
151
.. code-block:: console
152

    
153
   # /etc/init.d/postgresql restart
154

    
155
Gunicorn setup
156
~~~~~~~~~~~~~~
157

    
158
Create the file ``synnefo`` under ``/etc/gunicorn.d/`` containing the following:
159

    
160
.. code-block:: console
161

    
162
   CONFIG = {
163
    'mode': 'django',
164
    'environment': {
165
      'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
166
    },
167
    'working_dir': '/etc/synnefo',
168
    'user': 'www-data',
169
    'group': 'www-data',
170
    'args': (
171
      '--bind=127.0.0.1:8080',
172
      '--workers=4',
173
      '--log-level=debug',
174
    ),
175
   }
176

    
177
.. warning:: Do NOT start the server yet, because it won't find the
178
    ``synnefo.settings`` module. We will start the server after successful
179
    installation of astakos. If the server is running::
180

    
181
       # /etc/init.d/gunicorn stop
182

    
183
Apache2 setup
184
~~~~~~~~~~~~~
185

    
186
Create the file ``synnefo`` under ``/etc/apache2/sites-available/`` containing
187
the following:
188

    
189
.. code-block:: console
190

    
191
   <VirtualHost *:80>
192
     ServerName node1.example.com
193

    
194
     RewriteEngine On
195
     RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
196
     RewriteRule ^(.*)$ - [F,L]
197
     RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
198
   </VirtualHost>
199

    
200
Create the file ``synnefo-ssl`` under ``/etc/apache2/sites-available/``
201
containing the following:
202

    
203
.. code-block:: console
204

    
205
   <IfModule mod_ssl.c>
206
   <VirtualHost _default_:443>
207
     ServerName node1.example.com
208

    
209
     Alias /static "/usr/share/synnefo/static"
210

    
211
   #  SetEnv no-gzip
212
   #  SetEnv dont-vary
213

    
214
     AllowEncodedSlashes On
215

    
216
     RequestHeader set X-Forwarded-Protocol "https"
217

    
218
     <Proxy * >
219
       Order allow,deny
220
       Allow from all
221
     </Proxy>
222

    
223
     SetEnv                proxy-sendchunked
224
     SSLProxyEngine        off
225
     ProxyErrorOverride    off
226

    
227
     ProxyPass        /static !
228
     ProxyPass        / http://localhost:8080/ retry=0
229
     ProxyPassReverse / http://localhost:8080/
230

    
231
     RewriteEngine On
232
     RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
233
     RewriteRule ^(.*)$ - [F,L]
234
     RewriteRule ^/login(.*) /im/login/redirect$1 [PT,NE]
235

    
236
     SSLEngine on
237
     SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
238
     SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
239
   </VirtualHost>
240
   </IfModule>
241

    
242
Now enable sites and modules by running:
243

    
244
.. code-block:: console
245

    
246
   # a2enmod ssl
247
   # a2enmod rewrite
248
   # a2dissite default
249
   # a2ensite synnefo
250
   # a2ensite synnefo-ssl
251
   # a2enmod headers
252
   # a2enmod proxy_http
253

    
254
.. warning:: Do NOT start/restart the server yet. If the server is running::
255

    
256
       # /etc/init.d/apache2 stop
257

    
258
.. _rabbitmq-setup:
259

    
260
Message Queue setup
261
~~~~~~~~~~~~~~~~~~~
262

    
263
The message queue will run on node1, so we need to create the appropriate
264
rabbitmq user. The user is named ``synnefo`` and gets full privileges on all
265
exchanges:
266

    
267
.. code-block:: console
268

    
269
   # rabbitmqctl add_user synnefo "examle_rabbitmq_passw0rd"
270
   # rabbitmqctl set_permissions synnefo ".*" ".*" ".*"
271

    
272
We do not need to initialize the exchanges. This will be done automatically,
273
during the Cyclades setup.
274

    
275
Pithos+ data directory setup
276
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277

    
278
As mentioned in the General Prerequisites section, there is a directory called
279
``/srv/pithos`` visible by both nodes. We create and setup the ``data``
280
directory inside it:
281

    
282
.. code-block:: console
283

    
284
   # cd /srv/pithos
285
   # mkdir data
286
   # chown www-data:www-data data
287
   # chmod g+ws data
288

    
289
You are now ready with all general prerequisites concerning node1. Let's go to
290
node2.
291

    
292
Node2
293
-----
294

    
295
General Synnefo dependencies
296
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297

    
298
 * apache (http server)
299
 * gunicorn (WSGI http server)
300
 * postgresql (database)
301

    
302
You can install the above by running:
303

    
304
.. code-block:: console
305

    
306
   # apt-get install apache2 postgresql
307

    
308
Make sure to install gunicorn >= v0.12.2. You can do this by installing from
309
the official debian backports:
310

    
311
.. code-block:: console
312

    
313
   # apt-get -t squeeze-backports install gunicorn
314

    
315
Node2 will connect to the databases on node1, so you will also need the
316
python-psycopg2 package:
317

    
318
.. code-block:: console
319

    
320
   # apt-get install python-psycopg2
321

    
322
Database setup
323
~~~~~~~~~~~~~~
324

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

    
331
Gunicorn setup
332
~~~~~~~~~~~~~~
333

    
334
Create the file ``synnefo`` under ``/etc/gunicorn.d/`` containing the following
335
(same contents as in node1; you can just copy/paste the file):
336

    
337
.. code-block:: console
338

    
339
   CONFIG = {
340
    'mode': 'django',
341
    'environment': {
342
      'DJANGO_SETTINGS_MODULE': 'synnefo.settings',
343
    },
344
    'working_dir': '/etc/synnefo',
345
    'user': 'www-data',
346
    'group': 'www-data',
347
    'args': (
348
      '--bind=127.0.0.1:8080',
349
      '--workers=4',
350
      '--log-level=debug',
351
      '--timeout=43200'
352
    ),
353
   }
354

    
355
.. warning:: Do NOT start the server yet, because it won't find the
356
    ``synnefo.settings`` module. We will start the server after successful
357
    installation of astakos. If the server is running::
358

    
359
       # /etc/init.d/gunicorn stop
360

    
361
Apache2 setup
362
~~~~~~~~~~~~~
363

    
364
Create the file ``synnefo`` under ``/etc/apache2/sites-available/`` containing
365
the following:
366

    
367
.. code-block:: console
368

    
369
   <VirtualHost *:80>
370
     ServerName node2.example.com
371

    
372
     RewriteEngine On
373
     RewriteCond %{THE_REQUEST} ^.*(\\r|\\n|%0A|%0D).* [NC]
374
     RewriteRule ^(.*)$ - [F,L]
375
     RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
376
   </VirtualHost>
377

    
378
Create the file ``synnefo-ssl`` under ``/etc/apache2/sites-available/``
379
containing the following:
380

    
381
.. code-block:: console
382

    
383
   <IfModule mod_ssl.c>
384
   <VirtualHost _default_:443>
385
     ServerName node2.example.com
386

    
387
     Alias /static "/usr/share/synnefo/static"
388

    
389
     SetEnv no-gzip
390
     SetEnv dont-vary
391
     AllowEncodedSlashes On
392

    
393
     RequestHeader set X-Forwarded-Protocol "https"
394

    
395
     <Proxy * >
396
       Order allow,deny
397
       Allow from all
398
     </Proxy>
399

    
400
     SetEnv                proxy-sendchunked
401
     SSLProxyEngine        off
402
     ProxyErrorOverride    off
403

    
404
     ProxyPass        /static !
405
     ProxyPass        / http://localhost:8080/ retry=0
406
     ProxyPassReverse / http://localhost:8080/
407

    
408
     SSLEngine on
409
     SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
410
     SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
411
   </VirtualHost>
412
   </IfModule>
413

    
414
As in node1, enable sites and modules by running:
415

    
416
.. code-block:: console
417

    
418
   # a2enmod ssl
419
   # a2enmod rewrite
420
   # a2dissite default
421
   # a2ensite synnefo
422
   # a2ensite synnefo-ssl
423
   # a2enmod headers
424
   # a2enmod proxy_http
425

    
426
.. warning:: Do NOT start/restart the server yet. If the server is running::
427

    
428
       # /etc/init.d/apache2 stop
429

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

    
434

    
435
Installation of Astakos on node1
436
================================
437

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

    
442
.. code-block:: console
443

    
444
   # apt-get install snf-astakos-app
445

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

    
452
.. code-block:: console
453

    
454
   # apt-get install snf-webproject
455

    
456
The reason snf-webproject is "Recommended" and not a hard dependency, is to give
457
the experienced administrator the ability to install synnefo in a custom made
458
django project. This corner case concerns only very advanced users that know
459
what they are doing and want to experiment with synnefo.
460

    
461

    
462
.. _conf-astakos:
463

    
464
Configuration of Astakos
465
========================
466

    
467
Conf Files
468
----------
469

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

    
477
After getting familiar with synnefo, you will be able to customize the software
478
as you wish and fits your needs. Many options are available, to empower the
479
administrator with extensively customizable setups.
480

    
481
For the snf-webproject component (installed as an astakos dependency), we
482
need the following:
483

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

    
487
.. code-block:: console
488

    
489
   DATABASES = {
490
    'default': {
491
        # 'postgresql_psycopg2', 'postgresql','mysql', 'sqlite3' or 'oracle'
492
        'ENGINE': 'postgresql_psycopg2',
493
         # ATTENTION: This *must* be the absolute path if using sqlite3.
494
         # See: http://docs.djangoproject.com/en/dev/ref/settings/#name
495
        'NAME': 'snf_apps',
496
        'USER': 'synnefo',                      # Not used with sqlite3.
497
        'PASSWORD': 'examle_passw0rd',          # Not used with sqlite3.
498
        # Set to empty string for localhost. Not used with sqlite3.
499
        'HOST': '4.3.2.1',
500
        # Set to empty string for default. Not used with sqlite3.
501
        'PORT': '5432',
502
    }
503
   }
504

    
505
Edit ``/etc/synnefo/10-snf-webproject-deploy.conf``. Uncomment and edit
506
``SECRET_KEY``. This is a django specific setting which is used to provide a
507
seed in secret-key hashing algorithms. Set this to a random string of your
508
choise and keep it private:
509

    
510
.. code-block:: console
511

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

    
514
For astakos specific configuration, edit the following options in
515
``/etc/synnefo/20-snf-astakos-app-settings.conf`` :
516

    
517
.. code-block:: console
518

    
519
   ASTAKOS_IM_MODULES = ['local']
520

    
521
   ASTAKOS_COOKIE_DOMAIN = '.example.com'
522

    
523
   ASTAKOS_BASEURL = 'https://node1.example.com'
524

    
525
   ASTAKOS_SITENAME = '~okeanos demo example'
526

    
527
   ASTAKOS_RECAPTCHA_PUBLIC_KEY = 'example_recaptcha_public_key!@#$%^&*('
528
   ASTAKOS_RECAPTCHA_PRIVATE_KEY = 'example_recaptcha_private_key!@#$%^&*('
529

    
530
   ASTAKOS_RECAPTCHA_USE_SSL = True
531

    
532
``ASTAKOS_IM_MODULES`` refers to the astakos login methods. For now only local
533
is supported. The ``ASTAKOS_COOKIE_DOMAIN`` should be the base url of our
534
domain (for all services). ``ASTAKOS_BASEURL`` is the astakos home page.
535

    
536
For the ``ASTAKOS_RECAPTCHA_PUBLIC_KEY`` and ``ASTAKOS_RECAPTCHA_PRIVATE_KEY``
537
go to https://www.google.com/recaptcha/admin/create and create your own pair.
538

    
539
Then edit ``/etc/synnefo/20-snf-astakos-app-cloudbar.conf`` :
540

    
541
.. code-block:: console
542

    
543
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
544

    
545
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/im/get_services'
546

    
547
   CLOUDBAR_MENU_URL = 'https://node1.example.com/im/get_menu'
548

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

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

    
556
Database Initialization
557
-----------------------
558

    
559
After configuration is done, we initialize the database by running:
560

    
561
.. code-block:: console
562

    
563
   # snf-manage syncdb
564

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

    
569
.. code-block:: console
570

    
571
   # snf-manage migrate im
572

    
573
Then, we load the pre-defined user groups
574

    
575
.. code-block:: console
576

    
577
   # snf-manage loaddata groups
578

    
579
.. _services-reg:
580

    
581
Services Registration
582
---------------------
583

    
584
When the database is ready, we configure the elements of the Astakos cloudbar,
585
to point to our future services:
586

    
587
.. code-block:: console
588

    
589
   # snf-manage service-add "~okeanos home" https://node1.example.com/im/ home-icon.png
590
   # snf-manage service-add "cyclades" https://node1.example.com/ui/
591
   # snf-manage service-add "pithos+" https://node2.example.com/ui/
592

    
593
Servers Initialization
594
----------------------
595

    
596
Finally, we initialize the servers on node1:
597

    
598
.. code-block:: console
599

    
600
   root@node1:~ # /etc/init.d/gunicorn restart
601
   root@node1:~ # /etc/init.d/apache2 restart
602

    
603
We have now finished the Astakos setup. Let's test it now.
604

    
605

    
606
Testing of Astakos
607
==================
608

    
609
Open your favorite browser and go to:
610

    
611
``http://node1.example.com/im``
612

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

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

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

    
624
.. code-block:: console
625

    
626
   root@node1:~ # snf-manage user-list
627

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

    
632
.. code-block:: console
633

    
634
   root@node1:~ # snf-manage user-modify --set-active 1
635

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

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

    
649
Let's continue to install Pithos+ now.
650

    
651

    
652
Installation of Pithos+ on node2
653
================================
654

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

    
659
.. code-block:: console
660

    
661
   # apt-get install snf-pithos-app
662

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

    
668
.. code-block:: console
669

    
670
   # apt-get install snf-pithos-webclient
671

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

    
676

    
677
.. _conf-pithos:
678

    
679
Configuration of Pithos+
680
========================
681

    
682
Conf Files
683
----------
684

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

    
691
Edit ``/etc/synnefo/20-snf-pithos-app-settings.conf``. There you need to set
692
only the two options:
693

    
694
.. code-block:: console
695

    
696
   PITHOS_BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
697

    
698
   PITHOS_BACKEND_BLOCK_PATH = '/srv/pithos/data'
699

    
700
   PITHOS_AUTHENTICATION_URL = 'https://node1.example.com/im/authenticate'
701
   PITHOS_AUTHENTICATION_USERS = None
702

    
703
   PITHOS_SERVICE_TOKEN = 'pithos_service_token22w=='
704

    
705
The ``PITHOS_BACKEND_DB_CONNECTION`` option tells to the pithos+ app where to
706
find the pithos+ backend database. Above we tell pithos+ that its database is
707
``snf_pithos`` at node1 and to connect as user ``synnefo`` with password
708
``example_passw0rd``.  All those settings where setup during node1's "Database
709
setup" section.
710

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

    
716
The ``PITHOS_AUTHENTICATION_URL`` option tells to the pithos+ app in which URI
717
is available the astakos authentication api. If not set, pithos+ tries to
718
authenticate using the ``PITHOS_AUTHENTICATION_USERS`` user pool.
719

    
720
The ``PITHOS_SERVICE_TOKEN`` should be the Pithos+ token returned by running on
721
the Astakos node (node1 in our case):
722

    
723
.. code-block:: console
724

    
725
   # snf-manage service-list
726

    
727
The token has been generated automatically during the :ref:`Pithos+ service
728
registration <services-reg>`.
729

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

    
733
.. code-block:: console
734

    
735
   PITHOS_UI_LOGIN_URL = "https://node1.example.com/im/login?next="
736
   PITHOS_UI_FEEDBACK_URL = "https://node1.example.com/im/feedback"
737

    
738
The ``PITHOS_UI_LOGIN_URL`` option tells the client where to redirect you, if
739
you are not logged in. The ``PITHOS_UI_FEEDBACK_URL`` option points at the
740
pithos+ feedback form. Astakos already provides a generic feedback form for all
741
services, so we use this one.
742

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

    
746
.. code-block:: console
747

    
748
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
749
   PITHOS_UI_CLOUDBAR_ACTIVE_SERVICE = '3'
750
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/im/get_services'
751
   CLOUDBAR_MENU_URL = 'https://node1.example.com/im/get_menu'
752

    
753
The ``CLOUDBAR_LOCATION`` tells the client where to find the astakos common
754
cloudbar.
755

    
756
The ``PITHOS_UI_CLOUDBAR_ACTIVE_SERVICE`` points to an already registered
757
Astakos service. You can see all :ref:`registered services <services-reg>` by
758
running on the Astakos node (node1):
759

    
760
.. code-block:: console
761

    
762
   # snf-manage service-list
763

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

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

    
771
Servers Initialization
772
----------------------
773

    
774
After configuration is done, we initialize the servers on node2:
775

    
776
.. code-block:: console
777

    
778
   root@node2:~ # /etc/init.d/gunicorn restart
779
   root@node2:~ # /etc/init.d/apache2 restart
780

    
781
You have now finished the Pithos+ setup. Let's test it now.
782

    
783

    
784
Testing of Pithos+
785
==================
786

    
787
Open your browser and go to the Astakos homepage:
788

    
789
``http://node1.example.com/im``
790

    
791
Login, and you will see your profile page. Now, click the "pithos+" link on the
792
top black cloudbar. If everything was setup correctly, this will redirect you
793
to:
794

    
795
``https://node2.example.com/ui``
796

    
797
and you will see the blue interface of the Pithos+ application.  Click the
798
orange "Upload" button and upload your first file. If the file gets uploaded
799
successfully, then this is your first sign of a successful Pithos+ installation.
800
Go ahead and experiment with the interface to make sure everything works
801
correctly.
802

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

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

    
808
If you would like to do more, such as:
809

    
810
 * Spawning VMs
811
 * Spawning VMs from Images stored on Pithos+
812
 * Uploading your custom Images to Pithos+
813
 * Spawning VMs from those custom Images
814
 * Registering existing Pithos+ files as Images
815
 * Connect VMs to the Internet
816
 * Create Private Networks
817
 * Add VMs to Private Networks
818

    
819
please continue with the rest of the guide.
820

    
821

    
822
Cyclades (and Plankton) Prerequisites
823
=====================================
824

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

    
830
Besides Astakos and Pithos+, you will also need a number of additional working
831
prerequisites, before you start the Cyclades installation.
832

    
833
Ganeti
834
------
835

    
836
`Ganeti <http://code.google.com/p/ganeti/>`_ handles the low level VM management
837
for Cyclades, so Cyclades requires a working Ganeti installation at the backend.
838
Please refer to the
839
`ganeti documentation <http://docs.ganeti.org/ganeti/2.5/html>`_ for all the
840
gory details. A successful Ganeti installation concludes with a working
841
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs
842
<GANETI_NODES>`.
843

    
844
The above Ganeti cluster can run on different physical machines than node1 and
845
node2 and can scale independently, according to your needs.
846

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

    
851
We highly recommend that you read the official Ganeti documentation, if you are
852
not familiar with Ganeti. If you are extremely impatient, you can result with
853
the above assumed setup by running:
854

    
855
.. code-block:: console
856

    
857
   root@node1:~ # apt-get install ganeti2
858
   root@node1:~ # apt-get install ganeti-htools
859
   root@node2:~ # apt-get install ganeti2
860
   root@node2:~ # apt-get install ganeti-htools
861

    
862
We assume that Ganeti will use the KVM hypervisor. After installing Ganeti on
863
both nodes, choose a domain name that resolves to a valid floating IP (let's say
864
it's ``ganeti.node1.example.com``). Make sure node1 and node2 have root access
865
between each other using ssh keys and not passwords. Also, make sure there is an
866
lvm volume group named ``ganeti`` that will host your VMs' disks. Finally, setup
867
a bridge interface on the host machines (e.g:: br0). Then run on node1:
868

    
869
.. code-block:: console
870

    
871
   root@node1:~ # gnt-cluster init --enabled-hypervisors=kvm --no-ssh-init
872
                                   --no-etc-hosts --vg-name=ganeti
873
                                   --nic-parameters link=br0 --master-netdev eth0
874
                                   ganeti.node1.example.com
875
   root@node1:~ # gnt-cluster modify --default-iallocator hail
876
   root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:kernel_path=
877
   root@node1:~ # gnt-cluster modify --hypervisor-parameters kvm:vnc_bind_address=0.0.0.0
878

    
879
   root@node1:~ # gnt-node add --no-node-setup --master-capable=yes
880
                               --vm-capable=yes node2.example.com
881

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

    
886
.. _cyclades-install-snfimage:
887

    
888
snf-image
889
---------
890

    
891
Installation
892
~~~~~~~~~~~~
893
For :ref:`Cyclades <cyclades>` to be able to launch VMs from specified Images,
894
you need the :ref:`snf-image <snf-image>` OS Definition installed on *all*
895
VM-capable Ganeti nodes. This means we need :ref:`snf-image <snf-image>` on
896
node1 and node2. You can do this by running on *both* nodes:
897

    
898
.. code-block:: console
899

    
900
   # apt-get install snf-image-host snf-pithos-backend python-psycopg2
901

    
902
snf-image also needs the `snf-pithos-backend <snf-pithos-backend>`, to be able to
903
handle image files stored on Pithos+. It also needs `python-psycopg2` to be able
904
to access the Pithos+ database. This is why, we also install them on *all*
905
VM-capable Ganeti nodes.
906

    
907
Now, you need to download and save the corresponding helper package. Please see
908
`here <https://code.grnet.gr/projects/snf-image/files>`_ for the latest package. Let's
909
assume that you installed snf-image-host version 0.4.4-1. Then, you need
910
snf-image-helper v0.4.4-1 on *both* nodes:
911

    
912
.. code-block:: console
913

    
914
   # cd /var/lib/snf-image/helper/
915
   # wget https://code.grnet.gr/attachments/download/1058/snf-image-helper_0.4.4-1_all.deb
916

    
917
.. warning:: Be careful: Do NOT install the snf-image-helper debian package.
918
             Just put it under /var/lib/snf-image/helper/
919

    
920
Once, you have downloaded the snf-image-helper package, create the helper VM by
921
running on *both* nodes:
922

    
923
.. code-block:: console
924

    
925
   # ln -s snf-image-helper_0.4.4-1_all.deb snf-image-helper.deb
926
   # snf-image-update-helper
927

    
928
This will create all the needed files under ``/var/lib/snf-image/helper/`` for
929
snf-image-host to run successfully.
930

    
931
Configuration
932
~~~~~~~~~~~~~
933
snf-image supports native access to Images stored on Pithos+. This means that
934
snf-image can talk directly to the Pithos+ backend, without the need of providing
935
a public URL. More details, are described in the next section. For now, the only
936
thing we need to do, is configure snf-image to access our Pithos+ backend.
937

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

    
941
.. code-block:: console
942

    
943
   PITHOS_DB="postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos"
944

    
945
   PITHOS_DATA="/srv/pithos/data"
946

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

    
950
If you would like to use Images that are also/only stored locally, you need to
951
save them under ``IMAGE_DIR``, however this guide targets Images stored only on
952
Pithos+.
953

    
954
Testing
955
~~~~~~~
956
You can test that snf-image is successfully installed by running on the
957
:ref:`GANETI-MASTER <GANETI_NODES>` (in our case node1):
958

    
959
.. code-block:: console
960

    
961
   # gnt-os diagnose
962

    
963
This should return ``valid`` for snf-image.
964

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

    
971
.. _snf-image-images:
972

    
973
snf-image's actual Images
974
-------------------------
975

    
976
Now that snf-image is installed successfully we need to provide it with some
977
Images. :ref:`snf-image <snf-image>` supports Images stored in ``extdump``,
978
``ntfsdump`` or ``diskdump`` format. We recommend the use of the ``diskdump``
979
format. For more information about snf-image's Image formats see `here
980
<https://code.grnet.gr/projects/snf-image/wiki/Image_Format>`_.
981

    
982
:ref:`snf-image <snf-image>` also supports three (3) different locations for the
983
above Images to be stored:
984

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

    
990
For the purpose of this guide, we will use the `Debian Squeeze Base Image
991
<https://pithos.okeanos.grnet.gr/public/9epgb>`_ found on the official
992
`snf-image page
993
<https://code.grnet.gr/projects/snf-image/wiki#Sample-Images>`_. The image is
994
of type ``diskdump``. We will store it in our new Pithos+ installation.
995

    
996
To do so, do the following:
997

    
998
a) Download the Image from the official snf-image page (`image link
999
   <https://pithos.okeanos.grnet.gr/public/9epgb>`_).
1000

    
1001
b) Upload the Image to your Pithos+ installation, either using the Pithos+ Web UI
1002
   or the command line client `kamaki
1003
   <http://docs.dev.grnet.gr/kamaki/latest/index.html>`_.
1004

    
1005
Once the Image is uploaded successfully, download the Image's metadata file
1006
from the official snf-image page (`image_metadata link
1007
<https://pithos.okeanos.grnet.gr/public/gwqcv>`_). You will need it, for
1008
spawning a VM from Ganeti, in the next section.
1009

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

    
1014
.. _ganeti-with-pithos-images:
1015

    
1016
Spawning a VM from a Pithos+ Image, using Ganeti
1017
------------------------------------------------
1018

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

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

    
1027
.. code-block:: console
1028

    
1029
   # gnt-instance add -o snf-image+default --os-parameters
1030
                      img_passwd=my_vm_example_passw0rd,
1031
                      img_format=diskdump,
1032
                      img_id="pithos://user@example.com/pithos/debian_base-6.0-7-x86_64.diskdump",
1033
                      img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}'
1034
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check
1035
                      testvm1
1036

    
1037
In the above command:
1038

    
1039
 * ``img_passwd``: the arbitrary root password of your new instance
1040
 * ``img_format``: set to ``diskdump`` to reflect the type of the uploaded Image
1041
 * ``img_id``: If you want to deploy an Image stored on Pithos+ (our case), this
1042
               should have the format
1043
               ``pithos://<username>/<container>/<filename>``:
1044
                * ``username``: ``user@example.com`` (defined during Astakos sign up)
1045
                * ``container``: ``pithos`` (default, if the Web UI was used)
1046
                * ``filename``: the name of file (visible also from the Web UI)
1047
 * ``img_properties``: taken from the metadata file. Used only the two mandatory
1048
                       properties ``OSFAMILY`` and ``ROOT_PARTITION``. `Learn more
1049
                       <https://code.grnet.gr/projects/snf-image/wiki/Image_Format#Image-Properties>`_
1050

    
1051
If the ``gnt-instance add`` command returns successfully, then run:
1052

    
1053
.. code-block:: console
1054

    
1055
   # gnt-instance info testvm1 | grep "console connection"
1056

    
1057
to find out where to connect using VNC. If you can connect successfully and can
1058
login to your new instance using the root password ``my_vm_example_passw0rd``,
1059
then everything works as expected and you have your new Debian Base VM up and
1060
running.
1061

    
1062
If ``gnt-instance add`` fails, make sure that snf-image is correctly configured
1063
to access the Pithos+ database and the Pithos+ backend data. Also, make sure
1064
you gave the correct ``img_id`` and ``img_properties``. If ``gnt-instance add``
1065
succeeds but you cannot connect, again find out what went wrong. Do *NOT*
1066
proceed to the next steps unless you are sure everything works till this point.
1067

    
1068
If everything works, you have successfully connected Ganeti with Pithos+. Let's
1069
move on to networking now.
1070

    
1071
.. warning::
1072
    You can bypass the networking sections and go straight to
1073
    :ref:`Cyclades Ganeti tools <cyclades-gtools>`, if you do not want to setup
1074
    the Cyclades Network Service, but only the Cyclades Compute Service
1075
    (recommended for now).
1076

    
1077
Network setup overview
1078
----------------------
1079

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

    
1086
Public Network setup
1087
--------------------
1088

    
1089
Physical hosts' public network setup
1090
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1091

    
1092
The physical hosts' setup is out of the scope of this guide.
1093

    
1094
However, two common cases that you may want to consider (and choose from) are:
1095

    
1096
a) One public bridge, where all VMs' public tap interfaces will connect.
1097
b) IP-less routing over the same vlan on every host.
1098

    
1099
When you setup your physical hosts (node1 and node2) for the Public Network,
1100
then you need to inform Ganeti about the Network's IP range.
1101

    
1102
Add the public network to Ganeti
1103
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1104

    
1105
Once you have Ganeti with IP pool management up and running, you need to choose
1106
the public network for your VMs and add it to Ganeti. Let's assume, that you
1107
want to assign IPs from the ``5.6.7.0/27`` range to your new VMs, with
1108
``5.6.7.1`` as their gateway. You can add the network by running:
1109

    
1110
.. code-block:: console
1111

    
1112
   # gnt-network add --network=5.6.7.0/27 --gateway=5.6.7.1 public_network
1113

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

    
1117
.. code-block:: console
1118

    
1119
   # gnt-network connect public_network default public_link
1120

    
1121
Your new network is now ready from the Ganeti perspective. Now, we need to setup
1122
`NFDHCPD` to actually reply with the correct IPs (that Ganeti will choose for
1123
each NIC).
1124

    
1125
NFDHCPD
1126
~~~~~~~
1127

    
1128
At this point, Ganeti knows about your preferred network, it can manage the IP
1129
pool and choose a specific IP for each new VM's NIC. However, the actual
1130
assignment of the IP to the NIC is not done by Ganeti. It is done after the VM
1131
boots and its dhcp client makes a request. When this is done, `NFDHCPD` will
1132
reply to the request with Ganeti's chosen IP. So, we need to install `NFDHCPD`
1133
on all VM-capable nodes of the Ganeti cluster (node1 and node2 in our case) and
1134
connect it to Ganeti:
1135

    
1136
.. code-block:: console
1137

    
1138
   # apt-get install nfdhcpd
1139

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

    
1145
.. code-block:: console
1146

    
1147
   # /etc/init.d/nfdhcpd restart
1148

    
1149
If you are using ``ferm``, then you need to run the following:
1150

    
1151
.. code-block:: console
1152

    
1153
   # echo "@include 'nfdhcpd.ferm';" >> /etc/ferm/ferm.conf
1154
   # /etc/init.d/ferm restart
1155

    
1156
Now, you need to connect `NFDHCPD` with Ganeti. To do that, you need to install
1157
a custom KVM ifup script for use by Ganeti, as ``/etc/ganeti/kvm-vif-bridge``,
1158
on all VM-capable GANETI-NODEs (node1 and node2). A sample implementation is
1159
provided along with `snf-cyclades-gtools <snf-cyclades-gtools>`, that will
1160
be installed in the next sections, however you will probably need to write your
1161
own, according to your underlying network configuration.
1162

    
1163
Testing the Public Network
1164
~~~~~~~~~~~~~~~~~~~~~~~~~~
1165

    
1166
So, we have setup the bridges/vlans on the physical hosts appropriately, we have
1167
added the desired network to Ganeti, we have installed nfdhcpd and installed the
1168
appropriate ``kvm-vif-bridge`` script under ``/etc/ganeti``.
1169

    
1170
Now, it is time to test that the backend infrastracture is correctly setup for
1171
the Public Network. We assume to have used the (b) method on setting up the
1172
physical hosts. We will add a new VM, the same way we did it on the previous
1173
testing section. However, now will also add one NIC, configured to be managed
1174
from our previously defined network. Run on the GANETI-MASTER (node1):
1175

    
1176
.. code-block:: console
1177

    
1178
   # gnt-instance add -o snf-image+default --os-parameters
1179
                      img_passwd=my_vm_example_passw0rd,
1180
                      img_format=diskdump,
1181
                      img_id="pithos://user@example.com/pithos/debian_base-6.0-7-x86_64.diskdump",
1182
                      img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}'
1183
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check
1184
                      --net 0:ip=pool,mode=routed,link=public_link
1185
                      testvm2
1186

    
1187
If the above returns successfully, connect to the new VM and run:
1188

    
1189
.. code-block:: console
1190

    
1191
   root@testvm2:~ # ifconfig -a
1192

    
1193
If a network interface appears with an IP from you Public Network's range
1194
(``5.6.7.0/27``) and the corresponding gateway, then you have successfully
1195
connected Ganeti with `NFDHCPD` (and ``kvm-vif-bridge`` works correctly).
1196

    
1197
Now ping the outside world. If this works too, then you have also configured
1198
correctly your physical hosts' networking.
1199

    
1200
Later, Cyclades will create the first NIC of every new VM by issuing an
1201
analogous command. The first NIC of the instance will be the NIC connected to
1202
the Public Network. The ``link`` variable will be set accordingly in the
1203
Cyclades conf files later on the guide.
1204

    
1205
Make sure everything works as expected, before proceeding with the Private
1206
Networks setup.
1207

    
1208
.. _private-networks-setup:
1209

    
1210
Private Networks setup
1211
----------------------
1212

    
1213
Physical hosts' private networks setup
1214
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1215

    
1216
At the physical host's level, it is the administrator's responsibility to
1217
configure the network appropriately, according to his/her needs (as for the
1218
Public Network).
1219

    
1220
However we propose the following setup:
1221

    
1222
For every possible Private Network we assume a pre-provisioned bridge interface
1223
exists on every host with the same name. Every Private Network will be
1224
associated with one of the pre-provisioned bridges. Then the instance's new NIC
1225
(while connecting to the Private Network) will be connected to that bridge. All
1226
instances' tap interfaces that reside in the same Private Network will be
1227
connected in the corresponding bridge of that network. Furthermore, every
1228
bridge will be connected to a corresponding vlan. So, lets assume that our
1229
Cyclades installation allows for 20 Private Networks to be setup. We should
1230
pre-provision the corresponding bridges and vlans to all the hosts. We can do
1231
this by running on all VM-capable Ganeti nodes (in our case node1 and node2):
1232

    
1233
.. code-block:: console
1234

    
1235
   # $iface=eth0
1236
   # for prv in $(seq 1 20); do
1237
	vlan=$prv
1238
	bridge=prv$prv
1239
	vconfig add $iface $vlan
1240
	ifconfig $iface.$vlan up
1241
	brctl addbr $bridge
1242
	brctl setfd $bridge 0
1243
	brctl addif $bridge $iface.$vlan
1244
	ifconfig $bridge up
1245
      done
1246

    
1247
The above will do the following (assuming ``eth0`` exists on both hosts):
1248

    
1249
 * provision 20 new bridges: ``prv1`` - ``prv20``
1250
 * provision 20 new vlans: ``eth0.1`` - ``eth0.20``
1251
 * add the corresponding vlan to the equivelant bridge
1252

    
1253
You can run ``brctl show`` on both nodes to see if everything was setup
1254
correctly.
1255

    
1256
Everything is now setup to support the 20 Cyclades Private Networks. Later,
1257
we will configure Cyclades to talk to those 20 pre-provisioned bridges.
1258

    
1259
Testing the Private Networks
1260
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1261

    
1262
To test the Private Networks, we will create two instances and put them in the
1263
same Private Network (``prv1``). This means that the instances will have a
1264
second NIC connected to the ``prv1`` pre-provisioned bridge.
1265

    
1266
We run the same command as in the Public Network testing section, but with one
1267
more argument for the second NIC:
1268

    
1269
.. code-block:: console
1270

    
1271
   # gnt-instance add -o snf-image+default --os-parameters
1272
                      img_passwd=my_vm_example_passw0rd,
1273
                      img_format=diskdump,
1274
                      img_id="pithos://user@example.com/pithos/debian_base-6.0-7-x86_64.diskdump",
1275
                      img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}'
1276
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check
1277
                      --net 0:ip=pool,mode=routed,link=public_link
1278
                      --net 1:ip=none,mode=bridged,link=prv1
1279
                      testvm3
1280

    
1281
   # gnt-instance add -o snf-image+default --os-parameters
1282
                      img_passwd=my_vm_example_passw0rd,
1283
                      img_format=diskdump,
1284
                      img_id="pithos://user@example.com/pithos/debian_base-6.0-7-x86_64.diskdump",
1285
                      img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}'
1286
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check
1287
                      --net 0:ip=pool,mode=routed,link=public_link
1288
                      --net 1:ip=none,mode=bridged,link=prv1
1289
                      testvm4
1290

    
1291
Above, we create two instances with their first NIC connected to the Public
1292
Network and their second NIC connected to the first Private Network (``prv1``).
1293
Now, connect to the instances using VNC and make sure everything works as
1294
expected:
1295

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

    
1299
b) Setup the second eth interface of the instances (``eth1``), by assigning two
1300
   different private IPs (e.g.: ``10.0.0.1`` and ``10.0.0.2``) and the
1301
   corresponding netmask. If they ``ping`` each other successfully, then
1302
   the Private Network works.
1303

    
1304
Repeat the procedure with more instances connected in different Private Networks
1305
(``prv{1-20}``), by adding more NICs on each instance. e.g.: We add an instance
1306
connected to the Public Network and Private Networks 1, 3 and 19:
1307

    
1308
.. code-block:: console
1309

    
1310
   # gnt-instance add -o snf-image+default --os-parameters
1311
                      img_passwd=my_vm_example_passw0rd,
1312
                      img_format=diskdump,
1313
                      img_id="pithos://user@example.com/pithos/debian_base-6.0-7-x86_64.diskdump",
1314
                      img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}'
1315
                      -t plain --disk 0:size=2G --no-name-check --no-ip-check
1316
                      --net 0:ip=pool,mode=routed,link=public_link
1317
                      --net 1:ip=none,mode=bridged,link=prv1
1318
                      --net 2:ip=none,mode=bridged,link=prv3
1319
                      --net 3:ip=none,mode=bridged,link=prv19
1320
                      testvm5
1321

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

    
1325
.. _cyclades-gtools:
1326

    
1327
Cyclades Ganeti tools
1328
---------------------
1329

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

    
1334
.. code-block:: console
1335

    
1336
   # apt-get install snf-cyclades-gtools
1337

    
1338
This will install the following:
1339

    
1340
 * ``snf-ganeti-eventd`` (daemon to publish Ganeti related messages on RabbitMQ)
1341
 * ``snf-ganeti-hook`` (all necessary hooks under ``/etc/ganeti/hooks``)
1342
 * ``snf-progress-monitor`` (used by ``snf-image`` to publish progress messages)
1343

    
1344
Configure ``snf-cyclades-gtools``
1345
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1346

    
1347
The package will install the ``/etc/synnefo/10-snf-cyclades-gtools-backend.conf``
1348
configuration file. At least we need to set the RabbitMQ endpoint for all tools
1349
that need it:
1350

    
1351
.. code-block:: console
1352

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

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

    
1358
Connect ``snf-image`` with ``snf-progress-monitor``
1359
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1360

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

    
1365
.. code-block:: console
1366

    
1367
   PROGRESS_MONITOR="snf-progress-monitor"
1368

    
1369
This file should be editted in all Ganeti nodes.
1370

    
1371
.. _rapi-user:
1372

    
1373
Synnefo RAPI user
1374
-----------------
1375

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

    
1381
.. code-block:: console
1382

    
1383
   # echo -n 'cyclades:Ganeti Remote API:example_rapi_passw0rd' | openssl md5
1384

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

    
1387
.. code-block:: console
1388

    
1389
   cyclades {HA1}55aec7050aa4e4b111ca43cb505a61a0 write
1390

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

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

    
1397

    
1398
Installation of Cyclades (and Plankton) on node1
1399
================================================
1400

    
1401
This section describes the installation of Cyclades. Cyclades is Synnefo's
1402
Compute service. Plankton (the Image Registry service) will get installed
1403
automatically along with Cyclades, because it is contained in the same Synnefo
1404
component right now.
1405

    
1406
We will install Cyclades (and Plankton) on node1. To do so, we install the
1407
corresponding package by running on node1:
1408

    
1409
.. code-block:: console
1410

    
1411
   # apt-get install snf-cyclades-app
1412

    
1413
.. warning:: Make sure you have installed ``python-gevent`` version >= 0.13.6.
1414
    This version is available at squeeze-backports and can be installed by
1415
    running: ``apt-get install -t squeeze-backports python-gevent``
1416

    
1417
If all packages install successfully, then Cyclades and Plankton are installed
1418
and we proceed with their configuration.
1419

    
1420

    
1421
Configuration of Cyclades (and Plankton)
1422
========================================
1423

    
1424
Conf files
1425
----------
1426

    
1427
After installing Cyclades, a number of new configuration files will appear under
1428
``/etc/synnefo/`` prefixed with ``20-snf-cyclades-app-``. We will descibe here
1429
only the minimal needed changes to result with a working system. In general, sane
1430
defaults have been chosen for the most of the options, to cover most of the
1431
common scenarios. However, if you want to tweak Cyclades feel free to do so,
1432
once you get familiar with the different options.
1433

    
1434
Edit ``/etc/synnefo/20-snf-cyclades-app-api.conf``:
1435

    
1436
.. code-block:: console
1437

    
1438
   ASTAKOS_URL = 'https://node1.example.com/im/authenticate'
1439

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

    
1444
TODO: Document the Network Options here
1445

    
1446
Edit ``/etc/synnefo/20-snf-cyclades-app-cloudbar.conf``:
1447

    
1448
.. code-block:: console
1449

    
1450
   CLOUDBAR_LOCATION = 'https://node1.example.com/static/im/cloudbar/'
1451
   CLOUDBAR_ACTIVE_SERVICE = '2'
1452
   CLOUDBAR_SERVICES_URL = 'https://node1.example.com/im/get_services'
1453
   CLOUDBAR_MENU_URL = 'https://account.node1.example.com/im/get_menu'
1454

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

    
1463
The ``CLOUDBAR_ACTIVE_SERVICE`` points to an already registered Astakos
1464
service. You can see all :ref:`registered services <services-reg>` by running
1465
on the Astakos node (node1):
1466

    
1467
.. code-block:: console
1468

    
1469
   # snf-manage service-list
1470

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

    
1474
Edit ``/etc/synnefo/20-snf-cyclades-app-plankton.conf``:
1475

    
1476
.. code-block:: console
1477

    
1478
   BACKEND_DB_CONNECTION = 'postgresql://synnefo:example_passw0rd@node1.example.com:5432/snf_pithos'
1479
   BACKEND_BLOCK_PATH = '/srv/pithos/data/'
1480

    
1481
In this file we configure the Plankton Service. ``BACKEND_DB_CONNECTION``
1482
denotes the Pithos+ database (where the Image files are stored). So we set that
1483
to point to our Pithos+ database. ``BACKEND_BLOCK_PATH`` denotes the actual
1484
Pithos+ data location.
1485

    
1486
Edit ``/etc/synnefo/20-snf-cyclades-app-queues.conf``:
1487

    
1488
.. code-block:: console
1489

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

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

    
1496
Edit ``/etc/synnefo/20-snf-cyclades-app-ui.conf``:
1497

    
1498
.. code-block:: console
1499

    
1500
   UI_LOGIN_URL = "https://node1.example.com/im/login"
1501
   UI_LOGOUT_URL = "https://node1.example.com/im/logout"
1502

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

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

    
1509
Edit ``/etc/default/vncauthproxy``:
1510

    
1511
.. code-block:: console
1512

    
1513
   CHUID="www-data:nogroup"
1514

    
1515
We have now finished with the basic Cyclades and Plankton configuration.
1516

    
1517
Database Initialization
1518
-----------------------
1519

    
1520
Once Cyclades is configured, we sync the database:
1521

    
1522
.. code-block:: console
1523

    
1524
   $ snf-manage syncdb
1525
   $ snf-manage migrate
1526

    
1527
and load the initial server flavors:
1528

    
1529
.. code-block:: console
1530

    
1531
   $ snf-manage loaddata flavors
1532

    
1533
If everything returns successfully, our database is ready.
1534

    
1535
Add the Ganeti backend
1536
----------------------
1537

    
1538
In our installation we assume that we only have one Ganeti cluster. Cyclades can
1539
manage multiple Ganeti backends, but for the purpose of this guide, we won't get
1540
into more detail regarding mulitple backends.
1541

    
1542
By default, when you install Cyclades, it sets up a dummy first backend. You can
1543
see it by running:
1544

    
1545
.. code-block:: console
1546

    
1547
   $ snf-manage backend-list
1548

    
1549
We modify this backend to reflect our already setup Ganeti cluster:
1550

    
1551
.. code-block:: console
1552

    
1553
   $ snf-manage backend-modify --clustername "ganeti.node1.example.com"
1554
                               --username=cyclades
1555
                               --password=example_rapi_passw0rd
1556
                               1
1557

    
1558
``clustername`` denotes the Ganeti-cluster's name. We provide the corresponding
1559
domain that resolves to the master IP, than the IP itself, to ensure Cyclades
1560
can talk to Ganeti even after a Ganeti master-failover.
1561

    
1562
``username`` and ``password`` denote the RAPI user's username and the RAPI
1563
user's password. We set the above to reflect our :ref:`RAPI User setup
1564
<rapi-user>`. The port is already set to the default RAPI port; you need to
1565
change it, only if you have changed it in your Ganeti cluster setup.
1566

    
1567
Once we setup the first backend to point at our Ganeti cluster, we update the
1568
Cyclades backends status by running:
1569

    
1570
.. code-block:: console
1571

    
1572
   $ snf-manage backend-update-status
1573

    
1574
Add the Public Network
1575
----------------------
1576

    
1577
After connecting Cyclades with our Ganeti cluster, we need to setup the Public
1578
Network:
1579

    
1580
.. code-block:: console
1581

    
1582
   $ snf-manage network-create --subnet=5.6.7.0/27
1583
                               --gateway=5.6.7.1
1584
                               --subnet6=2001:648:2FFC:1322::/64
1585
                               --gateway6=2001:648:2FFC:1322::1
1586
                               --public --dhcp --type=PUBLIC_ROUTED
1587
                               --name=public_network
1588

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

    
1592
.. code-block:: console
1593

    
1594
   $ snf-manage reconcile-networks
1595
   $ snf-manage reconcile-pools
1596

    
1597
You can see all available networks by running:
1598

    
1599
.. code-block:: console
1600

    
1601
   $ snf-manage listnetworks
1602

    
1603
and inspect each network's state by running:
1604

    
1605
.. code-block:: console
1606

    
1607
   $ snf-manage network-inspect <net_id>
1608

    
1609
Finally, you can see the networks from the Ganeti perspective by running on the
1610
Ganeti MASTER:
1611

    
1612
.. code-block:: console
1613

    
1614
   $ gnt-network list
1615
   $ gnt-network info <network_name>
1616

    
1617
Servers restart
1618
---------------
1619

    
1620
Restart gunicorn on node1:
1621

    
1622
.. code-block:: console
1623

    
1624
   # /etc/init.d/gunicorn restart
1625

    
1626
Now let's do the final connections of Cyclades with Ganeti.
1627

    
1628
``snf-dispatcher`` initialization
1629
---------------------------------
1630

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

    
1636
.. code-block:: console
1637

    
1638
   SNF_DSPTCH_ENABLE=true
1639

    
1640
and start the daemon:
1641

    
1642
.. code-block:: console
1643

    
1644
   # /etc/init.d/snf-dispatcher start
1645

    
1646
You can see that everything works correctly by tailing its log file
1647
``/var/log/synnefo/dispatcher.log``.
1648

    
1649
``snf-ganeti-eventd`` on GANETI MASTER
1650
--------------------------------------
1651

    
1652
The last step of the Cyclades setup is enabling the ``snf-ganeti-eventd``
1653
daemon (part of the :ref:`Cyclades Ganeti tools <cyclades-gtools>` package).
1654
The daemon is already installed on the GANETI MASTER (node1 in our case).
1655
``snf-ganeti-eventd`` is disabled by default during the ``snf-cyclades-gtools``
1656
installation, so we enable it in its configuration file
1657
``/etc/default/snf-ganeti-eventd``:
1658

    
1659
.. code-block:: console
1660

    
1661
   SNF_EVENTD_ENABLE=true
1662

    
1663
and start the daemon:
1664

    
1665
.. code-block:: console
1666

    
1667
   # /etc/init.d/snf-ganeti-eventd start
1668

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

    
1671
If all the above return successfully, then you have finished with the Cyclades
1672
and Plankton installation and setup. Let's test our installation now.
1673

    
1674

    
1675
Testing of Cyclades (and Plankton)
1676
==================================
1677

    
1678
Cyclades Web UI
1679
---------------
1680

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

    
1685
 `http://node1.example.com/ui/`
1686

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

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

    
1697
Cyclades Images
1698
---------------
1699

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

    
1705
 * Upload an Image file to Pithos+
1706
 * Register that Image file to Plankton
1707
 * Spawn a new VM from that Image from the Cyclades Web UI
1708

    
1709
We will use the `kamaki <http://docs.dev.grnet.gr/kamaki/latest/index.html>`_
1710
command line client to do the uploading and registering of the Image.
1711

    
1712
Installation of `kamaki`
1713
~~~~~~~~~~~~~~~~~~~~~~~~
1714

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

    
1722
.. code-block:: console
1723

    
1724
   # apt-get install kamaki
1725

    
1726
Configuration of kamaki
1727
~~~~~~~~~~~~~~~~~~~~~~~
1728

    
1729
Now we need to setup kamaki, by adding the appropriate URLs and tokens of our
1730
installation. We do this by running:
1731

    
1732
.. code-block:: console
1733

    
1734
   $ kamaki config set astakos.url "https://node1.example.com"
1735
   $ kamaki config set compute.url="https://node1.example.com/api/v1.1"
1736
   $ kamaki config set image.url "https://node1.examle.com/plankton"
1737
   $ kamaki config set storage.url "https://node2.example.com/v1"
1738
   $ kamaki config set storage.account "user@example.com"
1739
   $ kamaki config set global.token "bdY_example_user_tokenYUff=="
1740

    
1741
The token at the last kamaki command is our user's (``user@example.com``) token,
1742
as it appears on the user's `Profile` web page on the Astakos Web UI.
1743

    
1744
You can see that the new configuration options have been applied correctly, by
1745
running:
1746

    
1747
.. code-block:: console
1748

    
1749
   $ kamaki config list
1750

    
1751
Upload an Image file to Pithos+
1752
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1753

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

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

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

    
1766
We create the new ``images`` container by running:
1767

    
1768
.. code-block:: console
1769

    
1770
   $ kamaki store create images
1771

    
1772
Then, we upload the Image file to that container:
1773

    
1774
.. code-block:: console
1775

    
1776
   $ kamaki store upload --container images \
1777
                         /srv/images/debian_base-6.0-7-x86_64.diskdump \
1778
                         debian_base-6.0-7-x86_64.diskdump
1779

    
1780
The first is the local path and the second is the remote path on Pithos+. If
1781
the new container and the file appears on the Pithos+ Web UI, then you have
1782
successfully created the container and uploaded the Image file.
1783

    
1784
Register an existing Image file to Plankton
1785
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1786

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

    
1790
.. code-block:: console
1791

    
1792
   $ kamaki image register "Debian Base"
1793
                           pithos://user@examle.com/images/debian_base-6.0-7-x86_64.diskdump
1794
                           --public
1795
                           --disk-format=diskdump
1796
                           --property OSFAMILY=linux --property ROOT_PARTITION=1
1797
                           --property description="Debian Squeeze Base System"
1798
                           --property size=451 --property kernel=2.6.32 --property GUI="No GUI"
1799
                           --property sortorder=1 --property USERS=root --property OS=debian
1800

    
1801
This command registers the Pithos+ file
1802
``pithos://user@examle.com/images/debian_base-6.0-7-x86_64.diskdump`` as an
1803
Image in Plankton. This Image will be public (``--public``), so all users will
1804
be able to spawn VMs from it and is of type ``diskdump``. The first two
1805
properties (``OSFAMILY`` and ``ROOT_PARTITION``) are mandatory. All the rest
1806
properties are optional, but recommended, so that the Images appear nicely on
1807
the Cyclades Web UI. ``Debian Base`` will appear as the name of this Image. The
1808
``OS`` property's valid values may be found in the ``IMAGE_ICONS`` variable
1809
inside the ``20-snf-cyclades-app-ui.conf`` configuration file.
1810

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

    
1816
Spawn a VM from the Cyclades Web UI
1817
-----------------------------------
1818

    
1819
If the registration completes successfully, then go to the Cyclades Web UI from
1820
your browser at:
1821

    
1822
 `https://node1.example.com/ui/`
1823

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

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

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

    
1840
Congratulations. You have successfully installed the whole Synnefo stack and
1841
connected all components. Go ahead in the next section to test the Network
1842
functionality from inside Cyclades and discover even more features.
1843

    
1844

    
1845
General Testing
1846
===============
1847

    
1848

    
1849
Notes
1850
=====