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

FreeBSD Manual Pages

  
 
  

home | help
CFGMAKER(1)			     mrtg			   CFGMAKER(1)

NAME
       cfgmaker	- Creates mrtg.cfg files (for mrtg-2.17.4)

SYNOPSIS
       cfgmaker	[options] [community@]router [[options]	[community@]router
       ...]

OPTIONS
	--ifref=nr    interface	references by Interface	Number (default)
	--ifref=ip		       ... by Ip Address
	--ifref=eth			   ... by Ethernet Number
	--ifref=descr			   ... by Interface Description
	--ifref=name			   ... by Interface Name
	--ifref=type			   ... by Interface Type
		       You may also use	multiple options separated by commas,
		      in which case the	first available	one is used:
		      e.g.  --ifref=ip,name,nr

	--ifdesc=nr	  interface description	uses Interface Number (default)
	--ifdesc=ip			   ... uses Ip Address
	--ifdesc=eth			   ... uses Ethernet Number
	--ifdesc=descr			   ... uses Interface Description
	--ifdesc=name			   ... uses Interface Name
	--ifdesc=catname		   ... uses CatOS Interface Name
	--ifdesc=ppname			   ... uses Passport Port Name
	--ifdesc=alias			   ... uses Interface Alias
	--ifdesc=type			   ... uses Interface Type
		       You may also use	multiple options separated by commas,
		      in which case the	first available	one is used:
		      e.g.  --ifdesc=catname,ppname,descr,alias,ip,name,nr

	--if-filter=f	  Test every interface against filter f	to decide wether
			  or not to include that interface into	the collection.
			  Currently f is being evaluated as a Perl expression
			  and it's truth value is used to reject or accept the
			  interface.
			  (Experimental, under development, might change)

	--if-template=templatefile
			  Replace the normal target entries for	the interfaces
			  with an entry	as specified by	the contents in	the file
			  templatefile.	 The file is supposed to contain Perl
			  code to be executed to generate the lines for	the
			  target in the	configuration file.
			  (Experimental, under development, might change)

	--host-template=templatefile
			  In addition to creating targets for a	host's interfaces
			  do also create targets for the host itself as	specified
			  by the contents in the file templatefile.  The file is
			  supposed to contain Perl code	to be executed to generate
			  the lines for	the host related targets (such as CPU,
			  ping response	time measurements etc.)	in the config-
			  uration file.
			  (Experimental, under development, might change)

	--global "x: a"	  add global config entries

	--no-down	  do not look at admin or opr status of	interfaces

	--show-op-down	  show interfaces which	are operatively	down

	--zero-speed=spd  use this speed in bits-per-second as the interface
			  speed	for all	interfaces that	return a speed of 0
			  via ifSpeed/ifHighSpeed.  100Mbps = 100000000

	--subdirs=format  give each router its own subdirectory, naming	each per
			  "format", in which HOSTNAME and SNMPNAME will	be
			  replaced by the values of those items	-- for instance,
			  --subdirs=HOSTNAME or	--subdirs="HOSTNAME (SNMPNAME)"

	--noreversedns	  do not reverse lookup	ip numbers

	--community=cmty  Set the default community string to "cmty" instead of
			  "public".

	--enable-ipv6	  Enable IPv6 support, if the required libraries are
			  present. Numeric IPv6	addresses must be enclosed
			  in square brackets, e.g. public@[2001:760:4::1]:161

	--use-16bit	  Use 16bit SNMP request IDs to	query all routers.

	--snmp-options=:[<port>][:[<tmout>][:[<retr>][:[<backoff>][:<ver>]]]]

			  Specify default SNMP options to be appended to all
			  routers following.  Individual fields	can be empty.
			  Routers following might override some	or all of the
		  options given	to --snmp-options.

	--dns-domain=domain
		  Specifies a domain to	append to the name of all
		  routers following.

	--nointerfaces	  Don't	do generate any	configuration lines for	interfaces,
			  skip the step	of gathering interface information and
			  don't	run any	interface template code.

	--interfaces	  Generate configuration lines for interfaces (this is the
			  default).  The main purpose of this option is	to negate
			  an --nointerfaces appearing earlier on the command line.

	--help		  brief	help message
	--man		  full documentation
	--version	  print	the version of cfgmaker

	--output=file	  output filename default is STDOUT

DESCRIPTION
       Cfgmaker	creates	MRTG configuration files based on information pulled
       from a router or	another	SNMP manageable	device.

       [community@]router

       Community is the	community name of the device you want to create	a
       configuration for. If not specified, it defaults	to 'public'; you might
       want to try this	first if you do	not know the community name of a
       device. If you are using	the wrong community name you will get no
       response	from the device.

       Router is the DNS name or the IP	number of an SNMP-managable device.
       Following the name you can specify 6 further options separated by
       colons.	The full syntax	looks like this:

       router[:[prt][:[tmout][:[retr][:[backoff][:vers]]]]]

       Of special interest may be the last parameter, vers.  If	you set	this
       to '2' then your	device will be queried with SNMP version 2 requests.
       This allows you to poll the 64 bit traffic counters in the device and
       will thus work much better with fast interfaces (no more	counter
       overrun).  Note that the	order in which the routers are specified on
       the command line	do matter as the same order is used when the
       configuration file is generated.	 The first specified router has	it's
       configuration lines genrated first, followed by the lines belonging to
       the next	router and so on.

       Note that the first line	of the generated cfg file will contain all the
       commandline options you used for	generating it. This is to allow	for
       the easy	'regeneration' in case you want	to add newhosts	or make	some
       other global change.

   Configuration
       Except for the --output and --global options, all options affect	only
       the routers following them on the command line.	If an option specified
       earlier on the command line reappears later on the command line with
       another value, the new value overrides the old value as far as
       remaining routers are concerned.	 This way options might	be tailored
       for groups of routers or	for individual routers.

       See --output and	--global for how their behaviour is affected by	where
       or how many times they appear on	the command line.

       See the Examples	below on how to	set an option differently for multiple
       routers.

       --help
	   Print a brief help message and exit.

       --man
	   Prints the manual page and exits.

       --version
	   Print the version of	cfgmaker.  This	should match the version of
	   MRTG	for which config files are being created.

       --ifref nr|ip|eth|descr|name
	   Select the interface	identification method.	Default	is nr which
	   identifies the router interfaces by their number.  Unfortunately
	   the interface numbering scheme in an	SNMP tree can change. Some
	   routers change their	numbering when new interfaces are added,
	   others change thier numbering every full moon just for fun.

	   To work around this sad problem MRTG	can identify interfaces	by 4
	   other properties. None of these works for all interfaces, but you
	   should be able to find one which does fine for you. Note that
	   especially ethernet addrsses	can be problematic as some routers
	   have	the same ethernet address on most of their interface cards.

	   Select ip to	identify the interface by its IP number. Use eth to
	   use the ethernet address for	identification.	Use descr to use the
	   Interface description. Or use name to use the Interface name.

	   You can specify multiple properties if you wish, separated by
	   commas.  In this case, cfgmaker will	use the	first item in the list
	   which can provide unique identification.  This allows you to
	   specify, for	example, to use	IP address and to use ifName if	this
	   is not defined:
	     --ifref ip,name

	   If your chosen method does not allow	unique interface
	   identification on the device	you are	querying, cfgmaker will	tell
	   you about it.

       --ifdesc	nr|ip|eth|descr|name|type|alias
	   Select what to use as the description of the	interface.  The
	   description appears in the "Title[]"	property for the target	as
	   well	as the text header in the HTML code defined in the target's
	   "PageTop[]".	 Default is to use nr which is just the	interface
	   number which	isn't always useful to the viewer of the graphs.

	   There are 6 other properties	which could be used.  Use ip if	you
	   want	to use the interface's IP-address.  Use	eth if you want	to use
	   the interface's ethernet address.  If you want a better
	   description,	you can	use either descr, name or alias.  Exactly what
	   each	of these do varies between different equipment so you might
	   need	to experiment.	For instance, for a serial interface on	a
	   Cisco router	running	IOS using name might result in "S0" being the
	   interface description , descr might result in "Serial0" and alias
	   might result	in "Link to HQ"	(provided that is what is used as the
	   interface's "description" in	the router's configuration).

	   Finally, if you want	to describe the	interface by it's Btype	(i.e
	   "ethernetCSMA", "propPointtoPoint" etc) you can use type.

	   You can specify multiple properties if you wish, separated by
	   commas.  In this case, cfgmaker will	use the	first item in the list
	   which is available for this interface.  This	allows you to specify,
	   for example,	to use any of the different aliases in order of
	   preference.

       --if-filter 'filter-expression'
	   First of all, this is under some development	and is experimental.

	   Use this if you want	to have	better control over what interfaces
	   gets	included into the configuration.  The filter-expression	is
	   evaluated as	a piece	of Perl	code and is expected to	return a truth
	   value.  If true, include the	interface and if false,	exclude	the
	   interface.

	   For a further discussion on how these filters work, see the section
	   "Details on Filters"	below.

       --if-template template-file
	   First of all, this is under some development	and is experimental.

	   Use this if you want	to control what	the line for each target
	   should look like in the configuration file.	The contents of	the
	   file	template-file will be evaluated	as a Perl program which
	   generates the lines using certain variables for input and output.

	   For a further discussion on how these templates work, see the
	   section "Details on Temaplates" below.

       --host-template template-file
	   First of all, this is under some development	and is experimental.

	   Use this if you want	to have	some extra targets related to the host
	   itself such as CPU utilization, ping	response time to the host,
	   number of busy modems etc.  The contents of the file	template-file
	   will	be evaluated once per host as a	Perl program which generates
	   the lines using certain variables for input and output.

	   For a further discussion on how these templates work, see the
	   section "Details on Templates" below.

       --community community-string
	   Use this to set the community for the routers following on the
	   command line	to community-string.  Individual routers might
	   overrride this community string by using the	syntax
	   community@router.

       --enable-ipv6
	   This	option enables IPv6 support. It	requires the appropriate perl
	   modules; if they are	not found then IPv6 is disabled	(see the ipv6
	   documentation).

	   cfgmaker will use IPv6 or IPv4 depending on the target. If the
	   target is a numeric address,	the protocol depends on	the type of
	   address. If the target is a hostname, cfgmaker will try to resolve
	   the name first to an	IPv6 address then to an	IPv4 address.

	   IPv6	numeric	addresses must be specified between square braces.

	   For example:

	    cfgmaker --enable-ipv6 [2001:760:4::1]:165:::2

	   If the target has both an IPv6 address and an IPv4 address with the
	   same	hostname, cfgmaker first queries the target using IPv6 and
	   falls back to IPv4 if it fails. This	is useful for targets which
	   don't support SNMP over IPv6.

       --use-16bit
	   This	option forces the use of 16bit SNMP request IDs.  Some broken
	   SNMP	agents do not accept 32bit request IDs.	 Try to	avoid this
	   option as much as possible, complain	to your	agent vendor instead.

       --snmp-options  :[port][:[timeout][:[retries][:[backoff][:version]]]]
	   Use this to set the default SNMP options for	all routers following
	   on the command line.	 Individual values might be omitted as well as
	   trailing colons.  Note that routers might override individual (or
	   all)	values specified by --snmp-options by using the	syntax

	   router[:[port][:[timeout][:[retries][:[backoff][:version]]]]]

       --global	"bla: abc"
	   Use this to add global options to the generated config file.	 You
	   can call --global several times to add multiple options.  The line
	   will	appear in the configuration just before	the config for the
	   next	router appearing on the	command	line.

	    --global "workdir: /home/mrtg"

	   If you want some default Options you	might want to put

	    --global "options[_]: growright,bits"

	   Specifying --global after the last router on	the command line will
	   create a line in the	configuration file which will appear after all
	   the routers.

       --noreversedns
	   Do not try to reverse lookup	IP numbers ... a must for DNS free
	   environments.

       --no-down
	   Normally cfgmaker will not include interfaces which are marked
	   anything but	administratively and operationally UP. With this
	   switch you get them all.

       --show-op-down
	   Include interfaces which are	operatively down.

       --zero-speed speed
	   Assign this speed in	bits-per-second	to all interfaces which	return
	   0 for ifSpeed and ifHighSpeed.  Some	switches, notably Foundry
	   equipment, return a speed of	zero for some interfaces.  For
	   example, to have all	interfaces reporting zero set to 100Mbps, use
	   --zero-speed=100000000.

       --subdirs format
	   Give	each router its	own subdirectory for the HTML and graphics (or
	   .rrd) files.	 The directory name is the given format	string with a
	   couple of pattern replacements.  The	string "HOSTNAME" will be
	   replaced by the hostname of the router (however you specified it on
	   the cfgmaker	commandline -- it may be an actual hostname or just an
	   IP address),	and "SNMPNAME" will be replaced	with the device's idea
	   of its own name (the	same name that appears on the right side of
	   the "Title" lines).	For instance, a	call like:

	    cfgmaker --subdirs=HOSTNAME__SNMPNAME public@10.10.0.18

	   would result	in the generation of lines looking something like:

	    Directory[10.10.0.18_1]: 10.10.0.18__fp2200-bothrip-1.3

       --output	file
	   Write the output from cfgmaker into the file	file. The default is
	   to use "STDOUT". --output is	expected to appear only	once on	the
	   command line. If used multiple times, the file specified by the
	   last	--output will be used.

       --nointerfaces
	   Don't generate configuration	lines for interfaces.

	   This	makes cfgmaker skip all	steps related to interfaces which
	   means it will not do	any polling of the router to retrieve
	   interface information which speeds up the execution of cfgmaker and
	   it will neither run any interface templates.

       --interfaces
	   This	makes cfgmaker generate	configuration lines for	interfaces
	   (the	default	behaviour).

	   The main usage of this option is to negate an --nointerfaces
	   appearing earlier on	the command line.

   SNMP	V3 Options
       Cfgmaker	supports SNMP V3 using the Net:SNMP perl module.  There	are
       optional	parameters affecting SNMP operation.

       --enablesnmpv3 {yes|no}
	   The --enablesnmpv3 option is	an optional flag to check for the
	   presence of the Net::SNMP libraries.	 Cfgmaker will try to
	   determine whether this flag is required and will set	the values
	   automatically.

       SNMPv3 Arguments

       A SNMP context is a collection of management information	accessible by
       a SNMP entity.  An item of management information may exist in more
       than one	context	and a SNMP entity potentially has access to many
       contexts.  The combination of a contextEngineID and a contextName
       unambiguously identifies	a context within an administrative domain.  In
       a SNMPv3	message, the contextEngineID and contextName are included as
       part of the scopedPDU.  All methods that	generate a SNMP	message
       optionally take a --contextengineid and --contextname argument to
       configure these fields.

       Context Engine ID
	   The --contextengineid argument expects a hexadecimal	string
	   representing	the desired contextEngineID.  The string must be 10 to
	   64 characters (5 to 32 octets) long and can be prefixed with	an
	   optional "0x".  Once	the --contextengineid is specified it stays
	   with	the object until it is changed again or	reset to default by
	   passing in the undefined value.  By default,	the contextEngineID is
	   set to match	the authoritativeEngineID of the authoritative SNMP
	   engine.

       Context Name
	   The contextName is passed as	a string which must be 0 to 32 octets
	   in length using the --contextname argument.	The contextName	stays
	   with	the object until it is changed.	 The contextName defaults to
	   an empty string which represents the	"default" context.

       User-based Security Model Arguments

       The User-based Security Model (USM) used	by SNMPv3 requires that	a
       securityName be specified using the --username argument.	 The creation
       of a Net::SNMP object with the version set to SNMPv3 will fail if the
       --username argument is not present.  The	--username argument expects a
       string 1	to 32 octets in	length.

       Different levels	of security are	allowed	by the User-based Security
       Model which address authentication and privacy concerns.	 A SNMPv3
       target will derive the security level (securityLevel) based on which of
       the following arguments are specified.

       By default a securityLevel of 'noAuthNoPriv' is assumed.	 If the
       --authkey or --authpassword arguments are specified, the	securityLevel
       becomes 'authNoPriv'.  The --authpassword argument expects a string
       which is	at least 1 octet in length.  Optionally, the --authkey
       argument	can be used so that a plain text password does not have	to be
       specified in a script.  The --authkey argument expects a	hexadecimal
       string produced by localizing the password with the
       authoritativeEngineID for the specific destination device.  The
       "snmpkey" utility included with the Net::SNMP  distribution can be used
       to create the hexadecimal string	(see snmpkey).

       Two different hash algorithms are defined by SNMPv3 which can be	used
       by the Security Model for authentication.  These	algorithms are
       HMAC-MD5-96 "MD5" (RFC 1321) and	HMAC-SHA-96 "SHA-1" (NIST FIPS PUB
       180-1).	 The default algorithm used by the module is HMAC-MD5-96.
       This behavior can be changed by using the --authprotocol	argument.
       This argument expects either the	string 'md5' or	'sha' to be passed to
       modify the hash algorithm.

       By specifying the arguments --privkey or	--privpassword the
       securityLevel associated	with the object	becomes	'authPriv'.  According
       to SNMPv3, privacy requires the use of authentication.  Therefore, if
       either of these two arguments are present and the --authkey or
       --authpassword arguments	are missing, the creation of the object	fails.
       The --privkey and --privpassword	arguments expect the same input	as the
       --authkey and --authpassword arguments respectively.

       The User-based Security Model described in RFC 3414 defines a single
       encryption protocol to be used for privacy.  This protocol, CBC-DES
       "DES" (NIST FIPS	PUB 46-1), is used by default or if the	string 'des'
       is passed to the	--privprotocol argument.  By working with the Extended
       Security	Options	Consortium http://www.snmp.com/eso/, the module	also
       supports	additional protocols which have	been defined in	draft
       specifications.	The draft
       http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt defines
       the support of CBC-3DES-EDE "Triple-DES"	(NIST FIPS 46-3) in the	User-
       based Security Model.  This protocol can	be selected using the
       --privprotocol argument with the	string '3desede'.  The draft
       http://www.snmp.com/eso/draft-blumenthal-aes-usm-04.txt describes the
       use of CFB128-AES-128/192/256 "AES" (NIST FIPS PUB 197) in the USM. The
       three AES encryption protocols, differentiated by their key sizes, can
       be selected by passing 'aescfb128', 'aescfb192',	or 'aescfb256' to the
       -privprotocol argument.

   Details on Filters
       The purpose of the filters is to	decide which interfaces	to accept and
       which interfaces	to reject.  This decision is done for each interface
       by evaluating the filter	expression as a	piece of Perl code and
       investigating the result	of the evaluation.  If true, accept the
       interface otherwise reject it.

       When working with filters, remember that	Perl has it's own idea of what
       truth and false is.  The	empty string ""	and the	string "0" are false,
       all other strings are true.  This further imples	that any integer value
       of 0 is false as	well as	any undef value.  It also implies that all
       references are considered true.

       As the filter is	evaluated as a Perl expression,	several	useful
       constructs in Perl are worth mentioning:

       Expressions might be grouped by using parentheses "()".	Expressions
       might be	combined using boolean operators such as the following:

       "and" (equivalent with "&&")
	   Boolean "and" of the	two expressions, is only true if both
	   expressions are true.  Example: expression1 and expression2

       "or" (equivalent	with "||")
	   Boolean "or"	of the two expressions,	is true	if either or both
	   expressions are true.  Example: expression1 or expression2

       "not" (equivalent with "!")
	   Boolean negation of a single	expression.  Example:  not expression
	   .  Yet another example: !expression

       (For more details on this I recommend a book on Perl)

       Predefined Filter Variables

       To facilitate, there are	a number of predefined values available	to use
       in the filter.  Note that these variables are also available when
       templates interfaces are	evaluated (but not host	templates).

       Caveat:	All these variables' names begin with a	dollar sign  ($),
       which is	a syntactic requirement	for scalar variables in	Perl.  The
       danger here is that the dollar sign in many shells is an	active
       character (often	used for shell variables exactly as in Perl variables)
       so it is	important to ensure that the Perl expression isn't evaluated
       by the command line shell as shell code before being passed to cfgmaker
       as command line arguments.  In shells like Bourne shell,	ksh shell or
       bash shell, placing the entire expression within	single qoutes will
       avoid such accidental evaluation:

	'--if-filter=($default_iftype && $if_admin)'

       $if_type
	   This	is an integer specifying the interface type as per the SNMP
	   standards and as reported by	the polled device.  A complete list of
	   interface types would be impractical	for this document , but	there
	   are a number	predefined varables below.  Normally, cfgmaker puts in
	   the target's	PageTop	this iftype value within paranthesis after the
	   name	of the interface type. (e.g "propPointToPointSerial (22)").

	   Here's a list of some of the	most common interface types by number:

	      6	ethernetCsmacd
	      7	iso88023Csmacd
	      9	iso88025TokenRing
	     15	fddi
	     19	E1
	     20	basicISDN
	     21	primaryISDN
	     22	propPointToPointSerial
	     23	ppp
	     24	softwareLoopback
	     30	ds3
	     32	frame-relay
	     33	rs232
	     37	atm
	     39	sonet
	     44	frameRelayService
	     46	hssi
	     49	aal5
	     53	propVirtual
	     62	Fast Ethernet (100BaseT)
	     63	ISDN & X.25
	     69	Full Duplex Fast Ethernet (100BaseFX)
	     94	Asymetric Digital Subscriber Loop (ADSL)
	    117	Gigabit	Ethernet
	    134	ATM Sub	Interface

       $default
	   True	if and only if cfgmaker	normally should	accepted the interface
	   based on the	interfaces administrative and operational state
	   (taking the flags --no-down and --show-op-down into account)	and
	   it's	type (and a few	other things).

       $default_ifstate
	   True	if and only if cfgmaker	would have accepted the	interface
	   based on it's operational and administrative	states (also taking
	   into	account	the presence of	the flags --no-down and
	   --show-op-down).

       $default_iftype
	   True	if and only if cfgmaker	would have accepted the	interface
	   based on it's type (and a few type specific details in addition).

       $if_admin
	   True	if and only if the interface is	in an adminstrative up state.

       $if_oper
	   True	if and only if the interface is	in an operational up state.

       A number	of variables are also predefined to easily decide if an
       interface belong	to a certain cathegory or not.	Below is all those
       variables listed	together with which if_type numbers each variable will
       be true for.  Note that some variables refer to other variables as
       well.

       $if_is_ethernet
	   True	for ethernet interfaces	(nr 6, 7, 26, 62, 69 and 117).

       $if_is_isdn
	   True	for various ISDN interface types (nr 20, 21, 63, 75, 76	and
	   77)

       $if_is_dialup
	   True	for dial-up interfaces such as PPP as well as ISDN.  (nr 23,
	   81, 82 and 108 in addition to the numbers of	$if_is_isdn).

       $if_is_atm
	   True	for miscellaneous ATM related interface	types (nr 37, 49, 107,
	   105,	106, 114 and 134).

       $if_is_wan
	   True	for WAN	interfaces point to point, Frame Relay and High	Speed
	   Serial ( 22,32,44,46)

       $if_is_lan
	   True	for LAN	interfaces (8, 9, 11, 15, 26, 55, 59, 60 and 115 in
	   addition to the numbers of $if_is_ethernet).

       $if_is_dsl
	   True	for ADSL, RDSL,	HDSL and SDSL (nr 94, 95, 96, 97)

       $if_is_loopback
	   True	for software loopback interfaces (nr 24)

       $if_is_ciscovlan
	   True	for Cisco VLAN interfaces (interfaces with the word Vlan or
	   VLAN	in their ifdescs)

       $if_vlan_id
	   Returns the vlan id associated with a specific port on Cisco
	   Catalyst switches under both	Catalyst OS and	IOS, and 3Com
	   switches.  If it is not a vlan interface, will return undef.

       $if_cisco_trunk
	   Returns the trunking	state of a specific port on Cisco Catalyst
	   switches under both Catalyst	OS and IOS.  Returns "1" if the
	   interface is	a trunk, undef otherwise.

       $if_MTU
	   Returns the Maximum Transfer	Unit associated	with a specific	port.

       Besides that, you can also use the variables defined for	templates
       below.  Further,	all the	variables available in cfgmaker	is at the
       scripts disposal	even if	the use	of such	features is discouraged.  More
       "shortcuts" in the form of variables and	functions will be made
       available in the	future instead.

       Examples	on Filters

       The following filter will not affect which interfaces get's included or
       excluded, it will make cfgmaker behave as normally.

	'--if-filter=$default'

       The following filter will make cfgmaker exclude PPP (23)	interfaces:

	'--if-filter=$default && $if_type!=23'

       The following filter will make cfgmaker behave as usual except that it
       will consider the operational state of an interface irrelevant but
       still reject all	interfaces which are administratively down.

	'--if-filter=$if_admin && $default_iftype'

   Details on Templates
       The contents of the template files are evaluated	as a Perl program.  A
       number or Perl variables	are available for the program to read and
       others are used to be written to.

       As quite	a few of the predefined	variables has values which are are
       supposed	to be used in HTML code	some of	them have an "HTML-escaped"
       variant,	e.g $html_syslocation is the HTML escaped variant of
       $syslocation.  The HTML escaping	means that the chars "<", ">" and "&"
       are replaced by "&lt;", "&gt;" and "&amp;" and that newlines embedded
       in the string are prepended with	"<BR>" and appended with a space
       character (if a newline is last in the string it	is not touched).

       Writable	Template Variables

       These are the variables available to store the configuration lines in.
       Some of them are	initialized prior to the evaluation of the template
       but such	content	normally is comments for inclusion in the final
       configuration file so those variables might be reset to the empty
       string in the template code to eliminate	the comments.  The other way
       around is also possible,	the contents of	these variables	might be
       extended	with further information for various reasons such as debugging
       etc.

       Once the	template has been evaluated, the following happens:  if	the
       template	is a interface template	and the	actual interface for some
       reason is rejected and thus needs to be commented out, all the lines in
       the variable $target_lines are turned into comments by adding a hash
       mark ("#") at their beginning.  Then all	the variables $head_lines,
       $problem_lines ,	$target_lines and $separator_lines are concatenated
       together	to form	the lines to add to the	configuration file.

       $target_lines
	   This	variable is the	placeholder for	the configuration lines
	   created by the template.  $target_lines is predefined to be empty
	   when	the template code is evaluated.

       $head_lines
	   This	variable is intended to	be the placeholder for the comment
	   line	appearing just before the target in the	configuration file.
	   It is initialized with that comment line before the evaluation of
	   the template	code and if the	template doesn't modify	$head_lines
	   during evaluation, the comment will look like usual in the config
	   file.

       $problem_lines
	   This	variable is intended to	be the placholder for the comment
	   lines describing any	problems which might have been encountered
	   when	trying to add the target into the configuration.  For host
	   templates it's normally not used and	for those it's predefined as
	   the empty string.  For interface templates $problem_lines is
	   predefined with the error description comments which	cfgmaker
	   normally would use for rejected interfaces or as the	empty string
	   for accepted	interfaces.

	   It is possible to test against $problem_lines to find out if	an
	   interface will be included or rejected but this is not recommended.
	   Test	against	$if_ok instead.

       $separator_lines
	   This	variable is the	placeholder for	the string to use as the
	   separator between the code for individual targets.  The contents of
	   this	variable is put	after each target (so the lines	will appear
	   after the end of the	last target in the config as well).

       Predefined Template Variables

       All the variables below are available for interface templates to	use.
       For host	templates, only	those listed under "Host and System Variables"
       are available.

       For interface templates the variables listed under "Predefined Filter
       Variables" are also available.

       Host and	System Variables

       $router_name
	   This	is the fully qualified name for	the router.  It	is affected by
	   the following items on the command line:  the router	name itself
	   and --dns-domain.

       $router_connect
	   This	is the reference string	for the	router being polled.  It is on
	   the form community@router possibly followed by some snmp options.
	   It is affected by the following items on the	command	line:  the
	   router name itself, --community, --snmp-options and --dns-domain.
	   (There's no HTML escaped variant available)

       $directory_name
	   This	variable should	contain	the directory name as cfgmaker
	   normally would use as the value for the "Directory[]" directive.
	   The value is	determined by the --subdirs command line option.  If
	   --subdirs isn't specified $directory_name will be the empty string.
	   (There's no HTML escaped variant available)

       $syscontact
	   This	variable is the	router's SNMP sysContact value.	 (HTML escaped
	   variant: $html_syscontact)

       $sysname
	   This	variable is the	router's SNMP sysName value.  (No HTML escaped
	   variant available)

       $syslocation
	   This	variable is the	router's SNMP sysLocation value.  (HTML
	   escaped variant: $html_syslocation)

       $sysdescr
	   This	variable is the	router's SNMP sysDescr value.  It is normally
	   not used by cfgmaker	but might be useful in a template.  (HTML
	   escaped variant: $html_sysdescr)

       Interface Target	Related	Variables

       $target_name
	   This	is what	cfgmaker normally would	use as the the name of the
	   target.  The	target name is what is found within the	square
	   brackets, "[]", for target directives.  (There's no HTML escaped
	   variant available)

       $if_ref
	   This	the reference string for the interface.	 It is expected	to be
	   used	in the "Target[xyz]" directive to distinguish what interface
	   to use.  The	value of this variable is affected by the --ifref
	   command line	option.	 It is normally	used together with
	   $router_connect.  (There's no HTML escaped variant available)

       $if_ok
	   This	variable is true if the	interface is going to be included into
	   the configuration file, otherwise false.  Don't test	against	other
	   variables such as $problem_lines to find out	if an interface	will
	   be rejected or not, use this	$if_ok instead.

       $default_target_lines
	   This	variable contains all the target lines which cfgmaker by
	   default outputs for this interface.	It's useful if you want	to
	   have	the "standard target" but want to add some extra lines to it
	   by using a template.

       By default cfgmaker uses	the following directives for each target it
       generates: Target[], SetEnv[], MaxBytes[], Title[], PageTop[] and if
       there is	any directory specified	also the Directory[] directive.

       To facilitate the creation of templates which generates target configs
       which are similar to the	default	one, each of the above mentioned
       directive lines have a corresponding variable containing	the line as
       cfgmaker	would have output it by	default.

       Note that none of these have a HTML escaped variant, text in them is
       HTML escaped where needed.  Also	note that they do not have any newline
       at the end.

       $default_target_directive
	   This	variable contains the default string for the Target[]
	   directive line.

       $default_setenv_directive
	   This	variable contains the default string for the SetEnv[]
	   directive line.

       $default_directory_directive
	   This	variable contains the default string for the Directory[]
	   directive line which	means it is an empty string (with no newline)
	   if there's no directory.

       $default_maxbytes_directive
	   This	variable contains the default string for the MaxBytes[]
	   directive line.

       $default_title_directive
	   This	variable contains the default string for the Title[] directive
	   line.

       $default_pagetop_directive
	   This	variable contains the default string for the PageTop[]
	   directive lines.

       Interface Network Configuration Variables

       $if_ip
	   This	variable should	contain	the IP-address of the interface, if
	   any has been	assigned to it.	 (There's no HTML escaped variant
	   available)

       $ifindex
	   This	variable is the	SNMP ifIndex for the interface which per
	   definition always is	an integer.  (There's no HTML escaped variant
	   available)

       $if_index
	   Equivalent with $ifindex.

       $if_eth
	   Contains the	ethernet address of the	interface, if any.  (There's
	   no HTML escaped variant available)

       $if_speed
	   This	variable is the	speed in bytes/second (with prefixes).
	   (There's no HTML escaped variant available)

       $if_speed_str
	   This	variable is a cooked speed description which is	either in bits
	   or bytes depending on wether	or not the bits	option is active and
	   also	with the proper	prefix for the speed (k, M, G etc).  (No HTML
	   escaped variant available)

       $if_type_desc
	   This	variable is a textual description of the interface type.
	   (HTML escaped variant: $html_if_type_desc)

       $if_type_num
	   This	variable the integer value corresponding to the	interface type
	   (for	a listing for the value	for the	more common interface types,
	   see the section DETAILS ON FILTERS above).  (No HTML	escaped
	   variant available)

       $if_dns_name
	   This	is the DNS name	for the	interface.  (No	HTML escaped variant
	   available)

       Interface Name, Description and Alias Variables

       It might	seem confusing with both Name, Description and Alias in	this
       context and to some extent it is.  Name and Description are usually
       supported on most equipment but how they	are used varies, both between
       manufacturers as	well as	between	different cathegories of equipment
       from the	same manufacturer.  The	Alias is at least supported by Cisco
       IOS, and	that variable contains whatever	is used	in the IOS statement
       called "description" for	the interface (not to be confused with the
       SNMP variables for Description).

       For better control from the command line	consider $if_title_desc	which
       contents	are controlled by the --if-descr command line option.

       $if_snmp_descr
	   This	variable should	contain	the "raw" description of the interface
	   as determined by the	SNMP polling of	the router.  (HTML escaped
	   variant: $html_if_snmp_descr)

       $if_snmp_name
	   The "raw" name for the interface as provided	by SNMP	polling.
	   (HTML escaped variant: $html_if_snmp_name)

       $if_snmp_alias
	   The "raw" ifAlias for the interface as provided by SNMP polling.
	   (HTML escaped variant: $html_if_snmp_alias)

       $if_cisco_descr
	   The "raw" CiscolocIfDescr for the interface as provided by SNMP
	   polling.  (HTML escaped variant: $html_if_cisco_descr)

       $if_description
	   This	is the "cooked"	description string for the interface, taking
	   into	account	the SNMP values	found for the interface's RDescr,
	   ifAlias and CiscolocIfDescr.	 (HTML escaped variant:
	   $html_if_description)

       $if_title
	   The full string cfgmaker by default would have used for the Title[]
	   directive in	the configuration as well as the content of the
	   topmost H1 tag in the PageTop[].  Is	composed by the	contents of
	   $desc_prefix, $if_title_desc	and $sysname.

	   As $if_title	depends	on $if_title_desc, it is possible to
	   indirectly control $if_title	by using the command line option
	   --if-descr.

	   (HTML escaped variant: $html_if_title)

       $if_port_name
	   If the host is a Cisco Catalyst LAN switch, this variable is	the
	   name	of that	port.  (No HTML	escaped	variant	available)

       $if_pp_port_name
	   If the host is a Nortel Passport LAN	switch,	this variable is the
	   name	of that	port.  (No HTML	escaped	variant	available)

       $desc_prefix
	   This	variable is a prefix of	the description	of what	the target is
	   to use in the "Title[]" directive and in the	H1 section of the
	   "PageTop[]".	 Default is "Traffic analysis for ".  (HTML escaped
	   variant: $html_desc_prefix)

       $if_title_desc
	   This	is the description of the interface normally used by cfgmaker
	   as part of the variable $if_title.  The latter is used as the full
	   string in the "Title[]" directove and the H1	section	in the
	   PageTop[].

	   $if_title_desc is controlled	by the command line option --if-descr
	   which indirectly controls the contents of $if_title

	   (HTML escaped variant: $html_if_title_desc)

       Help Functions for Templates

       The following functions exists to facilitate the	writing	of host	and
       interface templates.

       html_escape(string)
	   html_escape() takes a string	as an argument and returns a new
	   string where	the following substitutions has	been done:  the	chars
	   "<",	">" and	"&" are	replaced by "&lt;", "&gt;" and "&amp;" and
	   that	newlines embedded in the string	are prepended with "<BR>" and
	   appended with a space character (newlines at	the end	of the string
	   are not touched).

       oid_pick($router_connect,$v3opt,"oid1","oid2"...)
	   This	function will try to poll each of the oids specified until it
	   is successful or has	run out	of oids. It will return	the name of
	   the first oid that worked or	undef if it is not successful

       Example Template	Files

       Template	Example	1: Eliminating Rejected	Targets	From Appearing

       This template file generates exactly the	same configuration code	per
       interface as cfgmaker does by default, with the exception that it
       eliminates all lines (comments as well as config	code) for an interface
       if the interface	happens	to be rejected.

	if(not $problem_lines)
	{
	  $target_lines	.= <<ECHO;

	Target[$target_name]: $if_ref:$router_connect
	SetEnv[$target_name]: MRTG_INT_IP="$if_ip" MRTG_INT_DESCR="$if_snmp_descr"
	ECHO

	  if ($directory_name) {
	      $target_lines .= "Directory[$target_name]: $directory_name\n";
	  }

	  $target_lines	.= <<ECHO;
	MaxBytes[$target_name]:	$if_speed
	Title[$target_name]: $html_desc_prefix$html_if_title_desc -- $sysname
	PageTop[$target_name]: <h1>$html_desc_prefix$html_if_title_desc	-- $sysname</h1>
		       <div id="sysdetails">
			       <table>
				       <tr>
					       <td>System:</td>
					       <td>$sysname in $html_syslocation</td>
				       </tr>
				       <tr>
					       <td>Maintainer:</td>
					       <td>$html_syscontact</td>
				       </tr>
				       <tr>
					       <td>Description:</td>
					       <td>$html_if_description</td>
				       </tr>
				       <tr>
					       <td>ifType:</td>
					       <td>$html_if_type_desc ($if_type_num)</td>
				       </tr>
				       <tr>
					       <td>ifName:</td>
					       <td>$html_if_snmp_name</td>
				       </tr>
	ECHO

	  $target_lines	.= <<ECHO if defined $if_port_name;
				       <tr>
					       <td>Port	Name:</td>
					       <td>$if_port_name</td>
				       </tr>
	ECHO

	  $target_lines	.= <<ECHO if defined $if_pp_port_name;
				       <tr>
					       <td>Port	Name:</td>
					       <td>$if_pp_port_name</td>
				       </tr>
	ECHO

	  $target_lines	.= <<ECHO;
				       <tr>
					       <td>Max Speed:</td>
					       <td>$if_speed_str</td>
				       </tr>
	ECHO

	  $target_lines	.= <<ECHO if $if_ip;
				       <tr>
					       <td>Ip:</td>
					       <td>$if_ip ($if_dns_name)</td>
				       </tr>
	ECHO

	  $target_lines	.= <<ECHO;
			       </table>
		       </div>
	ECHO
	} else {
	  $head_lines="";
	  $problem_lines="";
	  $target_lines="";
	  $separator_lines="";
	}

       Template	Example	2: Simplier Version of Example 1

       Example 1 was partly intended to	demonstrate how	to customize the
       generation of interface targets but also	to provide a hint of how the
       variables are used in the "default" template which one could consider
       that cfgmaker normally uses.

       If you're only intrested	in the easiest way of entirely eliminating
       those reject interfaces,	the template below would do the	job as well by
       using $default_target_lines.

	if($if_ok) {
	 $target_lines = $default_target_lines;
	} else {
	  $head_lines="";
	  $problem_lines="";
	  $target_lines="";
	  $separator_lines="";
	}

       Template	Example	3: Creating CPU	Targets	for Hosts

       Below is	an example of a	host template.

	$head_lines .= <<ECHO;
	#---------------------------------------------------------------------
	ECHO

	my $target_name	= $router_name . ".cpu";

	$target_lines .= <<ECHO;

	YLegend[$target_name]: Percentage CPU load
	ShortLegend[$target_name]: %
	Legend1[$target_name]: CPU load	in %
	Legend2[$target_name]:
	Legend3[$target_name]: Max Observed CPU	load
	Legend4[$target_name]:
	LegendI[$target_name]: &nbsp;CPU Load:
	LegendO[$target_name]:
	WithPeak[$target_name]:	ywm
	MaxBytes[$target_name]:	100
	Options[$target_name]: growright, gauge, nopercent
	Title[$target_name]: $router_name CPU load
	Target[$target_name]: 1.3.6.1.4.1.9.2.1.58.0&1.3.6.1.4.1.9.2.1.58.0:$router_connect
	PageTop[$target_name]: <h1>$router_name	CPU load</h1>
		       <div>
			       <table>
				       <tr>
					       <td>System:</td>
					       <td>$router_name	in $html_syslocation</td>
				       </tr>
				       <tr>
					       <td>Maintainer:</td>
					       <td>$html_syscontact</td>
				       </tr>
				       <tr>
					       <td>Description:</td>
					       <td>$html_sysdescr</td>
				       </tr>
				       <tr>
					       <td>Resource:</td>
					       <td>CPU.</td>
				       </tr>
			       </table>
		       </div>
	ECHO

EXAMPLES
       The first example creates a config file for router.place.xyz:  the
       router has the community	name public.  Interfaces get identified	by
       their IP	number.	 Two global options get	added to the config file.  The
       config file gets	redirected to mrtg.conf.  The '\' signs	at the end of
       the line	mean that this command should be written on a single line.

	cfgmaker --global "WorkDir: /home/tobi"		  \
		 --global "Options[_]: growright,bits"	  \
		 --ifref=ip				  \
		 public@router.place.xyz > mrtg.cfg

       Note: if	cfgmaker is not	in your	path, but you are in the directory
       where cfgmaker is stored, you can start it with ./cfgmaker

       The next	example	creates	a config file for four devices:
       router1.place.xyz, router2.place.xyz, switch1.place.xyz and
       switch2.place.xyz all with the community	public.

       The two routers will have --ifref set to	descr whilst the two switches
       will use	--ifref	set to name.  Further the routers will use --ifdesc
       set to alias and	switch1.place.xyz will use --ifdesc set	to descr
       whilst switch2.place.xyz	use name instead.

       Finally,	there will be two Options lines	inserted in the	configuration:
       One will	be in the beginning, whilst the	other will be inserted after
       the lines related to the	two routers but	before those lines related to
       the switches.

	cfgmaker --global "WorkDir: /home/tobi"		  \
		 --global "Options[_]: growright,bits"	  \
		 --ifref=descr				  \
		 --ifdesc=alias				  \
		 public@router1.place.xyz		  \
		 public@router2.place.xyz		  \
		 --global "Options[_]: growright"	  \
		 --ifref=name				  \
		 --ifdesc=descr				  \
		 public@switch1.place.xyz		  \
		 --ifdesc=name				  \
		 public@switch2.place.xyz > mrtg.cfg

       The next	example	demonstrates how to use	the --community,
       --snmp-options and --dns-domain to make the command line	simpler.  All
       the equipment will use the community hidden, except for the ppp-server
       which use community access.  All	equipment uses these SNMP options: 1s
       timeout,	1 retry	and SNMP version 2 (backoff and	port is	unspecified
       which means they	use the	default	values).  The exception	again is the
       ppp-server which	uses SNMP version 1.  Finally, all the equipment is
       part of the domain place.xyz, except for	the ppp-server which is	part
       of the domain remote.place.xyz.	Note that the latter is	achieved
       simply by specifying the	name of	the ppp-server to be ppp-server.remote
       .

	cfgmaker --global "WorkDir: /home/tobi"		  \
		 --global "Options[_]: growright,bits"	  \
		 --dns-domain=place.xyz			  \
		 --community=hidden			  \
		 --snmp-options=::1:1::2		  \
		 router1				  \
		 router2				  \
		 router3				  \
		 router4				  \
		 router5				  \
		 switch1				  \
		 switch2				  \
		 switch3				  \
		 switch4				  \
		 switch5				  \
		 switch6				  \
		 switch7				  \
		 access@ppp-server.remote:::::1	> mrtg.cfg

SEE ALSO
       mrtg-reference

AUTHOR
       Tobias Oetiker <tobi@oetiker.ch>	and Jakob Ilves
       <jakob.ilves@oracle.com>

LICENSE
       GNU General Public License

COPYRIGHT
       Cfgmaker	is Copyright 2000 by Tobias Oetiker <tobi@oetiker.ch>

2.17.4				  2012-01-12			   CFGMAKER(1)

NAME | SYNOPSIS | OPTIONS | DESCRIPTION | EXAMPLES | SEE ALSO | AUTHOR | LICENSE | COPYRIGHT

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

home | help