admin-guide.rst 64 KB
Newer Older
1
2
3
4
5
6
7
8
9
.. _admin-guide:

Synnefo Administrator's Guide
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is the complete Synnefo Administrator's Guide.



10
11
12
13
14
15
General Synnefo Architecture
============================

The following graph shows the whole Synnefo architecture and how it interacts
with multiple Ganeti clusters. We hope that after reading the Administrator's
Guide you will be able to understand every component and all the interactions
16
17
between them. It is a good idea to first go through the Administrator's Guide
before proceeding.
18

19
.. image:: images/synnefo-arch2.png
20
   :width: 100%
21
   :target: _images/synnefo-arch2.png
22
23


24

25
26
Identity Service (Astakos)
==========================
27
28


29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
Overview
--------

Authentication methods
~~~~~~~~~~~~~~~~~~~~~~

Local Authentication
````````````````````

LDAP Authentication
```````````````````

.. _shibboleth-auth:

Shibboleth Authentication
`````````````````````````

Astakos can delegate user authentication to a Shibboleth federation.

To setup shibboleth, install package::

  apt-get install libapache2-mod-shib2

Change appropriately the configuration files in ``/etc/shibboleth``.

Add in ``/etc/apache2/sites-available/synnefo-ssl``::

  ShibConfig /etc/shibboleth/shibboleth2.xml
  Alias      /shibboleth-sp /usr/share/shibboleth

59
  <Location /ui/login/shibboleth>
60
61
62
63
64
65
66
67
68
69
70
71
72
    AuthType shibboleth
    ShibRequireSession On
    ShibUseHeaders On
    require valid-user
  </Location>

and before the line containing::

  ProxyPass        / http://localhost:8080/ retry=0

add::

  ProxyPass /Shibboleth.sso !
73

74
75
76
Then, enable the shibboleth module::

  a2enmod shib2
77

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
After passing through the apache module, the following tokens should be
available at the destination::

  eppn # eduPersonPrincipalName
  Shib-InetOrgPerson-givenName
  Shib-Person-surname
  Shib-Person-commonName
  Shib-InetOrgPerson-displayName
  Shib-EP-Affiliation
  Shib-Session-ID

Finally, add 'shibboleth' in ``ASTAKOS_IM_MODULES`` list. The variable resides
inside the file ``/etc/synnefo/20-snf-astakos-app-settings.conf``

Architecture
------------

Prereqs
-------

Installation
------------

Configuration
-------------

Working with Astakos
--------------------

107
108
User registration
~~~~~~~~~~~~~~~~~
109

110
111
When a new user signs up, he/she is not directly marked as active. You can see 
his/her state by running (on the machine that runs the Astakos app):
112
113
114

.. code-block:: console

115
   $ snf-manage user-list
116

117
118
More detailed user status is provided in the `status` field of the `user-show` 
command:
119

120
.. code-block:: console
121

122
  $ snf-manage user-show <user-id>
123

124
125
126
127
128
  id                  : 6
  uuid                : 78661411-5eed-412f-a9ea-2de24f542c2e
  status              : Accepted/Active (accepted policy: manual)
  email               : user@synnefo.org
  ....
129
130


131
132
133
Based on how your configuration of `astakos-app`, there are several ways for a 
user to get activated and be able to login. We discuss the user activation 
flow in the following section.
134

135
136

User activation flow
137
138
````````````````````

139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
A user can register for an account using the astakos signup form. Once the form
is submited successfully a user entry is created in astakos database. That entry
is passed through the astakos activation backend which handles whether the user
should be automatically verified and activated.


Email verification
``````````````````

The verification process takes place in order to ensure that the user owns the
email provided during the signup process. By default, after each successful
signup astakos notifies user with an verification url via email. 

At this stage:

    * subsequent registrations invalidate and delete the previous registrations 
      of the same email address.

    * in case user misses the initial notification, additional emails can be
      send either via the url which is prompted to the user if he tries to
      login, or by the administrator using the ``snf-manage user-activation-send
      <userid>`` command.

    * administrator may also enforce a user to get verified using the
      ``snf-manage user-modify --verify <userid>`` command.


Account activation
``````````````````

Once user gets verified it is time for astakos to decide whether or not to
proceed through user activation process. If ``ASTAKOS_MODERATION_ENABLED``
setting is set to ``False`` (default value) user gets activated automatically. 

In case the moderation is enabled astakos may still automatically activate the
user in the following cases:

    * User email matches any of the regular expressions defined in
      ``ASTAKOS_RE_USER_EMAIL_PATTERNS`` (defaults to ``[]``)
    * User used a signup method (e.g. ``shibboleth``) for which automatic
      activation is enabled (see 
      :ref:`authentication methods policies <auth_methods_policies>`).

If all of the above fail to trigger automatic activation, an email is sent 
to the persons listed in ``HELPDESK``, ``MANAGERS`` and ``ADMINS`` settings, 
notifing that there is a new user pending for moderation and that it's 
up to the administrator to decide if the user should be activated, using the 
``user-modify`` command.

.. code-block:: console

    # command to activate a pending user
    $ snf-manage user-modify --accept <userid>

    # command to reject a pending user
    $ snf-manage user-modify --reject --reject-reason="spammer" <userid>

Once activation process finish, a greeting message is sent to the user email
address and a notification for the activation to the persons listed in 
``HELPDESK``, ``MANAGERS`` and ``ADMINS`` settings. Once activated the user is 
able to login and access the synnefo services.


Additional authentication methods
`````````````````````````````````

Astakos supports third party logins from external identity providers. This
can be usefull since it allows users to use their existing credentials to 
login to astakos service.

Currently astakos supports the following identity providers:

    * `Shibboleth <http://www.internet2.edu/shibboleth>`_ (module name
      ``shibboleth``)
    * `Google <https://developers.google.com/accounts/docs/OAuth2>`_ (module
      name ``google``)
    * `Twitter <https://dev.twitter.com/docs/auth>`_ (module name ``twitter``)
    * `LinkedIn <http://developer.linkedin.com/documents/authentication>`_
      (module name ``linkedin``)

To enable any of the above modules (by default only ``local`` accounts are
allowed), retrieve and set the required provider settings and append the 
module name in ``ASTAKOS_IM_MODULES``.

.. code-block:: python

    # settings from https://code.google.com/apis/console/
    ASTAKOS_GOOGLE_CLIENT_ID = '1111111111-epi60tvimgha63qqnjo40cljkojcann3.apps.googleusercontent.com'
    ASTAKOS_GOOGLE_SECRET = 'tNDQqTDKlTf7_LaeUcWTWwZM'
    
    # let users signup and login using their google account
    ASTAKOS_IM_MODULES = ['local', 'google']


.. _auth_methods_policies:

Authentication method policies
``````````````````````````````

Astakos allows you to override the default policies for each enabled provider 
separately by adding the approriate settings in your ``.conf`` files in the 
following format:

**ASTAKOS_AUTH_PROVIDER_<module>_<policy>_POLICY**

Available policies are:

    * **CREATE** Users can signup using that provider (default: ``True``) 
    * **REMOVE/ADD** Users can remove/add login method from their profile 
      (default: ``True``)
    * **AUTOMODERATE** Automatically activate users that signup using that
      provider (default: ``False``)
    * **LOGIN** Whether or not users can use the provider to login (default:
      ``True``).

e.g. to enable automatic activation for your academic users, while keeping 
locally signed up users under moderation you can apply the following settings.

.. code-block:: python

    ASTAKOS_AUTH_PROVIDER_SHIBBOLETH_AUTOMODERATE_POLICY = True
    ASTAKOS_AUTH_PROVIDER_SHIBBOLETH_REMOVE_POLICY = False

262

263
264
265
Setting quota limits
~~~~~~~~~~~~~~~~~~~~

266
267
Set default quota
`````````````````
268
269
270
271

In 20-snf-astakos-app-settings.conf, 
uncomment the default setting ``ASTAKOS_SERVICES``
and customize the ``'uplimit'`` values.
272
These are the default base quota for all users.
273
274
275
276

To apply your configuration run::

    # snf-manage astakos-init --load-service-resources
277
    # snf-manage quota --sync
278

279
280
Set base quota for individual users
```````````````````````````````````
281

282
For individual users that need different quota than the default
283
284
you can set it for each resource like this::

285
286
    # use this to display quota / uuid
    # snf-manage user-show 'uuid or email' --quota
287

288
    # snf-manage user-modify 'user-uuid' --set-base-quota 'cyclades.vm' 10
289
290
291
292
293
294
295
296
297
298
299
300


Enable the Projects feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to enable the projects feature so that users may apply
on their own for resources by creating and joining projects,
in ``20-snf-astakos-app-settings.conf`` set::

    # this will make the 'projects' page visible in the dashboard
    ASTAKOS_PROJECTS_VISIBLE = True

301
302
You can change the maximum allowed number of pending project applications
per user with::
303

304
305
306
307
    # snf-manage resource-modify astakos.pending_app --limit <number>

You can also set a user-specific limit with::

308
    # snf-manage user-modify 'user-uuid' --set-base-quota 'astakos.pending_app' 5
309

310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
When users apply for projects they are not automatically granted
the resources. They must first be approved by the administrator.

To list pending project applications in astakos::

    # snf-manage project-list --pending

Note the last column, the application id. To approve it::

    # <app id> from the last column of project-list
    # snf-manage project-control --approve <app id>

To deny an application::

    # snf-manage project-control --deny <app id>

326
327
328
329
330
331
Users designated as *project admins* can approve, deny, or modify
an application through the web interface. In
``20-snf-astakos-app-settings.conf`` set::

    # UUIDs of users that can approve or deny project applications from the web.
    ASTAKOS_PROJECT_ADMINS = [<uuid>, ...]
332
333


334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
Astakos advanced operations
---------------------------

Adding "Terms of Use"
~~~~~~~~~~~~~~~~~~~~~

Astakos supports versioned terms-of-use. First of all you need to create an
html file that will contain your terms. For example, create the file
``/usr/share/synnefo/sample-terms.html``, which contains the following:

.. code-block:: console

   <h1>~okeanos terms</h1>

   These are the example terms for ~okeanos

Then, add those terms-of-use with the snf-manage command:

.. code-block:: console

   $ snf-manage term-add /usr/share/synnefo/sample-terms.html

Your terms have been successfully added and you will see the corresponding link
appearing in the Astakos web pages' footer.

359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
Enabling reCAPTCHA
~~~~~~~~~~~~~~~~~~

Astakos supports the `reCAPTCHA <http://www.google.com/recaptcha>`_ feature.
If enabled, it protects the Astakos forms from bots. To enable the feature, go
to https://www.google.com/recaptcha/admin/create and create your own reCAPTCHA
key pair. Then edit ``/etc/synnefo/20-snf-astakos-app-settings.conf`` and set
the corresponding variables to reflect your newly created key pair. Finally, set
the ``ASTAKOS_RECAPTCHA_ENABLED`` variable to ``True``:

.. code-block:: console

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

   ASTAKOS_RECAPTCHA_ENABLED = True

Restart the service on the Astakos node(s) and you are ready:

.. code-block:: console

   # /etc/init.d/gunicorn restart

Checkout your new Sign up page. If you see the reCAPTCHA box, you have setup
everything correctly.

385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427


File Storage Service (Pithos)
=============================

Overview
--------

Architecture
------------

Prereqs
-------

Installation
------------

Configuration
-------------

Working with Pithos
-------------------

Pithos advanced operations
--------------------------



Compute/Network/Image Service (Cyclades)
========================================

Compute Overview
----------------

Network Overview
----------------

Image Overview
--------------

Architecture
------------

428
Asynchronous communication with Ganeti backends
Christos Stavrakakis's avatar
Christos Stavrakakis committed
429
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430
431
432
433
434
435
436
Synnefo uses Google Ganeti backends for VM cluster management. In order for
Cyclades to be able to handle thousands of user requests, Cyclades and Ganeti
communicate asynchronously. Briefly, requests are submitted to Ganeti through
Ganeti's RAPI/HTTP interface, and then asynchronous notifications about the
progress of Ganeti jobs are being created and pushed upwards to Cyclades. The
architecture and communication with a Ganeti backend is shown in the graph
below:
437
438
439
440

.. image:: images/cyclades-ganeti-communication.png
   :width: 50%
   :target: _images/cyclades-ganeti-communication.png
441

442
The Cyclades API server is responsible for handling user requests. Read-only
443
444
requests are directly served by looking up the Cyclades DB. If the request
needs an action in the Ganeti backend, Cyclades submit jobs to the Ganeti
445
446
master using the `Ganeti RAPI interface
<http://docs.ganeti.org/ganeti/2.2/html/rapi.html>`_.
447

448
449
While Ganeti executes the job, `snf-ganeti-eventd`, `snf-ganeti-hook` and
`snf-progress-monitor` are monitoring the progress of the job and send
450
corresponding messages to the RabbitMQ servers. These components are part
451
of `snf-cyclades-gtools` and must be installed on all Ganeti nodes. Specially:
452
453

* *snf-ganeti-eventd* sends messages about operations affecting the operating
454
455
  state of instances and networks. Works by monitoring the Ganeti job queue.
* *snf-ganeti_hook* sends messages about the NICs of instances. It includes a
Christos Stavrakakis's avatar
Christos Stavrakakis committed
456
457
  number of `Ganeti hooks <http://docs.ganeti.org/ganeti/2.2/html/hooks.html>`_
  for customisation of operations.
458
459
* *snf-progress_monitor* sends messages about the progress of the Image deployment
  phase which is done by the Ganeti OS Definition `snf-image`.
460

461
462
463
Finally, `snf-dispatcher` consumes messages from the RabbitMQ queues, processes
these messages and properly updates the state of the Cyclades DB. Subsequent
requests to the Cyclades API, will retrieve the updated state from the DB.
464
465


466
467
468
Prereqs
-------

469
Work in progress. Please refer to :ref:`administrator's install quide <quick-install-admin-guide>`.
470

471
472
473
Installation
------------

474
Work in progress. Please refer to :ref:`administrator's install quide <quick-install-admin-guide>`.
475

476
477
478
Configuration
-------------

479
Work in progress. Please refer to :ref:`administrator's install quide <quick-install-admin-guide>`.
480

481
482
483
Working with Cyclades
---------------------

484
Managing Ganeti Backends
Christos Stavrakakis's avatar
Christos Stavrakakis committed
485
~~~~~~~~~~~~~~~~~~~~~~~~
486

487
488
489
Since v0.11, Synnefo is able to manage multiple Ganeti clusters (backends)
making it capable to scale linearly to tens of thousands of VMs. Backends
can be dynamically added or removed via `snf-manage` commands.
490

491
492
493
494
495
Each newly created VM is allocated to a Ganeti backend by the Cyclades backend
allocator. The VM is "pinned" to this backend, and can not change through its
lifetime. The backend allocator decides in which backend to spawn the VM based
on the available resources of each backend, trying to balance the load between
them.
496
497

Handling of Networks, as far as backends are concerned, is based on whether the
498
499
500
501
network is public or not. Public networks are created through the `snf-manage
network-create` command, and are only created on one backend. Private networks
are created on all backends, in order to ensure that VMs residing on different
backends can be connected to the same private network.
502

503
504
505
Listing existing backends
`````````````````````````
To list all the Ganeti backends known to Synnefo, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
506

507
508
509
510
511
.. code-block:: console

   $ snf-manage backend-list

Adding a new Ganeti backend
Christos Stavrakakis's avatar
Christos Stavrakakis committed
512
```````````````````````````
513
514
Backends are dynamically added under the control of Synnefo with `snf-manage
backend-add` command. In this section it is assumed that a Ganeti cluster,
515
516
named ``cluster.example.com`` is already up and running and configured to be
able to host Synnefo VMs.
517

518
To add this Ganeti cluster, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
519

520
521
522
523
.. code-block:: console

   $ snf-manage backend-add --clustername=cluster.example.com --user="synnefo_user" --pass="synnefo_pass"

524
525
526
527
528
where ``clustername`` is the Cluster hostname of the Ganeti cluster, and
``user`` and ``pass`` are the credentials for the `Ganeti RAPI user
<http://docs.ganeti.org/ganeti/2.2/html/rapi.html#users-and-passwords>`_.  All
backend attributes can be also changed dynamically using the `snf-manage
backend-modify` command.
529

530
531
532
``snf-manage backend-add`` will also create all existing private networks to
the new backend. You can verify that the backend is added, by running
`snf-manage backend-list`.
533

534
535
536
537
538
539
540
541
542
543
Note that no VMs will be spawned to this backend, since by default it is in a
``drained`` state after addition and also it has no public network assigned to
it.

So, first you need to create its public network, make sure everything works as
expected and finally make it active by un-setting the ``drained`` flag. You can
do this by running:

.. code-block:: console

544
   $ snf-manage backend-modify --drained=False <backend_id>
545
546

Removing an existing Ganeti backend
Christos Stavrakakis's avatar
Christos Stavrakakis committed
547
```````````````````````````````````
548
In order to remove an existing backend from Synnefo, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
549

550
551
.. code-block:: console

552
   # snf-manage backend-remove <backend_id>
553

554
555
556
This command will fail if there are active VMs on the backend. Also, the
backend is not cleaned before removal, so all the Synnefo private networks
will be left on the Ganeti nodes. You need to remove them manually.
557

558
559
560
561
562
563
Allocation of VMs in Ganeti backends
````````````````````````````````````
As already mentioned, the Cyclades backend allocator is responsible for
allocating new VMs to backends. This allocator does not choose the exact Ganeti
node that will host the VM but just the Ganeti backend. The exact node is
chosen by the Ganeti cluster's allocator (hail).
564
565
566
567

The decision about which backend will host a VM is based on the available
resources. The allocator computes a score for each backend, that shows its load
factor, and the one with the minimum score is chosen. The admin can exclude
568
backends from the allocation phase by marking them as ``drained`` by running:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
569

570
571
.. code-block:: console

572
   $ snf-manage backend-modify --drained=True <backend_id>
573
574

The backend resources are periodically updated, at a period defined by
575
the ``BACKEND_REFRESH_MIN`` setting, or by running `snf-manage backend-update-status`
576
command. It is advised to have a cron job running this command at a smaller
577
interval than ``BACKEND_REFRESH_MIN`` in order to remove the load of refreshing
578
579
the backends stats from the VM creation phase.

580
581
582
Finally, the admin can decide to have a user's VMs being allocated to a
specific backend, with the ``BACKEND_PER_USER`` setting. This is a mapping
between users and backends. If the user is found in ``BACKEND_PER_USER``, then
583
584
Synnefo allocates all his/hers VMs to the specific backend in the variable,
even if is marked as drained (useful for testing).
585

586
587
588
589

Managing Virtual Machines
~~~~~~~~~~~~~~~~~~~~~~~~~

590
591
592
593
594
595
As mentioned, Cyclades uses Ganeti for management of VMs. The administrator can
handle Cyclades VMs just like any other Ganeti instance, via `gnt-instance`
commands. All Ganeti instances that belong to Synnefo, are separated from
others, by a prefix in their names. This prefix is defined in
``BACKEND_PREFIX_ID`` setting in
``/etc/synnefo/20-snf-cyclades-app-backend.conf``.
596

597
Apart from handling instances directly in the Ganeti level, a number of `snf-manage`
598
599
commands are available:

600
601
602
603
604
605
* ``snf-manage server-list``: List servers
* ``snf-manage server-show``: Show information about a server in the Cyclades DB
* ``snf-manage server-inspect``: Inspect the state of a server both in DB and Ganeti
* ``snf-manage server-modify``: Modify the state of a server in the Cycldes DB
* ``snf-manage server-create``: Create a new server
* ``snf-manage server-import``: Import an existing Ganeti instance to Cyclades
606
607
608
609
610


Managing Virtual Networks
~~~~~~~~~~~~~~~~~~~~~~~~~

611
612
613
614
Cyclades is able to create and manage Virtual Networks. Networking is
desployment specific and must be customized based on the specific needs of the
system administrator. For better understanding of networking please refer to
the :ref:`Network <networks>` section.
615
616
617

Exactly as Cyclades VMs can be handled like Ganeti instances, Cyclades Networks
can also by handled as Ganeti networks, via `gnt-network commands`. All Ganeti
618
networks that belong to Synnefo are named with the prefix
619
620
`${BACKEND_PREFIX_ID}-net-`.

621
There are also the following `snf-manage` commands for managing networks:
622

623
624
625
626
627
628
* ``snf-manage network-list``: List networks
* ``snf-manage network-show``: Show information about a network in the Cyclades DB
* ``snf-manage network-inspect``: Inspect the state of the network in DB and Ganeti backends
* ``snf-manage network-modify``: Modify the state of a network in the Cycldes DB
* ``snf-manage network-create``: Create a new network
* ``snf-manage network-remove``: Remove an existing network
629

630
Managing Network Resources
631
``````````````````````````
632

633
634
635
Proper operation of the Cyclades Network Service depends on the unique
assignment of specific resources to each type of virtual network. Specifically,
these resources are:
636

637
638
639
640
641
* IP addresses. Cyclades creates a Pool of IPs for each Network, and assigns a
  unique IP address to each VM, thus connecting it to this Network. You can see
  the IP pool of each network by running `snf-manage network-inspect
  <network_ID>`. IP pools are automatically created and managed by Cyclades,
  depending on the subnet of the Network.
642
* Bridges corresponding to physical VLANs, which are required for networks of
643
644
645
  type `PRIVATE_PHYSICAL_VLAN`.
* One Bridge corresponding to one physical VLAN which is required for networks of
  type `PRIVATE_MAC_PREFIX`.
646

647
648
Cyclades allocates those resources from pools that are created by the
administrator with the `snf-manage pool-create` management command.
649

650
651
652
Pool Creation
`````````````
Pools are created using the `snf-manage pool-create` command:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
653

654
655
656
657
658
659
660
.. code-block:: console

   # snf-manage pool-create --type=bridge --base=prv --size=20

will create a pool of bridges, containing bridges prv1, prv2,..prv21.

You can verify the creation of the pool, and check its contents by running:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
661

662
663
664
665
666
.. code-block:: console

   # snf-manage pool-list
   # snf-manage pool-show --type=bridge 1

667
With the same commands you can handle a pool of MAC prefixes. For example:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
668

669
670
671
672
.. code-block:: console

   # snf-manage pool-create --type=mac-prefix --base=aa:00:0 --size=65536

673
674
675
676
will create a pool of MAC prefixes from ``aa:00:1`` to ``b9:ff:f``. The MAC
prefix pool is responsible for providing only unicast and locally administered
MAC addresses, so many of these prefixes will be externally reserved, to
exclude from allocation.
677

678
679
680
681
682
Cyclades advanced operations
----------------------------

Reconciliation mechanism
~~~~~~~~~~~~~~~~~~~~~~~~
683

684
685
686
687
688
689
On certain occasions, such as a Ganeti or RabbitMQ failure, the state of
Cyclades database may differ from the real state of VMs and networks in the
Ganeti backends. The reconciliation process is designed to synchronize
the state of the Cyclades DB with Ganeti. There are two management commands
for reconciling VMs and Networks

690
691
692
Reconciling Virtual Machines
````````````````````````````

693
Reconciliation of VMs detects the following conditions:
694

695
696
 * Stale DB servers without corresponding Ganeti instances
 * Orphan Ganeti instances, without corresponding DB entries
697
 * Out-of-sync state for DB entries wrt to Ganeti instances
698

699
To detect all inconsistencies you can just run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
700

701
.. code-block:: console
702
703

  $ snf-manage reconcile-servers
704

705
Adding the `--fix-all` option, will do the actual synchronization:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
706

707
.. code-block:: console
708
709

  $ snf-manage reconcile --fix-all
710
711
712
713

Please see ``snf-manage reconcile --help`` for all the details.


714
Reconciling Networks
Christos Stavrakakis's avatar
Christos Stavrakakis committed
715
````````````````````
716

717
Reconciliation of Networks detects the following conditions:
718

719
720
721
722
723
724
  * Stale DB networks without corresponding Ganeti networks
  * Orphan Ganeti networks, without corresponding DB entries
  * Private networks that are not created to all Ganeti backends
  * Unsynchronized IP pools

To detect all inconsistencies you can just run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
725

726
.. code-block:: console
727

728
729
730
  $ snf-manage reconcile-networks

Adding the `--fix-all` option, will do the actual synchronization:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
731

732
.. code-block:: console
733

734
735
736
  $ snf-manage reconcile-networks --fix-all

Please see ``snf-manage reconcile-networks --help`` for all the details.
737
738


739

740
741
742
743
744
Block Storage Service (Archipelago)
===================================

Overview
--------
745
746
747
748
749
750
Archipelago offers Copy-On-Write snapshotable volumes. Pithos images can be used
to provision a volume with Copy-On-Write semantics (i.e. a clone). Snapshots
offer a unique deduplicated image of a volume, that reflects the volume state
during snapshot creation and are indistinguishable from a Pithos image.

Archipelago is used by Cyclades and Ganeti for fast provisioning of VMs based on
751
752
CoW volumes. Moreover, it enables live migration of thinly-provisioned VMs with
no physically shared storage.
753

754
755
756
Archipelago Architecture
------------------------

757
758
759
.. image:: images/archipelago-architecture.png
   :width: 50%
   :target: _images/archipelago-architecture.png
760

761
762
763
764
765
766
767
768
769
.. _syn+archip+rados:

Overview of Synnefo + Archipelago + RADOS
-----------------------------------------

.. image:: images/synnefo-arch3.png
   :width: 100%
   :target: _images/synnefo-arch3.png

770
771
Prereqs
-------
772

773
774
775
776
777
778
779
780
781
782
783
784
785
The administrator must initialize the storage backend where archipelago volume
blocks will reside.

In case of a files backend, the administrator must create two directories. One
for the archipelago data blocks and one for the archipelago map blocks. These
should probably be over shared storage to enable sharing archipelago volumes
between multiple nodes. He or she, must also be able to supply a directory where
the pithos data and map blocks reside.

In case of a RADOS backend, the administrator must create two rados pools, one
for data blocks, and one for the map blocks. These pools, must be the same pools
used in pithos, in order to enable volume creation based on pithos images.

786
787
Installation
------------
788

789
790
791
Archipelago consists of

* ``libxseg0``: libxseg used to communicate over shared memory segments
792
* ``python-xseg``: python bindings for libxseg
793
794
* ``archipelago-kernel-dkms``: contains archipelago kernel modules to provide
  block devices to be used as vm disks
795
796
* ``python-archipelago``: archipelago python module. Includes archipelago and
  vlmc functionality.
797
798
799
800
801
802
803
804
805
806
807
808
809
810
* ``archipelago``: user space tools and peers for the archipelago management and
  volume composition
* ``archipelago-ganeti``: ganeti ext storage scripts, that enable ganeti to
  provision VMs over archipelago

Performing

.. code-block:: console

  $ apt-get install archipelago-ganeti 

should fetch all the required packages and get you up 'n going with archipelago

Bare in mind, that custom librados is required, which is provided in the apt
811
repo of GRNet.
812
813


814
815
For now, librados is a dependency of archipelago, even if you do not intend to
use archipelago over RADOS.
816
817
818

Configuration
-------------
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
Archipelago should work out of the box with a RADOS backend, but basic
configuration can be done in ``/etc/default/archipelago`` .

If you wish to change the storage backend to files, set

.. code-block:: console

   STORAGE="files"

and provide the appropriate settings for files storage backend in the conf file.

These are:

* ``FILED_IMAGES``: directory for archipelago data blocks.
* ``FILED_MAPS``: directory for archipelago map blocks.
* ``PITHOS``: directory of pithos data blocks.
* ``PITHOSMAPS``: directory of pithos map blocks.

The settings for RADOS storage backend are:

* ``RADOS_POOL_MAPS``: The pool where archipelago and pithos map blocks reside.
* ``RADOS_POOL_BLOCKS``: The pool where archipelago and pithos data blocks
841
  reside.
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865

Examples can be found in the conf file.

Be aware that archipelago infrastructure doesn't provide default values for this
settings. If they are not set in the conf file, archipelago will not be able to
function.

Archipelago also provides ``VERBOSITY`` config options to control the output
generated by the userspace peers.

The available options are:

* ``VERBOSITY_BLOCKERB``
* ``VERBOSITY_BLOCKERM``
* ``VERBOSITY_MAPPER``
* ``VERBOSITY_VLMC``

and the available values are:

* 0 : Error only logging.
* 1 : Warning logging.
* 2 : Info logging.
* 3 : Debug logging. WARNING: This options produces tons of output, but the
  logrotate daemon should take care of it.
866
867
868
869

Working with Archipelago
------------------------

870
``archipelago`` provides basic functionality for archipelago.
871
872
873
874
875
876
877
878

Usage:

.. code-block:: console

  $ archipelago [-u] command


879
880
Currently it supports the following commands:

881
882
883
884
885
886
* ``start [peer]``
  Starts archipelago or the specified peer.
* ``stop [peer]``
  Stops archipelago or the specified peer.
* ``restart [peer]``
  Restarts archipelago or the specified peer.
887
* ``status``
888
889
890
891
  Show the status of archipelago.

Available peers: ``blockerm``, ``blockerb``, ``mapperd``, ``vlmcd``.

892
893
894
895
896
897

``start``, ``stop``, ``restart`` can be combined with the ``-u / --user`` option
to affect only the userspace peers supporting archipelago.



898
899
Archipelago advanced operations
-------------------------------
900
901
902
The ``vlmc`` tool provides a way to interact with archipelago volumes

* ``vlmc map <volumename>``: maps the volume to a xsegbd device.
903

904
* ``vlmc unmap </dev/xsegbd[1-..]>``: unmaps the specified device from the
905
  system.
906

907
908
* ``vlmc create <volumename> --snap <snapname> --size <size>``: creates a new
  volume named <volumename> from snapshot name <snapname> with size <size>.
909
910
  The ``--snap`` and ``--size`` are optional, but at least one of them is
  mandatory. e.g:
911

912
913
914
  ``vlmc create <volumename> --snap <snapname>`` creates a volume named
  volumename from snapshot snapname. The size of the volume is the same as
  the size of the snapshot.
915

916
917
  ``vlmc create <volumename> --size <size>`` creates an empty volume of size
  <size> named <volumename>.
918

919
920
* ``vlmc remove <volumename>``: removes the volume and all the related
  archipelago blocks from storage.
921

922
923
* ``vlmc list``: provides a list of archipelago volumes. Currently only works
  with RADOS storage backend.
924

925
926
927
* ``vlmc info <volumename>``: shows volume information. Currently returns only
  volume size.

928
929
930
931
932
933
934
935
936
937
938
939
940
941
* ``vlmc open <volumename>``: opens an archipelago volume. That is, taking all
  the necessary locks and also make the rest of the infrastructure aware of the
  operation.

  This operation succeeds if the volume is alread opened.

* ``vlmc close <volumename>``: closes an archipelago volume. That is, performing
  all the necessary functions in the insfrastrure to successfully release the
  volume. Also releases all the acquired locks.

  ``vlmc close`` should be performed after a ``vlmc open`` operation.

* ``vlmc lock <volumename>``: locks a volume. This step allow the administrator
  to lock an archipelago volume, independently from the rest of the
942
  infrastrure.
943
944
945
946
947
948
949
950

* ``vlmc unlock [-f] <volumename>``: unlocks a volume. This allow the
  administrator to unlock a volume, independently from the rest of the
  infrastructure.
  The unlock option can be performed only by the blocker that acquired the lock
  in the first place. To unlock a volume from another blocker, ``-f`` option
  must be used to break the lock.

951

952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
Synnefo management commands ("snf-manage")
==========================================

Each Synnefo service, Astakos, Pithos and Cyclades are controlled by the
administrator using the "snf-manage" admin tool. This tool is an extension of
the Django command-line management utility. It is run on the host that runs
each service and provides different types of commands depending the services
running on the host. If you are running more than one service on the same host
"snf-manage" adds all the corresponding commands for each service dynamically,
providing a unified admin environment.

To run "snf-manage" you just type:

.. code-block:: console

   # snf-manage <command> [arguments]

on the corresponding host that runs the service. For example, if you have all
services running on different physical hosts you would do:

.. code-block:: console

   root@astakos-host # snf-manage <astakos-command> [argument]
   root@pithos-host # snf-manage <pithos-command> [argument]
   root@cyclades-host # snf-manage <cyclades-command> [argument]

If you have all services running on the same host you would do:

.. code-block:: console

   root@synnefo-host # snf-manage <{astakos,pithos,cyclades}-command> [argument]

Note that you cannot execute a service's command on a host that is not running
this service. For example, the following will return an error if Astakos and
Cyclades are installed on different physical hosts:

.. code-block:: console

   root@astakos-host # snf-manage <cyclades-command> [argument]
   Unknown command: 'cyclades-command'
   Type 'snf-manage help' for usage.

This is the complete list of "snf-manage" commands for each service.

Astakos snf-manage commands
---------------------------

============================  ===========================
Name                          Description
============================  ===========================
fix-superusers                Transform superusers created by syncdb into AstakosUser instances
1003
cleanup-full                  Cleanup sessions and session catalog
1004
1005
commission-list               List pending commissions
commission-show               Show details for a pending commission
1006
1007
1008
component-add                 Register a component
component-list                List components
component-modify              Modify component attributes
1009
1010
1011
1012
1013
1014
project-control               Manage projects and applications
project-list                  List projects
project-show                  Show project details
quota                         List and check the integrity of user quota
reconcile-resources-astakos   Reconcile resource usage of Quotaholder with Astakos DB
resource-export-astakos       Export astakos resources in json format
1015
resource-import               Register resources
1016
resource-list                 List resources
1017
resource-modify               Modify a resource's default base quota and boolean flags
1018
service-import                Register services
1019
service-list                  List services
1020
service-show                  Show service details
1021
1022
1023
term-add                      Add approval terms
user-activation-send          Send user activation
user-add                      Add user
1024
1025
1026
1027
1028
1029
1030
authpolicy-add                Create a new authentication provider policy profile
authpolicy-list               List existing authentication provider policy profiles
authpolicy-remove             Remove an authentication provider policy
authpolicy-set                Assign an existing authentication provider policy profile to a user or group
authpolicy-show               Show authentication provider profile details
group-add                     Create a group with the given name
group-list                    List available groups
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
user-list                     List users
user-modify                   Modify user
user-show                     Show user details
============================  ===========================

Pithos snf-manage commands
--------------------------

============================  ===========================
Name                          Description
============================  ===========================
1042
1043
1044
reconcile-commissions-pithos  Display unresolved commissions and trigger their recovery
resource-export-pithos        Export pithos resources in json format
reconcile-resources-pithos    Detect unsynchronized usage between Astakos and Pithos DB resources and synchronize them if specified so.
1045
1046
1047
1048
1049
============================  ===========================

Cyclades snf-manage commands
----------------------------

1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
============================== ===========================
Name                           Description
============================== ===========================
backend-add                    Add a new Ganeti backend
backend-list                   List backends
backend-modify                 Modify a backend
backend-update-status          Update backend statistics for instance allocation
backend-remove                 Remove a Ganeti backend
server-create                  Create a new server
server-show                    Show server details
server-list                    List servers
server-modify                  Modify a server
server-import                  Import an existing Ganeti VM into synnefo
server-inspect                 Inspect a server in DB and Ganeti
network-create                 Create a new network
network-list                   List networks
network-modify                 Modify a network
network-inspect                Inspect network state in DB and Ganeti
network-remove                 Delete a network
flavor-create                  Create a new flavor
flavor-list                    List flavors
flavor-modify                  Modify a flavor
image-list                     List images
image-show                     Show image details
pool-create                    Create a bridge or mac-prefix pool
pool-show                      Show pool details
pool-list                      List pools
pool-modify                    Modify a pool
pool-remove                    Delete a pool
queue-inspect                  Inspect the messages of a RabbitMQ queue
queue-retry                    Resend messages from Dead Letter queues to original exchanges
resource-export-cyclades       Export Cyclades resources in JSON format.
service-export-cyclades        Export Cyclades services in JSON format.
reconcile-servers              Reconcile servers of Synnefo DB with state of Ganeti backend
reconcile-networks             Reconcile networks of Synnefo DB with state of Ganeti backend
reconcile-pools                Check consistency of pool resources
reconcile-commissions-cyclades Detect and resolve pending commissions to Quotaholder
reconcile-resources-cyclades   Reconcile resource usage of Astakos with Cyclades DB.
============================== ===========================
1089

1090
1091
1092
1093
1094
1095
1096
1097
Astakos helper scripts
======================

Astakos includes two scripts to facilitate the installation procedure.
Running:

.. code-block:: console

1098
   snf-component-register [<component_name>]
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109

automates the registration of the standard Synnefo components (astakos,
cyclades, and pithos) in astakos database. It internally uses the script:

.. code-block:: console

   snf-service-export <component_name> <base_url>

which simulates the export of service and resource definitions of the
standard Synnefo components.

1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
Pithos managing accounts
========================

Pithos provides a utility tool for managing accounts.
To run you just type:

.. code-block:: console

   # pithos-manage-accounts <command> [arguments]

This is the list of the available commands:

============================  ===========================
Name                          Description
============================  ===========================
delete                        Remove an account from the Pithos DB
export-quota                  Export account quota in a file
list                          List existing/dublicate accounts
merge                         Move an account contents in another account
set-container-quota           Set container quota for all or a specific account
============================  ===========================

1132

1133
The "kamaki" API client
1134
=======================
1135
1136
1137

To upload, register or modify an image you will need the **kamaki** tool.
Before proceeding make sure that it is configured properly. Verify that
1138
*image.url*, *file.url*, *user.url* and *token* are set as needed:
1139
1140
1141
1142
1143

.. code-block:: console

   $ kamaki config list

1144
To change a setting use ``kamaki config set``:
1145
1146
1147

.. code-block:: console

1148
   $ kamaki config set image.url https://cyclades.example.com/image
1149
1150
   $ kamaki config set file.url https://pithos.example.com/v1
   $ kamaki config set user.url https://accounts.example.com
1151
1152
   $ kamaki config set token ...

1153
1154
To test that everything works, try authenticating the current account with
kamaki:
1155
1156
1157
1158
1159

.. code-block:: console

  $ kamaki user authenticate

1160
This will output user information.
1161

1162
1163
1164
Upload Image
------------

1165
1166
By convention, images are stored in a container called ``images``. Check if the
container exists, by listing all containers in your account:
1167
1168
1169

.. code-block:: console

1170
   $ kamaki file list
1171

1172
If the container ``images`` does not exist, create it:
1173
1174
1175

.. code-block:: console

1176
  $ kamaki file create images
1177

1178
You are now ready to upload an image to container ``images``. You can upload it
1179
with a Pithos client, or use kamaki directly:
1180
1181
1182

.. code-block:: console

1183
   $ kamaki file upload ubuntu.iso images
1184

1185
You can use any Pithos client to verify that the image was uploaded correctly,
1186
or you can list the contents of the container with kamaki:
1187

1188
1189
1190
.. code-block:: console

  $ kamaki file list images
1191
1192

The full Pithos URL for the previous example will be
1193
1194
``pithos://u53r-un1qu3-1d/images/ubuntu.iso`` where ``u53r-un1qu3-1d`` is the
unique user id (uuid).
1195
1196
1197
1198

Register Image
--------------

1199
To register an image you will need to use the full Pithos URL. To register as
1200
1201
1202
1203
a public image the one from the previous example use:

.. code-block:: console

1204
   $ kamaki image register Ubuntu pithos://u53r-un1qu3-1d/images/ubuntu.iso --public
1205
1206

The ``--public`` flag is important, if missing the registered image will not
1207
be listed by ``kamaki image list``.
1208

1209
Use ``kamaki image register`` with no arguments to see a list of available
1210
1211
1212
1213
options. A more complete example would be the following:

.. code-block:: console

1214
   $ kamaki image register Ubuntu pithos://u53r-un1qu3-1d/images/ubuntu.iso \
1215
1216
1217
1218
1219
1220
            --public --disk-format diskdump --property kernel=3.1.2

To verify that the image was registered successfully use:

.. code-block:: console

1221
   $ kamaki image list --name-like=ubuntu
1222

1223
1224
1225
1226

Miscellaneous
=============

1227
.. _branding:
Olga Brani's avatar
Olga Brani committed
1228

1229
Branding
1230
--------
Olga Brani's avatar
Olga Brani committed
1231

1232
1233
1234
1235
Since Synnefo v0.14, you are able to adapt the Astakos, Pithos and Cyclades Web
UI to your company’s visual identity. This is possible using the snf-branding
component, which is automatically installed on the nodes running the API
servers for Astakos, Pithos and Cyclades. 
Olga Brani's avatar
Olga Brani committed
1236
1237
1238
1239

Configuration
~~~~~~~~~~~~~

1240
1241
1242
1243
This can be done by modifing the settings provided by the snf-branding component
to match your service identity. The settings for the snf-branding application
can be found inside the configuration file ``/etc/synnefo/15-snf-branding.conf``
on the nodes that have Astakos, Pithos and Cyclades installed.
Olga Brani's avatar
Olga Brani committed
1244

1245
1246
1247
By default, the global service name is "Synnefo" and the company name is
"GRNET". These names and their respective logos and URLs are used throughout
the Astakos, Pithos and Cyclades UI.
Olga Brani's avatar
Olga Brani committed
1248

1249
**Names and URLs:**
Olga Brani's avatar
Olga Brani committed
1250

1251
1252
The first group of branding customization refers to the service's and company's
information.
Olga Brani's avatar
Olga Brani committed
1253

1254
1255
You can overwrite the company and the service name and URL respectively by
uncommenting and setting the following:
Olga Brani's avatar
Olga Brani committed
1256

1257
1258
1259
1260
1261
.. code-block:: python
  
  # setting used in Astakos Dashboard/Projects pages
  BRANDING_SERVICE_NAME = 'My cloud'
  BRANDING_SERVICE_URL = 'http://www.mycloud.synnefo.org/'
Olga Brani's avatar
Olga Brani committed
1262

1263
1264
1265
1266
1267
  # settings used in Astakos, Pithos, Cyclades footer only if 
  # BRANDING_SHOW_COPYRIGHT is set to True
  BRANDING_SHOW_COPYRIGHT = True
  BRANDING_COMPANY_NAME = 'Company LTD'
  BRANDING_COMPANY_URL = 'https://www.company-ltd.synnefo.org/'
Olga Brani's avatar
Olga Brani committed
1268
1269
1270
1271


**Copyright options:**

1272
1273
By default, no Copyright message is shown in the UI footer. If you want to make
it visible in the footer of Astakos, Pithos and Cyclades UI, you can uncomment
1274
and set to ``True`` the ``BRANDING_SHOW_COPYRIGHT`` setting:
Olga Brani's avatar
Olga Brani committed
1275

1276
.. code-block:: python
Olga Brani's avatar
Olga Brani committed
1277
1278
1279

  #BRANDING_SHOW_COPYRIGHT = False

1280
Copyright message defaults to 'Copyright (c) 2011-<current_year>
1281
1282
<BRANDING_COMPANY_NAME>.' but you can overwrite it to a completely custom one by
setting the following option:
Olga Brani's avatar
Olga Brani committed
1283

1284
1285
1286
.. code-block:: python

  BRANDING_COPYRIGHT_MESSAGE = 'Copyright (c) 2011-2013 GRNET'
Olga Brani's avatar
Olga Brani committed
1287
1288
1289
1290


**Images:**

1291
1292
The Astakos, Pithos and Cyclades Web UI has some logos and images.
 
Olga Brani's avatar
Olga Brani committed
1293
1294
1295
1296
1297
1298
1299
1300
The branding-related images are presented in  the following table:

===============  ============================  =========
Image            Name/extension  convention    Usage
===============  ============================  =========
Favicon          favicon.ico                   Favicon for all services
Dashboard logo   dashboard_logo.png            Visible in all Astakos UI pages
Compute logo     compute_logo.png              Visible in all Cyclades UI pages
1301
1302
Console logo     console_logo.png              Visible in the Cyclades Console Window
Storage logo     storage_logo.png              Visible in all Pithos UI pages
Olga Brani's avatar
Olga Brani committed
1303
1304
===============  ============================  =========

1305
There are two methods  available for replacing all, or individual, 
1306
branding-related images:
Olga Brani's avatar
Olga Brani committed
1307

1308
1309
1. Create a new directory inside ``/usr/share/synnefo/static/`` (e.g.
   ``mybranding``) and place there some or all of your images.
Olga Brani's avatar
Olga Brani committed
1310

1311
   If you want to replace all of your images, keep the name/extension
1312
1313
   conventions as indicated in the above table and change the
   ``BRANDING_IMAGE_MEDIA_URL`` setting accordingly:
Olga Brani's avatar
Olga Brani committed
1314

1315
1316
1317
1318
   .. code-block:: python
        
      # using relative path
      BRANDING_IMAGE_MEDIA_URL= '/static/mybranding/images/' 
Olga Brani's avatar
Olga Brani committed
1319

1320
1321
      # or if you already host them in a separate domain (e.g. cdn)
      BRANDING_IMAGE_MEDIA_URL= 'https://cdn.synnefo.org/branding/images/'
Olga Brani's avatar
Olga Brani committed
1322
1323


1324
1325
1326
1327
   If you wish to replace individual images, **do not uncomment**
   ``BRANDING_IMAGE_MEDIA_URL``, but instead provide a relative path, pointing to
   the file inside your directory for each ``BRANDING_<image>_URL`` that you wish
   to replace.
Olga Brani's avatar
Olga Brani committed
1328

1329
2. Upload some or all of your images to a server and replace each 
1330
   ``BRANDING_<image>_URL`` with the absolute url of the image (i.e.
1331
   ``BRANDING_DASHBOARD_URL = 'https://www.synnefo.com/images/my_dashboard.jpg'``).
Olga Brani's avatar
Olga Brani committed
1332

1333
   Note that the alternative text  for each image tag inside html documents is 
1334
   alt=“BRANDING_SERVICE_NAME {Dashboard, Compute. Console, Storage}” respectively.
Olga Brani's avatar
Olga Brani committed
1335

1336
.. note:: Retina optimized images:
Olga Brani's avatar
Olga Brani committed
1337

1338
1339
   Synnefo UI is optimized for Retina displays. As far as images are concerned,  
   `retina.js <http://retinajs.com/>`_ is used.
Olga Brani's avatar
Olga Brani committed
1340

1341
   Retina.js checks each image on a page to see if there is a high-resolution 
1342
1343
   version of that image on your server. If a high-resolution variant exists, 
   the script will swap in that image in-place.
Olga Brani's avatar
Olga Brani committed
1344

1345
1346
1347
1348
1349
   The script assumes you use  `Apple's prescribed high-resolution modifier (@2x)
   <http://developer.apple.com/library/ios/#documentation/2DDrawing/Conceptual/
   DrawingPrintingiOS/SupportingHiResScreensInViews/SupportingHiResScreensInViews
   .html#//apple_ref/doc/uid/TP40010156-CH15-SW1>`_ to denote high-resolution 
   image variants on your server.
Olga Brani's avatar
Olga Brani committed
1350

1351
1352
1353
1354
1355
   For each of the images that you wish the script to  replace, you must have a 
   high-resolution variant in the same folder  named correctly and it will be 
   detected automatically. For example if your image is in <my_directory> and is 
   named "my_image.jpg" the script will look in the same directory for an image 
   named "my_image@2x.jpg".
Olga Brani's avatar
Olga Brani committed
1356

1357
1358
   In case that you don’t want to use a high-resolution image, the 
   normal-resolution image will be visible.
Olga Brani's avatar
Olga Brani committed
1359

1360
1361
More branding
~~~~~~~~~~~~~
Olga Brani's avatar
Olga Brani committed
1362

1363
1364
Although, it is not 100% branding-related, further verbal customization is
feasible. 
Olga Brani's avatar
Olga Brani committed
1365
1366
1367

**EMAILS**

1368
1369
1370
The output of all email `*`.txt files will be already customized to contain your
company and service names but you can further alter their content if you feel it
best fits your needs as simple as creasynnefo template.    
1371

1372
1373
In order to overwrite one or more email-templates you need to place your 
modified <email-file>.txt files respecting the following structure:
1374
  
1375
1376
  **/etc/synnefo/templates/**
      **im/**
1377
1378
1379
1380
1381
          | activation_email.txt
          | email.txt
          | invitation.txt
          | switch_accounts_email.txt
          | welcome_email.txt
1382
          **projects/**
1383
1384
1385
1386
1387
1388
1389
1390
              | project_approval_notification.txt
              | project_denial_notification.txt    
              | project_membership_change_notification.txt
              | project_membership_enroll_notification.txt
              | project_membership_leave_request_notification.txt
              | project_membership_request_notification.txt
              | project_suspension_notification.txt
              | project_termination_notification.txt
1391
      **registration/**
1392
1393
1394
1395
1396
          | email_change_email.txt
          | password_email.txt

Feel free to omit any of the above files you do not wish to overwrite.

Olga Brani's avatar
Olga Brani committed
1397
1398
1399
Below is a list of all emails sent by Synnefo to users along with a short 
description and a link to their content: