Documentation for httpDNS 1.2.0

What is httpDNS?

Based on the idea by Carl Kossack and Axel Werner to use a generic web space for the publication of a dynamic IP address through a HTML page, you can distribute your router's IP address to a closed user group on the WWW using httpDNS. The major improvement is that httpDNS exclusively uses HTTP for all DNS communication. Therefore there is no need to give your secret FTP web server password to other users. Differently to common dynDNS services, with httpDNS IP addresses are not available to the general public, but to users holding the server's secret key, only. The option package consists of two separate programs: The CGI to use with the fli4l httpd option and the server program, which is running in the web space.

Typical Purposes:
Basic Features:
Recommendations:

How is httpDNS working?

Some definitions, at first:
The package is parted into two separate programs:
  1. The server program is written in PHP4 and runs on the web server in the WWW. It is executed every time its URL is requested and checks the consistency of the encrypted information transmitted by issuing the request. The encrypted information contains the requesting client's host name and IP address. If the decryption is successful, this information as well as a current time stamp is stored into a file on the server. If there already is a entry with the same host name stored, the entry is overwritten. This way only the most recent IP address of the client is being hold. The server program responds all saved entries in encrypted form to the client. If the decryption of the request fails, an error message is issued to the client.
  2. The client program is a Bash/Bourne Shell CGI script. It transmits the current IP address of the client (as seen from the WWW) together with the client's host name in cryped form to the server. The server's response is decrypted, evaluated and all contained entries are stored locally. Right after that all stored entries from all servers are read from files and their time stamps are compared to each other. Only the newest entry for each particular host name is put into the hosts.httpdns file. A selected client of the network can then be easily access through its host name.
By the way: httpDNS uses 'Universal Standard Time (UST)' for all internal time stamps. That way it is working independent of the actual geographic location of the web server or the time zone set on the web server.

Quick Installation for the Hurried (or: 12 Steps to Success ;-) )

  1. Extract httpdns.zip into your fli4l folder.
  2. Open config/httpdns.txt and set OPT_HTTPDNS='yes'. Save the file.
  3. Update your fli4l router installation (using e.g. IMonC or mkfli4l.bat). Reboot the router.
  4. Use your browser to access the httpd web interface of the router. Click the new menu item 'httpDNS' and select tab 'Key Generator'.
  5. Three random keys are generated and displayed after some time. Please be patient, the process may take a while depending on the router's performance (several seconds up to several minutes).
  6. Mark and copy a separate key for each server you wish to install and paste it into a HTTPDNS_SERVER_%_KEY variable in the config/httpdns.txt file.
  7. In the config/httpdns.txt file, set HTTPDNS_INTERFACE to the device used accessing the WWW (e.g. ethernet card 'eth1') and put your preferred host name into HTTPDNS_HOSTNAME. For each server you at least have to set a HTTPDNS_SERVER_%_NAME variable, as well as the number of servers in HTTPDNS_SERVER_N. Leave HTTPDNS_SERVER_%_DNSFILE with it's default value. Save the file.
  8. Update your fli4l router installation (using e.g. IMonC or mkfli4l.bat). Reboot the router.
  9. With the browser choose tab 'Administration' in the router's web interface.
  10. Every server defined should be displayed next to a number of buttons, with one button of either 'Manual installation' (if no FTP login information was given in the config/httpdns.txt) or 'Upload Program' (if FTP was enabled). Click this button and follow the instructions displayed.
  11. Choose tab 'Synchronization' and click the button 'Synchronize all DNS' in the 'Current IP Address' windows displayed.
  12. If every server's request status is 'Successful.', you won. Congratulations! Any other case, please, read the entire documentation.

Installing the httpDNS Option on Your fli4l Router

The httpDNS package needs to be installed just as any other package. Though there is a small thing, that has to be taken into account: Since the servers need keys of a very special type, I included a key generation utility in the httpd web interface. Only, the key generator is not available before the installation of the package. You see the problem? ;-)

Therefore, enable the package by editing the config/httpdns.txt file and set OPT_HTTPDNS='yes'. Save the file, compile the fli4l software using IMonC or mkfli4l.bat and transfer it to the router, which needs to be restarted afterwards. As soon as the router has rebooted, invoke the httpd web interface of the router. There you will find a new menu item called "httpDNS". Just click on the new item and select the tab "Key Generator" and wait a moment or two until the generation is finished and three keys are displayed.

For each server you intend to install you will need one separate key. Theoretically you can use a single key with any number of servers. Only, since the key determines the accessibility too the server, what's the point of installing separate servers with one shared key? Anyway, put your keys in the HTTPDNS_SERVER_%_KEY variables of your config/httpdns.txt file. Where the '%' is to be replaced by the number of the server. Your can easily mark and copy a key in the Key Generator window and past it into the file. But make sure you mark the entire key, because every key has to be exactly 41 characters long.

Now is the moment where you have to choose an appropriate host name for your router. The host name needs to be unique within the network. Any other client in the network or any device or any client within the router’s domain therefore cannot use it. Nor should it be the name of the domain itself, for otherwise the name service may not work properly. Mind, the host name has nothing to do with the variable HOSTNAME in the config/base file and - too uphold the differentiation - should not be the same. Apart from these few rules you can choose whatever you think is a nice and representational name for your router within the network. Anyway, regarding the host name you are obliged to come to an agreement with the httpDNS server administrator and the other users using the server. State your host name in the variable HTTPDNS_HOSTNAME in the file config/httpdns.txt. The host name is valid for all the servers you are synchronizing with. Very much like a domain name it can only contain small letters, numbers, as well as dots ('.') and dashes ('-').

To enable the client program to detect the current IP address locally, you have to set the variable HTTPDNS_INTERFACE to hold the name of the interfacing device used to access the WWW. In case you are using an external DSL modem or your fli4l is configured as a router the device name my likely be 'eth1'. If you are unsure which interface is used, use the Trial and Error method until the correct IP address is displayed by selecting the tab 'Synchronization' in the httpd web interface.
If HTTPDNS_INTERFACE is left empty or omitted at all, the client program gets the IP address from the server through a mirror request. That way, the server program responds the HTTP REMOTE IP sent with the client's request. It is useful to try this methode of detecting the IP address, if the client is installed behind another router or masquerading proxy.

HTTPDNS_DNSFOLDER states the location the received DNS entries are stored in. In most cases the default value should do nicely. If you want all DNS entries to be available after rebooting the router, you may choose to store the entries on a physical disk drive instate of the RAM disk used commonly. But mind, even if you could preserve the entries from other clients that way, a new IP address may be assigned too your router once you reconnect to the ISP. As long as you do not resynchronize with all the servers the other clients are not able to reach your router for they will try to access your router's old IP address.

Set HTTPDNS_SERVER_N to the number of servers you wish to use. All the other properties can be set separately for each server.

HTTPDNS_SERVER_%_NAME contains the URL of the server. This could be something like 'members.myprovider.com/yourname' or if you have registered your own domain address something like 'www.mydomain.com'. In both examples the server program has to be stored in your home folder on the web server. Since this is neither an appropriate place nor does it support the service of more than one server, you should consider putting the program into a subfolder, e.g. 'httpdns'. The URL then has to be changed to either 'members.myprovider.com/yourname/httpdns' or 'www.mydomain.com/httpdns'. You can use as many folders as you like. That way you can put one server into the subfolder 'httpdns-vpn', while another is placed into 'lan-party' in the same web space. The servers are working independently.

With the HTTPDNS_SERVER_%_IPUP variable set to either 'yes' or 'no' you can determine whether or not the client program should synchronize with the server once the ip-up event takes place. Ip-up usually takes place when your router connects the ISP and is assigned a new IP address. If your are using dial-up network to connect the internet, your should consider enabling this feature for the main servers at least. With leased lines and any other type of permanent connection problems can occur, if the ISP does not assign an IP address immediately, but after several seconds or minutes.

HTTPDNS_SERVER_%_DNSFILE determines the folder and file name of the file the DNS entries are stored in the web space. The path is relative to the home folder on the web server. You can use the same DNS file with more than one server. Just, I cannot imagine any use for that feature ;-), because then every server responds the same collection of DNS entries. So why to setup separate servers? If the variable is left empty, the default value ('httpdns.dns') is assumed, which is locates the DNS file in the same folder the server is running.
The HTTPDNS_SERVER_%_LOGFILE variable works quite the same way, but determines the folder and the file name of the log file on the server. If left empty, logging is disabled for this server completely. Every event on the server is usually logged. The log normally is only needed maintenance purposes and should be disabled in normal server operation, because logging my need quite some amount of web space and also is a security risk, since every access to the server is being filed in plain text format. You can use one log file for several servers. But because the server name is not written to the log it may be difficult to determine which server a given line is originating from.

Variable
Default Value
Description
Valid
Example
Optional
OPT_HTTPDNS
'no'
Activates the httpDNS optional package.
yes or no
'yes'
no
HTTPDNS_INTERFACE
''
Device the WWW is accessed through. Usually this is the ISDN interface card or an ethernet NIC connected to the modem. Property is needed to fetch the current IP address. If left empty, the IP address is requested from the server.
all NIC and PPP devices
'eth1'
yes
HTTPDNS_HOSTNAME
''
Unique name of the fli4l router. NOTE: All letters are converted to small letters!
a-z, 0-9, '-', '@', '_', '!' and '.'
'hunter99'
no
HTTPDNS_DNSFOLDER
'/var/run/httpdns'
Folder on the client the DNS files are stored in. All entries are preserved during reboot if the folder is not part of the RAM disk, but located on physical disk.
any absolute path
'/boot/httpdns'
no
HTTPDNS_SERVER_N
'0'
Number of servers you wish to use.
any number
'1'
no
HTTPDNS_SERVER_%_NAME
''
URL of the n'th server. Must point to the folder the server program is put in. The server program file name is appended automatically.
URL (HTTP)
'members.myprovider.com/yourname/httpdns/sub/folder' no
HTTPDNS_SERVER_%_KEY
''
Secret key of the n'th server. Has to be declared on every client that wants to access the server.
use key gen- erartor, please!
'iAZoUkX!v0@V_flg5BLyPwuHTFbK3R9xaIYEGJnqp'
no
HTTPDNS_SERVER_%_IPUP
'no'
Do you want the client to synchronize with this server after connecting to the ISP?
yes or no
'yes'
yes
HTTPDNS_SERVER_%_DNSFILE 'httpdns.dns'
Name of the file used to store entries on the server. If it contains a path, necessary folders are created automatically at the first start of the server program.
file name with or without path
'subfolder/httpdns.log'
yes
HTTPDNS_SERVER_%_LOGFILE ''
If you want all activities to be logged, state the log file name here. If it contains a path, necessary folders are created automatically at the first start of the server program. file name with or without path
'subfolder/access.log'
yes
HTTPDNS_SERVER_%_LOGLEVEL
'5'
Specify how detailed the server program does it's logging. '9' is very verbose, while '0' disables logging, entirely.
0-9
'0'
yes

What's next?
If you want to use a MySQL database for storing DNS and log data, see chapter Configuring the Use of a MySQL Database
If you have FTP access to your web space you may want to configure the automatic installation of the server program. See chapter Configuring the FTP Upload of the Server Program (Optional)
If you already have configured the automatic installation of the server program you may want to start the procedure. See chapter Starting the Automated Installation of the Server Program
If you want to upload the server program manually, have a look at chapter Manual Installation of the Server Program

Configuring the Use of a MySQL Database

If you have access to a MySQL database, you may consider using it for holding all DNS and/or log data, instate of using files. MySQL offers additional security through password protection of your data and is usually faster accessible than files, reducing the server's total response time.

The database does not necessarily have to be hosted on the same server the httpDNS server program is installed on. Any MySQL server may do. All you need is to configure the apropriate variables, so the server program can login to MySQL. The use of MySQL can be separately configured for each httpDNS server.

Note: The httpDNS server program does not create any database, just tables. Therefore, please make sure the database already exists, before uploading the server program!

Variable
Default Value
Description
Valid
Example
Optional with MySQL
HTTPDNS_SERVER_%_MYSQL
'no'
Activates MySQL for this server.
'yes' or 'no'
'yes'
no
HTTPDNS_SERVER_%_MYSQL_SERVER
'localhost'
URL to MySQL server.
URL with or without port specification
'localhost' or 'localhost:3306'
no
HTTPDNS_SERVER_%_MYSQL_USER
''
User name for MySQL server login.
any
'username'
no
HTTPDNS_SERVER_%_MYSQL_PWD
''
Password for MySQL server login.
any
'password'
no
HTTPDNS_SERVER_%_MYSQL_DB
''
Database to use. The database has to be created manually, because some limitations may apply on some servers for creating databases.
any
'mydb01'
no
HTTPDNS_SERVER_%_MYSQL_DNSTABLE
'httpDNS_DNS'
Name of the table holding DNS information. All tables are automatically created by httpDNS.
a-z, A-Z, 0-9, '_' and '$', no blanks, max. 64 chars
'my_dns_table'
yes (see below)
HTTPDNS_SERVER_%_MYSQL_LOGTABLE
'httpDNS_Log'
Name of the table holding log information. All tables are automatically created by httpDNS. a-z, A-Z, 0-9, '_' and '$', no blanks, max. 64 chars 'my_log_table'
yes (see below)

httpDNS allows you to specify whether you want to use MySQL with both, DNS and log data, or just with on of them. The HTTPDNS_SERVER_%_MYSQL_DNSTABLE and HTTPDNS_SERVER_%_MYSQL_LOGTABLE determine this behaviour. If MySQL is enabled and the corresponding table variable is set, the server program will use MySQL to store the data. If the table variable is left unset, an external file will be used.

Setting of Variable
DNS Data stored in

HTTPDNS_
SERVER_%_
DNSFILE
HTTPDNS_
SERVER_%_
MYSQL
HTTPDNS_
SERVER_
%_MYSQL_
DNSTABLE
Local File
MySQL DB
Remark
unset
'no'
don't care
yes
no
Using default file name
set
'no'
don't care
yes
no

unset
'yes'
unset
yes
no
Using default file name
set
'yes'
unset
yes
no

unset
'yes'
set no
yes

set
'yes'
set
no
yes
Warning during build
Setting of Variable
Log Data stored in

HTTPDNS_
SERVER_%_
LOGFILE
HTTPDNS_
SERVER_%_
MYSQL
HTTPDNS_
SERVER_
%_MYSQL_
LOGTABLE
Local File
MySQL DB
Remark
unset
'no'
don't care
no
no
Logging disabled
set
'no'
don't care
yes
no

unset
'yes'
unset
no
no
Logging disabed
set
'yes'
unset
yes
no

unset
'yes'
set no
yes

set
'yes'
set
no
yes
Warning during build

Configuring the FTP Upload of the Server Program (Optional)

Uploading the server program into the web space requires quite a number of commands. It's completely annoying, because if you forget to enter a single command you have to redo everything from start. To simplify the procedure I have worked it into the web interface. Only, the automatism needs several variables to be set. They are only used for uploading the server program. If you want to do that manually,  you don't have to give this information. Because the variables are only used for FTP upload, they only need to be declared on the client the server is administered from. No need to declare them elsewhere.

Variable
Default Value
Description
Valid
Example
Optional
HTTPDNS_SERVER_%_FTPURL
''
FTP address of the web server.
URL (FTP)
'ftp.myprovider.de'
yes
HTTPDNS_SERVER_%_FTPUSER ''
FTP user name as defined by the web space provider.
a-z, 0-9, '-' and '.' 'firstname.lastname'
yes
HTTPDNS_SERVER_%_FTPPWD
''
FTP Password.
any value
'password'
yes
HTTPDNS_SERVER_%_FOLDER
''
Sub folder the server shall be running in. The folder has to correlate the one given with HTTPDNS_SERVER_%_NAME. relative paths, only
'httpdns/sub/folder'
yes

Configuring Password Access

In some situations there is no cryption module available to compute the needed query string for an ip address update. For instance, single pc's or other routers than fli4l (as silly as it sounds, but there are still some around ;-) ) are unable to update ip information on a httpDNS server. This can be helped, if a special password is defined to alternatively update without crypted query. The password can be chosen freely and allows only to add a new hostnames to the server's database and update ip information stored in the database. No information of any host can be read, nor any log be viewed by password.

Some hardware routers and modems support DDNS (DynDNS). To use this feature together with httpDNS, the router or modem has to have a "Custom DDNS" entry. That way you can enter a custom DDNS server address (URL) rather than only choose popular predefined ones. The URL to use with httpDNS should look like this:

www.tiger.adm24.eu/httpdns-test/httpdns.php?hostname=YOURHOSTNAME&password=YOURPASSWORD

As shown, there is no ip sent. This is for security reasons. The server program strictly uses the ip address of the source of the query. That way altering the ip address is limited and spoofing made more tricky. But keep in mind, that all information is sent without encryption and everyone who knows the password can change ip addresses and add hosts on the server.

Variable
Default Value
Desciption
Valid
Example
Optional
HTTPDNS_SERVER_%_PASSWORD
''
Enable password access of the server by setting a password.
any value
'5hDdfg2aLsf'
yes

Setting the Lifetime of Host Entries

Probably some hosts don't synchronize frequently enough to ensure there is a valid IP address held by the server. It is rather anoying, if you try to connect to a host like that and end up only get error messages. To avoid this sort of problems you can set a lifetime for host entries. Whenever the server program is called, it checks, if any host entries are older than the given number of hours and automatically deletes those expired entries from the database.

Variable
Default Value
Description
Valid
Example
Optional
HTTPDNS_SERVER_%_LIFETIME
'0'
Number of hours until a host entry is erased from the server database, if not updated. '0' disables this feature.
0 to 65535
'8770'
yes

You can even use this feature to check, if a certain host is online. Therefore you need to install easycron on the host to synchronize periodically (eg. every 55 minutes). This does not cause any noticeable amount of traffic. Set up your server with a host entry lifetime of '1'. If you query the server for the host name with a polling link and you get an 'N/A' response, then the host is down for some time.

Web Interface Buttons

Icon
Name
Description
See Chapter
httpdns_sync.gif
Synchronize
Starts the synchronization with the server next to the symbol.
Synchronization with the Server
httpdns_syncall.gif
Synchronize All DNS
Starts the synchronization with all servers.
Synchronization with the Server
httpdns_viewlog.gif
Show Server Log
Views the content of the server's log file.
Server Administration
httpdns_clearlog.gif
Clear Server Log
Empties the server's log file.
Server Administration
httpdns_manual.gif
Setup Manually
Starts the configuartion procedure of the server program for manual installation.
Manual Installation of the Server Program
httpdns_upload.gif
Upload Program
Starts the automated installation of the server program.
Starting the Automated Installation of the Server Program
httpdns_linkgen.gif Generate Polling Links
Displays a list of http links, which can be used to query ip addresses of single hosts.
Gerneration of Polling Links
httpdns_linkgen.gif Erase Host Entry
Erases a single host from server.
Erasing Hosts

Starting the Automated Installation of the Server Program

If all three variables (HTTPDNS_SERVER_%_FTPURL, HTTPDNS_SERVER_%_FTPUSER and HTTPDNS_SERVER_%_FTPPWD) for the FTP access are declared, the button 'Upload Program' instate of the button 'Setup Manually' is displayed next to the server's name in the tab 'Administration'. Just click the button and the server program is configured and uploaded automatically. Afterwards, the result of the attempt is displayed together with the responses received from the FTP server during the upload. Please, have a closer look at the responses, because the number of errors recognized by the upload tool is limited and a 'Successful.' status may possibly be displayed, despite the fact the upload fail. Everything is limited! ;-)

If you, at one point, want to modify the configuration of the server, just set the according variables and upload the server program once more.

Manual Installation of the Server Program

If you do not have FTP access to the web space or you do not want to use FTP or you simply feel more comfortable installing the server program manually, it is easy to do so. After setting the basic variables for the server, the tab 'Administration' can be invoked in the httpd web interface, displaying the list of servers with a button 'Setup Manually' for each server. Just click the button to see the info dialog how a manual installation is done. The info box also contains a link to the specially configured server program still saved on the router. Click the link to download the program onto your computer.

Afterwards login to your web space and create the folders you declared for the server (see HTTPDNS_SERVER_%_NAME), the log file (see HTTPDNS_SERVER_%_LOGFILE) and the DNS file (HTTPDNS_SERVER_%_DNSFILE). Put the previously downloaded server program in the appropriate folder. If the web space is on an UNIX server you have to make the server program file executable using the command 'chmod 755 httpdns.php'. Aaaaaaaaand here we go!

Synchronization with the Server

The synchronization is done automatically after dialup and connection to the WWW, if the HTTPDNS_SERVER_%_IPUP variable has been set to 'yes' for a server.

As long as the router is online, the synchronization can be started manually through the httpd web interface or from the command line of the router. The web interface displays on clicking 'Synchronization' a 'Synchronize' buttons in each server's window and a button 'Synchronize all DNS' right on top of the page in the window 'Current IP Address'. Click the buttons to synchronize with one or with all servers listed. The result of the synchronization is to be seen in the afterwards displayed status box.

How the synchronization is started from the command line, you can clear in chapter Running the Client Program from the Router's Command Line

Gerneration of Polling Links

If you want to query the httpDNS server independent of fli4l, you can use the button "Generate Polling Links" to display a link for each host registered on the server. The links are valid for unlimited time for an unlimited number of request of a single host's IP address. Due to the encryption the links can not easily be modified to gain access to the rest of the data stored on the server. The server security is therefore not compromised.

The current IP is:
<IFRAME src="http://www.tiger.adm24.eu/httpdns-test/httpdns.php?query=oHdADfKVvZh.tczmGONilqjaJE_01xPCQRIFTr3w7t4pFQjC|Gd2n0.a6vDxPumKkAY">
    Server not available
</IFRAME><br>


The example above displays the current IP in a separate frame within a web page or "Server not available", if the link is invalid. If the host the link has been generated for is not registered on the server anymore, the text "N/A" will be returned instate of the IP address.

The <IFRAME> statement supports a class parameter, which can be used to format the frame and the content using a Cascading Style Sheet (CSS). The IP address is part of the body of the frame.

Erasing Hosts

In some cases (eg. if a host is renamed) it is necessary to erase host entries from the server. To allow you to handle that comfortably, you find a button in the administration tab of the web interface next to every server running httpDNS 1.2.0 and above. Once you click the button, the server is queried for all host entries and the entries are listed each with a X next to it. Just click the X next to the entry you want to delete from the server.

Mind, you need to synchronize with the server, again, to remove the host entry from your local router as well.

Files on the web server

After it has been configured by the httpd web interface, the server program itself contains all information necessary for operation, but no DNS entries, of course. Initially I programmed the server program to use a external configuration file. But this didn't really make sense, because it only lengthened the execution time processing a request and nobody edits the configuration file in web space manually, if changes can easily be uploaded with some clicks in the web interface. That's how the all-in-one server Program was born.

Hint: If you want reset the DNS table on the server, just delete the DNS file. The server will start from zero with the next request received and recreates a new DNS file. Please, use the appropriate button in the httpd web interface to clear the log file.

The server program can be executed from any folder you like. There is no general path information stored when the server program is configured. You therefore can move the server program between folders without reconfiguration. Only the paths and names of the DNS and log files are permanent. If you just stated file names but no paths for those files, the server program will look for them in the server program's folder. If you move the server program, you have to move the other files, as well. If you declared path information for the DNS and log files, they have to stay were they are, for they are otherwise recreated on the exact spot.

Description
Usual File Name
Usual Folder
File Format
Server Program
httpdns.php
-
Text, PHP4
DNS File
httpdns.dns
Same as the server Program or as stated in HTTPDNS_SERVER_%_DNSFILE
Text, encoded
Log File
httpdns.log
Same as the server Program or as stated in HTTPDNS_SERVER_%_LOGFILE
Text

Server Administration

Normally the server needs no maintenance. The server program completely handles all DNS entries. Only if you want to reset the DNS, the DNS file has to be deleted manually. I don't want to integrate a reset button in the httpd web interface, because accidentally resetting the DNS file can jeopardize the network stability.

To view and clear log files on servers you find appropriate buttons in the tab 'Administration' of the httpd web interface. Logs are displayed unfiltered. Once the log file was cleared the first line in the new log file always states who cleared the log file.

If you want to change a server's configuration (e.g. changing the server key), you just have to make the changes to the config/httpdns.txt file, update the router and re-upload the server program after rebooting the router. All DNS entries on the server are preserved during this procedure.

Named Administrator

To prevent other users from erasing server logs and deleting host entries, you can name an administrator for the server by it's hostname. If the server program is called with an erase log or kill host command, it checks if the command received comes from the same IP address as the administrator's hostname is registred with in the database. If the command's IP address and the administrator's IP address do not match, the command is not executed, but an error message returned.

This is not a completely save procedure, but it at least ensures that users cannot "accidentally" erase data on the server. Of course, any IP address can be faked ...

Variable
Default Value
Description
Valid
Example
Optional
HTTPDNS_SERVER_%_ADMIN
''
Hostname of the administrator of the server. Prevents any other user from erasing server data. '' disables this feature.
a-z, 0-9, '-', '@', '_', '!' and '.' 'master'
yes

Setting User Rights

The httpDNS package is programmed to support the user rights control feature of the httpd option. For further information how the user rights are controlled, please read the httpd package documentation. Mind, if no entries are made to the user rights table everybody is allowed everything!

The section for setting user rights of the httpDNS package is named - you won't belief it - 'httpdns'. ;-)

User Rights Entry
Key Generator
View DNS Tables
Synchronize
Upload Server Program
View & Clear Server Log
View Journal
'httpdns:'
no
no no
no
no
no
'httpdns:view'
yes yes no no no
no
'httpdns:view,sync'
yes
yes
yes no no no
'httpdns:view,sync,admin' or 'httpdns:all' or simply ''
yes yes
yes
yes yes
yes

Running the Client Program from the Router's Command Line

The client program is - as I mentioned earlier - a shell script. This means it can be executed from the fli4l router's command line. That way httpDNS can easily be automated and interfaced with other programs. For example, you can use easycron to run synchronizations automatically in a specific time interval.

Through a command line parameter the client program has to be told what to do. You only can state as many parameters as you like, though if a server is stated several times it is only synced once. Also if you append the parameters '1 --update' to synchronize with server number 1, the update of the host file will be done only once (as with any synchonization).

Parameter
Description
Example
-a, --all
Synchronize with all servers and update hosts.httpdns file.
/srv/www/admin/httpdns.cgi -a
-h, --help
Show help and program version.
/srv/www/admin/httpdns.cgi -h
-i, --ipup
Synchronize with all servers, where HTTPDNS_SERVER_%_IPUP='yes'. Update hosts.httpdns file afterwards.
/srv/www/admin/httpdns.cgi -i
-u, --update
Only update hosts.httpdns file. Do not synchronize with servers. Only locally stored DNS entries are processed.
/srv/www/admin/httpdns.cgi -u
-s, --silent
Additional parameter. Suppresses any output to the console.
/srv/www/admin/httpdns.cgi -a -s
{Server Name}
Only synchronize with the server stated and update hosts.httpdns file afterwards. The server must have been configured previously and the name stated must be exactly the name in HTTPDNS_SERVER_%_NAME.
/srv/www/admin/httpdns.cgi member.myprovider.com/yourname
{Server Number}
Only synchronize with the server stated and update hosts.httpdns file afterwards. The server must have been configured previously and the number stated must be the number as indicated by '%' in HTTPDNS_SERVER_%_NAME. /srv/www/admin/httpdns.cgi 1 2 3

No parameter shows help.
/srv/www/admin/httpdns.cgi

The CGI terminates with an error level of 0, if successfully executed or with an error value, if an error occured during execution.

Extended Functionallity with WGet

NetCat is a small and handy tool, but does not offer too much functionallity. By setting the variable HTTPDNS_USEWGET='yes' WGet rather than NetCat is chosen as communication tool. Do not forget to enable OPT_WGET in config/tools.txt! Just mind, that WGet needs much more disc space than NetCat.

Some of the additional features through the use of WGet are described in the following chapters. More features will be introduced in upcoming versions of httpDNS.

HTTP Login

Most webspaces are nowerdays configured to use .access files for each seperate folder to set access rights. You can make use of this feature and enhance your httpDNS server's security. Please read your webspace provider's documentation about how to set up .access restricions. Most webspace's configuration software (like Confixx) will make it very easy to set access right. After you have configured your webspace accordingly, let httpDNS know the login information by setting the following variables. You can set up seperate logins for each server.

Variable Description
Valid
Example
HTTPDNS_SERVER_%_HTTPUSER
The user name used to access the webfolder.
any value
'httpdns'
HTTPDNS_SERVER_%_HTTPPWD The password used to get access to the webfolder.
any value
'iO02Dq_yasE2'

Windows Client Program

Because httpDNS is designed to run on Linux based OS'es, there is a separate MS Windows tool available to get access to the basic features of any httpDNS server. Mind, the Windows Client Program is not intentionally designed to replace the fli4l web interface for httpDNS, but to synchronize IP information of a network without a fli4l router with those of fli4l routed networks. The tool therefore is more of an extension than a replacement.

The tool is bundled with the httpDNS opt and located in the 'windows\opt\httpdns' subfolder of your fli4l folder. It comes as a AutoIt3 script including all sources and as single all-in-one compiled EXE file. The EXE file is ready to use without any previous setup. The Windows Client Program does not require any other tools being installed and only uses parts of the OS, which should be available on any Windows PC. The MS Internet Explorer is not need for program execution.

Note: Unfortunately MS Windows 95, 98 and ME do not support the COM libraries needed for exchanging data with the server program. The Windows Client program therefore cannot be run on those OS'es.

Saving of Settings and Working with Profiles

All settings are stored in the MS Windows registry, rather than in files, to avoid problems with file access rights. Therefore make sure you have sufficient user rights to write the registry when running the program and exempt the Windows Client Program from your anit-virus software's registry access blocker. If you want to save your settings to file, use the MS Windows RegEdit tool to export all information rooted in 'HKEY_CURRENT_USER\SOFTWARE\httpDNS'.

Because all settings including passwords are stored plain-text, it is written to 'HKEY_CURRENT_USER\*' rather than 'HKEY_LOCAL_MACHINE\*'. That way it is to a certain degree protected from being viewed and modified by any other user working on the same system. If you want to share the settings with other users, you have to export them from your HKCU using RegEdit and distribute the file to be imported by the other users into their HKCU.

The settings are stored in profiles which can be named freely. Each profile holds all information of any field in the Windows Client's dialog. To create a new profile just enter the profile's name in the combo box on top of the form and press the 'Save' button to it's right hand side. Profiles can be overwritten by saving them with the same name. When opened the Windows Client will automatically load the profile saved last.

To restore the settings of a profile, just choose the profile from the drop-down list of the profile combo box. Select '<new profile>' to empty all fields and start over by creating a new profile. Mind, to name the profile and save the settings by clicking on the 'Save' button.

Synchronizing

Updating the IP information stored on the server can be done with the 'Synchronize' tab of the dialog.

Field
Description
Valid
Example
Server URL
HTTP address of the server program as stated in HTTPDNS_SERVER_%_NAME.
any URL
http://www.tiger.adm24.eu/httpdns-test
Hostname
Name this network is represented with on the server.
a-z, 0-9, '-', '@', '_', '!' and '.' myhost.network
Password
Password as defined in HTTPDNS_SERVER_%_PASSWORD
a-z, 0-9, '-', '@', '_', '!' and '.' 5hDdfg2aLsf

After entering all needed information press 'Submit' to transfer the data to the server program. If sucessful a pop-up displaying the IP address synchronized will appear and the program will terminate. In case of an error, a message will be shown and the program will be kept open for you to modify the settings.

Note: To synchronize httpDNS 1.1.5 and up has to be installed on the server and HTTPDNS_SERVER_%_PASSWORD must have been set.

Quering IPs

To retreive an IP from the server use the tab 'Query IP'. Define what to do with the IP information, once received. The Windows Client can automatically patch any text file and/or invoke an external program (eg. WinOpenVPN or PuTTY).

If a 'Filename' is set, the program will try to open the file look for any occurence of the 'Find' text and replace it with the 'Replace with' text. In both text fields the placeholder @IP can be used to replace an IP address. In case of the 'Find' text it's the old IP address, while in 'Replace with' it stands for the newly received IP address. The 'Find' field also digests AutoIt3 Regular Expressions (for further information search for StringRegExp in the AutoIt3 manual 'windows\autoit\AutoIt3.chm'). The Search and Replace routine is not case-sensitive. In 'Replace with' are placeholders for the current date (@DATE) and current time (@TIME) available.

If a shell command is stated in 'Execute cmd.', it will be executed after the text file has been patched or staight after receivind the IP address from the server, if no text file is set in 'Filename'. Once more, use @IP as placeholder for the new IP address (eg. 'cmd /c ping @IP' will try to ping the host).

Field
Description
Valid
Example
Server URL
Link with crypted query. Use the httpd web interface to generate the links and copy and paste it into the Windows Client.
any link generated by the httpDNS web interface
http://www.tiger.adm24.eu/httpdns-test/httpdns.php?
query=oHdADfKVvZh.tczmGONilqjaJE_01xPCQRIFTr3w7t4pF
QjC|Gd2n0.a6vDxPumKkAY
Filename
Name and path of the text file to be patched with the received IP address. If empty, no file will be modified.
any text file given by it's full path
C:\WINNT\system32\drivers\etc\hosts
Find
Text pattern being searched in the text file. Use @IP as placeholder for any IP address.
any text, as well as any AutoIt3 Regular Expression
remote='@IP' ; Synchronized on [-[:digit:]]* at [:[:digit:]]*
Replace with
Text to replace any occurence of the 'Find' text. Use @IP as placeholder of the received IP address. The placeholders @DATE and @TIME insert the current date and time.
any text
remote='@IP' ; Synchronized on @DATE at @TIME
Append
If Append is checked, the Windows Client will append the 'Replace with' text at the end of the text file, in case no match of the 'Find' text is found in the text file.
-
-
Execute cmd.
After the text file has been patched or if no text file is set, the command stated will be executed. Use @IP as placeholder of the received IP address. any shell command
cmd /c "C:\Programs\PuTTY\putty.exe root@@IP"   or
cmd /c "echo @IP > %TEMP%\ip.txt && notepad %TEMP%\ip.txt"

After entering all needed information press 'Submit' to transfer the data to the server program. If sucessful the program will terminate. In case of an error, a message will be shown and the program will be kept open for you to modify the settings.

Note: Querying IP addresses requires httpDNS 1.1.1 and up running on the server.

Command Line Parameters

The Windows Client Program will behave differently depending on the number of paramters it is invoked with.
No. of Param's
Description
0
Opens the dialog and loads the settings of the profile saved last.
1
Opens the dialog and loads the settings of the profile stated in the first parameter. Exception: '-h' or '/?' or '--help' will open the help box.
2
Does not open the dialog, but loads the profile stated in the second parameter and executes the httpDNS command stated in the first parameter.

Invoked with two parameters, the first parameter has to be one of these:
Param #1
Description
'-s' or '--sync' or '/s'
Loads the profile stated in the second parameter and synchronizes with the server program. The Windows Client terminates without any dialogs, but maybe error messages.
'-q' or '--query' or '/q'
Loads the profile stated in the second parameter and queries the IP address from the server program. It patches the text file if 'Filename' is set, executes a given 'Execute cmd.' command and terminates without any dialogs, but maybe error messages.

The program sets the ERRORLEVEL environment variable after termination, so other programs can check, if it was run successfully (eg. httpdns.exe -q profile && echo Success!).

Safety Issues

The encryption used in httpDNS is quite sufficient for SOHO (Small Office, Home Office) applications. It is definitely NOT unbreakable, but a good compromise between preserving privacy and limiting execution time. I do not intend to describe the encryption process in this document. If you are interested in how encryption in httpDNS is done, you have to read the source code. I just want to say as much as this: The server key is not being sent either way during synchronizations. That way it is ensured the key cannot be easily calculated from the data transmitted. Surely, if someone has a sufficient amount of synchronization data, he may probably be able to reconstruct parts of the key. I therefore suggest changing the server keys periodically (every couple of months or once a year).

I would like to emphasize that the encryption used is NOT appropriate for professional use of httpDNS! Furthermore the open source jeopardizes any other possibility of improving safety besides encryption. National authorities (like the NSA) won't have any problem breaking the encryption. And this is quite intended by me, since I don't want this package to be abused for criminal purposes.

Please note, the DNS file, the log file and the server program with it's integrated server key stored in web space are readable by the web space provider. This is intended due to the laws in European countries. Laws will implicate providers being responsible for criminal actions done through or with the help of the services being offered by the provider. Thus you may be kicked off a web space if you prevent the provider from reading your data stored in his web space.

Hint: Do avoid the entire files being downloaded from web space, put the DNS and log files into hidden sub folders apart from the server program. Use a htaccess file in those folders to prevent users from accessing it.

Uninstallation of the Server Program

Once a server is not needed anymore, you only need to delete the server program and the corresponding DNS and log files from the web space. The deletion has to be done manually through normally accessing the web server. The server specific variables have to be erased from the config/httpdns.txt file.

Mind, you don't have to uninstall the server to modify it's configuration or change it's key.

Troubleshooting

I am trying hard to make my programs as bug-free as possible. Though it simply is not possible to make a program run flawless. Anyway, if you experience a reproducible "uncertain behaviour" ;-) of httpDNS or if you find a typo somewhere in httpDNS, please contact me by email. You will find my current mail address in the OPT database on www.fli4l.de directly above the description of this package (just click on 'Tiger'). But PLEASE mind: I do not offer end user support!

In the following section you will find a number of hints to make some troubles go away. I stand back from listing each and every error message displayed by httpDNS, just because the error message itself is supposed to explain what went wrong.

Installation

Error Description
Problem Solution
When compiling fli4l (mkfli4l) a 'Invalid Key' error is displayed. I do not have and cannot create any key, for the key generator is not running, yet.
A key has to contain 41 characters in length from as special character set.
For the first installation run  you can leave the key variable empty. HTTPDNS_SERVER_%_KEY=''
In the window 'Current IP Address' no or not the correct IP address is displayed.
HTTPDNS_INTERFACE not set correctly.
The variable must hold the name of the device through which the WWW is accessed. Leave HTTPDNS_INTERFACE empty, it the client is installed behind another router or a masquerading proxy.
When I click the tab 'Synchronization' in the web interface a error message 'offline' is displayed, despise I am online.
HTTPDNS_INTERFACE not set correctly.
The variable must hold the name of the device through which the WWW is accessed.

Setup and Administration of the Server

Error Description
Problem Solution
Only a 'Setup Manually' button is displayed in the tab 'Administration', but no 'Upload Program' button.
At least on of the variables HTTPDNS_SERVER_%_FTPURL, HTTPDNS_SERVER_%_FTPUSER or HTTPDNS_SERVER_%_FTPPWD is not set.
To make use of the automated upload feature all FTP variables in config/httpdns.txt need to be set.
On viewing a server's log file I get a lot of junk data.
The web server seems to add frames or pop-ups to any HTML page.
There is no solution but to change the web space package from your current provider or to change providers at all.
During the automated upload error messages are reported from the FTP server.
Error 530 during Logging in: Login failed, due to illegal user name or password.
Error 530 some later after logging in: The 'chmod' command is not supported.
Errors 526 and 536: The server program could not be copied to the web space.
For there are various reasons, there are various solutions. Anyway, it's a good idea to consult the web space providers FTP manual and check if the FTP variables are set correspondingly. If the chmod command is not supported you are probably not privileged to execute programs (run PHP's) on the web space.
Right after setting up the server the synchronization results 'Invalid response' or 'Server error'.
The server program tries to create the files and folders for storing DNS data and logs. Due to access restrictions the creation is prohibited.
Erase all automatically created folders and recreate them manually. Change the access rights to those folders with the command 'chmod 777' and try to synchronize. The files should have been created, now. Restore the access right with the command 'chmod 755'.
'Not available' is displayed as status.
The NSLookup did not yield any results.
The given URL or FTP URL is invalid or your ISP's DNS is currently down.
The button 'Generate Polling Links' is not being displayed
The button is only displayed, if the server supports quering by links. This feature was introduced in httpDNS 1.1.1.
Update your server program.
The button 'Erase Host' is not being displayed
The button is only displayed, if the server supports the deletion of hosts. This feature was introduced in httpDNS 1.1.7.
Update your server program.
During erasing of hosts or the clearing of the server log a 'You have no administrator rights' error is displayed, but I am a named administrator of the sever.
The IP address you are sending the server command from does not match the IP address your hostname is registered with.
Just synchronize with the server.

Synchronization

Error Description
Problem Solution
Even after synchronizing a wrong IP address is written to the hosts.httpdns file for my router's host name.
HTTPDNS_INTERFACE not set correctly or the ISP assigns the IP address after some time delayed or the client is installed behind another router or masquerading Proxy.
The variable must hold the name of the device through which the WWW is accessed. Check your IP address as displayed in the windows 'Current IP Address' by selecting tab 'Synchronization' in the web interface.
Some modems with integrated DHCP assign a temporary IP address until the ISP assigns the valid address. In that case you can only synchronize manually using the web interface after the valid address was assigned.
Leave HTTPDNS_INTERFACE empty, it the client is installed behind another router or a masquerading proxy.
Synchronization does work, but the other clients cannot find my router.
HTTPDNS_INTERFACE not set correctly The variable must hold the name of the device through which the WWW is accessed. Check your IP address as displayed in the windows 'Current IP Address' by selecting tab 'Synchronization' in the web interface. The IP address displayed has to be the one your router was assigned by the ISP not the one used to access your router from the LAN.
Leave HTTPDNS_INTERFACE empty, it the client is installed behind another router or a masquerading proxy.
HTTPDNS_SERVER_%_IPUP is set 'yes', but the router does not synchronize on dial-up.
IP-up event is not triggered
If your are running fli4l in a straight router configuration with the OPT_DHCP option enabled, the variable DHCPCD_EXEC_IPUPDOWN has to be 'yes' or no ip-up event will occur.

The client cannot find the server and a 'No answer' status is displayed.
The server program is not stored in the correct folder.
Either move the server program to the correct folder or change the URL in HTTPDNS_SERVER_%_NAME.
The URL in HTTPDNS_SERVER_%_NAME corresponds to the folder the server program is stored in. Anyway, there still is a 'No answer' status being displayed.
Probably the web server does not support PHP4.
Or the server program was not set to be executable on the web server.
Open your browser and request the URL with '/httpdns.php' appended. If you receive data junk, the web server does not support PHP4 or the server program was not set to be executable by the use of 'chmod 755 httpdns.php'. If a 'httpDNS' header line is displayed, the URL is correct. Check if the corresponding variables are set correctly. If a '404 not found' error message is displayed, the URL is incorrect. Have a look in the web space provider's manual for information how to access the web space.
'Encryption failed.' is being displayed.
No valid key was declared for the server.
Start the key generator and copy a key to the server's key variable in config/httpdns.txt.
The client does not receive any DNS entries from the server. The DNS file cannot be created on the web server
Check the access rights to the server's folder and the DNS file using the chmod command.
There are no buttons in the windows after selecting tab 'Synchronization' in the web interface.
User right 'sync' not set for you.
Please, contact your system administrator, who sets the user rights for the 'httpdns' section of the httpd package. If you are the administrator, please read further information in the manual for the httpd package regarding the setting of user rights.
An old server is still being listed when tab 'Synchronization' is selected, despise I already deleted the corresponding variables from the configuration.
There still is an old DNS file from the server in the local folder declared in HTTPDNS_DNSFOLDER
The file has to be deleted manually from the folder. The httpDNS client evaluates every file with the extension ".dns" stored in the folder HTTPDNS_DNSFOLDER.

Using Extended Debugging Functions

httpDNS provides several optional variables to enable and configure debugging. Please refer to the tables below for a detailed description.

Local Logging on Your fli4l Router

Variable
Default Value
Description
Example
Valid
HTTPDNS_DEBUG
'no'
During normal program execution all temporary files are deleted right away. With debugging enabled, the files containig the HTTP request sent to the sever (httpdns-request.tmp) and the server's response (httpdns-response.tmp) are saved to the /tmp folder.
'yes'
yes or no
HTTPDNS_LOGFILE
''
Independent of the HTTPDNS_DEBUG option the CGI can be configured to keep a journal of all WAN activities regarding the package. Just state the file you want the data to be written to to enable logging. Vice versa, an empty HTTPDNS_LOGFILE variable disables the journal creation, but does not delete the journal file. To view and delete the journal file you can use the httpd web interface. The log file is written in Common Log Format.
'/var/log/httpdns.log' any filename with absolute path
HTTPDNS_LOGLEVEL
'5'
Determines how verbose the logging is done. 0 disables logging entirely, while 9 is extremely noisy. Please refer to the table below for a description of the different levels.
'1'
0-9 or empty

Remote Logging on the Server

The remote log can be viewed and clear using the web interface.

Variable
Default Value
Description
Example
Valid
HTTPDNS_SERVER_%_LOGFILE
'httpdns.log'
If you want the logging data to be written to disk, just state the name and relative path of the file on the server.
'log/serverlog.txt'
any filename with relative path
HTTPDNS_SERVER_%_MYSQL_LOGTABLE
'httpDNS_Log'
Instate of a file you can use a table in a MySQL database to store logging information. Please, make sure to enable MySQL with the variable HTTPDNS_SERVER_%_MYSQL!
'my_log'
up to 64 characters of 0-9, a-z, A-Z, $ and _
HTTPDNS_SERVER_%_LOGLEVEL
'5'
Independent of the way the information is store, this variable sets the verbosity of the server's log. Please refer to the table below for a description of the different levels.
'1'
0-9 or empty

Log Levels

Log Level
Remark
Error
Warning
Info
Notice
0
Logging disables
no
no
no
no
1

yes
no no no
3

yes no no no
5
Default log level
yes yes no no
7

yes yes yes no
9

yes yes yes yes

License and Support

Valid for the entire package content the following is stated:

copyright © 2006-2008 Tiger
This package is licensed by Free Software Foundation, Inc., General Public License Version 2, June 1991

The GPL2 is the only legal base this package is published on. I do NOT acknowledge any other national or international, implicated or explicit law. If this or the GPL2 does not meet the local laws in your country I strictly forbid this package to be used in your country.

Please, understand I don't choose to give any end user support! Therefore, any mail sent to me with content like "The package does not work for me. Where is my mistake?" will stay unanswered. Please, ask your questions regarding httpDNS and it's installation in the OPT newsgroup on www.fli4l.de. English language will be accepted.

If you somehow find a bug in my program or you would like to improve existing or develop new features, you are welcome to contact me by email for assistance. You will find my current mail address in the OPT database on www.fli4l.de directly above the description of this package (just click on 'Tiger').

Visit the httpDNS homepage: www.tiger.adm24.eu

Donations

If you think my work on this package is worth a small amount of money, please don't hesitate to donate to:

World Wide Fund for Nature - United Kingdom
Conservation Project "Tigers"
http://www.wwf.org.uk/researcher/issues/rarespecies/0000000157.asp

World Wide Fund for Nature - United States
Conservation Project "Tigers"
http://www.worldwildlife.org/tigers/

World Wide Fund for Nature - International
Conservation Project "Tigers"
http://www.panda.org/about_wwf/what_we_do/species/our_solutions/endangered_species/tigers/index.cfm

To find a local site of the WWF in your country go to:
http://www.wwf.org/

The WWF is internationally doing fantastic work in preserving endangered big cat species. And those tigers need the money much more than I do. By the way: Big international companies (like Exxon/Esso) sponsor the WWF's administration. Money donated by private people therefore goes directly into the project work.