sysdbql(7): Document the query language.

diff --git a/.gitignore b/.gitignore
index d3e9df3da051dbeea5282825a13dbbeeda661448..74921b82349d1474e1b4d3333f42755977e1dbb8 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -33,6 +33,8 @@ doc/*.1
 doc/*.1.html
 doc/*.5
 doc/*.5.html
+doc/*.7
+doc/*.7.html
 doc/docbook-xsl.css
 src/frontend/grammar.c
 src/frontend/grammar.h

diff --git a/doc/Makefile.am b/doc/Makefile.am
index d673a1b5abe8a21dd62b6c80aad5fb9e248d97aa..f605ecfab29233b31fa7c0084b62d98bbf01588c 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-SUFFIXES = .1 .5 .1.html .5.html .1.txt .5.txt
+SUFFIXES = .1 .5 .7 .1.html .5.html .7.html .1.txt .5.txt .7.txt
 
 EXTRA_DIST = \
                sysdb.1.txt \
@@ -8,7 +8,8 @@ EXTRA_DIST = \
                sysdbd-collectd-unixsock.5.txt \
                sysdbd-mk-livestatus.5.txt \
                sysdbd-puppet-store-configs.5.txt \
-               sysdbd-syslog.5.txt
+               sysdbd-syslog.5.txt \
+               sysdbql.7.txt
 CLEANFILES = \
                sysdb.1 \
                sysdbd.1 \
@@ -18,6 +19,7 @@ CLEANFILES = \
                sysdbd-mk-livestatus.5 \
                sysdbd-puppet-store-configs.5 \
                sysdbd-syslog.5 \
+               sysdbql.7 \
                docbook-xsl.css \
                sysdb.1.html \
                sysdbd.1.html \
@@ -26,7 +28,8 @@ CLEANFILES = \
                sysdbd-collectd-unixsock.5.html \
                sysdbd-mk-livestatus.5.html \
                sysdbd-puppet-store-configs.5.html \
-               sysdbd-syslog.5.html
+               sysdbd-syslog.5.html \
+               sysdbql.7.html
 
 man_MANS = \
                sysdb.1 \
@@ -36,7 +39,8 @@ man_MANS = \
                sysdbd-collectd-unixsock.5 \
                sysdbd-mk-livestatus.5 \
                sysdbd-puppet-store-configs.5 \
-               sysdbd-syslog.5
+               sysdbd-syslog.5 \
+               sysdbql.7
 
 html_DATA = \
                docbook-xsl.css \
@@ -47,7 +51,8 @@ html_DATA = \
                sysdbd-collectd-unixsock.5.html \
                sysdbd-mk-livestatus.5.html \
                sysdbd-puppet-store-configs.5.html \
-               sysdbd-syslog.5.html
+               sysdbd-syslog.5.html \
+               sysdbql.7.html
 
 ADOC_ATTRS = -apackage_version=$(PACKAGE_VERSION) \
                -abuild_date="$$( date --utc '+%F' )" \
@@ -61,6 +66,7 @@ sysdbd-collectd-unixsock.5: sysdbd-collectd-unixsock.5.txt ../version
 sysdbd-mk-livestatus.5: sysdbd-mk-livestatus.5.txt ../version
 sysdbd-puppet-store-configs.5: sysdbd-puppet-store-configs.5.txt ../version
 sysdbd-syslog.5: sysdbd-syslog.5.txt ../version
+sysdbql.7: sysdbql.7.txt ../version
 
 sysdb.1.html: sysdb.1.txt ../version
 sysdbd.1.html: sysdbd.1.txt ../version
@@ -70,6 +76,7 @@ sysdbd-collectd-unixsock.5.html: sysdbd-collectd-unixsock.5.txt ../version
 sysdbd-mk-livestatus.5.html: sysdbd-mk-livestatus.5.txt ../version
 sysdbd-puppet-store-configs.5.html: sysdbd-puppet-store-configs.5.txt ../version
 sysdbd-syslog.5.html: sysdbd-syslog.5.txt ../version
+sysdbql.7.html: sysdbql.7.txt ../version
 
 # This is an ugly hack but fine for now.
 docbook-xsl.css:
@@ -85,3 +92,8 @@ docbook-xsl.css:
 .5.txt.5.html:
        @A2X@ -d manpage -f xhtml $(ADOC_ATTRS) $<
 
+.7.txt.7:
+       @A2X@ -d manpage -f manpage $(ADOC_ATTRS) $<
+.7.txt.7.html:
+       @A2X@ -d manpage -f xhtml $(ADOC_ATTRS) $<
+

diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
new file mode 100644 (file)
index 0000000..375c28d
--- /dev/null
+++ b/doc/sysdbql.7.txt
@@ -0,0 +1,193 @@
+sysdbdql(7)
+===========
+Sebastian "tokkee" Harl <sh@tokkee.org>
+version {package_version}, {build_date}
+:doctype: manpage
+
+NAME
+----
+sysdbql - the SysDB query language
+
+SYNOPSIS
+--------
+
+  LIST;
+
+  QUERY hosts WHERE attribute.architecture = 'amd64';
+
+DESCRIPTION
+-----------
+SysDB stores system and inventory information about hardware and software
+systems. This information is stored in a graph-like hierarchy of generic
+objects. The central object type is a host, which generally represents a
+physical or virtual machine or any other type of physical resource. Hosts, in
+turn, may reference a list of services which represent any kind of logical
+resource like a software system. Both, hosts and services, may reference a
+list of attributes which represent further information about the respective
+host or service object. For example, attributes may specify static information
+like a host's architecture or the software version or snapshots of performance
+data like the current memory utilization or much more.
+
+The SysDB query language is a human-readable format for describing a request
+to retrieve data from a SysDB daemon. It is very remotely similar to the
+Standard Query Language (SQL) supported by relational database management
+systems (RDBMS) but specialized for SysDB's use-case.
+
+QUERY COMMANDS
+--------------
+Each command is terminated by a semicolon. The following commands are
+available to retrieve information from SysDB:
+
+*LIST*::
+Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
+return value is a list of hosts where each host description includes its name,
+the timestamp of the last update of the object in SysDB and an approximation
+of the interval with which the host was updated.
+
+*FETCH* '<hostname>'::
+Retrieve detailed information about the specified host object. The return
+value includes the hostname, a list of services referenced by the host, and a
+list of attributes for the host and each service. If the host does not exist,
+an error is returned.
+
+*LOOKUP* hosts *WHERE* '<search_condition>'::
+Retrieve detailed information about all host objects matching the specified
+search condition. The return value is a list of detailed information for each
+matching host providing the same details as returned by the *FETCH* command.
+See the section "WHERE clause" for more details about how to specify the
+search condition.
+
+WHERE clause
+~~~~~~~~~~~~
+The *WHERE* clause in a query specifies a boolean expression which is used to
+match host objects based on their names, their attributes, or services
+referenced by the host. Each *WHERE* clause may be made up of one or multiple
+subexpressions each matching on one criteria. The following subexpressions
+are supported by SysDB:
+
+'<field>' '<operator>' '<value>'::
+       Match a named field against the specified value. See below for what fields
+       and operators are supported.
+
+*NOT* '<subexpression>'::
+       Invert the boolean result of the specified subexpression.
+
+'<subexpression>' *AND* '<subexpression>'::
+'<subexpression>' *OR* '<subexpression>'::
+       Combine multiple subexpressions using logical AND or logical OR.
+
+The following fields may be queried:
+
+*host.name*::
+       The full name of the host.
+
+*service.name*::
+       The full service name as referenced by the host.
+
+*attribute.name*::
+       The full name of a host attribute.
+
+*attribute.*'<name>'::
+       The value of the named host attribute. If an attribute of the specified
+       does not exist, each comparison is treated as if the value does not match.
+
+The following operators may be used to match field values:
+
+*=*::
+       Evaluates to true if the field value exactly matches the specified value.
+
+*!=*::
+       Evaluates to true if the field value does not match the exact specified
+       value.
+
+*=~*::
+       Evaluates to true if the field value matches the specified regular
+       expression. SysDB uses POSIX extended regular expressions.
+
+*!~*::
+       Evalues to true if the field value does not match the specified regular
+       expression.
+
+RESPONSE FORMAT
+---------------
+The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
+used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
+
+EXAMPLES
+--------
+The following examples illustrate the use of the commands and what their
+replies look like. The replies are pretty-printed to more easily follow them.
+
+  LIST;
+  {"hosts":[{
+      "name": "host1.example.com",
+      "last_update": "2001-02-03 04:05:06 +0700",
+      "update_interval": "5m4s"
+    },{
+      "name": "host2.example.com",
+      "last_update": "2001-02-03 04:05:06 +0700",
+      "update_interval": "5m4s"
+    }]}
+
+  FETCH 'host1.example.com';
+  {
+      "name": "host1.example.com",
+      "last_update": "2001-02-03 04:05:06 +0700",
+      "update_interval": "5m4s",
+      "attributes": [{
+          "name": "architecture",
+          "value": "amd64",
+          "last_update": "2001-02-03 04:05:06 +0700",
+          "update_interval": "5m4s"
+        },{
+          ...
+        }],
+      "services": [{
+          "name": "some service",
+          "last_update": "2001-02-03 04:05:06 +0700",
+          "update_interval": "5m4s"
+        },{
+          ...
+        }]}
+
+  LOOKUP hosts WHERE attribute.architecture = 'amd64';
+  [{
+      "name": "host1.example.com",
+      "last_update": "2001-02-03 04:05:06 +0700",
+      "update_interval": "5m4s",
+      "attributes": [{
+          "name": "architecture",
+          "value": "amd64",
+          "last_update": "2001-02-03 04:05:06 +0700",
+          "update_interval": "5m4s"
+        },{
+          ...
+        }],
+      "services": [{
+          "name": "some service",
+          "last_update": "2001-02-03 04:05:06 +0700",
+          "update_interval": "5m4s"
+        },{
+          ...
+    }]},{
+      ...
+    }]
+
+SEE ALSO
+--------
+*sysdb*(1)
+
+AUTHOR
+------
+SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
+
+COPYRIGHT
+---------
+Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
+
+This is free software under the terms of the BSD license, see the source for
+copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.
+
+// vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
+