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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>3.5. Custom Object Variables</title>
<link rel="stylesheet" href="../stylesheets/icinga-docs.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<meta name="keywords" content="Supervision, Icinga, Nagios, Linux">
<link rel="home" href="index.html" title="Icinga Version 1.14 Documentation">
<link rel="up" href="ch03.html" title="Chapter 3. Configuring Icinga">
<link rel="prev" href="objectdefinitions.html" title="3.4. Object Definitions">
<link rel="next" href="configcgi.html" title="3.6. CGI Configuration File Options">
<script src="../js/jquery-min.js" type="text/javascript"></script><script src="../js/icinga-docs.js" type="text/javascript"></script>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<CENTER><IMG src="../images/logofullsize.png" border="0" alt="Icinga" title="Icinga"></CENTER>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">3.5. Custom Object Variables</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="objectdefinitions.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. Configuring Icinga</th>
<td width="20%" align="right"> <a accesskey="n" href="configcgi.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section" title="3.5. Custom Object Variables">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="customobjectvars"></a>3.5. <a name="custom_object_vars"></a>Custom Object Variables</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section">3.5.1. <a href="customobjectvars.html#introduction">Introduction</a></span></dt>
<dt><span class="section">3.5.2. <a href="customobjectvars.html#basicscustomvars">Custom Variable Basics</a></span></dt>
<dt><span class="section">3.5.3. <a href="customobjectvars.html#examples">Examples</a></span></dt>
<dt><span class="section">3.5.4. <a href="customobjectvars.html#customvarsasmacros">Custom Variables As Macros</a></span></dt>
<dt><span class="section">3.5.5. <a href="customobjectvars.html#inheritancecustomvars">Custom Variables And Inheritance</a></span></dt>
</dl></div>
<a class="indexterm" name="idm140381632942416"></a>
<div class="section" title="3.5.1. Introduction">
<div class="titlepage"><div><div><h3 class="title">
<a name="introduction"></a>3.5.1. Introduction</h3></div></div></div>
<p>Users often request that new variables be added to host, service, and contact definitions. These include variables for SNMP
community, MAC address, AIM username, Skype number, and street address. The list is endless. The problem is that it makes Icinga
less generic and more infrastructure-specific. Icinga was intended to be flexible, which meant things needed to be designed in a
generic manner. Host definitions in Icinga, for example, have a generic "address" variable that can contain anything from an IP
address to human-readable driving directions - whatever is appropriate for the user's setup.</p>
<p>Still, there needs to be a method for admins to store information about their infrastructure components in their Icinga
configuration without imposing a set of specific variables on others. Icinga attempts to solve this problem by allowing users to
define custom variables in their object definitions. Custom variables allow users to define additional properties in their host,
service, and contact definitions, and use their values in notifications, event handlers, and host and service checks.</p>
</div>
<div class="section" title="3.5.2. Custom Variable Basics">
<div class="titlepage"><div><div><h3 class="title">
<a name="basicscustomvars"></a>3.5.2. Custom Variable Basics</h3></div></div></div>
<p>There are a few important things that you should note about custom variables:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Custom variable names must begin with an underscore (_) to prevent name collision with standard variables</p>
</li>
<li class="listitem">
<p>Custom variable names are converted to all uppercase before use</p>
</li>
<li class="listitem">
<p>Custom variables are <a class="link" href="objectinheritance.html" title="7.26. Object Inheritance">inherited</a> from object templates like normal variables</p>
</li>
<li class="listitem">
<p>Scripts can reference custom variable values with <a class="link" href="macros.html" title="5.2. Understanding Macros and How They Work">macros and environment variables</a></p>
</li>
</ul></div>
<a name="customobjectvars-runtime"></a>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top">
<p>Custom variables are replaced <span class="emphasis"><em>during runtime</em></span>, neither during the verification phase (icinga -v icinga.cfg)
nor during the Icinga start up process so placing them in host names, service descriptions, and several other places of the
object definition will lead to an error message during verification like "<code class="literal"><object> contains one or more illegal
characters.</code>". Changing the directive "illegal_object_name_chars" will <span class="emphasis"><em>not</em></span> solve this issue.</p>
</td></tr>
</table></div>
<a class="indexterm" name="idm140381632927808"></a>
</div>
<div class="section" title="3.5.3. Examples">
<div class="titlepage"><div><div><h3 class="title">
<a name="examples"></a>3.5.3. Examples</h3></div></div></div>
<p>Here's an example of how custom variables can be defined in different types of object definitions:</p>
<pre class="programlisting">
define host{
host_name linuxserver
_mac_address 00:06:5B:A6:AD:AA ; <-- Custom MAC_ADDRESS variable
_rack_number R32 ; <-- Custom RACK_NUMBER variable
...
}
define service{
host_name linuxserver
description Memory Usage
_SNMP_community public ; <-- Custom SNMP_COMMUNITY variable
_TechContact Jane Doe ; <-- Custom TECHCONTACT variable
....
}
define contact{
contact_name john
_AIM_username john16 ; <-- Custom AIM_USERNAME variable
_YahooID john32 ; <-- Custom YAHOOID variable
...
}
</pre>
</div>
<div class="section" title="3.5.4. Custom Variables As Macros">
<div class="titlepage"><div><div><h3 class="title">
<a name="customvarsasmacros"></a>3.5.4. Custom Variables As Macros</h3></div></div></div>
<p>Custom variable values can be referenced in scripts and executables that Icinga runs for checks, notifications, etc. by
using <a class="link" href="macros.html" title="5.2. Understanding Macros and How They Work">macros</a> or environment variables.</p>
<p>In order to prevent name collision among custom variables from different object types, Icinga prepends "_HOST", "_SERVICE",
or "_CONTACT" to the beginning of custom host, service, or contact variables, respectively, in macro and environment variable names. The
table below shows the corresponding macro and environment variable names for the custom variables that were defined in the example
above.</p>
<div class="informaltable">
<table border="1">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td><p> <span class="bold"><strong>Object Type</strong></span> </p></td>
<td><p> <span class="bold"><strong>Variable Name</strong></span> </p></td>
<td><p> <span class="bold"><strong>Macro Name</strong></span> </p></td>
<td><p> <span class="bold"><strong>Environment Variable</strong></span> </p></td>
</tr>
<tr>
<td><p>Host</p></td>
<td><p>MAC_ADDRESS</p></td>
<td><p>$_HOSTMAC_ADDRESS$</p></td>
<td><p>ICINGA__HOSTMAC_ADDRESS</p></td>
</tr>
<tr>
<td><p>Host</p></td>
<td><p>RACK_NUMBER</p></td>
<td><p>$_HOSTRACK_NUMBER$</p></td>
<td><p>ICINGA__HOSTRACK_NUMBER</p></td>
</tr>
<tr>
<td><p>Service</p></td>
<td><p>SNMP_COMMUNITY</p></td>
<td><p>$_SERVICESNMP_COMMUNITY$</p></td>
<td><p>ICINGA__SERVICESNMP_COMMUNITY</p></td>
</tr>
<tr>
<td><p>Service</p></td>
<td><p>TECHCONTACT</p></td>
<td><p>$_SERVICETECHCONTACT$</p></td>
<td><p>ICINGA__SERVICETECHCONTACT</p></td>
</tr>
<tr>
<td><p>Contact</p></td>
<td><p>AIM_USERNAME</p></td>
<td><p>$_CONTACTAIM_USERNAME$</p></td>
<td><p>ICINGA__CONTACTAIM_USERNAME</p></td>
</tr>
<tr>
<td><p>Contact</p></td>
<td><p>YAHOOID</p></td>
<td><p>$_CONTACTYAHOOID$</p></td>
<td><p>ICINGA__CONTACTYAHOOID</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" title="3.5.5. Custom Variables And Inheritance">
<div class="titlepage"><div><div><h3 class="title">
<a name="inheritancecustomvars"></a>3.5.5. Custom Variables And Inheritance</h3></div></div></div>
<p>Custom object variables are <a class="link" href="objectinheritance.html" title="7.26. Object Inheritance">inherited</a> just like standard host, service, or contact
variables.</p>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="objectdefinitions.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="configcgi.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">3.4. Object Definitions </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 3.6. CGI Configuration File Options</td>
</tr>
</table>
</div>
<P class="copyright">© 1999-2009 Ethan Galstad, 2009-2017 Icinga Development Team, https://www.icinga.com</P>
</body>
</html>
|
