admin-guide.rst 66.1 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
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``

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
Twitter Authentication
```````````````````````

To enable twitter authentication while signed in under a Twitter account,
visit dev.twitter.com/apps.

Click Create an application.

Fill the necessary information and for callback URL give::

    https://node1.example.com/ui/login/twitter/authenticated

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


Google Authentication
`````````````````````

To enable google authentication while signed in under a Google account,
visit https://code.google.com/apis/console/.

Under API Access select Create another client ID, select Web application,
expand more options in Your site or hostname section and in Authorized
Redirect URIs add:


Fill the necessary information and for callback URL give::

    https://node1.example.com/ui/login/google/authenticated

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

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
Architecture
------------

Prereqs
-------

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

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

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

141
142
User registration
~~~~~~~~~~~~~~~~~
143

144
145
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):
146
147
148

.. code-block:: console

149
   $ snf-manage user-list
150

151
152
More detailed user status is provided in the `status` field of the `user-show` 
command:
153

154
.. code-block:: console
155

156
  $ snf-manage user-show <user-id>
157

158
159
160
161
162
  id                  : 6
  uuid                : 78661411-5eed-412f-a9ea-2de24f542c2e
  status              : Accepted/Active (accepted policy: manual)
  email               : user@synnefo.org
  ....
163
164


165
166
167
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.
168

169
170

User activation flow
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
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
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

296

297
298
299
Setting quota limits
~~~~~~~~~~~~~~~~~~~~

300
301
Set default quota
`````````````````
302
303
304
305

In 20-snf-astakos-app-settings.conf, 
uncomment the default setting ``ASTAKOS_SERVICES``
and customize the ``'uplimit'`` values.
306
These are the default base quota for all users.
307
308
309
310

To apply your configuration run::

    # snf-manage astakos-init --load-service-resources
311
    # snf-manage quota --sync
312

313
314
Set base quota for individual users
```````````````````````````````````
315

316
For individual users that need different quota than the default
317
318
you can set it for each resource like this::

319
320
    # use this to display quota / uuid
    # snf-manage user-show 'uuid or email' --quota
321

322
    # snf-manage user-modify 'user-uuid' --set-base-quota 'cyclades.vm' 10
323
324
325
326
327
328
329
330
331
332
333
334


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

335
336
You can change the maximum allowed number of pending project applications
per user with::
337

338
339
340
341
    # snf-manage resource-modify astakos.pending_app --limit <number>

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

342
    # snf-manage user-modify 'user-uuid' --set-base-quota 'astakos.pending_app' 5
343

344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
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>

360
361
362
363
364
365
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>, ...]
366
367


368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
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.

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
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.

419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461


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
------------

462
Asynchronous communication with Ganeti backends
Christos Stavrakakis's avatar
Christos Stavrakakis committed
463
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464
465
466
467
468
469
470
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:
471
472
473
474

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

476
The Cyclades API server is responsible for handling user requests. Read-only
477
478
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
479
480
master using the `Ganeti RAPI interface
<http://docs.ganeti.org/ganeti/2.2/html/rapi.html>`_.
481

482
483
While Ganeti executes the job, `snf-ganeti-eventd`, `snf-ganeti-hook` and
`snf-progress-monitor` are monitoring the progress of the job and send
484
corresponding messages to the RabbitMQ servers. These components are part
485
of `snf-cyclades-gtools` and must be installed on all Ganeti nodes. Specially:
486
487

* *snf-ganeti-eventd* sends messages about operations affecting the operating
488
489
  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
490
491
  number of `Ganeti hooks <http://docs.ganeti.org/ganeti/2.2/html/hooks.html>`_
  for customisation of operations.
492
493
* *snf-progress_monitor* sends messages about the progress of the Image deployment
  phase which is done by the Ganeti OS Definition `snf-image`.
494

495
496
497
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.
498
499


500
501
502
Prereqs
-------

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

505
506
507
Installation
------------

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

510
511
512
Configuration
-------------

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

515
516
517
Working with Cyclades
---------------------

518
Managing Ganeti Backends
Christos Stavrakakis's avatar
Christos Stavrakakis committed
519
~~~~~~~~~~~~~~~~~~~~~~~~
520

521
522
523
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.
524

525
526
527
528
529
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.
530
531

Handling of Networks, as far as backends are concerned, is based on whether the
532
533
534
535
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.
536

537
538
539
Listing existing backends
`````````````````````````
To list all the Ganeti backends known to Synnefo, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
540

541
542
543
544
545
.. code-block:: console

   $ snf-manage backend-list

Adding a new Ganeti backend
Christos Stavrakakis's avatar
Christos Stavrakakis committed
546
```````````````````````````
547
548
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,
549
550
named ``cluster.example.com`` is already up and running and configured to be
able to host Synnefo VMs.
551

552
To add this Ganeti cluster, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
553

554
555
556
557
.. code-block:: console

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

558
559
560
561
562
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.
563

564
565
566
``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`.
567

568
569
570
571
572
573
574
575
576
577
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

578
   $ snf-manage backend-modify --drained=False <backend_id>
579
580

Removing an existing Ganeti backend
Christos Stavrakakis's avatar
Christos Stavrakakis committed
581
```````````````````````````````````
582
In order to remove an existing backend from Synnefo, we run:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
583

584
585
.. code-block:: console

586
   # snf-manage backend-remove <backend_id>
587

588
589
590
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.
591

592
593
594
595
596
597
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).
598
599
600
601

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
602
backends from the allocation phase by marking them as ``drained`` by running:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
603

604
605
.. code-block:: console

606
   $ snf-manage backend-modify --drained=True <backend_id>
607
608

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

614
615
616
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
617
618
Synnefo allocates all his/hers VMs to the specific backend in the variable,
even if is marked as drained (useful for testing).
619

620
621
622
623

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

624
625
626
627
628
629
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``.
630

631
Apart from handling instances directly in the Ganeti level, a number of `snf-manage`
632
633
commands are available:

634
635
636
637
638
639
* ``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
640
641
642
643
644


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

645
646
647
648
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.
649
650
651

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
652
networks that belong to Synnefo are named with the prefix
653
654
`${BACKEND_PREFIX_ID}-net-`.

655
There are also the following `snf-manage` commands for managing networks:
656

657
658
659
660
661
662
* ``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
663

664
Managing Network Resources
665
``````````````````````````
666

667
668
669
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:
670

671
672
673
674
675
* 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.
676
* Bridges corresponding to physical VLANs, which are required for networks of
677
678
679
  type `PRIVATE_PHYSICAL_VLAN`.
* One Bridge corresponding to one physical VLAN which is required for networks of
  type `PRIVATE_MAC_PREFIX`.
680

681
682
Cyclades allocates those resources from pools that are created by the
administrator with the `snf-manage pool-create` management command.
683

684
685
686
Pool Creation
`````````````
Pools are created using the `snf-manage pool-create` command:
Christos Stavrakakis's avatar
Christos Stavrakakis committed
687

688
689
690
691
692
693
694
.. 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
695

696
697
698
699
700
.. code-block:: console

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

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

703
704
705
706
.. code-block:: console

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

707
708
709
710
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.
711

712
713
714
715
716
Cyclades advanced operations
----------------------------

Reconciliation mechanism
~~~~~~~~~~~~~~~~~~~~~~~~
717

718
719
720
721
722
723
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

724
725
726
Reconciling Virtual Machines
````````````````````````````

727
Reconciliation of VMs detects the following conditions:
728

729
730
 * Stale DB servers without corresponding Ganeti instances
 * Orphan Ganeti instances, without corresponding DB entries
731
 * Out-of-sync state for DB entries wrt to Ganeti instances
732

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

735
.. code-block:: console
736
737

  $ snf-manage reconcile-servers
738

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

741
.. code-block:: console
742

743
  $ snf-manage reconcile-servers --fix-all
744

745
Please see ``snf-manage reconcile-servers --help`` for all the details.
746
747


748
Reconciling Networks
Christos Stavrakakis's avatar
Christos Stavrakakis committed
749
````````````````````
750

751
Reconciliation of Networks detects the following conditions:
752

753
754
755
756
757
758
  * 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
759

760
.. code-block:: console
761

762
763
764
  $ snf-manage reconcile-networks

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

766
.. code-block:: console
767

768
769
770
  $ snf-manage reconcile-networks --fix-all

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


773

774
775
776
777
778
Block Storage Service (Archipelago)
===================================

Overview
--------
779
780
781
782
783
784
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
785
786
CoW volumes. Moreover, it enables live migration of thinly-provisioned VMs with
no physically shared storage.
787

788
789
790
Archipelago Architecture
------------------------

791
792
793
.. image:: images/archipelago-architecture.png
   :width: 50%
   :target: _images/archipelago-architecture.png
794

795
796
797
798
799
800
801
802
803
.. _syn+archip+rados:

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

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

804
805
Prereqs
-------
806

807
808
809
810
811
812
813
814
815
816
817
818
819
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.

820
821
Installation
------------
822

823
824
825
Archipelago consists of

* ``libxseg0``: libxseg used to communicate over shared memory segments
826
* ``python-xseg``: python bindings for libxseg
827
828
* ``archipelago-kernel-dkms``: contains archipelago kernel modules to provide
  block devices to be used as vm disks
829
830
* ``python-archipelago``: archipelago python module. Includes archipelago and
  vlmc functionality.
831
832
833
834
835
836
837
838
839
840
841
842
843
844
* ``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
845
repo of GRNet.
846
847


848
849
For now, librados is a dependency of archipelago, even if you do not intend to
use archipelago over RADOS.
850
851
852

Configuration
-------------
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
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
875
  reside.
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899

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.
900
901
902
903

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

904
``archipelago`` provides basic functionality for archipelago.
905
906
907
908
909
910
911
912

Usage:

.. code-block:: console

  $ archipelago [-u] command


913
914
Currently it supports the following commands:

915
916
917
918
919
920
* ``start [peer]``
  Starts archipelago or the specified peer.
* ``stop [peer]``
  Stops archipelago or the specified peer.
* ``restart [peer]``
  Restarts archipelago or the specified peer.
921
* ``status``
922
923
924
925
  Show the status of archipelago.

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

926
927
928
929
930
931

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



932
933
Archipelago advanced operations
-------------------------------
934
935
936
The ``vlmc`` tool provides a way to interact with archipelago volumes

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

938
* ``vlmc unmap </dev/xsegbd[1-..]>``: unmaps the specified device from the
939
  system.
940

941
942
* ``vlmc create <volumename> --snap <snapname> --size <size>``: creates a new
  volume named <volumename> from snapshot name <snapname> with size <size>.
943
944
  The ``--snap`` and ``--size`` are optional, but at least one of them is
  mandatory. e.g:
945

946
947
948
  ``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.
949

950
951
  ``vlmc create <volumename> --size <size>`` creates an empty volume of size
  <size> named <volumename>.
952

953
954
* ``vlmc remove <volumename>``: removes the volume and all the related
  archipelago blocks from storage.
955

956
957
* ``vlmc list``: provides a list of archipelago volumes. Currently only works
  with RADOS storage backend.
958

959
960
961
* ``vlmc info <volumename>``: shows volume information. Currently returns only
  volume size.

962
963
964
965
966
967
968
969
970
971
972
973
974
975
* ``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
976
  infrastrure.
977
978
979
980
981
982
983
984

* ``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.

985

986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
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
1037
cleanup-full                  Cleanup sessions and session catalog
1038
1039
commission-list               List pending commissions
commission-show               Show details for a pending commission
1040
1041
1042
component-add                 Register a component
component-list                List components
component-modify              Modify component attributes
1043
1044
1045
1046
1047
1048
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
1049
resource-import               Register resources
1050
resource-list                 List resources
1051
resource-modify               Modify a resource's default base quota and boolean flags
1052
service-import                Register services
1053
service-list                  List services
1054
service-show                  Show service details
1055
1056
1057
term-add                      Add approval terms
user-activation-send          Send user activation
user-add                      Add user
1058
1059
1060
1061
1062
1063
1064
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
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
user-list                     List users
user-modify                   Modify user
user-show                     Show user details
============================  ===========================

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

============================  ===========================
Name                          Description
============================  ===========================
1076
1077
1078
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.
1079
1080
1081
1082
1083
============================  ===========================

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

1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
============================== ===========================
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.
============================== ===========================
1123

1124
1125
1126
1127
1128
1129
1130
1131
Astakos helper scripts
======================

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

.. code-block:: console

1132
   snf-component-register [<component_name>]
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143

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.

1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
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
============================  ===========================

1166

1167
The "kamaki" API client
1168
=======================
1169
1170
1171

To upload, register or modify an image you will need the **kamaki** tool.
Before proceeding make sure that it is configured properly. Verify that
1172
*image.url*, *file.url*, *user.url* and *token* are set as needed:
1173
1174
1175
1176
1177

.. code-block:: console

   $ kamaki config list

1178
To change a setting use ``kamaki config set``:
1179
1180
1181

.. code-block:: console

1182
   $ kamaki config set image.url https://cyclades.example.com/image
1183
1184
   $ kamaki config set file.url https://pithos.example.com/v1
   $ kamaki config set user.url https://accounts.example.com
1185
1186
   $ kamaki config set token ...

1187
1188
To test that everything works, try authenticating the current account with
kamaki:
1189
1190
1191
1192
1193

.. code-block:: console

  $ kamaki user authenticate

1194
This will output user information.
1195

1196
1197
1198
Upload Image
------------

1199
1200
By convention, images are stored in a container called ``images``. Check if the
container exists, by listing all containers in your account:
1201
1202
1203

.. code-block:: console

1204
   $ kamaki file list
1205

1206
If the container ``images`` does not exist, create it:
1207
1208
1209

.. code-block:: console

1210
  $ kamaki file create images
1211

1212
You are now ready to upload an image to container ``images``. You can upload it
1213
with a Pithos client, or use kamaki directly:
1214
1215
1216

.. code-block:: console

1217
   $ kamaki file upload ubuntu.iso images
1218

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

1222
1223
1224
.. code-block:: console

  $ kamaki file list images
1225
1226

The full Pithos URL for the previous example will be
1227
1228
``pithos://u53r-un1qu3-1d/images/ubuntu.iso`` where ``u53r-un1qu3-1d`` is the
unique user id (uuid).
1229
1230
1231
1232

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

1233
To register an image you will need to use the full Pithos URL. To register as
1234
1235
1236
1237
a public image the one from the previous example use:

.. code-block:: console

1238
   $ kamaki image register Ubuntu pithos://u53r-un1qu3-1d/images/ubuntu.iso --public
1239
1240

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

1243
Use ``kamaki image register`` with no arguments to see a list of available
1244
1245
1246
1247
options. A more complete example would be the following:

.. code-block:: console

1248
   $ kamaki image register Ubuntu pithos://u53r-un1qu3-1d/images/ubuntu.iso \
1249
1250
1251
1252
1253
1254
            --public --disk-format diskdump --property kernel=3.1.2

To verify that the image was registered successfully use:

.. code-block:: console

1255
   $ kamaki image list --name-like=ubuntu
1256

1257
1258
1259
1260

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

1261
.. _branding:
Olga Brani's avatar
Olga Brani committed
1262

1263
Branding
1264
--------
Olga Brani's avatar
Olga Brani committed
1265

1266
1267
1268
1269
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
1270
1271
1272
1273

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

1274
1275
1276
1277
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
1278

1279
1280
1281
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
1282

1283
**Names and URLs:**
Olga Brani's avatar
Olga Brani committed
1284

1285
1286
The first group of branding customization refers to the service's and company's
information.
Olga Brani's avatar
Olga Brani committed
1287

1288
1289
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
1290

1291
1292
1293
1294
1295
.. 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
1296

1297
1298
1299
1300
1301
  # 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
1302
1303


Olga Brani's avatar
Olga Brani committed
1304
**Copyright and footer options:**
Olga Brani's avatar
Olga Brani committed
1305

1306
1307
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
1308
and set to ``True`` the ``BRANDING_SHOW_COPYRIGHT`` setting:
Olga Brani's avatar
Olga Brani committed
1309

1310
.. code-block:: python
Olga Brani's avatar
Olga Brani committed
1311
1312
1313

  #BRANDING_SHOW_COPYRIGHT = False

1314
Copyright message defaults to 'Copyright (c) 2011-<current_year>
1315
1316
<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
1317

1318
1319
1320
.. code-block:: python

  BRANDING_COPYRIGHT_MESSAGE = 'Copyright (c) 2011-2013 GRNET'
Olga Brani's avatar
Olga Brani committed
1321

Olga Brani's avatar
Olga Brani committed
1322
1323
1324
1325
1326
1327
1328
1329
1330
If you want to include a custom message in the footer, you can uncomment and 
set the ``BRANDING_FOOTER_EXTRA_MESSAGE`` setting. You can use html markup. 
Your custom message will appear  above Copyright message at the Compute 
templates and the Dashboard UI.

.. code-block:: python

  #BRANDING_FOOTER_EXTRA_MESSAGE = ''

Olga Brani's avatar
Olga Brani committed
1331
1332
1333

**Images:**

1334
1335
The Astakos, Pithos and Cyclades Web UI has some logos and images.
 
Olga Brani's avatar
Olga Brani committed
1336
1337
1338
1339
1340
1341
1342
1343
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
1344
1345
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
1346
1347
===============  ============================  =========

1348
There are two methods  available for replacing all, or individual, 
1349
branding-related images:
Olga Brani's avatar
Olga Brani committed
1350

1351
1352
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
1353

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

1358
1359
1360
1361
   .. code-block:: python
        
      # using relative path
      BRANDING_IMAGE_MEDIA_URL= '/static/mybranding/images/' 
Olga Brani's avatar
Olga Brani committed
1362

1363
1364
      # 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
1365
1366


1367
1368
1369
1370
   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
1371

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

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

1379
.. note:: Retina optimized images:
Olga Brani's avatar
Olga Brani committed
1380

1381
1382
   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
1383

1384
   Retina.js checks each image on a page to see if there is a high-resolution 
1385
1386
   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
1387

1388
1389
1390
1391
1392
   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
1393

1394
1395
1396
1397
1398
   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
1399

1400
1401
   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
1402

1403
1404
More branding
~~~~~~~~~~~~~
Olga Brani's avatar
Olga Brani committed
1405

1406
1407
Although, it is not 100% branding-related, further verbal customization is
feasible. 
Olga Brani's avatar
Olga Brani committed
1408
1409
1410

**EMAILS**

1411
1412
1413
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.    
1414

1415
1416
In order to overwrite one or more email-templates you need to place your 
modified <email-file>.txt files respecting the following structure:
1417
  
1418
1419
  **/etc/synnefo/templates/**
      **im/**
1420
1421
1422
1423
1424
          | activation_email.txt
          | email.txt
          | invitation.txt
          | switch_accounts_email.txt
          | welcome_email.txt
1425
          **projects/**
1426
1427
1428
1429
1430
1431
1432
1433
              | 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
1434
      **registration/**
1435
1436
1437
1438
1439
          | 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
1440
1441
1442
Below is a list of all emails sent by Synnefo to users along with a short 
description and a link to their content:

1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469