= IP-Role Mapper Service Usage =

The IP-Role mapper is a REST based web-service which provides methods for mapping roles to IP address ranges and an IP address to a number of associated roles. It will work both with IPv4 and IPv6 addresses, even mixed, however depending on the contents of the configuration file.

The configuration file for the service can be modified or moved while the service is running. Any changes will make the service re-load the configuration the next time any of its methods are invoked. However, bear in mind that the appropriate {{{context-param}}} in the server configuration or the {{{web.xml}}} file must be updated if the configuration file is moved to another directory.

The IP-Role mapper service will continue using the last known good configuration in the event that the configuration file gets corrupted. E.g. after it has been edited.

This web-service provides three methods; getRanges, getRoles and status, which are described below:

== getRanges ==
This method returns a new-line separated list of IP ranges associated with one or more roles. If any of the IP ranges, associated with the roles, overlap each other then they will be merged into a single range.

The method is invoked by an URL of the form:
{{{
http://<context root>/iprolemapping/getRanges&role=<some role>&role=<another role>....&role=<yet another role>
}}}

=== Example: ===

Typing:

{{{
http://alhena:7980/iprolemapping/getRanges?role=inhouse&role=doghouse&role=henhouse
}}}

in a web browser could make the test system return (depending on the configuration):

{{{
172.18.0.0-172.18.255.255
130.255.26.35
127.0.0.1
172.16.7.0-172.16.7.255
130.225.24.0-130.225.25.255
130.225.26.33
}}}

Any queries on roles which do not exist in the configuration will just be ignored. Thus, if there are no "hits" on the query, then the service will reply with an empty page.

== getRoles ==

This method returns a comma separated list of all the roles associated with a specific IP address (IPv4 or IPv6 depending on the configuration) and it is invoked by an URL of the form:
{{{
http://<context root>/iprolemapping/getRoles/<IPv4 or IPv6 address>
}}}

=== Example: ===

Typing:

{{{
http://alhena:7980/iprolemapping/getRoles/130.225.26.33
}}}

in a web browser could make the test system return (depending on the configuration):

{{{
doghouse,henhouse,inhouse
}}}

If a query is made on an IP address (IPv4 or IPv6 depending on the configuration) which has not been associated with any role in the configuration, the the service just replies with an empty page.

== status ==

This method has been added to assist (automated) surveillance of the IP-Role mapper service. It is invoked by an URL of the form:
{{{
http://<context root>/iprolemapping/status
}}}

=== Example: ===

Typing:

{{{
http://localhost:7880/iprolemapping/status
}}}

in a web browser could make the test system return:

{{{
STATUS: OK

MESSAGE: Running normally.

Currently using this configuration: /home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml
}}}

... or if the configuration has been changed to be non-working (in which case the service will continue using the last known good configuration):

{{{
STATUS: WARNING

MESSAGE: Failed (re-)initialising configuration. Will proceed with the current configuration. The failing configuration file is: /home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml Cause of the failure: java.io.IOException: Failed parsing configuration file '/home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml'

Currently using this configuration: /home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml
}}}

The IP-Role mapper service will only report error in case it has been launched with an invalid configuration file from the beginning. That is, it has not had the chance to read a working configuration at any time, and therefore it does not have a known good configuration to fall back to. In that situation the reply would look like this:

{{{
STATUS: ERROR

MESSAGE: Failed (re-)initialising configuration. Will proceed with the current configuration. The failing configuration file is: /home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml Cause of the failure: java.io.IOException: Failed parsing configuration file '/home/tsh/doms/testbed/tomcat/webapps/iprolemapping/WEB-INF/ipRangesAndRoles.xml'

Currently using this configuration: null
}}}