path: root/docs/mon.1

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MON 1"
.TH MON 1 "2015-01-02" "mon 1.0.1" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
mon \- A Humble Monitoring API Tool for https://github.com/Crapworks/RESTlos
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
m is a synonym of the mon command. You can use either command, but m is shorter to type.
.PP
.Vb 1
\&    m [OPTIONS] QUERY [OPTIONS]
.Ve
.PP
mi is a synomym for mon \-\-interactive \-\-meta
.PP
.Vb 1
\&    mi [OPTIONS]
.Ve
.SS "Where \s-1OPTIONS\s0 can be one (or several) of:"
.IX Subsection "Where OPTIONS can be one (or several) of:"
.IP "\-\-config=VAL or \-c=VAL" 4
.IX Item "--config=VAL or -c=VAL"
Specifies a config file to read instead the default ones.
.IP "\-\-debug or \-D" 4
.IX Item "--debug or -D"
Prints out extra debugging infos during execution. This option also implies \-\-verbose.  \s-1CAUTION:\s0 This switch does not work together with the shell auto completion.
.IP "\-\-dry or \-d" 4
.IX Item "--dry or -d"
Does not modify any object via the \s-1API\s0, read only operations only.
.IP "\-\-errfile=PATH or \-E=PATH" 4
.IX Item "--errfile=PATH or -E=PATH"
If mon is used it is usefull to track if the last mon invocation exited with an error. \s-1PATH\s0 specifies the full path to a status file to be written if mon exists with an error.
.Sp
Puppet can check for that file and can re-try the same operation the next run.
.Sp
Mon deletes that file automatically after the next successfull run.
.IP "\-\-help or \-h" 4
.IX Item "--help or -h"
Implies a \-\-dry. Also prints out all available options.
.IP "\-\-interactive or \-i" 4
.IX Item "--interactive or -i"
Starts mon in interactive mode. Prefix a command with '!' to run it via shell, e.g. '!ls /tmp'.
.IP "\-\-meta or \-m" 4
.IX Item "--meta or -m"
By default mon does not show any meta (aka nagios custom variables) in its \s-1JSON\s0 output. Those are all variables starting with an underscore (e.g. _WORKER). One exception is the 'edit' operation of mon, it always shows all the meta variables.
.Sp
The meta switch makes mon to display also all meta vairables all the time.
.IP "\-\-nocolor or \-n" 4
.IX Item "--nocolor or -n"
By default mon prints out some text in colors. Use this switch to disable that. Or use an environment variable to do that (see \s-1ENVIRONMENT\s0 \s-1VARIABLES\s0 below).
.IP "\-\-quiet or \-q" 4
.IX Item "--quiet or -q"
Quiet mode. No output at all. This also implies \-\-debug=0, \-\-verbose=0, \-\-nocolor.
.IP "\-\-syslog or \-s" 4
.IX Item "--syslog or -s"
Loggs stuff to syslog. See later in this manpage for info more about this.
.IP "\-\-unique or \-u" 4
.IX Item "--unique or -u"
Prints only unique entries in getfmt.
.IP "\-\-verbose or \-v" 4
.IX Item "--verbose or -v"
Prints out extra infos during execution. \s-1CAUTION:\s0 This switch does not work together with the shell auto completion.
.IP "\-\-version or \-V" 4
.IX Item "--version or -V"
Prints out program version.
.IP "\-\-foo.bar=value" 4
.IX Item "--foo.bar=value"
In addition it is possible to overwrite all values of the mon.conf via command line interface. E.g. \-\-restlos.api.port=10043 will overwrite the api port (ignores the value of the mon.conf).
.Sp
These keys must be in 'dot\-separated' format.
.PP
An option can be written at the beginning or at the end of each command.
.SS "Where \s-1QUERY\s0 can be one one of:"
.IX Subsection "Where QUERY can be one one of:"
.Vb 10
\&    delete CATEGORY [where FIELD1 OP VALUE1 [and ...]] 
\&    edit|view CATEGORY [where FIELD1 OP VALUE1 [and ...]] 
\&    get CATEGORY [where FIELD1 OP VALUE1 [and ...]]
\&    get CATEGORY [where FIELD1 OP VALUE1 [and ...]] > datafile.json
\&    getfmt FORMAT CATEGORY [where FIELD1 OP VALUE1 [and ...]]
\&    getfmt FORMAT CATEGORY [where FIELD1 OP VALUE1 [and ...]] > datafile
\&    insert CATEGORY set FIELD1 = VALUE1 [and FIELD2 = VALUE2 ...] 
\&    post CATEGORY < datafile.json 
\&    post CATEGORY from datafile.json 
\&    put CATEGORY < datafile.json 
\&    put CATEGORY from datafile.json 
\&    update CATEGORY delete FIELD1 [and FIELD2 ...] 
\&      where FIELD3 OP VALUE3 [and ...]]]
\&    update CATEGORY set FIELD1 = FORMAT [and FIELD2 = 
\&      FORMAT2 ...] where FIELD3 OP VALUE3 [and ...]]] 
\&    verify|restart|reload [OPTIONS]
.Ve
.PP
\fIShortcut versions of the commands above are:\fR
.IX Subsection "Shortcut versions of the commands above are:"
.PP
.Vb 10
\&    a for and
\&    d for delete
\&    e for edit
\&    f for getfmt
\&    g for get
\&    i for insert
\&    l and ~ for like
\&    p for post
\&    r for reload/restart
\&    s for set
\&    t for put
\&    u for update
\&    v for view
\&    y for verify
\&    : for where
\&    == for eq
\&    != for ne
\&    =~ for matches
\&    !~ for nmatches
.Ve
.PP
They don't show up in the online help in order not to mess it up.
.SS "And \s-1OP\s0 can be:"
.IX Subsection "And OP can be:"
.IP "like" 4
.IX Item "like"
Like is the fastest operator and will be used within the query string against the monitoring \s-1API\s0 itself.
.Sp
Example:
  m get host where host_name like testfe01
.Sp
will result in a query string /host?host_name=testfe01. All other operators Pre-fetch the results from the \s-1API\s0 and filter the response JSONs.
.IP "matches" 4
.IX Item "matches"
Can be used to use perl regex to filter the fields.
.Sp
Example:
  m get host where host_name matches 'server\ed\ed\e.*\e.cinetic.de'
.IP "nmatches" 4
.IX Item "nmatches"
Negation of matches.
.IP "eq" 4
.IX Item "eq"
The specific field must be exactly as specified.
.Sp
Example:
  m get host where host_name eq 'server10.example.com'
.IP "ne" 4
.IX Item "ne"
Negation of eq
.IP "lt, le, gt, ge" 4
.IX Item "lt, le, gt, ge"
The specific field must match (numerically) as specified.
.Sp
Example:
  m get host where host_name lt 10
.Sp
retrieves all hosts with its host number lower than 10.
.Sp
Example:
  m get host where host_name gt 10 and host_name le 20 and host_name like server
.Sp
retrieves all server hosts between 10 up to 20, which are server{11..20} actually.
.SS "And \s-1FORMAT\s0 can be:"
.IX Subsection "And FORMAT can be:"
.IP "A string" 4
.IX Item "A string"
Example:
  m update host set name = foo where host_name like testfe01
.IP "A string with special chars" 4
.IX Item "A string with special chars"
Example:
  m update host set name = 'foo! bar% baz$' where host_name like testfe01
.IP "A mon variable (uses a value of the current object)" 4
.IX Item "A mon variable (uses a value of the current object)"
Examples:
.Sp
.Vb 1
\&  m update host set name = \*(Aq$host_name\*(Aq where host_name like testfe01
\&
\&  m update host set name = \*(Aq${host_name}foo\*(Aq where host_name like testfe01
.Ve
.Sp
Notice: This actually uses the host_name value of the current host object being modified. It can be done with any value of this object.
.IP "A string with variables expanded by the shell" 4
.IX Item "A string with variables expanded by the shell"
Example:
  m update host set name = \*(L"$shell_expanded \e$host_name\*(R" where host_name like testfe01b
.Sp
Notice: In double quotes you must escape the variable if you want to use a mon variable. It is possible to use @ instead to avoid cryptic escape sequences.
.Sp
.Vb 1
\&  m update host set name = "$shell_expanded @host_name" where host_name like testfe01b
.Ve
.Sp
It also works this way:
.Sp
.Vb 1
\&  m update host set name = "$shell_expanded @{host_name}foo" where host_name like testfe01b
.Ve
.IP "A common use case" 4
.IX Item "A common use case"
.Vb 1
\&  m update host set name = @host_name where host_name like testfe01
.Ve
.ie n .IP "Some ""encrypted"" example" 4
.el .IP "Some ``encrypted'' example" 4
.IX Item "Some encrypted example"
.Vb 1
\&  m update host set _FOO = "@{host_name}knurks${bash_variable}\e$foo\*(Aq where host_name like testfe01
.Ve
.IP "Or via getfmt" 4
.IX Item "Or via getfmt"
.Vb 1
\&  m getfmt "Host: @host_name" host where host_name like testfe01
.Ve
.Sp
One special case is the following:
.Sp
.Vb 1
\&  m getfmt "Host: @HOSTNAME" host where host_name like testfe01
.Ve
.Sp
which explicitly turns host_name which may be a \s-1FQDN\s0 to a host name.
.SH "CONFIG"
.IX Header "CONFIG"
Create a config file by using the the sample configuration file \fI/usr/share/mon/examples/mon.conf.sample\fR into one of the following (or into several places):
.PP
.Vb 4
\&    /etc/mon.conf
\&    /etc/mon.d/*.conf
\&    ~/.mon.conf
\&    ~/.mon.d/*.conf
.Ve
.PP
The last config file always overwrites the values configured in the previous config files. The password can be specified in plain text in restlos.auth.password. If that does not exist it can be in restlos.auth.password.enc but Base64 encoded. Example:
.PP
.Vb 1
\&  bash \-c \*(Aqread \-s PASSWORD; tr \-d "\en" <<< "$PASSWORD" | base64\*(Aq
.Ve
.PP
This can be overwritten with the \s-1MON_CONFIG\s0 environment variable or the \-\-config= or \-c= switch.
.PP
It's also possible to overwrite each single config line via command line option (see \-\-foo.bar=value above).
.PP
Some configuration options also support default values. Read the comments of the sample config file to find out more about that.
.SH "STDOUT and STDERR"
.IX Header "STDOUT and STDERR"
\&\s-1JSON\s0 output is always printed to \s-1STDOUT\s0. Makes it easier to redirect it into a file. All other output is always printed to \s-1STDERR\s0, so it's not interfering with the \s-1JSON\s0 stuff.
.SH "JSON BACKUPS"
.IX Header "JSON BACKUPS"
Mon writes backups of the \s-1JSON\s0 data before data is going to be manipulated into the backups.dir directory. Backups older than backups.keep.days days will be deleted on each run automatically, thus the disk space and inodes should not be a problem.
.PP
Backup file names are in the form of
.PP
.Vb 1
\&    backup_%Y%m%d_%H%M%S_CATEGORY.json
.Ve
.PP
To recover data just do something like this:
.PP
.Vb 2
\&    vim ~/.mon/BACKFILE # For the case you want to edit some stuff
\&    m post CATEGORY < ~/.mon/BACKFILE
.Ve
.PP
Set backups.disable to 1 to disable backups.
.SH ""
.IX Header ""
\&\s-1ZSH\s0 users can copy or include the following file to have shell auto completion: \fI/usr/share/mon/contrib/zsh/_mon.zsh\fR. You can add \fI/usr/share/mon/contrib/zsh\fR to the \s-1FPATH\s0 variable and run \fBcompinit m mon\fR.
.PP
There is nothing like that for the Bash atm.
=head1 \s-1ZSH\s0 \s-1AUTO\s0 \s-1COMPLETION\s0
.PP
\&\s-1ZSH\s0 users can copy or include the following file to have shell auto completion: \fI/usr/share/mon/contrib/zsh/_mon.zsh\fR. You can add \fI/usr/share/mon/contrib/zsh\fR to the \s-1FPATH\s0 variable and run \fBcompinit m mon\fR.
.PP
There is nothing like that for the Bash atm.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.SS "\s-1COLOR\s0 \s-1OUTPUT\s0"
.IX Subsection "COLOR OUTPUT"
By default mon uses Term::ANSIColor to produce colorful text output. To disable that just set the \s-1MON_COLORFUL\s0 environment variable to 0. It's not possible to specify this in a config file because in verbose mode there is stuff printed already before parsing it.
.SS "\s-1SSL\s0 \s-1CA\s0 \s-1CERTIFICATE\s0"
.IX Subsection "SSL CA CERTIFICATE"
For restlos.api.host \fI./ca.pem\fR or \fI/etc/ssl/certs/ca.pem\fR or \fI/usr/share/mon/ca.pem\fR is used (the first \s-1CA\s0 file found actually).  Alternatively point the \s-1HTTPS_CA_FILE\s0 environment variable to the \s-1CA\s0 file to use.
.PP
The file \fI/etc/ssl/certs/ca.pem\fR actually comes from the recommended package dependency ca-root-cert, which should be in the Unitix deb repository.
.SS "\s-1SYSLOG\s0"
.IX Subsection "SYSLOG"
it's possible to set the \s-1MON_SYSLOG\s0 environment variable to a value != to logg to syslog. Mon always uses \s-1LOG_LOCAL0\s0.
.SH "EXIT CODE"
.IX Header "EXIT CODE"
.IP "0" 4
Mon terminates without any error.
.IP "2" 4
.IX Item "2"
The \s-1API\s0 itself terminates with an error (e.g. syntax error).
.IP "3" 4
.IX Item "3"
Some hard error raised by mon itself.
.PP
All other exit codes are undefined and/or caused by the autodie Perl module.
.SH "INPUT JSON FORMAT"
.IX Header "INPUT JSON FORMAT"
The mon supports everything that the RESTlos \s-1API\s0 supports as valid \s-1JSON\s0 input. In addition mon also supports to insert a single object in list style format.
.PP
Example:
.PP
.Vb 1
\&  [ "address", "172.19.184.14", "host_name", "server01.example.com" ]
.Ve
.PP
Will be interpreted by mon as
.PP
.Vb 1
\&  { "address" : "172.19.184.14", "host_name" : "server01.example.com" }
.Ve
.PP
and pushed this way into the \s-1API\s0.
.SH "MORE EXAMPLES"
.IX Header "MORE EXAMPLES"
Get a list of possible commands
.PP
.Vb 1
\&    m
.Ve
.PP
Get a list of possible categories
.PP
.Vb 1
\&    m get
.Ve
.PP
Get all defined category objects (e.g. 'mon get host' gets all hosts)
.PP
.Vb 1
\&    m get CATEGORY
.Ve
.PP
Print notice with all possible fields
.PP
.Vb 1
\&    m get CATEGORY where
.Ve
.PP
Get some stuff
.PP
.Vb 1
\&    m get CATEGORY where FIELDNAME like VALUE [and FIELDNAME2 like VALUE2 ...]
.Ve
.PP
Update objects per \s-1POST\s0 request (e.g. mon post contact < pbuetow.json)
.PP
.Vb 1
\&    m post CATEGORY < object.json
.Ve
.PP
Get some stuff, open the results in \f(CW$EDITOR\fR (vim by default), commit the changes back via put.
.PP
.Vb 1
\&    m edit CATEGORY where FIELDNAME like VALUE [and FIELDNAME2 like VALUE2 ...]
.Ve
.PP
Get some stuff, open the results in \f(CW$PAGER\fR (view by default), just to see in read only mode.
.PP
.Vb 1
\&    m view CATEGORY where FIELDNAME like VALUE [and FIELDNAME2 like VALUE2 ...]
.Ve
.PP
Validate the current monitoring configuration
.PP
.Vb 1
\&    m verify
.Ve
.PP
Restart/reload the monitoring configuration by restarting the monitoring core. Validation of the configuration is done by the monitoring \s-1API\s0. On failure the previous version will be rolled back automatically by the \s-1API\s0.
.PP
.Vb 1
\&    m restart
.Ve
.PP
Run a command in verbose mode
.PP
.Vb 1
\&    m verbose get
.Ve
.PP
Fetch all categories
.PP
.Vb 1
\&    ( m get 2>&1 ) | while read category; do m get $category > $category.json; done
.Ve
.PP
Delete all contacts with alias like Foo
.PP
.Vb 1
\&    m delete contact where alias like Foo
.Ve
.PP
Update fields of an existing object
.PP
.Vb 1
\&    m update contact set alias = "Paul Buetow" and _CUSTOM_NEW = "foo" where alias like Buetow
.Ve
.PP
Create some fields, and delete them again
.PP
.Vb 1
\&    m update contact set _FOO = "Master of the Universe" and _BAR = "Beer" where email like 1und1
\&
\&    m update contact delete _FOO and _BAR where email like 1und1
.Ve
.PP
Insert a new contact (raises an error if contact already exists)
.PP
.Vb 1
\&    m insert contact set name = "Master of the Universe" and _BAR = "Beer"
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Buetow \- <http://mon.buetow.org>