-
Notifications
You must be signed in to change notification settings - Fork 0
/
monit.1
4126 lines (4126 loc) · 167 KB
/
monit.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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 "MONIT 1"
.TH MONIT 1 "www.mmonit.com" "August 20. 2012" "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"
Monit \- utility for monitoring services on a Unix system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBmonit\fR [options] {arguments}
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBmonit\fR is a utility for managing and monitoring processes,
programs, files, directories and filesystems on a Unix system.
Monit conducts automatic maintenance and repair and can execute
meaningful causal actions in error situations. E.g. Monit can
start a process if it does not run, restart a process if it does
not respond and stop a process if it uses too much resources. You
can use Monit to monitor files, directories and filesystems for
changes, such as timestamps changes, checksum changes or size
changes.
.PP
Monit is controlled via an easy to configure control file based
on a free-format, token-oriented syntax. Monit logs to syslog or
to its own log file and notifies you about error conditions via
customizable alert messages. Monit can perform various \s-1TCP/IP\s0
network checks, protocol checks and can utilize \s-1SSL\s0 for such
checks. Monit provides a http(s) interface and you may use a
browser to access the Monit program.
.SH "GENERAL OPERATION"
.IX Header "GENERAL OPERATION"
The behavior of Monit is controlled by command-line options
\&\fIand\fR a run control file, monitrc,
the syntax of which we describe in a later section. Command-line
options override \fI.monitrc\fR declarations.
.PP
The default location for \fImonitrc\fR is \fI~/.monitrc\fR. If this
file does not exist, Monit will try \fI/etc/monitrc\fR and a few
other places. See \s-1FILES\s0 for details. You can also
specify the control file directly by using the \fI\-c\fR command-line
switch to monit. For instance,
.PP
.Vb 1
\& $ monit \-c /var/monit/monitrc
.Ve
.PP
Before Monit is started the first time, you can test the control
file for syntax errors:
.PP
.Vb 2
\& $ monit \-t
\& $ Control file syntax OK
.Ve
.PP
If there was an error, Monit will print an error message to the
console, including the line number in the control file from where
the error was found.
.PP
Once you have a working Monit control file you can start Monit
from the console, like so:
.PP
.Vb 1
\& $ monit
.Ve
.PP
You can change some configuration directives via command-line
switches, but for simplicity it is recommended that you put these
in the control file.
.PP
If all goes well, Monit will now detach from the terminal and run
as a background process, i.e. as a daemon process. As a daemon,
Monit runs in cycles; It monitor services, then goes to sleep for
a configured period, then wakes up and start monitoring again in
an endless loop.
.SS "Options"
.IX Subsection "Options"
The following options are recognized by Monit. However, it is
recommended that you set options (when applicable) directly in
the \fI.monitrc\fR control file.
.PP
\&\fB\-c\fR \fIfile\fR
Use this control file
.PP
\&\fB\-d\fR \fIn\fR
Run Monit as a daemon once per \fIn\fR seconds. Or use \fI\*(L"set
daemon\*(R"\fR in monitrc.
.PP
\&\fB\-g\fR \fIname\fR
Set group name for start, stop, restart, monitor and
unmonitor action.
.PP
\&\fB\-l\fR \fIlogfile\fR
Print log information to this file. Or use \fI\*(L"set logfile\*(R"\fR
in monitrc.
.PP
\&\fB\-p\fR \fIpidfile\fR
Use this lock file in daemon mode. Or use \fI\*(L"set pidfile\*(R"\fR
in monitrc.
.PP
\&\fB\-s\fR \fIstatefile\fR
Write state information to this file. Or use \fI\*(L"set
statefile\*(R"\fR in monitrc.
.PP
\&\fB\-I\fR
Do not run in background (needed for run from init)
.PP
\&\fB\-t\fR
Run syntax check for the control file
.PP
\&\fB\-v\fR
Verbose mode, work noisy (diagnostic output)
.PP
\&\fB\-vv\fR
Very verbose mode, same as \-v plus log stack-trace on error
.PP
\&\fB\-H\fR \fI[filename]\fR
Print \s-1MD5\s0 and \s-1SHA1\s0 hashes of the file or of stdin if the
filename is omitted; Monit will exit afterwards
.PP
\&\fB\-V\fR
Print version number and patch level
.PP
\&\fB\-h\fR
Print a help text
.SS "Arguments"
.IX Subsection "Arguments"
Once you have Monit running as a daemon process, you can call
Monit with one of the following arguments. Monit will then
connect to the Monit daemon (on \s-1TCP\s0 port 127.0.0.1:2812 by
default) and ask the Monit daemon to perform the requested
action. In other words; calling monit without arguments starts
the Monit daemon, and calling monit \fIwith\fR arguments enables you
to communicate with the Monit daemon process.
.IP "start all" 4
.IX Item "start all"
Start all services listed in the control file and enable
monitoring for them. If the group option is set (\fI\-g\fR), only
start and enable monitoring of services in the named group (\*(L"all\*(R"
is not required in this case).
.IP "start name" 4
.IX Item "start name"
Start the named service and enable monitoring for it. The name is
a service entry name from the monitrc file.
.IP "stop all" 4
.IX Item "stop all"
Stop all services listed in the control file and disable their
monitoring. If the group option is set, only stop and disable
monitoring of the services in the named group (all" is not
required in this case).
.IP "stop name" 4
.IX Item "stop name"
Stop the named service and disable its monitoring. The name is a
service entry name from the monitrc file.
.IP "restart all" 4
.IX Item "restart all"
Stop and start \fIall\fR services. If the group option is set, only
restart the services in the named group (\*(L"all\*(R" is not required in
this case).
.IP "restart name" 4
.IX Item "restart name"
Restart the named service. The name is a service entry name from
the monitrc file.
.IP "monitor all" 4
.IX Item "monitor all"
Enable monitoring of all services listed in the control file. If
the group option is set, only start monitoring of services in the
named group (\*(L"all\*(R" is not required in this case).
.IP "monitor name" 4
.IX Item "monitor name"
Enable monitoring of the named service. The name is a service
entry name from the monitrc file. Monit will also enable
monitoring of all services this service depends on.
.IP "unmonitor all" 4
.IX Item "unmonitor all"
Disable monitoring of all services listed in the control file. If
the group option is set, only disable monitoring of services in
the named group (\*(L"all\*(R" is not required in this case).
.IP "unmonitor name" 4
.IX Item "unmonitor name"
Disable monitoring of the named service. The name is a service
entry name from the monitrc file. Monit will also disable
monitoring of all services that depends on this service.
.IP "status" 4
.IX Item "status"
Print status information of each service.
.IP "summary" 4
.IX Item "summary"
Print a short status summary.
.IP "reload" 4
.IX Item "reload"
Reinitialize a running Monit daemon, the daemon will reread its
configuration, close and reopen log files.
.IP "quit" 4
.IX Item "quit"
Kill the Monit daemon process
.IP "validate" 4
.IX Item "validate"
Check all services listed in the control file. This action is
also the default behavior when Monit runs in daemon mode.
.IP "procmatch regex" 4
.IX Item "procmatch regex"
Allows for easy testing of pattern for process match check. The
command takes regular expression as an argument and displays all
running processes matching the pattern.
.SH "WHAT TO MONITOR?"
.IX Header "WHAT TO MONITOR?"
You can use Monit to monitor daemon \fBprocesses\fR or similar
programs running on localhost. Monit is particularly useful for
monitoring daemon processes, such as those started at system boot
time from /etc/init.d/. For instance sendmail, sshd, apache and
mysql. In contrast to many other monitoring systems, Monit can act if
an error situation should occur, e.g.; if sendmail is not
running, monit can start sendmail again automatically or if
apache is using too many resources (e.g. if a DoS attack is in
progress) Monit can stop or restart apache and send you an alert
message. Monit can also monitor process characteristics, such as
how much memory or cpu cycles a process is using.
.PP
You can also use Monit to monitor \fBfiles\fR, \fBdirectories\fR and
\&\fBfilesystems\fR on localhost. Monit can monitor these items for
changes, such as timestamps changes, checksum changes or size
changes. This is also useful for security reasons \- you can
monitor the md5 or sha1 checksum of files that should not change
and get an alert or perform an action if they should change.
.PP
Monit can monitor \fBnetwork connections\fR to various servers,
either on localhost or on remote hosts. \s-1TCP\s0, \s-1UDP\s0 and Unix Domain
Sockets are supported. Network test can be performed on a
protocol level; Monit has built-in tests for the main Internet
protocols, such as \s-1HTTP\s0, \s-1SMTP\s0 etc. Even if a protocol is not
supported you can still test the server because you can configure
Monit to send any data and test the response from the server.
.PP
Monit can be used to test \fBprograms\fR or scripts at certain
times, much like cron, but in addition, you can test the exit
value of a program and perform an action or send an alert if the
exit value indicate an error. This means that you can use Monit
to perform any type of check you can write a script for.
.PP
Finally, Monit can be used to monitor general \fBsystem\fR resources
on localhost such as overall \s-1CPU\s0 usage, Memory and Load Average.
.SH "THE MONIT CONTROL FILE"
.IX Header "THE MONIT CONTROL FILE"
Monit is configured and controlled via a control file called
\&\fImonitrc\fR. The default location for this file is ~/.monitrc. If
this file does not exist, Monit will try /etc/monitrc, then
\&\f(CW@sysconfdir\fR@/monitrc and finally ./monitrc. The value of
\&\f(CW@sysconfdir\fR@ is given at configure time as ./configure
\&\-\-sysconfdir. For instance, using \fI./configure \-\-sysconfdir
/var/monit/etc\fR will make Monit search for \fImonitrc\fR in
\&\fI/var/monit/etc\fR
.PP
Monit uses its own Domain Specific Language (\s-1DSL\s0); The control
file consists of a series of service entries and global option
statements in a free-format, token-oriented syntax.
.PP
Comments begin with a \fB#\fR and extend through the end of the
line. There are three kinds of tokens in the control file:
\&\fIkeywords\fR, \fInumbers\fR and \fIstrings\fR. On a semantic level, the
control file consists of only three type of entries:
.IP "1. Global set-statements" 4
.IX Item "1. Global set-statements"
A global set-statement starts with the keyword \fIset\fR and the
item to configure.
.IP "2. Global include-statement" 4
.IX Item "2. Global include-statement"
The include statement consists of the keyword \fIinclude\fR and
a glob string.
.IP "3. One or more service entry statements." 4
.IX Item "3. One or more service entry statements."
A service entry starts with the keyword \fIcheck\fR followed by the
service type.
.PP
The meaning of the various statements will be explained in the
following sections.
.SH "LOGGING"
.IX Header "LOGGING"
Monit will log status and error messages to a log file. Use the
\&\fIset logfile\fR statement in the monitrc control file. To setup
Monit to log to its own logfile, use e.g. \fIset logfile
/var/log/monit.log\fR. If \fBsyslog\fR is given as a value for the
\&\fI\-l\fR command-line switch (or the keyword \fIset logfile syslog\fR
is found in the control file) Monit will use the \fBsyslog\fR system
daemon to log messages with a priority assigned to each message
based on the context. To turn off logging, simply do not set the
logfile in the control file (and of course, do not use the \-l
switch)
.SH "DAEMON MODE"
.IX Header "DAEMON MODE"
Use
.PP
.Vb 1
\& set daemon n (where n is a number in seconds)
.Ve
.PP
to specify Monit's poll cycle length and run Monit in daemon
mode. You must specify a numeric argument which is a polling
interval in seconds. In daemon mode, Monit detaches from the
console, puts itself in the background and runs continuously,
monitoring each specified service and then goes to sleep for the
given poll interval, wakes up and start monitoring again in an
endless cycle.
.PP
Alternatively, you can use the \fI\-d\fR command line switch to set
the poll interval, but it is strongly recommended to set the poll
interval in your \fI~/.monitrc\fR file, by using \fIset daemon\fR.
.PP
Monit will then always start in daemon mode. If you do not use
this statement and do not start monit with the \-d option, Monit
will just run through the service checks once and then exit. This
may be useful in some situations, but Monit is primarily designed
to run as a daemon process.
.PP
Calling monit with a Monit daemon running in the background sends
a wake-up signal to the daemon, forcing it to check services
immediately. Calling monit with the quit argument will kill a
running Monit daemon process instead of waking it up.
.SH "INIT SUPPORT"
.IX Header "INIT SUPPORT"
The \fIset init\fR statement prevents Monit from transforming itself
into a daemon process. Instead Monit will run as a foreground
process. (You should still use set daemon to specify the poll
cycle).
.PP
This is required to run Monit from init. Using init to start
Monit is probably the best way to run Monit if you want to be
certain that you always have a running Monit daemon on your
system. Another option is to run Monit from crontab. In any case,
you should make sure that the control file does not have any
syntax errors before you start Monit from init or crontab.
.PP
To setup Monit to run from init, you can either use the set init
statement in Monit's control file or use the \-I option from the
command line. Here is what you must add to /etc/inittab:
.PP
.Vb 2
\& # Run Monit in standard run\-levels
\& mo:2345:respawn:/usr/local/bin/monit \-Ic /etc/monitrc
.Ve
.PP
After you have modified init's configuration file, you can run
the following command to re-examine /etc/inittab and start Monit:
.PP
.Vb 1
\& telinit q
.Ve
.PP
For systems without telinit:
.PP
.Vb 1
\& kill \-1 1
.Ve
.PP
If Monit is used to monitor services that are also started at
boot time (e.g. services started via \s-1SYSV\s0 init rc scripts or via
inittab) then, in some cases, a race condition could occur. That
is; if a service is slow to start, Monit can assume that the
service is not running and possibly try to start it and raise an
alert, while, in fact the service is already about to start or
already in its startup sequence. Please see the \s-1FAQ\s0 for a
solution to this problem.
.SH "INCLUDE FILES"
.IX Header "INCLUDE FILES"
The Monit control file, \fImonitrc\fR, can include additional
configuration files. This feature helps one to maintain a certain
structure or to place repeating settings into one file. Include
statements can be placed at virtually any spot. The syntax is the
following:
.PP
.Vb 1
\& include globstring
.Ve
.PP
The globstring is any kind of string as defined in \fIglob\fR\|(7). Thus,
you can refer to a single file or you can load several files at
once. If you want to use whitespace in your string the globstring
need to be embedded into quotes (') or double quotes ("). If the
globstring matches a directory instead of a file, it is silently
ignored.
.PP
Any \fIinclude\fR statements in included files are parsed as in the
main control file.
.PP
If the globstring matches several results, the files are included
in a non sorted manner. If you need to rely on a certain order,
you might need to use single \fIinclude\fR statements.
.PP
An example,
.PP
.Vb 1
\& include /etc/monit.d/*.cfg
.Ve
.PP
This will load any file matching the globstring. That is, all
files in \fI/etc/monit.d\fR that ends with the prefix \fI.cfg\fR.
.SH "GROUP SUPPORT"
.IX Header "GROUP SUPPORT"
Service entries in the control file, \fImonitrc\fR, can be grouped
together by the \fIgroup\fR statement. The syntax is simply (keyword
in capital):
.PP
.Vb 1
\& GROUP groupname
.Ve
.PP
With this statement it is possible to group similar service
entries together and manage them as a whole. Monit provides
functions to start, stop, restart, monitor and unmonitor a
group of services, like so:
.PP
To start a group of services from the console:
.PP
.Vb 1
\& Monit \-g <groupname> start
.Ve
.PP
To stop a group of services:
.PP
.Vb 1
\& Monit \-g <groupname> stop
.Ve
.PP
To restart a group of services:
.PP
.Vb 1
\& Monit \-g <groupname> restart
.Ve
.PP
Note:
the \fIstatus\fR and \fIsummary\fR commands don't support the \-g
option and will print the state of all services.
.PP
Service can be added to multiple groups by adding group statement
multiple times:
.PP
.Vb 2
\& group www
\& group filesystem
.Ve
.SH "MONITORING MODE"
.IX Header "MONITORING MODE"
Monit supports three monitoring modes per service: \fIactive\fR,
\&\fIpassive\fR and \fImanual\fR. See also the example section below for
usage of the mode statement.
.PP
In \fIactive\fR mode, Monit will monitor a service and in case of
problems Monit will act and raise alerts, start, stop or restart
the service. Active mode is the default mode.
.PP
In \fIpassive\fR mode, Monit will passively monitor a service and
specifically \fBnot\fR try to fix a problem, but it will still raise
alerts in case of a problem.
.PP
For use in clustered environments there is also a \fImanual\fR
mode. In this mode, Monit will enter \fIactive\fR mode \fBonly\fR if a
service was brought under monit's control, for example by
executing the following command in the console:
.PP
.Vb 2
\& Monit start sybase
\& (Monit will call sybase\*(Aqs start method and enable monitoring)
.Ve
.PP
If a service was not started by Monit or was stopped or disabled
for example by:
.PP
.Vb 2
\& Monit stop sybase
\& (Monit will call sybase\*(Aqs stop method and disable monitoring)
.Ve
.PP
Monit will then not monitor the service. This allows for having
services configured in monitrc and start it with Monit only if it
should run. This feature can be used to build a simple failsafe
cluster.
.PP
A service's monitoring state is persistent across Monit restart.
This means that you probably would like to make certain that
services in manual mode are stopped or in unmonitored mode at
server shutdown. Do for instance the following in a server
shutdown script:
.PP
.Vb 1
\& Monit stop sybase
.Ve
.PP
or
.PP
.Vb 1
\& Monit unmonitor sybase
.Ve
.PP
If you use Monit in a HA-cluster you should place the state file
in a temporary filesystem so if the machine should crash and the
stand-by machine take over services, any manual monitoring mode
services that were started on the crashed machine won't be
started on reboot. Use for example:
.PP
.Vb 1
\& set statefile /tmp/monit.state
.Ve
.SH "ALERT MESSAGES"
.IX Header "ALERT MESSAGES"
Monit will raise an email alert in the following situations:
.PP
.Vb 10
\& o A service timed out
\& o A service does not exist
\& o A service related data access problem
\& o A service related program execution problem
\& o A service is of invalid object type
\& o A program status failed
\& o A icmp problem
\& o A port connection problem
\& o A resource statement match
\& o A file checksum problem
\& o A file size problem
\& o A file/directory timestamp problem
\& o A file/directory/filesystem permission problem
\& o A file/directory/filesystem uid problem
\& o A file/directory/filesystem gid problem
\& o An action is done per administrator\*(Aqs request
.Ve
.PP
Monit will send an alert each time a monitored object changed.
This involves:
.PP
.Vb 8
\& o Monit started, stopped or reloaded
\& o A file checksum changed
\& o A file size changed
\& o A file content match
\& o A file/directory timestamp changed
\& o A filesystem mount flags changed
\& o A process PID changed
\& o A process PPID changed
.Ve
.PP
You use the alert statement to notify Monit that you want alert
messages sent to an email address. If you do not specify an alert
statement, Monit will not send alert messages.
.PP
There are two forms of alert statement:
.PP
.Vb 2
\& o Global \- common for all services
\& o Local \- per service
.Ve
.PP
In both cases you can use more than one alert statement. In other
words, you can send many different emails to many different
addresses.
.PP
Recipients in the global and in the local lists are alerted when
a service failed, recovered or changed. If the same email address
is in the global and in the local list, Monit will only send one
alert. Local (per service) defined alert email addresses override
global addresses in case of a conflict. Finally, you may choose
to only use a global alert list (recommended), a local per
service list or both.
.PP
It is also possible to disable the global alerts locally for
particular service(s) and recipients.
.SS "Setting a global alert statement"
.IX Subsection "Setting a global alert statement"
If a change occurred on a monitored services, Monit will send an
alert to all recipients in the global list who has registered
interest for the event type. Here is the syntax for the global
alert statement:
.IP "\s-1SET\s0 \s-1ALERT\s0 mail-address [ [\s-1NOT\s0] {events}] [\s-1MAIL\-FORMAT\s0 {mail\-format}] [\s-1REMINDER\s0 number]" 4
.IX Item "SET ALERT mail-address [ [NOT] {events}] [MAIL-FORMAT {mail-format}] [REMINDER number]"
.PP
Simply using the following in the global section of monitrc:
.PP
.Vb 1
\& set alert foo@bar
.Ve
.PP
will send a default email to the address foo@bar whenever an
event occurred on any service. Such an event may be that a
service timed out, a service doesn't exist and so on. If you want
to send alert messages to more email addresses, add a \fIset alert
\&'email'\fR statement for each address.
.PP
For explanations of the \fIevents, MAIL-FORMAT and \s-1REMINDER\s0\fR
keywords above, please see below.
.PP
You can also use the \s-1NOT\s0 option ahead of the events list which
will reverse the meaning of the list. That is, only send alerts
for events \fInot\fR in the list. This can save you some
configuration bytes if you are interested in most events except a
few.
.SS "Setting a local alert statement"
.IX Subsection "Setting a local alert statement"
Each service can also have its own recipient list.
.IP "\s-1ALERT\s0 mail-address [ [\s-1NOT\s0] {events}] [\s-1MAIL\-FORMAT\s0 {mail\-format}] [\s-1REMINDER\s0 number]" 4
.IX Item "ALERT mail-address [ [NOT] {events}] [MAIL-FORMAT {mail-format}] [REMINDER number]"
.PP
or
.IP "\s-1NOALERT\s0 mail-address" 4
.IX Item "NOALERT mail-address"
.PP
If you only want an alert message sent for certain events and for
certain service(s), for example only for timeout events or only
if a service died, then postfix the alert-statement with a filter
block:
.PP
.Vb 3
\& check process myproc with pidfile /var/run/my.pid
\& alert foo@bar only on { timeout, nonexist }
\& ...
.Ve
.PP
(\fIonly\fR and \fIon\fR are noise keywords, ignored by Monit. As a
side note; Noise keywords are used in the control file grammar to
make an entry resemble English and thus make it easier to read
(or, so goes the philosophy). The full set of available noise
keywords are listed below in the Control File section).
.PP
You can also setup to send alerts for all events except some by
putting the word \fInot\fR ahead of the list. For example, if you
want to receive alerts for all events except Monit instance
events, you can write (note that the noise words 'but' and 'on'
are optional):
.PP
.Vb 3
\& check system myserver
\& alert foo@bar but not on { instance }
\& ...
.Ve
.PP
instead of:
.PP
.Vb 10
\& alert foo@bar on { action
\& checksum
\& connection
\& content
\& data
\& exec
\& fsflags
\& gid
\& icmp
\& invalid
\& nonexist
\& permission
\& pid
\& ppid
\& resource
\& size
\& status
\& timeout
\& timestamp
\& uid
\& uptime }
.Ve
.PP
This will send alerts for all events to foo@bar, except Monit
instance events. An instance event \s-1BTW\s0, is an event fired
whenever the Monit program start or stop.
.PP
Event filtering can be used to send an email to different email
addresses depending on the events that occurred. For instance:
.PP
.Vb 3
\& alert foo@bar { nonexist, timeout, resource, icmp, connection }
\& alert security@bar on { checksum, permission, uid, gid }
\& alert manager@bar
.Ve
.PP
This will send an alert message to foo@bar whenever a nonexist,
timeout, resource or connection problem occurs and a message to
security@bar if a checksum, permission, uid or gid problem
occurs. And finally, a message to manager@bar whenever any error
event occurs.
.PP
Here is the list of events you can use in a mail-filter: \fIaction,
checksum, connection, content, data, exec, fsflags, gid, icmp,
instance, invalid, nonexist, permission, pid, ppid, resource, size,
status, timeout, timestamp, uid, uptime\fR
.PP
You can also disable the alerts locally using the \s-1NOALERT\s0
statement. This is useful if you have lots of services monitored
and are using the global alert statement, but don't want to
receive alerts for some minor subset of services:
.PP
.Vb 1
\& noalert appadmin@bar
.Ve
.PP
For example, if you stick the noalert statement in a 'check
system' entry, you won't receive system related alerts (such as
Monit instance started/stopped/reloaded alert, system overloaded
alert, etc.) but will receive alerts for all other monitored
services.
.PP
The following example will alert foo@bar on all events on all
services by default, except the service mybar which will send an
alert only on timeout. The trick is based on the fact that local
definition of the same recipient overrides the global setting
(including registered events and mail format):
.PP
.Vb 1
\& set alert foo@bar
\&
\& check process myfoo with pidfile /var/run/myfoo.pid
\& ...
\& check process mybar with pidfile /var/run/mybar.pid
\& alert foo@bar only on { timeout }
.Ve
.SS "Alert message layout"
.IX Subsection "Alert message layout"
Monit provides a default mail message layout that is short and to
the point. Here's an example of a standard alert mail sent by
monit:
.PP
.Vb 4
\& From: monit@tildeslash.com
\& Subject: Monit alert \-\- Does not exist apache
\& To: hauk@tildeslash.com
\& Date: Thu, 04 Sep 2003 02:33:03 +0200
\&
\& Does not exist Service apache
\&
\& Date: Thu, 04 Sep 2003 02:33:03 +0200
\& Action: restart
\& Host: www.tildeslash.com
\&
\& Your faithful employee,
\& monit
.Ve
.PP
If you want to, you can change the format of this message with
the optional \fImail-format\fR statement. The syntax for this
statement is as follows:
.PP
.Vb 8
\& mail\-format {
\& from: monit@localhost
\& reply\-to: support@domain.com
\& subject: $SERVICE $EVENT at $DATE
\& message: Monit $ACTION $SERVICE at $DATE on $HOST: $DESCRIPTION.
\& Yours sincerely,
\& monit
\& }
.Ve
.PP
Where the keyword \fIfrom:\fR is the email address Monit should
pretend it is sending from. It does not have to be a real mail
address, but it must be a proper formatted mail address, on the
form: name@domain. The \fIreply-to:\fR keyword can be used to set
the reply-to mail header. The keyword \fIsubject:\fR is for the
email subject line. The subject must be on only \fIone\fR line. The
\&\fImessage:\fR keyword denotes the mail body. If used, this keyword
should always be the last in a mail-format statement. The mail
body can be as long as you want, but must \fBnot\fR contain the '}'
character.
.PP
All of these format keywords are optional, but if used, you must
provide at least one. Thus if you only want to change the from
address Monit is using you can do:
.PP
.Vb 1
\& set alert foo@bar with mail\-format { from: bofh@bar.baz }
.Ve
.PP
From the previous example you will notice that some special \f(CW$XXX\fR
variables were used. If used, they will be substituted and
expanded into the text with these values:
.IP "\(bu" 4
\&\fI\f(CI$EVENT\fI\fR
.Sp
.Vb 2
\& A string describing the event that occurred. The values are
\& fixed and are:
\&
\& Event: | Failure state: | Success state:
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ACTION | "Action done" | "Action done"
\& CHECKSUM | "Checksum failed" | "Checksum succeeded"
\& CONNECTION| "Connection failed" | "Connection succeeded"
\& CONTENT | "Content failed", | "Content succeeded"
\& DATA | "Data access error" | "Data access succeeded"
\& EXEC | "Execution failed" | "Execution succeeded"
\& FSFLAG | "Filesystem flags failed"| "Filesystem flags succeeded"
\& GID | "GID failed" | "GID succeeded"
\& ICMP | "ICMP failed" | "ICMP succeeded"
\& INSTANCE | "Monit instance changed" | "Monit instance changed not"
\& INVALID | "Invalid type" | "Type succeeded"
\& NONEXIST | "Does not exist" | "Exists"
\& PERMISSION| "Permission failed" | "Permission succeeded"
\& PID | "PID failed" | "PID succeeded"
\& PPID | "PPID failed" | "PPID succeeded"
\& RESOURCE | "Resource limit matched" | "Resource limit succeeded"
\& SIZE | "Size failed" | "Size succeeded"
\& STATUS | "Status failed" | "Status succeeded"
\& TIMEOUT | "Timeout" | "Timeout recovery"
\& TIMESTAMP | "Timestamp failed" | "Timestamp succeeded"
\& UID | "UID failed" | "UID succeeded"
\& UPTIME | "Uptime failed" | "Uptime succeeded"
.Ve
.IP "\(bu" 4
\&\fI\f(CI$SERVICE\fI\fR
.Sp
.Vb 1
\& The service entry name in monitrc
.Ve
.IP "\(bu" 4
\&\fI\f(CI$DATE\fI\fR
.Sp
.Vb 1
\& The current time and date (RFC 822 date style).
.Ve
.IP "\(bu" 4
\&\fI\f(CI$HOST\fI\fR
.Sp
.Vb 1
\& The name of the host Monit is running on
.Ve
.IP "\(bu" 4
\&\fI\f(CI$ACTION\fI\fR
.Sp
.Vb 2
\& The name of the action which was done. Action names are fixed
\& and are:
\&
\& Action: | Name:
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ALERT | "alert"
\& EXEC | "exec"
\& RESTART | "restart"
\& START | "start"
\& STOP | "stop"
\& UNMONITOR| "unmonitor"
.Ve
.IP "\(bu" 4
\&\fI\f(CI$DESCRIPTION\fI\fR
.Sp
.Vb 1
\& The description of the error condition
.Ve
.SS "Setting a global mail format"
.IX Subsection "Setting a global mail format"
It is possible to set a standard mail format with the following
global set-statement (keywords are in capital):
.IP "\s-1SET\s0 MAIL-FORMAT {mail\-format}" 4
.IX Item "SET MAIL-FORMAT {mail-format}"
.PP
Format set with this statement will apply to every alert
statement that does \fInot\fR have its own specified mail-format.
This statement is most useful for setting a default from address
for messages sent by monit, like so:
.PP
.Vb 1
\& set mail\-format { from: monit@foo.bar.no }
.Ve
.SS "Setting an error reminder"
.IX Subsection "Setting an error reminder"
Monit by default sends just one error notification if a service
failed and another when it recovered. If you want to be notified
more then once if a service remains in a failed state, you can
use the reminder option to the alert statement (keywords are in
capital):
.IP "\s-1ALERT\s0 ... [\s-1WITH\s0] \s-1REMINDER\s0 [\s-1ON\s0] number [\s-1CYCLES\s0]" 4
.IX Item "ALERT ... [WITH] REMINDER [ON] number [CYCLES]"
.PP
For example if you want to be notified each tenth cycle if a
service remains in a failed state, you can use:
.PP
.Vb 1
\& alert foo@bar with reminder on 10 cycles
.Ve
.PP
Likewise if you want to be notified on each failed cycle, you can