X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=doc%2Fsysdb.7.txt;h=383784855281edd1b8372edcb460b62106b6f287;hp=325cbca17bc5f0aa6ad1787f3427be94d9188a2a;hb=0a3dd5b9b97e25156412a95bcecf25f8d75c72fc;hpb=3ec2d4e765697f64eb3a240709b00e83f769d739

diff --git a/doc/sysdb.7.txt b/doc/sysdb.7.txt
index 325cbca..3837848 100644
--- a/doc/sysdb.7.txt
+++ b/doc/sysdb.7.txt
@@ -1,7 +1,5 @@
 sysdb(7)
 ========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-version {package_version}, {build_date}
 :doctype: manpage
 
 NAME
@@ -28,7 +26,7 @@ collects system and inventory information from the backends and aggregates
 objects retrieved from different backends based on their attributes. This way,
 it creates a uniform hierarchy of the entire infrastructure.
 
-For details about the SysDB daemon, see its manual page *sysdbd*(1).
+For details about the SysDB daemon, see its manual page manpage:sysdbd[1].
 
 sysdb
 ~~~~~
@@ -36,13 +34,73 @@ The SysDB client is a terminal-based, interactive shell which may be used to
 query the SysDB daemon. It connects to a running daemon and then accepts
 commands from the user, sends them to the server, and displays the results.
 
-For details about the SysDB client, see its manual page *sysdb*(1). For
+For details about the SysDB client, see its manual page manpage:sysdb[1]. For
 details about how to query the database, see the specification of the SysDB
-query language in *sysdbql*(7).
+query language in manpage:sysdbql[7].
+
+CONCEPTS
+--------
+SysDB's features are build around a set of concepts which are explained in
+this section.
+
+Object Store
+~~~~~~~~~~~~
+The central part of SysDB's database is the object store which stores all
+objects (hosts, services) known to SysDB. The implementation is provided by a
+"store" plugin and may be backed by arbitrary data-stores. At least one store
+plugin has to be loaded to let the daemon do its work.
+
+Hosts and Services
+~~~~~~~~~~~~~~~~~~
+The basic building block of SysDB's store are host and service objects
+representing physical and logical resources. Each host is identified by a
+unique name and each service is identified by a unique pair of a hostname and
+a service name. All services are assigned to the respective host which is
+usually interpreted as the service running on that host. In addition, hosts
+and services may have a list of attributes assigned to them. These are
+arbitrary key-value pairs providing additional information about the
+respective object and they may be used to further categorize and identify an
+object. For example, the *mk-livestatus* and *puppet::store-configs* backend
+plugins provide a list of all hosts and services known to the monitoring
+system queried through the Check_MK livestatus interface and all hosts will be
+attributed with all "fact" values known to Puppet. This allows to query hosts
+based on facts like architecture or LSB information using query commands like
+*LOOKUP* (see manpage:sysdbql[7]).
+
+Host and service objects are provided and updated by backend plugins and
+queried from other systems, like inventory databases or monitoring systems.
+
+Hostname Canonicalization
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Before storing an object in SysDB's store, any hostname used to identify the
+object is canonicalized. This is done by so called "cname" plugins and may be
+based on arbitrary information derived from the original hostname. This way,
+hosts provided by different backends may be mapped to the same host in SysDB
+even if, for example, one backend uses short hostnames while another uses
+fully qualified domain names (FQDNs). For example, the *cname::dns* plugin
+uses reverse DNS queries to resolve a name to its canonical hostname as
+provided by DNS.
+
+Metrics and Time-Series
+~~~~~~~~~~~~~~~~~~~~~~~
+A metric identifies performance data about a host. SysDB does not collect or
+store the actual data but collects information about which metrics are
+available from backends. It then provides a generic way to fetch time-series
+data directly from a backend's data-store. In some cases, this requires
+additional configuration. For example, the *collectd::unixsock* plugin
+provides information about which metrics are available from a collectd
+instance. Using the *TimeseriesBackend* and *TimeseriesBaseURL* configuration
+options (see manpage:sysdbd-collectd-unixsock[5]), SysDB may be told where to
+fetch time-series data from. The details are automatically managed by the
+plugin and the *timeseries::rrdtool* plugin may be used to fetch the data from
+RRD files managed by collectd. Fetching the data may be done using the
+*TIMESERIES* query command (see manpage:sysdbql[7]).
 
 SEE ALSO
 --------
-*sysdb*(1), *sysdbd*(1), *sysdbql*(7)
+manpage:sysdb[1], manpage:sysdbd[1], manpage:sysdbql[7]
+
+The SysDB homepage: https://sysdb.io/
 
 AUTHOR
 ------