root / docs / admin-guide.rst @ d2a9f85f
History | View | Annotate | Download (8.1 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: |
44 |
|
45 |
Manual activation |
46 |
~~~~~~~~~~~~~~~~~ |
47 |
|
48 |
You can manually activate a new user that has already signed up, by sending |
49 |
him/her an activation email. The email will contain an approriate activation |
50 |
link, which will complete the activation process if followed. You can send the |
51 |
email by running: |
52 |
|
53 |
.. code-block:: console |
54 |
|
55 |
$ snf-manage sendactivation <user ID or email> |
56 |
|
57 |
Be sure to have already setup your mail server and defined it in your synnefo |
58 |
settings, before running the command. |
59 |
|
60 |
Automatic activation |
61 |
~~~~~~~~~~~~~~~~~~~~ |
62 |
|
63 |
|
64 |
The "kamaki" API client |
65 |
----------------------- |
66 |
|
67 |
To upload, register or modify an image you will need the **kamaki** tool. |
68 |
Before proceeding make sure that it is configured properly. Verify that |
69 |
*image_url*, *storage_url*, and *token* are set as needed: |
70 |
|
71 |
.. code-block:: console |
72 |
|
73 |
$ kamaki config list |
74 |
|
75 |
To chage a setting use ``kamaki config set``: |
76 |
|
77 |
.. code-block:: console |
78 |
|
79 |
$ kamaki config set image_url https://cyclades.example.com/plankton |
80 |
$ kamaki config set storage_url https://pithos.example.com/v1 |
81 |
$ kamaki config set token ... |
82 |
|
83 |
Upload Image |
84 |
------------ |
85 |
|
86 |
As a shortcut, you can configure a default account and container that will be |
87 |
used by the ``kamaki store`` commands: |
88 |
|
89 |
.. code-block:: console |
90 |
|
91 |
$ kamaki config set storage_account images@example.com |
92 |
$ kamaki config set storage_container images |
93 |
|
94 |
If the container does not exist, you will have to create it before uploading |
95 |
any images: |
96 |
|
97 |
.. code-block:: console |
98 |
|
99 |
$ kamaki store create images |
100 |
|
101 |
You are now ready to upload an image. You can upload it with a Pithos+ client, |
102 |
or use kamaki directly: |
103 |
|
104 |
.. code-block:: console |
105 |
|
106 |
$ kamaki store upload ubuntu.iso |
107 |
|
108 |
You can use any Pithos+ client to verify that the image was uploaded correctly. |
109 |
The full Pithos URL for the previous example will be |
110 |
``pithos://images@example.com/images/ubuntu.iso``. |
111 |
|
112 |
|
113 |
Register Image |
114 |
-------------- |
115 |
|
116 |
To register an image you will need to use the full Pithos+ URL. To register as |
117 |
a public image the one from the previous example use: |
118 |
|
119 |
.. code-block:: console |
120 |
|
121 |
$ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso --public |
122 |
|
123 |
The ``--public`` flag is important, if missing the registered image will not |
124 |
be listed by ``kamaki glance list``. |
125 |
|
126 |
Use ``kamaki glance register`` with no arguments to see a list of available |
127 |
options. A more complete example would be the following: |
128 |
|
129 |
.. code-block:: console |
130 |
|
131 |
$ kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso \ |
132 |
--public --disk-format diskdump --property kernel=3.1.2 |
133 |
|
134 |
To verify that the image was registered successfully use: |
135 |
|
136 |
.. code-block:: console |
137 |
|
138 |
$ kamaki glance list -l |
139 |
|
140 |
|
141 |
Admin tool: snf-manage |
142 |
---------------------- |
143 |
|
144 |
``snf-manage`` is a tool used to perform various administrative tasks. It needs |
145 |
to be able to access the django database, so the following should be able to |
146 |
import the Django settings. |
147 |
|
148 |
Additionally, administrative tasks can be performed via the admin web interface |
149 |
located in /admin. Only users of type ADMIN can access the admin pages. To |
150 |
change the type of a user to ADMIN, snf-admin can be used: |
151 |
|
152 |
.. code-block:: console |
153 |
|
154 |
$ snf-manage user modify 42 --type ADMIN |
155 |
|
156 |
|
157 |
Adding Astakos "Terms of Use" |
158 |
----------------------------- |
159 |
|
160 |
Astakos supports versioned terms-of-use. First of all you need to create an |
161 |
html file that will contain your terms. For example, create the file |
162 |
``/usr/share/synnefo/sample-terms.html``, which contains the following: |
163 |
|
164 |
.. code-block:: console |
165 |
|
166 |
<h1>~okeanos terms</h1> |
167 |
|
168 |
These are the example terms for ~okeanos |
169 |
|
170 |
Then, add those terms-of-use with the snf-manage command: |
171 |
|
172 |
.. code-block:: console |
173 |
|
174 |
$ snf-manage addterms /usr/share/synnefo/sample-terms.html |
175 |
|
176 |
Your terms have been successfully added and you will see the corresponding link |
177 |
appearing in the Astakos web pages' footer. |
178 |
|
179 |
|
180 |
Reconciliation mechanism |
181 |
------------------------ |
182 |
|
183 |
On certain occasions, such as a Ganeti or RabbitMQ failure, the VM state in the |
184 |
system's database may differ from that in the Ganeti installation. The |
185 |
reconciliation process is designed to bring the system's database in sync with |
186 |
what Ganeti knows about each VM, and is able to detect the following three |
187 |
conditions: |
188 |
|
189 |
* Stale DB servers without corresponding Ganeti instances |
190 |
* Orphan Ganeti instances, without corresponding DB entries |
191 |
* Out-of-sync operstate for DB entries wrt to Ganeti instances |
192 |
|
193 |
The reconciliation mechanism runs as a management command, e.g., as follows: |
194 |
[PYTHONPATH needs to contain the parent of the synnefo Django project |
195 |
directory]: |
196 |
|
197 |
.. code-block:: console |
198 |
|
199 |
$ export PYTHONPATH=/srv:$PYTHONPATH |
200 |
$ snf-manage reconcile --detect-all -v 2 |
201 |
|
202 |
Please see ``snf-manage reconcile --help`` for all the details. |
203 |
|
204 |
The administrator can also trigger reconciliation of operating state manually, |
205 |
by issuing a Ganeti ``OP_INSTANCE_QUERY_DATA`` command on a Synnefo VM, using |
206 |
gnt-instance info. |
207 |
|
208 |
Logging |
209 |
------- |
210 |
|
211 |
Logging in Synnefo is using Python's logging module. The module is configured |
212 |
using dictionary configuration, whose format is described here: |
213 |
|
214 |
http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema |
215 |
|
216 |
Note that this is a feature of Python 2.7 that we have backported for use in |
217 |
Python 2.6. |
218 |
|
219 |
The logging configuration dictionary is defined in settings.d/00-logging.conf |
220 |
and is broken in 4 separate dictionaries: |
221 |
|
222 |
* LOGGING is the logging configuration used by the web app. By default all |
223 |
loggers fall back to the main 'synnefo' logger. The subloggers can be |
224 |
changed accordingly for finer logging control. e.g. To disable debug |
225 |
messages from the API set the level of 'synnefo.api' to 'INFO'. |
226 |
|
227 |
* DISPATCHER_LOGGING is the logging configuration of the logic/dispatcher.py |
228 |
command line tool. |
229 |
|
230 |
* SNFADMIN_LOGGING is the logging configuration of the snf-admin tool. |
231 |
Consider using matching configuration for snf-admin and the synnefo.admin |
232 |
logger of the web app. |
233 |
|
234 |
Please note the following: |
235 |
|
236 |
* As of Synnefo v0.7, by default the Django webapp logs to syslog, the |
237 |
dispatcher logs to /var/log/synnefo/dispatcher.log and the console, |
238 |
snf-admin logs to the console. |
239 |
* Different handlers can be set to different logging levels: |
240 |
for example, everything may appear to the console, but only INFO and higher |
241 |
may actually be stored in a longer-term logfile |
242 |
|
243 |
|
244 |
Scaling up to multiple nodes |
245 |
============================ |
246 |
|
247 |
Here we will describe how to deploy all services, interconnected with each |
248 |
other, on multiple physical nodes. For now, if you installed successfully using |
249 |
the quick installation guide and need more details, please refer to each |
250 |
component's own documentation. |
251 |
|
252 |
Upgrade Notes |
253 |
============= |
254 |
|
255 |
Cyclades upgrade notes |
256 |
---------------------- |
257 |
|
258 |
.. toctree:: |
259 |
:maxdepth: 2 |
260 |
|
261 |
cyclades-upgrade |
262 |
|
263 |
Changelog |
264 |
========= |