Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
augeas
base64
blockresolver
boolean
c
cachefilter
camel
ccode
conditionals
constants
counter
cpptemplate
crypto
csvstorage
curlget
date
dbus
dbusrecv
desktop
dini
directoryvalue
doc
dpkg
dump
enum
error
fcrypt
file
filecheck
fstab
gitresolver
glob
gpgme
haskell
hexcode
hexnumber
hidden
hosts
iconv
ini
internalnotification
ipaddr
iterate
jni
journald
keytometa
line
lineendings
list
logchange
lua
mathcheck
mini
mozprefs
multifile
network
ni
noresolver
null
passwd
path
process
profile
python
python2
range
regexdispatcher
regexstore
rename
required
resolver
ruby
semlock
shell
simpleini
simplespeclang
spec
struct
sync
syslog
tcl
template
timeofday
tracer
type
typechecker
uname
validation
wresolver
xerces
xmltool
yajl
yamlcpp
yamlsmith
yanlr
zeromqrecv
zeromqsend
CMakeLists.txt
README.md
plugin-symbols.map

README.md

elektra-plugins(7) -- plugins overview

Multiple plugins can be mounted into the key database (KDB). On every access to the key data base they are executed and thus can change the functionality and behavior.

Description

Elektra has a wide range of different plugins. The plugin folders should contain a README.md with further information. (Or follow links below.) The plugins are:

Overview Plugins

C-Interface

All plugins implement the same interface:

  • kdbOpen() calls elektraPluginOpen() of every plugin to let them do their initialisation.
  • kdbGet() requests elektraPluginGet() of every plugin in the queried backends to return a key set.
  • kdbSet() usually calls elektraPluginSet() of every plugin in the queried backends to store the configuration.
  • kdbSet() also calls elektraPluginError() for every plugin when an error happens. Because of elektraPluginError(), plugins are guaranteed to have their chance for necessary cleanups.
  • kdbClose() makes sure that plugins can finally free their own resources in elektraPluginClose().
  • kdbCheckConfig() can be called manually to ensure a plugin is configured properly.
  • kdbGenConfig() can be called to produce all valid configurations of a plugin.

KDB-Interface

See also

For an easy introduction, see this tutorial how to write a storage plugin. For more background information of the plugins framework, continue here. Otherwise, you can visit the the API documentation.

Plugins

Resolver

Before configuration is actually written, the file name needs to be determined (resolvers will be automatically added by kdb mount):

  • resolver uses advanced POSIX APIs to handle conflicts gracefully

  • wresolver minimalistic resolver for non-POSIX systems

  • noresolver does not resolve, but can act as one

  • gitresolver checks out and commits files to a local git repository and afterwards the configuration file must be synced with harddisc (recommended to add at every kdb mount):

  • curlget fetches configuration file from a remote host

  • blockresolver resolves tagged blocks inside config files

  • multifile

  • sync uses POSIX APIs to sync configuration files with the hard disk

Storage

Are responsible for reading writing the configuration to configuration files.

Read and write everything a KeySet might contain:

  • dini uses by default the ini plugin but has legacy support for dump
  • ini supports a range of INI file formats.
  • dump makes a dump of a KeySet in an Elektra-specific format

Read (and write) standard config files:

  • augeas reads/writes many different configuration files using the augeas library
  • hosts reads/writes hosts files
  • line reads/writes any file line by line
  • yajl reads/writes JSON.

Using semi-structured data for config files, mainly suitable for spec-namespace (put a focus on having nice syntax for metadata):

  • ni parses INI files based on (including metadata) ni.
  • tcl-like config files (including metadata).

Only suited for import/export:

  • xerces uses XML (without a specific schema).
  • xmltool uses XML (in Elektra's XML schema).
  • simpleini line-based key-value pairs with configurable format (without sections)
  • mini dependency free, line based key-value storage plugin.
  • yamlsmith exports key sets in the YAML format

Plugins that just show some functionality, (currently) not intended for productive use:

  • typechecker type checks a configuration specification
  • regexdispatcher generates regex representations of specification keywords
  • fstab for fstab files.
  • regexstore
  • csvstorage for csv files
  • passwd for passwd files
  • dpkg reads /var/lib/dpkg/{available,status}
  • mozprefs for Mozilla preference files
  • c writes Elektra C-structures (ksNew(.. keyNew(...)
  • file reads and writes a file from/to a single key
  • camel reads and writes a very limited subset of YAML
  • yamlcpp reads and writes data in the YAML format using yaml-cpp
  • yanlr reads data using a parser generated by ANTLR

System Information

Information compiled in Elektra:

  • version is a built-in plugin directly within the core so that it cannot give wrong version information
  • constants various constants, including version information
  • desktop contains information which desktop is currently running

Providing information found on the system not available in persistent files:

  • uname information from the uname syscall.

Filter

Filter plugins process keys and their values in both directions. In one direction they undo what they do in the other direction. Most filter plugins available now encode and decode values. Storage plugins that use characters to separate key names, values or metadata will not work without them.

  • cachefilter stores filtered keys internally so that they do not get accidentally lost and can be written to the storage again without the user having to remember including them in the writeout

Encoding

Rewrite unwanted characters with different techniques:

  • ccode using the technique from arrays in the programming language C
  • hexcode using hex codes
  • base64 using the Base64 encoding scheme (RFC4648)

Transformations:

  • directoryvalue converts directory values to leaf values
  • keytometa transforms keys to metadata
  • rename renames keys according to different rules
  • boolean canonicalizes boolean keys
  • hexnumber converts between hexadecimal and decimal

Doing other stuff:

  • crypto encrypts / decrypts confidential values
  • gpgme encrypts / decrypts confidential values (with GPGME)
  • fcrypt encrypts / decrypts entire backend files
  • iconv makes sure the configuration will have correct character encoding
  • hidden hides keys whose names start with a ..
  • null takes care of null values and other binary specialities

Notification and Logging

Log/Send out all changes to configuration to:

  • dbus sends notifications for every change via dbus notification
  • dbusrecv receives notifications via dbus notification
  • zeromqsend sends notifications for every change via ZeroMQ sockets notification
  • zeromqrecv receives notifications via ZeroMQ sockets notification
  • syslog logs key database changes to syslog
  • journald logs key database changes to journald
  • logchange prints the change of every key on the console

Notification of key changes:

Debug

Trace everything that happens within KDB:

Checker

Copies metadata to keys:

  • spec copies metadata from spec namespace (the standard way)
  • glob using globbing techniques (needed by some plugins)
  • struct using a defined structure (may also reject configuration not conforming to that structure)

Plugins that check if values are valid based on metadata (typically copied by the spec plugin just before):

Value Validation

  • validation by using regex
  • network by using network APIs
  • ipaddr checks IP addresses using regular expressions
  • path by checking files on file system
  • type using run-time type checking (CORBA types/)
  • enum compares the keyvalue against a list of valid values
  • mathcheck by mathematical expressions using key values as operands
  • conditionals by using if-then-else like statements
  • required rejects non-required keys
  • date validates date and time data
  • range checks if a value is within a given range

Other Validation

Interpreter

These plugins start an interpreter and allow you to execute a script in an interpreted language whenever Elektra’s key database gets accessed. Note that they depend on the presence of the respective binding during run-time.

  • jni java plugins started by jni, works with jna plugins
  • python Python 3 plugins
  • python2 Python 2 plugins (deprecated)
  • ruby Ruby plugins
  • lua Lua plugins
  • shell executes shell commandos
  • haskell used for linking haskell plugins and is a small example for such plugins itself

Others

  • doc contains the documentation of the plugin interface
  • error yields errors as described in metadata (handy for test purposes)
  • template to be copied for new plugins
  • cpptemplate a template for C++ based plugins
  • list loads other plugins
  • iterate iterate over all keys and run exported functions on tagged keys
  • semlock a semaphore based global locking logic
  • process proxy plugin that executes other plugins in a separate process
  • profile links profile keys
  • simplespeclang simple configuration specification language