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:
-
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
--
TimotheLitt - 25 Sep 2012