root / docs / admin-guide.rst @ 2e1e6844
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 |
========= |