From 0c6db1980ba06dbe4b380d3fdf5e5eca12e0f2c2 Mon Sep 17 00:00:00 2001 From: Sebastian Harl Date: Mon, 5 May 2014 17:35:20 +0200 Subject: [PATCH] sysdbql(7): Document the query language. --- .gitignore | 2 + doc/Makefile.am | 22 ++++-- doc/sysdbql.7.txt | 193 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+), 5 deletions(-) create mode 100644 doc/sysdbql.7.txt diff --git a/.gitignore b/.gitignore index d3e9df3..74921b8 100644 --- 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 d673a1b..f605ecf 100644 --- 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 index 0000000..375c28d --- /dev/null +++ b/doc/sysdbql.7.txt @@ -0,0 +1,193 @@ +sysdbdql(7) +=========== +Sebastian "tokkee" Harl +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* '':: +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* '':: +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: + +'' '' '':: + Match a named field against the specified value. See below for what fields + and operators are supported. + +*NOT* '':: + Invert the boolean result of the specified subexpression. + +'' *AND* '':: +'' *OR* '':: + 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.*'':: + 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 . + +COPYRIGHT +--------- +Copyright (C) 2012-2014 Sebastian "tokkee" Harl + +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 : + -- 2.30.2