4 Kamaki is easy to install from source or as a package. Some ui features are optional and can be install separately. Kamaki behavior can be configured in the kamaki config file.
9 Kamaki interfaces rely on a list of configuration options. Be default, they are configured to communicate with the `Okeanos IaaS <http://okeanos.grnet.gr>`_.
11 .. note:: It is essential for users to get a configuration token (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
14 .. code-block:: console
17 Example 1.1: Set user token to myt0k3n==
19 $ kamaki config set token myt0k3n==
24 For installing any or all of the following, consult the `kamaki installation guide <installation.html#install-ansicolors>`_
27 * Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
28 * Can be switched on/off in kamaki configuration file: colors=on/off
29 * Has not been tested on non unix / linux based platforms
32 * For kamaki contributors only
33 * Allow unittests to run on kamaki.clients package
34 * Needs mock version 1.X or better
36 Any of the above features can be installed at any time before or after kamaki installation.
41 Kamaki comes with preset default values to all configuration options. All vital configuration options are set to use the okeanos.grnet.gr cloud services. User information is not included and should be provided either through the kamaki config command or by editing the configuration file.
43 Kamaki configuration options are vital for correct Kamaki behavior. An incorrect option may render some command groups dysfunctional. There are two ways of managing configuration options: edit the config file or use the kamaki config command.
48 Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory.
50 If a user needs to switch between different setups, Kamaki can explicitly load configuration files with the --config option:
52 .. code-block:: console
54 $ kamaki --config <custom_config_file_path> [other options]
56 Using many different configuration files for different cloud services is encouraged.
58 Modifying options at runtime
59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
61 All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
63 .. code-block:: console
65 $ kamaki file list -o global.account=anotheraccount -o global.token=aT0k3n==
67 will invoke *kamaki file list* with the specified options, but the initial global.account and global.token values will be restored to initial values afterwards.
69 .. note:: on-the-fly calls to file require users to explicetely provide the account uuid corresponding to this token. The account is actually the uuid field at the response of the following call::
71 $kamaki user authenticate aT0k3n==
76 Kamaki config command allows users to see and manage all configuration options.
79 lists all configuration options currently used by a Kamaki installation
81 * kamaki config get <group.option>
82 show the value of a specific configuration option. Options must be of the form group.option
84 * kamaki config set <group.option> <value>
85 set the group.option to value
87 * kamaki config delete <group.option>
88 delete a configuration option
90 The above commands cause option values to be permanently stored in the Kamaki configuration file.
92 Editing the configuration file
93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
95 The configuration file is a simple text file that can be created by the user.
97 A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example:
99 .. code-block:: console
101 $ kamaki config set token myT0k3N==
103 In the above example, if the kamaki configuration file does not exist, it will be created with all the default values plus the *global.token* option set to *myT0k3n==* value.
105 The configuration file is formatted so that it can be parsed by the python ConfigParser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example::
108 url=https://okeanos.grnet.gr/pithos
111 two configuration options are created: *file.url* and *file.token*. These values will be loaded at every future kamaki execution.
116 The [global] group is treated by kamaki as a generic group for arbitrary options, and it is used as a super-group for vital Kamaki options, namely token, url, cli. In case of conflict, the most specific options overrides the global ones.
118 * global.colors <on|off>
119 enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
121 * global.token <user authentication token>
123 * global.log_file <logfile full path>
124 set a custom location for kamaki logging. Default value is ~/.kamaki.log
126 * global.log_token <on|off>
127 allow kamaki to log user tokens
129 * global.log_data <on|off>
130 allow kamaki to log http data (by default, it logs only method, URL and headers)
132 * file.cli <UI command specifications for file>
133 a special package that is used to load storage commands to kamaki UIs. Don't touch this unless if you know what you are doing.
135 * file.url <OOS storage or Pithos+ service url>
136 the url of the OOS storage or Pithos+ service. Set to Okeanos.grnet.gr Pithos+ storage service by default. Users should set a different value if they need to use a different storage service.
139 it set, it overrides possible global.token option for file level commands
141 * compute.url <OOS compute or Cyclades service url>
142 the url of the OOS compute or Cyclades service. Set to Okeanos.grnet.gr Cyclades IaaS service by default. Users should set a different value if they need to use a different IaaS service.
144 * cyclades.cli <UI command specifications for cyclades>
145 a special package that is used to load cyclades commands to kamaki UIs. Don't touch this unless you know what you are doing.
147 * flavor.cli <UI command specifications for VM flavors>
148 a special package that is used to load cyclades VM flavor commands to kamaki UIs. Don't touch this unless you know what you are doing.
150 * network.cli <UI command specifications for virtual networks>
151 a special package that is used to load cyclades virtual network commands to kamaki UIs. Don't touch this unless you know what you are doing.
153 * image.url <Plankton image service url>
154 the url of the Plankton service. Set to Okeanos.grnet.gr Plankton service by default. Users should set a different value if they need to use a different service. Note that the *image compute* commands are depended on the compute.url instead.
156 * image.cli <UI command specifications for Plankton (and Compute) image service>
157 a special package that is used to load image-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
159 * user.url <Astakos authentication service url>
160 the url of the Astakos authentication service. Set to the Okeanos.grnet.gr Astakos service by default. Users should set a different value if they need to use a different service.
162 * user.cli <UI command specifications for Astakos authentication service>
163 a special package that is used to load astakos-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
165 * history.file <history file path>
166 the path of a simple file for inter-session kamaki history. Make sure kamaki is executed in a context where this file is accessible for reading and writing. Kamaki automatically creates the file if it doesn't exist
174 Kamaki log file path is set by the following command::
176 $ kamaki config set log_file <logfile path>
178 By default, kamaki logs at ~/.kamaki.log
180 When initialized, kamaki attempts to open one of these locations for writing, in the order presented above and uses the first accessible for appending logs. If the log_file option is set, kamaki prepends the value of this option to the logfile list, so the custom location will be the first one kamaki will attetmpt to log at.
182 Kamaki will not crush if the logging location is not accessible.
184 Richer connection logs
185 """"""""""""""""""""""
187 Kamaki logs down the http requests and responses in /var/log/kamaki/clients.log (make sure it is accessible). The request and response data and user authentication information is excluded from the logs be default. The former may render the logs unreadable and the later are sensitive information. Users my activate data and / or token logging my setting the global options log_data and log_token respectively::
189 $ kamaki config set log_data on
190 $ kamaki config set log_token on
192 Either or both of these options may be switched off either by setting them to ``off`` or by deleting them.
194 $ kamaki config set log_data off
195 $ kamaki config delete log_token
197 Set custom thread limit
198 """""""""""""""""""""""
200 Some operations (e.g. download and upload) may use threaded http connections for better performance. Kamaki.clients utilizes a sophisticated mechanism for dynamically adjusting the number of simultaneous threads running, but users may wish to enforce their own upper thread limit. In that case, the max_threads option may be set to the configuration file::
202 $ kamaki config set max_threads 3
204 If the value is not a positive integer, kamaki will ignore it and a warning message will be logged.
209 Kamaki contains a live test suite for the kamaki.clients API, where "live" means that the tests are performed against active services that up and running. The live test package is named "livetest", it is accessible as kamaki.clients.livetest and it is designed to check the actual relation between kamaki and synnefo services.
211 The livetest suite can be activated with the following option on the configuration file::
216 In most tests, livetest will run as long as an Astakos identity manager service is accessible and kamaki is set up to authenticate a valid token on this server.
218 In specific, a setup file needs at least the following mandatory settings in the configuration file:
220 * If authentication information is used for default kamaki clients::
223 url=<Astakos Identity Manager URL>
224 token=<A valid user token>
226 * else if this authentication information is only for testing add this under [livetest]::
228 user_url=<Astakos Identity Manager URL>
229 user_token=<A valid user token>
231 Each service tested in livetest might need some more options under the [livetest] label, as shown bellow:
233 * kamaki livetest astakos::
235 astakos_email = <The valid email of testing user>
236 astakos_name = <The exact "real" name of testing user>
237 astakos_username = <The username of the testing user>
238 astakos_uuid = <The valid unique user id of the testing user>
240 * kamaki livetest pithos::
242 astakos_uuid = <The valid unique user id of the testing user>
244 * kamaki livetest cyclades / image::
246 image_id = <A valid image id used for testing>
247 image_local_path = <The local path of the testing image>
248 image_details = <A text file containing testing image details in a python dict>
250 - example image.details content:
252 u'id': u'b3e68235-3abd-4d60-adfe-1379a4f8d3fe',
255 u'description': u'Debian 6.0.6 (Squeeze) Base System',
257 u'kernel': u'2.6.32',
259 u'osfamily': u'linux',
260 u'root_partition': u'1',
265 u'name': u'Debian Base',
267 u'status': u'ACTIVE',
268 u'created': u'2012-11-19T14:54:57+00:00',
269 u'updated': u'2012-11-19T15:29:51+00:00'
272 flavor_details = <A text file containing the testing images' flavor details in a python dict>
274 - example flavor.details content:
276 u'name': u'C1R1drbd',
279 u'SNF:disk_template': u'drbd',
284 After setup, kamaki can run all tests::
286 $ kamaki livetest all
288 a specific test (e.g. astakos)::
290 $ kamaki livetest astakos
292 or a specific method from a service (e.g. astakos authenticate)::
294 $ kamaki livetest astakos authenticate
296 The unit testing system
297 """""""""""""""""""""""
299 Kamaki container a set of finegrained unit tests for the kamaki.clients package. This set is not used when kamaki is running. Instead, it is aimed to developers who debug or extent the kamaki clients library. For more information, check the `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the `developers section <developers/extending-clients-api.html>`_.