%META:TOPICINFO{author="TWikiContributor" date="1354416507" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="Sandbox.PluginDevelopment"}%
---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/PingPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/PingPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{ title="Page contents" depth="2" }%
</div></sticky>
This plugin tests if a remote host identified by host name or IP address is reachable via ping command.

---++ Syntax Rules

%INCLUDE{"VarPING"}%

---++ =PING= Examples

---+++!! Basic Usage
<verbatim>
%PING{ host="www.google.com" wait="1" }%
</verbatim>
%PING{ host="www.google.com" wait="1" }%

<verbatim>
%PING{ host="irs.gov" wait="1" }%
</verbatim>
%PING{ host="irs.gov" wait="1" }%

<verbatim>
%PING{ host="www.yahoo.com" wait="1" format="$host result is $result" }%
</verbatim>
%PING{ host="www.yahoo.com" wait="1" format="$host result is $result" }%

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>PINGPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Test if a remote host is reachable via ping command

   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server. 

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/VarPING== | PING variable documentation |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | Plugin Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.
      * Make sure the dependencies listed in the table below are resolved.
        <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Net::Ping</td><td align="left">&gt;=0</td><td align="left">Required.</td></tr></table>

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script, enable the plugin in the __Plugins__ section
      * Test if the installation was successful: See examples above.

---++ Plugin Info

|  Plugin Author: | TWiki:Main.MagnusLewisSmith |
|  Copyright: | &copy; 2005 TWiki:Main.MagnusLewisSmith%BR% &copy; 2010-2012 Peter Thoeny, [[http://twiki.org/][TWiki.org]] |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2012-12-01 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2012-12-01: | TWikibug:Item6962: Fix manifest; add category to VarPING; doc enhancements -- TWiki:Main.PeterThoeny |
|  2012-06-06: | TWikibug:Item6613: Adding format parameter -- TWiki:Main.AaronLWalker |
|  2005-09-28: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarPING, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
