Statistics
| Branch: | Tag: | Revision:

root / docs / admin-guide.rst @ 7a3439cf

History | View | Annotate | Download (9.9 kB)

1
.. _admin-guide:
2

    
3
Synnefo Administrator's Guide
4
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5

    
6
This is the complete Synnefo Administrator's Guide.
7

    
8
Common administrative tasks
9
===========================
10

    
11
If you installed Synnefo successfully and have a working deployment, here are
12
some common administrative tasks that you may find useful.
13

    
14

    
15
.. _user_activation:
16

    
17
User activation
18
---------------
19

    
20
When a new user signs up, he/she is not marked as active. You can see his/her
21
state by running (on the machine that runs the Astakos app):
22

    
23
.. code-block:: console
24

    
25
   $ snf-manage listusers
26

    
27
There are two different ways to activate a new user. Both need access to a
28
running mail server. Your mail server should be defined in the
29
``/etc/synnefo/00-snf-common-admins.conf`` related constants. At least:
30

    
31
.. code-block:: console
32

    
33
   EMAIL_HOST = "my_mail_server.example.com"
34
   EMAIL_PORT = "25"
35

    
36
Manual activation
37
~~~~~~~~~~~~~~~~~
38

    
39
You can manually activate a new user that has already signed up, by sending
40
him/her an activation email. The email will contain an approriate activation
41
link, which will complete the activation process if followed. You can send the
42
email by running:
43

    
44
.. code-block:: console
45

    
46
   $ snf-manage sendactivation <user ID or email>
47

    
48
Be sure to have already setup your mail server and defined it in your synnefo
49
settings, before running the command.
50

    
51
Automatic activation
52
~~~~~~~~~~~~~~~~~~~~
53

    
54

    
55
The "kamaki" API client
56
-----------------------
57

    
58
To upload, register or modify an image you will need the **kamaki** tool.
59
Before proceeding make sure that it is configured properly. Verify that
60
*image_url*, *storage_url*, and *token* are set as needed:
61

    
62
.. code-block:: console
63

    
64
   $ kamaki config list
65

    
66
To chage a setting use ``kamaki config set``:
67

    
68
.. code-block:: console
69

    
70
   $ kamaki config set image_url https://cyclades.example.com/plankton
71
   $ kamaki config set storage_url https://pithos.example.com/v1
72
   $ kamaki config set token ...
73

    
74
Upload Image
75
------------
76

    
77
As a shortcut, you can configure a default account and container that will be
78
used by the ``kamaki store`` commands:
79

    
80
.. code-block:: console
81

    
82
   $ kamaki config set storage_account images@example.com
83
   $ kamaki config set storage_container images
84

    
85
If the container does not exist, you will have to create it before uploading
86
any images:
87

    
88
.. code-block:: console
89

    
90
   $ kamaki store create images
91

    
92
You are now ready to upload an image. You can upload it with a Pithos+ client,
93
or use kamaki directly:
94

    
95
.. code-block:: console
96

    
97
   $ kamaki store upload ubuntu.iso
98

    
99
You can use any Pithos+ client to verify that the image was uploaded correctly.
100
The full Pithos URL for the previous example will be
101
``pithos://images@example.com/images/ubuntu.iso``.
102

    
103

    
104
Register Image
105
--------------
106

    
107
To register an image you will need to use the full Pithos+ URL. To register as
108
a public image the one from the previous example use:
109

    
110
.. code-block:: console
111

    
112
   $ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso --public
113

    
114
The ``--public`` flag is important, if missing the registered image will not
115
be listed by ``kamaki glance list``.
116

    
117
Use ``kamaki glance register`` with no arguments to see a list of available
118
options. A more complete example would be the following:
119

    
120
.. code-block:: console
121

    
122
   $ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso \
123
            --public --disk-format diskdump --property kernel=3.1.2
124

    
125
To verify that the image was registered successfully use:
126

    
127
.. code-block:: console
128

    
129
   $ kamaki glance list -l
130

    
131

    
132
Admin tool: snf-manage
133
----------------------
134

    
135
``snf-manage`` is a tool used to perform various administrative tasks. It needs
136
to be able to access the django database, so the following should be able to
137
import the Django settings.
138

    
139
Additionally, administrative tasks can be performed via the admin web interface
140
located in /admin. Only users of type ADMIN can access the admin pages. To
141
change the type of a user to ADMIN, snf-admin can be used:
142

    
143
.. code-block:: console
144

    
145
   $ snf-manage user-modify 42 --type ADMIN
146

    
147

    
148
Adding Astakos "Terms of Use"
149
-----------------------------
150

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

    
155
.. code-block:: console
156

    
157
   <h1>~okeanos terms</h1>
158

    
159
   These are the example terms for ~okeanos
160

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

    
163
.. code-block:: console
164

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

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

    
170

    
171
Reconciliation mechanism
172
------------------------
173

    
174
On certain occasions, such as a Ganeti or RabbitMQ failure, the VM state in the
175
system's database may differ from that in the Ganeti installation. The
176
reconciliation process is designed to bring the system's database in sync with
177
what Ganeti knows about each VM, and is able to detect the following three
178
conditions:
179

    
180
 * Stale DB servers without corresponding Ganeti instances
181
 * Orphan Ganeti instances, without corresponding DB entries
182
 * Out-of-sync operstate for DB entries wrt to Ganeti instances
183

    
184
The reconciliation mechanism runs as a management command, e.g., as follows:
185
[PYTHONPATH needs to contain the parent of the synnefo Django project
186
directory]:
187

    
188
.. code-block:: console
189

    
190
   $ export PYTHONPATH=/srv:$PYTHONPATH
191
   $ snf-manage reconcile --detect-all -v 2
192

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

    
195
The administrator can also trigger reconciliation of operating state manually,
196
by issuing a Ganeti ``OP_INSTANCE_QUERY_DATA`` command on a Synnefo VM, using
197
gnt-instance info.
198

    
199
Logging
200
-------
201

    
202
Logging in Synnefo is using Python's logging module. The module is configured
203
using dictionary configuration, whose format is described here:
204

    
205
http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema
206

    
207
Note that this is a feature of Python 2.7 that we have backported for use in
208
Python 2.6.
209

    
210
The logging configuration dictionary is defined in settings.d/00-logging.conf
211
and is broken in 4 separate dictionaries:
212

    
213
  * LOGGING is the logging configuration used by the web app. By default all
214
    loggers fall back to the main 'synnefo' logger. The subloggers can be
215
    changed accordingly for finer logging control. e.g. To disable debug
216
    messages from the API set the level of 'synnefo.api' to 'INFO'.
217
  
218
  * DISPATCHER_LOGGING is the logging configuration of the logic/dispatcher.py
219
    command line tool.
220
  
221
  * SNFADMIN_LOGGING is the logging configuration of the snf-admin tool.
222
    Consider using matching configuration for snf-admin and the synnefo.admin
223
    logger of the web app.
224

    
225
Please note the following:
226

    
227
  * As of Synnefo v0.7, by default the Django webapp logs to syslog, the
228
    dispatcher logs to /var/log/synnefo/dispatcher.log and the console,
229
    snf-admin logs to the console.
230
  * Different handlers can be set to different logging levels:
231
    for example, everything may appear to the console, but only INFO and higher
232
    may actually be stored in a longer-term logfile
233

    
234

    
235
.. _shibboleth-auth:
236

    
237
Authentication using Shibboleth
238
===============================
239

    
240
Astakos can delegate user authentication to a Shibboleth federation.
241

    
242
To setup shibboleth, install package::
243

    
244
  apt-get install libapache2-mod-shib2
245

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

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

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

    
253
  <Location /im/login/shibboleth>
254
    AuthType shibboleth
255
    ShibRequireSession On
256
    ShibUseHeaders On
257
    require valid-user
258
  </Location>
259

    
260
and before the line containing::
261

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

    
264
add::
265

    
266
  ProxyPass /Shibboleth.sso !
267

    
268
Then, enable the shibboleth module::
269

    
270
  a2enmod shib2
271

    
272
After passing through the apache module, the following tokens should be
273
available at the destination::
274

    
275
  eppn # eduPersonPrincipalName
276
  Shib-InetOrgPerson-givenName
277
  Shib-Person-surname
278
  Shib-Person-commonName
279
  Shib-InetOrgPerson-displayName
280
  Shib-EP-Affiliation
281
  Shib-Session-ID
282

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

    
286

    
287
Scaling up to multiple nodes
288
============================
289

    
290
Here we will describe how to deploy all services, interconnected with each
291
other, on multiple physical nodes.
292

    
293
synnefo components
294
------------------
295

    
296
You need to install the appropriate synnefo software components on each node,
297
depending on its type, see :ref:`Architecture <cyclades-architecture>`.
298

    
299
Please see the page of each synnefo software component for specific
300
installation instructions, where applicable.
301

    
302
Install the following synnefo components:
303

    
304
Nodes of type :ref:`APISERVER <APISERVER_NODE>`
305
    Components
306
    :ref:`snf-common <snf-common>`,
307
    :ref:`snf-webproject <snf-webproject>`,
308
    :ref:`snf-cyclades-app <snf-cyclades-app>`
309
Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>`
310
    Components
311
    :ref:`snf-common <snf-common>`,
312
    :ref:`snf-cyclades-gtools <snf-cyclades-gtools>`
313
Nodes of type :ref:`LOGIC <LOGIC_NODE>`
314
    Components
315
    :ref:`snf-common <snf-common>`,
316
    :ref:`snf-webproject <snf-webproject>`,
317
    :ref:`snf-cyclades-app <snf-cyclades-app>`.
318

    
319
RabbitMQ
320
--------
321

    
322
RabbitMQ is used as a generic message broker for Cyclades. It should be
323
installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high
324
availability configuration as described here:
325

    
326
    http://www.rabbitmq.com/pacemaker.html
327

    
328
The values set for the user and password must be mirrored in the ``RABBIT_*``
329
variables in your settings, as managed by :ref:`snf-common <snf-common>`.
330

    
331
.. todo:: Document an active-active configuration based on the latest version
332
   of RabbitMQ.
333

    
334

    
335
Upgrade Notes
336
=============
337

    
338
Cyclades upgrade notes
339
----------------------
340

    
341
.. toctree::
342
   :maxdepth: 2
343

    
344
   cyclades-upgrade
345

    
346
Changelog
347
=========