doc/sysdb.7.txt

   1 sysdb(7)
   2 ========
   3 :doctype: manpage
   4
   5 NAME
   6 ----
   7 sysdb - the System DataBase (SysDB)
   8
   9 SYNOPSIS
  10 --------
  11
  12   sysdbd -C /path/to/sysdbd.conf
  13
  14   sysdb -H /path/to/sysdbd.sock
  15
  16 DESCRIPTION
  17 -----------
  18 include::sysdb-description.txt[]
  19
  20 SysDB is made up of several components:
  21
  22 sysdbd
  23 ~~~~~~
  24 The SysDB daemon acts as the data collection instance and database server. It
  25 collects system and inventory information from the backends and aggregates
  26 objects retrieved from different backends based on their attributes. This way,
  27 it creates a uniform hierarchy of the entire infrastructure.
  28
  29 For details about the SysDB daemon, see its manual page manpage:sysdbd[1].
  30
  31 sysdb
  32 ~~~~~
  33 The SysDB client is a terminal-based, interactive shell which may be used to
  34 query the SysDB daemon. It connects to a running daemon and then accepts
  35 commands from the user, sends them to the server, and displays the results.
  36
  37 For details about the SysDB client, see its manual page manpage:sysdb[1]. For
  38 details about how to query the database, see the specification of the SysDB
  39 query language in manpage:sysdbql[7].
  40
  41 CONCEPTS
  42 --------
  43 SysDB's features are build around a set of concepts which are explained in
  44 this section.
  45
  46 Object Store
  47 ~~~~~~~~~~~~
  48 The central part of SysDB's database is the object store which stores all
  49 objects (hosts, services) known to SysDB. The implementation is provided by a
  50 "store" plugin and may be backed by arbitrary data-stores. At least one store
  51 plugin has to be loaded to let the daemon do its work.
  52
  53 Hosts and Services
  54 ~~~~~~~~~~~~~~~~~~
  55 The basic building block of SysDB's store are host and service objects
  56 representing physical and logical resources. Each host is identified by a
  57 unique name and each service is identified by a unique pair of a hostname and
  58 a service name. All services are assigned to the respective host which is
  59 usually interpreted as the service running on that host. In addition, hosts
  60 and services may have a list of attributes assigned to them. These are
  61 arbitrary key-value pairs providing additional information about the
  62 respective object and they may be used to further categorize and identify an
  63 object. For example, the *mk-livestatus* and *puppet::store-configs* backend
  64 plugins provide a list of all hosts and services known to the monitoring
  65 system queried through the Check_MK livestatus interface and all hosts will be
  66 attributed with all "fact" values known to Puppet. This allows to query hosts
  67 based on facts like architecture or LSB information using query commands like
  68 *LOOKUP* (see manpage:sysdbql[7]).
  69
  70 Host and service objects are provided and updated by backend plugins and
  71 queried from other systems, like inventory databases or monitoring systems.
  72
  73 Hostname Canonicalization
  74 ~~~~~~~~~~~~~~~~~~~~~~~~~
  75 Before storing an object in SysDB's store, any hostname used to identify the
  76 object is canonicalized. This is done by so called "cname" plugins and may be
  77 based on arbitrary information derived from the original hostname. This way,
  78 hosts provided by different backends may be mapped to the same host in SysDB
  79 even if, for example, one backend uses short hostnames while another uses
  80 fully qualified domain names (FQDNs). For example, the *cname::dns* plugin
  81 uses reverse DNS queries to resolve a name to its canonical hostname as
  82 provided by DNS.
  83
  84 Metrics and Time-Series
  85 ~~~~~~~~~~~~~~~~~~~~~~~
  86 A metric identifies performance data about a host. SysDB does not collect or
  87 store the actual data but collects information about which metrics are
  88 available from backends. It then provides a generic way to fetch time-series
  89 data directly from a backend's data-store. In some cases, this requires
  90 additional configuration. For example, the *collectd::unixsock* plugin
  91 provides information about which metrics are available from a collectd
  92 instance. Using the *TimeseriesBackend* and *TimeseriesBaseURL* configuration
  93 options (see manpage:sysdbd-collectd-unixsock[5]), SysDB may be told where to
  94 fetch time-series data from. The details are automatically managed by the
  95 plugin and the *timeseries::rrdtool* plugin may be used to fetch the data from
  96 RRD files managed by collectd. Fetching the data may be done using the
  97 *TIMESERIES* query command (see manpage:sysdbql[7]).
  98
  99 SEE ALSO
 100 --------
 101 manpage:sysdb[1], manpage:sysdbd[1], manpage:sysdbql[7]
 102
 103 The SysDB homepage: https://sysdb.io/
 104
 105 AUTHOR
 106 ------
 107 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 108
 109 COPYRIGHT
 110 ---------
 111 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 112
 113 This is free software under the terms of the BSD license, see the source for
 114 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 115 FITNESS FOR A PARTICULAR PURPOSE.
 116
 117 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 118