root / docs / admin-guide.rst @ 382ca20a
History | View | Annotate | Download (10.7 kB)
1 |
.. _admin-guide: |
---|---|
2 |
|
3 |
Synnefo Administrator's Guide |
4 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
5 |
|
6 |
This is the complete Synnefo Administrator's Guide. |
7 |
|
8 |
Quick Installation |
9 |
================== |
10 |
|
11 |
The quick installation guide describes how to install the whole synnefo stack |
12 |
in just two physical nodes, for testing purposes. This guide is useful to those |
13 |
interested in deploying synnefo in large scale, as a starting point that will |
14 |
help them get familiar with the synnefo components and overall architecture, as |
15 |
well as the interconnection between different services. Such an installation, |
16 |
also provides a quick preview of the basic synnefo features, although we would |
17 |
like to think that synnefo unveils its real power while scaling. |
18 |
|
19 |
| :ref:`Administrator's quick installation guide <quick-install-admin-guide>` |
20 |
| This guide will walk you through a complete installation using debian packages. |
21 |
|
22 |
Common administrative tasks |
23 |
=========================== |
24 |
|
25 |
If you installed Synnefo successfully and have a working deployment, here are |
26 |
some common administrative tasks that you may find useful. |
27 |
|
28 |
|
29 |
.. _user_activation: |
30 |
|
31 |
User activation |
32 |
--------------- |
33 |
|
34 |
When a new user signs up, he/she is not marked as active. You can see his/her |
35 |
state by running (on the machine that runs the Astakos app): |
36 |
|
37 |
.. code-block:: console |
38 |
|
39 |
$ snf-manage listusers |
40 |
|
41 |
There are two different ways to activate a new user. Both need access to a |
42 |
running mail server. Your mail server should be defined in the |
43 |
``/etc/synnefo/00-snf-common-admins.conf`` related constants. At least: |
44 |
|
45 |
.. code-block:: console |
46 |
|
47 |
EMAIL_HOST = "my_mail_server.example.com" |
48 |
EMAIL_PORT = "25" |
49 |
|
50 |
Manual activation |
51 |
~~~~~~~~~~~~~~~~~ |
52 |
|
53 |
You can manually activate a new user that has already signed up, by sending |
54 |
him/her an activation email. The email will contain an approriate activation |
55 |
link, which will complete the activation process if followed. You can send the |
56 |
email by running: |
57 |
|
58 |
.. code-block:: console |
59 |
|
60 |
$ snf-manage sendactivation <user ID or email> |
61 |
|
62 |
Be sure to have already setup your mail server and defined it in your synnefo |
63 |
settings, before running the command. |
64 |
|
65 |
Automatic activation |
66 |
~~~~~~~~~~~~~~~~~~~~ |
67 |
|
68 |
|
69 |
The "kamaki" API client |
70 |
----------------------- |
71 |
|
72 |
To upload, register or modify an image you will need the **kamaki** tool. |
73 |
Before proceeding make sure that it is configured properly. Verify that |
74 |
*image_url*, *storage_url*, and *token* are set as needed: |
75 |
|
76 |
.. code-block:: console |
77 |
|
78 |
$ kamaki config list |
79 |
|
80 |
To chage a setting use ``kamaki config set``: |
81 |
|
82 |
.. code-block:: console |
83 |
|
84 |
$ kamaki config set image_url https://cyclades.example.com/plankton |
85 |
$ kamaki config set storage_url https://pithos.example.com/v1 |
86 |
$ kamaki config set token ... |
87 |
|
88 |
Upload Image |
89 |
------------ |
90 |
|
91 |
As a shortcut, you can configure a default account and container that will be |
92 |
used by the ``kamaki store`` commands: |
93 |
|
94 |
.. code-block:: console |
95 |
|
96 |
$ kamaki config set storage_account images@example.com |
97 |
$ kamaki config set storage_container images |
98 |
|
99 |
If the container does not exist, you will have to create it before uploading |
100 |
any images: |
101 |
|
102 |
.. code-block:: console |
103 |
|
104 |
$ kamaki store create images |
105 |
|
106 |
You are now ready to upload an image. You can upload it with a Pithos+ client, |
107 |
or use kamaki directly: |
108 |
|
109 |
.. code-block:: console |
110 |
|
111 |
$ kamaki store upload ubuntu.iso |
112 |
|
113 |
You can use any Pithos+ client to verify that the image was uploaded correctly. |
114 |
The full Pithos URL for the previous example will be |
115 |
``pithos://images@example.com/images/ubuntu.iso``. |
116 |
|
117 |
|
118 |
Register Image |
119 |
-------------- |
120 |
|
121 |
To register an image you will need to use the full Pithos+ URL. To register as |
122 |
a public image the one from the previous example use: |
123 |
|
124 |
.. code-block:: console |
125 |
|
126 |
$ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso --public |
127 |
|
128 |
The ``--public`` flag is important, if missing the registered image will not |
129 |
be listed by ``kamaki glance list``. |
130 |
|
131 |
Use ``kamaki glance register`` with no arguments to see a list of available |
132 |
options. A more complete example would be the following: |
133 |
|
134 |
.. code-block:: console |
135 |
|
136 |
$ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso \ |
137 |
--public --disk-format diskdump --property kernel=3.1.2 |
138 |
|
139 |
To verify that the image was registered successfully use: |
140 |
|
141 |
.. code-block:: console |
142 |
|
143 |
$ kamaki glance list -l |
144 |
|
145 |
|
146 |
Admin tool: snf-manage |
147 |
---------------------- |
148 |
|
149 |
``snf-manage`` is a tool used to perform various administrative tasks. It needs |
150 |
to be able to access the django database, so the following should be able to |
151 |
import the Django settings. |
152 |
|
153 |
Additionally, administrative tasks can be performed via the admin web interface |
154 |
located in /admin. Only users of type ADMIN can access the admin pages. To |
155 |
change the type of a user to ADMIN, snf-admin can be used: |
156 |
|
157 |
.. code-block:: console |
158 |
|
159 |
$ snf-manage user modify 42 --type ADMIN |
160 |
|
161 |
|
162 |
Adding Astakos "Terms of Use" |
163 |
----------------------------- |
164 |
|
165 |
Astakos supports versioned terms-of-use. First of all you need to create an |
166 |
html file that will contain your terms. For example, create the file |
167 |
``/usr/share/synnefo/sample-terms.html``, which contains the following: |
168 |
|
169 |
.. code-block:: console |
170 |
|
171 |
<h1>~okeanos terms</h1> |
172 |
|
173 |
These are the example terms for ~okeanos |
174 |
|
175 |
Then, add those terms-of-use with the snf-manage command: |
176 |
|
177 |
.. code-block:: console |
178 |
|
179 |
$ snf-manage addterms /usr/share/synnefo/sample-terms.html |
180 |
|
181 |
Your terms have been successfully added and you will see the corresponding link |
182 |
appearing in the Astakos web pages' footer. |
183 |
|
184 |
|
185 |
Reconciliation mechanism |
186 |
------------------------ |
187 |
|
188 |
On certain occasions, such as a Ganeti or RabbitMQ failure, the VM state in the |
189 |
system's database may differ from that in the Ganeti installation. The |
190 |
reconciliation process is designed to bring the system's database in sync with |
191 |
what Ganeti knows about each VM, and is able to detect the following three |
192 |
conditions: |
193 |
|
194 |
* Stale DB servers without corresponding Ganeti instances |
195 |
* Orphan Ganeti instances, without corresponding DB entries |
196 |
* Out-of-sync operstate for DB entries wrt to Ganeti instances |
197 |
|
198 |
The reconciliation mechanism runs as a management command, e.g., as follows: |
199 |
[PYTHONPATH needs to contain the parent of the synnefo Django project |
200 |
directory]: |
201 |
|
202 |
.. code-block:: console |
203 |
|
204 |
$ export PYTHONPATH=/srv:$PYTHONPATH |
205 |
$ snf-manage reconcile --detect-all -v 2 |
206 |
|
207 |
Please see ``snf-manage reconcile --help`` for all the details. |
208 |
|
209 |
The administrator can also trigger reconciliation of operating state manually, |
210 |
by issuing a Ganeti ``OP_INSTANCE_QUERY_DATA`` command on a Synnefo VM, using |
211 |
gnt-instance info. |
212 |
|
213 |
Logging |
214 |
------- |
215 |
|
216 |
Logging in Synnefo is using Python's logging module. The module is configured |
217 |
using dictionary configuration, whose format is described here: |
218 |
|
219 |
http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema |
220 |
|
221 |
Note that this is a feature of Python 2.7 that we have backported for use in |
222 |
Python 2.6. |
223 |
|
224 |
The logging configuration dictionary is defined in settings.d/00-logging.conf |
225 |
and is broken in 4 separate dictionaries: |
226 |
|
227 |
* LOGGING is the logging configuration used by the web app. By default all |
228 |
loggers fall back to the main 'synnefo' logger. The subloggers can be |
229 |
changed accordingly for finer logging control. e.g. To disable debug |
230 |
messages from the API set the level of 'synnefo.api' to 'INFO'. |
231 |
|
232 |
* DISPATCHER_LOGGING is the logging configuration of the logic/dispatcher.py |
233 |
command line tool. |
234 |
|
235 |
* SNFADMIN_LOGGING is the logging configuration of the snf-admin tool. |
236 |
Consider using matching configuration for snf-admin and the synnefo.admin |
237 |
logger of the web app. |
238 |
|
239 |
Please note the following: |
240 |
|
241 |
* As of Synnefo v0.7, by default the Django webapp logs to syslog, the |
242 |
dispatcher logs to /var/log/synnefo/dispatcher.log and the console, |
243 |
snf-admin logs to the console. |
244 |
* Different handlers can be set to different logging levels: |
245 |
for example, everything may appear to the console, but only INFO and higher |
246 |
may actually be stored in a longer-term logfile |
247 |
|
248 |
|
249 |
.. _shibboleth-auth: |
250 |
|
251 |
Authentication using Shibboleth |
252 |
=============================== |
253 |
|
254 |
Astakos can delegate user authentication to a Shibboleth federation. |
255 |
|
256 |
To setup shibboleth, install package:: |
257 |
|
258 |
apt-get install libapache2-mod-shib2 |
259 |
|
260 |
Change appropriately the configuration files in ``/etc/shibboleth``. |
261 |
|
262 |
Add in ``/etc/apache2/sites-available/synnefo-ssl``:: |
263 |
|
264 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
265 |
Alias /shibboleth-sp /usr/share/shibboleth |
266 |
|
267 |
<Location /im/login/shibboleth> |
268 |
AuthType shibboleth |
269 |
ShibRequireSession On |
270 |
ShibUseHeaders On |
271 |
require valid-user |
272 |
</Location> |
273 |
|
274 |
and before the line containing:: |
275 |
|
276 |
ProxyPass / http://localhost:8080/ retry=0 |
277 |
|
278 |
add:: |
279 |
|
280 |
ProxyPass /Shibboleth.sso ! |
281 |
|
282 |
Then, enable the shibboleth module:: |
283 |
|
284 |
a2enmod shib2 |
285 |
|
286 |
After passing through the apache module, the following tokens should be |
287 |
available at the destination:: |
288 |
|
289 |
eppn # eduPersonPrincipalName |
290 |
Shib-InetOrgPerson-givenName |
291 |
Shib-Person-surname |
292 |
Shib-Person-commonName |
293 |
Shib-InetOrgPerson-displayName |
294 |
Shib-EP-Affiliation |
295 |
Shib-Session-ID |
296 |
|
297 |
Finally, add 'shibboleth' in ``ASTAKOS_IM_MODULES`` list. The variable resides |
298 |
inside the file ``/etc/synnefo/20-snf-astakos-app-settings.conf`` |
299 |
|
300 |
|
301 |
Scaling up to multiple nodes |
302 |
============================ |
303 |
|
304 |
Here we will describe how to deploy all services, interconnected with each |
305 |
other, on multiple physical nodes. |
306 |
|
307 |
synnefo components |
308 |
------------------ |
309 |
|
310 |
You need to install the appropriate synnefo software components on each node, |
311 |
depending on its type, see :ref:`Architecture <cyclades-architecture>`. |
312 |
|
313 |
Please see the page of each synnefo software component for specific |
314 |
installation instructions, where applicable. |
315 |
|
316 |
Install the following synnefo components: |
317 |
|
318 |
Nodes of type :ref:`APISERVER <APISERVER_NODE>` |
319 |
Components |
320 |
:ref:`snf-common <snf-common>`, |
321 |
:ref:`snf-webproject <snf-webproject>`, |
322 |
:ref:`snf-cyclades-app <snf-cyclades-app>` |
323 |
Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>` |
324 |
Components |
325 |
:ref:`snf-common <snf-common>`, |
326 |
:ref:`snf-cyclades-gtools <snf-cyclades-gtools>` |
327 |
Nodes of type :ref:`LOGIC <LOGIC_NODE>` |
328 |
Components |
329 |
:ref:`snf-common <snf-common>`, |
330 |
:ref:`snf-webproject <snf-webproject>`, |
331 |
:ref:`snf-cyclades-app <snf-cyclades-app>`. |
332 |
|
333 |
RabbitMQ |
334 |
-------- |
335 |
|
336 |
RabbitMQ is used as a generic message broker for Cyclades. It should be |
337 |
installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high |
338 |
availability configuration as described here: |
339 |
|
340 |
http://www.rabbitmq.com/pacemaker.html |
341 |
|
342 |
The values set for the user and password must be mirrored in the ``RABBIT_*`` |
343 |
variables in your settings, as managed by :ref:`snf-common <snf-common>`. |
344 |
|
345 |
.. todo:: Document an active-active configuration based on the latest version |
346 |
of RabbitMQ. |
347 |
|
348 |
|
349 |
Upgrade Notes |
350 |
============= |
351 |
|
352 |
Cyclades upgrade notes |
353 |
---------------------- |
354 |
|
355 |
.. toctree:: |
356 |
:maxdepth: 2 |
357 |
|
358 |
cyclades-upgrade |
359 |
|
360 |
Changelog |
361 |
========= |