Skip to content

Commit

Permalink
Migrate macros
Browse files Browse the repository at this point in the history 
Signed-off-by: nook24 <[email protected]>
  • Loading branch information
@nook24
nook24 committed Dec 21, 2024
1 parent be9fdbe commit 1e33ddf
Show file tree
Hide file tree
Showing 4 changed files with 118 additions and 76 deletions.
2 changes: 1 addition & 1 deletion .vitepress/config.mts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ export default defineConfig({
{ text: 'CGI Configuration File Options', link: '/documentation/usersguide/configcgi' },
{ text: 'Authentication And Authorization CGIs', link: '/documentation/usersguide/cgiauth' },
{ text: 'Plugins', link: '/documentation/usersguide/plugins' },

{ text: 'Macros', link: '/documentation/usersguide/macros' },
{ text: 'Naemon Logo', link: '/logo' }
]
},
Expand Down
8 changes: 4 additions & 4 deletions .vitepress/theme/naemon.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@

--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(-45deg, #4FC3F7 50%, var(--vp-c-brand-1));
--vp-home-hero-image-background-image: linear-gradient(45deg, var(--vp-c-brand-2) 50%, var(--vp-c-brand-1) 50%);

--vp-home-hero-image-background-image: linear-gradient(45deg, var(--vp-c-brand-2) 50%, var(--vp-c-brand-1) 50%);
--vp-home-hero-image-filter: blur(68px);

--red-light: #D73A49;
Expand All @@ -23,11 +23,11 @@
}

.text-red {
color: var(--red-light);
color: var(--red-light) !important;
}

.dark .text-red {
color: var(--red-dark);
color: var(--red-dark) !important;
}

/* Adds a background color to images to be better visible */
Expand Down
182 changes: 112 additions & 70 deletions legacy/documentation/usersguide/macros.md → src/documentation/usersguide/macros.md
View file
Original file line number Diff line number Diff line change
@@ -1,55 +1,60 @@
---
layout: doctoc
title: Understanding Macros and How They Work
---
# Understanding Macros and How They Work

<span class="glyphicon glyphicon-arrow-right"></span> See Also: <a href="macrolist.html">List of Available Macros</a>



### Macros
## Macros

One of the main features that make Naemon so flexible is the ability to use macros in command
definitions. Macros allow you to reference information from hosts, services, and other sources in your commands.



### Macro Substitution - How Macros Work
## Macro Substitution - How Macros Work

Before Naemon executes a command, it will replace any macros it finds in the command definition
with their corresponding values. This macro substitution occurs for all types of commands
that Naemon executes - host and service checks, notifications, event handlers, etc.

Certain macros may themselves contain other macros.
These include the $HOSTNOTES$, $HOSTNOTESURL$, $HOSTACTIONURL$, $SERVICENOTES$, $SERVICENOTESURL$, and $SERVICEACTIONURL$ macros.
These include the `$HOSTNOTES$`, `$HOSTNOTESURL$`, `$HOSTACTIONURL$`, `$SERVICENOTES$`, `$SERVICENOTESURL$`, and `$SERVICEACTIONURL$` macros.



### Example 1: Host Address Macro
## Example 1: Host Address Macro

When you use host and service macros in command definitions, they refer to values for the host or service
for which the command is being run. Let's try an example.
Assuming we are using a host definition and a <i>check_ping</i> command defined like this:
Assuming we are using a host definition and a `check_ping` command defined like this:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
define host {
host_name linuxbox
address <font color="red">192.168.1.2</font>
address <span class="text-red">192.168.1.2</span>
check_command check_ping
...
}
</code>

<code>
define command {
command_name check_ping
command_line /usr/lib/naemon/plugins/check_ping -H <font color="red">$HOSTADDRESS$</font> -w 100.0,90% -c 200.0,60%
command_line /usr/lib/naemon/plugins/check_ping -H <span class="text-red">$HOSTADDRESS$</span> -w 100.0,90% -c 200.0,60%
}
</code>
</pre>
</div>

the expanded/final command line to be executed for the host's check command would look like this:

<pre>
/usr/lib/naemon/plugins/check_ping -H <font color="red">192.168.1.2</font> -w 100.0,90% -c 200.0,60%
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
/usr/lib/naemon/plugins/check_ping -H <span class="text-red">192.168.1.2</span> -w 100.0,90% -c 200.0,60%
</code>
</pre>
</div>


Pretty simple, right?
The beauty in this is that you can use a single command definition to check an unlimited
Expand All @@ -58,50 +63,65 @@ host's address is automatically substituted in the command line before execution



### Example 2: Command Argument Macros
## Example 2: Command Argument Macros

You can pass arguments to commands as well, which is quite handy if you'd like to keep
your command definitions rather generic. Arguments are specified in the object
(i.e. host or service) definition, by separating them from the command name with
exclamation points (!) like so:
exclamation points (`!`) like so:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
define service {
host_name linuxbox
service_description PING
check_command check_ping!<font color="red">200.0,80%</font>!<font color="red">400.0,40%</font>
check_command check_ping!<span class="text-red">200.0,80%</span>!<span class="text-red">400.0,40%</span>
...
}
</code>
</pre>
</div>


In the example above, the service check command has two arguments (which can be referenced
with <a href="macrolist.html#arg">$ARGn$</a> macros). The $ARG1$ macro will be
"<font color="red">200.0,80%</font>" and $ARG2$ will be "<font color="red">400.0,40%</font>"
with [`$ARGn$`](macrolist#arg) macros). The `$ARG1$` macro will be
"<span class="text-red">200.0,80%</span>" and `$ARG2$` will be "<span class="text-red">400.0,40%</span>"
(both without quotes). Assuming we are using the host definition given
earlier and a <i>check_ping</i> command defined like this:
earlier and a `check_ping` command defined like this:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
define command {
command_name check_ping
command_line /usr/lib/naemon/plugins/check_ping -H <font color="red">$HOSTADDRESS$</font> -w <font color="red">$ARG1$</font> -c <font color="red">$ARG2$</font>
command_line /usr/lib/naemon/plugins/check_ping -H <span class="text-red">$HOSTADDRESS$</span> -w <span class="text-red">$ARG1$</span> -c <span class="text-red">$ARG2$</span>
}
</code>
</pre>
</div>


the expanded/final command line to be executed for the service's check command would look like this:

<pre>
/usr/lib/naemon/plugins/check_ping -H <font color="red">192.168.1.2</font> -w <font color="red">200.0,80%</font> -c <font color="red">400.0,40%</font>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
/usr/lib/naemon/plugins/check_ping -H <span class="text-red">192.168.1.2</span> -w <span class="text-red">200.0,80%</span> -c <span class="text-red">400.0,40%</span>
</code>
</pre>
</div>

{{ site.hint }}If you need to pass bang (!) characters in your command arguments, you can do so by escaping them with a backslash (\).{{ site.end }}
> [!TIP]
> If you need to pass bang (`!`) characters in your command arguments, you can do so by escaping them with a backslash (`\`).
If you need to include backslashes in your command arguments, they should also be escaped with a backslash.

### On-Demand Macros
## On-Demand Macros

Normally when you use host and service macros in command definitions, they refer to values
for the host or service for which the command is being run. For instance, if a host
check command is being executed for a host named "linuxbox", all the <a href="macrolist.html">standard host macros</a> will
check command is being executed for a host named "linuxbox", all the [standard host macros](macrolist) will
refer to values for that host ("linuxbox").

If you would like to reference values for another host or service in a command (for which the command is
Expand All @@ -115,34 +135,43 @@ they should get their value. Here's the basic format for on-demand macros:
</ul>

Replace <i>HOSTMACRONAME</i> and <i>SERVICEMACRONAME</i> with the name of one of the standard host
of service macros found <a href="macrolist.html">here</a>.
of service macros found [here](macrolist).

Note that the macro name is separated from the host or service identifier by a colon (:).
For on-demand service macros, the service identifier consists of both a host name and a
service description - these are separated by a colon (:) as well.

{{ site.hint }}On-demand service macros can contain an empty host name field. In this case the name of the host associated with the service will automatically be used.{{ site.end }}
> [!TIP]
> On-demand service macros can contain an empty host name field. In this case the name of the host associated with the service will automatically be used.
Examples of on-demand host and service macros follow:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
$HOSTDOWNTIME:myhost$ <--- On-demand host macro
$SERVICESTATEID:novellserver:DS Database$ <--- On-demand service macro
$SERVICESTATEID::CPU Load$ <--- On-demand service macro with blank host name field
</code>
</pre>
</div>

On-demand macros are also available for hostgroup, servicegroup, contact, and contactgroup macros. For example:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
$CONTACTEMAIL:john$ <--- On-demand contact macro
$CONTACTGROUPMEMBERS:linux-admins$ <--- On-demand contactgroup macro
$HOSTGROUPALIAS:linux-servers$ <--- On-demand hostgroup macro
$SERVICEGROUPALIAS:DNS-Cluster$ <--- On-demand servicegroup macro
</code>
</pre>
</div>



### On-Demand Group Macros
## On-Demand Group Macros

You can obtain the values of a macro across all contacts, hosts, or services
in a specific group by using a special format for your on-demand macro declaration.
Expand All @@ -156,76 +185,85 @@ in an on-demand macro, like so:
</ul>

Replace <i>HOSTMACRONAME</i>, <i>SERVICEMACRONAME</i>, and <i>CONTACTMACRONAME</i> with
the name of one of the standard host, service, or contact macros found <a href="macrolist.html">here</a>.
the name of one of the standard host, service, or contact macros found [here](macrolist).
The delimiter you specify is used to separate macro values for each group member.

For example, the following macro will return a comma-separated list of host state ids for hosts
that are members of the <i>hg1</i> hostgroup:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
$HOSTSTATEID:hg1:,$
</code>
</pre>
</div>

This macro definition will return something that looks like this:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
0,2,1,1,0,0,2
</code>
</pre>
</div>



### Custom Variable Macros
## Custom Variable Macros

Any <a href="customobjectvars.html">custom object variables</a> that you define in host,
Any [custom object variables](customobjectvars) that you define in host,
service, or contact definitions are also available as macros. Custom variable macros are named as follows:

<ul>
<li>$_HOST<i>varname</i>$</li>
<li>$_SERVICE<i>varname</i>$</li>
<li>$_CONTACT<i>varname</i>$</li>
</ul>
- `$_HOSTvarname$`
- `$_SERVICEvarname$`
- `$_CONTACTvarname$`


Take the following host definition with a custom variable called `_MACADDRESS`...

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
define host {
host_name linuxbox
address 192.168.1.1
<font color="red">_MACADDRESS 00:01:02:03:04:05</font>
<span class="text-red">_MACADDRESS 00:01:02:03:04:05</span>
...
}
</code>
</pre>
</div>

The `_MACADDRESS` custom variable would be available in a macro called <font color="red">`$_HOSTMACADDRESS$`</font>.
More information on custom object variables and how they can be used in macros can be found <a href="customobjectvars.html">here</a>.
The `_MACADDRESS` custom variable would be available in a macro called <span class="text-red">`$_HOSTMACADDRESS$`</span>.
More information on custom object variables and how they can be used in macros can be found [here](customobjectvars).



### Macro Cleansing
## Macro Cleansing

Some macros are stripped of potentially dangerous shell metacharacters before being substituted into commands to be executed.
Which characters are stripped from the macros depends on the setting of
the <a href="configmain.html#illegal_macro_output_chars">`illegal_macro_output_chars`</a> directive.
the [`illegal_macro_output_chars`](configmain#illegal_macro_output_chars) directive.
The following macros are stripped of potentially dangerous characters:

<ol>
<li><a href="macrolist.html#hostoutput">$HOSTOUTPUT$</a></li>
<li><a href="macrolist.html#longhostoutput">$LONGHOSTOUTPUT$</a></li>
<li><a href="macrolist.html#hostperfdata">$HOSTPERFDATA$</a></li>
<li><a href="macrolist.html#hostackauthor">$HOSTACKAUTHOR$</a></li>
<li><a href="macrolist.html#hostackcomment">$HOSTACKCOMMENT$</a></li>
<li><a href="macrolist.html#serviceoutput">$SERVICEOUTPUT$</a></li>
<li><a href="macrolist.html#longserviceoutput">$LONGSERVICEOUTPUT$</a></li>
<li><a href="macrolist.html#serviceperfdata">$SERVICEPERFDATA$</a></li>
<li><a href="macrolist.html#serviceackauthor">$SERVICEACKAUTHOR$</a></li>
<li><a href="macrolist.html#serviceackcomment">$SERVICEACKCOMMENT$</a></li>
</ol>
1. [`$HOSTOUTPUT$`](macrolist#hostoutput)
2. [`$LONGHOSTOUTPUT$`](macrolist#longhostoutput)
3. [`$HOSTPERFDATA$`](macrolist#hostperfdata)
4. [`$HOSTACKAUTHOR$`](macrolist#hostackauthor)
5. [`$HOSTACKCOMMENT$`](macrolist#hostackcomment)
6. [`$SERVICEOUTPUT$`](macrolist#serviceoutput)
7. [`$LONGSERVICEOUTPUT$`](macrolist#longserviceoutput)
8. [`$SERVICEPERFDATA$`](macrolist#serviceperfdata)
9. [`$SERVICEACKAUTHOR$`](macrolist#serviceackauthor)
10. [`$SERVICEACKCOMMENT$`](macrolist#serviceackcomment)

Additionally, any macros that contain <a href="customobjectvars.html">custom variables</a> are stripped for safety and security.
Additionally, any macros that contain [custom variables](customobjectvars) are stripped for safety and security.



### Macros as Environment Variables
## Macros as Environment Variables

Since Naemon macros are no longer available in the environment for performance reasons. Its
a huge waste of resources to calculate all macros all the time even if they are not used.
Expand All @@ -235,18 +273,22 @@ can edit your command to export specific macros.

Example notification command:

<pre>
<div class="language- vp-adaptive-theme">
<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0">
<code>
define command {
command_name my_old_notification_script
command_line <font color="red">NAGIOS_HOSTNAME="$HOSTNAME$"</font> /usr/local/bin/notifiy.pl ...
command_line <span class="text-red">NAGIOS_HOSTNAME="$HOSTNAME$"</span> /usr/local/bin/notifiy.pl ...
}
</code>
</pre>
</div>

This way you can define whatever environment macro you need and only those are calculated on runtime.



### Available Macros
## Available Macros

A list of all the macros that are available in Naemon, as well as
a chart of when they can be used, can be found <a href="macrolist.html">here</a>.
a chart of when they can be used, can be found [here](macrolist).
2 changes: 1 addition & 1 deletion src/documentation/usersguide/toc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@

[Plugins](plugins) :white_check_mark:

[Macros and how they work](macros)
[Macros and how they work](macros) :white_check_mark:

[Standard macros available in Naemon](macrolist)

Expand Down

0 comments on commit 1e33ddf

Please sign in to comment.