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