cfgmaker.txt
上传用户:shbosideng
上传日期:2013-05-04
资源大小:1555k
文件大小:61k
- CFGMAKER(1) mrtg CFGMAKER(1)
- NNAAMMEE
- cfgmaker - Creates mrtg.cfg files (for mrtg-2.13.2)
- SSYYNNOOPPSSIISS
- cfgmaker [options] [community@]router [[options] [commu-
- nity@]router ...]
- OOPPTTIIOONNSS
- --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
- --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=alias ... uses Interface Alias
- --ifdesc=type ... uses Interface Type
- --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
- DDEESSCCRRIIPPTTIIOONN
- CCffggmmaakkeerr creates MRTG configuration files based on infor-
- mation pulled from a router or another SNMP manageable
- device.
- [_c_o_m_m_u_n_i_t_y@@]_r_o_u_t_e_r
- _C_o_m_m_u_n_i_t_y is the community name of the device you want to
- create a configuration for. If not specified, it defaults
- to 'ppuubblliicc'; 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.
- _R_o_u_t_e_r is the DNS name or the IP number of an SNMP-man-
- agable device. Following the name you can specify 6 fur-
- ther options separated by colons. The full syntax looks
- like this:
- rroouutteerr[:[pprrtt][:[ttmmoouutt][:[rreettrr][:[bbaacckkooffff][:vveerrss]]]]]
- Of special interest may be the last parameter, vveerrss. If
- you set this to '2' then your device will be queried with
- SNMP version 2 requests. This allows 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, fol-
- lowed 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 generat-
- ing it. This is to allow for the easy 'regeneration' in
- case you want to add newhosts or make some other global
- change.
- CCoonnffiigguurraattiioonn
- Except for the ----oouuttppuutt and ----gglloobbaall 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 ----oouuttppuutt and ----gglloobbaall for how their behaviour is
- affected by where or how many times they appear on the
- command line.
- See the EExxaammpplleess below on how to set an option differently
- for multiple routers.
- ----hheellpp
- Print a brief help message and exit.
- ----mmaann
- Prints the manual page and exits.
- ----vveerrssiioonn
- Print the version of cfgmaker. This should match the
- version of MRTG for which config files are being cre-
- ated.
- ----iiffrreeff nnrr|iipp|eetthh|ddeessccrr|nnaammee
- Select the interface identification method. Default
- is nnrr 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 iipp to identify the interface by its IP number.
- Use eetthh to use the ethernet address for identifica-
- tion. Use ddeessccrr to use the Interface description. Or
- use nnaammee to use the Interface name.
- If your chosen method does not allow unique interface
- identification on the device you are querying, ccffgg--
- mmaakkeerr will tell you about it.
- ----iiffddeesscc nnrr|iipp|eetthh|ddeessccrr|nnaammee|ttyyppee|aalliiaass
- Select what to use as the description of the inter-
- face. The description appears in the "Title[]" prop-
- erty for the target as well as the text header in the
- HTML code defined in the target's "PageTop[]".
- Default is to use nnrr which is just the interface num-
- ber which isn't always useful to the viewer of the
- graphs.
- There are 6 other properties which could be used. Use
- iipp if you want to use the interface's IP-address. Use
- eetthh if you want to use the interface's ethernet
- address. If you want a better description, you can
- use either ddeessccrr, nnaammee or aalliiaass. 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 nnaammee
- might result in "S0" being the interface description ,
- ddeessccrr might result in "Serial0" and aalliiaass might result
- in "Link to HQ" (provided that is what is used as the
- interface's "description" in the router's configura-
- tion).
- Finally, if you want to describe the interface by it's
- Btype (i.e "ethernetCSMA", "propPointtoPoint" etc) you
- can use ttyyppee.
- ----iiff--ffiilltteerr 'ffiilltteerr--eexxpprreessssiioonn'
- First of all, this is under some developement and is
- experimental.
- Use this if you want to have better control over what
- interfaces gets included into the configuration. The
- ffiilltteerr--eexxpprreessssiioonn 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 inter-
- face.
- For a further discussion on how these filters work,
- see the section "Details on Filters" below.
- ----iiff--tteemmppllaattee tteemmppllaattee--ffiillee
- 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 tteemmppllaattee--ffiillee will be evalu-
- ated 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.
- ----hhoosstt--tteemmppllaattee tteemmppllaattee--ffiillee
- 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 tteemmppllaattee--ffiillee will be
- evaluated once per host as a Perl program which gener-
- ates 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.
- ----ccoommmmuunniittyy ccoommmmuunniittyy--ssttrriinngg
- Use this to set the community for the routers follow-
- ing on the command line to ccoommmmuunniittyy--ssttrriinngg. Individ-
- ual routers might overrride this community string by
- using the syntax ccoommmmuunniittyy@@rroouutteerr.
- ----eennaabbllee--iippvv66
- 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 tar-
- get. 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.
- ----uussee--1166bbiitt
- 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.
- ----ssnnmmpp--ooppttiioonnss :[ppoorrtt][:[ttiimmeeoouutt][:[rreettrriieess][:[bbaacckk--
- ooffff][:vveerrssiioonn]]]]
- 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 ----ssnnmmpp--ooppttiioonnss by using the syntax
- rroouutteerr[:[ppoorrtt][:[ttiimmeeoouutt][:[rreettrriieess][:[bbaacckkooffff][:vveerr--
- ssiioonn]]]]]
- ----gglloobbaall ""_b_l_a_: _a_b_c""
- Use this to add global options to the generated config
- file. You can call ----gglloobbaall several times to add mul-
- tiple options. The line will appear in the configura-
- tion 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 ----gglloobbaall after the last router on the com-
- mand line will create a line in the configuration file
- which will appear after all the routers.
- ----nnoorreevveerrsseeddnnss
- Do not try to reverse lookup IP numbers ... a must for
- DNS free environments.
- ----nnoo--ddoowwnn
- Normally cfgmaker will not include interfaces which
- are marked anything but administratively and opera-
- tionally UP. With this switch you get them all.
- ----sshhooww--oopp--ddoowwnn
- Include interfaces which are operatively down.
- ----zzeerroo--ssppeeeedd _s_p_e_e_d
- 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.
- ----ssuubbddiirrss _f_o_r_m_a_t
- Give each router its own subdirectory for the HTML and
- graphics (or .rrd) files. The directory name is the
- given _f_o_r_m_a_t string with a couple of pattern replace-
- ments. The string "HOSTNAME" will be replaced by the
- hostname of the router (however you specified it on
- the ccffggmmaakkeerr commandline -- it may be an actual host-
- name 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 some-
- thing like:
- Directory[10.10.0.18_1]: 10.10.0.18__fp2200-bothrip-1.3
- ----oouuttppuutt _f_i_l_e
- Write the output from ccffggmmaakkeerr into the file _f_i_l_e. The
- default is to use "STDOUT". ----oouuttppuutt is expected to
- appear only once on the command line. If used multiple
- times, the file specified by the last ----oouuttppuutt will be
- used.
- ----nnooiinntteerrffaacceess
- Don't generate configuration lines for interfaces.
- This makes cfgmaker skip all steps related to inter-
- faces 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.
- ----iinntteerrffaacceess
- This makes cfgmaker generate configuration lines for
- interfaces (the default behaviour).
- The main usage of this option is to negate an --noint-
- erfaces appearing earlier on the command line.
- SSNNMMPP VV33 OOppttiioonnss
- CCffggmmaakkeerr supports SNMP V3. There are optional parameters
- affecting SNMP operation.
- _S_N_M_P_v_3 _A_r_g_u_m_e_n_t_s
- A SNMP context is a collection of management information
- accessible by a SNMP entity. An item of management infor-
- mation may exist in more than one context and a SNMP
- entity potentially has access to many contexts. The com-
- bination of a contextEngineID and a contextName unambigu-
- ously identifies a context within an administrative
- domain. In a SNMPv3 message, the contextEngineID and con-
- textName are included as part of the scopedPDU. All meth-
- ods that generate a SNMP message optionally take a ----ccoonn--
- tteexxtteennggiinneeiidd and ----ccoonntteexxttnnaammee argument to configure these
- fields.
- Context Engine ID
- The ----ccoonntteexxtteennggiinneeiidd 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 ----ccoonntteexxtteennggiinneeiidd 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 authorita-
- tiveEngineID 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 ----ccoonntteexxttnnaammee argu-
- ment. The contextName stays with the object until it
- is changed. The contextName defaults to an empty
- string which represents the "default" context.
- _U_s_e_r_-_b_a_s_e_d _S_e_c_u_r_i_t_y _M_o_d_e_l _A_r_g_u_m_e_n_t_s
- The User-based Security Model (USM) used by SNMPv3
- requires that a securityName be specified using the --uusseerr--
- nnaammee argument. The creation of a Net::SNMP object with
- the version set to SNMPv3 will fail if the ----uusseerrnnaammee
- argument is not present. The --uusseerrnnaammee 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 ----aauutthhkkeeyy or ----aauutthhppaasssswwoorrdd arguments are speci-
- fied, the securityLevel becomes 'authNoPriv'. The ----aauutthh--
- ppaasssswwoorrdd argument expects a string which is at least 1
- octet in length. Optionally, the ----aauutthhkkeeyy argument can
- be used so that a plain text password does not have to be
- specified in a script. The ----aauutthhkkeeyy argument expects a
- hexadecimal string produced by localizing the password
- with the authoritativeEngineID for the specific destina-
- tion device. The "snmpkey" utility included with the
- Net::SNMP distribution can be used to create the hexadec-
- imal 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 behav-
- ior can be changed by using the ----aauutthhpprroottooccooll argument.
- This argument expects either the string 'md5' or 'sha' to
- be passed to modify the hash algorithm.
- By specifying the arguments ----pprriivvkkeeyy or ----pprriivvppaasssswwoorrdd
- 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 ----aauutthhkkeeyy or ----aauutthhppaasssswwoorrdd
- arguments are missing, the creation of the object fails.
- The ----pprriivvkkeeyy and ----pprriivvppaasssswwoorrdd arguments expect the same
- input as the ----aauutthhkkeeyy and ----aauutthhppaasssswwoorrdd arguments
- respectively.
- The User-based Security Model described in RFC 3414
- defines a single encryption protocol to be used for pri-
- vacy. This protocol, CBC-DES "DES" (NIST FIPS PUB 46-1),
- is used by default or if the string 'des' is passed to the
- ----pprriivvpprroottooccooll 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 proto-
- col can be selected using the ----pprriivvpprroottooccooll 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 proto-
- cols, differentiated by their key sizes, can be selected
- by passing 'aescfb128', 'aescfb192', or 'aescfb256' to the
- --pprriivvpprroottooccooll argument.
- DDeettaaiillss oonn FFiilltteerrss
- 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 ref-
- erences 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:
- "aanndd" (equivalent with "&&&&")
- Boolean "and" of the two expressions, is only true if
- both expressions are true. Example: _e_x_p_r_e_s_s_i_o_n_1 aanndd
- _e_x_p_r_e_s_s_i_o_n_2
- "oorr" (equivalent with "||||")
- Boolean "or" of the two expressions, is true if either
- or both expressions are true. Example: _e_x_p_r_e_s_s_i_o_n_1 oorr
- _e_x_p_r_e_s_s_i_o_n_2
- "nnoott" (equivalent with "!!")
- Boolean negation of a single expression. Example:
- nnoott _e_x_p_r_e_s_s_i_o_n . Yet another example: !!_e_x_p_r_e_s_s_i_o_n
- (For more details on this I recommend a book on Perl)
- _P_r_e_d_e_f_i_n_e_d _F_i_l_t_e_r _V_a_r_i_a_b_l_e_s
- 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 evalu-
- ated 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)'
- $$iiff__ttyyppee
- 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 paran-
- thesis 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
- $$ddeeffaauulltt
- True if and only if cfgmaker normally should accepted
- the interface based on the interfaces administrative
- and operational state (taking the flags ----nnoo--ddoowwnn and
- ----sshhooww--oopp--ddoowwnn into account) and it's type (and a few
- other things).
- $$ddeeffaauulltt__iiffssttaattee
- 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 ----nnoo--ddoowwnn and ----sshhooww--oopp--ddoowwnn).
- $$ddeeffaauulltt__iiffttyyppee
- True if and only if cfgmaker would have accepted the
- interface based on it's type (and a few type specific
- details in addition).
- $$iiff__aaddmmiinn
- True if and only if the interface is in an adminstra-
- tive up state.
- $$iiff__ooppeerr
- 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.
- $$iiff__iiss__eetthheerrnneett
- True for ethernet interfaces (nr 6, 7, 26, 62, 69 and
- 117).
- $$iiff__iiss__iissddnn
- True for various ISDN interface types (nr 20, 21, 63,
- 75, 76 and 77)
- $$iiff__iiss__ddiiaalluupp
- True for dial-up interfaces such as PPP as well as
- ISDN. (nr 23, 81, 82 and 108 in addition to the num-
- bers of $$iiff__iiss__iissddnn).
- $$iiff__iiss__aattmm
- True for miscellaneous ATM related interface types (nr
- 37, 49, 107, 105, 106, 114 and 134).
- $$iiff__iiss__wwaann
- True for WAN interfaces point to point, Frame Relay
- and High Speed Serial ( 22,32,44,46)
- $$iiff__iiss__llaann
- True for LAN interfaces (8, 9, 11, 15, 26, 55, 59, 60
- and 115 in addition to the numbers of $$iiff__iiss__eetthheerr--
- nneett).
- $$iiff__iiss__ddssll
- True for ADSL, RDSL, HDSL and SDSL (nr 94, 95, 96, 97)
- $$iiff__iiss__llooooppbbaacckk
- True for software loopback interfaces (nr 24)
- $$iiff__iiss__cciissccoovvllaann
- True for Cisco VLAN interfaces (interfaces with the
- word Vlan or VLAN in their ifdescs)
- $$iiff__vvllaann__iidd
- Returns the vlan id associated with a specific port on
- Cisco Catalyst switches under both Catalyst OS and
- IOS. If it is not a vlan interface, will return
- undef.
- $$iiff__MMTTUU
- 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 avaiable in
- the future instead.
- _E_x_a_m_p_l_e_s _o_n _F_i_l_t_e_r_s
- 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'
- DDeettaaiillss oonn TTeemmppllaatteess
- 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 "<", ">" and "&" 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).
- _W_r_i_t_a_b_l_e _T_e_m_p_l_a_t_e _V_a_r_i_a_b_l_e_s
- These are the variables available to store the configura-
- tion 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 hap-
- pens: 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
- $$ttaarrggeett__lliinneess are turned into comments by adding a hash
- mark ("#") at their beginning. Then all the variables
- $$hheeaadd__lliinneess, $$pprroobblleemm__lliinneess , $$ttaarrggeett__lliinneess and $$sseeppaarraa--
- ttoorr__lliinneess are concatenated together to form the lines to
- add to the configuration file.
- $$ttaarrggeett__lliinneess
- This variable is the placeholder for the configuration
- lines created by the template. $$ttaarrggeett__lliinneess is pre-
- defined to be empty when the template code is evalu-
- ated.
- $$hheeaadd__lliinneess
- 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 $$hheeaadd__lliinneess
- during evaluation, the comment will look like usual in
- the config file.
- $$pprroobblleemm__lliinneess
- 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 $$pprroobblleemm__lliinneess 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 $$pprroobblleemm__lliinneess to find
- out if an interface will be included or rejected but
- this is not recommended. Test against $$iiff__ookk instead.
- $$sseeppaarraattoorr__lliinneess
- This variable is the placeholder for the string to use
- as the separator between the code for individual tar-
- gets. 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).
- _P_r_e_d_e_f_i_n_e_d _T_e_m_p_l_a_t_e _V_a_r_i_a_b_l_e_s
- All the variables below are available for interface tem-
- plates to use. For host templates, only those listed
- under "Host and System Variables" are available.
- For interface templates the variables listed under "Prede-
- fined Filter Variables" are also available.
- _H_o_s_t _a_n_d _S_y_s_t_e_m _V_a_r_i_a_b_l_e_s
- $$rroouutteerr__nnaammee
- 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 ----ddnnss--ddoommaaiinn.
- $$rroouutteerr__ccoonnnneecctt
- 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, ----ccoommmmuunniittyy, ----ssnnmmpp--ooppttiioonnss and ----ddnnss--ddoommaaiinn.
- (There's no HTML escaped variant available)
- $$ddiirreeccttoorryy__nnaammee
- 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 ----ssuubbddiirrss command line option. If ----ssuubbddiirrss isn't
- specified $$ddiirreeccttoorryy__nnaammee will be the empty string.
- (There's no HTML escaped variant available)
- $$ssyyssccoonnttaacctt
- This variable is the router's SNMP sysContact value.
- (HTML escaped variant: $$hhttmmll__ssyyssccoonnttaacctt)
- $$ssyyssnnaammee
- This variable is the router's SNMP sysName value. (No
- HTML escaped variant available)
- $$ssyyssllooccaattiioonn
- This variable is the router's SNMP sysLocation value.
- (HTML escaped variant: $$hhttmmll__ssyyssllooccaattiioonn)
- $$ssyyssddeessccrr
- 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: $$hhttmmll__ssyyssddeessccrr)
- _I_n_t_e_r_f_a_c_e _T_a_r_g_e_t _R_e_l_a_t_e_d _V_a_r_i_a_b_l_e_s
- $$ttaarrggeett__nnaammee
- 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 direc-
- tives. (There's no HTML escaped variant available)
- $$iiff__rreeff
- 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 ----iiffrreeff command line
- option. It is normally used together with
- $$rroouutteerr__ccoonnnneecctt. (There's no HTML escaped variant
- available)
- $$iiff__ookk
- 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 $$pprroobb--
- lleemm__lliinneess to find out if an interface will be rejected
- or not, use this $$iiff__ookk instead.
- $$ddeeffaauulltt__ttaarrggeett__lliinneess
- This variable contains all the target lines which cfg-
- maker 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 tem-
- plate.
- 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 correspond-
- ing 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.
- $$ddeeffaauulltt__ttaarrggeett__ddiirreeccttiivvee
- This variable contains the default string for the Tar-
- get[] directive line.
- $$ddeeffaauulltt__sseetteennvv__ddiirreeccttiivvee
- This variable contains the default string for the
- SetEnv[] directive line.
- $$ddeeffaauulltt__ddiirreeccttoorryy__ddiirreeccttiivvee
- 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.
- $$ddeeffaauulltt__mmaaxxbbyytteess__ddiirreeccttiivvee
- This variable contains the default string for the
- MaxBytes[] directive line.
- $$ddeeffaauulltt__ttiittllee__ddiirreeccttiivvee
- This variable contains the default string for the
- Title[] directive line.
- $$ddeeffaauulltt__ppaaggeettoopp__ddiirreeccttiivvee
- This variable contains the default string for the
- PageTop[] directive lines.
- _I_n_t_e_r_f_a_c_e _N_e_t_w_o_r_k _C_o_n_f_i_g_u_r_a_t_i_o_n _V_a_r_i_a_b_l_e_s
- $$iiff__iipp
- This variable should contain the IP-address of the
- interface, if any has been assigned to it. (There's
- no HTML escaped variant available)
- $$iiffiinnddeexx
- This variable is the SNMP ifIndex for the interface
- which per definition always is an integer. (There's
- no HTML escaped variant available)
- $$iiff__iinnddeexx
- Equivalent with $$iiffiinnddeexx.
- $$iiff__eetthh
- Contains the ethernet address of the interface, if
- any. (There's no HTML escaped variant available)
- $$iiff__ssppeeeedd
- This variable is the speed in bytes/second (with pre-
- fixes). (There's no HTML escaped variant available)
- $$iiff__ssppeeeedd__ssttrr
- 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)
- $$iiff__ttyyppee__ddeesscc
- This variable is a textual description of the inter-
- face type. (HTML escaped variant: $$hhttmmll__iiff__ttyyppee__ddeesscc)
- $$iiff__ttyyppee__nnuumm
- 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 avail-
- able)
- $$iiff__ddnnss__nnaammee
- This is the DNS name for the interface. (No HTML
- escaped variant available)
- _I_n_t_e_r_f_a_c_e _N_a_m_e_, _D_e_s_c_r_i_p_t_i_o_n _a_n_d _A_l_i_a_s _V_a_r_i_a_b_l_e_s
- It might seem confusing with both _N_a_m_e, _D_e_s_c_r_i_p_t_i_o_n and
- _A_l_i_a_s in this context and to some extent it is. _N_a_m_e and
- _D_e_s_c_r_i_p_t_i_o_n 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 _A_l_i_a_s 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 _D_e_s_c_r_i_p_-
- _t_i_o_n).
- For better control from the command line consider
- $$iiff__ttiittllee__ddeesscc which contents are controlled by the
- ----iiff--ddeessccrr command line option.
- $$iiff__ssnnmmpp__ddeessccrr
- This variable should contain the "raw" description of
- the interface as determined by the SNMP polling of the
- router. (HTML escaped variant: $$hhttmmll__iiff__ssnnmmpp__ddeessccrr)
- $$iiff__ssnnmmpp__nnaammee
- The "raw" name for the interface as provided by SNMP
- polling. (HTML escaped variant: $$hhttmmll__iiff__ssnnmmpp__nnaammee)
- $$iiff__ssnnmmpp__aalliiaass
- The "raw" ifAlias for the interface as provided by
- SNMP polling. (HTML escaped variant:
- $$hhttmmll__iiff__ssnnmmpp__aalliiaass)
- $$iiff__cciissccoo__ddeessccrr
- The "raw" CiscolocIfDescr for the interface as pro-
- vided by SNMP polling. (HTML escaped variant:
- $$hhttmmll__iiff__cciissccoo__ddeessccrr)
- $$iiff__ddeessccrriippttiioonn
- This is the "cooked" description string for the inter-
- face, taking into account the SNMP values found for
- the interface's RDescr, ifAlias and CiscolocIfDescr.
- (HTML escaped variant: $$hhttmmll__iiff__ddeessccrriippttiioonn)
- $$iiff__ttiittllee
- 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 $$ddeesscc__pprreeffiixx,
- $$iiff__ttiittllee__ddeesscc and $$ssyyssnnaammee.
- As $$iiff__ttiittllee depends on $$iiff__ttiittllee__ddeesscc, it is possible
- to indirectly control $$iiff__ttiittllee by using the command
- line option ----iiff--ddeessccrr.
- (HTML escaped variant: $$hhttmmll__iiff__ttiittllee)
- $$iiff__ppoorrtt__nnaammee
- If the host is a Cisco Catalyst LAN switch, this vari-
- able is the name of that port. (No HTML escaped vari-
- ant available)
- $$ddeesscc__pprreeffiixx
- 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 "Traf-
- fic analysis for ". (HTML escaped variant:
- $$hhttmmll__ddeesscc__pprreeffiixx)
- $$iiff__ttiittllee__ddeesscc
- This is the description of the interface normally used
- by cfgmaker as part of the variable $$iiff__ttiittllee. The
- latter is used as the full string in the "Title[]"
- directove and the H1 section in the PageTop[].
- $$iiff__ttiittllee__ddeesscc is controlled by the command line
- option ----iiff--ddeessccrr which indirectly controls the con-
- tents of $$iiff__ttiittllee
- (HTML escaped variant: $$hhttmmll__iiff__ttiittllee__ddeesscc)
- _H_e_l_p _F_u_n_c_t_i_o_n_s _f_o_r _T_e_m_p_l_a_t_e_s
- The following functions exists to facilitate the writing
- of host and interface templates.
- hhttmmll__eessccaappee((_ss_tt_rr_ii_nn_gg))
- _hh_tt_mm_ll____ee_ss_cc_aa_pp_ee_((_)) takes a string as an argument and
- returns a new string where the following substitutions
- has been done: the chars "<", ">" and "&" are
- replaced by "<", ">" and "&" 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).
- _E_x_a_m_p_l_e _T_e_m_p_l_a_t_e _F_i_l_e_s
- Template Example 1: Eliminating Rejected Targets From
- Appearing
- This template file generates exactly the same configura-
- tion 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_namen";
- }
- $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;
- <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="";
- }
- _T_e_m_p_l_a_t_e _E_x_a_m_p_l_e _2_: _S_i_m_p_l_i_e_r _V_e_r_s_i_o_n _o_f _E_x_a_m_p_l_e _1
- Example 1 was partly intended to demonstrate how to cus-
- tomize 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 $$ddeeffaauulltt__ttaarrggeett__lliinneess.
- if($if_ok) {
- $target_lines = $default_target_lines;
- } else {
- $head_lines="";
- $problem_lines="";
- $target_lines="";
- $separator_lines="";
- }
- _T_e_m_p_l_a_t_e _E_x_a_m_p_l_e _3_: _C_r_e_a_t_i_n_g _C_P_U _T_a_r_g_e_t_s _f_o_r _H_o_s_t_s
- 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]: 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
- EEXXAAMMPPLLEESS
- The first example creates a config file for
- _r_o_u_t_e_r_._p_l_a_c_e_._x_y_z: the router has the community name _p_u_b_-
- _l_i_c. Interfaces get identified by their IP number. Two
- global options get added to the config file. The config
- file gets redirected to _m_r_t_g_._c_o_n_f. 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:
- _r_o_u_t_e_r_1_._p_l_a_c_e_._x_y_z, _r_o_u_t_e_r_2_._p_l_a_c_e_._x_y_z, _s_w_i_t_c_h_1_._p_l_a_c_e_._x_y_z
- and _s_w_i_t_c_h_2_._p_l_a_c_e_._x_y_z all with the community _p_u_b_l_i_c.
- The two routers will have ----iiffrreeff set to ddeessccrr whilst the
- two switches will use ----iiffrreeff set to nnaammee. Further the
- routers will use ----iiffddeesscc set to aalliiaass and
- _s_w_i_t_c_h_1_._p_l_a_c_e_._x_y_z will use ----iiffddeesscc set to ddeessccrr whilst
- _s_w_i_t_c_h_2_._p_l_a_c_e_._x_y_z use nnaammee 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 ----ccoommmmuunniittyy,
- ----ssnnmmpp--ooppttiioonnss and ----ddnnss--ddoommaaiinn to make the command line
- simpler. All the equipment will use the community _h_i_d_d_e_n,
- except for the ppp-server which use community _a_c_c_e_s_s. All
- equipment uses these SNMP options: 11ss ttiimmeeoouutt, 11 rreettrryy and
- SSNNMMPP vveerrssiioonn 22 (bbaacckkooffff and ppoorrtt is unspecified which
- means they use the default values). The exception again
- is the ppp-server which uses SSNNMMPP vveerrssiioonn 11. Finally, all
- the equipment is part of the domain _p_l_a_c_e_._x_y_z, except for
- the ppp-server which is part of the domain
- _r_e_m_o_t_e_._p_l_a_c_e_._x_y_z. Note that the latter is achieved simply
- by specifying the name of the ppp-server to be
- _p_p_p_-_s_e_r_v_e_r_._rr_ee_mm_oo_tt_ee .
- 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
- SSEEEE AALLSSOO
- mrtg-reference
- AAUUTTHHOORR
- Tobias Oetiker <tobi@oetiker.ch> and Jakob Ilves
- <jakob.ilves@oracle.com>
- LLIICCEENNSSEE
- GNU General Public License
- CCOOPPYYRRIIGGHHTT
- Cfgmaker is Copyright 2000 by Tobias Oetiker
- <tobi@oetiker.ch>
- 2.13.2 2006-02-03 CFGMAKER(1)