Statistics
| Branch: | Tag: | Revision:

root / docs / admin-guide.rst @ dc9283a6

History | View | Annotate | Download (8.9 kB)

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