doc/elektra.5

   1 .\"     Title: elektra
   2 .\"    Author: Avi Alkalay <avi at unix.sh>
   3 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   4 .\"      Date: March 2004
   5 .\"    Manual:
   6 .\"    Source: Elektra Initiative
   7 .\"
   8 .TH "ELEKTRA" "5" "March 2004" "Elektra Initiative" ""
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 elektra \- A framework to store configuration atoms hierarchically
  15 .sp
  16 .it 1 an-trap
  17 .nr an-no-space-flag 1
  18 .nr an-break-flag 1
  19 .br
  20 Note
  21 .PP
  22 This section is provided for the sake of the openness of Elektra\&. You should not access the Elektra\'s key files directly\&. You should use the API or the
  23 \fBkdb\fR(1)
  24 command for that\&.
  25
  26 Elektra Key Storage Strategy.PP
  27 Elektra implements a very simple way to store the key\-value pairs\&. The value (and some metainfo) for each key is stored in a single file\&. The key name (and some of its context) is sufficient to find the file name that stores the value\&.
  28 .PP
  29 The
  30 \fIsystem/*\fR
  31 keys are stored under
  32 \fI/etc/kdb/\fR, and the
  33 \fIuser/*\fR
  34 keys can be found under each user\'s
  35 \fI$HOME/\&.kdb/\fR\&.
  36 .PP
  37 Here are some examples of key names, and where Elektra goes to look for them in the disk\&.
  38 .PP
  39 \fIsystem/sw/XFree86/screen0/driver\fR
  40 .RS 4
  41 Maps to:
  42 \fI/etc/kdb/system/sw/XFree86/screen0/driver\fR
  43 .RE
  44 .PP
  45 \fIuser/env/PATH\fR
  46 .RS 4
  47 Maps to:
  48 \fI~$USER/\&.kdb/user/env/PATH\fR
  49 .RE
  50 .PP
  51 \fIuser:luciana/env/PATH\fR
  52 .RS 4
  53 Maps to:
  54 \fI~luciana/\&.kdb/user/env/PATH\fR
  55 .RE
  56 .PP
  57 \fIsystem/mime\&.types/some\&.mime\fR
  58 .RS 4
  59 Maps to:
  60 \fI/etc/kdb/system/mime\&.types/some\&.mime\fR
  61 .RE
  62 .PP
  63 Some may think that one file per key will consume many filesystem i\-nodes\&. Actually, when not using Reiser4 filesystem, it may consume some more disk space, and it may also be not so efficient than reading one single text file, as KConfig does\&. But Elektra\'s nature lets applications load their keys on demand; so it is possible to avoid the read\-all\-use\-some approach\&. Writing updated keys back to disk is also more robust, because unchanged keys won\'t be touched, different from a single file approach, that must be entirelly rewritten\&.
  64 .PP
  65 Besides that, big applications (like Mozilla, Konqueror, KDE, Gnome) key gathering time is a very small part of what they have to do to start up\&. And the benefits of an homogeneous key database to the entire system are much bigger then these issues\&. Think about a common integration between everything, flexibility, security granularity and openness\&.
  66 XML, Storage Backends and Elektra.PP
  67 This document you are just reading was written in DocBook XML\&. XML is a wonderfull technology, but brings no value to this software\&. Two main goals of the Elektra Project are to be lightweight, and to be accessible by early boot stage programs like
  68 \fB/sbin/init\fR
  69 and the
  70 \fI/etc/rc\&.d\fR
  71 scripts\&.
  72 .PP
  73 XML parsing libraries are memory eaters, not so fast as we can expect, and they are usualy located under
  74 \fI/usr/lib\fR, which may be unavailable to these early boot stage needs\&.
  75 .PP
  76 Some discussions asked for a sort of plugin architecture to let user decide the format to store keys content\&. Well, the info that goes into the key file is not big deal as you\'ll see, and sometimes, too many options is bad business, and not the path for the Elektra Project\&.
  77 .PP
  78 So no XML, no plugin architecture, no sophistication\&. Lets keep it simple and generic\&. A very straight forward text based file format was defined to store a single key value\&.
  79 Key Files Format.PP
  80 Inside Elektra key database, each key is a file, and every file is a key\&. So most of the key\'s metainformation are actually its file attributes, as you can see in a regular
  81 \fBls\fR(1)
  82 command output\&.
  83 .PP
  84 So what needs to be stored inside the key file is the data type (binary or text), key comment and the actual data\&. The format of each key file is:
  85 .sp
  86 .RS 4
  87 .nf
  88 File Format Version
  89 Data Type
  90 As many lines of
  91 comments as we want (UTF\-8 encoded)
  92 <DATA>
  93 The data encoded as text
  94
  95 .fi
  96 .RE
  97 .PP
  98 So if we set the key
  99 \fIsystem/hw/eth0/driver\fR
 100 as type
 101 \fBString\fR
 102 and value "\fI3com\fR", and comment "\fIThe driver for my network interface\fR", we\'ll find the file
 103 \fI/etc/kdb/system/hw/eth0/driver\fR
 104 containing:
 105 .sp
 106 .RS 4
 107 .nf
 108 RG002
 109 40
 110 The driver for my network interface
 111 <DATA>
 112 3com
 113
 114 .fi
 115 .RE
 116 .PP
 117 Other example: setting
 118 \fIuser/tmp/proprietary\fR
 119 as
 120 \fBBinary\fR, and value "\fIA groovy data I want to hide\fR", and comment "\fIStay away from here\fR", you\'ll get in
 121 \fI~$USER/\&.kdb/user/tmp/proprietary\fR
 122 the following:
 123 .sp
 124 .RS 4
 125 .nf
 126 RG002
 127 20
 128 Stay away from here
 129 <DATA>
 130 41206772 6f6f7679 20646174 61204920 77616e74 20746f20 68696465
 131
 132 .fi
 133 .RE
 134 .PP
 135 The current data types are:
 136 .PP
 137 Between 20 and 39
 138 .RS 4
 139 Binary value\&. The data will be encoded into a text format\&. Today only type 20 is used, and means a raw stream of bytes with no special semantics to Elektra\&. The other values are reserved for future use; being treated still as binary values but possibly with some semantics to Elektra or a higher level application\&.
 140 .RE
 141 .PP
 142 40 up to 254
 143 .RS 4
 144 Text, UTF\-8 encoded\&. Values higher then 40 are reserved for future or application specific implementations of more abstract data types, like time/date, color, font, etc\&. But always represented as pure text that can be edited in any text editor like
 145 \fBvi\fR(1)\&.
 146 .RE
 147 .PP
 148 Types between 0 and 19 are used only internaly in the API, and will never appear into a key file\&. They are used to define meta keys as directory, link, etc\&.
 149 .SH "SEE ALSO"
 150 .PP
 151 \fBkdb\fR(1),
 152 \fBelektra\fR(7)
 153 .SH "AUTHOR"
 154 .PP
 155 \fBAvi Alkalay\fR <\&avi at unix\&.sh\&>
 156 .br
 157 Linux Market Developer, Senior IT and Software Architect, IBM Linux Impact Team :: \fIibm\&.com/linux\fR
 158 .sp -1n
 159 .IP "" 4
 160 Author.
 161 .SH "COPYRIGHT"
 162 Copyright \(co 2004 Avi Alkalay
 163 .br