Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HOSTS.CFG(5)		      File Formats Manual		  HOSTS.CFG(5)

NAME
       hosts.cfg - Main	Xymon configuration file

SYNOPSIS
       hosts.cfg

DESCRIPTION
       The  hosts.cfg(5) file is the most important configuration file for all
       of the Xymon programs.  This file contains the full  list  of  all  the
       systems	monitored  by Xymon, including the set of tests	and other con-
       figuration items	stored for each	host.

FILE FORMAT
       Each line of the	file defines a host. Blank lines  and  lines  starting
       with  a	hash mark (#) are treated as comments and ignored.  Long lines
       can be broken up	by putting a backslash at the end of the line and con-
       tinuing the entry on the	next line.

       The format of an	entry in the hosts.cfg file is as follows:
	  IP-address hostname #	tag1 tag2 ...

       The  IP-address	and  hostname  are  mandatory; all of the tags are op-
       tional.	Listing	a host with only IP-address and	hostname will cause  a
       network test to be executed for the host	- the connectivity test	is en-
       abled by	default, but no	other tests.

       The optional tags are then used to define which tests are relevant  for
       the  host, and also to set e.g. the time-interval used for availability
       reporting by xymongen(1)

       An example of setting up	the hosts.cfg file is  in  the	Xymon  on-line
       documentation  (from  the  Help menu, choose "Configuring Monitoring").
       The following describes the possible settings in	a hosts.cfg file  sup-
       ported by Xymon.

TAGS RECOGNIZED	BY ALL TOOLS
       include filename
	      This tag is used to include another file into the	hosts.cfg file
	      at run-time, allowing for	a large	hosts.cfg file to be split  up
	      into more	manageable pieces.

	      The  "filename"  argument	 should	 point to a file that uses the
	      same syntax as hosts.cfg.	The filename can be an absolute	 file-
	      name  (if	 it begins with	a '/'),	or a relative filename - rela-
	      tive file	names are prefixed with	the directory where  the  main
	      hosts.cfg	file is	located	(usually $XYMONHOME/etc/).

	      You can nest include tags, i.e. a	file that is included from the
	      main hosts.cfg file can itself include other files.

       dispinclude filename
	      Acts like	the "include" tag, but only  for  the  xymongen	 tool.
	      Can  be used e.g.	to put a group of hosts	on multiple sub-pages,
	      without having to	repeat the host	definitions.

       netinclude filename
	      Acts like	the "include" tag, but only for	the xymonnet tool.

       directory directoryname
	      This tag is used to include all files in	the  named  directory.
	      Files  are included in alphabetical order. If there are sub- di-
	      rectories, these are recursively included	 also.	The  following
	      files  are  ignored: Files that begin with a dot,	files that end
	      with a tilde, RCS	files that end with ",v", RPM package  manager
	      files  ending  in	 ".rpmsave" or ".rpmnew", DPKG package manager
	      files ending in ".dpkg-new" or  ".dpkg-orig",  and  all  special
	      files (devices, sockets, pipes etc).

       optional	include/directory
	      Both "include" and "directory" can be prefixed with the tag "op-
	      tional", which will preven an error message being	logged if  the
	      file or directory	is not present on a system.

GENERAL	PER-HOST OPTIONS
       noclear
	      Controls whether stale status messages go	purple or clear	when a
	      host is down. Normally, when a host is down the client  statuses
	      ("cpu",  "disk",	"memory"  etc) will stop updating - this would
	      usually make them	go "purple" which can trigger alerts. To avoid
	      that, Xymon checks if the	"conn" test has	failed,	and if that is
	      true then	the other tests	will go	"clear"	instead	of  purple  so
	      you  only	 get  alerts  for  the "conn" test. If you do want the
	      stale statuses to	go purple, you can use the  "noclear"  tag  to
	      override this behaviour.

	      Note that	"noclear" also affects the behaviour of	network	tests;
	      see below.

       prefer When a single host is defined multiple  time  in	the  hosts.cfg
	      file,  xymongen  tries  to guess which definition	is the best to
	      use for the information used on the "info" column,  or  for  the
	      NOPROPRED	and other xymongen-specific settings. Host definitions
	      that have	a "noconn" tag or an IP	of 0.0.0.0 get lower priority.

	      By using the "prefer" tag	you tell xymongen that this host defi-
	      nition should be used.

	      Note: This only applies to hosts that are	defined	multiple times
	      in the hosts.cfg file, although it will not hurt to  add	it  on
	      other hosts as well.

       multihomed
	      Tell  Xymon that data from the host can arrive from multiple IP-
	      addresses.  By default, Xymon will warn if it sees data for  one
	      host  coming  from  different IP-addresses, because this usually
	      indicates	a mis-configuration of the hostname on at least	one of
	      the  servers involved. Some hosts	with multiple IP-addresses may
	      use different IP's for sending data to Xymon, however. This  tag
	      disables the check of source IP when receiving data.

       delayred=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...]
	      Usually,	status changes happen immediately. This	tag is used to
	      defer an update to red for the  STATUSCOLUMN  status  for	 DELAY
	      minutes.	E.g.   with delayred=disk:10,cpu:30, a red disk-status
	      will not appear on the Xymon webpages until it has been red  for
	      at  least	 10 minutes.  Note: Since most tests only execute once
	      every 5 minutes, it will usually not make	sense to set N to any-
	      thing but	a multiple of 5. The exception is network tests, since
	      xymonnet-again.sh(1) will	re-run failed  network	tests  once  a
	      minute for up to 30 minutes.

       delayyellow=STATUSCOLUMN:DELAY[,STATUSCOLUMN:DELAY...]
	      Same as delayred,	but defers the change to a yellow status.

XYMONGEN DISPLAY OPTIONS
       These  tags  are	 processed by the xymongen(1) tool when	generating the
       Xymon webpages or reports.

       page NAME [Page-title]
	      This defines a page at the level below the entry page. All hosts
	      following	 the "page" directive appear on	this page, until a new
	      "page", "subpage"	or "subparent" line is found.

       subpage NAME [Page-title]
	      This defines a sub-page in the  second  level  below  the	 entry
	      page.   You  must	 have a	previous "page"	line to	hook this sub-
	      page to.

       subparent parentpage newpage [Page-title]
	      This is used to define sub-pages	in  whatever  levels  you  may
	      wish.  Just like the standard "subpage" tag, "subparent" defines
	      a	new Xymon web page; however with  "subparent"  you  explicitly
	      list  which page it should go as a sub-page to. You can pick any
	      page as the parent - pages, sub-pages or	even  other  subparent
	      pages.  So this allows you to define any tree structure of pages
	      that you like.

	      E.g. with	this in	hosts.cfg:

		 page USA United States
		 subpage NY New	York
		 subparent NY manhattan	Manhattan data centers
		 subparent manhattan wallstreet	Wall Street center

	      you get this hierarchy of	pages:

		 USA (United States)
		   NY (New York)
		     manhattan (Manhattan data centers)
			wallstreet (Wall Street	center)

	      Note: The	parent page must be defined before you define the sub-
	      parent.  If  not,	 the page will not be generated, and you get a
	      message in the log file.

	      Note: xymongen is	case-sensitive,	when trying to match the  name
	      of the parent page.

	      The  inspiration for this	came from Craig	Cook's mkbb.pl script,
	      and I am grateful	to Craig for suggesting	that I implement it in
	      xymongen.	 The  idea  to	explicitly list	the parent page	in the
	      "subparent" tag was what made it easy to implement.

       vpage

       vsubpage

       vsubparent
	      These are	page-definitions similar to the	"page",	"subpage"  and
	      "subparent"  definitions.	 However,  on these pages the rows are
	      the tests, and the columns are the hosts (normal pages  have  it
	      the  other  way around). This is useful if you have a very large
	      number of	tests for a few	hosts, and prefer to have them	listed
	      on a page	that can be scrolled vertically.
	      Note  that  the "group" directives have no effect	on these types
	      of pages.

       group [group-title]

       group-compress [group-title]
	      Defines a	group of hosts,	that appear together on	the web	 page,
	      with a single header-line	listing	all of the columns. Hosts fol-
	      lowing the "group" line appear inside the	 group,	 until	a  new
	      "group" or page-line is found. The two group-directives are han-
	      dled identically by Xymon	and xymongen, but both forms  are  al-
	      lowed for	backwards compatibility.

       group-sorted [group-title]
	      Same  as	the  "group"  line, but	will sort the hosts inside the
	      group so they appear in strict lexicographic order.

       group-only COLUMN1|COLUMN2|COLUMN3 [group-title]
	      Same as the "group" and  "group-compress"	 lines,	 but  includes
	      only the columns explicitly listed in the	group. Any columns not
	      listed will be ignored for these hosts.

       group-except COLUMN1|COLUMN2|COLUMN3 [group-title]
	      Same as the "group-only" lines, but includes all columns	EXCEPT
	      those explicitly listed in the group. Any	columns	listed will be
	      ignored for these	hosts -	all other columns are shown.

       title Page, group or host title text
	      The "title" tag is used to put custom headings  into  the	 pages
	      generated	by xymongen, in	front of page/subpage links, groups or
	      hosts.

	      The title	tag operates on	the next item in  the  hosts.cfg  file
	      following	the title tag.

	      If  a  title  tag	precedes a host	entry, the title is shown just
	      before the host is listed	on the status page. The	 column	 head-
	      ings  present for	the host will be repeated just after the head-
	      ing.

	      If a title tag precedes a	group entry, the title	is  show  just
	      before the group on the status page.

	      If  a title tag precedes a page/subpage/subparent	entry, the ti-
	      tle text replaces	the normal "Pages hosted locally" heading nor-
	      mally  inserted by Xymon.	This appears on	the page that links to
	      the sub-pages, not on the	sub-page itself. To get	a custom head-
	      ing  on  the sub-page, you may want to use the "--pagetext-head-
	      ing" when	running	xymongen(1)

       NAME:hostname
	      Overrides	the default hostname used on the overview  web	pages.
	      If  "hostname"  contains	spaces,	 it must be enclosed in	double
	      quotes, e.g. NAME:"R&D Oracle Server"

       CLIENT:hostname
	      Defines an alias for a host, which will be used when identifying
	      status  messages.	 This is typically used	to accommodate a local
	      client that sends	in status reports with a  different  hostname,
	      e.g.  if you use hostnames with domains in your Xymon configura-
	      tion, but	the client is a	silly Window box that does not include
	      the  hostname.  Or  vice-versa. Whatever the reason, this	can be
	      used to match status reports with	the hosts you define  in  your
	      hosts.cfg	file. It causes	incoming status	reports	with the spec-
	      ified hostname  to  be  filed  using  the	 hostname  defined  in
	      hosts.cfg.

       NOCOLUMNS:column[,column]
	      Used  to drop certain of the status columns generated by the Xy-
	      mon client. column is one	of cpu,	 disk,	files,	memory,	 msgs,
	      ports,  procs.   This setting stops these	columns	from being up-
	      dated for	the host. Note:	If the columns already exist, you must
	      use the xymon(1) utility to drop them, or	they will go purple.

       COMMENT:Host comment
	      Adds  a  small text after	the hostname on	the web	page. This can
	      be used to describe the host, without  completely	 changing  its
	      display-name  as	the  NAME:  tag	 does. If the comment includes
	      whitespace, it must be in	double-quotes, e.g.  COMMENT:"Sun  web
	      server"

       DESCR:Hosttype:Description
	      Define some informational	text about the host. The "Hosttype" is
	      a	text describing	the type of this device	- "router",  "switch",
	      "hub",  "server" etc. The	"Description" is an informational text
	      that will	be shown on the	"Info" column page; this can  e.g.  be
	      used to store information	about the physical location of the de-
	      vice, contact persons etc. If the	text contain  whitespace,  you
	      must  enclose it in double-quotes, e.g.  DESCR:"switch:4th floor
	      Marketing	switch"

       CLASS:Classname
	      Force the	host to	belong to a specific  class.  Class-names  are
	      used  when  configuring log-file monitoring (they	can be used as
	      references   in	client-local.cfg(5),	analysis.cfg(5)	   and
	      alerts.cfg(5)  to	 group	log  file checks or alerts). Normally,
	      class-names are controlled on the	client by starting  the	 Xymon
	      client  with  the	"--class=Classname" option.  If	you specify it
	      in the hosts.cfg file on the  Xymon  server,  it	overrides  any
	      class  name  that	 the client reports. If	not set, then the host
	      belongs to a class named	by  the	 operating  system  the	 Xymon
	      client is	running	on.

       dialup The keyword "dialup" for a host means that it is OK for it to be
	      off-line - this should not trigger an alert. All	network	 tests
	      will  go "clear" upon failure, and any missing reports from e.g.
	      cpu- and disk-status will	not go purple when they	 are  not  up-
	      dated.

       nonongreen
	      Ignore  this host	on the "All non-green" page. Even if it	has an
	      active alert, it will not	be included  in	 the  "All  non-green"
	      page. This also removes the host from the	event-log display.

       nodisp Ignore  this host	completely when	generating the Xymon webpages.
	      Can be useful for	monitoring a host without having it show up on
	      the  webpages,  e.g. because it is not yet in production use. Or
	      for hiding a host	that is	shown only on a	second pageset.

       TRENDS:[*,][![graph,...]]
	      Defines the RRD graphs to	include	in the "trends"	column	gener-
	      ated by xymongen.	 This option syntax is complex.
	      If this option is	not present, xymongen provides graphs matching
	      the standard set of RRD files: la, disk, memory, users,  vmstat,
	      iostat, netstat, tcp, bind, apache, sendmail
	      *	 If  this  option  is specified, the list of graphs to include
	      start out	as being empty (no graphs).
	      *	 To  include  all  default  graphs,  use  an  asterisk.	  E.g.
	      "TRENDS:*"
	      *	To exclude a certain graph, specify it prefixed	with '!'. E.g.
	      to see all graphs	except users: "TRENDS:*,!users"
	      *	The netstat, vmstat and	 tcp  graphs  have  many  "subgraphs".
	      Which   of   these   are	shown  can  be	specified  like	 this:
	      "TRENDS:*,netstat:netstat2|netstat3,tcp:http|smtp|conn"	  This
	      will  show  all graphs, but instead of the normal	netstat	graph,
	      there will be two: The netstat2 and netstat3 graphs. Instead  of
	      the  combined  tcp  graphs  showing  all services, there will be
	      three: One for each of the http, conn and	smtp services.

       COMPACT:COLUMN=COLUMN1|COLUMN2|COLUMN3[,ditto]
	      Collapses	a series of statuses into a single column on the over-
	      view web page.

       INTERFACES:REGEXP
	      On  systems with multiple	network	interfaces, the	operating sys-
	      tem may report a number of network interface where  the  statis-
	      tics  are	of no interest.	By default Xymon tracks	and graphs the
	      traffic on all network interfaces. This option defines a regular
	      expression, and only those interfaces whose name matches the ex-
	      pression are tracked.

XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE
       NOTE: The "NK" set of tags is deprecated. They will  be	supported  for
       Xymon  4.x,  but	 will be dropped in version 5.	It is recommended that
       you move	your critical systems view to the criticalview.cgi(1)  viewer,
       which  has  a  separate	configuration tool, criticaleditor.cgi(1) with
       more facilities than the	NK tags	in hosts.cfg.

       xymongen	will create three sets of pages: The main page xymon.html, the
       all-non-green-statuses  page  (nongreen.html),  and a specially reduced
       version of nongreen.html	 with  only  selected  tests  (critical.html).
       This  page  includes selected tests that	currently have a red or	yellow
       status.

       NK:testname[,testname]
	      NOTE:  This  has	been  deprecated,  you	 should	  use	criti-
	      calview.cgi(1) instead of	the NK tag.

	      Define  the  tests  that you want	included on the	critical page.
	      E.g. if you have a host where you	only  want  to	see  the  http
	      tests on critical.html, you specify it as

		12.34.56.78  www.acme.com  # http://www.acme.com/ NK:http

	      If  you  want multiple tests for a host to show up on the	criti-
	      cal.html page, specify all the tests separated by	 commas.   The
	      test names correspond to the column names	(e.g.  https tests are
	      covered by an "NK:http" tag).

       NKTIME=day:starttime:endtime[,day:starttime:endtime]
	      This tag limits the time when an active alert  is	 presented  on
	      the NK web page.

	      By default, tests	with a red or yellow status that are listed in
	      the "NK:testname"	tag will appear	on the NK page.	 However,  you
	      may  not	want  the  test	 to be shown outside of	normal working
	      hours - if, for example, the host	is not being  serviced	during
	      week-ends.

	      You can then use the NKTIME tag to define	the time periods where
	      the alert	will show up on	the NK page.

	      The time specification consists of

	      day-of-week: W means Mon-Fri ("weekdays"), * means all  days,  0
	      ..  6  = Sunday .. Saturday.  Listing multiple days is possible,
	      e.g. "60"	is valid meaning "Saturday and Sunday".

	      starttime: Time to start showing	errors,	 must  be  in  24-hour
	      clock format as HHMM hours/minutes.  E.g.	for 8 am enter "0800",
	      for 9.30 pm enter	"2130"

	      endtime: Time to stop showing errors.

	      If necessary, multiple periods can be specified. E.g. to monitor
	      a	  site	 24x7,	 except	  between  noon	 and  1	 pm,  use  NK-
	      TIME=*:0000:1159,*:1300:2359

	      The interval between start time and end time may cross midnight,
	      e.g.  *:2330:0200	 would	be  valid  and have the	same effect as
	      *:2330:2400,*:0000:0200.

XYMON TAGS FOR THE WML (WAP) CARDS
       If xymongen is run with the "--wml" option, it will generate a  set  of
       WAP-format output "cards" that can be viewed with a WAP-capable device,
       e.g. a PDA or cell-phone.

       WML:[+|-]testname[,[+|-]testname]
	      This tag determines which	tests for this hosts are  included  in
	      the WML (WAP) page. Syntax is identical to the NK: tag.

	      The  default  set	 of WML	tests are taken	from the --wml command
	      line option.  If no "WML:" tag is	specified, the	"NK:"  tag  is
	      used if present.

XYMON STATUS PROPAGATION OPTIONS
       These tags affect how a status propagates upwards from a	single test to
       the page	and higher. This can also be done with	the  command-line  op-
       tions  --nopropyellow and --nopropred, but the tags apply to individual
       hosts, whereas the command line options are global.

       NOPROPRED:[+|-]testname[,[+|-]testname]
	      This tag is used to inhibit a yellow or red status  from	propa-
	      gating  upwards -	i.e. from a test status	color to the (sub)page
	      status color, and	further	on to xymon.html or nongreen.html

	      If a host-specific tag begins with a '-' or a '+', the host-spe-
	      cific  tags  are	removed/added  to the default setting from the
	      command-line option. If the host-specific	 tag  does  not	 begin
	      with  a  '+'  or	a '-', the default setting is ignored for this
	      host and the NOPROPRED applies to	the tests given	with this tag.

	      E.g.:  xymongen  runs  with   "--nopropred=ftp,smtp".    "NOPRO-
	      PRED:+dns,-smtp"	gives a	NOPROPRED setting of "ftp,dns" (dns is
	      added to the default, smtp is removed).  "NOPROPRED:dns" gives a
	      setting of "dns" only (the default is ignored).

	      Note:  If	you set	use the	"--nopropred=*"	command	line option to
	      disable propagation of all alerts, you cannot use	 the  "+"  and
	      "-"  methods to add or remove from the wildcard setting. In that
	      case, do not use the "+" or "-" setting, but simply list the re-
	      quired tests that	you want to keep from propagating.

       NOPROPYELLOW:[+|-]testname[,[+|-]testname]
	      Similar  to  NOPROPRED: tag, but applies to propagating a	yellow
	      status upwards.

       NOPROPPURPLE:[+|-]testname[,[+|-]testname]
	      Similar to NOPROPRED: tag, but applies to	propagating  a	purple
	      status upwards.

       NOPROPACK:[+|-]testname[,[+|-]testname]
	      Similar  to  NOPROPRED:  tag,  but applies to propagating	an ac-
	      knowledged status	upwards.

XYMON AVAILABILITY REPORT OPTIONS
       These options affect the	way the	Xymon availability  reports  are  pro-
       cessed (see report.cgi(1) for details about availability	reports).

       REPORTTIME=day:starttime:endtime[,day:starttime:endtime]
	      This tag defines the time	interval where you measure uptime of a
	      service for reporting purposes.

	      When xymongen generates a	report,	it computes  the  availability
	      of  each	service	- i.e. the percentage of time that the service
	      is reported as available (meaning: not red).

	      By default, this calculation is done on a	24x7 basis, so no mat-
	      ter when an outage occurs, it counts as downtime.

	      The  REPORTTIME tag allows you to	specify	a period of time other
	      than 24x7	for the	service	availability calculation.  If you have
	      systems  where you only guarantee	availability from e.g. 7 AM to
	      8	PM on weekdays,	you can	use
		REPORTTIME=W:0700:2000
	      and the availability calculation will only be performed for  the
	      service with measurements	from this time interval.

	      The syntax for REPORTTIME	is the same as the one used by the NK-
	      TIME parameter.

	      When REPORTTIME is specified, the	availability calculation  hap-
	      pens like	this:

	      *	 Only  measurements  done during the given time	period is used
	      for the calculation.
	      *	"blue" time reduces the	length of the report interval,	so  if
	      you  are	generating a report for	a 10-hour period and there are
	      20 minutes of "blue" time,  then	the  availability  calculation
	      will  consider  the reporting period to be 580 minutes (10 hours
	      minus 20 minutes).  This allows you to have  scheduled  downtime
	      during  the  REPORTTIME interval without hurting your availabil-
	      ity; this	is (I believe) the whole idea of  the  downtime	 being
	      "planned".
	      *	 "red"	and  "clear"  status  counts as	downtime; "yellow" and
	      "green" count as uptime. "purple"	time is	ignored.

	      The availability calculation correctly  handles  status  changes
	      that cross into/out of a REPORTTIME interval.

	      If  no  REPORTTIME  is  given,  the standard 24x7	calculation is
	      used.

       WARNPCT:percentage
	      Xymon's reporting	facility uses a	computed availability  thresh-
	      old  to  color  services	green  (100% available), yellow	(above
	      threshold, but less than 100%), or red (below threshold) in  the
	      reports.

	      This  option allows you to set the threshold value on a host-by-
	      host basis, instead of using a global setting for	all hosts. The
	      threshold	is defined as the percentage of	the time that the host
	      must be available, e.g. "WARNPCT:98.5" if	you want the threshold
	      to be at 98.5%

       noflap[=test1,test2,...]
	      Disable  flap  detection for this	host, or for specific tests on
	      this host. Flap detection	 is  globally  controlled  by  options
	      given  to	xymond on the command line, but, if enabled, it	can be
	      disabled using this option.

NETWORK	TEST SETTINGS
       testip By default, Xymon	will perform a name lookup of the hostname  to
	      get  the	IP  address  it	 will  use for network tests. This tag
	      causes Xymon to use the IP listed	in the hosts.cfg file.

       NET:location
	      This tag defines the host	as being tested	from a specific	 loca-
	      tion.   If xymonnet sees that the	environment variable XYMONNET-
	      WORK is set, it will only	test the hosts that  have  a  matching
	      "NET:location"  tag in the hosts.cfg file. So this tag is	useful
	      if you have more than one	system running network tests, but  you
	      still  want  to  keep a consolidated hosts.cfg file for all your
	      systems.

	      Note: The	"--test-untagged" option modifies this behaviour,  see
	      xymonnet(1)

       noclear
	      Some  network  tests depend on others. E.g. if the host does not
	      respond to ping, then there's a good chance that the entire host
	      is  down	and all	network	tests will fail. Or if the http	server
	      is down, then any	web content checks are also  likely  to	 fail.
	      To avoid floods of alerts, the default behaviour is for xymonnet
	      to change	the status of these tests that fail because of another
	      problem  to "clear" instead of "red". The	"noclear" tag disables
	      this behaviour and causes	all failing tests to be	reported  with
	      their true color.

	      This  behaviour  can  also be implemented	on a per-test basis by
	      putting the "~" flag on any network test.

	      Note that	"noclear" also affects whether stale  status  messages
	      from  e.g. a client on the host go purple	or clear when the host
	      is down; see the "noclear" description in	the "GENERAL  PER-HOST
	      OPTIONS" section above.

       nosslcert
	      Disables	the  standard  check  of any SSL certificates for this
	      host. By default,	if an SSL-enabled service is tested, a	second
	      test result is generated with information	about the SSL certifi-
	      cate - this tag disables the  SSL	 certificate  checks  for  the
	      host.

       ssldays=WARNDAYS:ALARMDAYS
	      Define  the number of days before	an SSL certificate expires, in
	      which the	sslcert	status shows a warning (yellow)	or alarm (red)
	      status.  These  default  to  the values from the "--sslwarn" and
	      "--sslalarm" options for the xymonnet(1) tool; the values	speci-
	      fied in the "ssldays" tag	overrides the default.

       sslbits=MINIMUMKEYBITS
	      Enable  checking	of the encryption strength of the SSL protocol
	      offered by the server. If	the server offers encryption  using  a
	      key with fewer than MINIMUMKEYBITS bits, the "sslcert" test will
	      go red. E.g. to check that your server only uses strong  encryp-
	      tion (128	bits or	better), use "sslbits=128".

       sni

       nosni  Enables  or disables use of SNI (Server Name Indication) for SSL
	      tests.

	      Some SSL implementations cannot handle SSL handshakes  with  SNI
	      data,  so	Xymon by default does not use SNI. This	default	can be
	      changed with the "--sni" option for xymonnet(1) but can also  be
	      managed per host with these tags.

	      SNI  support was added in	Xymon 4.3.13, where the	default	was to
	      use SNI. This was	changed	in 4.3.14 so SNI support  is  disabled
	      by  default,  and	the "sni" and "nosni" tags were	introduced to-
	      gether with the "--sni" option for xymonnet.

       DOWNTIME=day:starttime:endtime[,day:starttime:endtime]

       DOWNTIME=columns:day:starttime:endtime:cause[,columns:day:start-
       time:endtime:cause]
	      This  tag	 can  be  used to ignore failed	checks during specific
	      times of the day - e.g. if you run services that are only	 moni-
	      tored  e.g. Mon-Fri 8am-5pm, or you always reboot	a server every
	      Monday between 5 and 6 pm.

	      What happens is that if a	test fails during the specified	 time,
	      it  is reported with status BLUE instead of red, yellow, or pur-
	      ple. Thus	you can	still see when the  service  was  unavailable,
	      but alarms will not be triggered and the downtime	is not counted
	      in the availability calculations generated by the	Xymon reports.

	      The "columns" and	"cause"	settings are  optional,	 but  both  or
	      neither  must  be	 specified. "columns" may be a comma-separated
	      list of status  columns  to  which  DOWNTIME  will  apply.   The
	      "cause"  string  will be displayed on the	status web page	to ex-
	      plain why	the system is down.

	      The syntax for DOWNTIME is the same as the one used by  the  NK-
	      TIME parameter.

       SLA=day:starttime:endtime[,day:starttime:endtime]
	      This tag is now deprecated. Use the DOWNTIME tag instead.

	      This  tag	works the opposite of the DOWNTIME tag - you use it to
	      specify the periods of the day that the service should be	green.
	      Failures OUTSIDE the SLA interval	are reported as	blue.

       depends=(testA:host1/test1,host2/test2),(testB:host3/test3),[...]
	      This  tag	 allows	 you to	define dependencies between tests.  If
	      "testA" for the current host depends on "test1" for host "host1"
	      and test "test2" for "host2", this can be	defined	with

		 depends=(testA:host1/test1,host2/test2)

	      When   deciding  the  color  to  report  for  testA,  if	either
	      host1/test1 failed or host2/test2	failed,	if  testA  has	failed
	      also  then  the color of testA will be "clear" instead of	red or
	      yellow.

	      Since all	tests are actually run	before	the  dependencies  are
	      evaluated, you can use any host/test in the dependency - regard-
	      less of the actual sequence that the hosts are  listed,  or  the
	      tests run. It is also valid to use tests from the	same host that
	      the dependency is	for. E.g.

		 1.2.3.4  foo #	http://foo/ webmin depends=(webmin:foo/http)

	      is valid;	if both	the http and the webmin	tests fail, then  web-
	      min will be reported as clear.

	      Note:  The  "depends" tag	is evaluated by	xymonnet while running
	      the network tests. It can	therefore only refer to	other  network
	      tests  that  are handled by the same server - there is currently
	      no way to	use the	e.g. the status	of locally  run	 tests	(disk,
	      cpu,  msgs)  or network tests from other servers in a dependency
	      definition. Such dependencies are	silently ignored.

       badTEST[-weekdays-starttime-endtime]:x:y:z
	      NOTE: This has been deprecated, use the delayred and delayyellow
	      settings instead.

	      Normally	when  a	 network test fails, the status	changes	to red
	      immediately.  With a "badTEST:x:y:z" tag this behaviour changes:
	      *	While "z" or more successive tests fail, the column goes RED.
	      *	While "y" or more successive tests fail, but fewer  than  "z",
	      the column goes YELLOW.
	      *	 While	"x" or more successive tests fail, but fewer than "y",
	      the column goes CLEAR.
	      *	While fewer than "x" successive	tests fail, the	 column	 stays
	      GREEN.

	      The  optional  time  specification  can  be  used	 to limit this
	      "badTEST"	setting	to a particular	time of	day, e.g. to require a
	      longer period of downtime	before raising an alarm	during out-of-
	      office hours. The	time-specification uses:
	      *	Weekdays: The weekdays this badTEST tag	applies, from 0	 (Sun-
	      day)  through  6 (Saturday). Putting "W" here counts as "12345",
	      i.e. all working days. Putting "*" here counts as	 all  days  of
	      the week,	equivalent to "0123456".
	      *	 start	time  and end time are specified using 24-hour clocks,
	      e.g. "badTEST-W-0900-2000" is valid for working days  between  9
	      AM (09:00) and 8 PM (20:00).

	      When  using multiple badTEST tags, the LAST one specified	with a
	      matching time-spec is used.

	      Note: The	"TEST" is replaced by the name of the test, e.g.

	       12.34.56.78  www.foo.com	 # http://www.foo.com/ badhttp:1:2:4

	      defines a	http test that goes "clear" after the  first  failure,
	      "yellow"	after  two  successive	failures, and "red" after four
	      successive failures.

	      For LDAP tests using URL's, use the  option  "badldapurl".   For
	      the other	network	tests, use "badftp", "badssh" etc.

CONNECTIVITY (PING) TEST
       These tags affect the behaviour of the xymonnet connectivity test.

       noping Disables	the  ping-test,	but will keep the "conn" column	on the
	      web display with a notice	that it	has been disabled.

       noconn Disables the ping-test, and does not put a "conn"	column on  the
	      web display.

       conn   The  "conn"  test	(which does a ping of the host)	is enabled for
	      all hosts	by default, and	normally you just want to  disable  it
	      using  "noconn" or "noping". However, on the rare	occasion where
	      you may want to check that a host	is NOT up, you can specify  it
	      as  an  explicit	test,  and use the normal test modifiers, e.g.
	      "!conn" will be green when the host is NOT up,  and  red	if  it
	      does appear on the network.

	      The  actual name of the tag - "conn" by default -	depends	on the
	      "--ping=TESTNAME"	option for xymonnet, as	that decides the test-
	      name for the connectivity	test.

       conn={best,|worst,}IP1[,IP2...]
	      This  adds  additional  IP-addresses  that are pinged during the
	      normal "conn" test. So the normal	"conn" test  must  be  enabled
	      (the  default)  before this tag has any effect. The IP-addresses
	      listed here are pinged in	addition to the	main IP-address.

	      When multiple IP's are pinged, you can choose if ALL  IP's  must
	      respond  (the  "worst"  method), or AT LEAST one IP must respond
	      (the "best" setting). All	of the IP's are	reported in  a	single
	      "conn"  status,  whose  color  is	 determined from the result of
	      pinging the IP's and the best/worst setting.  The	default	method
	      is  "best" - so it will report green if just one of the IP's re-
	      spond to ping.

       badconn[-weekdays-starttime-endtime]:x:y:z
	      This is taken directly from the "fping.sh" connectivity- testing
	      script,  and  is used by xymonnet	when it	runs with ping testing
	      enabled (the default). See the description of the	"badTEST" tag.

       route:router1,router2,....
	      This tag is taken	from the "fping.sh" script, and	is used	by xy-
	      monnet when run with the "--ping"	option to enable ping testing.

	      The router1,router2,... is a comma-separated list	of hosts else-
	      where in the hosts.cfg file. You cannot have any spaces  in  the
	      list - separate hosts with commas.

	      This tag changes the color reported for a	ping check that	fails,
	      when one or more of the hosts in the "route" list	is also	 down.
	      A	 "red"	status	becomes	"yellow" - other colors	are unchanged.
	      The status message will include information about	the  hosts  in
	      the router-list that are down, to	aid tracking down which	router
	      is the root cause	of the problem.

	      Note: Internally,	 the  ping  test  will	still  be  handled  as
	      "failed",	 and  therefore	any other tests	run for	this host will
	      report a status of "clear".

       route_LOCATION:router1,router2,...
	      If the XYMONNETWORK environment variable is defined,  a  tag  of
	      "route_XYMONNETWORK:"  is	 recognized  by	xymonnet with the same
	      effect as	the normal "route:" tag	(see above).  This allows  you
	      to  have different route:	tags for each server running xymonnet.
	      The actual text for the tag then must match the value  you  have
	      for  the	XYMONNETWORK setting.  E.g. with XYMONNETWORK=dmz, the
	      tag becomes "route_dmz:"

       trace  If the connectivity test fails, run a "traceroute"  and  include
	      the  output from this in the status message from the failed con-
	      nectivity	test. Note: For	this to	work, you may have  to	define
	      the TRACEROUTE environment variable, see xymonserver.cfg(5)

       notrace
	      Similar  to  the	"trace"	option,	this disables the running of a
	      traceroute for the host after a failed connectivity test.	It  is
	      only  used  if  running  traceroute  is made the default via the
	      --trace option.

SIMPLE NETWORK TESTS
       These tests perform a simple network test of a service by connecting to
       the port	and possibly checking that a banner is shown by	the server.

       How these tests operate are configured in the protocols.cfg(5) configu-
       ration file, which controls which port to use for the service,  whether
       to  send	 any data to the service, whether to check for a response from
       the service etc.

       You can modify the behaviour of these tests  on	a  per-test  basis  by
       adding one or more modifiers to the test: :NUMBER changes the port num-
       ber from	the default to the one you specify for	this  test.   E.g.  to
       test ssh	running	on port	8022, specify the test as ssh:8022.

       :s  makes  the  test silent, i.e. it does not send any data to the ser-
       vice. E.g. to do	a silent test of an smtp server, enter smtp:s.

       You can combine these two: ftp:8021:s is	valid.

       If you must test	a service from a multi-homed host (i.e.	using  a  spe-
       cific  source  IP-address instead of the	one your operating system pro-
       vides), you can use the modifier	"@IPADDRESS" at	the end	 of  the  test
       specification,  after  any other	modifiers or port number.  "IPADDRESS"
       must be a valid dotted IP-address (not hostname)	which is  assigned  to
       the host	running	the network tests.

       The  name of the	test also determines the column	name that the test re-
       sult will appear	with in	the Xymon webpages.

       By prefixing a test with	"!" it becomes a reverse test: Xymon will  ex-
       pect  the  service  NOT	to be available, and send a green status if it
       does NOT	respond. If a connection to the	service	succeeds,  the	status
       will go red.

       By  prefixing  a	 test  with "?"	errors will be reported	with a "clear"
       status instead of red. This is known as a test for a "dialup"  service,
       and  allows you to run tests of hosts that are not always online, with-
       out getting alarms while	they are off-line.

       ftp ssh telnet smtp pop3	imap nntp rsync	clamd oratns qmtp qmqp
	      These tags are for testing services  offering  the  FTP,	Secure
	      Shell (ssh), SMTP, POP3, IMAP, NNTP, rsync, CLAM anti-virus dae-
	      mon (clamd), Oracle TNS listener (oratns), qmail QMTP  and  QMQP
	      protocols.

       ftps telnets smtps pop3s	imaps nntps
	      These  tags  are for testing of the SSL-tunneled versions	of the
	      standard ftp, telnet, smtp, pop3,	imap and nntp  protocols.   If
	      Xymon  was  configured  with support for SSL, you	can test these
	      services like any	other network service -	xymonnet will setup an
	      SSL-encrypted  session  while  testing  the service.  The	server
	      certificate is validated and information about it	 sent  in  the
	      "sslcert"	 column. Note that smtps does not have a standard port
	      number assignment, so you	will need to enter this	into the  pro-
	      tocols.cfg file or your /etc/services file.

       bbd    Test that	a Big Brother compatible daemon	is running. This check
	      works both for the Xymon xymond(8) daemon, and the original  Big
	      Brother bbd daemon.

DNS SERVER TESTS
       These tags are used to setup monitoring of DNS servers.

       dns    Simple  DNS test.	It will	attempt	to lookup the A	record for the
	      hostname of the DNS server.

       dig    This is an alias for the "dns" test. In xymonnet,	the "dns"  and
	      "dig"  tests  are	 handled identically, so all of	the facilities
	      for testing described for	the "dns" test are also	available  for
	      the "dig"	test.

       dns=hostname

       dns=TYPE:lookup[,TYPE:lookup...]
	      The  default  DNS	 tests	will  attempt a	DNS lookup of the DNS'
	      servers own hostname. You	can specify the	hostname to lookup  on
	      a	DNS server by listing it on each test.

	      The  second  form	 of  the  test	allows you to perform multiple
	      queries of the DNS server, requesting  different	types  of  DNS
	      records.	The TYPE defines the type of DNS data: A (IP-address),
	      MX (Mail eXchanger), PTR (reverse), CNAME	(alias),  SOA  (Start-
	      Of-Authority),  NS  (Name	Server)	are among the more common ones
	      used. The	"lookup" is the	query. E.g. to lookup the  MX  records
	      for  the "foo.com" domain, you would use "dns=mx:foo.com". Or to
	      lookup   the   nameservers    for	   the	  "bar.org"    domain,
	      "dns=ns:bar.org".	  You  can list	multiple lookups, separated by
	      commas. For the test to end up with a green status, all  lookups
	      must succeed.

OTHER NETWORK TESTS
       ntp    Check  for  a running NTP	(Network Time Protocol)	server on this
	      host. This test uses the "ntpdate" utility to check  for	a  NTP
	      server - you should either have ntpdate in your PATH, or set the
	      location	of  the	 ntpdate  program   in	 $XYMONHOME/etc/xymon-
	      server.cfg

       rpc[=rpcservice1,rpcservice2,...]
	      Check  for one or	more available RPC services. This check	is in-
	      direct in	that it	only queries the RPC Portmapper	on  the	 host,
	      not the actual service.

	      If  only	"rpc"  is  given, the test only	verifies that the port
	      mapper is	available on the remote	host. If  you  want  to	 check
	      that  one	or more	RPC services are registered with the port map-
	      per, list	the names  of  the  desired  RPC  services  after  the
	      equals-sign.  E.g. for a working NFS server the "mount", "nlock-
	      mgr" and "nfs" services must be available; this can  be  checked
	      with "rpc=mount,nlockmgr,nfs".

	      This  test  uses	the  rpcinfo tool for the actual test; if this
	      tool is not available in the PATH	of xymonnet, you  must	define
	      the  RPCINFO environment variable	to point at this tool. See xy-
	      monserver.cfg(5)

HTTP TESTS
       Simple testing of a http	URL is done simply by putting the URL into the
       hosts.cfg  file.	 Note  that this only applies to URL's that begin with
       "http:" or "https:".

       The following items describe more advanced forms	of http	URL's.

       Basic Authentication with username/password
	      If the URL requires authentication in the	form of	a username and
	      password,	 it  is	most likely using the HTTP "Basic" authentica-
	      tion. xymonnet support this, and you can	provide	 the  username
	      and password either by embedding them in the URL e.g.
		  http://USERNAME:PASSWORD@www.sample.com/
	      or  by  putting the username and password	into the ~/.netrc file
	      (see ftp(1) for details).

       Authentication with SSL client certificates
	      An SSL client certificate	can be used  for  authentication.   To
	      use this,	the client certificate must be stored in a PEM-format-
	      ted file together	with the client	certificate key, in  the  $XY-
	      MONHOME/certs/ directory.	The URL	is then	given as
		  http://CERT:FILENAME@www.sample.com/
	      The  "CERT:"  part is literal - i.e. you write C-E-R-T-colon and
	      then the filename	of the PEM-formatted certificate.
	      A	PEM-formatted certificate file can be generated	based on  cer-
	      tificates	 stored	in Microsoft Internet Explorer and OpenSSL. Do
	      as follows:
	      From the MSIE Tools-Options menu,	pick the Content tab, click on
	      Certificates,  choose  the  Personal tab,	select the certificate
	      and click	Export.	Make sure you export the private key also.  In
	      the  Export  File	 Format, choose	PKCS 12	(.PFX),	check the "In-
	      clude all	certificates" checkbox and uncheck the "Enable	strong
	      protection".   Provide  a	 temporary  password  for the exported
	      file, and	select a filename for the PFX-file.
	      Now run  "openssl	 pkcs12	 -in  file.pfx	-out  file.pem".  When
	      prompted	for the	"Import	Password", provide the temporary pass-
	      word you gave when exporting the	certificate.  Then  provide  a
	      "PEM pass	phrase"	(twice)	when prompted for one.
	      The  file.pem  file  is  the  one	you should use in the FILENAME
	      field in the URL - this file must	be kept	in  $XYMONHOME/certs/.
	      The  PEM	pass  phrase must be put into a	file named the same as
	      the certificate, but with	extension ".pass". E.g.	 if  you  have
	      the PEM certificate in $XYMONHOME/certs/client.pem, you must put
	      the pass phrase into the $XYMONHOME/certs/client.pass file. Make
	      sure  to	protect	 this file with	Unix permissions, so that only
	      the user running Xymon can read it.

       Forcing an HTTP or SSL version
	      Some SSL sites will only allow you to connect, if	you  use  spe-
	      cific  "dialects"	 of HTTP or SSL. Normally this is auto-negoti-
	      ated, but	experience shows that this fails on some systems.

	      xymonnet can be told to use specific dialects, by	adding one  or
	      more  "dialect  names"  to  the  URL  scheme, i.e. the "http" or
	      "https" in the URL:

	      *	"2",  e.g. https2://www.sample.com/ : use only SSLv2
	      *	"3",  e.g. https3://www.sample.com/ : use only SSLv3
	      *	"t",  e.g. httpst://www.sample.com/ : use only TLSv1.0
	      *	"a",  e.g. httpsa://www.sample.com/ : use only TLSv1.0
	      *	"b",  e.g. httpsb://www.sample.com/ : use only TLSv1.1
	      *	"c",  e.g. httpsc://www.sample.com/ : use only TLSv1.2
	      *	"m",  e.g. httpsm://www.sample.com/ : use only 128-bit ciphers
	      *	"h",  e.g. httpsh://www.sample.com/ : use  only	 >128-bit  ci-
	      phers
	      *	"10", e.g. http10://www.sample.com/ : use HTTP 1.0
	      *	"11", e.g. http11://www.sample.com/ : use HTTP 1.1

	      These  can be combined where it makes sense, e.g to force	TLS1.2
	      and HTTP 1.0 you would use "httpsc10".

	      Note that	SSLv2 support is disabled in all current  OpenSSL  re-
	      leases.	TLS  version-specific  scheme testing requires OpenSSL
	      1.0.1 or higher.

       Testing sites by	IP-address
	      xymonnet ignores the "testip" tag	normally used to force a  test
	      to  use  the  IP-address	from the hosts.cfg file	instead	of the
	      hostname,	when it	performs http and https	tests.

	      The reason for this is that  it  interacts  badly	 with  virtual
	      hosts, especially	if these are IP-based as is common with	https-
	      websites.

	      Instead the IP-address to	connect	to can be overridden by	speci-
	      fying it as:

		   http://www.sample.com=1.2.3.4/index.html

	      The  "=1.2.3.4"  will  case xymonnet to run the test against the
	      IP-address "1.2.3.4", but	still trying to	access a virtual  web-
	      site with	the name "www.sample.com".

	      The "=ip.address.of.host"	must be	the last part of the hostname,
	      so if you	need to	combine	this with e.g. an explicit  port  num-
	      ber, it should be	done as

		   http://www.sample.com:3128=1.2.3.4/index.html

       HTTP Testing via	proxy
	      NOTE:  This  is  not  enabled  by	 default.  You	must  add  the
	      "--bb-proxy-syntax" option when running xymonnet(1) if you  want
	      to use this.

	      xymonnet	supports the Big Brother syntax	for specifying an HTTP
	      proxy to use when	performing http	tests. This syntax just	 joins
	      the proxy- and the target-URL into one, e.g.
		  http://webproxy.sample.com:3128/http://www.foo.com/
	      would  be	the syntax for testing the www.foo.com website via the
	      proxy running on "webproxy.sample.com" port 3128.

	      If the proxy port	number is not specified, the default HTTP port
	      number (80) is used.

	      If your proxy requires authentication, you can specify the user-
	      name and password	inside the proxy-part of the URL, e.g.
		  http://fred:Wilma1@webproxy.sam-
	      ple.com:3128/http://www.foo.com/
	      will  authenticate to the	proxy using a username of "fred" and a
	      password of "Wilma1", before requesting the proxy	to  fetch  the
	      www.foo.com homepage.

	      Note  that  it  is not possible to test https-sites via a	proxy,
	      nor is it	possible to use	https for connecting to	the proxy  it-
	      self.

       cont[=COLUMN];URL;[expected_data_regexp|#digesttype:digest]
	      This tag is used to specify a http/https check, where it is also
	      checked that specific content is present in the server response.

	      If the URL itself	includes a semi-colon, this must be escaped as
	      '%3B'  to	 avoid	confusion  over	which semicolon	is part	of the
	      URL, and which semicolon acts as a delimiter.

	      The data that must be returned can be specified either as	a reg-
	      ular  expression	(except	 that  <space> is not allowed) or as a
	      message digest (typically	using an MD5 sum or SHA-1 hash).

	      The regex	is pre-processed for backslash "\"  escape  sequences.
	      So  you  can really put any character in this string by escaping
	      it first:
		 \n	Newline	(LF, ASCII 10 decimal)
		 \r	Carriage return	(CR, ASCII 13 decimal)
		 \t	TAB (ASCII 8 decimal)
		 \\    Backslash (ASCII	92 decimal)
		 \XX	The character with ASCII hex-value XX

	      If you must have whitespace in the regex,	 use  the  [[:space:]]
	      syntax, e.g. if you want to test for the string "All is OK", use
	      "All[[:space:]]is[[:space:]]OK".	Note that this may  depend  on
	      your  particular	implementation of the regex functions found in
	      your C library. Thanks to	Charles	Goyard for this	tip.

	      Note: If you are migrating from the "cont2.sh" script, you  must
	      change  the  '_' used as wildcards by cont2.sh into '.' which is
	      the regular-expression wildcard character.

	      Message  digests	can  use  whatever  digest   algorithms	  your
	      libcrypto	 implementation	 (usually  OpenSSL)  supports.	Common
	      message digests are "md5", "sha1", "sha256"  or  "sha512".   The
	      digest  is  calculated  on the data portion of the response from
	      the server, i.e. HTTP headers are	not included in	the digest (as
	      they change from one request to the next).

	      The  expected  digest  value  can	 be computed with the xymondi-
	      gest(1) utility.

	      "cont" tags in hosts.cfg result in two status reports: One  sta-
	      tus with the "http" check, and another with the "content"	check.

	      As with normal URL's, the	extended syntax	described above	can be
	      used e.g.	when testing SSL sites that require the	use  of	 SSLv2
	      or strong	ciphers.

	      The  column  name	 for the result	of the content check is	by de-
	      fault called "content" - you can change  the  default  with  the
	      "--content=NAME"	option	to xymonnet. See xymonnet(1) for a de-
	      scription	of this	option.

	      If more than one content check is	present	for a host, the	 first
	      content check is reported	in the column "content", the second is
	      reported in the column "content1", the third in "content2" etc.

	      You can also specify the column name directly in the test	speci-
	      fication,	 by  writing  it as "cont=COLUMN;http://...".  Column-
	      names cannot include whitespace or semi-colon.

	      The content-check	status by default includes the full  URL  that
	      was  requested,  and  the	HTML data returned by the server.  You
	      can hide the HTML	data on	a per-host  (not  per-test)  basis  by
	      adding the HIDEHTTP tag to the host entry.

       content=URL
	      This  syntax  is	deprecated.  You should	use the	"cont" tag in-
	      stead, see above.

       post[=COLUMN];URL;form-data;[expected_data_regexp|#digesttype:digest]
	      This tag can be used to test web pages, that use an input	 form.
	      Data  can	 be posted to the form by specifying them in the form-
	      data field, and the result can be	checked	as if it was a	normal
	      content  check  (see above for a description of the cont-tag and
	      the restrictions on how the URL must be written).

	      The   form-data	field	must   be   entered    in    "applica-
	      tion/x-www-form-urlencoded"  format,  which is the most commonly
	      used format for web forms.

	      E.g. if you have a web form defined like this:

		 <form action="/cgi-bin/form.cgi" method="post">
		   <p>Given name<input type="text" name="givenname"></p>
		   <p>Surname<input type="text"	name="surname"></p>
		   <input type="submit"	value="Send">
		 </form>

	      and you want to post the value "John" to	the  first  field  and
	      "Doe Jr."	to the second field, then the form data	field would be

		  givenname=John&surname=Doe+Jr.

	      Note that	any spaces in the input	value is replaced with '+'.

	      If  your	form-data  requires  a different content-type, you can
	      specify it by beginning the form-data with  (content-type=TYPE),
	      e.g.  "(content-type=text/xml)"  followed	by the POST data. Note
	      that as with normal forms, the POST data should be specified us-
	      ing  escape-sequences for	reserved characters: "space" should be
	      entered as "\x20", double	quote as "\x22", newline as "\n", car-
	      riage-return  as "\r", TAB as "\t", backslash as "\\".  Any byte
	      value can	be entered using "\xNN"	with NN	being the  hexadecimal
	      value, e.g. "\x20" is the	space character.

	      The  [expected_data_regexp|#digesttype:digest]  is  the expected
	      data returned from the server in response	to the POST.  See  the
	      "cont;"  tag  above  for	details. If you	are only interested in
	      knowing if it is possible	to submit the  form  (but  don't  care
	      about  the  data),  this can be an empty string -	but the	';' at
	      the end is required.

       nocont[=COLUMN];URL;forbidden_data_regexp
	      This tag works just like "cont" tag, but reverses	the test.   It
	      is  green	 when  the "forbidden_data_regexp" is NOT found	in the
	      response,	and red	when it	IS found. So it	can be used  to	 watch
	      for  data	 that  should  NOT  be present in the response,	e.g. a
	      server error message.

       nopost[=COLUMN];URL;form-data;expected_data_regexp
	      This tag works just like "post" tag, but reverses	the test.   It
	      is  green	 when  the "forbidden_data_regexp" is NOT found	in the
	      response,	and red	when it	IS found. So it	can be used  to	 watch
	      for  data	 that  should  NOT  be present in the response,	e.g. a
	      server error message.

       type[=COLUMN];URL;expected_content_type
	      This is a	variant	of the content check - instead of checking the
	      content  data,  it  checks  the type of the data as given	by the
	      HTTP Content-Type: header. This can used to check	if a  URL  re-
	      turns  e.g.  a  PDF  file,  regardless of	what is	inside the PDF
	      file.

       soap[=COLUMN];URL;SOAPMESSAGE;[expected_data_regexp|#digesttype:digest]
	      Send SOAP	message	over HTTP. This	is  identical  to  the	"cont"
	      test,  except  that  the	request	sent to	the server uses	a Con-
	      tent-type	of "application/soap+xml", and it also sends  a	 "SOA-
	      PAction"	header	with  the URL. SOAPMESSAGE is the SOAP message
	      sent to the server. Since	SOAP messages are  usually  XML	 docu-
	      ments,  you  can	store  this  in	 a separate file by specifying
	      "file:FILENAME" as the SOAPMESSAGE parameter.  E.g. a test spec-
	      ification	of
		  soap=echo;http://soap.foo.bar/baz?wsdl;file:/home/foo/msg.xml;.
	      will read	the SOAP message from the file	/home/foo/msg.xml  and
	      post it to the URL http://soap.foo.bar/bas?wsdl

	      Note  that  SOAP	XML  documents usually must begin with the XML
	      version line, <?xml version="1.0">

       nosoap[=COLUMN];URL;SOAPMESSAGE;[forbidden_data_regexp|#digesttype:di-
       gest]
	      This  tag	works just like	"soap" tag, but	reverses the test.  It
	      is green when the	"forbidden_data_regexp"	is NOT	found  in  the
	      response,	 and  red when it IS found. So it can be used to watch
	      for data that should NOT be present  in  the  response,  e.g.  a
	      server error message.

       httphead[=COLUMN];URL
	      This is used to perform an HTTP HEAD request instead of a	GET.

       httpstatus[=COLUMN];URL;okstatusexpr;notokstatusexpr
	      This is used to explicitly test for certain HTTP statuscodes re-
	      turned when the URL is requested.	The okstatusexpr and nokoksta-
	      tusexpr  expressions  are	 Perl-compatible  regular expressions,
	      e.g. "2..|302" will match	all OK codes and  the  redirect	 (302)
	      status  code.  If	 the  URL  cannot  be retrieved, the status is
	      "999".

       HIDEHTTP
	      The status display for HTTP checks usually includes the URL, and
	      for  content  checks also	the actual data	from the web page.  If
	      you would	like to	hide these from	view, then  the	 HIDEHTTP  tag
	      will  keep  this	information from showing up on the status web-
	      pages.

       headermatch
	      Content checks by	default	only search the	HTML body returned  by
	      the  webserver.  This  option  causes it to also search the HTTP
	      headers for the string that must / must not be present.

       browser=BROWSERNAME
	      By default, Xymon	sends an HTTP "User-Agent" header  identifying
	      it  a  "Xymon".  Some  websites  require that you	use a specific
	      browser, typically Internet Explorer. To cater  for  testing  of
	      such  sites, this	tag can	be used	to modify the data sent	in the
	      User-Agent header.
	      E.g. to perform an HTTP test with	Xymon masquerading as  an  In-
	      ternet  Explorer 6.0 browser, use	browser="Mozilla/4.0 (compati-
	      ble; MSIE	6.0; Windows NT	5.0)".	If you do not  know  what  the
	      User-Agent header	should be, open	up the browser that works with
	      this  particular	site,  and  open  the  URL   "javascript:docu-
	      ment.writeln(navigator.userAgent)"  (just	 copy  this  into  the
	      "Open URL" dialog. The text that shows up	is  what  the  browser
	      sends as the User-Agent header.

       httphdr=STRING
	      Xymon  can  be  send  additional	headers	 when  performing HTTP
	      checks, to allow for validation  of  any	custom	configurations
	      needed  for  your	site. Note that	this is	a host-wide configura-
	      tion. The	string will be added directly to the headers  for  all
	      URLs  on that host. There	is currently no	way to have this occur
	      only for specific	URLs checked.
	      The string should	be  encased  in	 quotes,  like	httphdr="X-Re-
	      quested-With:  XMLHttpRequest".	Newlines can be	included, how-
	      ever the string MUST NOT end with	a newline as  that  may	 cause
	      premature	ending of the headers sent.

LDAP (DIRECTORY	SERVER)	TESTS
       ldap

       ldaps  Simple  check  for  an LDAP service. This	check merely looks for
	      any service running on the ldap/ldaps service port, but does not
	      perform any actual LDAP transaction.

       ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]
	      Check  for  an  LDAP service by performing an LDAP request. This
	      tag is in	the form of an LDAP URI	(cf. RFC 2255).	This  type  of
	      LDAP  test  requires that	xymonnet(1) was	built with support for
	      LDAP, e.g. via the OpenLDAP library.  The	components of the LDAP
	      URI are:
		hostport is a host name	with an	optional ":portnumber"
		dn is the search base
		attrs is a comma separated list	of attributes to request
		scope is one of	these three strings:
		  base one sub (default=base)
		filter is filter
		exts are recognized set	of LDAP	and/or API extensions.

       ldaps://hostport/dn[?attrs[?scope[?filter[?exts]]]]
	      LDAP  service  check using LDAPv3	and STARTTLS for talking to an
	      LDAP server that requires	TLS encryption.	See xymonnet(1)	for  a
	      discussion  of  the  different ways of running LDAP servers with
	      SSL/TLS, and which of these are supported	by xymonnet.

       ldaplogin=username:password
	      Define a username	and password to	use when binding to  the  LDAP
	      server  for  ldap	URI tests. If not specified, xymonnet will at-
	      tempt an anonymous bind.

       ldapyellowfail
	      Used with	an LDAP	URL test. If the LDAP query fails  during  the
	      search of	the directory, the ldap	status is normally reported as
	      "red" (alarm). This tag reduces a	search failure to  a  "yellow"
	      (warning)	status.

PERFORMANCE MONITORING TESTS
       apache[=URL]
	      If  you  are running an Apache web server, adding	this tag makes
	      xymonnet(1) collect performance statistics from the  Apache  web
	      server by	querying the URL http://IP.ADDRESS.OF.HOST/server-sta-
	      tus?auto.	 The response is sent as a data-report	and  processed
	      by  the Xymon xymond_rrd module into an RRD file and an "apache"
	      graph. If	your web server	requires e.g. authentication, or  runs
	      on  a  different	URL for	the server-status, you can provide the
	      full  URL	 needed	 to  fetch  the	  server-status	  page,	  e.g.
	      apache=http://LOGIN:PASSWORD@10.0.0.1/server-status?auto	for  a
	      password	    protected	    server-status	page,	    or
	      apache=http://10.0.0.1:8080/apache/server-status?auto    for   a
	      server listening on port 8080 and	with a different path  to  the
	      server-status page.

	      Note  that  you  need  to	 enable	 the server-status URL in your
	      Apache configuration. The	following configuration	is needed:

		  <Location /server-status>
		      SetHandler server-status
		      Order deny,allow
		      Deny from	all
		      allow from 127.0.0.1
		  </Location>
		  ExtendedStatus On

	      Change "127.0.0.1" to the	IP-address of  the  server  that  runs
	      your network tests.

DEFAULT	HOST
       If  you	have certain tags that you want	to apply to all	hosts, you can
       define a	host name ".default." and put the tags on that host. Note that
       per-host	 definitions  will  override the default ones. To apply	to all
       hosts this should be listed FIRST in your file.

       NOTE: The ".default." host entry	will only accept the following tags  -
       others are silently ignored: delayyellow, delayred, NOCOLUMNS, COMMENT,
       DESCR, CLASS, dialup, testip, nonongreen, nodisp, noinfo, notrends, no-
       client,	TRENDS,	 NOPROPRED, NOPROPYELLOW, NOPROPPURPLE,	NOPROPACK, RE-
       PORTTIME, WARNPCT, NET, noclear,	nosslcert, ssldays, DOWNTIME, depends,
       noping,	noconn,	 trace,	notrace, HIDEHTTP, browser, pulldata. Specifi-
       cally, note that	network	tests, "badTEST" settings, and alternate page-
       set relations cannot be listed on the ".default." host.

SENDING	SUMMARIES TO REMOTE XYMON SERVERS
       summary ROW.COLUMN IP URL
	      If you have multiple Xymon servers, the "summary"	directive lets
	      you form a hierarchy of servers by sending the overall status of
	      this  server  to a remote	Xymon server, which then displays this
	      in a special summary section. E.g. if your  offices  are	spread
	      over  three  locations,  you can have a Xymon server at each of-
	      fice. These branch-office	Xymon have a "summary"	definition  in
	      their  hosts.cfg	file that makes	them report the	overall	status
	      of their branch Xymon to the central Xymon server	 you  maintain
	      at the corporate headquarters.

	      Multiple "summary" definitions are allowed.

	      The  ROW.COLUMN setting defines how this summary is presented on
	      the server that receives the summary. The	ROW text will be  used
	      as  the  heading	for a summary line, and	the COLUMN defines the
	      name of the column where this summary is shown - like the	 host-
	      name and testname	used in	the normal displays. The IP is the IP-
	      address of the remote (upstream) Xymon server, where  this  sum-
	      mary is sent). The URL is	the URL	of your	local Xymon server.

	      The  URL	need not be that of your Xymon server's	main page - it
	      could be the URL of a sub-page on	the local Xymon	server.	 Xymon
	      will report the summary using the	color of the page found	at the
	      URL you specify.	E.g. on	your corporate Xymon server you	want a
	      summary  from  the Las Vegas office - but	you would like to know
	      both what	the overall status is, and what	is the status  of  the
	      servers  on the critical Sales department	back-office servers in
	      Las Vegas. So you	configure the Las Vegas	Xymon server  to  send
	      two summaries:

		  summary Vegas.All 10.0.1.1 http://vegas.foo.com/xymon/
		  summary    Vegas.Sales   10.0.1.1   http://vegas.foo.com/xy-
	      mon/sales/

	      This gives you one summary line for Baltimore, with two columns:
	      An "All" column showing the overall status, and a	"Sales"	column
	      showing the status of the	"sales"	page on	 the  Baltimore	 Xymon
	      server.

	      Note:  Pages  defined using alternate pageset definitions	cannot
	      be used, the URL must point to a web page	from the  default  set
	      of Xymon webpages.

OTHER TAGS
       pulldata[=[IP][:port]]
	      This  option  is	recognized  by	the xymonfetch(8) utility, and
	      causes it	to poll	the host for client data. The optional	IP-ad-
	      dress and	port-number can	be used	if the client-side msgcache(8)
	      daemon is	listening on a non-standard IP-address or port-number.

FILES
       ~xymon/server/etc/hosts.cfg

SEE ALSO
       xymongen(1), xymonnet(1), xymondigest(1), xymonserver.cfg(5), xymon(7)

Xymon			  Version 4.3.30:  4 Sep 2019		  HOSTS.CFG(5)

NAME | SYNOPSIS | DESCRIPTION | FILE FORMAT | TAGS RECOGNIZED BY ALL TOOLS | GENERAL PER-HOST OPTIONS | XYMONGEN DISPLAY OPTIONS | XYMON TAGS FOR THE CRITICAL SYSTEMS OVERVIEW PAGE | XYMON TAGS FOR THE WML (WAP) CARDS | XYMON STATUS PROPAGATION OPTIONS | XYMON AVAILABILITY REPORT OPTIONS | NETWORK TEST SETTINGS | CONNECTIVITY (PING) TEST | SIMPLE NETWORK TESTS | DNS SERVER TESTS | OTHER NETWORK TESTS | HTTP TESTS | LDAP (DIRECTORY SERVER) TESTS | PERFORMANCE MONITORING TESTS | DEFAULT HOST | SENDING SUMMARIES TO REMOTE XYMON SERVERS | OTHER TAGS | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hosts.cfg&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help