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 Hosts and Services
  47 ~~~~~~~~~~~~~~~~~~
  48 The basic building block of SysDB's store are host and service objects
  49 representing physical and logical resources. Each host is identified by a
  50 unique name and each service is identified by a unique pair of a hostname and
  51 a service name. All services are assigned to the respective host which is
  52 usually interpreted as the service running on that host. In addition, hosts
  53 and services may have a list of attributes assigned to them. These are
  54 arbitrary key-value pairs providing additional information about the
  55 respective object and they may be used to further categorize and identify an
  56 object. For example, the *mk-livestatus* and *puppet::store-configs* backend
  57 plugins provide a list of all hosts and services known to the monitoring
  58 system queried through the Check_MK livestatus interface and all hosts will be
  59 attributed with all "fact" values known to Puppet. This allows to query hosts
  60 based on facts like architecture or LSB information using query commands like
  61 *LOOKUP* (see manpage:sysdbql[7]).
  62
  63 Host and service objects are managed by backend plugins and queried from other
  64 systems, like inventory databases or monitoring systems.
  65
  66 Hostname Canonicalization
  67 ~~~~~~~~~~~~~~~~~~~~~~~~~
  68 Before storing an object in SysDB's store, any hostname used to identify the
  69 object is canonicalized. This is done by so called "cname" plugins and may be
  70 based on arbitrary information derived from the original hostname. This way,
  71 hosts provided by different backends may be mapped to the same host in SysDB
  72 even if, for example, one backend uses short hostnames while another uses
  73 fully qualified domain names (FQDNs). For example, the *cname::dns* plugin
  74 uses reverse DNS queries to resolve a name to its canonical hostname as
  75 provided by DNS.
  76
  77 Metrics and Time-Series
  78 ~~~~~~~~~~~~~~~~~~~~~~~
  79 A metric identifies performance data about a host. SysDB does not collect or
  80 store the actual data but collects information about which metrics are
  81 available from backends. It then provides a generic way to fetch time-series
  82 data directly from a backend's data-store. In some cases, this requires
  83 additional configuration. For example, the *collectd::unixsock* plugin
  84 provides information about which metrics are available from a collectd
  85 instance. Using the *TimeseriesBackend* and *TimeseriesBaseURL* configuration
  86 options (see manpage:sysdbd-collectd-unixsock[5]), SysDB may be told where to
  87 fetch time-series data from. The details are automatically managed by the
  88 plugin and the *timeseries::rrdtool* plugin may be used to fetch the data from
  89 RRD files managed by collectd. Fetching the data may be done using the
  90 *TIMESERIES* query command (see manpage:sysdbql[7]).
  91
  92 SEE ALSO
  93 --------
  94 manpage:sysdb[1], manpage:sysdbd[1], manpage:sysdbql[7]
  95
  96 The SysDB homepage: https://sysdb.io/
  97
  98 AUTHOR
  99 ------
 100 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 101
 102 COPYRIGHT
 103 ---------
 104 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 105
 106 This is free software under the terms of the BSD license, see the source for
 107 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 108 FITNESS FOR A PARTICULAR PURPOSE.
 109
 110 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 111