Updating your DHIS Hosts

Our new Web Update interface allows you to update your DHIS hosts with a simple HTTPS request; it is as simple as that and all you are required to do is to go to a web link in order to bring your hosts online. This method is particularly useful if you have a hardware based router with support for dynamic DNS and on which you can configure an update URL.

This page describes the new Web Update mechanism and how to use it in order to mark your host online, but before going any further, let us make a few things clear:

• You need a DHIS web account:
  If you don't have one you can donate here and one will be created for you. If you have one you can login here.

• Using your web account and after loggin in, you need to create your DHIS host; this is your hostname under dhis.org

• Your host must be configured for PASSWORD authentication.

• You need to know your host's password; not your web login password, but your host's specific and individual password.

The process is fairly straight forward, just go to:

https://host.dhis.org:password@is.dhis.org/update/

Ant that's all.

The username is either your hostname (.dhis.org) or your host ID number. Your IP address is taken from the request's source arriving at the server so it also does not need to be specified.

That's it. Providing you give the right host ID or Name and password, your host is marked online with the IP address from which the request was received at the server.

Going Online and Going Offline

When your web client device goes to the URL link and successfully authenticates, the corresponding DHIS host is brought online, i.e. it is made to point to the IP address from which the request came from.

By default it stays online for aproximately 6 minutes. After this period has elapsed if there haven't been any more recent updates the host is brought offline, i.e. it's IP address is made to point to 192.168.255.0 in IPv4 or a random site local address in IPv6.

In order to keep your host online your client needs to make an HTTP request every so often in order to refresh the online timer.

So in order to keep your host online with the default timeout, we recommend that you configure your client to make updates (refresh) once every 5 minutes.

Changing refresh timeouts

If you feel brave enough to play with non-standard refresh times, there is yet another goodie: the UpdateTimeout parameter.

Including the UpdateTimeout=minutes in the HTTP request sets the online timeout to a new value, i.e. your host will only go offline if it isn't refreshed in this amount of time.

The UpdateTimeout is given in minutes and can be as high as 35791394 which is 596523 hours, 24855 days or 68 years.

If you specify an UpdateTimeout of 0 your host will remain online forever until you update it again, this being equivalent to a static DNS entry.

If you wish to bring your host offline straigh away, you can also specify an UpdateTimeout of -1 which will produce the desired effect.

One thing to keep in mind is that the UpdateTimeout must always be higher than the interval between your client refresh requests; so if you configure your client to update every 10 minutes for example, you should request an update timeout of 11 minutes.

The following URL will could be used to configure an update client that refreshes every half hour.

If you want to bring your host online indefinitely until you submit a new update you can use:

To bring the host offline straight away you can use:

Updating with a different IP address

On most cases users want to update their Internet/WAN/Outside IP address; DHIS takes care of this automatically by retrieving the IP address from which the update requests reaches our servers and using it as the IP address to be used in the dynamic DNS name.

In some cases however, users may wish to make their DHIS hostnames point to IP addresses other than the one from where they are submitting the updates. In order to cover this we have introduced the IPAddr form parameter.

To make your DHIS hostname point to the IPv4 address 1.2.3.4 regardless of where you are submitting the update from you just need to use something like this:

Authentication

If you are having authentication problems and your client / hardware doesn't work well with HTTP Basic Authentication you may use HTTP form parameters and the GET method to specify your username and password instead. The URL forms below are all equivalent and all achieve the same desired updating effect: