1CFGMAKER(1)                          mrtg                          CFGMAKER(1)
2
3
4

NAME

6       cfgmaker - Creates mrtg.cfg files (for mrtg-2.16.4)
7

SYNOPSIS

9       cfgmaker [options] [community@]router [[options] [community@]router
10       ...]
11

OPTIONS

13        --ifref=nr    interface references by Interface Number (default)
14        --ifref=ip                     ... by Ip Address
15        --ifref=eth                        ... by Ethernet Number
16        --ifref=descr                      ... by Interface Description
17        --ifref=name                       ... by Interface Name
18        --ifref=type                       ... by Interface Type
19                       You may also use multiple options separated by commas,
20                      in which case the first available one is used:
21                      e.g.  --ifref=ip,name,nr
22
23        --ifdesc=nr       interface description uses Interface Number (default)
24        --ifdesc=ip                        ... uses Ip Address
25        --ifdesc=eth                       ... uses Ethernet Number
26        --ifdesc=descr                     ... uses Interface Description
27        --ifdesc=name                      ... uses Interface Name
28        --ifdesc=catname                   ... uses CatOS Interface Name
29        --ifdesc=ppname                    ... uses Passport Port Name
30        --ifdesc=alias                     ... uses Interface Alias
31        --ifdesc=type                      ... uses Interface Type
32                       You may also use multiple options separated by commas,
33                      in which case the first available one is used:
34                      e.g.  --ifdesc=catname,ppname,descr,alias,ip,name,nr
35
36        --if-filter=f     Test every interface against filter f to decide wether
37                          or not to include that interface into the collection.
38                          Currently f is being evaluated as a Perl expression
39                          and it's truth value is used to reject or accept the
40                          interface.
41                          (Experimental, under development, might change)
42
43        --if-template=templatefile
44                          Replace the normal target entries for the interfaces
45                          with an entry as specified by the contents in the file
46                          templatefile.  The file is supposed to contain Perl
47                          code to be executed to generate the lines for the
48                          target in the configuration file.
49                          (Experimental, under development, might change)
50
51        --host-template=templatefile
52                          In addition to creating targets for a host's interfaces
53                          do also create targets for the host itself as specified
54                          by the contents in the file templatefile.  The file is
55                          supposed to contain Perl code to be executed to generate
56                          the lines for the host related targets (such as CPU,
57                          ping response time measurements etc.) in the config-
58                          uration file.
59                          (Experimental, under development, might change)
60
61        --global "x: a"   add global config entries
62
63        --no-down         do not look at admin or opr status of interfaces
64
65        --show-op-down    show interfaces which are operatively down
66
67        --zero-speed=spd  use this speed in bits-per-second as the interface
68                          speed for all interfaces that return a speed of 0
69                          via ifSpeed/ifHighSpeed.  100Mbps = 100000000
70
71        --subdirs=format  give each router its own subdirectory, naming each per
72                          "format", in which HOSTNAME and SNMPNAME will be
73                          replaced by the values of those items -- for instance,
74                          --subdirs=HOSTNAME or --subdirs="HOSTNAME (SNMPNAME)"
75
76        --noreversedns    do not reverse lookup ip numbers
77
78        --community=cmty  Set the default community string to "cmty" instead of
79                          "public".
80
81        --enable-ipv6     Enable IPv6 support, if the required libraries are
82                          present. Numeric IPv6 addresses must be enclosed
83                          in square brackets, e.g. public@[2001:760:4::1]:161
84
85        --use-16bit       Use 16bit SNMP request IDs to query all routers.
86
87        --snmp-options=:[<port>][:[<tmout>][:[<retr>][:[<backoff>][:<ver>]]]]
88
89                          Specify default SNMP options to be appended to all
90                          routers following.  Individual fields can be empty.
91                          Routers following might override some or all of the
92                  options given to --snmp-options.
93
94        --dns-domain=domain
95                  Specifies a domain to append to the name of all
96                  routers following.
97
98        --nointerfaces    Don't do generate any configuration lines for interfaces,
99                          skip the step of gathering interface information and
100                          don't run any interface template code.
101
102        --interfaces      Generate configuration lines for interfaces (this is the
103                          default).  The main purpose of this option is to negate
104                          an --nointerfaces appearing earlier on the command line.
105
106        --help            brief help message
107        --man             full documentation
108        --version         print the version of cfgmaker
109
110        --output=file     output filename default is STDOUT
111

DESCRIPTION

113       Cfgmaker creates MRTG configuration files based on information pulled
114       from a router or another SNMP manageable device.
115
116       [community@]router
117
118       Community is the community name of the device you want to create a
119       configuration for. If not specified, it defaults to 'public'; you might
120       want to try this first if you do not know the community name of a
121       device. If you are using the wrong community name you will get no
122       response from the device.
123
124       Router is the DNS name or the IP number of an SNMP-managable device.
125       Following the name you can specify 6 further options separated by
126       colons.  The full syntax looks like this:
127
128       router[:[prt][:[tmout][:[retr][:[backoff][:vers]]]]]
129
130       Of special interest may be the last parameter, vers.  If you set this
131       to '2' then your device will be queried with SNMP version 2 requests.
132       This allows to poll the 64 bit traffic counters in the device and will
133       thus work much better with fast interfaces (no more counter overrun).
134       Note that the order in which the routers are specified on the command
135       line do matter as the same order is used when the configuration file is
136       generated.  The first specified router has it's configuration lines
137       genrated first, followed by the lines belonging to the next router and
138       so on.
139
140       Note that the first line of the generated cfg file will contain all the
141       commandline options you used for generating it. This is to allow for
142       the easy 'regeneration' in case you want to add newhosts or make some
143       other global change.
144
145   Configuration
146       Except for the --output and --global options, all options affect only
147       the routers following them on the command line.  If an option specified
148       earlier on the command line reappears later on the command line with
149       another value, the new value overrides the old value as far as
150       remaining routers are concerned.  This way options might be tailored
151       for groups of routers or for individual routers.
152
153       See --output and --global for how their behaviour is affected by where
154       or how many times they appear on the command line.
155
156       See the Examples below on how to set an option differently for multiple
157       routers.
158
159       --help
160           Print a brief help message and exit.
161
162       --man
163           Prints the manual page and exits.
164
165       --version
166           Print the version of cfgmaker.  This should match the version of
167           MRTG for which config files are being created.
168
169       --ifref nr|ip|eth|descr|name
170           Select the interface identification method.  Default is nr which
171           identifies the router interfaces by their number.  Unfortunately
172           the interface numbering scheme in an SNMP tree can change. Some
173           routers change their numbering when new interfaces are added,
174           others change thier numbering every full moon just for fun.
175
176           To work around this sad problem MRTG can identify interfaces by 4
177           other properties. None of these works for all interfaces, but you
178           should be able to find one which does fine for you. Note that
179           especially ethernet addrsses can be problematic as some routers
180           have the same ethernet address on most of their interface cards.
181
182           Select ip to identify the interface by its IP number. Use eth to
183           use the ethernet address for identification. Use descr to use the
184           Interface description. Or use name to use the Interface name.
185
186           You can specify multiple properties if you wish, separated by
187           commas.  In this case, cfgmaker will use the first item in the list
188           which can provide unique identification.  This allows you to
189           specify, for example, to use IP address and to use ifName if this
190           is not defined:
191             --ifref ip,name
192
193           If your chosen method does not allow unique interface
194           identification on the device you are querying, cfgmaker will tell
195           you about it.
196
197       --ifdesc nr|ip|eth|descr|name|type|alias
198           Select what to use as the description of the interface.  The
199           description appears in the "Title[]" property for the target as
200           well as the text header in the HTML code defined in the target's
201           "PageTop[]".  Default is to use nr which is just the interface
202           number which isn't always useful to the viewer of the graphs.
203
204           There are 6 other properties which could be used.  Use ip if you
205           want to use the interface's IP-address.  Use eth if you want to use
206           the interface's ethernet address.  If you want a better
207           description, you can use either descr, name or alias.  Exactly what
208           each of these do varies between different equipment so you might
209           need to experiment.  For instance, for a serial interface on a
210           Cisco router running IOS using name might result in "S0" being the
211           interface description , descr might result in "Serial0" and alias
212           might result in "Link to HQ" (provided that is what is used as the
213           interface's "description" in the router's configuration).
214
215           Finally, if you want to describe the interface by it's Btype (i.e
216           "ethernetCSMA", "propPointtoPoint" etc) you can use type.
217
218           You can specify multiple properties if you wish, separated by
219           commas.  In this case, cfgmaker will use the first item in the list
220           which is available for this interface.  This allows you to specify,
221           for example, to use any of the different aliases in order of
222           preference.
223
224       --if-filter 'filter-expression'
225           First of all, this is under some developement and is experimental.
226
227           Use this if you want to have better control over what interfaces
228           gets included into the configuration.  The filter-expression is
229           evaluated as a piece of Perl code and is expected to return a truth
230           value.  If true, include the interface and if false, exclude the
231           interface.
232
233           For a further discussion on how these filters work, see the section
234           "Details on Filters" below.
235
236       --if-template template-file
237           First of all, this is under some development and is experimental.
238
239           Use this if you want to control what the line for each target
240           should look like in the configuration file.  The contents of the
241           file template-file will be evaluated as a Perl program which
242           generates the lines using certain variables for input and output.
243
244           For a further discussion on how these templates work, see the
245           section "Details on Temaplates" below.
246
247       --host-template template-file
248           First of all, this is under some development and is experimental.
249
250           Use this if you want to have some extra targets related to the host
251           itself such as CPU utilization, ping response time to the host,
252           number of busy modems etc.  The contents of the file template-file
253           will be evaluated once per host as a Perl program which generates
254           the lines using certain variables for input and output.
255
256           For a further discussion on how these templates work, see the
257           section "Details on Templates" below.
258
259       --community community-string
260           Use this to set the community for the routers following on the
261           command line to community-string.  Individual routers might
262           overrride this community string by using the syntax
263           community@router.
264
265       --enable-ipv6
266           This option enables IPv6 support. It requires the appropriate perl
267           modules; if they are not found then IPv6 is disabled (see the ipv6
268           documentation).
269
270           cfgmaker will use IPv6 or IPv4 depending on the target. If the
271           target is a numeric address, the protocol depends on the type of
272           address. If the target is a hostname, cfgmaker will try to resolve
273           the name first to an IPv6 address then to an IPv4 address.
274
275           IPv6 numeric addresses must be specified between square braces.
276
277           For example:
278
279            cfgmaker --enable-ipv6 [2001:760:4::1]:165:::2
280
281           If the target has both an IPv6 address and an IPv4 address with the
282           same hostname, cfgmaker first queries the target using IPv6 and
283           falls back to IPv4 if it fails. This is useful for targets which
284           don't support SNMP over IPv6.
285
286       --use-16bit
287           This option forces the use of 16bit SNMP request IDs.  Some broken
288           SNMP agents do not accept 32bit request IDs.  Try to avoid this
289           option as much as possible, complain to your agent vendor instead.
290
291       --snmp-options  :[port][:[timeout][:[retries][:[backoff][:version]]]]
292           Use this to set the default SNMP options for all routers following
293           on the command line.  Individual values might be omitted as well as
294           trailing colons.  Note that routers might override individual (or
295           all) values specified by --snmp-options by using the syntax
296
297           router[:[port][:[timeout][:[retries][:[backoff][:version]]]]]
298
299       --global "bla: abc"
300           Use this to add global options to the generated config file.  You
301           can call --global several times to add multiple options.  The line
302           will appear in the configuration just before the config for the
303           next router appearing on the command line.
304
305            --global "workdir: /home/mrtg"
306
307           If you want some default Options you might want to put
308
309            --global "options[_]: growright,bits"
310
311           Specifying --global after the last router on the command line will
312           create a line in the configuration file which will appear after all
313           the routers.
314
315       --noreversedns
316           Do not try to reverse lookup IP numbers ... a must for DNS free
317           environments.
318
319       --no-down
320           Normally cfgmaker will not include interfaces which are marked
321           anything but administratively and operationally UP. With this
322           switch you get them all.
323
324       --show-op-down
325           Include interfaces which are operatively down.
326
327       --zero-speed speed
328           Assign this speed in bits-per-second to all interfaces which return
329           0 for ifSpeed and ifHighSpeed.  Some switches, notably Foundry
330           equipment, return a speed of zero for some interfaces.  For
331           example, to have all interfaces reporting zero set to 100Mbps, use
332           --zero-speed=100000000.
333
334       --subdirs format
335           Give each router its own subdirectory for the HTML and graphics (or
336           .rrd) files.  The directory name is the given format string with a
337           couple of pattern replacements.  The string "HOSTNAME" will be
338           replaced by the hostname of the router (however you specified it on
339           the cfgmaker commandline -- it may be an actual hostname or just an
340           IP address), and "SNMPNAME" will be replaced with the device's idea
341           of its own name (the same name that appears on the right side of
342           the "Title" lines).  For instance, a call like:
343
344            cfgmaker --subdirs=HOSTNAME__SNMPNAME public@10.10.0.18
345
346           would result in the generation of lines looking something like:
347
348            Directory[10.10.0.18_1]: 10.10.0.18__fp2200-bothrip-1.3
349
350       --output file
351           Write the output from cfgmaker into the file file. The default is
352           to use "STDOUT". --output is expected to appear only once on the
353           command line. If used multiple times, the file specified by the
354           last --output will be used.
355
356       --nointerfaces
357           Don't generate configuration lines for interfaces.
358
359           This makes cfgmaker skip all steps related to interfaces which
360           means it will not do any polling of the router to retrieve
361           interface information which speeds up the execution of cfgmaker and
362           it will neither run any interface templates.
363
364       --interfaces
365           This makes cfgmaker generate configuration lines for interfaces
366           (the default behaviour).
367
368           The main usage of this option is to negate an --nointerfaces
369           appearing earlier on the command line.
370
371   SNMP V3 Options
372       Cfgmaker supports SNMP V3 using the Net:SNMP perl module.  There are
373       optional parameters affecting SNMP operation.
374
375       --enablesnmpv3 {yes|no}
376           The --enablesnmpv3 option is an optional flag to check for the
377           presence of the Net::SNMP libraries.  Cfgmaker will try to
378           determine whether this flag is required and will set the values
379           automatically.
380
381       SNMPv3 Arguments
382
383       A SNMP context is a collection of management information accessible by
384       a SNMP entity.  An item of management information may exist in more
385       than one context and a SNMP entity potentially has access to many
386       contexts.  The combination of a contextEngineID and a contextName
387       unambiguously identifies a context within an administrative domain.  In
388       a SNMPv3 message, the contextEngineID and contextName are included as
389       part of the scopedPDU.  All methods that generate a SNMP message
390       optionally take a --contextengineid and --contextname argument to
391       configure these fields.
392
393       Context Engine ID
394           The --contextengineid argument expects a hexadecimal string
395           representing the desired contextEngineID.  The string must be 10 to
396           64 characters (5 to 32 octets) long and can be prefixed with an
397           optional "0x".  Once the --contextengineid is specified it stays
398           with the object until it is changed again or reset to default by
399           passing in the undefined value.  By default, the contextEngineID is
400           set to match the authoritativeEngineID of the authoritative SNMP
401           engine.
402
403       Context Name
404           The contextName is passed as a string which must be 0 to 32 octets
405           in length using the --contextname argument.  The contextName stays
406           with the object until it is changed.  The contextName defaults to
407           an empty string which represents the "default" context.
408
409       User-based Security Model Arguments
410
411       The User-based Security Model (USM) used by SNMPv3 requires that a
412       securityName be specified using the --username argument.  The creation
413       of a Net::SNMP object with the version set to SNMPv3 will fail if the
414       --username argument is not present.  The --username argument expects a
415       string 1 to 32 octets in length.
416
417       Different levels of security are allowed by the User-based Security
418       Model which address authentication and privacy concerns.  A SNMPv3
419       target will derive the security level (securityLevel) based on which of
420       the following arguments are specified.
421
422       By default a securityLevel of 'noAuthNoPriv' is assumed.  If the
423       --authkey or --authpassword arguments are specified, the securityLevel
424       becomes 'authNoPriv'.  The --authpassword argument expects a string
425       which is at least 1 octet in length.  Optionally, the --authkey
426       argument can be used so that a plain text password does not have to be
427       specified in a script.  The --authkey argument expects a hexadecimal
428       string produced by localizing the password with the
429       authoritativeEngineID for the specific destination device.  The
430       "snmpkey" utility included with the Net::SNMP  distribution can be used
431       to create the hexadecimal string (see snmpkey).
432
433       Two different hash algorithms are defined by SNMPv3 which can be used
434       by the Security Model for authentication.  These algorithms are
435       HMAC-MD5-96 "MD5" (RFC 1321) and HMAC-SHA-96 "SHA-1" (NIST FIPS PUB
436       180-1).   The default algorithm used by the module is HMAC-MD5-96.
437       This behavior can be changed by using the --authprotocol argument.
438       This argument expects either the string 'md5' or 'sha' to be passed to
439       modify the hash algorithm.
440
441       By specifying the arguments --privkey or --privpassword the
442       securityLevel associated with the object becomes 'authPriv'.  According
443       to SNMPv3, privacy requires the use of authentication.  Therefore, if
444       either of these two arguments are present and the --authkey or
445       --authpassword arguments are missing, the creation of the object fails.
446       The --privkey and --privpassword arguments expect the same input as the
447       --authkey and --authpassword arguments respectively.
448
449       The User-based Security Model described in RFC 3414 defines a single
450       encryption protocol to be used for privacy.  This protocol, CBC-DES
451       "DES" (NIST FIPS PUB 46-1), is used by default or if the string 'des'
452       is passed to the --privprotocol argument.  By working with the Extended
453       Security Options Consortium http://www.snmp.com/eso/, the module also
454       supports additional protocols which have been defined in draft
455       specifications.  The draft
456       http://www.snmp.com/eso/draft-reeder-snmpv3-usm-3desede-00.txt defines
457       the support of CBC-3DES-EDE "Triple-DES" (NIST FIPS 46-3) in the User-
458       based Security Model.  This protocol can be selected using the
459       --privprotocol argument with the string '3desede'.  The draft
460       http://www.snmp.com/eso/draft-blumenthal-aes-usm-04.txt describes the
461       use of CFB128-AES-128/192/256 "AES" (NIST FIPS PUB 197) in the USM. The
462       three AES encryption protocols, differentiated by their key sizes, can
463       be selected by passing 'aescfb128', 'aescfb192', or 'aescfb256' to the
464       -privprotocol argument.
465
466   Details on Filters
467       The purpose of the filters is to decide which interfaces to accept and
468       which interfaces to reject.  This decision is done for each interface
469       by evaluating the filter expression as a piece of Perl code and
470       investigating the result of the evaluation.  If true, accept the
471       interface otherwise reject it.
472
473       When working with filters, remember that Perl has it's own idea of what
474       truth and false is.  The empty string "" and the string "0" are false,
475       all other strings are true.  This further imples that any integer value
476       of 0 is false as well as any undef value.  It also implies that all
477       references are considered true.
478
479       As the filter is evaluated as a Perl expression, several useful
480       constructs in Perl are worth mentioning:
481
482       Expressions might be grouped by using parentheses "()".  Expressions
483       might be combined using boolean operators such as the following:
484
485       "and" (equivalent with "&&")
486           Boolean "and" of the two expressions, is only true if both
487           expressions are true.  Example: expression1 and expression2
488
489       "or" (equivalent with "||")
490           Boolean "or" of the two expressions, is true if either or both
491           expressions are true.  Example: expression1 or expression2
492
493       "not" (equivalent with "!")
494           Boolean negation of a single expression.  Example:  not expression
495           .  Yet another example: !expression
496
497       (For more details on this I recommend a book on Perl)
498
499       Predefined Filter Variables
500
501       To facilitate, there are a number of predefined values available to use
502       in the filter.  Note that these variables are also available when
503       templates interfaces are evaluated (but not host templates).
504
505       Caveat:  All these variables' names begin with a dollar sign  ($),
506       which is a syntactic requirement for scalar variables in Perl.  The
507       danger here is that the dollar sign in many shells is an active
508       character (often used for shell variables exactly as in Perl variables)
509       so it is important to ensure that the Perl expression isn't evaluated
510       by the command line shell as shell code before being passed to cfgmaker
511       as command line arguments.  In shells like Bourne shell, ksh shell or
512       bash shell, placing the entire expression within single qoutes will
513       avoid such accidental evaluation:
514
515        '--if-filter=($default_iftype && $if_admin)'
516
517       $if_type
518           This is an integer specifying the interface type as per the SNMP
519           standards and as reported by the polled device.  A complete list of
520           interface types would be impractical for this document , but there
521           are a number predefined varables below.  Normally, cfgmaker puts in
522           the target's PageTop this iftype value within paranthesis after the
523           name of the interface type. (e.g "propPointToPointSerial (22)").
524
525           Here's a list of some of the most common interface types by number:
526
527              6 ethernetCsmacd
528              7 iso88023Csmacd
529              9 iso88025TokenRing
530             15 fddi
531             19 E1
532             20 basicISDN
533             21 primaryISDN
534             22 propPointToPointSerial
535             23 ppp
536             24 softwareLoopback
537             30 ds3
538             32 frame-relay
539             33 rs232
540             37 atm
541             39 sonet
542             44 frameRelayService
543             46 hssi
544             49 aal5
545             53 propVirtual
546             62 Fast Ethernet (100BaseT)
547             63 ISDN & X.25
548             69 Full Duplex Fast Ethernet (100BaseFX)
549             94 Asymetric Digital Subscriber Loop (ADSL)
550            117 Gigabit Ethernet
551            134 ATM Sub Interface
552
553       $default
554           True if and only if cfgmaker normally should accepted the interface
555           based on the interfaces administrative and operational state
556           (taking the flags --no-down and --show-op-down into account) and
557           it's type (and a few other things).
558
559       $default_ifstate
560           True if and only if cfgmaker would have accepted the interface
561           based on it's operational and administrative states (also taking
562           into account the presence of the flags --no-down and
563           --show-op-down).
564
565       $default_iftype
566           True if and only if cfgmaker would have accepted the interface
567           based on it's type (and a few type specific details in addition).
568
569       $if_admin
570           True if and only if the interface is in an adminstrative up state.
571
572       $if_oper
573           True if and only if the interface is in an operational up state.
574
575       A number of variables are also predefined to easily decide if an
576       interface belong to a certain cathegory or not.  Below is all those
577       variables listed together with which if_type numbers each variable will
578       be true for.  Note that some variables refer to other variables as
579       well.
580
581       $if_is_ethernet
582           True for ethernet interfaces (nr 6, 7, 26, 62, 69 and 117).
583
584       $if_is_isdn
585           True for various ISDN interface types (nr 20, 21, 63, 75, 76 and
586           77)
587
588       $if_is_dialup
589           True for dial-up interfaces such as PPP as well as ISDN.  (nr 23,
590           81, 82 and 108 in addition to the numbers of $if_is_isdn).
591
592       $if_is_atm
593           True for miscellaneous ATM related interface types (nr 37, 49, 107,
594           105, 106, 114 and 134).
595
596       $if_is_wan
597           True for WAN interfaces point to point, Frame Relay and High Speed
598           Serial ( 22,32,44,46)
599
600       $if_is_lan
601           True for LAN interfaces (8, 9, 11, 15, 26, 55, 59, 60 and 115 in
602           addition to the numbers of $if_is_ethernet).
603
604       $if_is_dsl
605           True for ADSL, RDSL, HDSL and SDSL (nr 94, 95, 96, 97)
606
607       $if_is_loopback
608           True for software loopback interfaces (nr 24)
609
610       $if_is_ciscovlan
611           True for Cisco VLAN interfaces (interfaces with the word Vlan or
612           VLAN in their ifdescs)
613
614       $if_vlan_id
615           Returns the vlan id associated with a specific port on Cisco
616           Catalyst switches under both Catalyst OS and IOS, and 3Com
617           switches.  If it is not a vlan interface, will return undef.
618
619       $if_cisco_trunk
620           Returns the trunking state of a specific port on Cisco Catalyst
621           switches under both Catalyst OS and IOS.  Returns "1" if the
622           interface is a trunk, undef otherwise.
623
624       $if_MTU
625           Returns the Maximum Transfer Unit associated with a specific port.
626
627       Besides that, you can also use the variables defined for templates
628       below.  Further, all the variables available in cfgmaker is at the
629       scripts disposal even if the use of such features is discouraged.  More
630       "shortcuts" in the form of variables and functions will be made
631       available in the future instead.
632
633       Examples on Filters
634
635       The following filter will not affect which interfaces get's included or
636       excluded, it will make cfgmaker behave as normally.
637
638        '--if-filter=$default'
639
640       The following filter will make cfgmaker exclude PPP (23) interfaces:
641
642        '--if-filter=$default && $if_type!=23'
643
644       The following filter will make cfgmaker behave as usual except that it
645       will consider the operational state of an interface irrelevant but
646       still reject all interfaces which are administratively down.
647
648        '--if-filter=$if_admin && $default_iftype'
649
650   Details on Templates
651       The contents of the template files are evaluated as a Perl program.  A
652       number or Perl variables are available for the program to read and
653       others are used to be written to.
654
655       As quite a few of the predefined variables has values which are are
656       supposed to be used in HTML code some of them have an "HTML-escaped"
657       variant, e.g $html_syslocation is the HTML escaped variant of
658       $syslocation.  The HTML escaping means that the chars "<", ">" and "&"
659       are replaced by "&lt;", "&gt;" and "&amp;" and that newlines embedded
660       in the string are prepended with "<BR>" and appended with a space
661       character (if a newline is last in the string it is not touched).
662
663       Writable Template Variables
664
665       These are the variables available to store the configuration lines in.
666       Some of them are initialized prior to the evaluation of the template
667       but such content normally is comments for inclusion in the final
668       configuration file so those variables might be reset to the empty
669       string in the template code to eliminate the comments.  The other way
670       around is also possible, the contents of these variables might be
671       extended with further information for various reasons such as debugging
672       etc.
673
674       Once the template has been evaluated, the following happens:  if the
675       template is a interface template and the actual interface for some
676       reason is rejected and thus needs to be commented out, all the lines in
677       the variable $target_lines are turned into comments by adding a hash
678       mark ("#") at their beginning.  Then all the variables $head_lines,
679       $problem_lines , $target_lines and $separator_lines are concatenated
680       together to form the lines to add to the configuration file.
681
682       $target_lines
683           This variable is the placeholder for the configuration lines
684           created by the template.  $target_lines is predefined to be empty
685           when the template code is evaluated.
686
687       $head_lines
688           This variable is intended to be the placeholder for the comment
689           line appearing just before the target in the configuration file.
690           It is initialized with that comment line before the evaluation of
691           the template code and if the template doesn't modify $head_lines
692           during evaluation, the comment will look like usual in the config
693           file.
694
695       $problem_lines
696           This variable is intended to be the placholder for the comment
697           lines describing any problems which might have been encountered
698           when trying to add the target into the configuration.  For host
699           templates it's normally not used and for those it's predefined as
700           the empty string.  For interface templates $problem_lines is
701           predefined with the error description comments which cfgmaker
702           normally would use for rejected interfaces or as the empty string
703           for accepted interfaces.
704
705           It is possible to test against $problem_lines to find out if an
706           interface will be included or rejected but this is not recommended.
707           Test against $if_ok instead.
708
709       $separator_lines
710           This variable is the placeholder for the string to use as the
711           separator between the code for individual targets.  The contents of
712           this variable is put after each target (so the lines will appear
713           after the end of the last target in the config as well).
714
715       Predefined Template Variables
716
717       All the variables below are available for interface templates to use.
718       For host templates, only those listed under "Host and System Variables"
719       are available.
720
721       For interface templates the variables listed under "Predefined Filter
722       Variables" are also available.
723
724       Host and System Variables
725
726       $router_name
727           This is the fully qualified name for the router.  It is affected by
728           the following items on the command line:  the router name itself
729           and --dns-domain.
730
731       $router_connect
732           This is the reference string for the router being polled.  It is on
733           the form community@router possibly followed by some snmp options.
734           It is affected by the following items on the command line:  the
735           router name itself, --community, --snmp-options and --dns-domain.
736           (There's no HTML escaped variant available)
737
738       $directory_name
739           This variable should contain the directory name as cfgmaker
740           normally would use as the value for the "Directory[]" directive.
741           The value is determined by the --subdirs command line option.  If
742           --subdirs isn't specified $directory_name will be the empty string.
743           (There's no HTML escaped variant available)
744
745       $syscontact
746           This variable is the router's SNMP sysContact value.  (HTML escaped
747           variant: $html_syscontact)
748
749       $sysname
750           This variable is the router's SNMP sysName value.  (No HTML escaped
751           variant available)
752
753       $syslocation
754           This variable is the router's SNMP sysLocation value.  (HTML
755           escaped variant: $html_syslocation)
756
757       $sysdescr
758           This variable is the router's SNMP sysDescr value.  It is normally
759           not used by cfgmaker but might be useful in a template.  (HTML
760           escaped variant: $html_sysdescr)
761
762       Interface Target Related Variables
763
764       $target_name
765           This is what cfgmaker normally would use as the the name of the
766           target.  The target name is what is found within the square
767           brackets, "[]", for target directives.  (There's no HTML escaped
768           variant available)
769
770       $if_ref
771           This the reference string for the interface.  It is expected to be
772           used in the "Target[xyz]" directive to distinguish what interface
773           to use.  The value of this variable is affected by the --ifref
774           command line option.  It is normally used together with
775           $router_connect.  (There's no HTML escaped variant available)
776
777       $if_ok
778           This variable is true if the interface is going to be included into
779           the configuration file, otherwise false.  Don't test against other
780           variables such as $problem_lines to find out if an interface will
781           be rejected or not, use this $if_ok instead.
782
783       $default_target_lines
784           This variable contains all the target lines which cfgmaker by
785           default outputs for this interface.  It's useful if you want to
786           have the "standard target" but want to add some extra lines to it
787           by using a template.
788
789       By default cfgmaker uses the following directives for each target it
790       generates: Target[], SetEnv[], MaxBytes[], Title[], PageTop[] and if
791       there is any directory specified also the Directory[] directive.
792
793       To facilitate the creation of templates which generates target configs
794       which are similar to the default one, each of the above mentioned
795       directive lines have a corresponding variable containing the line as
796       cfgmaker would have output it by default.
797
798       Note that none of these have a HTML escaped variant, text in them is
799       HTML escaped where needed.  Also note that they do not have any newline
800       at the end.
801
802       $default_target_directive
803           This variable contains the default string for the Target[]
804           directive line.
805
806       $default_setenv_directive
807           This variable contains the default string for the SetEnv[]
808           directive line.
809
810       $default_directory_directive
811           This variable contains the default string for the Directory[]
812           directive line which means it is an empty string (with no newline)
813           if there's no directory.
814
815       $default_maxbytes_directive
816           This variable contains the default string for the MaxBytes[]
817           directive line.
818
819       $default_title_directive
820           This variable contains the default string for the Title[] directive
821           line.
822
823       $default_pagetop_directive
824           This variable contains the default string for the PageTop[]
825           directive lines.
826
827       Interface Network Configuration Variables
828
829       $if_ip
830           This variable should contain the IP-address of the interface, if
831           any has been assigned to it.  (There's no HTML escaped variant
832           available)
833
834       $ifindex
835           This variable is the SNMP ifIndex for the interface which per
836           definition always is an integer.  (There's no HTML escaped variant
837           available)
838
839       $if_index
840           Equivalent with $ifindex.
841
842       $if_eth
843           Contains the ethernet address of the interface, if any.  (There's
844           no HTML escaped variant available)
845
846       $if_speed
847           This variable is the speed in bytes/second (with prefixes).
848           (There's no HTML escaped variant available)
849
850       $if_speed_str
851           This variable is a cooked speed description which is either in bits
852           or bytes depending on wether or not the bits option is active and
853           also with the proper prefix for the speed (k, M, G etc).  (No HTML
854           escaped variant available)
855
856       $if_type_desc
857           This variable is a textual description of the interface type.
858           (HTML escaped variant: $html_if_type_desc)
859
860       $if_type_num
861           This variable the integer value corresponding to the interface type
862           (for a listing for the value for the more common interface types,
863           see the section DETAILS ON FILTERS above).  (No HTML escaped
864           variant available)
865
866       $if_dns_name
867           This is the DNS name for the interface.  (No HTML escaped variant
868           available)
869
870       Interface Name, Description and Alias Variables
871
872       It might seem confusing with both Name, Description and Alias in this
873       context and to some extent it is.  Name and Description are usually
874       supported on most equipment but how they are used varies, both between
875       manufacturers as well as between different cathegories of equipment
876       from the same manufacturer.  The Alias is at least supported by Cisco
877       IOS, and that variable contains whatever is used in the IOS statement
878       called "description" for the interface (not to be confused with the
879       SNMP variables for Description).
880
881       For better control from the command line consider $if_title_desc which
882       contents are controlled by the --if-descr command line option.
883
884       $if_snmp_descr
885           This variable should contain the "raw" description of the interface
886           as determined by the SNMP polling of the router.  (HTML escaped
887           variant: $html_if_snmp_descr)
888
889       $if_snmp_name
890           The "raw" name for the interface as provided by SNMP polling.
891           (HTML escaped variant: $html_if_snmp_name)
892
893       $if_snmp_alias
894           The "raw" ifAlias for the interface as provided by SNMP polling.
895           (HTML escaped variant: $html_if_snmp_alias)
896
897       $if_cisco_descr
898           The "raw" CiscolocIfDescr for the interface as provided by SNMP
899           polling.  (HTML escaped variant: $html_if_cisco_descr)
900
901       $if_description
902           This is the "cooked" description string for the interface, taking
903           into account the SNMP values found for the interface's RDescr,
904           ifAlias and CiscolocIfDescr.  (HTML escaped variant:
905           $html_if_description)
906
907       $if_title
908           The full string cfgmaker by default would have used for the Title[]
909           directive in the configuration as well as the content of the
910           topmost H1 tag in the PageTop[].  Is composed by the contents of
911           $desc_prefix, $if_title_desc and $sysname.
912
913           As $if_title depends on $if_title_desc, it is possible to
914           indirectly control $if_title by using the command line option
915           --if-descr.
916
917           (HTML escaped variant: $html_if_title)
918
919       $if_port_name
920           If the host is a Cisco Catalyst LAN switch, this variable is the
921           name of that port.  (No HTML escaped variant available)
922
923       $if_pp_port_name
924           If the host is a Nortel Passport LAN switch, this variable is the
925           name of that port.  (No HTML escaped variant available)
926
927       $desc_prefix
928           This variable is a prefix of the description of what the target is
929           to use in the "Title[]" directive and in the H1 section of the
930           "PageTop[]".  Default is "Traffic analysis for ".  (HTML escaped
931           variant: $html_desc_prefix)
932
933       $if_title_desc
934           This is the description of the interface normally used by cfgmaker
935           as part of the variable $if_title.  The latter is used as the full
936           string in the "Title[]" directove and the H1 section in the
937           PageTop[].
938
939           $if_title_desc is controlled by the command line option --if-descr
940           which indirectly controls the contents of $if_title
941
942           (HTML escaped variant: $html_if_title_desc)
943
944       Help Functions for Templates
945
946       The following functions exists to facilitate the writing of host and
947       interface templates.
948
949       html_escape(string)
950           html_escape() takes a string as an argument and returns a new
951           string where the following substitutions has been done:  the chars
952           "<", ">" and "&" are replaced by "&lt;", "&gt;" and "&amp;" and
953           that newlines embedded in the string are prepended with "<BR>" and
954           appended with a space character (newlines at the end of the string
955           are not touched).
956
957       oid_pick($router_connect,$v3opt,"oid1","oid2"...)
958           This function will try to poll each of the oids specified until it
959           is successful or has run out of oids. It will return the name of
960           the first oid that worked or undef if it is not successful
961
962       Example Template Files
963
964       Template Example 1: Eliminating Rejected Targets From Appearing
965
966       This template file generates exactly the same configuration code per
967       interface as cfgmaker does by default, with the exception that it
968       eliminates all lines (comments as well as config code) for an interface
969       if the interface happens to be rejected.
970
971        if(not $problem_lines)
972        {
973          $target_lines .= <<ECHO;
974
975        Target[$target_name]: $if_ref:$router_connect
976        SetEnv[$target_name]: MRTG_INT_IP="$if_ip" MRTG_INT_DESCR="$if_snmp_descr"
977        ECHO
978
979          if ($directory_name) {
980              $target_lines .= "Directory[$target_name]: $directory_name\n";
981          }
982
983          $target_lines .= <<ECHO;
984        MaxBytes[$target_name]: $if_speed
985        Title[$target_name]: $html_desc_prefix$html_if_title_desc -- $sysname
986        PageTop[$target_name]: <h1>$html_desc_prefix$html_if_title_desc -- $sysname</h1>
987                       <div id="sysdetails">
988                               <table>
989                                       <tr>
990                                               <td>System:</td>
991                                               <td>$sysname in $html_syslocation</td>
992                                       </tr>
993                                       <tr>
994                                               <td>Maintainer:</td>
995                                               <td>$html_syscontact</td>
996                                       </tr>
997                                       <tr>
998                                               <td>Description:</td>
999                                               <td>$html_if_description</td>
1000                                       </tr>
1001                                       <tr>
1002                                               <td>ifType:</td>
1003                                               <td>$html_if_type_desc ($if_type_num)</td>
1004                                       </tr>
1005                                       <tr>
1006                                               <td>ifName:</td>
1007                                               <td>$html_if_snmp_name</td>
1008                                       </tr>
1009        ECHO
1010
1011          $target_lines .= <<ECHO if defined $if_port_name;
1012                                       <tr>
1013                                               <td>Port Name:</td>
1014                                               <td>$if_port_name</td>
1015                                       </tr>
1016        ECHO
1017
1018          $target_lines .= <<ECHO if defined $if_pp_port_name;
1019                                       <tr>
1020                                               <td>Port Name:</td>
1021                                               <td>$if_pp_port_name</td>
1022                                       </tr>
1023        ECHO
1024
1025          $target_lines .= <<ECHO;
1026                                       <tr>
1027                                               <td>Max Speed:</td>
1028                                               <td>$if_speed_str</td>
1029                                       </tr>
1030        ECHO
1031
1032          $target_lines .= <<ECHO if $if_ip;
1033                                       <tr>
1034                                               <td>Ip:</td>
1035                                               <td>$if_ip ($if_dns_name)</td>
1036                                       </tr>
1037        ECHO
1038
1039          $target_lines .= <<ECHO;
1040                               </table>
1041                       </div>
1042        ECHO
1043        } else {
1044          $head_lines="";
1045          $problem_lines="";
1046          $target_lines="";
1047          $separator_lines="";
1048        }
1049
1050       Template Example 2: Simplier Version of Example 1
1051
1052       Example 1 was partly intended to demonstrate how to customize the
1053       generation of interface targets but also to provide a hint of how the
1054       variables are used in the "default" template which one could consider
1055       that cfgmaker normally uses.
1056
1057       If you're only intrested in the easiest way of entirely eliminating
1058       those reject interfaces, the template below would do the job as well by
1059       using $default_target_lines.
1060
1061        if($if_ok) {
1062         $target_lines = $default_target_lines;
1063        } else {
1064          $head_lines="";
1065          $problem_lines="";
1066          $target_lines="";
1067          $separator_lines="";
1068        }
1069
1070       Template Example 3: Creating CPU Targets for Hosts
1071
1072       Below is an example of a host template.
1073
1074        $head_lines .= <<ECHO;
1075        #---------------------------------------------------------------------
1076        ECHO
1077
1078        my $target_name = $router_name . ".cpu";
1079
1080        $target_lines .= <<ECHO;
1081
1082        YLegend[$target_name]: Percentage CPU load
1083        ShortLegend[$target_name]: %
1084        Legend1[$target_name]: CPU load in %
1085        Legend2[$target_name]:
1086        Legend3[$target_name]: Max Observed CPU load
1087        Legend4[$target_name]:
1088        LegendI[$target_name]: &nbsp;CPU Load:
1089        LegendO[$target_name]:
1090        WithPeak[$target_name]: ywm
1091        MaxBytes[$target_name]: 100
1092        Options[$target_name]: growright, gauge, nopercent
1093        Title[$target_name]: $router_name CPU load
1094        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
1095        PageTop[$target_name]: <h1>$router_name CPU load</h1>
1096                       <div>
1097                               <table>
1098                                       <tr>
1099                                               <td>System:</td>
1100                                               <td>$router_name in $html_syslocation</td>
1101                                       </tr>
1102                                       <tr>
1103                                               <td>Maintainer:</td>
1104                                               <td>$html_syscontact</td>
1105                                       </tr>
1106                                       <tr>
1107                                               <td>Description:</td>
1108                                               <td>$html_sysdescr</td>
1109                                       </tr>
1110                                       <tr>
1111                                               <td>Resource:</td>
1112                                               <td>CPU.</td>
1113                                       </tr>
1114                               </table>
1115                       </div>
1116        ECHO
1117

EXAMPLES

1119       The first example creates a config file for router.place.xyz:  the
1120       router has the community name public.  Interfaces get identified by
1121       their IP number.  Two global options get added to the config file.  The
1122       config file gets redirected to mrtg.conf.  The '\' signs at the end of
1123       the line mean that this command should be written on a single line.
1124
1125        cfgmaker --global "WorkDir: /home/tobi"           \
1126                 --global "Options[_]: growright,bits"    \
1127                 --ifref=ip                               \
1128                 public@router.place.xyz > mrtg.cfg
1129
1130       Note: if cfgmaker is not in your path, but you are in the directory
1131       where cfgmaker is stored, you can start it with ./cfgmaker
1132
1133       The next example creates a config file for four devices:
1134       router1.place.xyz, router2.place.xyz, switch1.place.xyz and
1135       switch2.place.xyz all with the community public.
1136
1137       The two routers will have --ifref set to descr whilst the two switches
1138       will use --ifref set to name.  Further the routers will use --ifdesc
1139       set to alias and switch1.place.xyz will use --ifdesc set to descr
1140       whilst switch2.place.xyz use name instead.
1141
1142       Finally, there will be two Options lines inserted in the configuration:
1143       One will be in the beginning, whilst the other will be inserted after
1144       the lines related to the two routers but before those lines related to
1145       the switches.
1146
1147        cfgmaker --global "WorkDir: /home/tobi"           \
1148                 --global "Options[_]: growright,bits"    \
1149                 --ifref=descr                            \
1150                 --ifdesc=alias                           \
1151                 public@router1.place.xyz                 \
1152                 public@router2.place.xyz                 \
1153                 --global "Options[_]: growright"         \
1154                 --ifref=name                             \
1155                 --ifdesc=descr                           \
1156                 public@switch1.place.xyz                 \
1157                 --ifdesc=name                            \
1158                 public@switch2.place.xyz > mrtg.cfg
1159
1160       The next example demonstrates how to use the --community,
1161       --snmp-options and --dns-domain to make the command line simpler.  All
1162       the equipment will use the community hidden, except for the ppp-server
1163       which use community access.  All equipment uses these SNMP options: 1s
1164       timeout, 1 retry and SNMP version 2 (backoff and port is unspecified
1165       which means they use the default values).  The exception again is the
1166       ppp-server which uses SNMP version 1.  Finally, all the equipment is
1167       part of the domain place.xyz, except for the ppp-server which is part
1168       of the domain remote.place.xyz.  Note that the latter is achieved
1169       simply by specifying the name of the ppp-server to be ppp-server.remote
1170       .
1171
1172        cfgmaker --global "WorkDir: /home/tobi"           \
1173                 --global "Options[_]: growright,bits"    \
1174                 --dns-domain=place.xyz                   \
1175                 --community=hidden                       \
1176                 --snmp-options=::1:1::2                  \
1177                 router1                                  \
1178                 router2                                  \
1179                 router3                                  \
1180                 router4                                  \
1181                 router5                                  \
1182                 switch1                                  \
1183                 switch2                                  \
1184                 switch3                                  \
1185                 switch4                                  \
1186                 switch5                                  \
1187                 switch6                                  \
1188                 switch7                                  \
1189                 access@ppp-server.remote:::::1 > mrtg.cfg
1190

SEE ALSO

1192       mrtg-reference
1193

AUTHOR

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

LICENSE

1199       GNU General Public License
1200
1202       Cfgmaker is Copyright 2000 by Tobias Oetiker <tobi@oetiker.ch>
1203
1204
1205
12062.16.4                            2010-05-17                       CFGMAKER(1)
Impressum