1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Template-Based Object Configuration</title>
<STYLE type="text/css">
<!--
.PageTitle { font-family: verdana,arial,serif; font-size: 12pt; font-weight: bold; }
.Default { font-family: verdana,arial,serif; font-size: 8pt; }
.SectionHeader { font-family: verdana,arial,serif; font-size: 10pt; font-weight: bold; background-color: #cbcbcb; }
.SectionTitle { font-family: verdana,arial,serif; font-size: 8pt; font-weight: bold; text-decoration: underline; }
.Definition { font-family: verdana,arial,serif; font-size: 7pt; text-align: left; color: #3333cc;}
.Required { font-family: verdana,arial,serif; font-size: 7pt; text-align: left; color: red; }
.Optional { font-family: verdana,arial,serif; font-size: 7pt; text-align: left; }
.RetentionNotes { font-family: verdana,rial,serif; font-size: 10pt; text-align: left; color: red; font-weight: bold; }
-->
</STYLE>
</head>
<body bgcolor="#FFFFFF" text="black" class="Default">
<p>
<div align="center">
<h2 class="PageTitle">Template-Based Object Configuration</h2>
</div>
</p>
<hr>
<p>
<strong><u>Notes</u></strong>
</p>
<p>
When creating and/or editing configuration files, keep the following in mind:
</p>
<p>
<ol>
<li>Lines that start with a '#' character are taken to be comments and are not processed
<li>Directive names are case-sensitive
</ol>
</p>
<p>
<strong><u>Introduction</u></strong>
</p>
<p>
One of the benefits of using the template-based config file format is that you can create object definitions that have some of their properties inherited from other object definitions. The notion of object inheritence, along with documentation on how to do it, is described <a href="templaterecursion.html">here</a>. I strongly suggest that you familiarize yourself with object inheritence once you read over the documentation presented below, as inheritence will make the job of creating and maintaining object definitions much easier than it otherwise would be.
</p>
<p>
<strong><u>Time-Saving Tricks</u></strong>
</p>
<p>
There are several things you can do with template-based object definitions that allow you to create large numbers of objects using just a small number of definitions in your config file(s). One example of such a trick is the ability to define a single service object that creates a service for multiple hosts and/or hostgroups. These tricks are described <a href="templatetricks.html">here</a>.
</p>
<a name="retention_notes"></a>
<p>
<strong><u>Retention Notes</u></strong>
</p>
<p>
It is important to point out that several directives in host and service definitions may not be picked up by Nagios when you change them. Host and service directives that can exhibit this behavior are marked with an asterisk (<a href="#retention_notes" class="RetentionNotes">*</a>). The reason for this behavior is due to the fact that Nagios chooses to honor values stored in the <a href="#state_retention_file">state retention file</a> over values found in the config files, assuming you have <a href="#retain_state_information">state retention</a> enabled on a program-wide basis <i>and</i> the value of the directive is changed during runtime (by submitting an <a href="configmain.html#check_external_commands">external command</a>).
</p>
<p>
One way to get around this problem is to disable the retention of non-status information using the <i>retain_nonstatus_information</i> directive in the host and service definitions. Disabling this directive will cause Nagios to take the initial values for these directives from your config files, rather than from the state retention file when it (re)starts. Using this option is not recommended, as it may result in some unexpected (from your point of view) results.
</p>
<p>
Alternatively, you can issue the appropriate <a href="extcommands.html">external command</a> or change the value of the host or service directive via the web interface, so that it matches what you've changed it to in the config files. This is usually done by using the <a href="cgis.html#extinfo_cgi">extended information CGI</a>. This option takes a bit more work, but is preferable to disabling the retention of non-status information (mentioned above).
</p>
<p>
<strong><u>Sample Configuration</u></strong>
</p>
<p>
A few sample object configuration files are created when you run the configure script - you can find them in the <i>sample-config/template-object/</i> subdirectory of the Nagios distribution.
</p>
<p>
<strong><u>Object Types</u></strong>
</p>
<p>
<a href="#host">Host definitions</a><br>
<a href="#hostgroup">Host group definitions</a><br>
<a href="#service">Service definitions</a><br>
<a href="#servicegroup">Service group definitions</a><br>
<a href="#contact">Contact definitions</a><br>
<a href="#contactgroup">Contact group definitions</a><br>
<a href="#timeperiod">Time period definitions</a><br>
<a href="#command">Command definitions</a><br>
<a href="#servicedependency">Service dependency definitions</a><br>
<a href="#serviceescalation">Service escalation definitions</a><br>
<a href="#hostdependency">Host dependency definitions</a><br>
<a href="#hostescalation">Host escalation definitions</a><br>
<a href="#hostextinfo">Extended host information definitions</a><br>
<a href="#serviceextinfo">Extended service information definitions</a><br>
</p>
<p>
<a name="host"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Host Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A host definition is used to define a physical server, workstation, device, etc. that resides on your network.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define host{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Required">address</td><td class="Required"><i>address</i></td></tr>
<tr><td></td><td class="Optional">parents</td><td class="Optional"><i>host_names</i></td></tr>
<tr><td></td><td class="Optional">hostgroups</td><td class="Optional"><i>hostgroup_names</i></td></tr>
<tr><td></td><td class="Optional">check_command</td><td class="Optional"><i>command_name</i></td></tr>
<tr><td></td><td class="Required">max_check_attempts</td><td class="Required">#</td></tr>
<tr><td></td><td class="Optional">check_interval</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">active_checks_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">passive_checks_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">check_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Optional">obsess_over_host</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">check_freshness</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">freshness_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">event_handler</td><td class="Optional"><i>command_name</i></td></tr>
<tr><td></td><td class="Optional">event_handler_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">low_flap_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">high_flap_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">flap_detection_enabled</td><td class="Optional">[0/1]</td></tr>
<!--<tr><td></td><td class="Optional">failure_prediction_enabled</td><td class="Optional">[0/1]</td></tr>//-->
<tr><td></td><td class="Optional">process_perf_data</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">retain_status_information</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">retain_nonstatus_information</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">contact_groups</td><td class="Required"><i>contact_groups</i></td></tr>
<tr><td></td><td class="Required">notification_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">notification_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Required">notification_options</td><td class="Required">[d,u,r,f]</td></tr>
<tr><td></td><td class="Optional">notifications_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">stalking_options</td><td class="Optional">[o,d,u]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define host{
host_name bogus-router
alias Bogus Router #1
address 192.168.1.254
parents server-backbone
check_command check-host-alive
max_check_attempts 5
check_period 24x7
process_perf_data 0
retain_nonstatus_information 0
contact_groups router-admins
notification_interval 30
notification_period 24x7
notification_options d,u,r
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to define a short name used to identify the host. It is used in host group and service definitions to reference this particular host. Hosts can have multiple services (which are monitored) associated with them. When used properly, the $HOSTNAME$ <a href="macros.html">macro</a> will contain this short name.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is used to define a longer name or description used to identify the host. It is provided in order to allow you to more easily identify a particular host. When used properly, the $HOSTALIAS$ <a href="macros.html">macro</a> will contain this alias/description.
</td>
</tr>
<tr>
<td valign="top"><strong>address</strong>:</td>
<td>
This directive is used to define the address of the host. Normally, this is an IP address, although it could really be anything you want (so long as it can be used to check the status of the host). You can use a FQDN to identify the host instead of an IP address, but if DNS services are not availble this could cause problems. When used properly, the $HOSTADDRESS$ <a href="macros.html">macro</a> will contain this address. <b>Note:</b> If you do not specify an address directive in a host definition, the name of the host will be used as its address. A word of caution about doing this, however - if DNS fails, most of your service checks will fail because the plugins will be unable to resolve the host name.
</td>
</tr>
<tr>
<td valign="top"><strong>parents</strong>:</td>
<td>
This directive is used to define a comma-delimited list of short names of the "parent" hosts for this particular host. Parent hosts are typically routers, switches, firewalls, etc. that lie between the monitoring host and a remote hosts. A router, switch, etc. which is closest to the remote host is considered to be that host's "parent". Read the "Determining Status and Reachability of Network Hosts" document located <a href="networkreachability.html">here</a> for more information. If this host is on the same network segment as the host doing the monitoring (without any intermediate routers, etc.) the host is considered to be on the local network and will not have a parent host. Leave this value blank if the host does not have a parent host (i.e. it is on the same segment as the Nagios host). The order in which you specify parent hosts has no effect on how things are monitored.
</td>
</tr>
<tr>
<td valign="top"><strong>hostgroups</strong>:</td>
<td>
This directive is used to identify the <i>short name(s)</i> of the <a href="#hostgroup">hostgroup(s)</a> that the host belongs to. Multiple hostgroups should are seperated by commas. This directive may be used as an alternative to (or in addition to) using the <i>members</i> directive in <a href="#hostgroup">hostgroup</a> definitions.
</td>
</tr>
<tr>
<td valign="top"><strong>check_command</strong>:</td>
<td>
This directive is used to specify the <i>short name</i> of the <a href="#command">command</a> that should be used to check if the host is up or down. Typically, this command would try and ping the host to see if it is "alive". The command must return a status of OK (0) or Nagios will assume the host is down. If you leave this argument blank, the host will <i>not</i> be checked - Nagios will always assume the host is up. This is useful if you are monitoring printers or other devices that are frequently turned off. The maximum amount of time that the notification command can run is controlled by the <a href="configmain.html#host_check_timeout">host_check_timeout</a> option.
</td>
</tr>
<tr>
<td valign="top"><strong>max_check_attempts</strong>:</td>
<td>
This directive is used to define the number of times that Nagios will retry the host check command if it returns any state other than an OK state. Setting this value to 1 will cause Nagios to generate an alert without retrying the host check again. Note: If you do not want to check the status of the host, you must still set this to a minimum value of 1. To bypass the host check, just leave the <i>check_command</i> option blank.
</td>
</tr>
<tr>
<td valign="top"><strong>check_interval</strong>:</td>
<td>
<i><strong>NOTE:</strong> Do NOT enable regularly scheduled checks of a host unless you absolutely need to! Host checks are already performed on-demand when necessary, so there are few times when regularly scheduled checks would be needed. Regularly scheduled host checks can negatively impact performance - see the <a href="tuning.html">performance tuning tips</a> for more information.</i>
This directive is used to define the number of "time units" between regularly scheduled checks of the host. Unless you've changed the <a href="configmain.html#interval_length">interval_length</a> directive from the default value of 60, this number will mean minutes. More information on this value can be found in the <a href="checkscheduling.html">check scheduling</a> documentation.
</td>
</tr>
<tr>
<td valign="top"><strong>active_checks_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not active checks (either regularly scheduled or on-demand) of this host are enabled. Values: 0 = disable active host checks, 1 = enable active host checks.
</td>
</tr>
<tr>
<td valign="top"><strong>passive_checks_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not passive checks are enabled for this host. Values: 0 = disable passive host checks, 1 = enable passive host checks.
</td>
</tr>
<tr>
<td valign="top"><strong>check_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which active checks of this host can be made.
</td>
</tr>
<tr>
<td valign="top"><strong>obsess_over_host <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive determines whether or not checks for the host will be "obsessed" over using the <a href="configmain.html#ochp_command">ochp_command</a>.
</td>
</tr>
<tr>
<td valign="top"><strong>check_freshness <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not <a href="freshness.html">freshness checks</a> are enabled for this host. Values: 0 = disable freshness checks, 1 = enable freshness checks.
</td>
</tr>
<tr>
<td valign="top"><strong>freshness_threshold</strong>:</td>
<td>
This directive is used to specify the freshness threshold (in seconds) for this host. If you set this directive to a value of 0, Nagios will determine a freshness threshold to use automatically.
</td>
</tr>
<tr>
<td valign="top"><strong>event_handler</strong>:</td>
<td>
This directive is used to specify the <i>short name</i> of the <a href="#command">command</a> that should be run whenever a change in the state of the host is detected (i.e. whenever it goes down or recovers). Read the documentation on
<a href="eventhandlers.html">event handlers</a> for a more detailed explanation of how to write scripts for handling events. The maximum amount of time that the event handler command can run is controlled by the <a href="configmain.html#event_handler_timeout">event_handler_timeout</a> option.
</td>
</tr>
<tr>
<td valign="top"><strong>event_handler_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not the event handler for this host is enabled. Values: 0 = disable host event handler, 1 = enable host event handler.
</td>
</tr>
<tr>
<td valign="top"><strong>low_flap_threshold</strong>:</td>
<td>
This directive is used to specify the low state change threshold used in flap detection for this host. More information on flap detection can be found <a href="flapping.html">here</a>. If you set this directive to a value of 0, the program-wide value specified by the <a href="configmain.html#low_host_flap_threshold">low_host_flap_threshold</a> directive will be used.
</td>
</tr>
<tr>
<td valign="top"><strong>high_flap_threshold</strong>:</td>
<td>
This directive is used to specify the high state change threshold used in flap detection for this host. More information on flap detection can be found <a href="flapping.html">here</a>. If you set this directive to a value of 0, the program-wide value specified by the <a href="configmain.html#high_host_flap_threshold">high_host_flap_threshold</a> directive will be used.
</td>
</tr>
<tr>
<td valign="top"><strong>flap_detection_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not flap detection is enabled for this host. More information on flap detection can be found <a href="flapping.html">here</a>. Values: 0 = disable host flap detection, 1 = enable host flap detection.
</td>
</tr>
<!--
<tr>
<td valign="top"><strong>failure_prediction_enabled</strong>:</td>
<td>
This directive is used to determine whether or not failure prediction is enabled for this host. Values: 0 = disable host failure prediction, 1 = enable host failure prediction.
</td>
</tr>
//-->
<tr>
<td valign="top"><strong>process_perf_data <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not the processing of performance data is enabled for this host. Values: 0 = disable performance data processing, 1 = enable performance data processing.
</td>
</tr>
<tr>
<td valign="top"><strong>retain_status_information</strong>:</td>
<td>
This directive is used to determine whether or not status-related information about the host is retained across program restarts. This is only useful if you have enabled state retention using the <a href="configmain.html#retain_state_information">retain_state_information</a> directive. Value: 0 = disable status information retention, 1 = enable status information retention.
</td>
</tr>
<tr>
<td valign="top"><strong>retain_nonstatus_information</strong>:</td>
<td>
This directive is used to determine whether or not non-status information about the host is retained across program restarts. This is only useful if you have enabled state retention using the <a href="configmain.html#retain_state_information">retain_state_information</a> directive. Value: 0 = disable non-status information retention, 1 = enable non-status information retention.
</td>
</tr>
<tr>
<td valign="top"><strong>contact_groups</strong>:</td>
<td>
This is a list of the <i>short names</i> of the <a href="#contactgroup">contact groups</a> that should be notified whenever there are problems (or recoveries) with this host. Multiple contact groups should be separated by commas.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_interval</strong>:</td>
<td>
This directive is used to define the number of "time units" to wait before re-notifying a contact that this server is <i>still</i> down or unreachable. Unless you've changed the <a href="configmain.html#interval_length">interval_length</a> directive from the default value of 60, this number will mean minutes. If you set this value to 0, Nagios will <i>not</i> re-notify contacts about problems for this host - only one problem notification will be sent out.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which notifications of events for this host can be sent out to contacts. If a host goes down, becomes unreachable, or recoveries during a time which is not covered by the time period, no notifications will be sent out.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_options</strong>:</td>
<td>
This directive is used to determine when notifications for the host should be sent out. Valid options are a combination of one or more of the following: <b>d</b> = send notifications on a DOWN state, <b>u</b> = send notifications on an UNREACHABLE state, <b>r</b> = send notifications on recoveries (OK state), and <b>f</b> = send notifications when the host starts and stops <a href="flapping.html">flapping</a>. If you specify <b>n</b> (none) as an option, no host notifications will be sent out. Example: If you specify <b>d,r</b> in this field, notifications will only be sent out when the host goes DOWN and when it recovers from a DOWN state.
</td>
</tr>
<tr>
<td valign="top"><strong>notifications_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not notifications for this host are enabled. Values: 0 = disable host notifications, 1 = enable host notifications.
</td>
</tr>
<tr>
<td valign="top"><strong>stalking_options</strong>:</td>
<td>
This directive determines which host states "stalking" is enabled for. Valid options are a combination of one or more of the following: <b>o</b> = stalk on UP states, <b>d</b> = stalk on DOWN states, and <b>u</b> = stalk on UNREACHABLE states. More information on state stalking can be found <a href="stalking.html">here</a>.
</td>
</tr>
</table>
</p>
<p>
<a name="hostgroup"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Host Group Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A host group definition is used to group one or more hosts together for display purposes in the <a href="cgis.html">CGIs</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define hostgroup{</td></tr>
<tr><td></td><td class="Required">hostgroup_name</td><td class="Required"><i>hostgroup_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Required">members</td><td class="Required"><i>members</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define hostgroup{
hostgroup_name novell-servers
alias Novell Servers
members netware1,netware2,netware3,netware4
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>hostgroup_name</strong>:</td>
<td>
This directive is used to define a short name used to identify the host group.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is used to define is a longer name or description used to identify the host group. It is provided in order to allow you to more easily identify a particular host group.
</td>
</tr>
<tr>
<td valign="top"><strong>members</strong>:</td>
<td>
This is a list of the <i>short names</i> of <a href="#host">hosts</a> that should be included in this group. Multiple host names should be separated by commas. This directive may be used as an alternative to (or in addition to) the <i>hostgroups</i> directive in <a href="#host">host definitions</a>.
</td>
</tr>
</table>
</p>
<p>
<a name="service"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Service Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A service definition is used to identify a "service" that runs on a host. The term "service" is used very loosely. It can mean an actual service that runs on the host (POP, SMTP, HTTP, etc.) or some other type of metric associated with the host (response to a ping, number of logged in users, free disk space, etc.). The different arguments to a service definition are outlined below.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define service{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">service_description</td><td class="Required"><i>service_description</i></td></tr>
<tr><td></td><td class="Optional">servicegroups</td><td class="Optional">servicegroup_names</td></tr>
<tr><td></td><td class="Optional">is_volatile</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">check_command</td><td class="Required"><i>command_name</i></td></tr>
<tr><td></td><td class="Required">max_check_attempts</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">normal_check_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">retry_check_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Optional">active_checks_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">passive_checks_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">check_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Optional">parallelize_check</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">obsess_over_service</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">check_freshness</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">freshness_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">event_handler</td><td class="Optional"><i>command_name</i></td></tr>
<tr><td></td><td class="Optional">event_handler_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">low_flap_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">high_flap_threshold</td><td class="Optional">#</td></tr>
<tr><td></td><td class="Optional">flap_detection_enabled</td><td class="Optional">[0/1]</td></tr>
<!--<tr><td></td><td class="Optional">failure_prediction_enabled</td><td class="Optional">[0/1]</td></tr>//-->
<tr><td></td><td class="Optional">process_perf_data</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">retain_status_information</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">retain_nonstatus_information</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">notification_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">notification_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Required">notification_options</td><td class="Required">[w,u,c,r,f]</td></tr>
<tr><td></td><td class="Optional">notifications_enabled</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Required">contact_groups</td><td class="Required"><i>contact_groups</i></td></tr>
<tr><td></td><td class="Optional">stalking_options</td><td class="Optional">[o,w,u,c]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define service{
host_name linux-server
service_description check-disk-sda1
check_command check-disk!/dev/sda1
max_check_attempts 5
normal_check_interval 5
retry_check_interval 3
check_period 24x7
notification_interval 30
notification_period 24x7
notification_options w,c,r
contact_groups linux-admins
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to specify the <i>short name</i> of the <a href="#host">host</a> that the service "runs" on or is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>service_description;</strong>:</td>
<td>
This directive is used to define the description of the service, which may contain spaces, dashes, and colons (semicolons, apostrophes, and quotation marks should be avoided). No two services associated with the same host can have the same description. Services are uniquely identified with their <i>host_name</i> and <i>service_description</i> directives.
</td>
</tr>
<tr>
<td valign="top"><strong>servicegroups</strong>:</td>
<td>
This directive is used to identify the <i>short name(s)</i> of the <a href="#servicegroup">servicegroup(s)</a> that the service belongs to. Multiple servicegroups should are seperated by commas. This directive may be used as an alternative to using the <i>members</i> directive in <a href="#servicegroup">servicegroup</a> definitions.
</td>
</tr>
<tr>
<td valign="top"><strong>is_volatile</strong>:</td>
<td>
This directive is used to denote whether the service is "volatile". Services are normally <i>not</i> volatile. More information on volatile service and how they differ from normal services can be found <a href="volatileservices.html">here</a>. Value: 0 = service is not volatile, 1 = service is volatile.
</td>
</tr>
<tr>
<td valign="top"><strong>check_command</strong>:</td>
<td>
<p>
This directive is used to specify the <i>short name</i> of the <a href="#command">command</a> that Nagios will run in order to check the status of the service. The maximum amount of time that the service check command can run is controlled by the <a href="configmain.html#service_check_timeout">service_check_timeout</a> option.</p>
</td>
</tr>
<tr>
<td valign="top"><strong>max_check_attempts</strong>:</td>
<td>
This directive is used to define the number of times that Nagios will retry the service check command if it returns any state other than an OK state. Setting this value to 1 will cause Nagios to generate an alert without retrying the service check again.
</td>
</tr>
<tr>
<td valign="top"><strong>normal_check_interval</strong>:</td>
<td>
This directive is used to define the number of "time units" to wait before scheduling the next "regular" check of the service. "Regular" checks are those that occur when the service is in an OK state or when the service is in a non-OK state, but has already been rechecked <b>max_attempts</b> number of times. Unless you've changed the <a href="configmain.html#interval_length">interval_length</a> directive from the default value of 60, this number will mean minutes. More information on this value can be found in the <a href="checkscheduling.html">check scheduling</a> documentation.
</td>
</tr>
<tr>
<td valign="top"><strong>retry_check_interval</strong>:</td>
<td>
This directive is used to define the number of "time units" to wait before scheduling a re-check of the service. Services are rescheduled at the retry interval when the have changed to a non-OK state. Once the service has been retried <b>max_attempts</b> times without a change in its status, it will revert to being scheduled at its "normal" rate as defined by the <b>check_interval</b> value. Unless you've changed the <a href="configmain.html#interval_length">interval_length</a> directive from the default value of 60, this number will mean minutes. More information on this value can be found in the <a href="checkscheduling.html">check scheduling</a> documentation.
</td>
</tr>
<tr>
<td valign="top"><strong>active_checks_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not active checks of this service are enabled. Values: 0 = disable active service checks, 1 = enable active service checks.
</td>
</tr>
<tr>
<td valign="top"><strong>passive_checks_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not passive checks of this service are enabled. Values: 0 = disable passive service checks, 1 = enable passive service checks.
</td>
</tr>
<tr>
<td valign="top"><strong>check_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which active checks of this service can be made.
</td>
</tr>
<tr>
<td valign="top"><strong>parallelize_check</strong>:</td>
<td>
This directive is used to determine whether or not the service check can be parallelized. By default, all service checks are parallelized. Disabling parallel checks of services can result in serious performance problems. More information on service check parallelization can be found <a href="parallelization.html">here</a>. Values: 0 = service check cannot be parallelized (use with caution!), 1 = service check can be parallelized.
</td>
</tr>
<tr>
<td valign="top"><strong>obsess_over_service <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive determines whether or not checks for the service will be "obsessed" over using the <a href="configmain.html#ocsp_command">ocsp_command</a>.
</td>
</tr>
<tr>
<td valign="top"><strong>check_freshness <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not <a href="freshness.html">freshness checks</a> are enabled for this service. Values: 0 = disable freshness checks, 1 = enable freshness checks.
</td>
</tr>
<tr>
<td valign="top"><strong>freshness_threshold</strong>:</td>
<td>
This directive is used to specify the freshness threshold (in seconds) for this service. If you set this directive to a value of 0, Nagios will determine a freshness threshold to use automatically.
</td>
</tr>
<tr>
<td valign="top"><strong>event_handler_enabled</strong>:</td>
<td>
This directive is used to determine whether or not the event handler for this service is enabled. Values: 0 = disable service event handler, 1 = enable service event handler.
</td>
</tr>
<tr>
<td valign="top"><strong>low_flap_threshold</strong>:</td>
<td>
This directive is used to specify the low state change threshold used in flap detection for this service. More information on flap detection can be found <a href="flapping.html">here</a>. If you set this directive to a value of 0, the program-wide value specified by the <a href="configmain.html#low_service_flap_threshold">low_service_flap_threshold</a> directive will be used.
</td>
</tr>
<tr>
<td valign="top"><strong>high_flap_threshold</strong>:</td>
<td>
This directive is used to specify the high state change threshold used in flap detection for this service. More information on flap detection can be found <a href="flapping.html">here</a>. If you set this directive to a value of 0, the program-wide value specified by the <a href="configmain.html#high_service_flap_threshold">high_service_flap_threshold</a> directive will be used.
</td>
</tr>
<tr>
<td valign="top"><strong>flap_detection_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not flap detection is enabled for this service. More information on flap detection can be found <a href="flapping.html">here</a>. Values: 0 = disable service flap detection, 1 = enable service flap detection.
</td>
</tr>
<!--
<tr>
<td valign="top"><strong>failure_prediction_enabled</strong>:</td>
<td>
This directive is used to determine whether or not failure prediction is enabled for this service. Values: 0 = disable service failure prediction, 1 = enable service failure prediction.
</td>
</tr>
//-->
<tr>
<td valign="top"><strong>process_perf_data <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not the processing of performance data is enabled for this service. Values: 0 = disable performance data processing, 1 = enable performance data processing.
</td>
</tr>
<tr>
<td valign="top"><strong>retain_status_information</strong>:</td>
<td>
This directive is used to determine whether or not status-related information about the service is retained across program restarts. This is only useful if you have enabled state retention using the <a href="configmain.html#retain_state_information">retain_state_information</a> directive. Value: 0 = disable status information retention, 1 = enable status information retention.
</td>
</tr>
<tr>
<td valign="top"><strong>retain_nonstatus_information</strong>:</td>
<td>
This directive is used to determine whether or not non-status information about the service is retained across program restarts. This is only useful if you have enabled state retention using the <a href="configmain.html#retain_state_information">retain_state_information</a> directive. Value: 0 = disable non-status information retention, 1 = enable non-status information retention.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_interval</strong>:</td>
<td>
This directive is used to define the number of "time units" to wait before re-notifying a contact that this service is <i>still</i> in a non-OK state. Unless you've changed the <a href="configmain.html#interval_length">interval_length</a> directive from the default value of 60, this number will mean minutes. If you set this value to 0, Nagios will <i>not</i> re-notify contacts about problems for this service - only one problem notification will be sent out.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which notifications of events for this service can be sent out to contacts. No service notifications will be sent out during times which is not covered by the time period.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_options</strong>:</td>
<td>
This directive is used to determine when notifications for the service should be sent out. Valid options are a combination of one or more of the following: <b>w</b> = send notifications on a WARNING state, <b>u</b> = send notifications on an UNKNOWN state, <b>c</b> = send notifications on a CRITICAL state, <b>r</b> = send notifications on recoveries (OK state), and <b>f</b> = send notifications when the service starts and stops <a href="flapping.html">flapping</a>. If you specify <b>n</b> (none) as an option, no service notifications will be sent out. Example: If you specify <b>w,r</b> in this field, notifications will only be sent out when the service goes into a WARNING state and when it recovers from a WARNING state.
</td>
</tr>
<tr>
<td valign="top"><strong>notifications_enabled <a href="#retention_notes" class="RetentionNotes">*</a></strong>:</td>
<td>
This directive is used to determine whether or not notifications for this service are enabled. Values: 0 = disable service notifications, 1 = enable service notifications.
</td>
</tr>
<tr>
<td valign="top"><strong>contact_groups</strong>:</td>
<td>
This is a list of the <i>short names</i> of the <a href="#contactgroup">contact groups</a> that should be notified whenever there are problems (or recoveries) with this service. Multiple contact groups should be separated by commas.
</td>
</tr>
<tr>
<td valign="top"><strong>stalking_options</strong>:</td>
<td>
This directive determines which service states "stalking" is enabled for. Valid options are a combination of one or more of the following: <b>o</b> = stalk on OK states, <b>w</b> = stalk on WARNING states, <b>u</b> = stalk on UNKNOWN states, and <b>c</b> = stalk on CRITICAL states. More information on state stalking can be found <a href="stalking.html">here</a>.
</td>
</tr>
</table>
</p>
<p>
<a name="servicegroup"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Service Group Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A service group definition is used to group one or more services together for display purposes in the <a href="cgis.html">CGIs</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define servicegroup{</td></tr>
<tr><td></td><td class="Required">servicegroup_name</td><td class="Required"><i>servicegroup_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Required">members</td><td class="Required"><i>members</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define servicegroup{
servicegroup_name dbservices
alias Database Services
members ms1,SQL Server,ms1,SQL Server Agent,ms1,SQL DTC
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>servicegroup_name</strong>:</td>
<td>
This directive is used to define a short name used to identify the service group.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is used to define is a longer name or description used to identify the service group. It is provided in order to allow you to more easily identify a particular service group.
</td>
</tr>
<tr>
<td valign="top"><strong>members</strong>:</td>
<td>
<p>
This is a list of the <i>descriptions</i> of <a href="#service">services</a> (and the names of their corresponding hosts) that should be included in this group. Host and service names should be separated by commas. This directive may be used as an alternative to the <i>servicegroups</i> directive in <a href="#service">service definitions</a>. The format of the member directive is as follows (note that a host name must precede a service name/description):
</p>
<p>
members=<host1>,<service1>,<host2>,<service2>,...,<host<i>n</i>>,<service<i>n</i>>
</p>
</td>
</tr>
</table>
</p>
<p>
<a name="contact"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Contact Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A contact definition is used to identify someone who should be contacted in the event of a problem on your network.
The different arguments to a contact definition are described below.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define contact{</td></tr>
<tr><td></td><td class="Required">contact_name</td><td class="Required"><i>contact_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Optional">contactgroups</td><td class="Optional"><i>contactgroup_names</i></td></tr>
<tr><td></td><td class="Required">host_notification_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Required">service_notification_period</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Required">host_notification_options</td><td class="Required">[d,u,r,f,n]</td></tr>
<tr><td></td><td class="Required">service_notification_options</td><td class="Required">[w,u,c,r,f,n]</td></tr>
<tr><td></td><td class="Required">host_notification_commands</td><td class="Optional"><i>command_name</i></td></tr>
<tr><td></td><td class="Required">service_notification_commands</td><td class="Optional"><i>command_name</i></td></tr>
<tr><td></td><td class="Optional">email</td><td class="Optional"><i>email_address</i></td></tr>
<tr><td></td><td class="Optional">pager</td><td class="Optional"><i>pager_number or pager_email_gateway</i></td></tr>
<tr><td></td><td class="Optional">address<i>x</i></td><td class="Optional"><i>additional_contact_address</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define contact{
contact_name jdoe
alias John Doe
service_notification_period 24x7
host_notification_period 24x7
service_notification_options w,u,c,r
host_notification_options d,u,r
service_notification_commands notify-by-email
host_notification_commands host-notify-by-email
email jdoe@localhost.localdomain
pager 555-5555@pagergateway.localhost.localdomain
address1 xxxxx.xyyy@icq.com
address2 555-555-5555
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>contact_name</strong>:</td>
<td>
This directive is used to define a short name used to identify the contact. It is referenced in <a href="#contactgroup">contact group</a> definitions. Under the right circumstances, the $CONTACTNAME$ <a href="macros.html">macro</a> will contain this
value.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is used to define a longer name or description for the contact. Under the rights circumstances, the $CONTACTALIAS$ <a href="macros.html">macro</a> will contain this value.
</td>
</tr>
<tr>
<td valign="top"><strong>contactgroups</strong>:</td>
<td>
This directive is used to identify the <i>short name(s)</i> of the <a href="#contactgroup">contactgroup(s)</a> that the contact belongs to. Multiple contactgroups should are seperated by commas. This directive may be used as an alternative to (or in addition to) using the <i>members</i> directive in <a href="#contactgroup">contactgroup</a> definitions.
</td>
</tr>
<tr>
<td valign="top"><strong>host_notification_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which the contact can be notified about host problems or recoveries. You can think of this as an "on call" time for host notifications for the contact. Read the documentation on <a href="timeperiods.html">time periods</a> for more information on how this works and potential problems that may result from improper use.
</td>
</tr>
<tr>
<td valign="top"><strong>service_notification_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which the contact can be notified about service problems or recoveries. You can think of this as an "on call" time for service notifications for the contact. Read the documentation on <a href="timeperiods.html">time periods</a> for more information on how this works and potential problems that may result from improper use.
</td>
</tr>
<tr>
<td valign="top"><strong>host_notification_commands</strong>:</td>
<td>
This directive is used to define a list of the <i>short names</i> of the <a href="#command">commands</a> used to notify the contact of a <i>host</i> problem or recovery. Multiple notification commands should be separated by commas. All
notification commands are executed when the contact needs to be notified. The maximum amount of time that a notification command can run is controlled by the <a href="configmain.html#notification_timeout">notification_timeout</a> option.
</td>
</tr>
<tr>
<td valign="top"><strong>host_notification_options</strong>:</td>
<td>
This directive is used to define the host states for which notifications can be sent out to this contact. Valid options are a combination of one or more of the following: <b>d</b> = notify on DOWN host states, <b>u</b> = notify on UNREACHABLE host states, <b>r</b> = notify on host recoveries (UP states), and <b>f</b> = notify when the host starts and stops <a href="flapping.html">flapping</a>. If you specify <b>n</b> (none) as an option, the contact will not receive any type of host notifications.
</td>
</tr>
<tr>
<td valign="top"><strong>service_notification_options</strong>:</td>
<td>
This directive is used to define the service states for which notifications can be sent out to this contact. Valid options are a combination of one or more of the following: <b>w</b> = notify on WARNING service states, <b>u</b> = notify on UNKNOWN service states, <b>c</b> = notify on CRITICAL service states, <b>r</b> = notify on service recoveries (OK states), and <b>f</b> = notify when the servuce starts and stops <a href="flapping.html">flapping</a>. If you specify <b>n</b> (none) as an option, the contact will not receive any type of service notifications.
</td>
</tr>
<tr>
<td valign="top"><strong>service_notification_commands</strong>:</td>
<td>
This directive is used to define a list of the <i>short names</i> of the <a href="#command">commands</a> used to notify the contact of a <i>service</i> problem or recovery. Multiple notification commands should be separated by commas. All
notification commands are executed when the contact needs to be notified. The maximum amount of time that a notification command can run is controlled by the <a href="configmain.html#notification_timeout">notification_timeout</a> option.
</td>
</tr>
<tr>
<td valign="top"><strong>email</strong>:</td>
<td>
This directive is used to define an email address for the contact. Depending on how you configure your notification commands, it can be used to send out an alert email to the contact. Under the right circumstances, the $CONTACTEMAIL$
<a href="macros.html">macro</a> will contain this value.
</td>
</tr>
<tr>
<td valign="top"><strong>pager</strong>:</td>
<td>
This directive is used to define a pager number for the contact. It can also be an email address to a pager gateway
(i.e. pagejoe@pagenet.com). Depending on how you configure your notification commands, it can be used to send out an alert page to the contact. Under the right circumstances, the $CONTACTPAGER$ <a href="macros.html">macro</a> will contain this value.
</td>
</tr>
<tr>
<td valign="top"><strong>address<i>x</i></strong>:</td>
<td>
Address directives are used to define additional "addresses" for the contact. These addresses can be anything - cell phone numbers, instant messaging addresses, etc. Depending on how you configure your notification commands, they can be used to send out an alert o the contact. Up to six addresses can be defined using these directives (<i>address1</i> through <i>address6</i>). The $CONTACTADDRESS<i>x</i>$ <a href="macros.html">macro</a> will contain this value.
</td>
</tr>
</table>
</p>
<p>
<a name="contactgroup"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Contact Group Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A contact group definition is used to group one or more <a href="#contact">contacts</a> together for the purpose of sending out alert/recovery notifications. When a host or service has a problem or recovers, Nagios will find the appropriate contact groups to send notifications to, and notify all contacts in those contact groups. This may sound complex, but for most people it doesn't have to be. It does, however, allow for flexibility in determining who gets notified for particular events. The different arguments to a contact group definition are outlined below.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define contactgroup{</td></tr>
<tr><td></td><td class="Required">contactgroup_name</td><td class="Required"><i>contactgroup_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Required">members</td><td class="Required"><i>members</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define contactgroup{
contactgroup_name novell-admins
alias Novell Administrators
members jdoe,rtobert,tzach
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>contactgroup_name</strong>:</td>
<td>
This directive is a short name used to identify the contact group.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is used to define a longer name or description used to identify the contact group.
</td>
</tr>
<tr>
<td valign="top"><strong>members</strong>:</td>
<td>
This directive is used to define a list of the <i>short names</i> of <a href="#contact">contacts </a> that should be included in this group. Multiple contact names should be separated by commas. This directive may be used as an alternative to (or in addition to) using the <i>contactgroups</i> directive in <a href="#contact">contact</a> definitions.
</td>
</tr>
</table>
</p>
<p>
<a name="timeperiod"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Time Period Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A time period is a list of times during various days that are considered to be "valid" times for notifications and service checks. It consists one or more time periods for each day of the week that "rotate" once the week has come to an end. Exceptions to the normal weekly time range rotations are not suported.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define timeperiod{</td></tr>
<tr><td></td><td class="Required">timeperiod_name</td><td class="Required"><i>timeperiod_name</i></td></tr>
<tr><td></td><td class="Required">alias</td><td class="Required"><i>alias</i></td></tr>
<tr><td></td><td class="Optional">sunday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">monday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">tuesday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">wednesday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">thursday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">friday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td></td><td class="Optional">saturday</td><td class="Optional"><i>timeranges</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define timeperiod{
timeperiod_name nonworkhours
alias Non-Work Hours
sunday 00:00-24:00
monday 00:00-09:00,17:00-24:00
tuesday 00:00-09:00,17:00-24:00
wednesday 00:00-09:00,17:00-24:00
thursday 00:00-09:00,17:00-24:00
friday 00:00-09:00,17:00-24:00
saturday 00:00-24:00
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>timeperiod_name</strong>:</td>
<td>
This directives is the short name used to identify the time period.
</td>
</tr>
<tr>
<td valign="top"><strong>alias</strong>:</td>
<td>
This directive is a longer name or description used to identify the time period.
</td>
</tr>
<tr>
<td valign="top"><strong><i>some</i>day</strong>:</td>
<td>
The <i>sunday</i> through <i>saturday</i> directives are comma-delimited lists of time ranges that are "valid" times for a particular day of the week. Notice that there are seven different days for which you can define time ranges (Sunday through Saturday). Each time range is in the form of <b>HH:MM-HH:MM</b>, where hours are specified on a 24 hour clock. For example, <b>00:15-24:00</b> means 12:15am in the morning for this day until 12:20am midnight (a 23 hour, 45 minute total time range). If you wish to exclude an entire day from the timeperiod, simply do not include it in the timeperiod definition.
</td>
</tr>
</table>
</p>
<p>
<a name="command"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Command Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
A command definition is just that. It defines a command. Commands that can be defined include service checks, service notifications, service event handlers, host checks, host notifications, and host event handlers. Command definitions can contain <a href="macros.html">macros</a>, but you must make sure that you include only those macros that are "valid" for the circumstances when the command will be used. More information on what macros are available and when they are "valid" can be found <a href="macros.html">here</a>. The different arguments to a command definition are outlined below.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define command{</td></tr>
<tr><td></td><td class="Required">command_name</td><td class="Required"><i>command_name</i></td></tr>
<tr><td></td><td class="Required">command_line</td><td class="Required"><i>command_line</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define command{
command_name check_pop
command_line /usr/local/nagios/libexec/check_pop -H $HOSTADDRESS$
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>command_name</strong>:</td>
<td>
This directive is the short name used to identify the command. It is referenced in <a href="#contact">contact</a>, <a href="#host">host</a>, and <a href="#service">service</a> definitions (in notification, check, and event handler directives), among other places.
</td>
</tr>
<tr>
<td valign="top"><strong>command_line</strong>:</td>
<td>
<p>
This directive is used to define what is actually executed by Nagios when the command is used for service or host checks, notifications, or <a href="eventhandlers.html">event handlers</a>. Before the command line is executed, all valid <a href="macros.html">macros</a> are replaced with their respective values. See the documentation on macros for determining when you can use different macros. Note that the command line is <i>not</i> surrounded in quotes. Also, if you want to pass a dollar sign ($) on the command line, you have to escape it with another dollar sign.
</p>
<p><strong>NOTE</strong>: You may not include a <b>semicolon</b> (;) in the <i>command_line</i> directive, because everything after it will be ignored as a config file comment. You can work around this limitation by setting one of the <a href="macros.html#user"><b>$USER$</b> macros in your <a
href="configmain.html#resource_file">resource file</a> to a semicolon and then referencing the appropriate $USER$ macro in the <i>command_line</i> directive in place of the semicolon.
</p>
<p>
If you want to pass arguments to commands during runtime, you can use <a href="macros.html#arg"><b>$ARGn$</b> macros</a> in the <i>command_line</i> directive of the command definition and then seperate individual arguments from the command name (and from each other) using bang (!) characters in the object definition directive (host check command, service event handler command, etc) that references the command. More information on how arguments in command definitions are processed during runtime can be found in the documentation on <a href="macros.html">macros</a>.
</p>
</td>
</tr>
</table>
</p>
<p>
<a name="servicedependency"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Service Dependency Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p class="SectionBody">
Service dependencies are an advanced feature of Nagios that allow you to suppress notifications and active checks of services based on the status of one or more other services. Service dependencies are optional and are mainly targeted at advanced users who have complicated monitoring setups. More information on how service dependencies work (read this!) can be found <a href="dependencies.html">here</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional. However, you must supply at least one type of criteria for the definition to be of much use.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define servicedependency{</td></tr>
<tr><td></td><td class="Required">dependent_host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">dependent_service_description</td><td class="Required"><i>service_description</i></td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">service_description</td><td class="Required"><i>service_description</i></td></tr>
<tr><td></td><td class="Optional">inherits_parent</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">execution_failure_criteria</td><td class="Optional">[o,w,u,c,p,n]</td></tr>
<tr><td></td><td class="Optional">notification_failure_criteria</td><td class="Optional">[o,w,u,c,p,n]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define servicedependency{
host_name WWW1
service_description Apache Web Server
dependent_host_name WWW1
dependent_service_description Main Web Site
execution_failure_criteria n
notification_failure_criteria w,u,c
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>dependent_host</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#host">host</a> that the <i>dependent</i> service "runs" on or is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>dependent_service_description</strong>:</td>
<td>
This directive is used to identify the <i>description</i> of the <i>dependent</i> <a href="#service">service</a>.
</td>
</tr>
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#host">host</a> that the service <i>that is being depended upon</i> (also referred to as the master service) "runs" on or is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>service_description</strong>:</td>
<td>
This directive is used to identify the <i>description</i> of the <a href="#service">service</a> <i>that is being depended upon</i> (also referred to as the master service).
</td>
</tr>
<tr>
<td valign="top"><strong>inherits_parent</strong>:</td>
<td>
This directive indicates whether or not the dependency inherits dependencies of the service <i>that is being depended upon</i> (also referred to as the master service). In other words, if the master service is dependent upon other services and any one of those dependencies fail, this dependency will also fail.
</td>
</tr>
<tr>
<td valign="top"><strong>execution_failure_criteria</strong>:</td>
<td>
This directive is used to specify the criteria that determine when the dependent service should <i>not</i> be actively checked. If the <i>master</i> service is in one of the failure states we specify, the <i>dependent</i> service will not be actively checked. Valid options are a combination of one or more of the following (multiple options are seperated with commas): <b>o</b> = fail on an OK state, <b>w</b> = fail on a WARNING state, <b>u</b> = fail on an UNKNOWN state, <b>c</b> = fail on a CRITICAL state, and <b>p</b> = fail on a pending state (e.g. the service has not yet been checked). If you specify <b>n</b> (none) as an option, the execution dependency will never fail and checks of the dependent service will always be actively checked (if other conditions allow for it to be). Example: If you specify <b>o,c,u</b> in this field, the <i>dependent</i> service will not be actively checked if the <i>master</i> service is in either an OK, a CRITICAL, or an UNKNOWN state.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_failure_criteria</strong>:</td>
<td>
This directive is used to define the criteria that determine when notifications for the dependent service should <i>not</i> be sent out. If the <i>master</i> service is in one of the failure states we specify, notifications for the <i>dependent</i> service will not be sent to contacts. Valid options are a combination of one or more of the following: <b>o</b> = fail on an OK state, <b>w</b> = fail on a WARNING state, <b>u</b> = fail on an UNKNOWN state, <b>c</b> = fail on a CRITICAL state, and <b>p</b> = fail on a pending state (e.g. the service has not yet been checked). If you specify <b>n</b> (none) as an option, the notification dependency will never fail and notifications for the dependent service will always be sent out. Example: If you specify <b>w</b> in this field, the notifications for the <i>dependent</i> service will not be sent out if the <i>master</i> service is in a WARNING state.
</td>
</tr>
</table>
</p>
<p>
<a name="serviceescalation"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Service Escalation Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
Service escalations are <i>completely optional</i> and are used to escalate notifications for a particular service. More information on how notification escalations work can be found <a href="escalations.html">here</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define serviceescalation{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">service_description</td><td class="Required"><i>service_description</i></td></tr>
<tr><td></td><td class="Required">contact_groups</td><td class="Required"><i>contactgroup_name</i></td></tr>
<tr><td></td><td class="Required">first_notification</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">last_notification</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">notification_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Optional">escalation_period</td><td class="Optional">timeperiod_name</td></tr>
<tr><td></td><td class="Optional">escalation_options</td><td class="Optional">[w,u,c,r]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define serviceescalation{
host_name nt-3
service_description Processor Load
first_notification 4
last_notification 0
notification_interval 30
contact_groups all-nt-admins,themanagers
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#host">host</a> that the <a href="#service">service</a> the escalation should apply to is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>service_description</strong>:</td>
<td>
This directive is used to identify the <i>description</i> of the <a href="#service">service</a> the escalation should apply to.
</td>
</tr>
<tr>
<td valign="top"><strong>first_notification</strong>:</td>
<td>
This directive is a number that identifies the <i>first</i> notification for which this escalation is effective. For instance, if you set this value to 3, this escalation will only be used if the service is in a non-OK state long enough for a third notification to go out.
</td>
</tr>
<tr>
<td valign="top"><strong>last_notification</strong>:</td>
<td>
This directive is a number that identifies the <i>last</i> notification for which this escalation is effective. For instance, if you set this value to 5, this escalation will not be used if more than five notifications are sent out for the service. Setting this value to 0 means to keep using this escalation entry forever (no matter how many notifications go out).
</td>
</tr>
<tr>
<td valign="top"><strong>contact_groups</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#contactgroup">contact group</a> that should be notified when the service notification is escalated. Multiple contact groups should be separated by commas.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_interval</strong>:</td>
<td>
This directive is used to determine the interval at which notifications should be made while this escalation is valid. If you specify a value of 0 for the interval, Nagios will send the first notification when this escalation definition is valid, but will then prevent any more problem notifications from being sent out for the host. Notifications are sent out again until the host recovers. This is useful if you want to stop having notifications sent out after a certain amount of time. Note: If multiple escalation entries for a host overlap for one or more notification ranges, the smallest notification interval from all escalation entries is used.
</td>
</tr>
<tr>
<td valign="top"><strong>escalation_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which this escalation is valid. If this directive is not specified, the escalation is considered to be valid during all times.
</td>
</tr>
<tr>
<td valign="top"><strong>escalation_options</strong>:</td>
<td>
This directive is used to define the criteria that determine when this service escalation is used. The escalation is used only if the service is in one of the states specified in this directive. If this directive is not specified in a service escalation, the escalation is considered to be valid during all service states. Valid options are a combination of one or more of the following: <b>r</b> = escalate on an OK (recovery) state, <b>w</b> = escalate on a WARNING state, <b>u</b> = escalate on an UNKNOWN state, and <b>c</b> = escalate on a CRITICAL state. Example: If you specify <b>w</b> in this field, the escalation will only be used if the service is in a WARNING state.
</td>
</tr>
</table>
</p>
<p>
<a name="hostdependency"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Host Dependency Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p class="SectionBody">
Host dependencies are an advanced feature of Nagios that allow you to suppress notifications for hosts based on the status of one or more other hosts. Host dependencies are optional and are mainly targeted at advanced users who have complicated monitoring setups. More information on how host dependencies work (read this!) can be found <a href="dependencies.html">here</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define hostdependency{</td></tr>
<tr><td></td><td class="Required">dependent_host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Optional">inherits_parent</td><td class="Optional">[0/1]</td></tr>
<tr><td></td><td class="Optional">execution_failure_criteria</td><td class="Optional">[o,d,u,p,n]</td></tr>
<tr><td></td><td class="Optional">notification_failure_criteria</td><td class="Optional">[o,d,u,p,n]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define hostdependency{
host_name WWW1
dependent_host_name DBASE1
notification_failure_criteria d,u
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>dependent_host</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <i>dependent</i> <a href="#host">host</a>.
</td>
</tr>
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#host">host</a> <i>that is being depended upon</i> (also referred to as the master host).
</td>
</tr>
<tr>
<td valign="top"><strong>inherits_parent</strong>:</td>
<td>
This directive indicates whether or not the dependency inherits dependencies of the host <i>that is being depended upon</i> (also referred to as the master host). In other words, if the master host is dependent upon other hosts and any one of those dependencies fail, this dependency will also fail.
</td>
</tr>
<tr>
<td valign="top"><strong>execution_failure_criteria</strong>:</td>
<td>
This directive is used to specify the criteria that determine when the dependent host should <i>not</i> be actively checked. If the <i>master</i> host is in one of the failure states we specify, the <i>dependent</i> host will not be actively checked. Valid options are a combination of one or more of the following (multiple options are seperated with commas): <b>o</b> = fail on an UP state, <b>d</b> = fail on a DOWN state, <b>u</b> = fail on an UNREACHABLE state, and <b>p</b> = fail on a pending state (e.g. the host has not yet been checked). If you specify <b>n</b> (none) as an option, the execution dependency will never fail and the dependent host will always be actively checked (if other conditions allow for it to be). Example: If you specify <b>u,d</b> in this field, the <i>dependent</i> host will not be actively checked if the <i>master</i> host is in either an UNREACHABLE or DOWN state.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_failure_criteria</strong>:</td>
<td>
This directive is used to define the criteria that determine when notifications for the dependent host should <i>not</i> be sent out. If the <i>master</i> host is in one of the failure states we specify, notifications for the <i>dependent</i> host will not be sent to contacts. Valid options are a combination of one or more of the following: <b>o</b> = fail on an UP state, <b>d</b> = fail on a DOWN state, <b>u</b> = fail on an UNREACHABLE state, and <b>p</b> = fail on a pending state (e.g. the host has not yet been checked). If you specify <b>n</b> (none) as an option, the notification dependency will never fail and notifications for the dependent host will always be sent out. Example: If you specify <b>d</b> in this field, the notifications for the <i>dependent</i> host will not be sent out if the <i>master</i> host is in a DOWN state.
</td>
</tr>
</table>
</p>
<p>
<a name="hostescalation"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Host Escalation Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p>
Host escalations are <i>completely optional</i> and are used to escalate notifications for a particular host. More information on how notification escalations work can be found <a href="escalations.html">here</a>.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Directives in red are required, while those in black are optional.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define hostescalation{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Optional">hostgroup_name</td><td class="Optional"><i>hostgroup_name</i></td></tr>
<tr><td></td><td class="Required">contact_groups</td><td class="Required"><i>contactgroup_name</i></td></tr>
<tr><td></td><td class="Required">first_notification</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">last_notification</td><td class="Required">#</td></tr>
<tr><td></td><td class="Required">notification_interval</td><td class="Required">#</td></tr>
<tr><td></td><td class="Optional">escalation_period</td><td class="Optional">timeperiod_name</td></tr>
<tr><td></td><td class="Optional">escalation_options</td><td class="Optional">[d,u,r]</td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define hostescalation{
host_name router-34
first_notification 5
last_notification 8
notification_interval 60
contact_groups all-router-admins
}
</pre>
</p>
<p><div class="SectionTitle">Directive Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#host">host</a> that the escalation should apply to.
</td>
</tr>
<tr>
<td valign="top"><strong>hostgroup_name</strong>:</td>
<td>
This directive is used to identify the <i>short name(s)</i> of the <a href="#hostgroup">hostgroup(s)</a> that the escalation should apply to. Multiple hostgroups should are seperated by commas. If this is used, the escalation will apply to all hosts that are members of the specified hostgroup(s).
</td>
</tr>
<tr>
<td valign="top"><strong>first_notification</strong>:</td>
<td>
This directive is a number that identifies the <i>first</i> notification for which this escalation is effective. For instance, if you set this value to 3, this escalation will only be used if the host is down or unreachable long enough for a third notification to go out.
</td>
</tr>
<tr>
<td valign="top"><strong>last_notification</strong>:</td>
<td>
This directive is a number that identifies the <i>last</i> notification for which this escalation is effective. For instance, if you set this value to 5, this escalation will not be used if more than five notifications are sent out for the host. Setting this value to 0 means to keep using this escalation entry forever (no matter how many notifications go out).
</td>
</tr>
<tr>
<td valign="top"><strong>contact_groups</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the <a href="#contactgroup">contact group</a> that should be notified when the host notification is escalated. Multiple contact groups should be separated by commas.
</td>
</tr>
<tr>
<td valign="top"><strong>notification_interval</strong>:</td>
<td>
This directive is used to determine the interval at which notifications should be made while this escalation is valid. If you specify a value of 0 for the interval, Nagios will send the first notification when this escalation definition is valid, but will then prevent any more problem notifications from being sent out for the host. Notifications are sent out again until the host recovers. This is useful if you want to stop having notifications sent out after a certain amount of time. Note: If multiple escalation entries for a host overlap for one or more notification ranges, the smallest notification interval from all escalation entries is used.
</td>
</tr>
<tr>
<td valign="top"><strong>escalation_period</strong>:</td>
<td>
This directive is used to specify the short name of the <a href="#timeperiod">time period</a> during which this escalation is valid. If this directive is not specified, the escalation is considered to be valid during all times.
</td>
</tr>
<tr>
<td valign="top"><strong>escalation_options</strong>:</td>
<td>
This directive is used to define the criteria that determine when this host escalation is used. The escalation is used only if the host is in one of the states specified in this directive. If this directive is not specified in a host escalation, the escalation is considered to be valid during all host states. Valid options are a combination of one or more of the following: <b>r</b> = escalate on an UP (recovery) state, <b>d</b> = escalate on a DOWN state, and <b>u</b> = escalate on an UNREACHABLE state. Example: If you specify <b>d</b> in this field, the escalation will only be used if the host is in a DOWN state.
</td>
</tr>
</table>
</p>
<p>
<a name="hostextinfo"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Extended Host Information Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p class="SectionBody">
Extended host information entries are basically used to make the output from the <a href="cgis.html#status_cgi">status</a>, <a href="cgis.html#statusmap_cgi">statusmap</a>, <a href="cgis.html#statuswrl_cgi">statuswrl</a>, and <a href="cgis.html#extinfo_cgi">extinfo</a> CGIs look pretty. They have no effect on monitoring and are completely optional.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Variables in red are required, while those in black are optional. However, you need to supply at least one optional variable in each definition for it to be of much use.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define hostextinfo{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Optional">notes</td><td class="Optional"><i>note_string</i></td></tr>
<tr><td></td><td class="Optional">notes_url</td><td class="Optional"><i>url</i></td></tr>
<tr><td></td><td class="Optional">action_url</td><td class="Optional"><i>url</i></td></tr>
<tr><td></td><td class="Optional">icon_image</td><td class="Optional"><i>image_file</i></td></tr>
<tr><td></td><td class="Optional">icon_image_alt</td><td class="Optional"><i>alt_string</i></td></tr>
<tr><td></td><td class="Optional">vrml_image</td><td class="Optional"><i>image_file</i></td></tr>
<tr><td></td><td class="Optional">statusmap_image</td><td class="Optional"><i>image_file</i></td></tr>
<tr><td></td><td class="Optional">2d_coords</td><td class="Optional"><i>x_coord,y_coord</i></td></tr>
<tr><td></td><td class="Optional">3d_coords</td><td class="Optional"><i>x_coord,y_coord,z_coord</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define hostextinfo{
host_name netware1
notes This is the primary Netware file server
notes_url http://webserver.localhost.localdomain/hostinfo.pl?host=netware1
icon_image novell40.png
icon_image_alt IntranetWare 4.11
vrml_image novell40.png
statusmap_image novell40.gd2
2d_coords 100,250
3d_coords 100.0,50.0,75.0
}
</pre>
</p>
<p><div class="SectionTitle">Variable Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This variable is used to identify the <i>short name</i> of the <a href="#host">host</a> which the data is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>notes</strong>:</td>
<td>
This directive is used to define an optional string of notes pertaining to the host. If you specify a note here, you will see the it in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified host).
</td>
</tr>
<tr>
<td valign="top"><strong>notes_url</strong>:</td>
<td>
This variable is used to define an optional URL that can be used to provide more information about the host. If you specify an URL, you will see a link that says "Extra Host Notes" in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified host). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. <i>/cgi-bin/nagios/</i>). This can be very useful if you want to make detailed information on the host, emergency contact methods, etc. available to other support staff.
</td>
</tr>
<tr>
<td valign="top"><strong>action_url</strong>:</td>
<td>
This directive is used to define an optional URL that can be used to provide more actions to be performed on the host. If you specify an URL, you will see a link that says "Extra Host Actions" in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified host). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. <i>/cgi-bin/nagios/</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>icon_image</strong>:</td>
<td>
This variable is used to define the name of a GIF, PNG, or JPG image that should be associated with this host. This image will be displayed in the <a href="cgis.html#status_cgi">status</a> and <a href="cgis.html#extinfo_cgi">extended information</a> CGIs. The image will look best if it is 40x40 pixels in size. Images for hosts are assumed to be in the <b>logos/</b> subdirectory in your HTML images directory (i.e. <i>/usr/local/nagios/share/images/logos</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>icon_image_alt</strong>:</td>
<td>
This variable is used to define an optional string that is used in the ALT tag of the image specified by the <i><icon_image></i> argument. The ALT tag is used in the <a href="cgis.html#status_cgi">status</a>, <a href="cgis.html#extinfo_cgi">extended information</a> and <a href="cgis.html#statusmap_cgi">statusmap</a> CGIs.
</td>
</tr>
<tr>
<td valign="top"><strong>vrml_image</strong>:</td>
<td>
This variable is used to define the name of a GIF, PNG, or JPG image that should be associated with this host. This image will be used as the texture map for the specified host in the <a href="cgis.html#statuswrl_cgi">statuswrl</a> CGI. Unlike the image you use for the <i><icon_image></i> variable, this one should probably <i>not</i> have any transparency. If it does, the host object will look a bit wierd. Images for hosts are assumed to be in the <b>logos/</b> subdirectory in your HTML images directory (i.e. <i>/usr/local/nagios/share/images/logos</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>statusmap_image</strong>:</td>
<td>
This variable is used to define the name of an image that should be associated with this host in the <a href="cgis.html#statusmap_cgi">statusmap</a> CGI. You can specify a JPEG, PNG, and GIF image if you want, although I would strongly suggest using a GD2 format image, as other image formats will result in a lot of wasted CPU time when the statusmap image is generated. GD2 images can be created from PNG images by using the <b>pngtogd2</b> utility supplied with Thomas Boutell's <a href="http://www.boutell.com/gd/">gd library</a>. The GD2 images should be created in <i>uncompressed</i> format in order to minimize CPU load when the statusmap CGI is generating the network map image. The image will look best if it is 40x40 pixels in size. You can leave these option blank if you are not using the statusmap CGI. Images for hosts are assumed to be in the <b>logos/</b> subdirectory in your HTML images directory (i.e. <i>/usr/local/nagios/share/images/logos</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>2d_coords</strong>:</td>
<td>
This variable is used to define coordinates to use when drawing the host in the <a href="cgis.html#statusmap_cgi">statusmap</a> CGI. Coordinates should be given in positive integers, as the correspond to physical pixels in the generated image. The origin for drawing (0,0) is in the upper left hand corner of the image and extends in the positive x direction (to the right) along the top of the image and in the positive y direction (down) along the left hand side of the image. For reference, the size of the icons drawn is usually about 40x40 pixels (text takes a little extra space). The coordinates you specify here are for the upper left hand corner of the host icon that is drawn. Note: Don't worry about what the maximum x and y coordinates that you can use are. The CGI will automatically calculate the maximum dimensions of the image it creates based on the largest x and y coordinates you specify.
</td>
</tr>
<tr>
<td valign="top"><strong>3d_coords</strong>:</td>
<td>
This variable is used to define coordinates to use when drawing the host in the <a href="cgis.html#statuswrl_cgi">statuswrl</a> CGI. Coordinates can be positive or negative real numbers. The origin for drawing is (0.0,0.0,0.0). For reference, the size of the host cubes drawn is 0.5 units on each side (text takes a little more space). The coordinates you specify here are used as the center of the host cube.
</td>
</tr>
</table>
</p>
<p>
<a name="serviceextinfo"></a>
<table border="0" width="100%">
<tr>
<td class="SectionHeader">Extended Service Information Definition</td>
</tr>
</table>
</p>
<p><div class="SectionTitle">Description:</div></p>
<p class="SectionBody">
Extended service information entries are basically used to make the output from the <a href="cgis.html#status_cgi">status</a> and <a href="cgis.html#extinfo_cgi">extinfo</a> CGIs look pretty. They have no effect on monitoring and are completely optional.
</p>
<p><div class="SectionTitle">Definition Format:</div></p>
<p class="SectionBody">
Note: Variables in red are required, while those in black are optional. However, you need to supply at least one optional variable in each definition for it to be of much use.
</p>
<p>
<table border="0" class="Default">
<tr><td colspan=3 class="Definition">define serviceextinfo{</td></tr>
<tr><td></td><td class="Required">host_name</td><td class="Required"><i>host_name</i></td></tr>
<tr><td></td><td class="Required">service_description</td><td class="Required"><i>service_description</i></td></tr>
<tr><td></td><td class="Optional">notes</td><td class="Optional"><i>note_string</i></td></tr>
<tr><td></td><td class="Optional">notes_url</td><td class="Optional"><i>url</i></td></tr>
<tr><td></td><td class="Optional">action_url</td><td class="Optional"><i>url</i></td></tr>
<tr><td></td><td class="Optional">icon_image</td><td class="Optional"><i>image_file</i></td></tr>
<tr><td></td><td class="Optional">icon_image_alt</td><td class="Optional"><i>alt_string</i></td></tr>
<tr><td> </td><td colspan=2 class="Definition">}</td></tr>
</table>
</p>
<p><div class="SectionTitle">Example Definition:</div></p>
<p class="SectionBody">
<pre>
define serviceextinfo{
host_name linux2
service_description Log Anomalies
notes Security-related log anomalies on secondary Linux server
notes_url http://webserver.localhost.localdomain/serviceinfo.pl?host=linux2&service=Log+Anomalies
icon_image security.png
icon_image_alt Security-Related Alerts
}
</pre>
</p>
<p><div class="SectionTitle">Variable Descriptions:</div></p>
<p>
<table border="0" class="Default">
<tr>
<td valign="top"><strong>host_name</strong>:</td>
<td>
This directive is used to identify the <i>short name</i> of the host that the <a href="#service">service</a> is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>service_description</strong>:</td>
<td>
This directive is description of the <a href="#service">service</a> which the data is associated with.
</td>
</tr>
<tr>
<td valign="top"><strong>notes</strong>:</td>
<td>
This directive is used to define an optional string of notes pertaining to the service. If you specify a note here, you will see the it in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified service).
</td>
</tr>
<tr>
<td valign="top"><strong>notes_url</strong>:</td>
<td>
This directive is used to define an optional URL that can be used to provide more information about the service. If you specify an URL, you will see a link that says "Extra Service Notes" in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified service). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. <i>/cgi-bin/nagios/</i>). This can be very useful if you want to make detailed information on the service, emergency contact methods, etc. available to other support staff.
</td>
</tr>
<tr>
<td valign="top"><strong>action_url</strong>:</td>
<td>
This directive is used to define an optional URL that can be used to provide more actions to be performed on the service. If you specify an URL, you will see a link that says "Extra Service Actions" in the <a href="cgis.html#extinfo_cgi">extended information</a> CGI (when you are viewing information about the specified service). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. <i>/cgi-bin/nagios/</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>icon_image</strong>:</td>
<td>
This variable is used to define the name of a GIF, PNG, or JPG image that should be associated with this host. This image will be displayed in the <a href="cgis.html#status_cgi">status</a> and <a href="cgis.html#extinfo_cgi">extended information</a> CGIs. The image will look best if it is 40x40 pixels in size. Images for hosts are assumed to be in the <b>logos/</b> subdirectory in your HTML images directory (i.e. <i>/usr/local/nagios/share/images/logos</i>).
</td>
</tr>
<tr>
<td valign="top"><strong>icon_image_alt</strong>:</td>
<td>
This variable is used to define an optional string that is used in the ALT tag of the image specified by the <i><icon_image></i> argument. The ALT tag is used in the <a href="cgis.html#status_cgi">status</a>, <a href="cgis.html#extinfo_cgi">extended information</a> and <a href="cgis.html#statusmap_cgi">statusmap</a> CGIs.
</td>
</tr>
</table>
</p>
<hr>
</body>
</html>
|
