IpPlugin

IP Address information for Foswiki

This plugin provides functions for obtaining information about IP addresses. It is useful when you want to identify a user by IP address.

For example, you may change content if a user is on your internal network. Or you may want to display a special icon if the user is using an IPV6 address.

It will also translate host names to addresses (and vice-versa when that's possible). Both IPV4 and IPV6 addresses are supported.

Syntax Rules

%IP{ address="192.0.2.100" get="attribute" range="192.0.2/24" noerror="1" numeric="1" }%

address is the default argument, so address= may be omitted

The default address is the address of the Foswiki client (REMOTE_ADDR).

The default attribute is type.

All attributes return a meaningful value for both IPV4 and IPV6 addresses.

range can be a comma-separated list of IPV6 address/prefixes andIPV4 address/prefixes, in any combination. It (currently) only applies to the is_in and not_in attributes.

By default, the class, is_in and not_in attributes return text strings. If you are using them in %IF or %CALC expressions, numeric="1" will return numeric codes that are easier to test.

By default any errors in arguments or name resolution are returned as a red text string.

noerror can be set true if you want errors ignored. In this case, the query is returned unmodified when errors are detected. This behavior may be desirable if you'd rather display an unresolvable hostname as its IP address rather than an error string. But you should always test your page without noerror first, so that any errors in the arguments can be fixed.

Attributes:

Attribute		#	Definition
class				Returns the class of an address
	IPV4	0	PUBLIC	Unique, globally routable address
		1	PRIVATE	Private networks: 0/8, 10/8, 127/8, 172.16/12, 192.168/16
		2	RESERVED	Special use addresses: 169.254/16, 192.0.2/24, 224/4, 240/5, 248/5
	IPV6	3	GLOBAL-UNICAST	Unique, globally routable host address
		4	UNIQUE-LOCAL-UNICAST	Unique, local-only routable host address
		5	LINK-LOCAL-UNICAST	Link-local, non-routable host address
		6	MULTICAST	Multicast
		7	IPV4COMP	IPV4 compatible space ::/96
		8	IPV4MAP	IPV4 mapped addresses ::FFFF:0:0/96
		9	LOOPBACK	Loopback address ::1/128
		2	RESERVED	Everything else
display			Returns the address in display format. IPV6 :: notation
expand			Returns the expanded address. IPV6 no ::
hostaddress			Returns the address(es) corresponding to a hostname. Use hostame instead of address to specify the input if you prefer clarity.
hostname			Returns the hostname corresponding to the address, or the address if name unknown
is_in			Returns "TRUE" or "1" if address is in range; otherwise "FALSE" or "0"
not_in			Returns "TRUE" or "1" if address is not in range; otherwise "FALSE" or "0"
reverse			Returns the reverse zone name of an address (in-addr.arpa or ip6.arpa)
type			Returns the type of address: 4 or 6 for IPV4 or IPV6 respectively

is_in and not_in_ are only meaningful when specified with a range. The address is compared to each item in the range to see if the item contains the address. IPV4 and IPV6 addresses are considered disjoint in these comparisons; an IPV4 address will never match an IPV6 range, and vice-versa. This is true even if the IPV6 item is IPV4MAP or IPV4COMP. To check an IPV4 address against all possible aliases, the range selector must have elements for IPV4 native, IPV4MAP and IPV4COMP.

Examples

This table shows the results of sample uses of the %IP% variable. The results are simulated so that they will display correctly even if you do not have the IpPlugin installed when viewing this page.

Macro call	Result	Remarks
%IP% equivalent to %IP{ address="%REMOTE_ADDR%" get="type" }%	6	Your IP address is 2001:db8::444
%IP{ "192.0.2.100" get="class" }%	RESERVED
%IP{ "2001:DB8:0::100" get="display"}%	2001:db8::100	Normalized IPV6 display
%IP{ "2001:DB8::100" get="expand"}%	2001:0db8:0000:0000:0000:0000:0000:0100	Expanded IPV6 address
%IP{ "www.foswiki.org" get="hostaddress" }%	66.220.11.188	IP address of www.foswiki.org
%IP{ "18.9.22.169" get="hostname" }%	WWW.MIT.EDU	Hostname from an IP address
%IP{ "192.0.2.100" get="is_in" range="192.0.2/24" }%	TRUE	Address is in range
%IP{ "2001:DB8:0::100" get="not_in" range="2001:db8::0/32" }%	FALSE	Address is in range
%IP{ "192.0.2.100" get="reverse" }%	100.2.0.192.in-addr.arpa.	Reverse address zone
%IP{ "2001:DB8:0::100" get="reverse" }%	0.0.1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
%IF{"%IP{get="is_in" range="10/8, 2001:db8::/32" numeric="1"}%=1" then="In the office" else="At home"}%	In the office
%IF{"%IP% = 4" then="<img alt=\"IPV4 Icon\" src=\"%ATTACHURL%/IPv4-gray.png\"/>" else="<img alt=\"IPV6 Icon\" src=\"%ATTACHURL%/IPv6-green.png\"/>"}%		Your connection type

Test

IpPlugin plugin is installed and enabled on this wiki

You should see your web browser's IP address and connection type below:

Your IP address	Connection type	Icon
%IP{ get="display"}%	IPV%IP%	None

Plugin Settings

• Set SHORTDESCRIPTION = IP Address functions
• There are no other settings for this plugin.

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 Foswiki server.

• Make sure you have an up-to-date Socket (get the latest from cpan) You may need a patch - see This bug report
• Download the .zip or .tgz file from the Plugin Home (see below)
• Optional: Download the .md5 file and verify that the checksums match. On most systems:
  • md5sum -c IpPlugin.md5
• unzip IpPlugin.zip or tar -xzf IpPlugin.tgz in your foswiki installation directory.
• You may have to correct permissions/ownership to the webserver user
• You can use the automated installer.
  • Run IpPlugin_installer as the webserver user to automatically check and install other modules that this module depends on, and enable the plugin.
• Alternatively,
  • Ensure that the dependencies listed below are met,

    File:	Description:
    data/Foswiki/IpPlugin.txt	Plugin topic
    data/Foswiki/IpPlugin.txt,v	Plugin topic repository
    pub/Foswiki/IpPlugin/IPv4-gray.png	Sample graphic
    pub/Foswiki/IpPlugin/IPv6-green.png	Sample graphic
    lib/Foswiki/Plugins/IpPlugin.pm	Plugin Perl module

  • Set the ownership of the extracted directories and files to the webserver user.
• Configure the Plugin:
  • Run the configure script to enable the Plugin
• Test the plugin by viewing the IpPlugin topic on your system and verify that the Test section indicates that IpPlugin is installed and active.

Plugin Info

Plugin Author:	Foswiki:Main.TimotheLitt
Copyright:	© 2012, Foswiki:Main.TimotheLitt
License:	GPL (GNU General Public License)
Plugin Version:	24 Sep 2012 (V1.000)
Change History:
24 Sep 2012:	Initial version
02 Oct 2012:	Add automated installer. No functional changes.
07-Oct-2012:	Foswiki port. No functional changes.
Foswiki Dependency:	$Foswiki::Plugins::VERSION 1.1
CPAN Dependencies:	CPAN:Socket, CPAN:Net::IP
Other Dependencies:	none
Perl Version:	5.8.8
Home:	http://foswiki.org/Extensions/IpPlugin
Support:	http://foswiki.org/Support/IpPlugin

-- TimotheLitt - 25 Sep 2012