~ubuntu-branches/ubuntu/saucy/monit/saucy : revision 22

1

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)

2

.\"

3

.\" Standard preamble:

4

.\" ========================================================================

5

.de Sp \" Vertical space (when we can't use .PP)

6

.if t .sp .5v

7

.if n .sp

8

..

9

.de Vb \" Begin verbatim text

10

.ft CW

11

.nf

12

.ne \\$1

13

..

14

.de Ve \" End verbatim text

15

.ft R

16

.fi

17

..

18

.\" Set up some character translations and predefined strings. \*(-- will

19

.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

20

.\" double quote, and \*(R" will give a right double quote. \*(C+ will

21

.\" give a nicer C++. Capital omega is used to do unbreakable dashes and

22

.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,

23

.\" nothing in troff, for use with C<>.

24

.tr \(*W-

25

.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

26

.ie n \{\

27

. ds -- \(*W-

28

. ds PI pi

29

. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch

30

. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch

31

. ds L" ""

32

. ds R" ""

33

. ds C` ""

34

. ds C' ""

35

'br\}

36

.el\{\

37

. ds -- \|\(em\|

38

. ds PI \(*p

39

. ds L" ``

40

. ds R" ''

41

'br\}

42

.\"

43

.\" Escape single quotes in literal strings from groff's Unicode transform.

44

.ie \n(.g .ds Aq \(aq

45

.el .ds Aq '

46

.\"

47

.\" If the F register is turned on, we'll generate index entries on stderr for

48

.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index

49

.\" entries marked with X<> in POD. Of course, you'll have to process the

50

.\" output yourself in some meaningful fashion.

51

.ie \nF \{\

52

. de IX

53

. tm Index:\\$1\t\\n%\t"\\$2"

54

..

55

. nr % 0

56

. rr F

57

.\}

58

.el \{\

59

. de IX

60

..

61

.\}

62

.\"

63

.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

64

.\" Fear. Run. Save yourself. No user-serviceable parts.

65

. \" fudge factors for nroff and troff

66

.if n \{\

67

. ds #H 0

68

. ds #V .8m

69

. ds #F .3m

70

. ds #[ \f1

71

. ds #] \fP

72

.\}

73

.if t \{\

74

. ds #H ((1u-(\\\\n(.fu%2u))*.13m)

75

. ds #V .6m

76

. ds #F 0

77

. ds #[ \&

78

. ds #] \&

79

.\}

80

. \" simple accents for nroff and troff

81

.if n \{\

82

. ds ' \&

83

. ds ` \&

84

. ds ^ \&

85

. ds , \&

86

. ds ~ ~

87

. ds /

88

.\}

89

.if t \{\

90

. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

91

. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'

92

. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'

93

. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'

94

. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'

95

. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

96

.\}

97

. \" troff and (daisy-wheel) nroff accents

98

.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'

99

.ds 8 \h'\*(#H'\(*b\h'-\*(#H'

100

.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]

101

.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'

102

.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'

103

.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]

104

.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]

105

.ds ae a\h'-(\w'a'u*4/10)'e

106

.ds Ae A\h'-(\w'A'u*4/10)'E

107

. \" corrections for vroff

108

.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'

109

.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'

110

. \" for low resolution devices (crt and lpr)

111

.if \n(.H>23 .if \n(.V>19 \

112

\{\

113

. ds : e

114

. ds 8 ss

115

. ds o a

116

. ds d- d\h'-1'\(ga

117

. ds D- D\h'-1'\(hy

118

. ds th \o'bp'

119

. ds Th \o'LP'

120

. ds ae ae

121

. ds Ae AE

122

.\}

123

.rm #[ #] #H #V #F C

124

.\" ========================================================================

125

.\"

126

.IX Title "MONIT 1"

127

.TH MONIT 1 "www.mmonit.com" "August 20. 2012" "User Commands"

128

.\" For nroff, turn off justification. Always turn off hyphenation; it makes

129

.\" way too many mistakes in technical documents.

130

.if n .ad l

131

.nh

132

.SH "NAME"

133

Monit \- utility for monitoring services on a Unix system

134

.SH "SYNOPSIS"

135

.IX Header "SYNOPSIS"

136

\&\fBmonit\fR [options] {arguments}

137

.SH "DESCRIPTION"

138

.IX Header "DESCRIPTION"

139

\&\fBmonit\fR is a utility for managing and monitoring processes,

140

programs, files, directories and filesystems on a Unix system.

141

Monit conducts automatic maintenance and repair and can execute

142

meaningful causal actions in error situations. E.g. Monit can

143

start a process if it does not run, restart a process if it does

144

not respond and stop a process if it uses too much resources. You

145

can use Monit to monitor files, directories and filesystems for

146

changes, such as timestamps changes, checksum changes or size

147

changes.

148

.PP

149

Monit is controlled via an easy to configure control file based

150

on a free-format, token-oriented syntax. Monit logs to syslog or

151

to its own log file and notifies you about error conditions via

152

customizable alert messages. Monit can perform various \s-1TCP/IP\s0

153

network checks, protocol checks and can utilize \s-1SSL\s0 for such

154

checks. Monit provides a http(s) interface and you may use a

155

browser to access the Monit program.

156

.SH "GENERAL OPERATION"

157

.IX Header "GENERAL OPERATION"

158

The behavior of Monit is controlled by command-line options

159

\&\fIand\fR a run control file, monitrc,

160

the syntax of which we describe in a later section. Command-line

161

options override \fI.monitrc\fR declarations.

162

.PP

163

The default location for \fImonitrc\fR is \fI~/.monitrc\fR. If this

164

file does not exist, Monit will try \fI/etc/monitrc\fR and a few

165

other places. See \s-1FILES\s0 for details. You can also

166

specify the control file directly by using the \fI\-c\fR command-line

167

switch to monit. For instance,

168

.PP

169

.Vb 1

170

\& $ monit \-c /var/monit/monitrc

171

.Ve

172

.PP

173

Before Monit is started the first time, you can test the control

174

file for syntax errors:

175

.PP

176

.Vb 2

177

\& $ monit \-t

178

\& $ Control file syntax OK

179

.Ve

180

.PP

181

If there was an error, Monit will print an error message to the

182

console, including the line number in the control file from where

183

the error was found.

184

.PP

185

Once you have a working Monit control file you can start Monit

186

from the console, like so:

187

.PP

188

.Vb 1

189

\& $ monit

190

.Ve

191

.PP

192

You can change some configuration directives via command-line

193

switches, but for simplicity it is recommended that you put these

194

in the control file.

195

.PP

196

If all goes well, Monit will now detach from the terminal and run

197

as a background process, i.e. as a daemon process. As a daemon,

198

Monit runs in cycles; It monitor services, then goes to sleep for

199

a configured period, then wakes up and start monitoring again in

200

an endless loop.

201

.SS "Options"

202

.IX Subsection "Options"

203

The following options are recognized by Monit. However, it is

204

recommended that you set options (when applicable) directly in

205

the \fI.monitrc\fR control file.

206

.PP

207

\&\fB\-c\fR \fIfile\fR

208

Use this control file

209

.PP

210

\&\fB\-d\fR \fIn\fR

211

Run Monit as a daemon once per \fIn\fR seconds. Or use \fI\*(L"set

212

daemon\*(R"\fR in monitrc.

213

.PP

214

\&\fB\-g\fR \fIname\fR

215

Set group name for start, stop, restart, monitor and

216

unmonitor action.

217

.PP

218

\&\fB\-l\fR \fIlogfile\fR

219

Print log information to this file. Or use \fI\*(L"set logfile\*(R"\fR

220

in monitrc.

221

.PP

222

\&\fB\-p\fR \fIpidfile\fR

223

Use this lock file in daemon mode. Or use \fI\*(L"set pidfile\*(R"\fR

224

in monitrc.

225

.PP

226

\&\fB\-s\fR \fIstatefile\fR

227

Write state information to this file. Or use \fI\*(L"set

228

statefile\*(R"\fR in monitrc.

229

.PP

230

\&\fB\-I\fR

231

Do not run in background (needed for run from init)

232

.PP

233

\&\fB\-t\fR

234

Run syntax check for the control file

235

.PP

236

\&\fB\-v\fR

237

Verbose mode, work noisy (diagnostic output)

238

.PP

239

\&\fB\-vv\fR

240

Very verbose mode, same as \-v plus log stack-trace on error

241

.PP

242

\&\fB\-H\fR \fI[filename]\fR

243

Print \s-1MD5\s0 and \s-1SHA1\s0 hashes of the file or of stdin if the

244

filename is omitted; Monit will exit afterwards

245

.PP

246

\&\fB\-V\fR

247

Print version number and patch level

248

.PP

249

\&\fB\-h\fR

250

Print a help text

251

.SS "Arguments"

252

.IX Subsection "Arguments"

253

Once you have Monit running as a daemon process, you can call

254

Monit with one of the following arguments. Monit will then

255

connect to the Monit daemon (on \s-1TCP\s0 port 127.0.0.1:2812 by

256

default) and ask the Monit daemon to perform the requested

257

action. In other words; calling monit without arguments starts

258

the Monit daemon, and calling monit \fIwith\fR arguments enables you

259

to communicate with the Monit daemon process.

260

.IP "start all" 4

261

.IX Item "start all"

262

Start all services listed in the control file and enable

263

monitoring for them. If the group option is set (\fI\-g\fR), only

264

start and enable monitoring of services in the named group (\*(L"all\*(R"

265

is not required in this case).

266

.IP "start name" 4

267

.IX Item "start name"

268

Start the named service and enable monitoring for it. The name is

269

a service entry name from the monitrc file.

270

.IP "stop all" 4

271

.IX Item "stop all"

272

Stop all services listed in the control file and disable their

273

monitoring. If the group option is set, only stop and disable

274

monitoring of the services in the named group (all" is not

275

required in this case).

276

.IP "stop name" 4

277

.IX Item "stop name"

278

Stop the named service and disable its monitoring. The name is a

279

service entry name from the monitrc file.

280

.IP "restart all" 4

281

.IX Item "restart all"

282

Stop and start \fIall\fR services. If the group option is set, only

283

restart the services in the named group (\*(L"all\*(R" is not required in

284

this case).

285

.IP "restart name" 4

286

.IX Item "restart name"

287

Restart the named service. The name is a service entry name from

288

the monitrc file.

289

.IP "monitor all" 4

290

.IX Item "monitor all"

291

Enable monitoring of all services listed in the control file. If

292

the group option is set, only start monitoring of services in the

293

named group (\*(L"all\*(R" is not required in this case).

294

.IP "monitor name" 4

295

.IX Item "monitor name"

296

Enable monitoring of the named service. The name is a service

297

entry name from the monitrc file. Monit will also enable

298

monitoring of all services this service depends on.

299

.IP "unmonitor all" 4

300

.IX Item "unmonitor all"

301

Disable monitoring of all services listed in the control file. If

302

the group option is set, only disable monitoring of services in

303

the named group (\*(L"all\*(R" is not required in this case).

304

.IP "unmonitor name" 4

305

.IX Item "unmonitor name"

306

Disable monitoring of the named service. The name is a service

307

entry name from the monitrc file. Monit will also disable

308

monitoring of all services that depends on this service.

309

.IP "status" 4

310

.IX Item "status"

311

Print status information of each service.

312

.IP "summary" 4

313

.IX Item "summary"

314

Print a short status summary.

315

.IP "reload" 4

316

.IX Item "reload"

317

Reinitialize a running Monit daemon, the daemon will reread its

318

configuration, close and reopen log files.

319

.IP "quit" 4

320

.IX Item "quit"

321

Kill the Monit daemon process

322

.IP "validate" 4

323

.IX Item "validate"

324

Check all services listed in the control file. This action is

325

also the default behavior when Monit runs in daemon mode.

326

.IP "procmatch regex" 4

327

.IX Item "procmatch regex"

328

Allows for easy testing of pattern for process match check. The

329

command takes regular expression as an argument and displays all

330

running processes matching the pattern.

331

.SH "WHAT TO MONITOR?"

332

.IX Header "WHAT TO MONITOR?"

333

You can use Monit to monitor daemon \fBprocesses\fR or similar

334

programs running on localhost. Monit is particularly useful for

335

monitoring daemon processes, such as those started at system boot

336

time from /etc/init.d/. For instance sendmail, sshd, apache and

337

mysql. In contrast to many other monitoring systems, Monit can act if

338

an error situation should occur, e.g.; if sendmail is not

339

running, monit can start sendmail again automatically or if

340

apache is using too many resources (e.g. if a DoS attack is in

341

progress) Monit can stop or restart apache and send you an alert

342

message. Monit can also monitor process characteristics, such as

343

how much memory or cpu cycles a process is using.

344

.PP

345

You can also use Monit to monitor \fBfiles\fR, \fBdirectories\fR and

346

\&\fBfilesystems\fR on localhost. Monit can monitor these items for

347

changes, such as timestamps changes, checksum changes or size

348

changes. This is also useful for security reasons \- you can

349

monitor the md5 or sha1 checksum of files that should not change

350

and get an alert or perform an action if they should change.

351

.PP

352

Monit can monitor \fBnetwork connections\fR to various servers,

353

either on localhost or on remote hosts. \s-1TCP\s0, \s-1UDP\s0 and Unix Domain

354

Sockets are supported. Network test can be performed on a

355

protocol level; Monit has built-in tests for the main Internet

356

protocols, such as \s-1HTTP\s0, \s-1SMTP\s0 etc. Even if a protocol is not

357

supported you can still test the server because you can configure

358

Monit to send any data and test the response from the server.

359

.PP

360

Monit can be used to test \fBprograms\fR or scripts at certain

361

times, much like cron, but in addition, you can test the exit

362

value of a program and perform an action or send an alert if the

363

exit value indicate an error. This means that you can use Monit

364

to perform any type of check you can write a script for.

365

.PP

366

Finally, Monit can be used to monitor general \fBsystem\fR resources

367

on localhost such as overall \s-1CPU\s0 usage, Memory and Load Average.

368

.SH "THE MONIT CONTROL FILE"

369

.IX Header "THE MONIT CONTROL FILE"

370

Monit is configured and controlled via a control file called

371

\&\fImonitrc\fR. The default location for this file is ~/.monitrc. If

372

this file does not exist, Monit will try /etc/monitrc, then

373

\&\f(CW@sysconfdir\fR@/monitrc and finally ./monitrc. The value of

374

\&\f(CW@sysconfdir\fR@ is given at configure time as ./configure

375

\&\-\-sysconfdir. For instance, using \fI./configure \-\-sysconfdir

376

/var/monit/etc\fR will make Monit search for \fImonitrc\fR in

377

\&\fI/var/monit/etc\fR

378

.PP

379

Monit uses its own Domain Specific Language (\s-1DSL\s0); The control

380

file consists of a series of service entries and global option

381

statements in a free-format, token-oriented syntax.

382

.PP

383

Comments begin with a \fB#\fR and extend through the end of the

384

line. There are three kinds of tokens in the control file:

385

\&\fIkeywords\fR, \fInumbers\fR and \fIstrings\fR. On a semantic level, the

386

control file consists of only three type of entries:

387

.IP "1. Global set-statements" 4

388

.IX Item "1. Global set-statements"

389

A global set-statement starts with the keyword \fIset\fR and the

390

item to configure.

391

.IP "2. Global include-statement" 4

392

.IX Item "2. Global include-statement"

393

The include statement consists of the keyword \fIinclude\fR and

394

a glob string.

395

.IP "3. One or more service entry statements." 4

396

.IX Item "3. One or more service entry statements."

397

A service entry starts with the keyword \fIcheck\fR followed by the

398

service type.

399

.PP

400

The meaning of the various statements will be explained in the

401

following sections.

402

.SH "LOGGING"

403

.IX Header "LOGGING"

404

Monit will log status and error messages to a log file. Use the

405

\&\fIset logfile\fR statement in the monitrc control file. To setup

406

Monit to log to its own logfile, use e.g. \fIset logfile

407

/var/log/monit.log\fR. If \fBsyslog\fR is given as a value for the

408

\&\fI\-l\fR command-line switch (or the keyword \fIset logfile syslog\fR

409

is found in the control file) Monit will use the \fBsyslog\fR system

410

daemon to log messages with a priority assigned to each message

411

based on the context. To turn off logging, simply do not set the

412

logfile in the control file (and of course, do not use the \-l

413

switch)

414

.SH "DAEMON MODE"

415

.IX Header "DAEMON MODE"

416

Use

417

.PP

418

.Vb 1

419

\& set daemon n (where n is a number in seconds)

420

.Ve

421

.PP

422

to specify Monit's poll cycle length and run Monit in daemon

423

mode. You must specify a numeric argument which is a polling

424

interval in seconds. In daemon mode, Monit detaches from the

425

console, puts itself in the background and runs continuously,

426

monitoring each specified service and then goes to sleep for the

427

given poll interval, wakes up and start monitoring again in an

428

endless cycle.

429

.PP

430

Alternatively, you can use the \fI\-d\fR command line switch to set

431

the poll interval, but it is strongly recommended to set the poll

432

interval in your \fI~/.monitrc\fR file, by using \fIset daemon\fR.

433

.PP

434

Monit will then always start in daemon mode. If you do not use

435

this statement and do not start monit with the \-d option, Monit

436

will just run through the service checks once and then exit. This

437

may be useful in some situations, but Monit is primarily designed

438

to run as a daemon process.

439

.PP

440

Calling monit with a Monit daemon running in the background sends

441

a wake-up signal to the daemon, forcing it to check services

442

immediately. Calling monit with the quit argument will kill a

443

running Monit daemon process instead of waking it up.

444

.SH "INIT SUPPORT"

445

.IX Header "INIT SUPPORT"

446

The \fIset init\fR statement prevents Monit from transforming itself

447

into a daemon process. Instead Monit will run as a foreground

448

process. (You should still use set daemon to specify the poll

449

cycle).

450

.PP

451

This is required to run Monit from init. Using init to start

452

Monit is probably the best way to run Monit if you want to be

453

certain that you always have a running Monit daemon on your

454

system. Another option is to run Monit from crontab. In any case,

455

you should make sure that the control file does not have any

456

syntax errors before you start Monit from init or crontab.

457

.PP

458

To setup Monit to run from init, you can either use the set init

459

statement in Monit's control file or use the \-I option from the

460

command line. Here is what you must add to /etc/inittab:

461

.PP

462

.Vb 2

463

\& # Run Monit in standard run\-levels

464

\& mo:2345:respawn:/usr/local/bin/monit \-Ic /etc/monitrc

465

.Ve

466

.PP

467

After you have modified init's configuration file, you can run

468

the following command to re-examine /etc/inittab and start Monit:

469

.PP

470

.Vb 1

471

\& telinit q

472

.Ve

473

.PP

474

For systems without telinit:

475

.PP

476

.Vb 1

477

\& kill \-1 1

478

.Ve

479

.PP

480

If Monit is used to monitor services that are also started at

481

boot time (e.g. services started via \s-1SYSV\s0 init rc scripts or via

482

inittab) then, in some cases, a race condition could occur. That

483

is; if a service is slow to start, Monit can assume that the

484

service is not running and possibly try to start it and raise an

485

alert, while, in fact the service is already about to start or

486

already in its startup sequence. Please see the \s-1FAQ\s0 for a

487

solution to this problem.

488

.SH "INCLUDE FILES"

489

.IX Header "INCLUDE FILES"

490

The Monit control file, \fImonitrc\fR, can include additional

491

configuration files. This feature helps one to maintain a certain

492

structure or to place repeating settings into one file. Include

493

statements can be placed at virtually any spot. The syntax is the

494

following:

495

.PP

496

.Vb 1

497

\& include globstring

498

.Ve

499

.PP

500

The globstring is any kind of string as defined in \fIglob\fR\|(7). Thus,

501

you can refer to a single file or you can load several files at

502

once. If you want to use whitespace in your string the globstring

503

need to be embedded into quotes (') or double quotes ("). If the

504

globstring matches a directory instead of a file, it is silently

505

ignored.

506

.PP

507

Any \fIinclude\fR statements in included files are parsed as in the

508

main control file.

509

.PP

510

If the globstring matches several results, the files are included

511

in a non sorted manner. If you need to rely on a certain order,

512

you might need to use single \fIinclude\fR statements.

513

.PP

514

An example,

515

.PP

516

.Vb 1

517

\& include /etc/monit.d/*.cfg

518

.Ve

519

.PP

520

This will load any file matching the globstring. That is, all

521

files in \fI/etc/monit.d\fR that ends with the prefix \fI.cfg\fR.

522

.SH "GROUP SUPPORT"

523

.IX Header "GROUP SUPPORT"

524

Service entries in the control file, \fImonitrc\fR, can be grouped

525

together by the \fIgroup\fR statement. The syntax is simply (keyword

526

in capital):

527

.PP

528

.Vb 1

529

\& GROUP groupname

530

.Ve

531

.PP

532

With this statement it is possible to group similar service

533

entries together and manage them as a whole. Monit provides

534

functions to start, stop, restart, monitor and unmonitor a

535

group of services, like so:

536

.PP

537

To start a group of services from the console:

538

.PP

539

.Vb 1

540

\& Monit \-g <groupname> start

541

.Ve

542

.PP

543

To stop a group of services:

544

.PP

545

.Vb 1

546

\& Monit \-g <groupname> stop

547

.Ve

548

.PP

549

To restart a group of services:

550

.PP

551

.Vb 1

552

\& Monit \-g <groupname> restart

553

.Ve

554

.PP

555

Note:

556

the \fIstatus\fR and \fIsummary\fR commands don't support the \-g

557

option and will print the state of all services.

558

.PP

559

Service can be added to multiple groups by adding group statement

560

multiple times:

561

.PP

562

.Vb 2

563

\& group www

564

\& group filesystem

565

.Ve

566

.SH "MONITORING MODE"

567

.IX Header "MONITORING MODE"

568

Monit supports three monitoring modes per service: \fIactive\fR,

569

\&\fIpassive\fR and \fImanual\fR. See also the example section below for

570

usage of the mode statement.

571

.PP

572

In \fIactive\fR mode, Monit will monitor a service and in case of

573

problems Monit will act and raise alerts, start, stop or restart

574

the service. Active mode is the default mode.

575

.PP

576

In \fIpassive\fR mode, Monit will passively monitor a service and

577

specifically \fBnot\fR try to fix a problem, but it will still raise

578

alerts in case of a problem.

579

.PP

580

For use in clustered environments there is also a \fImanual\fR

581

mode. In this mode, Monit will enter \fIactive\fR mode \fBonly\fR if a

582

service was brought under monit's control, for example by

583

executing the following command in the console:

584

.PP

585

.Vb 2

586

\& Monit start sybase

587

\& (Monit will call sybase\*(Aqs start method and enable monitoring)

588

.Ve

589

.PP

590

If a service was not started by Monit or was stopped or disabled

591

for example by:

592

.PP

593

.Vb 2

594

\& Monit stop sybase

595

\& (Monit will call sybase\*(Aqs stop method and disable monitoring)

596

.Ve

597

.PP

598

Monit will then not monitor the service. This allows for having

599

services configured in monitrc and start it with Monit only if it

600

should run. This feature can be used to build a simple failsafe

601

cluster.

602

.PP

603

A service's monitoring state is persistent across Monit restart.

604

This means that you probably would like to make certain that

605

services in manual mode are stopped or in unmonitored mode at

606

server shutdown. Do for instance the following in a server

607

shutdown script:

608

.PP

609

.Vb 1

610

\& Monit stop sybase

611

.Ve

612

.PP

613

or

614

.PP

615

.Vb 1

616

\& Monit unmonitor sybase

617

.Ve

618

.PP

619

If you use Monit in a HA-cluster you should place the state file

620

in a temporary filesystem so if the machine should crash and the

621

stand-by machine take over services, any manual monitoring mode

622

services that were started on the crashed machine won't be

623

started on reboot. Use for example:

624

.PP

625

.Vb 1

626

\& set statefile /tmp/monit.state

627

.Ve

628

.SH "ALERT MESSAGES"

629

.IX Header "ALERT MESSAGES"

630

Monit will raise an email alert in the following situations:

631

.PP

632

.Vb 10

633

\& o A service timed out

634

\& o A service does not exist

635

\& o A service related data access problem

636

\& o A service related program execution problem

637

\& o A service is of invalid object type

638

\& o A program status failed

639

\& o A icmp problem

640

\& o A port connection problem

641

\& o A resource statement match

642

\& o A file checksum problem

643

\& o A file size problem

644

\& o A file/directory timestamp problem

645

\& o A file/directory/filesystem permission problem

646

\& o A file/directory/filesystem uid problem

647

\& o A file/directory/filesystem gid problem

648

\& o An action is done per administrator\*(Aqs request

649

.Ve

650

.PP

651

Monit will send an alert each time a monitored object changed.

652

This involves:

653

.PP

654

.Vb 8

655

\& o Monit started, stopped or reloaded

656

\& o A file checksum changed

657

\& o A file size changed

658

\& o A file content match

659

\& o A file/directory timestamp changed

660

\& o A filesystem mount flags changed

661

\& o A process PID changed

662

\& o A process PPID changed

663

.Ve

664

.PP

665

You use the alert statement to notify Monit that you want alert

666

messages sent to an email address. If you do not specify an alert

667

statement, Monit will not send alert messages.

668

.PP

669

There are two forms of alert statement:

670

.PP

671

.Vb 2

672

\& o Global \- common for all services

673

\& o Local \- per service

674

.Ve

675

.PP

676

In both cases you can use more than one alert statement. In other

677

words, you can send many different emails to many different

678

addresses.

679

.PP

680

Recipients in the global and in the local lists are alerted when

681

a service failed, recovered or changed. If the same email address

682

is in the global and in the local list, Monit will only send one

683

alert. Local (per service) defined alert email addresses override

684

global addresses in case of a conflict. Finally, you may choose

685

to only use a global alert list (recommended), a local per

686

service list or both.

687

.PP

688

It is also possible to disable the global alerts locally for

689

particular service(s) and recipients.

690

.SS "Setting a global alert statement"

691

.IX Subsection "Setting a global alert statement"

692

If a change occurred on a monitored services, Monit will send an

693

alert to all recipients in the global list who has registered

694

interest for the event type. Here is the syntax for the global

695

alert statement:

696

.IP "\s-1SET\s0 \s-1ALERT\s0 mail-address [ [\s-1NOT\s0] {events}] [\s-1MAIL\-FORMAT\s0 {mail\-format}] [\s-1REMINDER\s0 number]" 4

697

.IX Item "SET ALERT mail-address [ [NOT] {events}] [MAIL-FORMAT {mail-format}] [REMINDER number]"

698

.PP

699

Simply using the following in the global section of monitrc:

700

.PP

701

.Vb 1

702

\& set alert foo@bar

703

.Ve

704

.PP

705

will send a default email to the address foo@bar whenever an

706

event occurred on any service. Such an event may be that a

707

service timed out, a service doesn't exist and so on. If you want

708

to send alert messages to more email addresses, add a \fIset alert

709

\&'email'\fR statement for each address.

710

.PP

711

For explanations of the \fIevents, MAIL-FORMAT and \s-1REMINDER\s0\fR

712

keywords above, please see below.

713

.PP

714

You can also use the \s-1NOT\s0 option ahead of the events list which

715

will reverse the meaning of the list. That is, only send alerts

716

for events \fInot\fR in the list. This can save you some

717

configuration bytes if you are interested in most events except a

718

few.

719

.SS "Setting a local alert statement"

720

.IX Subsection "Setting a local alert statement"

721

Each service can also have its own recipient list.

722

.IP "\s-1ALERT\s0 mail-address [ [\s-1NOT\s0] {events}] [\s-1MAIL\-FORMAT\s0 {mail\-format}] [\s-1REMINDER\s0 number]" 4

723

.IX Item "ALERT mail-address [ [NOT] {events}] [MAIL-FORMAT {mail-format}] [REMINDER number]"

724

.PP

725

or

726

.IP "\s-1NOALERT\s0 mail-address" 4

727

.IX Item "NOALERT mail-address"

728

.PP

729

If you only want an alert message sent for certain events and for

730

certain service(s), for example only for timeout events or only

731

if a service died, then postfix the alert-statement with a filter

732

block:

733

.PP

734

.Vb 3

735

\& check process myproc with pidfile /var/run/my.pid

736

\& alert foo@bar only on { timeout, nonexist }

737

\& ...

738

.Ve

739

.PP

740

(\fIonly\fR and \fIon\fR are noise keywords, ignored by Monit. As a

741

side note; Noise keywords are used in the control file grammar to

742

make an entry resemble English and thus make it easier to read

743

(or, so goes the philosophy). The full set of available noise

744

keywords are listed below in the Control File section).

745

.PP

746

You can also setup to send alerts for all events except some by

747

putting the word \fInot\fR ahead of the list. For example, if you

748

want to receive alerts for all events except Monit instance

749

events, you can write (note that the noise words 'but' and 'on'

750

are optional):

751

.PP

752

.Vb 3

753

\& check system myserver

754

\& alert foo@bar but not on { instance }

755

\& ...

756

.Ve

757

.PP

758

instead of:

759

.PP

760

.Vb 10

761

\& alert foo@bar on { action

762

\& checksum

763

\& connection

764

\& content

765

\& data

766

\& exec

767

\& fsflags

768

\& gid

769

\& icmp

770

\& invalid

771

\& nonexist

772

\& permission

773

\& pid

774

\& ppid

775

\& resource

776

\& size

777

\& status

778

\& timeout

779

\& timestamp

780

\& uid

781

\& uptime }

782

.Ve

783

.PP

784

This will send alerts for all events to foo@bar, except Monit

785

instance events. An instance event \s-1BTW\s0, is an event fired

786

whenever the Monit program start or stop.

787

.PP

788

Event filtering can be used to send an email to different email

789

addresses depending on the events that occurred. For instance:

790

.PP

791

.Vb 3

792

\& alert foo@bar { nonexist, timeout, resource, icmp, connection }

793

\& alert security@bar on { checksum, permission, uid, gid }

794

\& alert manager@bar

795

.Ve

796

.PP

797

This will send an alert message to foo@bar whenever a nonexist,

798

timeout, resource or connection problem occurs and a message to

799

security@bar if a checksum, permission, uid or gid problem

800

occurs. And finally, a message to manager@bar whenever any error

801

event occurs.

802

.PP

803

Here is the list of events you can use in a mail-filter: \fIaction,

804

checksum, connection, content, data, exec, fsflags, gid, icmp,

805

instance, invalid, nonexist, permission, pid, ppid, resource, size,

806

status, timeout, timestamp, uid, uptime\fR

807

.PP

808

You can also disable the alerts locally using the \s-1NOALERT\s0

809

statement. This is useful if you have lots of services monitored

810

and are using the global alert statement, but don't want to

811

receive alerts for some minor subset of services:

812

.PP

813

.Vb 1

814

\& noalert appadmin@bar

815

.Ve

816

.PP

817

For example, if you stick the noalert statement in a 'check

818

system' entry, you won't receive system related alerts (such as

819

Monit instance started/stopped/reloaded alert, system overloaded

820

alert, etc.) but will receive alerts for all other monitored

821

services.

822

.PP

823

The following example will alert foo@bar on all events on all

824

services by default, except the service mybar which will send an

825

alert only on timeout. The trick is based on the fact that local

826

definition of the same recipient overrides the global setting

827

(including registered events and mail format):

828

.PP

829

.Vb 1

830

\& set alert foo@bar

831

\&

832

\& check process myfoo with pidfile /var/run/myfoo.pid

833

\& ...

834

\& check process mybar with pidfile /var/run/mybar.pid

835

\& alert foo@bar only on { timeout }

836

.Ve

837

.SS "Alert message layout"

838

.IX Subsection "Alert message layout"

839

Monit provides a default mail message layout that is short and to

840

the point. Here's an example of a standard alert mail sent by

841

monit:

842

.PP

843

.Vb 4

844

\& From: monit@tildeslash.com

845

\& Subject: Monit alert \-\- Does not exist apache

846

\& To: hauk@tildeslash.com

847

\& Date: Thu, 04 Sep 2003 02:33:03 +0200

848

\&

849

\& Does not exist Service apache

850

\&

851

\& Date: Thu, 04 Sep 2003 02:33:03 +0200

852

\& Action: restart

853

\& Host: www.tildeslash.com

854

\&

855

\& Your faithful employee,

856

\& monit

857

.Ve

858

.PP

859

If you want to, you can change the format of this message with

860

the optional \fImail-format\fR statement. The syntax for this

861

statement is as follows:

862

.PP

863

.Vb 8

864

\& mail\-format {

865

\& from: monit@localhost

866

\& reply\-to: support@domain.com

867

\& subject: $SERVICE $EVENT at $DATE

868

\& message: Monit $ACTION $SERVICE at $DATE on $HOST: $DESCRIPTION.

869

\& Yours sincerely,

870

\& monit

871

\& }

872

.Ve

873

.PP

874

Where the keyword \fIfrom:\fR is the email address Monit should

875

pretend it is sending from. It does not have to be a real mail

876

address, but it must be a proper formatted mail address, on the

877

form: name@domain. The \fIreply-to:\fR keyword can be used to set

878

the reply-to mail header. The keyword \fIsubject:\fR is for the

879

email subject line. The subject must be on only \fIone\fR line. The

880

\&\fImessage:\fR keyword denotes the mail body. If used, this keyword

881

should always be the last in a mail-format statement. The mail

882

body can be as long as you want, but must \fBnot\fR contain the '}'

883

character.

884

.PP

885

All of these format keywords are optional, but if used, you must

886

provide at least one. Thus if you only want to change the from

887

address Monit is using you can do:

888

.PP

889

.Vb 1

890

\& set alert foo@bar with mail\-format { from: bofh@bar.baz }

891

.Ve

892

.PP

893

From the previous example you will notice that some special \f(CW$XXX\fR

894

variables were used. If used, they will be substituted and

895

expanded into the text with these values:

896

.IP "\(bu" 4

897

\&\fI\f(CI$EVENT\fI\fR

898

.Sp

899

.Vb 2

900

\& A string describing the event that occurred. The values are

901

\& fixed and are:

902

\&

903

\& Event: | Failure state: | Success state:

904

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

905

\& ACTION | "Action done" | "Action done"

906

\& CHECKSUM | "Checksum failed" | "Checksum succeeded"

907

\& CONNECTION| "Connection failed" | "Connection succeeded"

908

\& CONTENT | "Content failed", | "Content succeeded"

909

\& DATA | "Data access error" | "Data access succeeded"

910

\& EXEC | "Execution failed" | "Execution succeeded"

911

\& FSFLAG | "Filesystem flags failed"| "Filesystem flags succeeded"

912

\& GID | "GID failed" | "GID succeeded"

913

\& ICMP | "ICMP failed" | "ICMP succeeded"

914

\& INSTANCE | "Monit instance changed" | "Monit instance changed not"

915

\& INVALID | "Invalid type" | "Type succeeded"

916

\& NONEXIST | "Does not exist" | "Exists"

917

\& PERMISSION| "Permission failed" | "Permission succeeded"

918

\& PID | "PID failed" | "PID succeeded"

919

\& PPID | "PPID failed" | "PPID succeeded"

920

\& RESOURCE | "Resource limit matched" | "Resource limit succeeded"

921

\& SIZE | "Size failed" | "Size succeeded"

922

\& STATUS | "Status failed" | "Status succeeded"

923

\& TIMEOUT | "Timeout" | "Timeout recovery"

924

\& TIMESTAMP | "Timestamp failed" | "Timestamp succeeded"

925

\& UID | "UID failed" | "UID succeeded"

926

\& UPTIME | "Uptime failed" | "Uptime succeeded"

927

.Ve

928

.IP "\(bu" 4

929

\&\fI\f(CI$SERVICE\fI\fR

930

.Sp

931

.Vb 1

932

\& The service entry name in monitrc

933

.Ve

934

.IP "\(bu" 4

935

\&\fI\f(CI$DATE\fI\fR

936

.Sp

937

.Vb 1

938

\& The current time and date (RFC 822 date style).

939

.Ve

940

.IP "\(bu" 4

941

\&\fI\f(CI$HOST\fI\fR

942

.Sp

943

.Vb 1

944

\& The name of the host Monit is running on

945

.Ve

946

.IP "\(bu" 4

947

\&\fI\f(CI$ACTION\fI\fR

948

.Sp

949

.Vb 2

950

\& The name of the action which was done. Action names are fixed

951

\& and are:

952

\&

953

\& Action: | Name:

954

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

955

\& ALERT | "alert"

956

\& EXEC | "exec"

957

\& RESTART | "restart"

958

\& START | "start"

959

\& STOP | "stop"

960

\& UNMONITOR| "unmonitor"

961

.Ve

962

.IP "\(bu" 4

963

\&\fI\f(CI$DESCRIPTION\fI\fR

964

.Sp

965

.Vb 1

966

\& The description of the error condition

967

.Ve

968

.SS "Setting a global mail format"

969

.IX Subsection "Setting a global mail format"

970

It is possible to set a standard mail format with the following

971

global set-statement (keywords are in capital):

972

.IP "\s-1SET\s0 MAIL-FORMAT {mail\-format}" 4

973

.IX Item "SET MAIL-FORMAT {mail-format}"

974

.PP

975

Format set with this statement will apply to every alert

976

statement that does \fInot\fR have its own specified mail-format.

977

This statement is most useful for setting a default from address

978

for messages sent by monit, like so:

979

.PP

980

.Vb 1

981

\& set mail\-format { from: monit@foo.bar.no }

982

.Ve

983

.SS "Setting an error reminder"

984

.IX Subsection "Setting an error reminder"

985

Monit by default sends just one error notification if a service

986

failed and another when it recovered. If you want to be notified

987

more then once if a service remains in a failed state, you can

988

use the reminder option to the alert statement (keywords are in

989

capital):

990

.IP "\s-1ALERT\s0 ... [\s-1WITH\s0] \s-1REMINDER\s0 [\s-1ON\s0] number [\s-1CYCLES\s0]" 4

991

.IX Item "ALERT ... [WITH] REMINDER [ON] number [CYCLES]"

992

.PP

993

For example if you want to be notified each tenth cycle if a

994

service remains in a failed state, you can use:

995

.PP

996

.Vb 1

997

\& alert foo@bar with reminder on 10 cycles

998

.Ve

999

.PP

1000

Likewise if you want to be notified on each failed cycle, you can

1001

use:

1002

.PP

1003

.Vb 1

1004

\& alert foo@bar with reminder on 1 cycle

1005

.Ve

1006

.SS "Setting a mail server for alert messages"

1007

.IX Subsection "Setting a mail server for alert messages"

1008

The mail server Monit should use to send alert messages is

1009

defined with a global set statement (keywords are in capital and

1010

optional statements in [brackets]):

1011

.PP

1012

.Vb 5

1013

\& SET MAILSERVER {hostname|ip\-address [PORT port]

1014

\& [USERNAME username] [PASSWORD password]

1015

\& [using SSLV2|SSLV3|TLSV1] [CERTMD5 checksum]}+

1016

\& [with TIMEOUT X SECONDS]

1017

\& [using HOSTNAME hostname]

1018

.Ve

1019

.PP

1020

The port statement allows one to use \s-1SMTP\s0 servers other then those

1021

listening on port 25. If omitted, port 25 is used unless ssl or

1022

tls is used, in which case port 465 is used by default.

1023

.PP

1024

Monit support plain smtp authentication \- you can set a username

1025

and a password using the \s-1USERNAME\s0 and \s-1PASSWORD\s0 options.

1026

.PP

1027

To use secure communication, use the \s-1SSLV2\s0, \s-1SSLV3\s0 or \s-1TLSV1\s0

1028

options, you can also specify the server certificate checksum

1029

using \s-1CERTMD5\s0 option.

1030

.PP

1031

As you can see, it is possible to set several \s-1SMTP\s0 servers. If

1032

Monit cannot connect to the first server in the list it will try

1033

the second server and so on. Monit has a default 5 seconds

1034

connection timeout and if the \s-1SMTP\s0 server is slow, Monit could

1035

timeout when connecting or reading from the server. If this is

1036

the case, you can use the optional timeout statement to explicit

1037

set the timeout to a higher value if needed. Here is an example

1038

for setting several mail servers:

1039

.PP

1040

.Vb 3

1041

\& set mailserver mail.tildeslash.com, mail.foo.bar port 10025

1042

\& username "Rabbi" password "Loew" using tlsv1, localhost

1043

\& with timeout 15 seconds

1044

.Ve

1045

.PP

1046

Here Monit will first try to connect to the server

1047

\&\*(L"mail.tildeslash.com\*(R", if this server is down Monit will try

1048

\&\*(L"mail.foo.bar\*(R" on port 10025 using the given credentials via tls

1049

and finally \*(L"localhost\*(R". We also set an explicit connect and read

1050

timeout; If Monit cannot connect to the first \s-1SMTP\s0 server in the

1051

list within 15 seconds it will try the next server and so on. The

1052

\&\fIset mailserver ..\fR statement is optional and if not defined

1053

Monit will not send email alerts. Not setting a mail server is

1054

recommended only if alert notification is delegated to M/Monit.

1055

.PP

1056

Monit, by default, use the local host name in \s-1SMTP\s0 \s-1HELO/EHLO\s0 and

1057

in the Message-ID header. Some mail servers check this

1058

information against \s-1DNS\s0 for spam protection and can reject the

1059

email if the \s-1DNS\s0 and the hostname used in the transaction does

1060

not match. If this is the case, you can override the default

1061

local host name by using the \s-1HOSTNAME\s0 option:

1062

.PP

1063

.Vb 2

1064

\& set mailserver mail.tildeslash.com using hostname

1065

\& "myhost.example.org"

1066

.Ve

1067

.SS "Event queue"

1068

.IX Subsection "Event queue"

1069

If the \s-1MTA\s0 (mail server) for sending alerts is not available,

1070

Monit \fIcan\fR queue events on the local file-system until the \s-1MTA\s0

1071

recover. Monit will then post queued events in order with their

1072

original timestamp so the events are not lost. This feature is

1073

most useful if Monit is used together with M/Monit and when event

1074

history is important.

1075

.PP

1076

The event queue is persistent across Monit restarts and provided

1077

that the back-end filesystem is persistent too, across system

1078

restart as well.

1079

.PP

1080

By default, the queue is disabled and if the alert handler fails,

1081

Monit will simply drop the alert message. To enable the event

1082

queue, add the following statement to the Monit control file:

1083

.PP

1084

.Vb 1

1085

\& SET EVENTQUEUE BASEDIR <path> [SLOTS <number>]

1086

.Ve

1087

.PP

1088

The <path> is the path to the directory where events will be

1089

stored. Optionally if you want to limit the queue size, use the

1090

slots option to only store up to \fInumber\fR event messages. If the

1091

slots option is not used, Monit will store as many events as the

1092

backend filesystem allows.

1093

.PP

1094

Example:

1095

.PP

1096

.Vb 3

1097

\& set eventqueue

1098

\& basedir /var/monit

1099

\& slots 5000

1100

.Ve

1101

.PP

1102

Events are stored in a binary format, with one file per event.

1103

The file size is ca. 130 bytes or a bit more (depending on the

1104

message length). The file name is composed of the unix timestamp,

1105

underscore and the service name, for example:

1106

.PP

1107

.Vb 1

1108

\& /var/monit/1131269471_apache

1109

.Ve

1110

.PP

1111

If you are running more then one Monit instance on the same

1112

machine, you \fBmust\fR use separated event queue directories to

1113

avoid sending wrong alerts to the wrong addresses.

1114

.PP

1115

If you want to purge the queue by hand, that is, remove queued

1116

event-files, Monit should be stopped before the removal.

1117

.SH "SERVICE TIMEOUT"

1118

.IX Header "SERVICE TIMEOUT"

1119

\&\fBMonit\fR provides a service timeout mechanism for situations

1120

where a service simply refuses to start or respond over a longer

1121

period.

1122

.PP

1123

The timeout mechanism is based on number of service restarts and

1124

number of poll-cycles. For example, if a service had \fIx\fR

1125

restarts within \fIy\fR poll-cycles (where \fIx\fR <= \fIy\fR) then Monit

1126

will perform an action (for example unmonitor the service). If a

1127

timeout occurs, Monit will send an alert message if you have

1128

register interest for this event.

1129

.PP

1130

The syntax for the timeout statement is as follows (keywords are

1131

in capital):

1132

.IP "\s-1IF\s0 <number> \s-1RESTART\s0 <number> \s-1CYCLE\s0(S) \s-1THEN\s0 <action>" 4

1133

.IX Item "IF <number> RESTART <number> CYCLE(S) THEN <action>"

1134

.PP

1135

Here is an example where Monit will unmonitor the service if it

1136

was restarted 2 times within 3 cycles:

1137

.PP

1138

.Vb 1

1139

\& if 2 restarts within 3 cycles then unmonitor

1140

.Ve

1141

.PP

1142

To have Monit check the service again after a monitoring was

1143

disabled, run 'monit monitor <servicename>' from the command

1144

line.

1145

.PP

1146

Example for setting custom exec on timeout:

1147

.PP

1148

.Vb 1

1149

\& if 5 restarts within 5 cycles then exec "/foo/bar"

1150

.Ve

1151

.PP

1152

Example for stopping the service:

1153

.PP

1154

.Vb 1

1155

\& if 7 restarts within 10 cycles then stop

1156

.Ve

1157

.SH "SERVICE TESTS"

1158

.IX Header "SERVICE TESTS"

1159

Monit provides several tests you can use in a 'check service'

1160

entry to test a service. There are two classes of tests:

1161

variable and constant tests. That is, the condition we test

1162

is either constant e.g. a number or it can vary.

1163

.PP

1164

A constant test has this general format:

1165

.IP "\s-1IF\s0 <\s-1TEST\s0> [[<X>] [\s-1TIMES\s0 \s-1WITHIN\s0] <Y> \s-1CYCLES\s0] \s-1THEN\s0 \s-1ACTION\s0 [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] [\s-1TIMES\s0 \s-1WITHIN\s0] <Y> \s-1CYCLES\s0] \s-1THEN\s0 \s-1ACTION\s0]" 4

1166

.IX Item "IF <TEST> [[<X>] [TIMES WITHIN] <Y> CYCLES] THEN ACTION [ELSE IF SUCCEEDED [[<X>] [TIMES WITHIN] <Y> CYCLES] THEN ACTION]"

1167

.PP

1168

If the <\s-1TEST\s0> condition should evaluate to true, then the

1169

selected action is executed each cycle the test condition remains

1170

true. The comparison value is constant. Recovery action is

1171

evaluated only once (on a failed to succeeded state change only).

1172

The '\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0' part is optional, if omitted, Monit will

1173

still send an alert on recovery. The alert is sent only once for

1174

each state change unless overridden by the 'reminder' alert

1175

option.

1176

.PP

1177

A variable test has this general format:

1178

.IP "\s-1IF\s0 \s-1CHANGED\s0 <\s-1TEST\s0> [[<X>] [\s-1TIMES\s0 \s-1WITHIN\s0] <Y> \s-1CYCLES\s0] \s-1THEN\s0 \s-1ACTION\s0" 4

1179

.IX Item "IF CHANGED <TEST> [[<X>] [TIMES WITHIN] <Y> CYCLES] THEN ACTION"

1180

.PP

1181

If the <\s-1TEST\s0> should evaluate to true, then the selected action

1182

is executed once. The comparison value is a variable where the

1183

last result becomes the new value and is used for comparisons in

1184

future cycles. An alert is delivered each time the condition

1185

becomes true.

1186

.PP

1187

You can use this test for alerts or for some automatic action,

1188

for example to reload monitored process after its configuration

1189

file was changed. Variable tests are supported for 'checksum',

1190

\&'size', 'pid, 'ppid' and 'timestamp' tests only.

1191

.IP "... [[<X>] [\s-1TIMES\s0 \s-1WITHIN\s0] <Y> \s-1CYCLES\s0] ..." 4

1192

.IX Item "... [[<X>] [TIMES WITHIN] <Y> CYCLES] ..."

1193

.PP

1194

If a test match, its action is executed at once. This behavior

1195

can optionally be changed and you can for instance require that a

1196

test must match over several poll cycles before the action is

1197

executed by using the statement above. You can use this in

1198

several ways. For example:

1199

.PP

1200

.Vb 1

1201

\& if failed port 80 for 3 times within 5 cycles then alert

1202

.Ve

1203

.PP

1204

or

1205

.PP

1206

.Vb 1

1207

\& if failed port 80 for 10 cycles then unmonitor

1208

.Ve

1209

.PP

1210

If you don't specify <X> times, it equals <Y> by default, thus

1211

the test match if it evaluate to true for <Y> consecutive cycles.

1212

.PP

1213

It is possible to use this option to tune and prevent a rush of

1214

notifications. You can use this option for failed, succeeded,

1215

recovered or changed rules. Here is a more complex example:

1216

.PP

1217

.Vb 5

1218

\& check filesystem rootfs with path /dev/hda1

1219

\& if space usage > 80% for 5 times within 15 cycles

1220

\& then alert else if succeeded for 10 cycles then alert

1221

\& if space usage > 90% for 5 cycles then

1222

\& exec \*(Aq/try/to/free/the/space\*(Aq

1223

.Ve

1224

.PP

1225

In each test you must select the action to be executed from this

1226

list:

1227

.IP "\(bu" 4

1228

\&\fB\s-1ALERT\s0\fR sends the user an alert event on each state change (for

1229

constant tests) or on each change (for variable tests).

1230

.IP "\(bu" 4

1231

\&\fB\s-1RESTART\s0\fR restarts the service \fIand\fR sends an alert. Restart is

1232

conducted by first calling the service's registered stop method

1233

and then the service's start method.

1234

.IP "\(bu" 4

1235

\&\fB\s-1START\s0\fR starts the service by calling the service's registered

1236

start method \fIand\fR send an alert.

1237

.IP "\(bu" 4

1238

\&\fB\s-1STOP\s0\fR stops the service by calling the service's registered

1239

stop method \fIand\fR send an alert. If Monit stops a service it

1240

will not be checked by Monit anymore nor restarted again later.

1241

To reactivate monitoring of the service again you must explicitly

1242

enable monitoring from the web interface or from the console,

1243

e.g. 'monit monitor apache'.

1244

.IP "\(bu" 4

1245

\&\fB\s-1EXEC\s0\fR can be used to execute an arbitrary program \fIand\fR send

1246

an alert. If you choose this action you must state the program to

1247

be executed and if the program require arguments you must enclose

1248

the program and its arguments in a quoted string. You may

1249

optionally specify the uid and gid the executed program should

1250

switch to upon start. For instance:

1251

.Sp

1252

.Vb 2

1253

\& exec "/usr/local/tomcat/bin/startup.sh"

1254

\& as uid nobody and gid nobody

1255

.Ve

1256

.Sp

1257

The uid and gid switch can be useful if the program to be started

1258

cannot change to a lesser privileged user and group. This is

1259

typically needed for Java Servers. Remember, if Monit is run by

1260

the superuser, then all programs executed by Monit will be

1261

started with superuser privileges unless the uid and gid

1262

extension was used.

1263

.IP "\(bu" 4

1264

\&\fB\s-1UNMONITOR\s0\fR will disable monitoring of the service \fIand\fR send

1265

an alert. The service will not be checked by Monit anymore nor

1266

restarted again later. To reactivate monitoring of the service

1267

you must explicitly enable monitoring from monit's web interface

1268

or from the console using the monitor argument.

1269

.SS "\s-1EXISTENCE\s0 \s-1TESTING\s0"

1270

.IX Subsection "EXISTENCE TESTING"

1271

Monit's default action when services does not exist (for example

1272

a process is not running, a file doesn't exist, etc.) is to

1273

perform service restart action.

1274

.PP

1275

The default action can be overrided with following statement:

1276

.IP "\s-1IF\s0 [\s-1DOES\s0] \s-1NOT\s0 \s-1EXIST\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1277

.IX Item "IF [DOES] NOT EXIST [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1278

.PP

1279

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1280

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1281

.PP

1282

Example:

1283

.PP

1284

.Vb 2

1285

\& check file with path /cifs/mydata

1286

\& if does not exist for 5 cycles then exec "/usr/bin/mount_cifs.sh"

1287

.Ve

1288

.SS "\s-1RESOURCE\s0 \s-1TESTING\s0"

1289

.IX Subsection "RESOURCE TESTING"

1290

Monit can examine how much system resources a service is using.

1291

This test can only be used within a system or process service

1292

entry in the Monit control file.

1293

.PP

1294

Depending on system or process characteristics, services can be

1295

stopped or restarted and alerts can be generated. Thus it is

1296

possible to utilize systems which are idle and to spare system

1297

under high load.

1298

.PP

1299

The full syntax for a resource-statement used for resource

1300

testing is as follows (keywords are in capital and optional

1301

statements in [brackets]),

1302

.IP "\s-1IF\s0 resource operator value [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1303

.IX Item "IF resource operator value [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1304

.PP

1305

\&\fIresource\fR is a choice of \*(L"\s-1CPU\s0\*(R", \*(L"\s-1TOTALCPU\s0\*(R",

1306

\&\*(L"\s-1CPU\s0([user|system|wait])\*(R", \*(L"\s-1MEMORY\s0\*(R", \*(L"\s-1SWAP\s0\*(R", \*(L"\s-1CHILDREN\s0\*(R", \*(L"\s-1TOTALMEMORY\s0\*(R",

1307

\&\*(L"\s-1LOADAVG\s0([1min|5min|15min])\*(R". Some resource tests can be used

1308

inside a check system entry, some in a check process entry and

1309

some in both:

1310

.PP

1311

System only resource tests:

1312

.PP

1313

\&\s-1CPU\s0([user|system|wait]) is the percent of time the system spend

1314

in user or system/kernel space. Some systems such as linux 2.6

1315

supports a 'wait' indicator as well.

1316

.PP

1317

\&\s-1SWAP\s0 is the swap usage of the system in either percent (of the

1318

systems total) or as an amount (Byte, kB, \s-1MB\s0, \s-1GB\s0).

1319

.PP

1320

Process only resource tests:

1321

.PP

1322

\&\s-1CPU\s0 is the \s-1CPU\s0 usage of the process itself (percent).

1323

.PP

1324

\&\s-1TOTALCPU\s0 is the total \s-1CPU\s0 usage of the process and its children

1325

in (percent). You will want to use \s-1TOTALCPU\s0 typically for

1326

services like Apache web server where one master process forks the

1327

child processes as workers.

1328

.PP

1329

\&\s-1CHILDREN\s0 is the number of child processes of the process.

1330

.PP

1331

\&\s-1TOTALMEMORY\s0 is the memory usage of the process and its child

1332

processes in either percent or as an amount (Byte, kB, \s-1MB\s0, \s-1GB\s0).

1333

.PP

1334

System and process resource tests:

1335

.PP

1336

\&\s-1MEMORY\s0 is the memory usage of the system or of a process (without

1337

children) in either percent (of the systems total) or as an

1338

amount (Byte, kB, \s-1MB\s0, \s-1GB\s0).

1339

.PP

1340

\&\s-1LOADAVG\s0([1min|5min|15min]) refers to the system's load average.

1341

The load average is the number of processes in the system run

1342

queue, averaged over the specified time period.

1343

.PP

1344

\&\fIoperator\fR is a choice of \*(L"<\*(R", \*(L">\*(R", \*(L"!=\*(R", \*(L"==\*(R" in C notation,

1345

\&\*(L"gt\*(R", \*(L"lt\*(R", \*(L"eq\*(R", \*(L"ne\*(R" in shell sh notation and \*(L"greater\*(R",

1346

\&\*(L"less\*(R", \*(L"equal\*(R", \*(L"notequal\*(R" in human readable form (if not

1347

specified, default is \s-1EQUAL\s0).

1348

.PP

1349

\&\fIvalue\fR is either an integer or a real number (except for

1350

\&\s-1CHILDREN\s0). For \s-1CPU\s0, \s-1TOTALCPU\s0, \s-1MEMORY\s0 and \s-1TOTALMEMORY\s0 you need to

1351

specify a \fIunit\fR. This could be \*(L"%\*(R" or if applicable \*(L"B\*(R" (Byte),

1352

\&\*(L"kB\*(R" (1024 Byte), \*(L"\s-1MB\s0\*(R" (1024 KiloByte) or \*(L"\s-1GB\s0\*(R" (1024 MegaByte).

1353

.PP

1354

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1355

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1356

.PP

1357

To calculate the cycles, a counter is raised whenever the

1358

expression above is true and it is lowered whenever it is false

1359

(but not below 0). All counters are reset in case of a restart.

1360

.PP

1361

The following is an example to check that the \s-1CPU\s0 usage of a

1362

service is not going beyond 50% during five poll cycles. If it

1363

does, Monit will restart the service:

1364

.PP

1365

.Vb 1

1366

\& if cpu is greater than 50% for 5 cycles then restart

1367

.Ve

1368

.PP

1369

See also \fIregex\fR\|(7).

1630

.PP

1631

\&\fIpath\fR is an absolute path to a file containing extended

1632

regular expression on every line. See also \fIregex\fR\|(7).

1633

.PP

1634

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1635

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1636

.PP

1637

You can use the \fI\s-1NOT\s0\fR statement to invert a match.

1638

.PP

1639

The content is only being checked every cycle. If content is

1640

being added and removed between two checks they are unnoticed.

1641

.PP

1642

On startup the read position is set to the end of the file

1643

and Monit continue to scan to the end of file on each cycle.

1644

But if the file size should decrease or inode change the read

1645

position is set to the start of the file.

1646

.PP

1647

Only lines ending with a newline character are inspected. Thus,

1648

lines are being ignored until they have been completed with this

1649

character. Also note that only the first 511 characters of a line

1650

are inspected.

1651

.IP "\s-1IGNORE\s0 [\s-1NOT\s0] \s-1MATCH\s0 {regex|path}" 4

1652

.IX Item "IGNORE [NOT] MATCH {regex|path}"

1653

.PP

1654

Lines matching an \fI\s-1IGNORE\s0\fR are not inspected during later

1655

evaluations. \fI\s-1IGNORE\s0 \s-1MATCH\s0\fR has always precedence over

1656

\&\fI\s-1IF\s0 \s-1MATCH\s0\fR.

1657

.PP

1658

All \fI\s-1IGNORE\s0 \s-1MATCH\s0\fR statements are evaluated first, in the

1659

order of their appearance. Thereafter, all the \fI\s-1IF\s0 \s-1MATCH\s0\fR

1660

statements are evaluated.

1661

.PP

1662

A real life example might look like this:

1663

.PP

1664

.Vb 7

1665

\& check file syslog with path /var/log/syslog

1666

\& ignore match

1667

\& "^\ew{3} [ :0\-9]{11} [._[:alnum:]\-]+ monit\e[[0\-9]+\e]:"

1668

\& ignore match /etc/monit/ignore.regex

1669

\& if match

1670

\& "^\ew{3} [ :0\-9]{11} [._[:alnum:]\-]+ mrcoffee\e[[0\-9]+\e]:"

1671

\& if match /etc/monit/active.regex then alert

1672

.Ve

1673

.SS "\s-1FILESYSTEM\s0 \s-1FLAGS\s0 \s-1TESTING\s0"

1674

.IX Subsection "FILESYSTEM FLAGS TESTING"

1675

Monit can test the flags of a filesystem for changes. This test

1676

is implicit and Monit will send alert in case of failure by

1677

default.

1678

.PP

1679

This test is useful for detecting changes of the filesystem flags

1680

such as when the filesystem became read-only based on disk errors

1681

or the mount flags were changed (such as nosuid). Each platform

1682

provides different set of flags. \s-1POSIX\s0 define the \s-1RDONLY\s0 and

1683

\&\s-1NOSUID\s0 flags which should work on all platforms. Some platforms

1684

(such as FreeBSD) has additonal flags.

1685

.PP

1686

The syntax for the fsflags statement is:

1687

.IP "\s-1IF\s0 \s-1CHANGED\s0 \s-1FSFLAGS\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action" 4

1688

.IX Item "IF CHANGED FSFLAGS [[<X>] <Y> CYCLES] THEN action"

1689

.PP

1690

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1691

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1692

.PP

1693

Example:

1694

.PP

1695

.Vb 3

1696

\& check filesystem rootfs with path /

1697

\& if changed fsflags then exec "/my/script"

1698

\& alert root@localhost

1699

.Ve

1700

.SS "\s-1SPACE\s0 \s-1TESTING\s0"

1701

.IX Subsection "SPACE TESTING"

1702

Monit can test file systems for space usage. This test may

1703

only be used within a check filesystem service entry in the

1704

Monit control file.

1705

.PP

1706

Monit will check a filesystem's total space usage. If you only

1707

want to check available space for non-superuser, you must set the

1708

watermark appropriately (i.e. total space minus reserved blocks

1709

for the superuser).

1710

.PP

1711

You can obtain (and set) the superuser's reserved blocks size,

1712

for example by using the tune2fs utility on Linux. On Linux 5% of

1713

available blocks are reserved for the superuser by default. On

1714

solaris 10% of the blocks are reserved. You can also use tunefs

1715

on solaris to change values on a live filesystem.

1716

.PP

1717

The full syntax for the space statement is:

1718

.IP "\s-1IF\s0 \s-1SPACE\s0 operator value unit [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1719

.IX Item "IF SPACE operator value unit [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1720

.PP

1721

\&\fIoperator\fR is a choice of \*(L"<\*(R",\*(L">\*(R",\*(L"!=\*(R",\*(L"==\*(R" in c notation, \*(L"gt\*(R",

1722

\&\*(L"lt\*(R", \*(L"eq\*(R", \*(L"ne\*(R" in shell sh notation and \*(L"greater\*(R", \*(L"less\*(R",

1723

\&\*(L"equal\*(R", \*(L"notequal\*(R" in human readable form (if not specified,

1724

default is \s-1EQUAL\s0).

1725

.PP

1726

\&\fIunit\fR is a choice of \*(L"B\*(R",\*(L"\s-1KB\s0\*(R",\*(L"\s-1MB\s0\*(R",\*(L"\s-1GB\s0\*(R", \*(L"%\*(R" or long

1727

alternatives \*(L"byte\*(R", \*(L"kilobyte\*(R", \*(L"megabyte\*(R", \*(L"gigabyte\*(R",

1728

\&\*(L"percent\*(R".

1729

.PP

1730

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1731

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1732

.SS "\s-1INODE\s0 \s-1TESTING\s0"

1733

.IX Subsection "INODE TESTING"

1734

If supported by the file-system, you can use Monit to test

1735

for inodes usage. This test may only be used within a check

1736

filesystem service entry in the Monit control file.

1737

.PP

1738

If the filesystem becomes unavailable, Monit will call the

1739

service's registered start method, if it is defined and if Monit

1740

is running in active mode. If Monit runs in passive mode or the

1741

start methods is not defined, Monit will just send an error

1742

alert.

1743

.PP

1744

The syntax for the inode statement is:

1745

.IP "\s-1IF\s0 \s-1INODE\s0(S) operator value [unit] [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1746

.IX Item "IF INODE(S) operator value [unit] [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1747

.PP

1748

\&\fIoperator\fR is a choice of \*(L"<\*(R",\*(L">\*(R",\*(L"!=\*(R",\*(L"==\*(R" in c notation, \*(L"gt\*(R",

1749

\&\*(L"lt\*(R", \*(L"eq\*(R", \*(L"ne\*(R" in shell sh notation and \*(L"greater\*(R", \*(L"less\*(R",

1750

\&\*(L"equal\*(R", \*(L"notequal\*(R" in human readable form (if not specified,

1751

default is \s-1EQUAL\s0).

1752

.PP

1753

\&\fIunit\fR is optional. If not specified, the value is an absolute

1754

count of inodes. You can use the \*(L"%\*(R" character or the longer

1755

alternative \*(L"percent\*(R" as a unit.

1756

.PP

1757

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1758

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1759

.SS "\s-1PERMISSION\s0 \s-1TESTING\s0"

1760

.IX Subsection "PERMISSION TESTING"

1761

Monit can monitor the permission of file objects. This test may

1762

only be used within a file, fifo, directory or filesystem service

1763

entry in the Monit control file.

1764

.PP

1765

The syntax for the permission statement is:

1766

.IP "\s-1IF\s0 \s-1FAILED\s0 \s-1PERM\s0(\s-1ISSION\s0) octalnumber [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1767

.IX Item "IF FAILED PERM(ISSION) octalnumber [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1768

.PP

1769

\&\fIoctalnumber\fR defines permissions for a file, a directory or a

1770

filesystem as four octal digits (0\-7). Valid range: 0000 \- 7777 (you

1771

can omit the leading zeros, Monit will add the zeros to the left

1772

thus for example \*(L"640\*(R" is valid value and matches \*(L"0640\*(R").

1773

.PP

1774

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1775

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1776

.PP

1777

The web interface will show a permission warning if the test

1778

failed.

1779

.PP

1780

We recommend that you use the \s-1UNMONITOR\s0 action in a permission

1781

statement. The rationale for this feature is security and that

1782

Monit does not start a possible cracked program or script.

1783

Example:

1784

.PP

1785

.Vb 2

1786

\& check file monit.bin with path "/usr/local/bin/monit"

1787

\& if failed permission 0555 then unmonitor

1788

.Ve

1789

.PP

1790

If the test fails, Monit will simply send an alert and stop

1791

monitoring the file and propagate an unmonitor action upward in

1792

a depend tree.

1793

.SS "\s-1UID\s0 \s-1TESTING\s0"

1794

.IX Subsection "UID TESTING"

1795

Monit can monitor the owner user id (uid) of a file object.

1796

This test may only be used within a check \- file, fifo,

1797

directory or filesystem service entry in the Monit control

1798

file.

1799

.PP

1800

The syntax for the uid statement is:

1801

.IP "\s-1IF\s0 \s-1FAILED\s0 \s-1UID\s0 user [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1802

.IX Item "IF FAILED UID user [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1803

.PP

1804

\&\fIuser\fR defines a user id either in numeric or in string form.

1805

.PP

1806

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1807

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1808

.PP

1809

The web interface will show a uid warning if the test should

1810

fail.

1811

.PP

1812

We recommend that you use the \s-1UNMONITOR\s0 action in a uid

1813

statement. The rationale for this feature is security and that

1814

Monit does not start a possible cracked program or script.

1815

Example:

1816

.PP

1817

.Vb 2

1818

\& check file passwd with path /etc/passwd

1819

\& if failed uid root then unmonitor

1820

.Ve

1821

.PP

1822

If the test fails, Monit will simply send an alert and stop

1823

monitoring the file and propagate an unmonitor action upward in

1824

a depend tree.

1825

.SS "\s-1GID\s0 \s-1TESTING\s0"

1826

.IX Subsection "GID TESTING"

1827

Monit can monitor the owner group id (gid) of file objects. This

1828

test may only be used within a file, fifo, directory or

1829

filesystem service entry in the Monit control file.

1830

.PP

1831

The syntax for the gid statement is:

1832

.IP "\s-1IF\s0 \s-1FAILED\s0 \s-1GID\s0 user [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1833

.IX Item "IF FAILED GID user [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1834

.PP

1835

\&\fIuser\fR defines a group id either in numeric or in string form.

1836

.PP

1837

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1838

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1839

.PP

1840

The web interface will show a gid warning if the test should

1841

fail.

1842

.PP

1843

We recommend that you use the \s-1UNMONITOR\s0 action in a gid

1844

statement. The rationale for this feature is security and that

1845

Monit does not start a possible cracked program or script.

1846

Example:

1847

.PP

1848

.Vb 2

1849

\& check file shadow with path /etc/shadow

1850

\& if failed gid root then unmonitor

1851

.Ve

1852

.PP

1853

If the test fails, Monit will simply send an alert and stop

1854

monitoring the file and propagate an unmonitor action upward in

1855

a depend tree.

1856

.SS "\s-1PID\s0 \s-1TESTING\s0"

1857

.IX Subsection "PID TESTING"

1858

Monit can test the process identification number (pid) of a

1859

process for changes. This test is implicit and Monit will send a

1860

alert in the case of failure by default.

1861

.PP

1862

The syntax for the pid statement is:

1863

.IP "\s-1IF\s0 \s-1CHANGED\s0 \s-1PID\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action" 4

1864

.IX Item "IF CHANGED PID [[<X>] <Y> CYCLES] THEN action"

1865

.PP

1866

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1867

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1868

.PP

1869

This test is useful to detect possible process restarts which has

1870

occurred in the timeframe between two Monit testing cycles. In

1871

the case that the restart was fast and the process provides

1872

expected service (i.e. all tests succeeded) you will be notified

1873

that the process was replaced.

1874

.PP

1875

For example sshd daemon can restart very quickly, thus if someone

1876

changes its configuration and do sshd restart outside of Monit's

1877

control you will be notified that the process was replaced by a

1878

new instance (or you can optionally do some other action such as

1879

preventively stop sshd).

1880

.PP

1881

Another example is a MySQL Cluster which has its own watchdog

1882

with process restart ability. You can use Monit for redundant

1883

monitoring.

1884

.PP

1885

Example:

1886

.PP

1887

.Vb 2

1888

\& check process sshd with pidfile /var/run/sshd.pid

1889

\& if changed pid then exec "/my/script"

1890

.Ve

1891

.SS "\s-1PPID\s0 \s-1TESTING\s0"

1892

.IX Subsection "PPID TESTING"

1893

Monit can test the process parent process identification number

1894

(ppid) of a process for changes. This test is implicit and Monit

1895

will send alert in the case of failure by default.

1896

.PP

1897

The syntax for the ppid statement is:

1898

.IP "\s-1IF\s0 \s-1CHANGED\s0 \s-1PPID\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action" 4

1899

.IX Item "IF CHANGED PPID [[<X>] <Y> CYCLES] THEN action"

1900

.PP

1901

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1902

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1903

.PP

1904

This test is useful for detecting changes of a process parent.

1905

.PP

1906

Example:

1907

.PP

1908

.Vb 2

1909

\& check process myproc with pidfile /var/run/myproc.pid

1910

\& if changed ppid then exec "/my/script"

1911

.Ve

1912

.SS "\s-1UPTIME\s0 \s-1TESTING\s0"

1913

.IX Subsection "UPTIME TESTING"

1914

The uptime statement may only be used in a check process service

1915

entry. If specified in the control file, Monit will test the

1916

process uptime.

1917

.PP

1918

Syntax (keywords are in capital):

1919

.IP "\s-1IF\s0 \s-1UPTIME\s0 [[operator] value [unit]] [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1920

.IX Item "IF UPTIME [[operator] value [unit]] [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1921

.PP

1922

\&\fIoperator\fR is a choice of \*(L"<\*(R", \*(L">\*(R", \*(L"!=\*(R", \*(L"==\*(R" in C notation,

1923

\&\*(L"\s-1GT\s0\*(R", \*(L"\s-1LT\s0\*(R", \*(L"\s-1EQ\s0\*(R", \*(L"\s-1NE\s0\*(R" in shell sh notation and \*(L"\s-1GREATER\s0\*(R",

1924

\&\*(L"\s-1LESS\s0\*(R", \*(L"\s-1EQUAL\s0\*(R", \*(L"\s-1NOTEQUAL\s0\*(R" in human readable form (if not

1925

specified, default is \s-1EQUAL\s0).

1926

.PP

1927

\&\fIvalue\fR is a uptime watermark.

1928

.PP

1929

\&\fIunit\fR is either \*(L"\s-1SECOND\s0\*(R", \*(L"\s-1MINUTE\s0\*(R", \*(L"\s-1HOUR\s0\*(R" or \*(L"\s-1DAY\s0\*(R" (it is also

1930

possible to use \*(L"\s-1SECONDS\s0\*(R", \*(L"\s-1MINUTES\s0\*(R", \*(L"\s-1HOURS\s0\*(R", or \*(L"\s-1DAYS\s0\*(R").

1931

.PP

1932

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

1933

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

1934

.PP

1935

Example of restarting the process if the uptime exceeded 3 days:

1936

.PP

1937

.Vb 4

1938

\& check process myapp with pidfile /var/run/myapp.pid

1939

\& start program = "/etc/init.d/myapp start"

1940

\& stop program = "/etc/init.d/myapp stop"

1941

\& if uptime > 3 days then restart

1942

.Ve

1943

.SS "\s-1CONNECTION\s0 \s-1TESTING\s0"

1944

.IX Subsection "CONNECTION TESTING"

1945

Monit is able to perform connection testing via networked

1946

ports or via Unix sockets. A connection test may only be

1947

used within a check process or within a check host service

1948

entry in the Monit control file.

1949

.PP

1950

If a service listens on one or more sockets, Monit can connect to

1951

the port (using either tcp or udp) and verify that the service

1952

will accept a connection and that it is possible to write and

1953

read from the socket. If a connection is not accepted or if there

1954

is a problem with socket i/o, Monit will assume that something is

1955

wrong and execute a specified action. If Monit is compiled with

1956

openssl, then ssl based network services can also be tested.

1957

.PP

1958

The full syntax for the statement used for connection testing is

1959

as follows (keywords are in capital and optional statements in

1960

[brackets]),

1961

.IP "\s-1IF\s0 \s-1FAILED\s0 [host] port [type] [protocol|{send/expect}+] [timeout] [retry] [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1962

.IX Item "IF FAILED [host] port [type] [protocol|{send/expect}+] [timeout] [retry] [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1963

.PP

1964

or for Unix sockets,

1965

.IP "\s-1IF\s0 \s-1FAILED\s0 [unixsocket] [type] [protocol|{send/expect}+] [timeout] [retry] [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

1966

.IX Item "IF FAILED [unixsocket] [type] [protocol|{send/expect}+] [timeout] [retry] [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

1967

.PP

1968

\&\fBhost:HOST hostname\fR. Optionally specify the host to connect to.

1969

If the host is not given then localhost is assumed if this test

1970

is used inside a process entry. If this test was used inside a

1971

remote host entry then the entry's remote host is assumed.

1972

Although \fIhost\fR is intended for testing name based virtual host

1973

in a \s-1HTTP\s0 server running on local or remote host, it does allow

1974

the connection statement to be used to test a server running on

1975

another machine. This may be useful; For instance if you use

1976

Apache httpd as a front-end and an application-server as the

1977

back-end running on another machine, this statement may be used

1978

to test that the back-end server is running and if not raise an

1979

alert.

1980

.PP

1981

\&\fBport:PORT number\fR. The port number to connect to

1982

.PP

1983

\&\fBunixsocket:UNIXSOCKET \s-1PATH\s0\fR. Specifies the path to a Unix

1984

socket. Servers based on Unix sockets always run on the local

1985

machine and do not use a port.

1986

.PP

1987

\&\fBtype:TYPE {TCP|UDP|TCPSSL}\fR. Optionally specify the socket type

1988

Monit should use when trying to connect to the port. The

1989

different socket types are; \s-1TCP\s0, \s-1UDP\s0 or \s-1TCPSSL\s0, where \s-1TCP\s0 is a

1990

regular stream based socket, \s-1UDP\s0 is a datagram socket and \s-1TCPSSL\s0

1991

specifies that Monit should use a \s-1TCP\s0 socket with \s-1SSL\s0 when

1992

connecting to a port. The default socket type is \s-1TCP\s0. If \s-1TCPSSL\s0

1993

is used you may optionally specify the \s-1SSL/TLS\s0 protocol to be

1994

used and the md5 sum of the server's certificate. The \s-1TCPSSL\s0

1995

options are:

1996

.PP

1997

.Vb 1

1998

\& TCPSSL [SSLAUTO|SSLV2|SSLV3|TLSV1] [CERTMD5 md5sum]

1999

.Ve

2000

.PP

2001

\&\fBproto(col):PROTO {protocols}\fR. Optionally specify the protocol

2002

Monit should speak when a connection is established. At the

2003

moment Monit knows how to speak:

2004

\fIAPACHE-STATUS\fR

2005

\fI\s-1DNS\s0\fR

2006

\fI\s-1DWP\s0\fR

2007

\fI\s-1FTP\s0\fR

2008

\fI\s-1GPS\s0\fR

2009

\fI\s-1HTTP\s0\fR

2010

\fI\s-1IMAP\s0\fR

2011

\fI\s-1CLAMAV\s0\fR

2012

\fI\s-1LDAP2\s0\fR

2013

\fI\s-1LDAP3\s0\fR

2014

\fI\s-1LMTP\s0\fR

2015

\fI\s-1MEMCACHE\s0\fR

2016

\fI\s-1MYSQL\s0\fR

2017

\fI\s-1NNTP\s0\fR

2018

\fI\s-1NTP3\s0\fR

2019

\fI\s-1POP\s0\fR

2020

\fIPOSTFIX-POLICY\fR

2021

\fI\s-1RADIUS\s0\fR

2022

\fI\s-1RDATE\s0\fR

2023

\fI\s-1RSYNC\s0\fR

2024

\fI\s-1SIP\s0\fR

2025

\fI\s-1SMTP\s0\fR

2026

\fI\s-1SSH\s0\fR

2027

\fI\s-1TNS\s0\fR

2028

\fI\s-1PGSQL\s0\fR

2029

If you have compiled Monit with ssl support, Monit can also speak

2030

the \s-1SSL\s0 variants such as:

2031

\fI\s-1HTTPS\s0\fR

2032

\fI\s-1FTPS\s0\fR

2033

\fI\s-1POPS\s0\fR

2034

\fI\s-1IMAPS\s0\fR

2035

To use the \s-1SSL\s0 protocol support you need to define the socket as

2036

\&\s-1SSL\s0 and use the general protocol name (for example in the case of

2037

\&\s-1HTTPS\s0) :

2038

\s-1TYPE\s0 \s-1TCPSSL\s0 \s-1PROTOCOL\s0 \s-1HTTP\s0

2039

If the server's protocol is not found in this list, simply do not

2040

specify the protocol and Monit will utilize a default test,

2041

including test if it is possible to read and write to the

2042

port. This default test is in most cases more than good enough to

2043

deduce if the server behind the port is up or not.

2044

.PP

2045

The protocol statement is:

2046

.PP

2047

.Vb 1

2048

\& PROTO(COL) {name}

2049

.Ve

2050

.PP

2051

The \s-1HTTP\s0 protocol supports in addition:

2052

.IP "\(bu" 4

2053

\&\s-1REQUEST\s0

2054

.IP "\(bu" 4

2055

\&\s-1HOSTHEADER\s0

2056

.IP "\(bu" 4

2057

\&\s-1CHECKSUM\s0

2058

.PP

2059

.Vb 1

2060

\& PROTO(COL) HTTP [REQUEST {"/path"} [with CHECKSUM checksum] [with HOSTHEADER "string"]

2061

.Ve

2062

.PP

2063

The Host header option can be used to explicit specify the \s-1HTTP\s0

2064

host header in the request. If not used, Monit will use the

2065

hostname or IP-address of the host as specified in the statement.

2066

Specifying a host header is useful if you want to connect to the

2067

host using an IP-address, and the web-server handle name based

2068

virtual hosts. Examples:

2069

.PP

2070

.Vb 4

2071

\& if failed host 192.168.1.100 port 8080 protocol http

2072

\& and request \*(Aq/testing\*(Aq hostheader \*(Aqexample.com\*(Aq

2073

\& with timeout 20 seconds for 2 cycles

2074

\& then alert

2075

.Ve

2076

.PP

2077

In addition to the standard protocols, the \fIAPACHE-STATUS\fR

2078

protocol is a test of a specific server type, rather than a

2079

generic protocol. Server performance is examined using the status

2080

page generated by Apache's mod_status, which is expected to be at

2081

its default address of http://www.example.com/server\-status.

2082

Currently the \fIAPACHE-STATUS\fR protocol examines the percentage

2083

of Apache child processes which are

2084

.PP

2085

.Vb 10

2086

\& o logging (loglimit)

2087

\& o closing connections (closelimit)

2088

\& o performing DNS lookups (dnslimit)

2089

\& o in keepalive with a client (keepalivelimit)

2090

\& o replying to a client (replylimit)

2091

\& o receiving a request (requestlimit)

2092

\& o initialising (startlimit)

2093

\& o waiting for incoming connections (waitlimit)

2094

\& o gracefully closing down (gracefullimit)

2095

\& o performing cleanup procedures (cleanuplimit)

2096

.Ve

2097

.PP

2098

Each of these quantities can be compared against a value relative

2099

to the total number of active Apache child processes. If the

2100

comparison expression is true the chosen action is performed.

2101

.PP

2102

The apache-status protocol statement is formally defined as

2103

(keywords in uppercase):

2104

.PP

2105

.Vb 1

2106

\& PROTO(COL) {limit} OP PERCENT [OR {limit} OP PERCENT]*

2107

.Ve

2108

.PP

2109

where {limit} is one or more of: loglimit, closelimit, dnslimit,

2110

keepalivelimit, replylimit, requestlimit, startlimit, waitlimit

2111

gracefullimit or cleanuplimit. The operator \s-1OP\s0 is one of:

2112

[<|=|>].

2113

.PP

2114

You can combine all of these test into one expression or you can

2115

choose to test a certain limit. If you combine the limits you

2116

must or' them together using the \s-1OR\s0 keyword.

2117

.PP

2118

Here's an example were we test for a loglimit more than 10

2119

percent, a dnslimit over 25 percent and a wait limit less than 20

2120

percent of processes. See also more examples below in the example

2121

section.

2122

.PP

2123

.Vb 5

2124

\& protocol apache\-status

2125

\& loglimit > 10% or

2126

\& dnslimit > 50% or

2127

\& waitlimit < 20%

2128

\& then alert

2129

.Ve

2130

.PP

2131

Obviously, do not use this test unless the httpd server you are

2132

testing is Apache Httpd and mod_status is activated on the

2133

server.

2134

.PP

2135

\&\fBsend/expect: {SEND|EXPECT} \*(L"string\*(R" ...\fR. If Monit does not

2136

support the protocol spoken by the server, you can write your own

2137

protocol-test using \fIsend\fR and \fIexpect\fR strings. The \fI\s-1SEND\s0\fR

2138

statement sends a string to the server port and the \fI\s-1EXPECT\s0\fR

2139

statement compares a string read from the server with the string

2140

given in the expect statement. If your system supports \s-1POSIX\s0

2141

regular expressions, you can use regular expressions in the

2142

expect string, see \fIregex\fR\|(7) to learn more about the types of

2143

regular expressions you can use in an expect string. Otherwise

2144

the string is used as it is. The send/expect statement is:

2145

.PP

2146

.Vb 1

2147

\& [{SEND|EXPECT} "string"]+

2148

.Ve

2149

.PP

2150

Note that Monit will send a string as it is, and you \fBmust\fR

2151

remember to include \s-1CR\s0 and \s-1LF\s0 in the string sent to the server if

2152

the protocol expect such characters to terminate a string (most

2153

text based protocols used over Internet does). Likewise monit

2154

will read up to 256 bytes from the server and use this string

2155

when comparing the expect string. If the server sends strings

2156

terminated by \s-1CRLF\s0, (i.e. \*(L"\er\en\*(R") you \fImay\fR remember to add the

2157

same terminating characters to the string you expect from the

2158

server.

2159

.PP

2160

As mentioned above, Monit limits the expect input to 255 bytes.

2161

You can override the default value by using this set statement at

2162

the top of the Monit configuration file:

2163

.PP

2164

.Vb 1

2165

\& SET EXPECTBUFFER <number> ["b"|"kb"|"mb"]

2166

.Ve

2167

.PP

2168

For example, to set the expect buffer to read 10 kilobytes:

2169

.PP

2170

.Vb 1

2171

\& set expectbuffer 10 kb

2172

.Ve

2173

.PP

2174

Note, if you want to test the number of bytes returned from the

2175

server you need to work around a bound check limit in \s-1POSIX\s0

2176

regex. You cannot use something like expect \*(L".{5000}\*(R" as the max

2177

number in a boundary check usually is {255}. However this should

2178

work, expect \*(L"(.{250}){20}\*(R"

2179

.PP

2180

You can use non-printable characters in a send string if needed.

2181

Use the hex notation, \e0xHEXHEX to send any char in the range

2182

\&\e0x00\-\e0xFF, that is, 0\-255 in decimal. This may be useful when

2183

testing some network protocols, particularly those over \s-1UDP\s0. For

2184

example, to test a quake 3 server you can use the following,

2185

.PP

2186

.Vb 2

2187

\& send "\e0xFF\e0xFF\e0xFF\e0xFFgetstatus"

2188

\& expect "sv_floodProtect|sv_maxPing"

2189

.Ve

2190

.PP

2191

Finally, send/expect can be used with any socket type, such as

2192

\&\s-1TCP\s0 sockets, \s-1UNIX\s0 sockets and \s-1UDP\s0 sockets.

2193

.PP

2194

\&\fBtimeout:with \s-1TIMEOUT\s0 x \s-1SECONDS\s0\fR. Optionally specifies the

2195

connect and read timeout for the connection. If Monit cannot

2196

connect to the server within this time it will assume that the

2197

connection failed and execute the specified action. The default

2198

connect timeout is 5 seconds.

2199

.PP

2200

\&\fBretry:RETRY x\fR. Optionally specifies the number of consecutive

2201

retries within the same testing cycle in the case that the

2202

connection failed. The default is fail on first error.

2203

.PP

2204

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

2205

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

2206

.PP

2207

Connection testing using the \s-1URL\s0 notation

2208

.IX Subsection "Connection testing using the URL notation"

2209

.PP

2210

You can test a \s-1HTTP\s0 server using the compact \s-1URL\s0 syntax. This

2211

test also allow you to use \s-1POSIX\s0 regular expressions to test the

2212

content returned by the \s-1HTTP\s0 server.

2213

.PP

2214

The full syntax for the \s-1URL\s0 statement is as follows (keywords are

2215

in capital and optional statements in [brackets]):

2216

.PP

2217

.Vb 5

2218

\& IF FAILED URL URL\-spec

2219

\& [CONTENT {==|!=} "regular\-expression"]

2220

\& [TIMEOUT number SECONDS] [[<X>] <Y> CYCLES]

2221

\& THEN action

2222

\& [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]

2223

.Ve

2224

.PP

2225

Where URL-spec is an \s-1URL\s0 on the standard form as specified in \s-1RFC\s0

2226

2396:

2227

.PP

2228

.Vb 1

2229

\& <protocol>://<authority><path>?<query>

2230

.Ve

2231

.PP

2232

Here is an example of an \s-1URL\s0 where all components are used:

2233

.PP

2234

.Vb 1

2235

\& http://user:password@www.foo.bar:8080/document/?querystring#ref

2236

.Ve

2237

.PP

2238

If a username and password is included in the \s-1URL\s0 Monit will

2239

attempt to login at the server using \fBBasic Authentication\fR.

2240

.PP

2241

Testing the content returned by the server is optional. If used,

2242

you can test if the content \fBmatch\fR or does \fBnot match\fR a

2243

regular expression. Here's an example on how the \s-1URL\s0 statement

2244

can be used in a \fIcheck service\fR:

2245

.PP

2246

.Vb 4

2247

\& check host FOO with address www.foo.bar

2248

\& if failed (url http://user:password@www.foo.bar:8080/login?querystring

2249

\& and content == \*(Aqup\*(Aq)

2250

\& then ...

2251

.Ve

2252

.PP

2253

Note that the content option extends the \s-1URL\s0 by the expected data

2254

and does not act as standalone failure specification. The syntax is

2255

\&\*(L"if failed (<\s-1URL\s0> and <content>)\*(R".

2256

.PP

2257

Monit will look at the content-length header returned by the

2258

server and download this amount before testing the content. That

2259

is, if the content-length is more than 1Mb or this header is not

2260

set by the server Monit will default to download up to 1 Mb and

2261

not more.

2262

.PP

2263

Only the http(s) protocol is supported in an \s-1URL\s0 statement. If

2264

the protocol is \fBhttps\fR Monit will use \s-1SSL\s0 when connecting to

2265

the server.

2266

.PP

2267

Remote host ping test

2268

.IX Subsection "Remote host ping test"

2269

.PP

2270

In addition Monit can perform \s-1ICMP\s0 Echo tests in remote host

2271

checks. The icmp test may only be used in a check host entry and

2272

Monit must run with super user privileges, that is, the root user

2273

must run monit. The reason is that the icmp test utilize a raw

2274

socket to send the icmp packet and only the super user is allowed

2275

to create a raw socket.

2276

.PP

2277

The full syntax for the \s-1ICMP\s0 Echo statement used for ping testing

2278

is as follows (keywords are in capital and optional statements in

2279

[brackets]):

2280

.PP

2281

.Vb 5

2282

\& IF FAILED ICMP TYPE ECHO

2283

\& [COUNT number] [WITH] [TIMEOUT number SECONDS]

2284

\& [[<X>] <Y> CYCLES]

2285

\& THEN action

2286

\& [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]

2287

.Ve

2288

.PP

2289

The rules for action and timeout are the same as those mentioned

2290

above in the \s-1CONNECTION\s0 \s-1TESTING\s0 section. The count parameter

2291

specifies how many consecutive echo requests will be send to the

2292

host in one cycle. In the case that no reply came within timeout

2293

frame, Monit reports error. When at least one reply was received,

2294

the test will pass. Monit sends by default three echo requests in

2295

one cycle to prevent the random packet loss from generating false

2296

alarm (i.e. up to 66% packet loss is tolerated). You can set the

2297

count option to a value between 1 and 20, which can serve as an

2298

error ratio. For example if you require 100% ping success, set

2299

the count to 1 (i.e. just one request will be sent, and if the

2300

packet was lost an error will be reported).

2301

.PP

2302

An icmp ping test is useful for testing if a host is up, before

2303

testing ports at the host. If an icmp ping test is used in a

2304

check host entry, this test is run first and if the ping test

2305

should fail we assume that the connection to the host is down and

2306

Monit does \fInot\fR continue to test any ports. Here's an example:

2307

.PP

2308

.Vb 6

2309

\& check host xyzzy with address xyzzy.org

2310

\& if failed icmp type echo count 5 with timeout 15 seconds

2311

\& then alert

2312

\& if failed port 80 proto http then alert

2313

\& if failed port 443 type TCPSSL proto http then alert

2314

\& alert foo@bar

2315

.Ve

2316

.PP

2317

In this case, if the icmp test should fail you will get \fIone\fR

2318

alert and only one alert as long as the host is down, and equally

2319

important, Monit will \fInot\fR test port 80 and port 443. Likewise

2320

if the icmp ping test should succeed (again) Monit will continue

2321

to test both port 80 and 443.

2322

.PP

2323

Keep in mind though that some firewalls can block icmp packages

2324

and thus render the test useless.

2325

.PP

2326

Examples

2327

.IX Subsection "Examples"

2328

.PP

2329

To check a port connection and receive an alert if Monit cannot

2330

connect to the port, use the following statement:

2331

.PP

2332

.Vb 1

2333

\& if failed port 80 then alert

2334

.Ve

2335

.PP

2336

In this case the machine in question is assumed to be the default

2337

host. For a process entry it's \fIlocalhost\fR and for a remote host

2338

entry it's the \fIaddress\fR of the remote host. Monit will conduct

2339

a tcp connection to the host at port 80 and use tcp by default.

2340

If you want to connect with udp, you can specify this after the

2341

port-statement;

2342

.PP

2343

.Vb 1

2344

\& if failed port 53 type udp protocol dns then alert

2345

.Ve

2346

.PP

2347

Monit will stop trying to connect to the port after 5 seconds and

2348

assume that the server behind the port is down. You may increase

2349

or decrease the connect timeout by explicit add a connection

2350

timeout. In the following example the timeout is increased to 15

2351

seconds and if Monit cannot connect to the server within 15

2352

seconds the test will fail and an alert message is sent.

2353

.PP

2354

.Vb 1

2355

\& if failed port 80 with timeout 15 seconds then alert

2356

.Ve

2357

.PP

2358

If a server is listening to a Unix socket the following statement

2359

can be used:

2360

.PP

2361

.Vb 1

2362

\& if failed unixsocket /var/run/sophie then alert

2363

.Ve

2364

.PP

2365

A Unix socket is used by some servers for fast (interprocess)

2366

communication on localhost only. A Unix socket is specified by a

2367

path and in the example above the path, /var/run/sophie,

2368

specifies a Unix socket.

2369

.PP

2370

If your machine answers for several virtual hosts you can prefix

2371

the port statement with a host-statement like so:

2372

.PP

2373

.Vb 3

2374

\& if failed host www.sol.no port 80 then alert

2375

\& if failed host 80.69.226.133 port 443 then alert

2376

\& if failed host kvasir.sol.no port 80 then alert

2377

.Ve

2378

.PP

2379

And as mentioned above, if you do not specify a host-statement,

2380

\&\fIlocalhost\fR or \fIaddress\fR is assumed.

2381

.PP

2382

Monit also knows how to speak some of the more popular Internet

2383

protocols. So, besides testing for connections, Monit can also

2384

speak with the server in question to verify that the server

2385

works. For example, the following is used to test a http server:

2386

.PP

2387

.Vb 2

2388

\& if failed host www.tildeslash.com port 80 proto http

2389

\& then restart

2390

.Ve

2391

.PP

2392

Some protocols also support a request statement. This statement

2393

can be used to ask the server for a special document entity.

2394

.PP

2395

Currently \fBonly\fR the \fI\s-1HTTP\s0\fR protocol module supports the

2396

request statement, such as:

2397

.PP

2398

.Vb 3

2399

\& if failed host www.myhost.com port 80 protocol http

2400

\& and request "/data/show.php?a=b&c=d"

2401

\& then restart

2402

.Ve

2403

.PP

2404

The request must contain an \s-1URI\s0 string specifying a document from

2405

the http server. The string will be \s-1URL\s0 encoded by Monit before

2406

it sends the request to the http server, so it's okay to use \s-1URL\s0

2407

unsafe characters in the request. If the request statement isn't

2408

specified, the default web server page will be requested.

2409

.PP

2410

You can override default Host header in \s-1HTTP\s0 request:

2411

.PP

2412

.Vb 3

2413

\& if failed host 192.168.1.100 port 80 protocol http

2414

\& hostheader "example.com"

2415

\& then alert

2416

.Ve

2417

.PP

2418

You can also test the checksum for documents returned by a http

2419

server. You can use either \s-1MD5\s0 sums:

2420

.PP

2421

.Vb 4

2422

\& if failed port 80 protocol http

2423

\& and request "/page.html"

2424

\& with checksum 8f7f419955cefa0b33a2ba316cba3659

2425

\& then alert

2426

.Ve

2427

.PP

2428

Or you can use \s-1SHA1\s0 sums:

2429

.PP

2430

.Vb 4

2431

\& if failed port 80 protocol http

2432

\& and request "/page.html"

2433

\& with checksum e428302e260e0832007d82de853aa8edf19cd872

2434

\& then alert

2435

.Ve

2436

.PP

2437

Monit will compute a checksum (either \s-1MD5\s0 or \s-1SHA1\s0 is used,

2438

depending on length of the hash) for the document (in the above

2439

case, /page.html) and compare the computed checksum with the

2440

expected checksum. If the sums does not match then the if-tests

2441

action is performed, in this case alert. Note that Monit will

2442

\&\fBnot\fR test the checksum for a document if the server does not

2443

set the \s-1HTTP\s0 \fIContent-Length\fR header. A \s-1HTTP\s0 server should set

2444

this header when it server a static document (i.e. a file). A

2445

server will often use chunked transfer encoding instead when

2446

serving dynamic content (e.g. a document created by a CGI-script

2447

or a Servlet), but to test the checksum for dynamic content is

2448

not very useful. There are no limitation on the document size,

2449

but keep in mind that Monit will use time to download the

2450

document over the network so it's probably smart not to ask monit

2451

to compute a checksum for documents larger than 1Mb or so,

2452

depending on you network connection of course. Tip; If you get a

2453

checksum error even if the document has the correct sum, the

2454

reason may be that the download timed out. In this case, explicit

2455

set a longer timeout than the default 5 seconds.

2456

.PP

2457

As mentioned above, if the server protocol is not supported by

2458

Monit you can write your own protocol test using send/expect

2459

strings. Here we show a protocol test using send/expect for an

2460

imaginary \*(L"Ali Baba and the Forty Thieves\*(R" protocol:

2461

.PP

2462

.Vb 6

2463

\& if failed host cave.persia.ir port 4040

2464

\& send "Open, Sesame!\er\en"

2465

\& expect "Please enter the cave\er\en"

2466

\& send "Shut, Sesame!\er\en"

2467

\& expect "See you later [A\-Za\-z ]+\er\en"

2468

\& then restart

2469

.Ve

2470

.PP

2471

The \fI\s-1TCPSSL\s0\fR statement can optionally test the md5 sum of the

2472

server's certificate. You must state the md5 certificate string

2473

you expect the server to deliver and upon a connect to the

2474

server, the server's actual md5 sum certificate string is tested.

2475

Any other symbol but [A\-Fa\-f0\-9] is being ignored in that sting.

2476

Thus it is possible to copy and paste the output of e.g. openssl.

2477

If they do not match, the connection test fails. If the ssl

2478

version handshake does not work properly you can also force a

2479

specific ssl version, as we demonstrate in this example:

2480

.PP

2481

.Vb 10

2482

\& if failed host shop.sol.no port 443

2483

\& type TCPSSL SSLV3 # Force Monit to use ssl version 3

2484

\& # We expect the server to return this md5 certificate sum

2485

\& # as either 12\-34\-56\-78\-90\-AB\-CD\-EF\-12\-34\-56\-78\-90\-AB\-CD\-EF

2486

\& # or e.g. 1234567890ABCDEF1234567890ABCDEF

2487

\& # or e.g. 1234567890abcdef1234567890abcdef

2488

\& # what ever come in more handy (see text above)

2489

\& CERTMD5 12\-34\-56\-78\-90\-AB\-CD\-EF\-12\-34\-56\-78\-90\-AB\-CD\-EF

2490

\& protocol http

2491

\& then restart

2492

.Ve

2493

.PP

2494

Here's an example where a connection test is used inside a

2495

process entry:

2496

.PP

2497

.Vb 4

2498

\& check process apache with pidfile /var/run/apache.pid

2499

\& start program = "/etc/init.d/httpd start"

2500

\& stop program = "/etc/init.d/httpd stop"

2501

\& if failed host www.tildeslash.com port 80 then restart

2502

.Ve

2503

.PP

2504

Here, a connection test is used in a remote host entry:

2505

.PP

2506

.Vb 2

2507

\& check host up2date with address ftp.redhat.com

2508

\& if failed port 21 and protocol ftp then alert

2509

.Ve

2510

.PP

2511

Since we did not explicit specify a host in the above test, monit

2512

will connect to port 21 at ftp.redhat.com. Apropos, the host

2513

address can be specified as a dotted \s-1IP\s0 address string or as

2514

hostname in the \s-1DNS\s0. The following is exactly[*] the same test,

2515

but here an ip address is used instead:

2516

.PP

2517

.Vb 2

2518

\& check host up2date with address 66.187.232.30

2519

\& if failed port 21 and protocol ftp then alert

2520

.Ve

2521

.PP

2522

[*] Well, not quite, since we specify an ip-address directly we

2523

will bypass any \s-1DNS\s0 round-robin setup, but that's another story.

2524

.PP

2525

Testing the \s-1SIP\s0 protocol

2526

.IX Subsection "Testing the SIP protocol"

2527

.PP

2528

The \s-1SIP\s0 protocol is used by communication platform servers such

2529

as Asterisk and FreeSWITCH.

2530

.PP

2531

The \s-1SIP\s0 test is similar to the other protocol tests, but in

2532

addition allows extra optional parameters.

2533

.IP "\s-1IF\s0 \s-1FAILED\s0 [host] [port] [type] \s-1PROTOCOL\s0 sip [\s-1AND\s0] [\s-1TARGET\s0 valid@uri] [\s-1AND\s0] [\s-1MAXFORWARD\s0 n] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

2534

.IX Item "IF FAILED [host] [port] [type] PROTOCOL sip [AND] [TARGET valid@uri] [AND] [MAXFORWARD n] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

2535

.PP

2536

\&\s-1TARGET\s0 :

2537

you may specify an alternative recipient for the message,

2538

by adding a valid sip uri after this keyword.

2539

.PP

2540

\&\s-1MAXFORWARD\s0 :

2541

Limit the number of proxies or gateways that can forward the

2542

request to the next server. It's value is an integer in the range

2543

0\-255, set by default to 70. If max-forward = 0, the next server

2544

may respond 200 \s-1OK\s0 (test succeeded) or send a 483 Too Many Hops

2545

(test failed)

2546

.PP

2547

\&\s-1SIP\s0 examples:

2548

.PP

2549

.Vb 4

2550

\& check host openser_all with address 127.0.0.1

2551

\& if failed port 5060 type udp protocol sip

2552

\& with target "localhost:5060" and maxforward 6

2553

\& then alert

2554

.Ve

2555

.PP

2556

If sips is supported, that is, sip over ssl, specify tcpssl as

2557

the connection type.

2558

.PP

2559

.Vb 4

2560

\& check host fwd.pulver.com with address fwd.pulver.com

2561

\& if failed port 5060 type tcpssl protocol SIP

2562

\& and target 613@fwd.pulver.com maxforward 10

2563

\& then alert

2564

.Ve

2565

.PP

2566

For more examples, see the example section below.

2567

.PP

2568

Testing the \s-1RADIUS\s0 protocol

2569

.IX Subsection "Testing the RADIUS protocol"

2570

.PP

2571

The \s-1RADIUS\s0 test is similar to the other protocol tests, but in

2572

addition allows extra optional parameters.

2573

.IP "\s-1IF\s0 \s-1FAILED\s0 [host] [port] [type] \s-1PROTOCOL\s0 radius [\s-1SECRET\s0 string] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

2574

.IX Item "IF FAILED [host] [port] [type] PROTOCOL radius [SECRET string] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

2575

.PP

2576

\&\s-1SECRET:\s0

2577

you may specify an alternative secret, default is \*(L"testing123\*(R".

2578

.PP

2579

\&\s-1RADIUS\s0 example:

2580

.PP

2581

.Vb 7

2582

\& check process radiusd with pidfile /var/run/radiusd.pid

2583

\& start program = "/etc/init.d/freeradius start"

2584

\& stop program = "/etc/init.d/freeradius stop"

2585

\& if failed host 127.0.0.1 port 1812 type udp protocol radius

2586

\& secret testing123

2587

\& then alert

2588

\& if 5 restarts within 5 cycles then timeout

2589

.Ve

2590

.SS "\s-1PROGRAM\s0 \s-1STATUS\s0 \s-1TESTING\s0"

2591

.IX Subsection "PROGRAM STATUS TESTING"

2592

You can check the exit status of a program or a script. This test

2593

may only be used within a check program service entry in the Monit

2594

control file.

2595

.PP

2596

An example:

2597

.PP

2598

.Vb 2

2599

\& check program myscript with path "/usr/local/bin/myscript.sh" with timeout 1000 seconds

2600

\& if status != 0 then alert

2601

.Ve

2602

.PP

2603

Sample script for the above example (/usr/local/bin/myscript.sh):

2604

.PP

2605

.Vb 3

2606

\& #!/bin/bash

2607

\& echo test

2608

\& exit $?

2609

.Ve

2610

.PP

2611

Notes: The interpreter (first line) is required unless the executed

2612

program is binary. The program must be executable.

2613

.PP

2614

Monit will execute the program periodically and if the exit

2615

status of the program does not match the expected result, Monit

2616

can perform an action. In the example above, Monit will raise an

2617

alert if the exit value of \fImyscript\fR is different from 0. By

2618

convention, 0 means the program exited normally.

2619

.PP

2620

Program checks are asynchronous. Meaning that Monit will not wait

2621

for the program to exit, but instead, Monit will start the

2622

program in the background and immediately continue checking the

2623

next service entry in \fImonitrc\fR. At the next cycle, Monit will

2624

check if the program has finished and if so, collect the programs

2625

exit status \- if the status indicate a failure, Monit will raise

2626

an alert message containing the program's error (stderr) output,

2627

if any. If the program has not exited after the first cycle,

2628

Monit will wait another cycle and so on. If the program is still

2629

running after 5 minutes, Monit will kill it and generate a

2630

program timeout event. It is possible to override the default

2631

timeout (see the syntax below).

2632

.PP

2633

The asynchronous nature of the program check allows for

2634

non-blocking behavior in the current Monit design, but it comes

2635

with a side-effect: when the program has finished executing and

2636

is waiting for Monit to collect the result, it becomes a

2637

so-called \*(L"zombie\*(R" process. A zombie process does not consume

2638

any system resources (only the \s-1PID\s0 remains in use) and it is

2639

under Monit's control; The zombie process is removed from the

2640

system as soon as Monit collects the exit status. This means that

2641

every \*(L"check program\*(R" will be associated with either a running

2642

process or a temporary zombie. This unwanted zombie side-effect

2643

will be removed in a later release of Monit.

2644

.PP

2645

The syntax of the program status statement is:

2646

.IP "\s-1IF\s0 \s-1STATUS\s0 operator value [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action [\s-1ELSE\s0 \s-1IF\s0 \s-1SUCCEEDED\s0 [[<X>] <Y> \s-1CYCLES\s0] \s-1THEN\s0 action]" 4

2647

.IX Item "IF STATUS operator value [[<X>] <Y> CYCLES] THEN action [ELSE IF SUCCEEDED [[<X>] <Y> CYCLES] THEN action]"

2648

.PP

2649

\&\fIoperator\fR is a choice of \*(L"<\*(R",\*(L">\*(R",\*(L"!=\*(R",\*(L"==\*(R" in c notation, \*(L"gt\*(R",

2650

\&\*(L"lt\*(R", \*(L"eq\*(R", \*(L"ne\*(R" in shell sh notation and \*(L"greater\*(R", \*(L"less\*(R",

2651

\&\*(L"equal\*(R", \*(L"notequal\*(R" in human readable form (if not specified,

2652

default is \s-1EQUAL\s0).

2653

.PP

2654

\&\fIaction\fR is a choice of \*(L"\s-1ALERT\s0\*(R", \*(L"\s-1RESTART\s0\*(R", \*(L"\s-1START\s0\*(R", \*(L"\s-1STOP\s0\*(R",

2655

\&\*(L"\s-1EXEC\s0\*(R" or \*(L"\s-1UNMONITOR\s0\*(R".

2656

.PP

2657

Multiple status tests can be used, for example:

2658

.PP

2659

.Vb 3

2660

\& check program hwtest with path "/usr/local/bin/hwtest.sh"

2661

\& if status = 1 then alert

2662

\& if status = 3 for 5 cycles then exec "/usr/local/bin/emergency.sh"

2663

.Ve

2664

.SH "SERVICE POLL TIME"

2665

.IX Header "SERVICE POLL TIME"

2666

Services are checked in regular intervals given by the \fIset

2667

daemon n\fR statement. Checks are performed in the same order as

2668

they are written in the \fI.monitrc\fR file, except if dependencies

2669

are setup between services, in which case the services hierarchy

2670

may alternate the order of the checks.

2671

.PP

2672

It is possible to modify the check schedule using the \fIevery\fR

2673

statement.

2674

.PP

2675

There are three variants:

2676

.IP "1. custom interval based on poll cycle length multiple" 4

2677

.IX Item "1. custom interval based on poll cycle length multiple"

2678

.Vb 1

2679

\& EVERY [number] CYCLES

2680

.Ve

2681

.IP "2. test schedule based on cron-style string" 4

2682

.IX Item "2. test schedule based on cron-style string"

2683

.Vb 1

2684

\& EVERY [cron]

2685

.Ve

2686

.IP "3. do-not-test schedule based on cron-style string" 4

2687

.IX Item "3. do-not-test schedule based on cron-style string"

2688

.Vb 1

2689

\& NOT EVERY [cron]

2690

.Ve

2691

.PP

2692

A cron-style string, consist of 5 fields separated with

2693

white-space. All fields are required:

2694

.PP

2695

.Vb 7

2696

\& Name: | Allowed values: | Special characters:

2697

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

2698

\& Minutes | 0\-59 | * \- ,

2699

\& Hours | 0\-23 | * \- ,

2700

\& Day of month | 1\-31 | * \- ,

2701

\& Month | 1\-12 (1=jan, 12=dec) | * \- ,

2702

\& Day of week | 0\-6 (0=sunday, 6=saturday) | * \- ,

2703

.Ve

2704

.PP

2705

The special characters:

2706

.PP

2707

.Vb 10

2708

\& Character: | Description:

2709

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

2710

\& * (asterisk) | The asterisk indicates that the expression will

2711

\& | match for all values of the field; e.g., using

2712

\& | an asterisk in the 4th field (month) would

2713

\& | indicate every month.

2714

\& \- (hyphen) | Hyphens are used to define ranges. For example,

2715

\& | 8\-9 in the hour field indicate between 8AM and

2716

\& | 9AM. Note that range is from time1 until and

2717

\& | including time2. That is, from 8AM and until

2718

\& | 10AM unless minutes are set. Another example,

2719

\& | 1\-5 in the weekday field, specify from monday to

2720

\& | friday (including friday).

2721

\& , (comma) | Comma are used to specify a sequence. For example

2722

\& | 17,18 in the day field indicate the 17th and 18th

2723

\& | day of the month. A sequence can also include

2724

\& | ranges. For example, using 1\-5,0 in the weekday

2725

\& | field indicate monday to friday and sunday.

2726

.Ve

2727

.PP

2728

Example 1: Check once per two cycles

2729

.PP

2730

.Vb 2

2731

\& check process nginx with pidfile /var/run/nginx.pid

2732

\& every 2 cycles

2733

.Ve

2734

.PP

2735

Example 2: Check every workday 8AM\-7PM

2736

.PP

2737

.Vb 3

2738

\& check program checkOracleDatabase with

2739

\& path /var/monit/programs/checkoracle.pl

2740

\& every "* 8\-19 * * 1\-5"

2741

.Ve

2742

.PP

2743

Example 3: Do not run the check in the backup window on

2744

Sunday 0AM\-3AM

2745

.PP

2746

.Vb 2

2747

\& check process mysqld with pidfile /var/run/mysqld.pid

2748

\& not every "* 0\-3 * * 0"

2749

.Ve

2750

.PP

2751

Limitations:

2752

.PP

2753

The current test scheduler is poll cycle based. When Monit starts

2754

testing and the service test is constraint with the \fIevery cron\fR

2755

statement, it checks whether the current time match the

2756

cron-string pattern. If it does, the test is done, otherwise it

2757

is skipped. The cron specification thus does not guarantee when

2758

exactly the test will run \- that depends on the default poll time

2759

and the length of the testing cycle. In other words, we cannot

2760

guarantee that Monit will run on a specific time. Therefor we

2761

\&\fBstrongly\fR recommend to use an asterix in the minute field or at

2762

minimum a range, e..g. 0\-15. \fBNever\fR use a specific minute as

2763

Monit may not run on that minute.

2764

.PP

2765

We will address this limitation in a future release and convert

2766

the test scheduler from serial polling into a parallel

2767

non-blocking scheduler where checks are guaranteed to run on time

2768

and with seconds resolution.

2769

.SH "MONIT HTTPD"

2770

.IX Header "MONIT HTTPD"

2771

If specified in the control file, Monit will start a Monit daemon

2772

with http support. From a Browser you can then start and stop

2773

services, disable or enable service monitoring as well as view

2774

the status of each service. Also, if Monit logs to its own file,

2775

you can view the content of this logfile in a Browser.

2776

.PP

2777

The control file statement for starting a Monit daemon with http

2778

support is a global set-statement:

2779

.IP "set httpd port 2812" 4

2780

.IX Item "set httpd port 2812"

2781

.PP

2782

And you can use this \s-1URL\s0, \fIhttp://localhost:2812/\fR, to access

2783

the daemon from a browser. The port number, in this case 2812,

2784

can be any number that you are allowed to bind to.

2785

.PP

2786

If you have compiled Monit with openssl, you can also start the

2787

httpd server with ssl support, using the following expression:

2788

.PP

2789

.Vb 3

2790

\& set httpd port 2812

2791

\& ssl enable

2792

\& pemfile /etc/certs/monit.pem

2793

.Ve

2794

.PP

2795

And you can use this \s-1URL\s0, \fIhttps://localhost:2812/\fR, to access

2796

the Monit web server over an ssl encrypted connection.

2797

.PP

2798

The pemfile, in the example above, holds both the server's

2799

private key and certificate. This file should be stored in a safe

2800

place on the filesystem and should have strict permissions, that

2801

is, no more than 0700.

2802

.PP

2803

In addition, if you want to check for client certificates you can

2804

use the \s-1CLIENTPEMFILE\s0 statement. In this case, a connecting

2805

client has to provided a certificate known by Monit in order to

2806

connect. This file also needs to have all necessary \s-1CA\s0

2807

certificates. A configuration could look like:

2808

.PP

2809

.Vb 4

2810

\& set httpd port 2812

2811

\& ssl enable

2812

\& pemfile /etc/certs/monit.pem

2813

\& clientpemfile /etc/certs/monit\-client.pem

2814

.Ve

2815

.PP

2816

By default self signed client certificates are not allowed. If

2817

you want to use a self signed certificate from a client it has to

2818

be allowed explicitly with the \s-1ALLOWSELFCERTIFICATION\s0 statement.

2819

.PP

2820

For more information on how to use Monit with \s-1SSL\s0 and for more

2821

information about certificates and generating pem files, please

2822

consult the \s-1README\s0.SSL file accompanying the software.

2823

.PP

2824

If you only want the http server to accept connect requests to

2825

one host addresses you can specify the bind address either as an

2826

\&\s-1IP\s0 number string or as a hostname. In the following example we

2827

bind the http server to the loopback device. In other words the

2828

http server will only be reachable from localhost:

2829

.PP

2830

.Vb 1

2831

\& set httpd port 2812 and use the address 127.0.0.1

2832

.Ve

2833

.PP

2834

or

2835

.PP

2836

.Vb 1

2837

\& set httpd port 2812 and use the address localhost

2838

.Ve

2839

.PP

2840

If you do not use the \s-1ADDRESS\s0 statement the http server will

2841

accept connections on any/all local addresses.

2842

.PP

2843

It is possible to hide monit's httpd server version, which

2844

usually is available in httpd header responses and in error

2845

pages.

2846

.PP

2847

.Vb 3

2848

\& set httpd port 2812

2849

\& ...

2850

\& signature {enable|disable}

2851

.Ve

2852

.PP

2853

Use \fIdisable\fR to hide the server signature \- Monit will only

2854

report its name (e.g. 'monit' instead of for example 'monit

2855

4.2'). By default the version signature is enabled. It is worth

2856

to stress that this option provides no security advantage and

2857

falls into the \*(L"security through obscurity\*(R" category.

2858

.PP

2859

If you remove the httpd statement from the config file, monit

2860

will stop the httpd server on configuration reload. Likewise if

2861

you change the port number, Monit will restart the http server

2862

using the new specified port number.

2863

.PP

2864

The status page displayed by the Monit web server is

2865

automatically refreshed with the same poll time set for the monit

2866

daemon.

2867

.PP

2868

\&\fBNote:\fR

2869

.PP

2870

We strongly recommend that you start Monit with http support (and

2871

bind the server to localhost, only, unless you are behind a

2872

firewall). The built-in web-server is small and does not use much

2873

resources, and more \fIimportantly\fR, Monit can use the http server

2874

for interprocess communication between a Monit client and a monit

2875

daemon.

2876

.PP

2877

For instance, you \fImust\fR start a Monit daemon with http support

2878

if you want to be able to use most of the available console

2879

commands. I.e. 'Monit stop all', 'Monit start all' etc.

2880

.PP

2881

If a Monit daemon is running in the background we will ask the

2882

daemon (via the \s-1HTTP\s0 protocol) to execute the above commands.

2883

That is, the daemon is requested to start and stop the services.

2884

This ensures that a daemon will not restart a service that you

2885

requested to stop and that (any) timeout lock will be removed

2886

from a service when you start it.

2887

.SS "\s-1FIPS\s0 support"

2888

.IX Subsection "FIPS support"

2889

Monit built-in web-server supports the OpenSSL \s-1FIPS\s0 module.

2890

To enable this mode, your OpenSSL library must first be built

2891

with \s-1FIPS\s0 support. Then in the Monit control file, simply

2892

add this \fIset\fR statement at the top;

2893

.PP

2894

.Vb 1

2895

\& set fips

2896

.Ve

2897

.PP

2898

Note that the \s-1FIPS\s0 module may not be supported in the latest

2899

version of OpenSSL. So make sure that your version of OpenSSL

2900

support the \s-1FIPS\s0 object module before attempting to enable this

2901

in Monit.

2902

.SS "Monit \s-1HTTPD\s0 Authentication"

2903

.IX Subsection "Monit HTTPD Authentication"

2904

Monit supports two types of authentication schema's for

2905

connecting to the httpd server, (three, if you count \s-1SSL\s0 client

2906

certificate validation). Both schema's can be used together or by

2907

itself. You \fBmust\fR choose at least one.

2908

.PP

2909

Host and network allow list

2910

.IX Subsection "Host and network allow list"

2911

.PP

2912

The http server maintains an access-control list of hosts and

2913

networks allowed to connect to the server. You can add as many

2914

hosts as you want to, but only hosts with a valid domain name or

2915

its \s-1IP\s0 address are allowed. Networks require a network \s-1IP\s0 and a

2916

netmask to be accepted.

2917

.PP

2918

The http server will query a name server to check any hosts

2919

connecting to the server. If a host (client) is trying to connect

2920

to the server, but cannot be found in the access list or cannot

2921

be resolved, the server will shutdown the connection to the

2922

client promptly.

2923

.PP

2924

Control file example:

2925

.PP

2926

.Vb 6

2927

\& set httpd port 2812

2928

\& allow localhost

2929

\& allow my.other.work.machine.com

2930

\& allow 10.1.1.1

2931

\& allow 192.168.1.0/255.255.255.0

2932

\& allow 10.0.0.0/8

2933

.Ve

2934

.PP

2935

Clients, not mentioned in the allow list, trying to connect to

2936

the server are logged with their ip-address.

2937

.PP

2938

Basic Authentication

2939

.IX Subsection "Basic Authentication"

2940

.PP

2941

This authentication schema is \s-1HTTP\s0 specific and described in more

2942

detail in \s-1RFC\s0 2617.

2943

.PP

2944

In short; a server challenge a client (e.g. a Browser) to send

2945

authentication information (username and password) and if

2946

accepted, the server will allow the client access to the

2947

requested document.

2948

.PP

2949

The biggest weakness with Basic Authentication is that the

2950

username and password is sent in clear-text (i.e. base64 encoded)

2951

over the network. It is therefor recommended that you do not use

2952

this authentication method unless you run the Monit http server

2953

with \fIssl\fR support. With ssl support it is completely safe to

2954

use Basic Authentication since \fBall\fR http data, including Basic

2955

Authentication headers will be encrypted.

2956

.PP

2957

Monit will use Basic Authentication if an allow statement

2958

contains a username and a password separated with a single ':'

2959

character, like so: \fIallow username:password\fR. The username and

2960

password must be written in clear-text. Special characters

2961

can be used but the password has to be quoted.

2962

.PP

2963

\&\s-1PAM\s0 is supported as well on platforms which provide \s-1PAM\s0 (such

2964

as Linux, Mac \s-1OS\s0 X, FreeBSD, NetBSD). The syntax is:

2965

\&\fIallow \f(CI@mygroup\fI\fR which provides access to the user of group

2966

called \fImygroup\fR. Monit uses \s-1PAM\s0 service called \fImonit\fR for

2967

\&\s-1PAM\s0 authentication, see \s-1PAM\s0 manual page for detailed instructions

2968

how to set the \s-1PAM\s0 service and \s-1PAM\s0 authentication plugins.

2969

Example Monit \s-1PAM\s0 for Mac \s-1OS\s0 X \- /etc/pam.d/monit:

2970

.PP

2971

.Vb 5

2972

\& # monit: auth account password session

2973

\& auth sufficient pam_securityserver.so

2974

\& auth sufficient pam_unix.so

2975

\& auth required pam_deny.so

2976

\& account required pam_permit.so

2977

.Ve

2978

.PP

2979

And configuration part for monitrc which allows only group admins

2980

authenticated using via \s-1PAM\s0 to access the http interface:

2981

.PP

2982

.Vb 1

2983

\& set httpd port 2812 allow @admin

2984

.Ve

2985

.PP

2986

Alternatively you can use files in \*(L"htpasswd\*(R" format (one

2987

user:passwd entry per line), like so: \fIallow

2988

[cleartext|crypt|md5] /path [users]\fR. By default cleartext

2989

passwords are read. In case the passwords are digested it is

2990

necessary to specify the cryptographic method. If you do not want

2991

all users in the password file to have access to Monit you can

2992

specify only those users that should have access, in the allow

2993

statement. Otherwise all users are added.

2994

.PP

2995

Example1:

2996

.PP

2997

.Vb 3

2998

\& set httpd port 2812

2999

\& allow hauk:password

3000

\& allow md5 /etc/httpd/htpasswd john paul ringo george

3001

.Ve

3002

.PP

3003

If you use this method together with a host list, then only

3004

clients from the listed hosts will be allowed to connect to the

3005

Monit http server and each client will be asked to provide a

3006

username and a password.

3007

.PP

3008

Example2:

3009

.PP

3010

.Vb 4

3011

\& set httpd port 2812

3012

\& allow localhost

3013

\& allow 10.1.1.1

3014

\& allow hauk:"password"

3015

.Ve

3016

.PP

3017

If you only want to use Basic Authentication, then just provide

3018

allow entries with username and password or password files as in

3019

example 1 above.

3020

.PP

3021

Finally it is possible to define some users as read-only. A

3022

read-only user can read the Monit web pages but will \fInot\fR get

3023

access to push-buttons and cannot change a service from the web

3024

interface.

3025

.PP

3026

.Vb 5

3027

\& set httpd port 2812

3028

\& allow admin:password

3029

\& allow hauk:password read\-only

3030

\& allow @admins

3031

\& allow @users read\-only

3032

.Ve

3033

.PP

3034

A user is set to read-only by using the \fIread-only\fR keyword

3035

\&\fBafter\fR username:password. In the above example the user \fIhauk\fR

3036

is defined as a read-only user, while the \fIadmin\fR user has all

3037

access rights.

3038

.PP

3039

If you use Basic Authentication it is a good idea to set the

3040

access permission for the control file (~/.monitrc) to only

3041

readable and writable for the user running monit, because the

3042

password is written in clear-text. (Use this command, /bin/chmod

3043

600 ~/.monitrc). In fact, since Monit \fBversion 3.0\fR, Monit will

3044

complain and exit if the control file is readable by others.

3045

.PP

3046

Clients trying to connect to the server but supply the wrong

3047

username and/or password are logged with their ip-address.

3048

.PP

3049

If the Monit command line interface is being used, at least one

3050

cleartext password is necessary. Otherwise, the Monit command

3051

line interface will not be able to connect to the Monit daemon

3052

server.

3053

.SH "DEPENDENCIES"

3054

.IX Header "DEPENDENCIES"

3055

If specified in the control file, Monit can do dependency

3056

checking before start, stop, monitoring or unmonitoring of

3057

services. The dependency statement may be used within any service

3058

entries in the Monit control file.

3059

.PP

3060

The syntax for the depend statement is simply:

3061

.IP "\s-1DEPENDS\s0 on service[, service [,...]]" 4

3062

.IX Item "DEPENDS on service[, service [,...]]"

3063

.PP

3064

Where \fBservice\fR is a service entry name, for instance \fBapache\fR

3065

or \fBdatafs\fR.

3066

.PP

3067

You may add more than one service name of any type or use more

3068

than one depend statement in an entry.

3069

.PP

3070

Services specified in a \fIdepend\fR statement will be checked

3071

during stop/start/monitor/unmonitor operations. If a service is

3072

stopped or unmonitored it will stop/unmonitor any services that

3073

depends on itself. Likewise, if a service is started, it will

3074

first stop any services that depends on itself and after it is

3075

started, start all depending services again. If the service is to

3076

be monitored (enable monitoring), all services which this service

3077

depends on will be monitored before enabling monitoring of this

3078

service.

3079

.PP

3080

Here is an example where we set up an apache service entry to

3081

depend on the underlying apache binary. If the binary should

3082

change an alert is sent and apache is not monitored anymore. The

3083

rationale is security and that Monit should not execute a

3084

possibly cracked apache binary.

3085

.PP

3086

.Vb 7

3087

\& (1) check process apache

3088

\& (2) with pidfile "/usr/local/apache/logs/httpd.pid"

3089

\& (3) ...

3090

\& (4) depends on httpd

3091

\& (5)

3092

\& (6) check file httpd with path /usr/local/apache/bin/httpd

3093

\& (7) if failed checksum then unmonitor

3094

.Ve

3095

.PP

3096

The first entry is the process entry for apache shown before

3097

(abbreviated for clarity). The fourth line sets up a dependency

3098

between this entry and the service entry named httpd in line 6. A

3099

depend tree works as follows, if an action is conducted in a

3100

lower branch it will propagate upward in the tree and for every

3101

dependent entry execute the same action. In this case, if the

3102

checksum should fail in line 7 then an unmonitor action is

3103

executed and the apache binary is not checked anymore. But since

3104

the apache process entry depends on the httpd entry this entry

3105

will also execute the unmonitor action. In short, if the checksum

3106

test for the httpd binary file should fail, both the check file

3107

httpd entry and the check process apache entry is set in

3108

un-monitoring mode.

3109

.PP

3110

A dependency tree is a general construct and can be used between

3111

all types of service entries and span many levels and propagate

3112

any supported action (except the exec action which will not

3113

propagate upward in a dependency tree for obvious reasons).

3114

.PP

3115

Here is another different example. Consider the following common

3116

server setup:

3117

.PP

3118

.Vb 2

3119

\& WEB\-SERVER \-> APPLICATION\-SERVER \-> DATABASE \-> FILESYSTEM

3120

\& (a) (b) (c) (d)

3121

.Ve

3122

.PP

3123

You can set dependencies so that the web-server depends on the

3124

application server to run before the web-server starts and the

3125

application server depends on the database server and the

3126

database depends on the file-system to be mounted before it

3127

starts. See also the example section below for examples using the

3128

depend statement.

3129

.PP

3130

Here we describe how Monit will function with the above

3131

dependencies:

3132

.IP "If no servers are running" 4

3133

.IX Item "If no servers are running"

3134

Monit will start the servers in the following order: \fId\fR, \fIc\fR,

3135

\&\fIb\fR, \fIa\fR

3136

.IP "If all servers are running" 4

3137

.IX Item "If all servers are running"

3138

When you run 'Monit stop all' this is the stop order: \fIa\fR, \fIb\fR,

3139

\&\fIc\fR, \fId\fR. If you run 'Monit stop d' then \fIa\fR, \fIb\fR and \fIc\fR

3140

are also stopped because they depend on \fId\fR and finally \fId\fR is

3141

stopped.

3142

.IP "If \fIa\fR does not run" 4

3143

.IX Item "If a does not run"

3144

When Monit runs it will start \fIa\fR

3145

.IP "If \fIb\fR does not run" 4

3146

.IX Item "If b does not run"

3147

When Monit runs it will first stop \fIa\fR then start \fIb\fR and

3148

finally start \fIa\fR again.

3149

.IP "If \fIc\fR does not run" 4

3150

.IX Item "If c does not run"

3151

When Monit runs it will first stop \fIa\fR and \fIb\fR then start \fIc\fR

3152

and finally start \fIb\fR then \fIa\fR.

3153

.IP "If \fId\fR does not run" 4

3154

.IX Item "If d does not run"

3155

When Monit runs it will first stop \fIa\fR, \fIb\fR and \fIc\fR then start

3156

\&\fId\fR and finally start \fIc\fR, \fIb\fR then \fIa\fR.

3157

.IP "If the control file contains a depend loop." 4

3158

.IX Item "If the control file contains a depend loop."

3159

A depend loop is for example; a\->b and b\->a or a\->b\->c\->a.

3160

.Sp

3161

When Monit starts it will check for such loops and complain and

3162

exit if a loop was found. It will also exit with a complaint if a

3163

depend statement was used that does not point to a service in the

3164

control file.

3165

.SH "THE RUN CONTROL FILE"

3166

.IX Header "THE RUN CONTROL FILE"

3167

The preferred way to set up Monit is to write a \fI.monitrc\fR file

3168

in your home directory. When there is a conflict between the

3169

command-line arguments and the arguments in this file, the

3170

command-line arguments take precedence. To protect the security

3171

of your control file and passwords the control file must have

3172

permissions \fIno more than 0700\fR (u=xrw,g=,o=); Monit will

3173

complain and exit otherwise.

3174

.SS "Run Control Syntax"

3175

.IX Subsection "Run Control Syntax"

3176

Comments begin with a '#' and extend through the end of the line.

3177

Otherwise the file consists of a series of service entries or

3178

global option statements in a free-format, token-oriented syntax.

3179

.PP

3180

There are three kinds of tokens: grammar , numbers (i.e.

3181

decimal digit sequences) and strings. Strings can be either

3182

quoted or unquoted. A quoted string is bounded by double quotes

3183

and may contain whitespace (and quoted digits are treated as a

3184

string). An unquoted string is any whitespace-delimited token,

3185

containing characters and/or numbers.

3186

.PP

3187

On a semantic level, the control file consists of two types of

3188

entries:

3189

.IP "1. Global set-statements" 4

3190

.IX Item "1. Global set-statements"

3191

A global set-statement starts with the keyword \fIset\fR and the

3192

item to configure.

3193

.IP "2. One or more service entry statements." 4

3194

.IX Item "2. One or more service entry statements."

3195

Each service entry consists of the keywords `check', followed by

3196

the service type. Each entry requires a <unique> descriptive

3197

name, which may be freely chosen. This name is used by monit

3198

to refer to the service internally and in all interactions

3199

with the user.

3200

.PP

3201

Currently, eight types of check statements are supported:

3202

.IP "1. \s-1CHECK\s0 \s-1PROCESS\s0 <unique name> <\s-1PIDFILE\s0 <path> | \s-1MATCHING\s0 <regex>>" 4

3203

.IX Item "1. CHECK PROCESS <unique name> <PIDFILE <path> | MATCHING <regex>>"

3204

<path> is the absolute path to the program's pidfile. If the

3205

pidfile does not exist or does not contain the pid number of a

3206

running process, Monit will call the entry's start method if

3207

defined.

3208

<regex> is alternative process specification using pattern matching

3209

to process name (command line) from process table instead of pidfile.

3210

The first match is used so this form of check is useful for unique

3211

pattern matching \- the pidfile should be used where possible as it

3212

defines expected pid exactly (pattern matching won't be useful for

3213

Apache in most cases for example).

3214

The pattern can be obtained using \fImonit procmatch \*(L".*\*(R"\fR \s-1CLI\s0 command

3215

which lists all processes visible to Monit or using the \fIps\fR utility.

3216

The \*(L"procmatch\*(R" \s-1CLI\s0 command can be used to test your pattern as well.

3217

If Monit runs in passive mode or the start methods is not defined,

3218

Monit will just send alerts on errors.

3219

.IP "2. \s-1CHECK\s0 \s-1FILE\s0 <unique name> \s-1PATH\s0 <path>" 4

3220

.IX Item "2. CHECK FILE <unique name> PATH <path>"

3221

<path> is the absolute path to the file. If the file does not

3222

exist or disappeared, Monit will call the entry's start method if

3223

defined, if <path> does not point to a regular file type (for

3224

instance a directory), Monit will disable monitoring of this

3225

entry. If Monit runs in passive mode or the start methods is not

3226

defined, Monit will just send alerts on errors.

3227

.IP "3. \s-1CHECK\s0 \s-1FIFO\s0 <unique name> \s-1PATH\s0 <path>" 4

3228

.IX Item "3. CHECK FIFO <unique name> PATH <path>"

3229

<path> is the absolute path to the fifo. If the fifo does not

3230

exist or disappeared, Monit will call the entry's start method if

3231

defined, if <path> does not point to a fifo type (for

3232

instance a directory), Monit will disable monitoring of this

3233

entry. If Monit runs in passive mode or the start methods is not

3234

defined, Monit will just send alerts on errors.

3235

.IP "4. \s-1CHECK\s0 \s-1FILESYSTEM\s0 <unique name> \s-1PATH\s0 <path>" 4

3236

.IX Item "4. CHECK FILESYSTEM <unique name> PATH <path>"

3237

<path> is the path to the filesystem block special device, mount point,

3238

file or a directory which is part of a filesystem. It is

3239

recommended to use a block special file directly (for example

3240

/dev/hda1 on Linux or /dev/dsk/c0t0d0s1 on Solaris, etc.) If you

3241

use a mount point (for example /data), be careful, because if the

3242

filesystem is unmounted the test will still be true because the mount

3243

point exist.

3244

.Sp

3245

If the filesystem becomes unavailable, Monit will call the entry's

3246

start method if defined. if <path> does not point to a filesystem,

3247

Monit will disable monitoring of this entry. If Monit runs in

3248

passive mode or the start methods is not defined, Monit will just

3249

send alerts on errors.

3250

.IP "5. \s-1CHECK\s0 \s-1DIRECTORY\s0 <unique name> \s-1PATH\s0 <path>" 4

3251

.IX Item "5. CHECK DIRECTORY <unique name> PATH <path>"

3252

<path> is the absolute path to the directory. If the directory

3253

does not exist or disappeared, Monit will call the entry's start

3254

method if defined, if <path> does not point to a directory, monit

3255

will disable monitoring of this entry. If Monit runs in passive

3256

mode or the start methods is not defined, Monit will just send

3257

alerts on errors.

3258

.IP "6. \s-1CHECK\s0 \s-1HOST\s0 <unique name> \s-1ADDRESS\s0 <host address>" 4

3259

.IX Item "6. CHECK HOST <unique name> ADDRESS <host address>"

3260

The host address can be specified as a hostname string or as an

3261

ip-address string on a dotted decimal format. Such as,

3262

tildeslash.com or \*(L"64.87.72.95\*(R".

3263

.IP "7. \s-1CHECK\s0 \s-1SYSTEM\s0 <unique name>" 4

3264

.IX Item "7. CHECK SYSTEM <unique name>"

3265

The system name is usually hostname, but any descriptive name can be

3266

used. This test allows one to check general system resources such as

3267

\&\s-1CPU\s0 usage (percent of time spent in user, system and wait), total

3268

memory usage or load average. The unique name is used as the system

3269

hostname in mail alerts and when M/Monit is configured, then also

3270

as initial name of the host entry in M/Monit.

3271

.IP "8. \s-1CHECK\s0 \s-1PROGRAM\s0 <unique name> \s-1PATH\s0 <executable file> [\s-1TIMEOUT\s0 <number> \s-1SECONDS\s0]" 4

3272

.IX Item "8. CHECK PROGRAM <unique name> PATH <executable file> [TIMEOUT <number> SECONDS]"

3273

<path> is the absolute path to the executable program or script.

3274

The \fIstatus\fR test allows to check the program's exit status. If

3275

program will not finish within <number> seconds, Monit will terminate

3276

it. The default program timeout is 600 seconds (5 minutes).

3277

.PP

3278

You can use noise keywords like 'if', `and', `with(in)', `has',

3279

`using', 'use', 'on(ly)', `usage' and `program(s)' anywhere in an

3280

entry to make it resemble English. They're ignored, but can make

3281

entries much easier to read at a glance. The punctuation

3282

characters ';' ',' and '=' are also ignored. Keywords are case

3283

insensitive.

3284

.PP

3285

.Vb 1

3286

\& Here are the legal global keywords:

3287

\&

3288

\& Keyword Function

3289

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

3290

\& set daemon Set a background poll interval in seconds.

3291

\& set init Set Monit to run from init. Monit will not

3292

\& transform itself into a daemon process.

3293

\& set logfile Name of a file to dump error\- and status\-

3294

\& messages to. If syslog is specified as the

3295

\& file, Monit will utilize the syslog daemon

3296

\& to log messages. This can optionally be

3297

\& followed by \*(Aqfacility <facility>\*(Aq where

3298

\& facility is \*(Aqlog_local0\*(Aq \- \*(Aqlog_local7\*(Aq or

3299

\& \*(Aqlog_daemon\*(Aq. If no facility is specified,

3300

\& LOG_USER is used.

3301

\& set mailserver The mailserver used for sending alert

3302

\& notifications. If the mailserver is not

3303

\& defined, Monit will try to use \*(Aqlocalhost\*(Aq

3304

\& as the smtp\-server for sending mail. You

3305

\& can add more mail servers, if Monit cannot

3306

\& connect to the first server it will try the

3307

\& next server and so on.

3308

\& set mail\-format Set a global mail format for all alert

3309

\& messages emitted by monit.

3310

\& set idfile Explicit set the location of the Monit id

3311

\& file. E.g. set idfile /var/monit/id.

3312

\& set pidfile Explicit set the location of the Monit lock

3313

\& file. E.g. set pidfile /var/run/xyzmonit.pid.

3314

\& set statefile Explicit set the location of the file Monit

3315

\& will write state data to. If not set, the

3316

\& default is $HOME/.monit.state.

3317

\& set httpd port Activates Monit http server at the given

3318

\& port number.

3319

\& ssl enable Enables ssl support for the httpd server.

3320

\& Requires the use of the pemfile statement.

3321

\& ssl disable Disables ssl support for the httpd server.

3322

\& It is equal to omitting any ssl statement.

3323

\& pemfile Set the pemfile to be used with ssl.

3324

\& clientpemfile Set the pemfile to be used when client

3325

\& certificates should be checked by monit.

3326

\& address If specified, the http server will only

3327

\& accept connect requests to this addresses

3328

\& This statement is an optional part of the

3329

\& set httpd statement.

3330

\& allow Specifies a host or IP address allowed to

3331

\& connect to the http server. Can also specify

3332

\& a username and password allowed to connect

3333

\& to the server. More than one allow statement

3334

\& are allowed. This statement is also an

3335

\& optional part of the set httpd statement.

3336

\& read\-only Set the user defined in username:password

3337

\& to read only. A read\-only user cannot change

3338

\& a service from the Monit web interface.

3339

\& include include a file or files matching the globstring

3340

\&

3341

\& Here are the legal service entry keywords:

3342

\&

3343

\& Keyword Function

3344

\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

3345

\& check Starts an entry and must be followed by the type

3346

\& of monitored service {filesystem|directory|file|host

3347

\& process|system|program} and a descriptive name for

3348

\& the service.

3349

\& pidfile Specify the process pidfile. Every

3350

\& process must create a pidfile with its

3351

\& current process id. This statement should only

3352

\& be used in a process service entry.

3353

\& path Must be followed by a path to the block

3354

\& special file for filesystem, regular

3355

\& file, directory or a process\*(Aqs pidfile.

3356

\& group Specify a groupname for a service entry.

3357

\& start The program used to start the specified

3358

\& service. Full path is required. This

3359

\& statement is optional, but recommended.

3360

\& stop The program used to stop the specified

3361

\& service. Full path is required. This

3362

\& statement is optional, but recommended.

3363

\& pid and ppid These keywords may be used as standalone

3364

\& statements in a process service entry to

3365

\& override the alert action for change of

3366

\& process pid and ppid.

3367

\& uid and gid These keywords are either 1) an optional part of

3368

\& a start, stop or exec statement. They may be

3369

\& used to specify a user id and a group id the

3370

\& program (process) should switch to upon start.

3371

\& This feature can only be used if the superuser

3372

\& is running monit. 2) uid and gid may also be

3373

\& used as standalone statements in a file service

3374

\& entry to test a file\*(Aqs uid and gid attributes.

3375

\& host The hostname or IP address to test the port

3376

\& at. This keyword can only be used together

3377

\& with a port statement or in the check host

3378

\& statement.

3379

\& port Specify a TCP/IP service port number which

3380

\& a process is listening on. This statement

3381

\& is also optional. If this statement is not

3382

\& prefixed with a host\-statement, localhost is

3383

\& used as the hostname to test the port at.

3384

\& type Specifies the socket type Monit should use when

3385

\& testing a connection to a port. If the type

3386

\& keyword is omitted, tcp is used. This keyword

3387

\& must be followed by either tcp, udp or tcpssl.

3388

\& tcp Specifies that Monit should use a TCP

3389

\& socket type (stream) when testing a port.

3390

\& tcpssl Specifies that Monit should use a TCP socket

3391

\& type (stream) and the secure socket layer (ssl)

3392

\& when testing a port connection.

3393

\& udp Specifies that Monit should use a UDP socket

3394

\& type (datagram) when testing a port.

3395

\& certmd5 The md5 sum of a certificate a ssl forged

3396

\& server has to deliver.

3397

\& proto(col) This keyword specifies the type of service

3398

\& found at the port. See CONNECTION TESTING

3399

\& for list of supported protocols.

3400

\& You\*(Aqre welcome to write new protocol test

3401

\& modules. If no protocol is specified Monit will

3402

\& use a default test which in most cases are good

3403

\& enough.

3404

\& request Specifies a server request and must come

3405

\& after the protocol keyword mentioned above.

3406

\& \- for http it can contain an URL and an

3407

\& optional query string.

3408

\& \- other protocols does not support this

3409

\& statement yet

3410

\& send/expect These keywords specify a generic protocol.

3411

\& Both require a string whether to be sent or

3412

\& to be matched against (as extended regex if

3413

\& supported). Send/expect can not be used

3414

\& together with the proto(col) statement.

3415

\& unix(socket) Specifies a Unix socket file and used like

3416

\& the port statement above to test a Unix

3417

\& domain network socket connection.

3418

\& URL Specify an URL string which Monit will use for

3419

\& connection testing.

3420

\& content Optional sub\-statement for the URL statement.

3421

\& Specifies that Monit should test the content

3422

\& returned by the server against a regular

3423

\& expression.

3424

\& timeout x sec. Define a network port connection timeout. Must

3425

\& be followed by a number in seconds and the

3426

\& keyword, seconds.

3427

\& timeout Define a service timeout. Must be followed by

3428

\& two digits. The first digit is max number of

3429

\& restarts for the service. The second digit

3430

\& is the cycle interval to test restarts.

3431

\& This statement is optional.

3432

\& alert Specifies an email address for notification

3433

\& if a service event occurs. Alert can also

3434

\& be postfixed, to only send a message for

3435

\& certain events. See the examples above. More

3436

\& than one alert statement is allowed in an

3437

\& entry. This statement is also optional.

3438

\& noalert Specifies an email address which don\*(Aqt want

3439

\& to receive alerts. This statement is also

3440

\& optional.

3441

\& restart, stop These keywords may be used as actions for

3442

\& unmonitor, various test statements. The exec statement is

3443

\& start and special in that it requires a following string

3444

\& exec specifying the program to be execute. You may

3445

\& also specify an UID and GID for the exec

3446

\& statement. The program executed will then run

3447

\& using the specified user id and group id.

3448

\& mail\-format Specifies a mail format for an alert message

3449

\& This statement is an optional part of the

3450

\& alert statement.

3451

\& checksum Specify that Monit should compute and monitor a

3452

\& file\*(Aqs md5/sha1 checksum. May only be used in a

3453

\& check file entry.

3454

\& expect Specifies a md5/sha1 checksum string Monit

3455

\& should expect when testing the checksum. This

3456

\& statement is an optional part of the checksum

3457

\& statement.

3458

\& timestamp Specifies an expected timestamp for a file

3459

\& or directory. More than one timestamp statement

3460

\& are allowed. May only be used in a check file or

3461

\& check directory entry.

3462

\& changed Part of a timestamp statement and used as an

3463

\& operator to simply test for a timestamp change.

3464

\& every Validate this entry only at every n poll cycle

3465

\& or per cron specification. Useful in daemon mode

3466

\& when the cycle is short and a service takes some

3467

\& time to start or to suppress monitoring during

3468

\& backup windows.

3469

\& mode Must be followed either by the keyword active,

3470

\& passive or manual. If active, Monit will restart

3471

\& the service if it is not running (this is the

3472

\& default behavior). If passive, Monit will not

3473

\& (re)start the service if it is not running \- it

3474

\& will only monitor and send alerts (resource

3475

\& related restart and stop options are ignored

3476

\& in this mode also). If manual, Monit will enter

3477

\& active mode only if a service was started under

3478

\& monit\*(Aqs control otherwise the service isn\*(Aqt

3479

\& monitored.

3480

\& cpu Must be followed by a compare operator, a number

3481

\& with "%" and an action. This statement is used

3482

\& to check the cpu usage in percent of a process

3483

\& with its children over a number of cycles. If

3484

\& the compare expression matches then the

3485

\& specified action is executed.

3486

\& mem The equivalent to the cpu token for memory of a

3487

\& process (w/o children!). This token must be

3488

\& followed by a compare operator a number with

3489

\& unit {B|KB|MB|GB|%|byte|kilobyte|megabyte|

3490

\& gigabyte|percent} and an action.

3491

\& swap Token for system swap usage monitoring. This token

3492

\& must be followed by a compare operator a number with

3493

\& unit {B|KB|MB|GB|%|byte|kilobyte|megabyte|gigabyte|percent}

3494

\& and an action.

3495

\& loadavg Must be followed by [1min,5min,15min] in (), a

3496

\& compare operator, a number and an action. This

3497

\& statement is used to check the system load

3498

\& average over a number of cycles. If the compare

3499

\& expression matches then the specified action is

3500

\& executed.

3501

\& children This is the number of child processes spawn by a

3502

\& process. The syntax is the same as above.

3503

\& totalmem The equivalent of mem, except totalmem is an

3504

\& aggregation of memory, not only used by a

3505

\& process but also by all its child

3506

\& processes. The syntax is the same as above.

3507

\& space Must be followed by a compare operator, a

3508

\& number, unit {B|KB|MB|GB|%|byte|kilobyte|

3509

\& megabyte|gigabyte|percent} and an action.

3510

\& inode(s) Must be followed by a compare operator, integer

3511

\& number, optionally by percent sign (if not, the

3512

\& limit is absolute) and an action.

3513

\& perm(ission) Must be followed by an octal number describing

3514

\& the permissions.

3515

\& size Must be followed by a compare operator, a

3516

\& number, unit {B|KB|MB|GB|byte|kilobyte|

3517

\& megabyte|gigabyte} and an action.

3518

\& uptime Must be followed by a compare operator, a

3519

\& number, unit {second(s)|minute(s)|hour(s)|day(s)}

3520

\& and an action.

3521

\& depends (on) Must be followed by the name of a service this

3522

\& service depends on.

3523

.Ve

3524

.PP

3525

Here's the complete list of reserved \fBkeywords\fR used by monit:

3526

.PP

3527

\&\fIif\fR, \fIthen\fR, \fIelse\fR, \fIset\fR, \fIdaemon\fR, \fIlogfile\fR,

3528

\&\fIsyslog\fR, \fIaddress\fR, \fIhttpd\fR, \fIssl\fR, \fIenable\fR, \fIdisable\fR,

3529

\&\fIpemfile\fR, \fIallow\fR, \fIread-only\fR, \fIcheck\fR, \fIinit\fR, \fIcount\fR,

3530

\&\fIpidfile\fR, \fIstatefile\fR, \fIgroup\fR, \fIstart\fR, \fIstop\fR, \fIuid\fR,

3531

\&\fIgid\fR, \fIconnection\fR, \fIport(number)\fR, \fIunix(socket)\fR, \fItype\fR,

3532

\&\fIproto(col)\fR, \fItcp\fR, \fItcpssl\fR, \fIudp\fR, \fIalert\fR, \fInoalert\fR,

3533

\&\fImail-format\fR, \fIrestart\fR, \fItimeout\fR, \fIchecksum\fR, \fIresource\fR,

3534

\&\fIexpect\fR, \fIsend\fR, \fImailserver\fR, \fIevery\fR, \fImode\fR, \fIactive\fR,

3535

\&\fIpassive\fR, \fImanual\fR, \fIdepends\fR, \fIhost\fR, \fIdefault\fR, \fIhttp\fR,

3536

\&\fIftp\fR, \fIsmtp\fR, \fIpop\fR, \fIntp3\fR, \fInntp\fR, \fIimap\fR, \fIclamav\fR,

3537

\&\fIssh\fR, \fIdwp\fR, \fIldap2\fR, \fIldap3\fR, \fItns\fR, \fIrequest\fR, \fIcpu\fR,

3538

\&\fImem\fR, \fItotalmem\fR, \fIswap\fR, \fIchildren\fR, \fIloadavg\fR, \fItimestamp\fR,

3539

\&\fIchanged\fR, \fIsecond(s)\fR, \fIminute(s)\fR, \fIhour(s)\fR, \fIday(s)\fR,

3540

\&\fIspace\fR, \fIinode\fR, \fIpid\fR, \fIppid\fR, \fIperm(ission)\fR, \fIicmp\fR,

3541

\&\fIprocess\fR, \fIfile\fR, \fIdirectory\fR, \fIfilesystem\fR, \fIsize\fR, \fIaction\fR,

3542

\&\fIunmonitor\fR, \fIrdate\fR, \fIrsync\fR, \fIdata\fR, \fIinvalid\fR, \fIexec\fR,

3543

\&\fInonexist\fR, \fIpolicy\fR, \fIreminder\fR, \fIinstance\fR, \fIeventqueue\fR,

3544

\&\fIbasedir\fR, \fIslot(s)\fR, \fIsystem\fR, \fIidfile\fR, \fIgps\fR, \fIradius\fR,

3545

\&\fIsecret\fR, \fItarget\fR, \fImaxforward\fR, \fIhostheader\fR, \fIregister\fR,

3546

\&\fIcredentials\fR, \fIfips\fR, \fIstatus\fR, \fIuptime\fR and \fIfailed\fR

3547

.PP

3548

And here is a complete list of \fBnoise keywords\fR ignored by

3549

monit:

3550

.PP

3551

\&\fIis\fR, \fIas\fR, \fIare\fR, \fIon(ly)\fR, \fIwith(in|out)\fR, \fIand\fR, \fIhas\fR,

3552

\&\fIusing\fR, \fIuse\fR, \fIthe\fR, \fIsum\fR, \fIprogram(s)\fR, \fIthan\fR, \fIfor\fR,

3553

\&\fIusage\fR, \fIwas\fR, \fIbut\fR, \fIof\fR.

3554

.PP

3555

\&\fBNote:\fR If the \fIstart\fR or \fIstop\fR programs are shell scripts,

3556

then the script must begin with \f(CW\*(C`#!\*(C'\fR and the remainder of the

3557

first line must specify an interpreter for the program. E.g.

3558

\&\f(CW\*(C`#!/bin/sh\*(C'\fR

3559

.PP

3560

It's possible to write scripts directly into the \fIstart\fR and

3561

\&\fIstop\fR entries by using a string of shell-commands. Like so:

3562

.PP

3563

.Vb 2

3564

\& start="/bin/bash \-c \*(Aqecho $$ > pidfile; exec program\*(Aq"

3565

\& stop="/bin/bash \-c \*(Aqkill \-s SIGTERM \`cat pidfile\`\*(Aq"

3566

.Ve

3567

.SS "\s-1CONFIGURATION\s0 \s-1EXAMPLES\s0"

3568

.IX Subsection "CONFIGURATION EXAMPLES"

3569

The simplest form is just the check statement. In this example we

3570

check to see if the server is running and log a message if not:

3571

.PP

3572

.Vb 1

3573

\& check process resin with pidfile /usr/local/resin/srun.pid

3574

.Ve

3575

.PP

3576

Checking process without pidfile:

3577

.PP

3578

.Vb 1

3579

\& check process pager matching "/sbin/dynamic_pager \-F /private/var/vm/swapfile"

3580

.Ve

3581

.PP

3582

To have Monit start the server if it's not running, add a start

3583

statement:

3584

.PP

3585

.Vb 3

3586

\& check process resin with pidfile /usr/local/resin/srun.pid

3587

\& start program = "/usr/local/resin/bin/srun.sh start"

3588

\& stop program = "/usr/local/resin/bin/srun.sh stop"

3589

.Ve

3590

.PP

3591

Here's a more advanced example for monitoring an apache

3592

web-server listening on the default port number for \s-1HTTP\s0 and

3593

\&\s-1HTTPS\s0. In this example Monit will restart apache if it's not

3594

accepting connections at the port numbers. The method Monit use

3595

for a process restart is to first execute the stop-program, wait

3596

up to 30s for the process to stop and then execute the start-program

3597

and wait up to 30s for it to start. The length of start or stop

3598

timeout can be overridden using the 'timeout' option. If Monit was

3599

unable to stop or start the service a failed alert message will

3600

be sent if you have requested alert messages to be sent.

3601

.PP

3602

.Vb 5

3603

\& check process apache with pidfile /var/run/httpd.pid

3604

\& start program = "/etc/init.d/httpd start" with timeout 60 seconds

3605

\& stop program = "/etc/init.d/httpd stop"

3606

\& if failed port 80 then restart

3607

\& if failed port 443 with timeout 15 seconds then restart

3608

.Ve

3609

.PP

3610

This example demonstrate how you can run a program as a specified

3611

user (uid) and with a specified group (gid). Many daemon programs

3612

will do the uid and gid switch by them self, but for those

3613

programs that does not (e.g. Java programs), monit's ability to

3614

start a program as a certain user can be very useful. In this

3615

example we start the Tomcat Java Servlet Engine as the standard

3616

\&\fInobody\fR user and group. Please note that Monit will only switch

3617

uid and gid for a program if the super-user is running monit,

3618

otherwise Monit will simply ignore the request to change uid and

3619

gid.

3620

.PP

3621

.Vb 7

3622

\& check process tomcat with pidfile /var/run/tomcat.pid

3623

\& start program = "/etc/init.d/tomcat start"

3624

\& as uid nobody and gid nobody

3625

\& stop program = "/etc/init.d/tomcat stop"

3626

\& # You can also use id numbers instead and write:

3627

\& as uid 99 and with gid 99

3628

\& if failed port 8080 then alert

3629

.Ve

3630

.PP

3631

In this example we use udp for connection testing to check if the

3632

name-server is running and also use timeout and alert:

3633

.PP

3634

.Vb 5

3635

\& check process named with pidfile /var/run/named.pid

3636

\& start program = "/etc/init.d/named start"

3637

\& stop program = "/etc/init.d/named stop"

3638

\& if failed port 53 use type udp protocol dns then restart

3639

\& if 3 restarts within 5 cycles then timeout

3640

.Ve

3641

.PP

3642

The following example illustrates how to check if the service

3643

\&'sophie' is answering connections on its Unix domain socket:

3644

.PP

3645

.Vb 4

3646

\& check process sophie with pidfile /var/run/sophie.pid

3647

\& start program = "/etc/init.d/sophie start"

3648

\& stop program = "/etc/init.d/sophie stop"

3649

\& if failed unix /var/run/sophie then restart

3650

.Ve

3651

.PP

3652

In this example we check an apache web-server running on

3653

localhost that answers for several IP-based virtual hosts or

3654

vhosts, hence the host statement before port:

3655

.PP

3656

.Vb 7

3657

\& check process apache with pidfile /var/run/httpd.pid

3658

\& start "/etc/init.d/httpd start"

3659

\& stop "/etc/init.d/httpd stop"

3660

\& if failed host www.sol.no port 80 then alert

3661

\& if failed host shop.sol.no port 443 then alert

3662

\& if failed host chat.sol.no port 80 then alert

3663

\& if failed host www.tildeslash.com port 80 then alert

3664

.Ve

3665

.PP

3666

To make sure that Monit is communicating with a http server a

3667

protocol test can be added:

3668

.PP

3669

.Vb 6

3670

\& check process apache with pidfile /var/run/httpd.pid

3671

\& start "/etc/init.d/httpd start"

3672

\& stop "/etc/init.d/httpd stop"

3673

\& if failed host www.sol.no port 80

3674

\& protocol HTTP

3675

\& then alert

3676

.Ve

3677

.PP

3678

This example shows a different way to check a webserver using

3679

the send/expect mechanism:

3680

.PP

3681

.Vb 7

3682

\& check process apache with pidfile /var/run/httpd.pid

3683

\& start "/etc/init.d/httpd start"

3684

\& stop "/etc/init.d/httpd stop"

3685

\& if failed host www.sol.no port 80

3686

\& send "GET / HTTP/1.0\er\enHost: www.sol.no\er\en\er\en"

3687

\& expect "HTTP/[0\-9\e.]{3} 200 .*\er\en"

3688

\& then alert

3689

.Ve

3690

.PP

3691

To make sure that Apache is logging successfully (i.e. no more

3692

than 60 percent of child servers are logging), use its mod_status

3693

page at www.sol.no/server\-status with this special protocol test:

3694

.PP

3695

.Vb 5

3696

\& check process apache with pidfile /var/run/httpd.pid

3697

\& start "/etc/init.d/httpd start"

3698

\& stop "/etc/init.d/httpd stop"

3699

\& if failed host www.sol.no port 80

3700

\& protocol apache\-status loglimit > 60% then restart

3701

.Ve

3702

.PP

3703

This configuration can be used to alert you if 25 percent or more

3704

of Apache child processes are stuck performing \s-1DNS\s0 lookups:

3705

.PP

3706

.Vb 5

3707

\& check process apache with pidfile /var/run/httpd.pid

3708

\& start "/etc/init.d/httpd start"

3709

\& stop "/etc/init.d/httpd stop"

3710

\& if failed host www.sol.no port 80

3711

\& protocol apache\-status dnslimit > 25% then alert

3712

.Ve

3713

.PP

3714

Here we use an icmp ping test to check if a remote host is up and

3715

if not send an alert:

3716

.PP

3717

.Vb 3

3718

\& check host www.tildeslash.com with address www.tildeslash.com

3719

\& if failed icmp type echo count 5 with timeout 15 seconds

3720

\& then alert

3721

.Ve

3722

.PP

3723

In the following example we ask Monit to compute and verify the

3724

checksum for the underlying apache binary used by the start and

3725

stop programs. If the the checksum test should fail, monitoring

3726

will be disabled to prevent possibly starting a compromised

3727

binary:

3728

.PP

3729

.Vb 5

3730

\& check process apache with pidfile /var/run/httpd.pid

3731

\& start program = "/etc/init.d/httpd start"

3732

\& stop program = "/etc/init.d/httpd stop"

3733

\& if failed host www.tildeslash.com port 80 then restart

3734

\& depends on apache_bin

3735

\&

3736

\& check file apache_bin with path /usr/local/apache/bin/httpd

3737

\& if failed checksum then unmonitor

3738

.Ve

3739

.PP

3740

In this example we ask Monit to test the checksum for a document

3741

on a remote server. If the checksum was changed we send an alert:

3742

.PP

3743

.Vb 5

3744

\& check host tildeslash with address www.tildeslash.com

3745

\& if failed port 80 protocol http

3746

\& and request "/monit/dist/monit\-4.0.tar.gz"

3747

\& with checksum f9d26b8393736b5dfad837bb13780786

3748

\& then alert

3749

.Ve

3750

.PP

3751

Here are a couple of tests for some popular communication

3752

servers, using the \s-1SIP\s0 protocol. First we test a FreeSWITCH

3753

server and then an Asterisk server

3754

.PP

3755

.Vb 12

3756

\& check process freeswitch

3757

\& with pidfile /usr/local/freeswitch/log/freeswitch.pid

3758

\& start program = a\*^XX/usr/local/freeswitch/bin/freeswitch \-nc \-hpa\*^XX

3759

\& stop program = a\*^XX/usr/local/freeswitch/bin/freeswitch \-stopa\*^XX

3760

\& if totalmem > 1000.0 MB for 5 cycles then alert

3761

\& if totalmem > 1500.0 MB for 5 cycles then alert

3762

\& if totalmem > 2000.0 MB for 5 cycles then restart

3763

\& if cpu > 60% for 5 cycles then alert

3764

\& if failed port 5060 type udp protocol SIP

3765

\& target me@foo.bar and maxforward 10

3766

\& then restart

3767

\& if 5 restarts within 5 cycles then timeout

3768

\&

3769

\& check process asterisk

3770

\& with pidfile /var/run/asterisk/asterisk.pid

3771

\& start program = a\*^XX/usr/sbin/asteriska\*^XX

3772

\& stop program = a\*^XX/usr/sbin/asterisk \-r \-x a\*^XXshutdown nowa\*^XXa\*^XX

3773

\& if totalmem > 1000.0 MB for 5 cycles then alert

3774

\& if totalmem > 1500.0 MB for 5 cycles then alert

3775

\& if totalmem > 2000.0 MB for 5 cycles then restart

3776

\& if cpu > 60% for 5 cycles then alert

3777

\& if failed port 5060 type udp protocol SIP

3778

\& and target me@foo.bar maxforward 10

3779

\& then restart

3780

\& if 5 restarts within 5 cycles then timeout

3781

.Ve

3782

.PP

3783

Some servers are slow starters, like for example Java based

3784

Application Servers. So if we want to keep the poll-cycle low

3785

(i.e. < 60 seconds) but allow some services to take its time to

3786

start, the \fBevery\fR statement is handy:

3787

.PP

3788

.Vb 4

3789

\& check process dynamo with pidfile /etc/dynamo.pid every 2 cycles

3790

\& start program = "/etc/init.d/dynamo start"

3791

\& stop program = "/etc/init.d/dynamo stop"

3792

\& if failed port 8840 then alert

3793

.Ve

3794

.PP

3795

Here is an example where we group together two database entries

3796

so you can manage them together, e.g.; 'Monit \-g database start

3797

all'. The mode statement is also illustrated in the first entry

3798

and have the effect that Monit will not try to (re)start this

3799

service if it is not running:

3800

.PP

3801

.Vb 5

3802

\& check process sybase with pidfile /var/run/sybase.pid

3803

\& start = "/etc/init.d/sybase start"

3804

\& stop = "/etc/init.d/sybase stop"

3805

\& mode passive

3806

\& group database

3807

\&

3808

\& check process oracle with pidfile /var/run/oracle.pid

3809

\& start program = "/etc/init.d/oracle start"

3810

\& stop program = "/etc/init.d/oracle stop"

3811

\& mode active # Not necessary really, since it\*(Aqs the default

3812

\& if failed port 9001 then restart

3813

\& group database

3814

.Ve

3815

.PP

3816

Here is an example to show the usage of the resource checks. It

3817

will send an alert when the \s-1CPU\s0 usage of the http daemon and its

3818

child processes raises beyond 60% for over two cycles. Apache is

3819

restarted if the \s-1CPU\s0 usage is over 80% for five cycles or the

3820

memory usage over 100Mb for five cycles or if the machines load

3821

average is more than 10 for 8 cycles:

3822

.PP

3823

.Vb 8

3824

\& check process apache with pidfile /var/run/httpd.pid

3825

\& start program = "/etc/init.d/httpd start"

3826

\& stop program = "/etc/init.d/httpd stop"

3827

\& if cpu > 40% for 2 cycles then alert

3828

\& if totalcpu > 60% for 2 cycles then alert

3829

\& if totalcpu > 80% for 5 cycles then restart

3830

\& if mem > 100 MB for 5 cycles then stop

3831

\& if loadavg(5min) greater than 10.0 for 8 cycles then stop

3832

.Ve

3833

.PP

3834

This examples demonstrate the timestamp statement with exec and

3835

how you may restart apache if its configuration file was

3836

changed.

3837

.PP

3838

.Vb 3

3839

\& check file httpd.conf with path /etc/httpd/httpd.conf

3840

\& if changed timestamp

3841

\& then exec "/etc/init.d/httpd graceful"

3842

.Ve

3843

.PP

3844

In this example we demonstrate usage of the extended alert

3845

statement and a file check dependency:

3846

.PP

3847

.Vb 10

3848

\& check process apache with pidfile /var/run/httpd.pid

3849

\& start = "/etc/init.d/httpd start"

3850

\& stop = "/etc/init.d/httpd stop"

3851

\& alert admin@bar on {nonexist, timeout}

3852

\& with mail\-format {

3853

\& from: bofh@$HOST

3854

\& subject: apache $EVENT \- $ACTION

3855

\& message: This event occurred on $HOST at $DATE.

3856

\& Your faithful employee,

3857

\& monit

3858

\& }

3859

\& if failed host www.tildeslash.com port 80 then restart

3860

\& if 3 restarts within 5 cycles then timeout

3861

\& depend httpd_bin

3862

\& group apache

3863

\&

3864

\& check file httpd_bin with path /usr/local/apache/bin/httpd

3865

\& alert security@bar on {checksum, timestamp,

3866

\& permission, uid, gid}

3867

\& with mail\-format {subject: Alaaarrm! on $HOST}

3868

\& if failed checksum

3869

\& and expect 8f7f419955cefa0b33a2ba316cba3659

3870

\& then unmonitor

3871

\& if failed permission 755 then unmonitor

3872

\& if failed uid root then unmonitor

3873

\& if failed gid root then unmonitor

3874

\& if changed timestamp then alert

3875

\& group apache

3876

.Ve

3877

.PP

3878

In this example, we demonstrate usage of the depend statement. In

3879

this case, we want to start oracle and apache. However, we've set

3880

up apache to use oracle as a back end, and if oracle is

3881

restarted, apache must be restarted as well.

3882

.PP

3883

.Vb 4

3884

\& check process apache with pidfile /var/run/httpd.pid

3885

\& start = "/etc/init.d/httpd start"

3886

\& stop = "/etc/init.d/httpd stop"

3887

\& depends on oracle

3888

\&

3889

\& check process oracle with pidfile /var/run/oracle.pid

3890

\& start = "/etc/init.d/oracle start"

3891

\& stop = "/etc/init.d/oracle stop"

3892

\& if failed port 9001 then restart

3893

.Ve

3894

.PP

3895

Next, we have 2 services, oracle-import and oracle-export that

3896

need to be restarted if oracle is restarted, but are independent

3897

of each other.

3898

.PP

3899

.Vb 4

3900

\& check process oracle with pidfile /var/run/oracle.pid

3901

\& start = "/etc/init.d/oracle start"

3902

\& stop = "/etc/init.d/oracle stop"

3903

\& if failed port 9001 then restart

3904

\&

3905

\& check process oracle\-import

3906

\& with pidfile /var/run/oracle\-import.pid

3907

\& start = "/etc/init.d/oracle\-import start"

3908

\& stop = "/etc/init.d/oracle\-import stop"

3909

\& depends on oracle

3910

\&

3911

\& check process oracle\-export

3912

\& with pidfile /var/run/oracle\-export.pid

3913

\& start = "/etc/init.d/oracle\-export start"

3914

\& stop = "/etc/init.d/oracle\-export stop"

3915

\& depends on oracle

3916

.Ve

3917

.PP

3918

Finally an example with all statements:

3919

.PP

3920

.Vb 10

3921

\& check process apache with pidfile /var/run/httpd.pid

3922

\& start program = "/etc/init.d/httpd start"

3923

\& stop program = "/etc/init.d/httpd stop"

3924

\& if 3 restarts within 5 cycles then timeout

3925

\& if failed host www.sol.no port 80 protocol http

3926

\& and use the request "/login.cgi"

3927

\& then alert

3928

\& if failed host shop.sol.no port 443 type tcpssl

3929

\& protocol http and with timeout 15 seconds

3930

\& then restart

3931

\& if cpu is greater than 60% for 2 cycles then alert

3932

\& if cpu > 80% for 5 cycles then restart

3933

\& if totalmem > 100 MB then stop

3934

\& if children > 200 then alert

3935

\& alert bofh@bar with mail\-format {from: monit@foo.bar.no}

3936

\& every 2 cycles

3937

\& mode active

3938

\& depends on weblogic

3939

\& depends on httpd.pid

3940

\& depends on httpd.conf

3941

\& depends on httpd_bin

3942

\& depends on datafs

3943

\& group server

3944

\&

3945

\& check file httpd.pid with path /usr/local/apache/logs/httpd.pid

3946

\& group server

3947

\& if timestamp > 7 days then restart

3948

\& every 2 cycles

3949

\& alert bofh@bar with mail\-format {from: monit@foo.bar.no}

3950

\& depends on datafs

3951

\&

3952

\& check file httpd.conf with path /etc/httpd/httpd.conf

3953

\& group server

3954

\& if timestamp was changed

3955

\& then exec "/usr/local/apache/bin/apachectl graceful"

3956

\& every 2 cycles

3957

\& alert bofh@bar with mail\-format {from: monit@foo.bar.no}

3958

\& depends on datafs

3959

\&

3960

\& check file httpd_bin with path /usr/local/apache/bin/httpd

3961

\& group server

3962

\& if failed checksum and expect the sum

3963

\& 8f7f419955cefa0b33a2ba316cba3659 then unmonitor

3964

\& if failed permission 755 then unmonitor

3965

\& if failed uid root then unmonitor

3966

\& if failed gid root then unmonitor

3967

\& if changed size then alert

3968

\& if changed timestamp then alert

3969

\& every 2 cycles

3970

\& alert bofh@bar with mail\-format {from: monit@foo.bar.no}

3971

\& alert foo@bar on { checksum, size, timestamp, uid, gid }

3972

\& depends on datafs

3973

\&

3974

\& check filesystem datafs with path /dev/sdb1

3975

\& group server

3976

\& start program = "/bin/mount /data"

3977

\& stop program = "/bin/umount /data"

3978

\& if failed permission 660 then unmonitor

3979

\& if failed uid root then unmonitor

3980

\& if failed gid disk then unmonitor

3981

\& if space usage > 80 % then alert

3982

\& if space usage > 94 % then stop

3983

\& if inode usage > 80 % then alert

3984

\& if inode usage > 94 % then stop

3985

\& alert root@localhost

3986

\&

3987

\& check host ftp.redhat.com with address ftp.redhat.com

3988

\& if failed icmp type echo with timeout 15 seconds

3989

\& then alert

3990

\& if failed port 21 protocol ftp

3991

\& then exec "/usr/X11R6/bin/xmessage \-display

3992

\& :0 ftp connection failed"

3993

\& alert foo@bar.com

3994

\&

3995

\& check host www.gnu.org with address www.gnu.org

3996

\& if failed port 80 protocol http

3997

\& and request "/pub/gnu/bash/bash\-2.05b.tar.gz"

3998

\& with checksum 8f7f419955cefa0b33a2ba316cba3659

3999

\& then alert

4000

\& alert rms@gnu.org with mail\-format {

4001

\& subject: The gnu server may be hacked again! }

4002

.Ve

4003

.PP

4004

Note: only the \fBcheck statement\fR is mandatory, the other

4005

statements are optional and the order of the optional statements

4006

is not important.

4007

.SH "FILES"

4008

.IX Header "FILES"

4009

\&\fI~/.monitrc\fR

4010

Default run control file

4011

.PP

4012

\&\fI/etc/monitrc\fR

4013

If the control file is not found in the default

4014

location and /etc contains a \fImonitrc\fR file, this

4015

file will be used instead.

4016

.PP

4017

\&\fI./monitrc\fR

4018

If the control file is not found in either of the

4019

previous two locations, and the current working

4020

directory contains a \fImonitrc\fR file, this file is

4021

used instead.

4022

.PP

4023

\&\fI~/.monit.pid\fR

4024

Lock file to help prevent concurrent runs (non-root

4025

mode).

4026

.PP

4027

\&\fI/var/run/monit.pid\fR

4028

Lock file to help prevent concurrent runs (root mode,

4029

Linux systems).

4030

.PP

4031

\&\fI/etc/monit.pid\fR

4032

Lock file to help prevent concurrent runs (root mode,

4033

systems without /var/run).

4034

.PP

4035

\&\fI~/.monit.state\fR

4036

Monit saves its state to this file and utilizes

4037

information found in this file to recover from

4038

a crash. This is a binary file and its content is

4039

only of interest to monit. You may set the location

4040

of this file in the Monit control file or by using

4041

the \-s switch when Monit is started.

4042

.PP

4043

\&\fI~/.monit.id\fR

4044

Monit save its unique id to this file.

4045

.SH "ENVIRONMENT"

4046

.IX Header "ENVIRONMENT"

4047

No environment variables are used by Monit. However, when Monit

4048

execute a script or a program Monit will set several environment

4049

variables which can be utilized by the executable. The following

4050

and \fIonly\fR the following environment variables are available:

4051

.IP "\s-1MONIT_EVENT\s0" 4

4052

.IX Item "MONIT_EVENT"

4053

The event that occurred on the service

4054

.IP "\s-1MONIT_DESCRIPTION\s0" 4

4055

.IX Item "MONIT_DESCRIPTION"

4056

A description of the error condition

4057

.IP "\s-1MONIT_SERVICE\s0" 4

4058

.IX Item "MONIT_SERVICE"

4059

The name of the service (from monitrc) on which the event

4060

occurred.

4061

.IP "\s-1MONIT_DATE\s0" 4

4062

.IX Item "MONIT_DATE"

4063

The time and date (rfc 822 style) the event occurred

4064

.IP "\s-1MONIT_HOST\s0" 4

4065

.IX Item "MONIT_HOST"

4066

The host the event occurred on

4067

.PP

4068

The following environment variables are only available for

4069

process service entries:

4070

.IP "\s-1MONIT_PROCESS_PID\s0" 4

4071

.IX Item "MONIT_PROCESS_PID"

4072

The process pid. This may be 0 if the process was (re)started,

4073

.IP "\s-1MONIT_PROCESS_MEMORY\s0" 4

4074

.IX Item "MONIT_PROCESS_MEMORY"

4075

Process memory. This may be 0 if the process was (re)started,

4076

.IP "\s-1MONIT_PROCESS_CHILDREN\s0" 4

4077

.IX Item "MONIT_PROCESS_CHILDREN"

4078

Process children. This may be 0 if the process was (re)started,

4079

.IP "\s-1MONIT_PROCESS_CPU_PERCENT\s0" 4

4080

.IX Item "MONIT_PROCESS_CPU_PERCENT"

4081

Process cpu%. This may be 0 if the process was (re)started,

4082

.PP

4083

In addition the following spartan \s-1PATH\s0 environment variable is

4084

available:

4085

.IP "PATH=/bin:/usr/bin:/sbin:/usr/sbin" 4

4086

.IX Item "PATH=/bin:/usr/bin:/sbin:/usr/sbin"

4087

.PP

4088

Scripts or programs that depends on other environment variables

4089

or on a more verbose \s-1PATH\s0 must provide means to set these

4090

variables by them self.

4091

.SH "SIGNALS"

4092

.IX Header "SIGNALS"

4093

If a Monit daemon is running, \s-1SIGUSR1\s0 wakes it up from its sleep

4094

phase and forces a poll of all services. \s-1SIGTERM\s0 and \s-1SIGINT\s0 will

4095

gracefully terminate a Monit daemon. The \s-1SIGTERM\s0 signal is sent

4096

to a Monit daemon if Monit is started with the \fIquit\fR action

4097

argument.

4098

.PP

4099

Sending a \s-1SIGHUP\s0 signal to a running Monit daemon will force

4100

the daemon to reinitialize itself, specifically it will reread

4101

configuration, close and reopen log files.

4102

.PP

4103

Running Monit in foreground while a background Monit daemon is

4104

running will wake up the daemon.

4105

.SH "NOTES"

4106

.IX Header "NOTES"

4107

This is a very silent program. Use the \-v switch if you want to

4108

see what Monit is doing, and tail \-f the logfile. Optionally for

4109

testing purposes; you can start Monit with the \-Iv switch. Monit

4110

will then print debug information to the console, to stop monit

4111

in this mode, simply press CTRL^C (i.e. \s-1SIGINT\s0) in the same

4112

console.

4113

.PP

4114

The syntax (and parser) of the control file was inspired by Eric

4115

S. Raymond et al. excellent fetchmail program. Some portions of

4116

this man page also receive inspiration from the same authors.

4117

.SH "COPYRIGHT"

4118

.IX Header "COPYRIGHT"

4119

4120

This product is distributed in the hope that it will be useful,

4121

but \s-1WITHOUT\s0 any warranty; without even the implied warranty of

4122

\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 for a particular purpose.

4123

.SH "SEE ALSO"

4124

.IX Header "SEE ALSO"

4125

\&\s-1GNU\s0 text utilities; \fImd5sum\fR\|(1); \fIsha1sum\fR\|(1); \fIopenssl\fR\|(1); \fIglob\fR\|(7);

4126

\&\fIregex\fR\|(7); \fIhttp://www.mmonit.com/\fR