1ELEKTRA(7) ELEKTRA(7)
2
6 elektra - A framework to store configuration atoms hierarchically
7 Library Linkage Architecture.PP The Elektra library (libelektra.so) has
8 2 layers: public methods and backend access, according to the following
9 architecture (these pictures were taken from the Elektra
10 presentation[1]):
11 When using local backends such as the filesys backend, all key access
13 happens in the actual process space as bellow:
14 A remote daemon backend is also possible as noted bellow:
16 True Facts About Elektra
18 · It is much more an agreement then a piece of software. Relation is
20 99% to 1%.
21 · It is a simple and consistent API to help software developers
23 programatically store and retrieve global and user-specific
24 configuration parameters.
25 · All key-value pairs are stored in clear-text files, UTF-8 encoded.
27 All old charsets are also supported, with automatic transparent
28 conversion to and from UTF-8.
29 · API supports change notifications and multiple backends.
31 · It provides a unique namespace for all values. Anywhere, anytime,
33 any program can preciselly access keys by their names. Security
34 restrictions may obviously apply.
35 · It is designed to be secure and lightweight, to let even early
37 boot-stage programs like /sbin/init to use it, instead of
38 /etc/inittab file.
39 · It is designed to be easy to administrate with regular command line
41 tools like cat, vi, cp, ls, ln. Its storage is 100% open.
42 · It tries to set distribution-independent naming standards to store
44 things like hardware configuration, networking, user´s session
45 configuration, system´s mime-types, parameters for kernel modules,
46 etc, that are generally stored under /etc.
47 · It requires existing software to be changed to use its API. This
49 will substitute hundreds of configuration-text-file parsing code,
50 into clear Elektra´s API key-value access methods.
51 · It is POSIX compliant. If it doesn´t compile and run easily on some
53 POSIX system, it should be easily modified to do so.
54 Elektra Is Not
55 · Is NOT something that accesses SQL/relational databases.
57 · Is NOT an OS service that can become unavailable and make system
59 unusable. It is just a library to access files according to a
60 namespace.
61 · Is NOT an alternative to network information systems like LDAP or
63 NIS. These are still required for networked environments.
64 · Is NOT a Webmin-like or other GUI tool to be used by end users.
66 · Is NOT an additional software layer to edit/generate existing
68 configuration files.
69 · Is NOT a "configuration system", because one can´t be created by
71 simply writing some code. A configuration system is an ecosystem,
72 and the Elektra Project tries to help build one.
73 · It doesn´t know a thing about the semantics of each data it stores.
75 Namespaces and Key Names.PP All keys are organized in a hierarchical
76 tree with 2 Namespaces (subtrees) as showed by the picture:
77 system
79 Contains all subsystems and global application keys/configuration.
80 Equivalent to files under /etc directory.
81 user
83 The current user´s keys. Equivalent to the dotfiles in a user´s
84 $HOME directory. These keys are phisically stored under the owner
85 user home directory. The many user:username in the picture shows
86 the full name of those trees. Read about user domains bellow for
87 more.
88 User Domains.PP Different from the system namespace, the user namespace
89 is dynamic. For example, the key user/env/PATH may have completely
90 different values for users luciana and valeria. In this example, if
91 valeria wants to access this key at luciana´s space, it should refer to
92 user:luciana/env/PATH. Access permissions apply.
93 User domains were implemented also to address situations when different
95 user names ($USER) have same UID. So a user key is stored in his home
96 directory based on the user name, not the UID. Inactive Keys.PP A
97 great thing about text configuration files is that some configuration
98 items can be there as an example, but inactive or commented. Elektra
99 provides a very simple way to simulate this behavior: if the key name
100 begins with a dot (.), it is considered inactive or commented. In real
101 world applications, the Elektra API will ignore these keys by default,
102 but the keys are still accessible if the developer wants to.
103 These are some keys that have inactive subtrees:
105 · system/sw/XFree/InputDevice/.Mouse3/Driver: All keys under
107 .Mouse3/* subtree won´t be read by default.
108 · user:valeria/env/env2/.PATH: The $PATH environment variable won´t
110 be set when valeria login.
111 · system/users/.louis/uid: The entire .louis/* subtree is inactive.
113 This is the same as commenting the user entry from a configuration
114 file.
115 See bellow more examples of inactive keys. Key Examples.PP Here are
117 some valid key names, and their values:
118 The Elektra keys of the combined /etc/passwd and /etc/shadow entry for
120 user ´nobody´ would look like:
121 · system/users/nobody/uid: 99
123 · system/users/nobody/gid: 99
125 · system/users/nobody/gecos: Nobody
127 · system/users/nobody/home: /
129 · system/users/nobody/shell: /sbin/nologin
131 · system/users/nobody/password: *
133 · system/users/nobody/passwdChangeBefore: 0
135 · system/users/nobody/passwdChangeAfter: 99999
137 · system/users/nobody/passwdWarnBefore: 7
139 · system/users/nobody/passwdDisableAfter:
141 · system/users/nobody/passwdDisabledSince:
143 · system/users/nobody/passwdReserved:
145 The environment variables I want set, when I log in, with their full
147 key name:
148 · user:aviram/env/env1/JAVA_HOME:
150 /usr/lib/jvm/java-1.4.1-ibm-1.4.1.0/jre
151 · user:aviram/env/env2/PATH: $PATH:~/bin:$JAVA_HOME/bin
153 · user:aviram/env/env2/PS1: \h:\w\$
155 · user:aviram/env/env3/PILOTRATE: 57600
157 The entry in /etc/inittab that is responsible for starting X11 would
159 look:
160 · system/init/x/runlevels: 5
162 · system/init/x/action: respawn
164 · system/init/x/process: /etc/X11/prefdm -nodaemon
166 The users database files and /etc/inittab were Elektrified to key-value
168 pairs using the users-convert and inittab-convert scripts included with
169 the distribution.
170 An example of an elektrified /etc/X11/xorg.conf or /etc/X11/XF86Config:
172 · system/sw/xorg/current/Layouts/Default
174 Layout/Inputs/Keyboard0/CoreKeyboard:
175 · system/sw/xorg/current/Layouts/Default
177 Layout/Inputs/Mouse0/CorePointer:
178 · system/sw/xorg/current/Layouts/Default
180 Layout/Screens/Screen0/Absolute.x: 0
181 · system/sw/xorg/current/Layouts/Default
183 Layout/Screens/Screen0/Absolute.y: 0
184 · system/sw/xorg/current/Layouts/Default
186 Layout/Screens/Screen0/ScreenNumber: 0
187 · system/sw/xorg/current/Files/FontPath: unix/:7100
189 · system/sw/xorg/current/Files/RgbPath: /usr/X11R6/lib/X11/rgb
191 · system/sw/xorg/current/Devices/Videocard0/BoardName: Intel 740
193 (generic)
194 · system/sw/xorg/current/Devices/Videocard0/Driver: i740
196 · system/sw/xorg/current/Devices/Videocard0/VendorName: Videocard
198 vendor
199 · system/sw/xorg/current/InputDevices/Keyboard0/Driver: keyboard
201 · system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbLayout:
203 us_intl
204 · system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbModel:
206 pc105
207 · system/sw/xorg/current/InputDevices/Mouse0/Driver: mouse
209 · system/sw/xorg/current/InputDevices/Mouse0/Options/Device:
211 /dev/input/mice
212 · system/sw/xorg/current/InputDevices/Mouse0/Options/Emulate3Buttons:
214 yes
215 · system/sw/xorg/current/InputDevices/Mouse0/Options/Protocol: IMPS/2
217 · system/sw/xorg/current/InputDevices/Mouse0/Options/ZAxisMapping: 4
219 5
220 · system/sw/xorg/current/Monitors/Monitor0/DisplaySize.height: 230
222 · system/sw/xorg/current/Monitors/Monitor0/DisplaySize.width: 300
224 · system/sw/xorg/current/Monitors/Monitor0/HorizSync: 30.0 - 61.0
226 · system/sw/xorg/current/Monitors/Monitor0/ModelName: SyncMaster
228 · system/sw/xorg/current/Monitors/Monitor0/Options/dpms:
230 · system/sw/xorg/current/Monitors/Monitor0/VendorName: Monitor Vendor
232 · system/sw/xorg/current/Monitors/Monitor0/VertRefresh: 56.0 - 75.0
234 · system/sw/xorg/current/Monitors/.Monitor1/HorizSync: 30.0 - 61.0
236 · system/sw/xorg/current/Monitors/.Monitor1/ModelName: Impression
238 · system/sw/xorg/current/Monitors/.Monitor1/Options/dpms:
240 · system/sw/xorg/current/Monitors/.Monitor1/VendorName: Monitor
242 Vendor
243 · system/sw/xorg/current/Monitors/.Monitor1/VertRefresh: 56.0 - 75.0
245 · system/sw/xorg/current/Screens/Screen0/DefaultDepth: 16
247 · system/sw/xorg/current/Screens/Screen0/Device: Videocard0
249 · system/sw/xorg/current/Screens/Screen0/Displays/00/Depth: 16
251 · system/sw/xorg/current/Screens/Screen0/Displays/00/Modes:
253 1024x768,800x600,640x480
254 · system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.x: 0
256 · system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.y: 0
258 · system/sw/xorg/current/Screens/Screen0/Monitor: Monitor0
260 · system/sw/xorg/current/Modules/dbe:
262 · system/sw/xorg/current/Modules/dri:
264 · system/sw/xorg/current/Modules/extmod:
266 · system/sw/xorg/current/Modules/fbdevhw:
268 · system/sw/xorg/current/Modules/freetype:
270 · system/sw/xorg/current/Modules/glx:
272 · system/sw/xorg/current/Modules/record:
274 · system/sw/xorg/current/Modules/type1:
276 · system/sw/xorg/current/DRI/Group: 0
278 · system/sw/xorg/current/DRI/Mode: 0666
280 Pay attention that the keys bellow
282 system/sw/XFree/current/Monitor/.Monitor1 are inactive because we have
283 .Monitor1 as their parent. So unless special options are used when
284 calling the API, these keys will not be retrieved from the database.
285 Throughout this text you will see other examples of key names. Key
287 Data Types.PP There are only two types of data that can be stored:
288 Text
290 Handled as pure text. Regardeless of the charset being used, these
291 values are always stored as UTF-8. This ensures very strong
292 internationalization and migration capabilities, while keeping
293 simplicity. If you don´t want the Elektra framework to convert your
294 non-ASCII text to UTF-8 (not recomended), you should use the Binary
295 data format.
296 Binary
298 A stream of bytes, not necessarily text. It is recommended that you
299 avoid using binary values because UNIX system administrators tend
300 to consider them as unmanageable blackboxes. Anyway, the value will
301 be encoded into pure text format based on hexadecimal digits, for
302 openness and ease of administration. This data type should also be
303 avoided because it is less efficient.
304 There are very good reasons why types like Integer, Time, Font, List,
306 etc were not implemented: Elektra was designed to be usefull for any
307 type of program, so having more specific data types implicates in the
308 definition of value limits, separators in the storage format, etc, that
309 may be good for some application and bad for other. So the semantics of
310 the data is handled by the application. A program or framework may
311 define its own special data handling methods using these essential
312 basic types. See the keyGetType() and keySetType() methods
313 documentation in the kdb(3) man page to understand how to set keys with
314 your own data types.
315 There are more two types of keys:
317 Directory
319 It can´t store a value, but, as a directory in a filesystem, it
320 serves as a way to group correlated keys.
321 Link
323 It is a link to another key. They work as symbolic links in the
324 filesystem: when trying to access them, you will actually access
325 the key they point to. The API also provides ways to access these
326 special keys without dereferencing them.
327 Key Meta Data.PP Besides the key name and the value, each key has other
328 attributes:
329 Owner´s User and Group
331 This is a system´s UID and GID equal to the ones found in regular
332 files´ attributes.
333 Access Permissions
335 Filesystem-like access permissions for user, group and others.
336 Modification, Access and Stat Times
338 Last time a key was modified, readed and stated (listed),
339 respectively.
340 Key Comment
342 Pretty much as a configuration file comment. Not intended to be
343 used in GUI applications, because it isn´t internationalizable.
344 Fine Grained Security Example.PP To show this metadata in action, this
345 screen shows the kdb command listing keys and their attributes related
346 to user nobody.
347 bash$ kdb ls -Rlv system/users/nobody
349 -rw-r--r-- root root 17 Mar 31 09:07 system/users/nobody/uid=99
350 -rw-r--r-- root root 17 Mar 31 09:07 system/users/nobody/gid=99
351 -rw-r--r-- root root 21 Mar 31 09:07 system/users/nobody/gecos=Nobody
352 -rw-r--r-- root root 16 Mar 31 09:07 system/users/nobody/home=/
353 -rw-r--r-- root root 28 Mar 31 09:07 system/users/nobody/shell=/sbin/nologin
354 -rw------- root root 16 Mar 31 09:07 system/users/nobody/password
355 -rw------- root root 16 Mar 31 09:07 system/users/nobody/passwdChangeBefore
356 -rw------- root root 20 Mar 31 09:07 system/users/nobody/passwdChangeAfter
357 -rw------- root root 16 Mar 31 09:07 system/users/nobody/passwdWarnBefore
358 -rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdDisableAfter
359 -rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdDisabledSince
360 -rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdReserved
361 We ran the kdb command without super-user credentials, asking for long
364 (-l), recursive (-R) listing, and to show each key value (-v). But
365 (since we are) regular user, we don´t have permission to see the values
366 of the system/users/nobody/passwd* fields.
367 The users database files were elektrified to key-value pairs using the
369 users-convert script included with the distribution. ExamplesSetting
370 Keys.PP bash$kdb set -c "My first key" user/example/key "Some nice
371 value"
372 bash$kdb set user:luciana/example/key -- "Some - nice - value with
374 dashes"
375 bash#KDB_ROOT=user:http/sw/httpd kdb set -u nobody -g http key "Some
377 value"
378 bash$kdb set -b image.png -t bin user/example/binaryKey
380 bash$kdb set -b file.txt user/example/regularKey
382 bash#kdb set -t link system/sw/XFree/current system/sw/XFree/handmade
384 Getting Keys.PP bash$KDB_ROOT=user/example kdb get some/key/name
385 bash$eval `kdb get -s user/env/env1/PS1`
387 bash$KDB_BACKEND=gconf kdb get
389 user/sw/gnome-terminal/global/active_encodings Listing.PP bash$kdb ls
390 -laR user:valeria
391 bash$kdb ls -lR system/sw/xorg/current
393 bash$KDB_ROOT=system/sw kdb ls -lR xorg
395 bash$KDB_BACKEND=fstab kdb ls -Rv system/filesystems
397 bash$eval `kdb ls -Rvs user/env/env2` Miscelaneous.PP bash#kdb ln
399 system/sw/xorg/handmade system/sw/xorg/current
400 bash#kdb mv system/sw/xorg/current system/sw/xorg/old
402 bash#kdb rm system/inittab/rc4
404 bash$KDB_BACKEND=gconf kdb rm user/gconfKey XML Import and Export.PP
406 bash#kdb export user/sw/app | sed -e ´s|/app/|/app2/|g´ | kdb import
407 bash#KDB_ROOT=system/sw kdb export myapp > myappconf.xml
409 bash#kdb import myappconf.xml
411 bash$KDB_BACKEND=gconf kdb export user/sw
413
415 kdb(1), elektra(5)
416
418 Avi Alkalay <avi at unix.sh>
419 Linux Market Developer, Senior IT and Software Architect, IBM Linux
420 Impact Team :: ibm.com/linux
421 Author.
422
424 Copyright © 2004 Avi Alkalay
425
427 1. Elektra presentation
428 elektra.sxi
429Elektra Initiative March 2004 ELEKTRA(7)