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

FreeBSD Manual Pages


home | help
XYMONNET(1)		    General Commands Manual		   XYMONNET(1)

       xymonnet	- Xymon	network	test tool

       xymonnet	 [--ping|--noping]  [--timeout=N]  [options] [hostname]	[host-
       (See the	OPTIONS	section	for a description of  the  available  command-
       line options).

       xymonnet(1)  handles  the  network  tests of hosts defined in the Xymon
       configuration file, hosts.cfg. It is normally run at regular  intervals
       by xymonlaunch(8) via an	entry in the tasks.cfg(5) file.

       xymonnet	 does  all  of	the normal tests of TCP-based network services
       (telnet,	ftp, ssh, smtp,	pop, imap ....)	- i.e.	all  of	 the  services
       listed  in  protocols.cfg.  For	these tests, a completely new and very
       speedy service- checker has been	implemented.

       xymonnet	has built-in support for testing SSL-enabled  protocols,  e.g.
       imaps, pop3s, nntps, telnets, if	SSL-support was	enabled	when configur-
       ing xymonnet. The full list of known  tests  is	found  in  the	proto-
       cols.cfg(5) file	in $XYMONHOME/etc/protocols.cfg.

       In  addition,  it  implements the "dns" and "dig" tests for testing DNS

       xymonnet	also implements	a check	for NTP	servers	- this test is	called
       "ntp".  If  you want to use it, you must	define the NTPDATE environment
       variable	to point at the	location of your ntpdate(1) program.

       Note: xymonnet performs the connectivity	test (ping) based on the host-
       name,  unless the host is tagged	with "testip" or the "--dns=ip"	option
       is used.	So the target of the connectivity test can  be	determined  by
       your /etc/hosts file or DNS.

       By  default, all	servers	are tested - if	XYMONNETWORK is	set via	xymon-
       server.cfg(5) then only the hosts marked	as belonging to	 this  network
       are  tested.  If	 the command-line includes one or more hostnames, then
       only those servers are tested.

	      Determines the timeout (in seconds) for  each  service  that  is
	      tested.  For TCP tests (those from XYMONNETSVCS),	if the connec-
	      tion to the service does not succeed within N seconds, the  ser-
	      vice  is reported	as being down. For HTTP	tests, this is the ab-
	      solute limit for the entire request to the webserver  (the  time
	      needed  to  connect  to  the  server, plus the time it takes the
	      server to	respond	to the request).  Default: 10 seconds

	      This option is deprecated, and will be ignored. Use the  --time-
	      out option instead.

	      This  option  sets  a timeout for	the external commands used for
	      testing of NTP and RPC services, and to perform traceroute.

	      Determines the number of network tests that run in parallel. De-
	      fault is operating system	dependent, but will usually be 256. If
	      xymonnet begins to complain  about  not  being  able  to	get  a
	      "socket",	 try  running  xymonnet	 with a	lower value like 50 or

       --dns-timeout=N (default: 30 seconds)
	      xymonnet will timeout all	DNS  lookups  after  N	seconds.   Any
	      pending  DNS  lookups  are  regarded as failed, i.e. the network
	      tests that depend	on this	DNS lookup will	report an error.
	      Note: If you use the --no-ares option, timeout  of  DNS  lookups
	      cannot be	controlled by xymonnet.

	      Same  as "--dns-timeout=N". The "--dns-max-all" option is	depre-
	      cated and	should not be used.

	      Determines how xymonnet finds the	IP addresses of	the  hosts  to
	      test.   By  default (the "standard"), xymonnet does a DNS	lookup
	      of the hostname to determine the IP address, unless the host has
	      the "testip" tag,	or the DNS lookup fails.
	      With  "--dns=only"  xymonnet  will ONLY do the DNS lookup; if it
	      fails, then all services on that host will be reported as	 being
	      With "--dns=ip" xymonnet will never do a DNS lookup; it will use
	      the IP adresse specified in hosts.cfg for	the tests. Thus,  this
	      setting  is  equivalent to having	the "testip" tag on all	hosts.
	      Note that	http tests will	ignore this setting and	still  perform
	      a	 DNS lookup for	the hostname given in the URL; see the "xymon-
	      net tags for HTTP	tests" section in hosts.cfg(5)

	      Disable the ARES resolver	built into xymonnet. This makes	xymon-
	      net  resolve  hostnames using your system	resolver function. You
	      should only use this as a	last resort if xymonnet	cannot resolve
	      the hostnames you	use in the normal way (via DNS or /etc/hosts).
	      One reason for using this	would be if you	need to	resolve	 host-
	      names via	NIS/NIS+ (a.k.a. Yellow	Pages).
	      The  system  resolver  function does not provide a mechanism for
	      controlling timeouts of the hostname lookups, so if your DNS  or
	      NIS  server  is down, xymonnet can take a	very long time to run.
	      The --dns-timeout	option is effectively disabled when using this

	      Log  failed  hostname  lookups  to  the  file FILENAME. FILENAME
	      should be	a full pathname.

	      With this	option,	xymonnet will send a status message  with  de-
	      tails of how many	hosts were processed, how many tests were gen-
	      erated, any errors that occurred during the run, and some	timing
	      statistics.  The default columnname is "xymonnet".

	      When  using  the	XYMONNETWORK environment variable to test only
	      hosts on a particular  network  segment,	xymonnet  will	ignore
	      hosts that do not	have any "NET:x" tag.  So only hosts that have
	      a	NET:$XYMONNETWORK tag will be tested.
	      With this	option,	hosts with no NET: tag	are  included  in  the
	      test, so that all	hosts that either have a matching NET: tag, or
	      no NET: tag at all are tested.

	      Used with	the Xymon extension. This	option
	      determines  how  long  failed  tests remain in the frequent-test
	      queue. The default is 1800 seconds (30 minutes).

	      Causes xymonnet to generate a warning if the run-time of	xymon-
	      net  exceeds  N  seconds.	 By  default  N	is set to the value of
	      TASKSLEEP, so a warning triggers if  the	network	 tests	cannot
	      complete	in  the	time given for one cycle of the	xymonnet task.
	      Apart from the warning, this option has no effect, i.e. it  will
	      not  terminate  xymonnet	prematurely.  So to eliminate any such
	      warnings,	use this option	with a very high value of N.

	      Warn if the response from	a TCP test is more than	N  bytes.   If
	      you  see	from the xymonnet status report	that you are transfer-
	      ring large amounts of data for your tests, you can  enable  this
	      option to	see which tests	have large replies.
	      Default: 0 (disabled).

	      Make the test results valid for N	minutes	before they go purple.
	      By default test results are valid	for 30 minutes;	if you run xy-
	      monnet  less  often than that, the results will go purple	before
	      the next run of xymonnet.	This option lets you change  how  long
	      the status is valid.

	      On  multi-homed hosts, this option can be	used to	explicitly se-
	      lect the source IP address used for the network  tests.	"IPAD-
	      DRESS" must be a valid IP-address	on the host running xymonnet.

	      Instead  of  reading  the	hosts.cfg file,	xymonnet will load the
	      hosts.cfg	configuration from the xymond daemon. This  eliminates
	      the  need	 for reading the hosts.cfg, and	if you have xymond and
	      xymonnet running on different hosts, it also eliminates the need
	      for  copying  the	 hosts.cfg file	between	systems. Note that the
	      "netinclude" option in hosts.cfg is ignored when this option  is

	      When  testing  well-known	 services (e.g.	FTP, SSH, SMTP,	POP-2,
	      POP-3, IMAP, NNTP	and rsync), xymonnet will  look	 for  a	 valid
	      service-specific	"OK"  response.	 If  another response is seen,
	      this will	cause the test to report a  warning  (yellow)  status.
	      Without this option, the response	from the service is ignored.
	      The  optional  color-name	 is  used to select a color other than
	      yellow for the status message when the response is wrong.	  E.g.
	      "--checkresponse=red"  will  cause  a "red" status message to be
	      sent when	the service does not respond as	expected.

	      By default, xymonnet sends some extra information	in the	status
	      messages,	 called	 "flags".  These  are used by xymongen e.g. to
	      pick different icons for reversed	tests when generating the  Xy-
	      mon  webpages.  This option makes	xymonnet omit these flags from
	      the status messages.

	      By default, TCP tests run	roughly	in the order  that  the	 hosts
	      are listed in the	hosts.cfg file.	If you have many tests for one
	      server, this may result in an exceptionally large	load when  Xy-
	      mon  is  testing it because Xymon	will perform a lot of tests at
	      the same time. To	avoid this, the	--shuffle option reorders  the
	      sequence	of tests so they are spread randomly across all	of the
	      servers tested.

       Note: xymonnet uses the program defined by the FPING environment	to ex-
       ecute  ping-tests  -  by	default, that is the xymonping(1) utility. See
       xymonserver.cfg(5) for a	description of how to customize	this, e.g.  if
       you need	to run it with "sudo" or a similar tool.

       --ping Enables xymonnet's ping test. The	column name used for ping test
	      results is defined by the	PINGCOLUMN environment variable	in xy-
	      If  not  specified, xymonnet uses	the CONNTEST environment vari-
	      able to determine	if it should perform the ping test or not.  So
	      if  you prefer to	use another tool to implement ping checks, ei-
	      ther set the CONNTEST environment	variable to false, or run  xy-
	      monnet with the "--noping".

	      Disable the connectivity test.


	      Enable/disable  the  use	of  traceroute when a ping-test	fails.
	      Performing a traceroute for failed ping tests is a  slow	opera-
	      tion,  so	 the default is	not to do any traceroute, unless it is
	      requested	on a  per-host	basis  via  the	 "trace"  tag  in  the
	      hosts.cfg(5)  entry  for each host. The "--trace"	option changes
	      this, so the default becomes to  run  traceroute	on  all	 hosts
	      where  the  ping test fails; you can then	disable	it on specific
	      hosts by putting a "notrace" tag on the host-entry.

	      Spread the task of pinging the hosts over	N  processes.  If  you
	      have  a very large number	of hosts the time it takes to ping all
	      of them can be substantial, even with  the  use  of  tools  like
	      fping or xymonping that ping many	hosts in parallel. This	option
	      causes xymonnet to start N separate  ping	 processes,  the  IP's
	      that are being ping'ed will be divided evenly between these pro-

	      Determines the name of the column	 Xymon	displays  for  content
	      checks.	The  default  is  "content".   If  you	have  used the
	      ""	or "" scripts earlier, you  may	 want  to  use
	      "--content=cont"	to  report  content checks using the same test
	      name as these scripts do.

	      Adhere to	the Big	Brother	syntax for a URL, which	allows	speci-
	      fying  a	HTTP  proxy  as	 part  of a URL. See "HTTP Testing via
	      proxy" in	the hosts.cfg(5) file for details. Beginning with  Xy-
	      mon  4.3.0,  this	 behaviour  is disabled	by default since URL's
	      that include other URL's are now much more common.  This	option
	      restores the old Big Brother-compatible behaviour.

	      Determines  the  name  of	 the column Xymon displays for the SSL
	      certificate checks.  The default is "sslcert".

	      Disables reporting of the	SSL certificate	check.


	      Determines the number of days before an SSL certificate expires,
	      where  xymonnet  will generate a warning or alarm	status for the
	      SSL certificate column.

	      Enables checking that the	encryption supported by	the SSL	proto-
	      col  uses	an encryption key of at	least N	bits.  E.g. to trigger
	      an alert if your SSL-enabled website supports less than 128 bits
	      of  encryption,  use "--sslbits=128".  Note: This	can be enabled
	      on  a  per-host  basis  using   the   "sslbits=N"	  setting   in

	      Enables checking of the length of	the public key in SSL certifi-
	      cates.  N	is the minimum size of the SSL public  key,  typically
	      such  keys  are  2048  bits, but some older certificates may use
	      keys with	1024 bits or less. If you specify this,	 SSL  certifi-
	      cates  with  keys	 less than N bits will result in the "sslcert"
	      status going yellow.  Default: 0,	i.e. this check	is disabled.

	      Do not show encryption cipher details on the "sslcert" status.

	      List ALL locally available encryption ciphers on	the  "sslcert"

	      Sets  the	 default  for  whether SSL connections use SNI (Server
	      Name Indication).	This can also be set with the "sni" or "nosni"
	      options in hosts.cfg for each host - the hosts.cfg entries over-
	      ride this	 option.  Default: off

	      Don't send any status updates to the Xymon server. Instead,  all
	      messages are dumped to stdout.

	      Causes  xymonnet	to collect information about the time spent in
	      different	parts of the program.  The information is  printed  on
	      stdout  just before the program ends. Note that this information
	      is also included in the status report sent with  the  "--report"

	      Dumps a bunch of status about the	tests as they progress to std-

	      Dumps internal memory structures before and/or after  the	 tests
	      have executed.

       --help or -?
	      Provide a	summary	of available command-line options.

	      Prints the version number	of xymonnet

	      Dump  the	 list  of  defined  TCP	services xymonnet knows	how to
	      test. Do not run any tests.

       If the file $XYMONHOME/etc/cookies exist, cookies  will	be  read  from
       this file and sent along	with the HTTP requests when checking websites.
       This file  is  in  the  Netscape	 Cookie	 format,  see  for details on this format. The
       curl(1) utility can output a file  in  this  format  if	run  with  the
       "--cookie-jar FILENAME" option.

       When  xymonnet  tests services that use SSL- or TLS-based protocols, it
       will check that the server certificate has not expired. This check hap-
       pens  automatically for https (secure web), pop3s, imaps, nntps and all
       other SSL-enabled services (except ldap,	see LDAP TESTS below).

       All certificates	found for a host are reported in one status message.

       Note: On	most systems, the end-date of the certificate  is  limited  to
       Jan  19th, 2038.	If your	certificate is valid after this	date, xymonnet
       will report it as valid only until Jan 19, 2038.	This is	due to limita-
       tions	 in	your	 operating     system	  C    library.	   See .

       ldap testing can	be done	in two ways. If	you  just  put	an  "ldap"  or
       "ldaps" tag in hosts.cfg, a simple test is performed that just verifies
       that it is possible to establish	a connection to	the port  running  the
       ldap service (389 for ldap, 636 for ldaps).

       Instead	you can	put an LDAP URI	in hosts.cfg. This will	cause xymonnet
       to initiate a full-blown	LDAP session with the server, and do  an  LDAP
       search  for the objects defined by the URI. This	requires that xymonnet
       was built with LDAP support, and	relies on an existing LDAP library  to
       be installed.  It has been tested with OpenLDAP 2.0.26 (from Red	Hat 9)
       and 2.1.22.  The	Solaris	8 system ldap library has also been  confirmed
       to work for un-encrypted	(plain ldap) access.

       The  format  of	LDAP URI's is defined in RFC 2255. LDAP	URLs look like


	 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.


       All "bind" operations to	LDAP servers use simple	authentication.	  Ker-
       beros  and SASL are not supported. If your LDAP server requires a user-
       name/password,  use  the	 "ldaplogin"  tag   to	 specify   this,   cf.
       hosts.cfg(5) If no username/password information	is provided, an	anony-
       mous bind will be attempted.

       SSL support requires both a client library and an LDAP server that sup-
       port  LDAPv3; it	uses the LDAP "STARTTLS" protocol request after	estab-
       lishing a connection to the standard (non-encrypted) LDAP port (usually
       port  389). It has only been tested with	OpenSSL	2.x, and probably will
       not work	with any other LDAP library.

       The older LDAPv2	experimental method of tunnelling normal LDAP  traffic
       through	an  SSL	 connection - ldaps, running on	port 636 - is not sup-
       ported, unless someone can explain how to get the OpenLDAP  library  to
       support it. This	method was never formally described in an RFC, and im-
       plementations of	it are non-standard.

       For a discussion	of the various ways of running encrypted ldap, see

       When testing LDAP URI's,	all of the communications are handled  by  the
       ldap  library. Therefore, it is not possible to obtain the SSL certifi-
       cate used by the	LDAP server, and it will not show up in	the  "sslcert"

       If  you	have more than one system running network tests	- e.g. if your
       network is separated by firewalls - then	is is problematic to  maintain
       multiple	 hosts.cfg  files  for each of the systems.  xymonnet supports
       the NET:location	tag in hosts.cfg(5) to distinguish between hosts  that
       should be tested	from different network locations. If you set the envi-
       ronment variable	XYMONNETWORK e.g. to "dmz"  before  running  xymonnet,
       then  it	 will  only test hosts that have a "NET:dmz" tag in hosts.cfg.
       This allows you to keep all of your hosts in the	same  hosts.cfg	 file,
       but test	different sets of hosts	by different systems running xymonnet.

       xymonnet	 first reads the protocols.cfg file to see which network tests
       are defined. It then scans the hosts.cfg	file, and collects information
       about  the  TCP service tests that need to be tested. It	picks out only
       the tests that were listed in the protocols.cfg file, plus  the	"dns",
       "dig" and "ntp" tests.

       It  then	 runs  two  tasks  in  parallel:  First, a separate process is
       started to run the "xymonping" tool for the connectivity	 tests.	 While
       xymonping  is  busy  doing  the "ping" checks, xymonnet runs all	of the
       TCP-based network tests.

       All of the TCP-based service checks are handled by a connection	tester
       written specifically for	this purpose. It uses only standard Unix-style
       network programming, but	relies on the Unix "select(2)" system-call  to
       handle many simultaneous	connections happening in parallel. Exactly how
       many parallel connections are being used	depends	on your	operating sys-
       tem  -  the  default is FD_SETSIZE/4, which amounts to 256 on many Unix

       You can choose the number of concurrent connections with	the "--concur-
       rency=N"	option to xymonnet.

       Connection attempts timeout after 10 seconds - this can be changed with
       the "--timeout=N" option.

       Both of these settings play a part in deciding  how  long  the  testing
       takes. A	conservative estimate for doing	N TCP tests is:

	  (1 + (N / concurrency)) * timeout

       In  real	life it	will probably be less, as the above formula is for ev-
       ery test	to require a timeout. Since the	most normal use	of Xymon is to
       check  for  services  that are active, you should have a	lot less time-

       The "ntp" and "rpcinfo" checks rely on external	programs  to  do  each

	      Defines the network segment where	xymonnet is currently running.
	      This is used to filter out only the entries in the  hosts.cfg(5)
	      file  that  have	a matching "NET:LOCATION" tag, and execute the
	      tests for	only those hosts.

	      Defines the maximum number of status messages that can  be  sent
	      in one combo message. Default is 0 - no limit.
	      In  practice,  the maximum size of a single Xymon	message	sets a
	      limit - the default value	for the	maximum	message	size is	32 KB,
	      but  that	will easily accommodate	100 status messages per	trans-
	      mission. So if you want to experiment with this setting, I  sug-
	      gest starting with a value of 10.

	      Defines a	a delay	(in microseconds) after	each message is	trans-
	      mitted to	the Xymon server. The default is  0,  i.e.   send  the
	      messages as fast as possible.  This gives	your Xymon server some
	      time to process the message before the next  message  comes  in.
	      Depending	on the speed of	your Xymon server, it may be necessary
	      to set this value	to half	a second or even 1 or 2	seconds.  Note
	      that  the	value is specified in MICROseconds, so to define a de-
	      lay of half a second, this must be set to	the value "500000";  a
	      delay  of	1 second is achieved by	setting	this to	"1000000" (one

       FPING  Command used to run the xymonping(1) utility. Used  by  xymonnet
	      for  connectivity	 (ping)	 testing.   See	xymonserver.cfg(5) for
	      more information about how to customize the program that is exe-
	      cuted to do ping tests.

	      Location	of  the	 traceroute(8)	utility, or an equivalent tool
	      e.g.  mtr(8).  Optionally	used when a connectivity test fails to
	      pinpoint the network location that is causing the	failure.

	      Location of the ntpdate(1) utility. Used by xymonnet when	check-
	      ing the "ntp" service.

	      Location of the rpcinfo(8) utility. Used	by  xymonnet  for  the
	      "rpc" service checks.

	      This file	contains definitions of	TCP services that xymonnet can
	      test. Definitions	for a default set of common services is	 built
	      into  xymonnet,  but  these can be overridden or supplemented by
	      defining	services  in  the  protocols.cfg  file.	  See	proto-
	      cols.cfg(5) for details on this file.

       $XYMONHOME/etc/netrc - authentication data for password-protected webs
	      If  you have password-protected sites, you can put the usernames
	      and passwords for	these here. They will then get picked up auto-
	      matically	 when running your network tests.  This	works for web-
	      sites that use the "Basic" authentication	scheme in  HTTP.   See
	      ftp(1) for details - a sample entry would	look like this
		 machine login fred password Wilma1
	      Note  that  the  machine-name  must  be  the name	you use	in the
	      http://machinename/ URL setting -	it need	not be the one you use
	      for the system-name in Xymon.

	      This  file  may  contain	website	 cookies, in the Netscape HTTP
	      Cookie format. If	a website  requires  a	static	cookie	to  be
	      present  in  order  for  the check to complete, then you can add
	      this cookie to this file,	and it will be	sent  along  with  the
	      HTTP request. To get the cookies into this file, you can use the
	      "curl --cookie-jar FILE"	to  request  the  URL  that  sets  the

       $XYMONTMP/*.status - test status	summary
	      Each  time xymonnet runs,	if any tests fail (i.e.	they result in
	      a	red status) then they will be listed  in  a  file  name	 TEST-
	      NAME.[LOCATION].status. The LOCATION part	may be null. This file
	      is used to determine how long the	failure	has lasted,  which  in
	      turn  decides  if	this test should be included in	the tests done
	      It is also used internally  by  xymonnet	when  determining  the
	      color for	tests that use the "badconn" or	"badTESTNAME" tags.

	      This  file  contains the hostnames of those hosts	that should be
	      retested by the test	tool.  It  is  updated
	      only  by	xymonnet during	the normal runs, and read by xymonnet-

       hosts.cfg(5),   protocols.cfg(5),   xymonserver.cfg(5),	 xymonping(1),
       curl(1),	ftp(1),	fping(1), ntpdate(1), rpcinfo(8)

Xymon			  Version 4.3.30:  4 Sep 2019		   XYMONNET(1)


Want to link to this manual page? Use this URL:

home | help