Provided by: elektra-doc_0.7.1-1_all bug

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

       o   It is much more an agreement then a piece of software. Relation is
           99% to 1%.

       o   It is a simple and consistent API to help software developers
           programatically store and retrieve global and user-specific
           configuration parameters.

       o   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.

       o   API supports change notifications and multiple backends.

       o   It provides a unique namespace for all values. Anywhere, anytime,
           any program can preciselly access keys by their names. Security
           restrictions may obviously apply.

       o   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.

       o   It is designed to be easy to administrate with regular command line
           tools like cat, vi, cp, ls, ln. Its storage is 100% open.

       o   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.

       o   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.

       o   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

       o   Is NOT something that accesses SQL/relational databases.

       o   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.

       o   Is NOT an alternative to network information systems like LDAP or
           NIS. These are still required for networked environments.

       o   Is NOT a Webmin-like or other GUI tool to be used by end users.

       o   Is NOT an additional software layer to edit/generate existing
           configuration files.

       o   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.

       o   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:

       o   system/sw/XFree/InputDevice/.Mouse3/Driver: All keys under
           .Mouse3/* subtree won't be read by default.

       o   user:valeria/env/env2/.PATH: The $PATH environment variable won't
           be set when valeria login.

       o   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:

       o   system/users/nobody/uid: 99

       o   system/users/nobody/gid: 99

       o   system/users/nobody/gecos: Nobody

       o   system/users/nobody/home: /

       o   system/users/nobody/shell: /sbin/nologin

       o   system/users/nobody/password: *

       o   system/users/nobody/passwdChangeBefore: 0

       o   system/users/nobody/passwdChangeAfter: 99999

       o   system/users/nobody/passwdWarnBefore: 7

       o   system/users/nobody/passwdDisableAfter:

       o   system/users/nobody/passwdDisabledSince:

       o   system/users/nobody/passwdReserved:

       The environment variables I want set, when I log in, with their full
       key name:

       o   user:aviram/env/env1/JAVA_HOME:
           /usr/lib/jvm/java-1.4.1-ibm-1.4.1.0/jre

       o   user:aviram/env/env2/PATH: $PATH:~/bin:$JAVA_HOME/bin

       o   user:aviram/env/env2/PS1: \h:\w\$

       o   user:aviram/env/env3/PILOTRATE: 57600

       The entry in /etc/inittab that is responsible for starting X11 would
       look:

       o   system/init/x/runlevels: 5

       o   system/init/x/action: respawn

       o   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:

       o   system/sw/xorg/current/Layouts/Default
           Layout/Inputs/Keyboard0/CoreKeyboard:

       o   system/sw/xorg/current/Layouts/Default
           Layout/Inputs/Mouse0/CorePointer:

       o   system/sw/xorg/current/Layouts/Default
           Layout/Screens/Screen0/Absolute.x: 0

       o   system/sw/xorg/current/Layouts/Default
           Layout/Screens/Screen0/Absolute.y: 0

       o   system/sw/xorg/current/Layouts/Default
           Layout/Screens/Screen0/ScreenNumber: 0

       o   system/sw/xorg/current/Files/FontPath: unix/:7100

       o   system/sw/xorg/current/Files/RgbPath: /usr/X11R6/lib/X11/rgb

       o   system/sw/xorg/current/Devices/Videocard0/BoardName: Intel 740
           (generic)

       o   system/sw/xorg/current/Devices/Videocard0/Driver: i740

       o   system/sw/xorg/current/Devices/Videocard0/VendorName: Videocard
           vendor

       o   system/sw/xorg/current/InputDevices/Keyboard0/Driver: keyboard

       o   system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbLayout:
           us_intl

       o   system/sw/xorg/current/InputDevices/Keyboard0/Options/XkbModel:
           pc105

       o   system/sw/xorg/current/InputDevices/Mouse0/Driver: mouse

       o   system/sw/xorg/current/InputDevices/Mouse0/Options/Device:
           /dev/input/mice

       o   system/sw/xorg/current/InputDevices/Mouse0/Options/Emulate3Buttons:
           yes

       o   system/sw/xorg/current/InputDevices/Mouse0/Options/Protocol: IMPS/2

       o   system/sw/xorg/current/InputDevices/Mouse0/Options/ZAxisMapping: 4
           5

       o   system/sw/xorg/current/Monitors/Monitor0/DisplaySize.height: 230

       o   system/sw/xorg/current/Monitors/Monitor0/DisplaySize.width: 300

       o   system/sw/xorg/current/Monitors/Monitor0/HorizSync: 30.0 - 61.0

       o   system/sw/xorg/current/Monitors/Monitor0/ModelName: SyncMaster

       o   system/sw/xorg/current/Monitors/Monitor0/Options/dpms:

       o   system/sw/xorg/current/Monitors/Monitor0/VendorName: Monitor Vendor

       o   system/sw/xorg/current/Monitors/Monitor0/VertRefresh: 56.0 - 75.0

       o   system/sw/xorg/current/Monitors/.Monitor1/HorizSync: 30.0 - 61.0

       o   system/sw/xorg/current/Monitors/.Monitor1/ModelName: Impression

       o   system/sw/xorg/current/Monitors/.Monitor1/Options/dpms:

       o   system/sw/xorg/current/Monitors/.Monitor1/VendorName: Monitor
           Vendor

       o   system/sw/xorg/current/Monitors/.Monitor1/VertRefresh: 56.0 - 75.0

       o   system/sw/xorg/current/Screens/Screen0/DefaultDepth: 16

       o   system/sw/xorg/current/Screens/Screen0/Device: Videocard0

       o   system/sw/xorg/current/Screens/Screen0/Displays/00/Depth: 16

       o   system/sw/xorg/current/Screens/Screen0/Displays/00/Modes:
           1024x768,800x600,640x480

       o   system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.x: 0

       o   system/sw/xorg/current/Screens/Screen0/Displays/00/Viewport.y: 0

       o   system/sw/xorg/current/Screens/Screen0/Monitor: Monitor0

       o   system/sw/xorg/current/Modules/dbe:

       o   system/sw/xorg/current/Modules/dri:

       o   system/sw/xorg/current/Modules/extmod:

       o   system/sw/xorg/current/Modules/fbdevhw:

       o   system/sw/xorg/current/Modules/freetype:

       o   system/sw/xorg/current/Modules/glx:

       o   system/sw/xorg/current/Modules/record:

       o   system/sw/xorg/current/Modules/type1:

       o   system/sw/xorg/current/DRI/Group: 0

       o   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 (C) 2004 Avi Alkalay

NOTES

        1. Elektra presentation
           [set $man.base.url.for.relative.links]/elektra.sxi