Back to the main page

Create man page


Man command runs the groff command. The groff is a text formatter that reads groff macros in a file and outputs a formatted file. These macros always start with a dot (.) followed by the macro name, and its parameters.

.TH macro for TITLE HEADER

.TH [name of program] [section number] [center footer] [left footer] [center header]

Manual pages are kept in sections.


.SH [section name]


The macro for bold is .B and the macro for italics is .I


Comments are prefixed with ."


Simple paragraphing is done with the .PP macro

The example, man for program that adds a system to Nagios

Program (shell script) name is addtonagios , so this is the file addtonagios.1
.TH addtonagios 1 "June 2017" "ver 1" "User commands"


addtonagios - script for adding a system to CA Sysadmin's Nagios


." I want addtonagios to be bold

.B addtonagios
-h < FQDN > -r < s|i > [-t system_type] -H  [-n notification_template] [-a alias/description]


This script only adds a system to Nagios. By default, Nagios pings a system to see if it's alive.
No other service except ping is configured by the script.

You must be a root to run the script.

The script can be run in non-interactive or interactive mode.
For the non-interactive mode, you need to know all required arguments. If you don't know them,
then use the interactive mode and you'll be asked questions and offered a choices to select from.

The first mandatory argument (-h) is a system's hostname, and since there is domain like,
it's recommended using a FQDN, although no error is reported if a short name is used. The script
checks if there is a DNS A record for a system and exits if it can't find it.

The second mandatory argument (-r) is to select how the script is run. The "s" is no non-interactive and
the "i" is for interactive.

For the INTERACTIVE mode (i), all you need are these two arguments, then you'll be asked questions for more info.
The script helps you by presenting current Nagios system types, hostgroups and notification templates, so
there is no problem if you don't know this info in advance. The script also offeres some default values, and you
go for them by pressing the ENTER. The -a can be used for CNAME or some description or safely omitted.
No error will be reported if arguments for system type, hostgroup, notification template and alias are used,
but they be all overwritten by new selections during interacive run.

For the NON-INTERACTIVE mode (s), you'll need to enter the third mandatory argument, which is a hostgroup system belongs to.
Only one hostgroup is supported. If you believe there is need for a new Nagios hostgroup, file a bug at sysadmins' bugzilla.
If a system type and notification template are omitted, the default values will be used.
The -a can be used for CNAME or some description or safely omitted.

The script also determines a systems parent, which is a default gateway. It's not supported for a parent to be a host of a VM. 
The default gateway is determined by calling the external script (place to add a support for new subnets).

Once new system is added, the script verifes Nagios configuration, and if all is well, the nagios service is reloaded.

And finally, the new configuraiton file is added under git control (to staging), commited to the local repo and pushed
to the remote one on ca-sa-repo. The remote repo will read that this commit is done by user Octocat.


A system's hostname, recommened FQDN

Run mode for the script, "s" for non-interactive and "i" for interactive

A system's Nagios type, this type defines check and notification intervals and other options. 
The types definitions are in the file /etc/nagios/objects/host-check-templates.cfg

Nagios hostgroup, defined in the file /etc/nagios/hostgroups/hostgroups.cfg

Notification template,defined in the file /etc/nagios/objects/notification-templates.cfg

A system's CNAME or a description


The example 1:

.B addtonagios -h -r s -H xsigo

This example shows adding the system using non-interactive mode. The system belongs to the xsigo
hostgroup. Since system's type and notification template is not provided, the default values will be used.

The example 2:

.B addtonagios -h ca-xen-admin2-vlan351 -r s -H prod_servers -n nt_sa -a "vlan351 interface for ca-xen-admin2"

This example shows adding the system ca-xen-admin2-vlan351 using non-interactive mode. Here the description and notification
template are provided and since there is no system's type, the script will use the default value.

The example 3:

.B addtonagios -h -r i

This example shows adding the system using interactive mode, hostgroup and other optional arguments
will be added when script asks you.


None, this is totally free software, feel free to use and improve it.


None, use on your own risk.


Please report any at


Created by Zarko Dudic at Company



Back to the main page