Provided by: elektra-doc_0.7.1-1_all 
NAME
elektra - A framework to store configuration atoms hierarchically Library Linkage
Architecture.PP The Elektra library (libelektra.so) has 2 layers: public methods and
backend access, according to the following architecture (these pictures were taken from
the Elektra presentation[1]):
When using local backends such as the filesys backend, all key access happens in the
actual process space as bellow:
A remote daemon backend is also possible as noted bellow:
True Facts About Elektra
· It is much more an agreement then a piece of software. Relation is 99% to 1%.
· It is a simple and consistent API to help software developers programatically store
and retrieve global and user-specific configuration parameters.
· All key-value pairs are stored in clear-text files, UTF-8 encoded. All old charsets
are also supported, with automatic transparent conversion to and from UTF-8.
· API supports change notifications and multiple backends.
· It provides a unique namespace for all values. Anywhere, anytime, any program can
preciselly access keys by their names. Security restrictions may obviously apply.
· It is designed to be secure and lightweight, to let even early boot-stage programs
like /sbin/init to use it, instead of /etc/inittab file.
· It is designed to be easy to administrate with regular command line tools like cat,
vi, cp, ls, ln. Its storage is 100% open.
· It tries to set distribution-independent naming standards to store things like
hardware configuration, networking, user's session configuration, system's mime-types,
parameters for kernel modules, etc, that are generally stored under /etc.
· It requires existing software to be changed to use its API. This will substitute
hundreds of configuration-text-file parsing code, into clear Elektra's API key-value
access methods.
· It is POSIX compliant. If it doesn't compile and run easily on some POSIX system, it
should be easily modified to do so.
Elektra Is Not
· Is NOT something that accesses SQL/relational databases.
· Is NOT an OS service that can become unavailable and make system unusable. It is just
a library to access files according to a namespace.
· Is NOT an alternative to network information systems like LDAP or NIS. These are still
required for networked environments.
· Is NOT a Webmin-like or other GUI tool to be used by end users.
· Is NOT an additional software layer to edit/generate existing configuration files.
· Is NOT a "configuration system", because one can't be created by simply writing some
code. A configuration system is an ecosystem, and the Elektra Project tries to help
build one.
· It doesn't know a thing about the semantics of each data it stores.
Namespaces and Key Names.PP All keys are organized in a hierarchical tree with 2
Namespaces (subtrees) as showed by the picture:
system
Contains all subsystems and global application keys/configuration. Equivalent to files
under /etc directory.
user
The current user's keys. Equivalent to the dotfiles in a user's $HOME directory. These
keys are phisically stored under the owner user home directory. The many user:username
in the picture shows the full name of those trees. Read about user domains bellow for
more.
User Domains.PP Different from the system namespace, the user namespace is dynamic. For
example, the key user/env/PATH may have completely different values for users luciana and
valeria. In this example, if valeria wants to access this key at luciana's space, it
should refer to user:luciana/env/PATH. Access permissions apply.
User domains were implemented also to address situations when different user names ($USER)
have same UID. So a user key is stored in his home directory based on the user name, not
the UID. Inactive Keys.PP A great thing about text configuration files is that some
configuration items can be there as an example, but inactive or commented. Elektra
provides a very simple way to simulate this behavior: if the key name begins with a dot
(.), it is considered inactive or commented. In real world applications, the Elektra API
will ignore these keys by default, but the keys are still accessible if the developer
wants to.
These are some keys that have inactive subtrees:
· system/sw/XFree/InputDevice/.Mouse3/Driver: All keys under .Mouse3/* subtree won't be
read by default.
· user:valeria/env/env2/.PATH: The $PATH environment variable won't be set when valeria
login.
· system/users/.louis/uid: The entire .louis/* subtree is inactive. This is the same as
commenting the user entry from a configuration file.
See bellow more examples of inactive keys. Key Examples.PP Here are some valid key names,
and their values:
The Elektra keys of the combined /etc/passwd and /etc/shadow entry for user 'nobody' would
look like:
· system/users/nobody/uid: 99
· system/users/nobody/gid: 99
· system/users/nobody/gecos: Nobody
· system/users/nobody/home: /
· system/users/nobody/shell: /sbin/nologin
· system/users/nobody/password: *
· system/users/nobody/passwdChangeBefore: 0
· system/users/nobody/passwdChangeAfter: 99999
· system/users/nobody/passwdWarnBefore: 7
· system/users/nobody/passwdDisableAfter:
· system/users/nobody/passwdDisabledSince:
· system/users/nobody/passwdReserved:
The environment variables I want set, when I log in, with their full key name:
· user:aviram/env/env1/JAVA_HOME: /usr/lib/jvm/java-1.4.1-ibm-1.4.1.0/jre
· user:aviram/env/env2/PATH: $PATH:~/bin:$JAVA_HOME/bin
· user:aviram/env/env2/PS1: \h:\w\$
· user:aviram/env/env3/PILOTRATE: 57600
The entry in /etc/inittab that is responsible for starting X11 would look:
· system/init/x/runlevels: 5
· system/init/x/action: respawn
· system/init/x/process: /etc/X11/prefdm -nodaemon
The users database files and /etc/inittab were Elektrified to key-value pairs using the
users-convert and inittab-convert scripts included with the distribution.
An example of an elektrified /etc/X11/xorg.conf or /etc/X11/XF86Config:
· system/sw/xorg/current/Layouts/Default Layout/Inputs/Keyboard0/CoreKeyboard:
· system/sw/xorg/current/Layouts/Default Layout/Inputs/Mouse0/CorePointer:
· system/sw/xorg/current/Layouts/Default Layout/Screens/Screen0/Absolute.x: 0
· system/sw/xorg/current/Layouts/Default Layout/Screens/Screen0/Absolute.y: 0
· system/sw/xorg/current/Layouts/Default Layout/Screens/Screen0/ScreenNumber: 0
· system/sw/xorg/current/Files/FontPath: unix/:7100
· system/sw/xorg/current/Files/RgbPath: /usr/X11R6/lib/X11/rgb
· system/sw/xorg/current/Devices/Videocard0/BoardName: Intel 740 (generic)
· system/sw/xorg/current/Devices/Videocard0/Driver: i740
· system/sw/xorg/current/Devices/Videocard0/VendorName: Videocard vendor
· system/sw/xorg/current/InputDevices/Keyboard0/Driver: keyboard
· system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbLayout: us_intl
· system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbModel: pc105
· system/sw/xorg/current/InputDevices/Mouse0/Driver: mouse
· system/sw/xorg/current/InputDevices/Mouse0/Options/Device: /dev/input/mice
· system/sw/xorg/current/InputDevices/Mouse0/Options/Emulate3Buttons: yes
· system/sw/xorg/current/InputDevices/Mouse0/Options/Protocol: IMPS/2
· system/sw/xorg/current/InputDevices/Mouse0/Options/ZAxisMapping: 4 5
· system/sw/xorg/current/Monitors/Monitor0/DisplaySize.height: 230
· system/sw/xorg/current/Monitors/Monitor0/DisplaySize.width: 300
· system/sw/xorg/current/Monitors/Monitor0/HorizSync: 30.0 - 61.0
· system/sw/xorg/current/Monitors/Monitor0/ModelName: SyncMaster
· system/sw/xorg/current/Monitors/Monitor0/Options/dpms:
· system/sw/xorg/current/Monitors/Monitor0/VendorName: Monitor Vendor
· system/sw/xorg/current/Monitors/Monitor0/VertRefresh: 56.0 - 75.0
· system/sw/xorg/current/Monitors/.Monitor1/HorizSync: 30.0 - 61.0
· system/sw/xorg/current/Monitors/.Monitor1/ModelName: Impression
· system/sw/xorg/current/Monitors/.Monitor1/Options/dpms:
· system/sw/xorg/current/Monitors/.Monitor1/VendorName: Monitor Vendor
· system/sw/xorg/current/Monitors/.Monitor1/VertRefresh: 56.0 - 75.0
· system/sw/xorg/current/Screens/Screen0/DefaultDepth: 16
· system/sw/xorg/current/Screens/Screen0/Device: Videocard0
· system/sw/xorg/current/Screens/Screen0/Displays/00/Depth: 16
· system/sw/xorg/current/Screens/Screen0/Displays/00/Modes: 1024x768,800x600,640x480
· system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.x: 0
· system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.y: 0
· system/sw/xorg/current/Screens/Screen0/Monitor: Monitor0
· system/sw/xorg/current/Modules/dbe:
· system/sw/xorg/current/Modules/dri:
· system/sw/xorg/current/Modules/extmod:
· system/sw/xorg/current/Modules/fbdevhw:
· system/sw/xorg/current/Modules/freetype:
· system/sw/xorg/current/Modules/glx:
· system/sw/xorg/current/Modules/record:
· system/sw/xorg/current/Modules/type1:
· system/sw/xorg/current/DRI/Group: 0
· system/sw/xorg/current/DRI/Mode: 0666
Pay attention that the keys bellow system/sw/XFree/current/Monitor/.Monitor1 are inactive
because we have .Monitor1 as their parent. So unless special options are used when calling
the API, these keys will not be retrieved from the database.
Throughout this text you will see other examples of key names. Key Data Types.PP There
are only two types of data that can be stored:
Text
Handled as pure text. Regardeless of the charset being used, these values are always
stored as UTF-8. This ensures very strong internationalization and migration
capabilities, while keeping simplicity. If you don't want the Elektra framework to
convert your non-ASCII text to UTF-8 (not recomended), you should use the Binary data
format.
Binary
A stream of bytes, not necessarily text. It is recommended that you avoid using binary
values because UNIX system administrators tend to consider them as unmanageable
blackboxes. Anyway, the value will be encoded into pure text format based on
hexadecimal digits, for openness and ease of administration. This data type should
also be avoided because it is less efficient.
There are very good reasons why types like Integer, Time, Font, List, etc were not
implemented: Elektra was designed to be useful for any type of program, so having more
specific data types implicates in the definition of value limits, separators in the
storage format, etc, that may be good for some application and bad for other. So the
semantics of the data is handled by the application. A program or framework may define its
own special data handling methods using these essential basic types. See the keyGetType()
and keySetType() methods documentation in the kdb(3) man page to understand how to set
keys with your own data types.
There are more two types of keys:
Directory
It can't store a value, but, as a directory in a filesystem, it serves as a way to
group correlated keys.
Link
It is a link to another key. They work as symbolic links in the filesystem: when
trying to access them, you will actually access the key they point to. The API also
provides ways to access these special keys without dereferencing them.
Key Meta Data.PP Besides the key name and the value, each key has other attributes:
Owner's User and Group
This is a system's UID and GID equal to the ones found in regular files' attributes.
Access Permissions
Filesystem-like access permissions for user, group and others.
Modification, Access and Stat Times
Last time a key was modified, readed and stated (listed), respectively.
Key Comment
Pretty much as a configuration file comment. Not intended to be used in GUI
applications, because it isn't internationalizable.
Fine Grained Security Example.PP To show this metadata in action, this screen shows the
kdb command listing keys and their attributes related to user nobody.
bash$ kdb ls -Rlv system/users/nobody
-rw-r--r-- root root 17 Mar 31 09:07 system/users/nobody/uid=99
-rw-r--r-- root root 17 Mar 31 09:07 system/users/nobody/gid=99
-rw-r--r-- root root 21 Mar 31 09:07 system/users/nobody/gecos=Nobody
-rw-r--r-- root root 16 Mar 31 09:07 system/users/nobody/home=/
-rw-r--r-- root root 28 Mar 31 09:07 system/users/nobody/shell=/sbin/nologin
-rw------- root root 16 Mar 31 09:07 system/users/nobody/password
-rw------- root root 16 Mar 31 09:07 system/users/nobody/passwdChangeBefore
-rw------- root root 20 Mar 31 09:07 system/users/nobody/passwdChangeAfter
-rw------- root root 16 Mar 31 09:07 system/users/nobody/passwdWarnBefore
-rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdDisableAfter
-rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdDisabledSince
-rw------- root root 15 Mar 31 09:07 system/users/nobody/passwdReserved
We ran the kdb command without super-user credentials, asking for long (-l), recursive
(-R) listing, and to show each key value (-v). But (since we are) regular user, we don't
have permission to see the values of the system/users/nobody/passwd* fields.
The users database files were elektrified to key-value pairs using the users-convert
script included with the distribution. ExamplesSetting Keys.PP bash$kdb set -c "My first
key" user/example/key "Some nice value"
bash$kdb set user:luciana/example/key -- "Some - nice - value with dashes"
bash#KDB_ROOT=user:http/sw/httpd kdb set -u nobody -g http key "Some value"
bash$kdb set -b image.png -t bin user/example/binaryKey
bash$kdb set -b file.txt user/example/regularKey
bash#kdb set -t link system/sw/XFree/current system/sw/XFree/handmade Getting Keys.PP
bash$KDB_ROOT=user/example kdb get some/key/name
bash$eval `kdb get -s user/env/env1/PS1`
bash$KDB_BACKEND=gconf kdb get user/sw/gnome-terminal/global/active_encodings Listing.PP
bash$kdb ls -laR user:valeria
bash$kdb ls -lR system/sw/xorg/current
bash$KDB_ROOT=system/sw kdb ls -lR xorg
bash$KDB_BACKEND=fstab kdb ls -Rv system/filesystems
bash$eval `kdb ls -Rvs user/env/env2` Miscelaneous.PP bash#kdb ln system/sw/xorg/handmade
system/sw/xorg/current
bash#kdb mv system/sw/xorg/current system/sw/xorg/old
bash#kdb rm system/inittab/rc4
bash$KDB_BACKEND=gconf kdb rm user/gconfKey XML Import and Export.PP bash#kdb export
user/sw/app | sed -e 's|/app/|/app2/|g' | kdb import
bash#KDB_ROOT=system/sw kdb export myapp > myappconf.xml
bash#kdb import myappconf.xml
bash$KDB_BACKEND=gconf kdb export user/sw
SEE ALSO
kdb(1), elektra(5)
AUTHOR
Avi Alkalay <avi at unix.sh>
Linux Market Developer, Senior IT and Software Architect, IBM Linux Impact Team ::
ibm.com/linux
Author.
COPYRIGHT
Copyright © 2004 Avi Alkalay
NOTES
1. Elektra presentation
[set $man.base.url.for.relative.links]/elektra.sxi