PINGER2(1) User Contributed Perl Documentation PINGER2(1) NNAAMMEE PingER2 - New version of PingER with more configurability and maintain- ablity SSYYNNOOPPSSIISS Edit pinger.xml to configure pingER2. To run pinger2 execute: "perl pinger2.pl." Pinger will ping all the hosts listed in the configuration and output the results in the DataDirectory PPiinnggeerr..XXMMLL CCoonnffiigguurraattiioonn FFiillee FFoorrmmaatt The Pinger.XML configuration file is written in XML following the XML Schema Definition in pinger.xsd. PingER2 does not check the file for adherence to this schema and might crash if the configuration file is corrupted. Use a XML-validator (for example http://apps.gotdot- net.com/xmltools/xsdvalidator/) to make sure manual changes to the file are correctly done. Preferred and strongly encouraged is the use of the configuration GUI. In case you should edit the configuration file manu- ally make sure that you pay attention to exact capitalization (e.g. TimeToNotification != TimetoNotification). Main Group All the configuration groups are contained in a and pair. Example: See the file pinger.example.xml in the main directory of the PingER distribution. Contains the version number of the PingER2 program. This will be used to convert the file-format to a new version when PingER2 evolves. Example: 2.0.0 All output produced from PingER2 will be dumped into this Directory. If you want to publish PingER2 data on the web using 'connectivity.pl' from the PingER distribution then make sure that this location is accessible. The path has to be provided without a trailing '/'. Example: /home/PingER/data This is the name of the machine where PingER2 runs. PingER2 can try to determine this automatically if this entry is missing. Since this name appears in the output of PingER2 this not be a bogus value like Localhost. Example: gaia9.cc.gatech.edu This IP will be outputted by PingER2 and can be determined by if the entry is missing. Example: 192.168.2.1 This number determines how many current ping processes are spawned by PingER2. This effectively multiplies the speed of PingER2. Make sure that you have clearance from your Networking Department to lunch massive ping attacks and refrain from ping- ing arbitrary targets for fun. This might lead to ICMP relay being disabled or you getting mail from network admins. Example: 5 PingER2 uses this command to query IPV4 addresses from DNS. The command should return a single line containing the IP or a blank line. Popular 'dig' or 'host' will return multiple lines due to CNAME or multiple IP addresses. PingER2 distribution contains a helper script called DnsV4Cmd.pl that uses Perl built-in gethostbyname to resolve host names to IPV4 addresses. For IPV6 such a built-in does not exists so that dig had to be used. The command should include %destination which will be replaced by PingER2 with the host name. Example: /home/pinger/pinger/dnsV4Cmd.pl %destination Exactly as DnsV4Cmd but defines the DNS-command to be used for IPV6 lookups. The command and it's caveats are described within the description of DnsV4Cmd. Example: /usr/bin/dig -t aaaa +short %destination PingER2 uses this command to ping individual host using IPV4 protocol. PingER2 will try to determine this command during the installation. Make sure that the user the script is run under has all the rights to execute the PingCmd, which might not be the case if you are running a security restricted *nix distri- bution. This means that either you have to have suid-bits set on the command or run the script using root rights of which the latter is strongly discouraged. The following identifiers should be present in the command: * %deadline Should be placed where the timeout parameter is placed * %count Will be replaced with the number of pings to send * %interval The script fills in the interval between individ- ual pings * %packetsize The size of individual packets will be entered here by the script * %destination The destination IP, without it there is no ping. Example: /bin/ping -n -w %deadline -c %count -i %interval -s %packetsize %destination Exactly the same as PingV4Cmd but for identifying the command used for pinging IPV6 hosts. Example: /bin/ping6 -n -w %deadline -c %count -i %interval -s %packetsize %destination The list of beacons stored in can be updated according to the entries in . This is recom- mended because using this technique no unnecessary hosts are pinged and new entries will be automatically updated. This tag has the following sub-entries: This is the command which will be used to retrieve the bea- cons List. %s will be expanded to the URL of the file to fetch as defined in BeaconListURL. Holds the address of the file to be downloaded using the command and be parsed for beacon information. Will be filled with a value by PingER2 to keep track of the last time the beaconList was retrieved. A date that determines the amount of time between two con- sequitive downloads of the list (See section on dates for examples and reference to the format used). Example: lynx -source -dump %s 1 day 1077803679 http://www-iepm.slac.stanford.edu/pinger/beacons.txt ::= BOOLEAN Using the values 'true' and 'false' it is possible to configure pinger to wait a random amount of time inside each ping inter- val specified by . Given for instance a waitIn- terval of 30 minutes and 'true' for doRandomWait, PingER2 will start pinging hosts anywhere inside each 30 minutes interval. This option is usefull if regular pings every day at the same time are not desireable (for instance if they might be regis- tered by the network administrator of the host ping or inter- fere with other regular activities as backups, etc.). Example: true ::= TIME IN MINUTES Specifies the amount of time to wait between runs of PingER2. Please notice that since PingER2 uses Cron to handle the activiation of the pinger2.pl script in regular intervals, it is necessary that after each change to the value of waitInter- val the script installCron.pl needs to be executed. The script will update the existing cron-table by replacing the current pinger2.pl entry with the new values. The amount of time should be specified in minutes, but can alternatively also be given using the modifiers hour, day, week or month. Example: 1 hour This field holds any number of -entries which will get called by PingER2. In contrast to these entries are not overridden by the refresh as defined in . That means that all custom hosts that are to be monitored in addition to the BeaconList should go into this list. Example: www.cc.gatech.edu www.foo.bar 192.168.1.1 This tag groups any number of -entries which will get called by PingER2. In contrast to these entries are overridden by the refresh as defined in . Customizations of the list of hosts to be pinged should go into the . Example: 134.79.18.21 false 50 ping.slac.stanford.edu 131.225.9.20 false 20 fnal.fnal.gov Sub-Entries: ::= xs:complexType Using this tag allows the configuration of individual host. The most important sub-tag is . Using this name PingER2 can effectively determine the IP and will assume default settings for the rest of the configuration parameters. Sub-Tags: ::= BOOLEAN If set to true this entry will enable the internal DNS- caching functionality. This means that PingER2 will store IPs to guard against DNS-failure. Example: true ::= BOOLEAN A host can be excluded from being pinged by setting this value to false. Example: false ::= A|Quad-A IP Address PingER2 will try to determine the IP address of the host using a DNS lookup when possible. To circumvent this lookup PingER2 provides this tag to statically assign an IP. Be aware that PingER2 also provides a DNS-cache which will utilize this field to store queried DNS-information. Example: 192.168.1.2 ::= full|... Determines how much of the statistics gathered from pinging this host will be stored in the data output. If the value is set to 'full' then all available information are dumped into the data directory. All other values reduce the output to "min/max/avg". Example: minimal ::= STRING The name of the host to be pinged. This is the essential tag that needs to be supplied for all s. Example: www.cc.gatech.edu ::= IPV4|IPV6 Controls IPv4 vs. IPv6 behavior in PingER2. To ping a indi- vidual host with both IPV4 and IPV6 the corresponding host entry has to be duplicated. Example: IPV4 ::= INTEGER Determines the amount of time to be wait between individual pings. Be aware that this will increase the time pingER2 needs to complete it's task. Example: 1 Complex Tags (still inside ) If PingER2 fails to reach the host or while determining the IP, Alarm offers a way to configure PingER2 to notify the maintainer of the local PingER version. This feature should be seen as warning tool or as a convenience feature for the beacon list maintainer. ::= TIME Determines the amount of time PingER will ignore fail- ures. When the interval passed without a successful ping or DNS-lookup then alarm will be invoked. Example: 12 hours ::= true|false This tag is used by pingER2 to switch off the Alarm when Snoozing is diabled or can be used by the main- tainer to do the same manually. Example: true ::= true | false With this feature PingER2 tries to simulate an alarm clock that goes back to sleep after the alarm rings only to ring again after the alarm interval passed again. If snooze is disabled an alarm will only trigger once. The alarm feature does not interfere with the host being pinged, it's just a convenience. Example: true >> ::= INTEGER This tag will hold the value in seconds after 1970 since when the failure occurred. PingER2 uses this value to determine when the alarm has to go off. Example: 1077812075 ::= STRING The AlarmCmd is triggered whenever a host exceeded the specified alarm interval. This parameter should contain %message which will be replaced before executing the command. The first example provided appends the error message to the log.file while the second sends an email to the account holder under which PingER2 is run. Example: echo '%message' >> log.file echo -e '%message' | mail `whoami` -s "PingER2 Error Message" This complex tag holds all information that determines how to ping a individual host. It is possible to have multiple entries per . PingER2 will traverse them one by one. The following two entries get grouped inside a -entry: ::= INTEGER The number of pings to send to the host. Notice that a large number will also take a respective amount of time, since pings are spaced with a time from . Example: 10 ::= INTEGER The size in byte of the payload sent to the host as part of the ICMP echo request. A large packet size may overload poor connections especially in developing countries. Example: 100 Example for Ping: 1000 10 This tag is structured exactly as but provides opportu- nity to provide default values, i.e. whenever a configuration tag is not found in a entry the will be queried. This saves disk space for the configuration file and makes it more easier to read and modify. DDeessccrriippttiioonn ooff IInntteerrnnaall VVaarriiaabblleess The following variable are used inside the PingER script that might be interesting when extending PingER2. logLevel Represents the amount of logging done by PingER2. From 0 to 10 where 0 is 0 is no and 10 is maximal logging. logFile Handle to the file which is used for logging. config This holds the data structure representation of the data unserial- ized from the configuration file using XML::Simple. beaconList, hostList These list are arrays of the respective hosts. defaultHost This variable holds the datastructure representing the fall-back options if the host does not specify it. dataDirectoy Retrieved from the configuration db. All data output is dumped into this directory. pingV4Cmd, pingV6Cmd, dnsV4Cmd, dnsV6Cmd Command strings to the respective commands. Should contain % quan- tifiers. srcName, srcIP Information representing the source machine. ProcessCount, maxProcessCount Number of current and maximal processes performing ping-queries. DDeessccrriippttiioonn ooff IInntteerrnnaall FFuunnccttiioonnss _c_h_e_c_k_B_e_a_c_o_n_C_o_n_f_i_g_u_r_a_t_i_o_n_(_) This function will retrieve information from the web about beacons and updates entries in the "". Caution: All existing sub-entries of "" will be overriden. Entries that are to survive update should to into "" In: The function takes no parameters. Out: The function returns no value. ppaarrsseeTTiimmee((ddaatteeSSttrriinngg)) This function will take it''s input parameter and transform it into seconds. ParseTime takes a string and extracts a number and an optional quantifier. The following time quantifiers are understood. · mi = Minutes = 60 seconds · mo = Months = 30 * 24 * 60 * 60 seconds · h = Hours = 60 * 60 seconds · d = Days = 24 * 60 * 60 seconds · w = Weeks = 7 * 24 * 60 * 60 seconds · y = Years = 365 * 24 * 60 * 60 seconds In: String with a time value. Out: Time in seconds. ggeettAAttttrriibbuutteeWWiitthhAAlltteerrnnaattiivvee((mmaaiinn,,aalltteerrnnaattiivvee,,aattttrriibbuutteeNNaammee)) Thefunction will retrieve an attribute from a given XML::Simple data structure. If the attribute is not available, the function will fall back onto an alternative data structure. In: Main data structure, Alternative data structure and attribute name Out: Value of the retrieved attribute or undef if the item could not be found in both the main and alternative data structure. ggeettHHoossttAAttttrriibbuuttee((hhoosstt,,aattttrriibbuuttee)) Retrieves an attribute from the given host or falls back onto the default host if the attribute could not be found. In: Host reference and attribute name. Out: Value of the retrieved host attribute or the value given by the defaultHost for that attribute. Undef if neither is available. ggeettGGrroouuppAAttttrriibbuuttee((hhoosstt,,ggrroouupp,,aattttrriibbuuttee)) Retrieves an attribute in a sub-entry of the given host or looks that entry up in the default host. That function is necessary for more com- plex lookups into the host/defaultHost data structures. In: Host reference, group name and attribute name. Out: The group attribute if found in the host, the sub-entry of the defaultHost/group or undef. sseettGGrroouuppAAttttrriibbuuttee((hhoosstt,,ggrroouupp,,aattttrriibbuuttee,,vvaalluuee)) Sets an attribute in a sub-entry of the given host. If the group does not exists it will be created. In: Host reference, group name, attribute name and value. Out: The function does not return any value. rreettrriieevveeAAnnddcchheecckkFFoorrDDeeffaauulltt((ttaaggNNaammee,, ddeeffaauullttVVaalluuee)) Will try to retrieve a tag with the given name from the main group. If the tag is not available it will set it to the value passed as the second parameter. In any case the function returns the value of the tag in the main group. ggeettLLiisstt((lliissttNNaammee)) The function will return the given list from the configuration file and initializes it with an empty entry in case the list did not exist. In: Name of the list to retrieve. Out: An array of the entries in the list. If the list is empty or did not exist an empty array is returned. cchheecckkDDeeffaauullttHHoossttCCoonnffiigg((hhoosstt)) This function will check and initialize the default values of the defaultHost entry. This is important because several functions lateron rely on results from the get*Attribute functions. In: The reference to the default host. Out: This function does not return any value. aallaarrmm((hhoosstt,,mmeessssaaggee)) The alarm function can be called anytime a problematic situation has occured. It will lookup the alarm configuration and trigger the alarm- Cmd if alarm time has exceeded. There is oneshot-functionality embedded in the alarm-system, that allows for notifications to be triggered only once. Input: Host that has produced an error and the error message. Output: This function does not produce any results. aallaarrmmNNoottiiffyy((hhoosstt,,mmeessssaaggee)) Does bypass the tolerance function of the alarm-system and directly dispatches a notification for the given host. Snoozing/Oneshot-func- tionality is maintained. Input: The host for which an alarm was triggered and the message to send to the administrative team. Output: This function does not produce any results. ggeettIIPP((hhoosstt)) Performs an DNS-lookup using the ipv4 or ipv6 command and retrieves the address as a string in A/AAAA format. Input: The host for which the DNS-lookup shall be performed. Output: The IP in A/AAAA format. uuppddaatteeDDNNSSCCaacchhee((hhoosstt)) Retrieves a new IP address for the given host and renews the cache using the retrieved address. Input: The host whose cache is to be updated. Output: This function does not produce any results. qquueerryyDDNNSSCCaacchhee((hhoosstt)) This function implements the query strategy for retrieving IP addresses. All the key logic of that strategy can be found inside this function. The current strategy can be described as follows: · A DNS lookup is always performed, regardless of whether the DNS- cache is on or off. A warning will always be issued when the DNS- lookup fails. · If the DNS-Cache is ON the following decision-path is taken: · if cached IP and retrieved IP are identical this IP is returned. · if cache and DNS-lookup disagree then the alarm function of the host is called and the new DNS entry takes the place of the cached one and is also returned. · If the DNS-Cache is OFF the following decision path happens: · If an IP has been given in the configuration it will always be prefered over the DNS-lookup. Appropriate warnings will be gen- erated. · If no IP is given the lookup-result will be returned. Input: The host to query an IP for. Output: An IP for the host or undefined. ddooPPiinngg((iipp,,iinntteerrvvaall,,ssiizzee,,nnuummPPiinnggss,,hhoosstt,,rreessuullttssMMaatttteerr)) This function sends the actual pings. It relies on the configured ping-tools to do the dirty work. Input: · ip = The IP of the host to ping. · interval = The interval between individual pings. · size = The size of the individual ping packets. · numPings = The number of pings of the given size to send. · host = The host structure for the IP address to ping. Needed to select IPV4/6 and to route alarm-functionality appropiately. · resultsMatter = Since the first ping of each batch is just used to prime the communication-channel this flag can be used to disable the logging of result. Output: Will return either a list of the results or undefined on fail- ure. lloogg__iitt((........)) This subroutine logs entries to the ping record file. It opens the file exclusively so that other processes will have to wait until this write is finished. Input: A huge number of parameters that hold all the statistics that need to be logged (8-15 parameters to be exact). Output: -1 on error, undefined otherwise. ppiinnggHHoosstt((hhoosstt)) Ping the given host accordingly to the entries given in the configura- tion file. All calls to doPing are concurrently using a server/client pipe. Input: The host to be pinged. Output: This function does not return any result. llooggggeerr((mmeessssaaggee,,llooggLLeevveell)) Will print the message passed if the set logLevel is high enough to surpass the current setting. Input: The message and the logLevel. Output: This function does not return any results. wwaaiittFFoorrCChhiilldd((PPiippeeIInnffoorrmmaattiioonn)) Will wait for one child, read the information the child produced and copy the state the child produced into the configuration xml setting. Input: The list of all processes spawned from the current one. Output: This function does not produce any results. _p_i_n_g_A_l_l_H_o_s_t_s_(_) This function will ping all hosts given in both the host- and the bea- con-list. Input: This function does not expect any parameters. Output: This function does not return any results. CCOOPPYYRRIIGGHHTT PingER2 is based on PingER from SLAC. 2004 - Christopher Ozbek - cozbek@cc.gatech.edu This is free software. Redistribute and modify under the same license as Perl itself. perl v5.8.8 2007-02-07 PINGER2(1)