{\itshape Elektra serves as a universal and secure framework to access configuration parameters in a global, hierarchical key database.}



Elektra provides a mature, consistent and easily comprehensible A\+P\+I. Its modularity effectively avoids code duplication across applications and tools regarding configuration tasks. Elektra abstracts from cross-\/platform-\/related issues and allows applications to be aware of other applications' configurations, leveraging easy application integration.

Elektra consists of three parts\+:


\begin{DoxyEnumerate}
\item {\itshape Lib\+Elektra} is a modular configuration access toolkit to construct and integrate applications into a global, hierarchical key database. The building blocks are\+:
\begin{DoxyItemize}
\item language bindings (inclusive high-\/level interfaces)
\item Gen\+Elektra, the code generator for type-\/safe bindings
\item plugins for configuration access behaviour and validation
\end{DoxyItemize}
\item {\itshape Spec\+Elektra} is a configuration specification language that is easy to use and self-\/contained in the same key database (i.\+e. written in any of the configuration file formats Elektra supports).
\item Tools on top of Lib\+Elektra for administrators, such as C\+L\+I tools and G\+U\+Is.
\end{DoxyEnumerate}

To highlight a few concrete things about Elektra, configuration data can come from any data source, but usually comes from configuration files that are \hyperlink{md_doc_help_elektra-mounting_doc_help_elektra-mounting_md}{\+\_\+mounted\+\_\+} into Elektra similar to mounting a file system. As Elektra is a plugin based framework, there are a lot of {\itshape storage plugins} that support various configuration formats like ini, json, xml, etc. However, there's a lot more to discover like executing scripts ({\ttfamily python}, {\ttfamily lua} or {\ttfamily shell}) when a configuration value changes, or, enhanced validation plugins that won't allow corrupted configuration to reach your application.

As an application developer you get instant access to various configuration formats and the ability to fallback to a default configuration without having to deal with this on your own. As an administrator you can choose your favourite configuration format and {\itshape mount} this configuration for the application. This features easy application integration as any application using Elektra can access any {\itshape mounted} configuration. You can even {\itshape mount} {\ttfamily /etc} files such as {\ttfamily hosts} or {\ttfamily fstab}, so that there is no need to configure the same data twice in different files.

In case you're worried about linking to such a powerful library. The core is a small library implemented in C, works cross-\/platform, and does not need any external dependencies. There are bindings for other languages in case C is too low-\/level for you.

\hyperlink{doc_WHY_md}{Why should I use Elektra?}

\subsection*{Contact}

Do not hesitate to ask any question on \href{https://github.com/ElektraInitiative/libelektra/issues}{\tt Git\+Hub issue tracker}, \href{https://lists.sourceforge.net/lists/listinfo/registry-list}{\tt Mailing List} or directly to one of the authors.

\subsection*{Quickstart}

If you want to use Elektra for your application, \hyperlink{doc_tutorials_application-integration_md}{read the application integration tutorial}.

\subsubsection*{Installation}

The preferred way to install Elektra is by using packages provided for your distribution. On Debian/\+Ubuntu, this can be done by running the following command\+:

```bash sudo apt-\/get install elektra-\/bin libelektra-\/dev ```

This will install the Elektra tools as well as everything needed to develop with Elektra.

If you're not running Debian/\+Ubuntu, check out the \href{#packages}{\tt package list}, \href{#download}{\tt download elektra directly} or \href{#compiling}{\tt compile it yourself}.

It is preferable to use a recent version\+: They contain many bug fixes and additional features. See \hyperlink{doc_INSTALL_md}{I\+N\+S\+T\+A\+L\+L} for other ways to install Elektra.

\subsubsection*{Usage}

Now that we have Elektra installed, we can start using the \hyperlink{md_doc_help_kdb_doc_help_kdb_md}{kdb command} and the qt-\/gui.

Here a small demo\+:

\href{https://asciinema.org/a/67xubv7tfkpu2434cx3aibjby}{\tt !\mbox{[}asciicast\mbox{]}(https\+://asciinema.\+org/a/67xubv7tfkpu2434cx3aibjby.\+png)}

For import/export/mount formats see \hyperlink{md_src_plugins_README_src_plugins_README_md}{Plugins}. For information about elektrified environment variables, see \hyperlink{md_src_libs_getenv_README_src_libs_getenv_README_md}{/src/libgetenv/\+R\+E\+A\+D\+M\+E.md}

\subsubsection*{Documentation}

To get an idea of Elektra, you can take a look at the \href{http://www.libelektra.org/ftp/elektra/presentations/2016/FOSDEM/fosdem.odp}{\tt presentation}.

The full documentation, including \href{http://libelektra.org/blob/master/doc/tutorials/}{\tt tutorials}, \hyperlink{md_doc_help_elektra-glossary_doc_help_elektra-glossary_md}{glossary}, and \hyperlink{md_doc_help_elektra-introduction_doc_help_elektra-introduction_md}{concepts and man pages} is available in the Git\+Hub repository.

You can read the documentation for the kdb tool, either


\begin{DoxyItemize}
\item http\+://libelektra.org/blob/master/doc/help/kdb.\+md \char`\"{}on Git\+Hub\char`\"{}
\item \href{http://doc.libelektra.org/api/latest/html/md_doc_help_kdb.html}{\tt in the A\+P\+I docu}
\item by using {\ttfamily kdb -\/-\/help} or {\ttfamily kdb help $<$command$>$}
\item by using {\ttfamily man kdb}
\end{DoxyItemize}

\subsection*{Goals}


\begin{DoxyItemize}
\item Make it trivial for applications and administrators to access any configuration
\item Postpone some decisions from programmers to
\item Make configuration storage more safe\+: avoid that applications receive wrong or unexpected values that could lead to undefined behaviour.
\item Allow software to be better integrated on configuration level maintainers/administrators, e.\+g. which syntax and the location of configuration files.
\item Reduce rank growth of configuration parsers in our ecosystem, but foster well maintained plugins instead.
\end{DoxyItemize}

And in terms of quality, we want\+:


\begin{DoxyEnumerate}
\item Simplicity (make configuration tasks simple),
\item Robustness (no undefined behaviour of applications), and
\item Extensibility (gain control over configuration access)
\end{DoxyEnumerate}

\hyperlink{doc_GOALS_md}{Read more about the goals of Elektra}

\subsection*{Facts and Features}


\begin{DoxyItemize}
\item Elektra uses the B\+S\+D licence.
\item Elektra implements an \href{http://doc.libelektra.org/api/latest/html/}{\tt A\+P\+I} to fully access a global key database.
\item Elektra can be thought of a virtual file system for configuration.
\item Elektra supports mounting of existing configuration files into the global key database.
\item Elektra has dozens of \hyperlink{md_src_plugins_README_src_plugins_README_md}{Plugins} that make it possible to have a tiny core, but still support many features, including\+:
\begin{DoxyItemize}
\item Elektra can import and export configuration files in any \hyperlink{md_src_plugins_README_src_plugins_README_md}{supported format}.
\item Elektra is able to log and notify other software on any configuration changes, e.\+g., using \hyperlink{md_src_plugins_dbus_README_src_plugins_dbus_README_md}{Dbus} and \hyperlink{md_src_plugins_journald_README_src_plugins_journald_README_md}{Journald}.
\item Elektra can improve robustness by rejecting invalid configuration via \hyperlink{md_src_plugins_type_README_src_plugins_type_README_md}{type checking}, \hyperlink{md_src_plugins_validation_README_src_plugins_validation_README_md}{regex} and more.
\item Elektra provides different mechanisms to \hyperlink{md_src_plugins_resolver_README_src_plugins_resolver_README_md}{locate configuration files}.
\item Elektra supports different ways to \hyperlink{md_src_plugins_ccode_README_src_plugins_ccode_README_md}{escape} and \hyperlink{md_src_plugins_iconv_README_src_plugins_iconv_README_md}{encode} content of configuration files.
\end{DoxyItemize}
\item Elektra is multi-\/process safe and can be used in multi-\/threaded programs.
\item Elektra (except for some \hyperlink{md_src_plugins_README_src_plugins_README_md}{plugins}) is portable and completely written in Ansi-\/\+C99.
\item Elektra (except for some \hyperlink{md_src_plugins_README_src_plugins_README_md}{plugins}) has no external dependency.
\item Elektra is suitable for embedded systems and early boot stage programs.
\item Elektra uses simple key/value pairs that include metadata for any other information.
\item Elektra provides many powerful Bindings to avoid low-\/level access code.
\item Elektra provides powerful Code Generation Techniques for high-\/level configuration access.
\end{DoxyItemize}

\subsection*{News}


\begin{DoxyItemize}
\item \href{http://doc.libelektra.org/news/9c9247ee-ee9c-4f4a-a68e-76959def9b82.html}{\tt 29 Apr 2016 0.\+8.\+16} stability improvements
\item \href{http://doc.libelektra.org/news/1ab4a560-c286-46d2-a058-1a8e7e208fe8.html}{\tt 16 Feb 2016 0.\+8.\+15} lib split, improved mount
\item \href{http://doc.libelektra.org/news/519cbfac-6db5-4594-8a38-dec4c84b134f.html}{\tt 19 Nov 2015 0.\+8.\+14} adds docu and plugins
\item \href{http://doc.libelektra.org/news/3c00a5f1-c017-4555-92b5-a2cf6e0803e3.html}{\tt 17 Sep 2015 0.\+8.\+13} adds elektrify-\/getenv
\item \href{http://doc.libelektra.org/news/98770541-32a1-486a-98a1-d02f26afc81a.html}{\tt 12 Jul 2015 0.\+8.\+12} adds dir namespace
\item \href{http://doc.libelektra.org/news/7d4647d4-4131-411e-9c2a-2aca39446e18.html}{\tt 03 Apr 2015 0.\+8.\+11} adds spec namespace
\item \href{http://doc.libelektra.org/news/6ce57ecf-420a-4a31-821e-1c5fe5532eb4.html}{\tt 02 Dec 2014 0.\+8.\+10} adds X\+D\+G/\+Open\+I\+C\+C compatibility
\item \href{http://doc.libelektra.org/news/38640673-3e07-4cff-9647-f6bdd89b1b08.html}{\tt 04 Nov 2014 0.\+8.\+9} adds qt-\/gui
\item \href{http://doc.libelektra.org/news/eca69e19-5ddb-438c-ac06-57c20b1a9160.html}{\tt 02 Sep 2014 0.\+8.\+8} adds 3-\/way merging
\end{DoxyItemize}

Also see \hyperlink{doc_NEWS_md}{News} and its \href{http://www.libelektra.org/news/feed.rss}{\tt R\+S\+S feed}.

\subsection*{Sources}

\subsubsection*{Packages}

The preferred way to install Elektra is by using packages provided for your distribution\+:
\begin{DoxyItemize}
\item \href{https://admin.fedoraproject.org/pkgdb/package/elektra/}{\tt Fedora}
\item \href{http://packages.gentoo.org/package/app-admin/elektra}{\tt Gentoo}
\item \href{https://aur.archlinux.org/packages/elektra/}{\tt Arch Linux}
\item \href{https://packages.debian.org/de/jessie/libelektra4}{\tt Debian}
\item \href{https://launchpad.net/ubuntu/+source/elektra}{\tt Ubuntu}
\end{DoxyItemize}

Available, but not up-\/to-\/date (Version 0.\+7)\+:
\begin{DoxyItemize}
\item \href{http://svnweb.mageia.org/packages/updates/1/elektra/}{\tt Mageia}
\item \href{http://community.linuxmint.com/software/view/elektra}{\tt Linux Mint}
\end{DoxyItemize}

For \href{https://build.opensuse.org/package/show/home:bekun:devel/elektra}{\tt Open\+S\+U\+S\+E, Cent\+O\+S, Fedora, R\+H\+E\+L and S\+L\+E} Kai-\/\+Uwe Behrmann kindly provides packages \href{http://software.opensuse.org/download.html?project=home%3Abekun%3Adevel&package=libelektra4}{\tt for download}. For Debian wheezy and jessie amd64 we provide latest builds. See build server below.

If there are no packages available for your distribution, see the \hyperlink{doc_INSTALL_md}{installation document}.

\subsubsection*{Download}

Elektra's uses a \href{https://github.com/ElektraInitiative/libelektra}{\tt git repository at Git\+Hub}.

You can clone the latest version of Elektra by running\+: \begin{DoxyVerb}     git clone https://github.com/ElektraInitiative/libelektra.git
\end{DoxyVerb}


Releases can be downloaded from \href{http://www.libelektra.org/ftp/elektra/releases/}{\tt http} and {\ttfamily \href{ftp://ftp.libelektra.org/elektra/releases/}{\tt ftp\+://ftp.\+libelektra.\+org/elektra/releases/}}

\subsubsection*{Compiling}

After downloading or cloning Elektra, {\ttfamily cd} to the directory and run the following commands to compile it\+:


\begin{DoxyItemize}
\item {\ttfamily mkdir -\/p build}
\item {\ttfamily cd build}
\item {\ttfamily cmake ..}
\item {\ttfamily make}
\end{DoxyItemize}

Then you can use {\ttfamily sudo make install} to install it.

You can also use the `./configure` command to generate a {\ttfamily cmake} command with special options.

For more information, especially how to set C\+Make Cache, see \hyperlink{doc_COMPILE_md}{here}. Make sure to read how to add plugins, tools and bindings.

\subsection*{Build Server}

The \href{http://build.libelektra.org:8080/}{\tt build server} builds Elektra on every commit in various ways and also produces \href{http://doc.libelektra.org/coverage/latest}{\tt L\+C\+O\+V code coverage report}.

To use the debian repository of the latest builds from master put following files in /etc/apt/sources.list. For jessie\+: \begin{DoxyVerb}    deb     [trusted=yes] http://194.117.254.29/elektra-stable/ jessie main
    deb-src [trusted=yes] http://194.117.254.29/elektra-stable/ jessie main
\end{DoxyVerb}


For wheezy\+: \begin{DoxyVerb}     deb     [trusted=yes] http://build.libelektra.org/debian/ wheezy main
     deb-src [trusted=yes] http://build.libelektra.org/debian/ wheezy main
\end{DoxyVerb}


\subsection*{Develop}

To start development, just clone the repo and start hacking! We prepared \href{https://github.com/ElektraInitiative/libelektra/issues?q=is%3Aissue+is%3Aopen+label%3A%22beginner+friendly%22}{\tt beginner friendly tasks} for you.


\begin{DoxyItemize}
\item We encourage you to improve documentation, especially the R\+E\+A\+D\+M\+E.\+md as if they were a webpage.
\item You should read the \hyperlink{doc_CODING_md}{coding document} before you issue a pull request.
\item Make yourself familiar with the \hyperlink{md_doc_help_elektra-data-structures_doc_help_elektra-data-structures_md}{Key\+Set} (also in the \href{http://doc.libelektra.org/api/latest/html/group__keyset.html}{\tt A\+P\+I docu}) the central data structure in Elektra.
\item You should read the \hyperlink{doc_DESIGN_md}{design document} before you make design relevant decisions.
\item In the source code, you should look into \hyperlink{md_src_libs_README_src_libs_README_md}{libs} and \hyperlink{md_src_plugins_README_src_plugins_README_md}{plugins}.
\item You can always peek into the T\+O\+D\+Os, if you don't know what to do. 
\end{DoxyItemize}