DNS Redirector - Full Readme

  Readme | FAQ

Implementation Considerations

Use a standard LAN with a hardware firewall as the default gateway...
See the Network Examples. Notice that proxy/SOCKS, ISA, or ICS is not compatible.

When used for a public HotSpot...
The guest LAN should be completely isolated from any internal/office LAN as shown in Network Examples.
You should mitigate problems as discussed in FAQ 34, FAQ 39, FAQ 113, FAQ 126.

When used for content filtering...
A dedicated server is not required; installation on your existing domain controller(s), small business server, or home server is adequate.

DNS Redirector will try and bind DNS service to all IPs assigned to the server...
If Microsoft's DNS service (found on some Windows Servers or Active Directory domain controllers) is installed see FAQ 91.
If another DNS server or something using the same ports is installed see FAQ 4.

You will need to change DHCP scope properties (option 6, DNS server)...
The IP address used by DNS Redirector needs to be the only one handed out as the DNS server.
If running multiple instances of DNS Redirector (only for content filtering, see FAQ 28) then add the IP of every DNS Redirector server.

No NAT and no DNS separation...
For a wireless HotSpot, the DNS Redirector server and all clients must be in the same IP address space and cannot be separated by a NAT device.
If used only for content filtering, blocked/allowed functionality will work regardless of network placement as discussed in FAQ 37.
Every client should use the IP of the DNS Redirector server as their default DNS server (usually provided via DHCP), another DNS server cannot exist in-between.

If running the GUI rather than the service see FAQ 133.

For third-party software that is known to work with or aid in the use of DNS Redirector see FAQ 71.

Installation

Download DNS Redirector (or from the file fulfillment email you received after purchase)
     Right-click the .zip file you just downloaded
     Select properties
     Click the Unblock button (if this button is not present just proceed), then OK
     Extract the contents to a new folder C:\DNSREDIR

Configure C:\DNSREDIR\dnsredir.ini (see INI Settings section below)

Setup IIS or other web server software (see Hosted Pages section below)

Verify firewall exceptions have been defined, see FAQ 102.

Verify the working directory has adequate permissions, see FAQ 129.

White-list domains that you need, see FAQ 121, FAQ 122.

Run C:\DNSREDIR\dnsredir.exe or as a service.

Change your DHCP scope to hand out the DNS Redirector server IP as the only DNS server.
     (DHCP option 6, DNS server) This should be the same IP you specified for ListenOnIP= in dnsredir.ini

INI Settings

Default values are in green
Example values are in blue

All files referenced in the .ini are assumed to be in the C:\DNSREDIR working directory.
All IP address fields will also accept an IPv6 address.
Click here to view a simple/condensed version of these descriptions.

Logging=Normal
Sets the log file detail. A new log file is created each day within the DailyLogs folder, the filename is the date.
Valid options are:
Off - No log is created (this is fastest and recommended for large networks)
Normal - Only queries modified/answered by DNS Redirector are logged
Full - Every query, response, and function is logged (useful for diagnostic/troubleshooting, use sparingly as log files become large quickly)

Optimize=Speed
Sets the string matching algorithm used on keyword lists.
Valid options are:
Speed - this is fastest and recommended for large networks
Memory - this will use less memory (ideal for machines with low resources serving smaller networks)

ListenOnIP=192.168.0.2, 192.168.0.3
Specify the static IP address(es) of this DNS Redirector server (recommended), see FAQ 4, FAQ 91.
Or leave blank to bind on all system IPs (including the IPv4 loopback address 127.0.0.1)

SimpleDNS=simpledns.txt
File containing DNS A records that you want to resolve locally.
The contents of the file needs to be in the following format:
IP address[tab]Fully qualified domain name
As shown in this example:
192.168.0.1[tab]router.example.com
192.168.0.2[tab]blocked.example.com
192.168.0.3[tab]welcome.example.com
Or as a catch-all:
192.168.0.8[tab]*
When using an asterisk all domain names will resolve to a single IP, regardless of being real or not. This method does not require a real DNS server to be specified under DNSServerIP= but will render all RedirectIP= and BlockedIP= functions disabled. This method is for specific scenarios where a real DNS server is not available (no Internet connection) and/or you need to make only a few internal sites available. Use the same steps as if you were setting up a RedirectIP= site at this IP, see the Hosted Pages section.

GetClientName=False
Sets whether the client computer name will be displayed in the GUI.
Valid options are:
False - this is faster and recommended for HotSpot/public network environments
True - this is useful in Internet filtering environments with Active Directory-integrated DNS

DNSServerIP=4.2.2.2, 4.2.2.3
Specify the IP of a real DNS server.
This is the DNS server that all normal queries are forwarded onto. On a corporate network you will usually declare the IP of your internal DNS or Active Directory integrated DNS server, otherwise declare the DNS server provided by your upstream Internet provider. This setting is always required, unless using SimpleDNS= with a catch-all asterisk record.

RedirectIP=192.168.0.3, 192.168.8.3
Initially redirect clients to this IP, where your welcome page is hosted.
When specified, the first time a client tries to browse the Internet they will be shown the website hosted at this IP address instead. When specifying RedirectIP= then AuthKeywordsFile= is also required. If initial redirection is not going to be used leave both settings blank. See the Hosted Pages section for setting up a page at this IP address. This must be an IP address, not a URL, for information on redirecting to an existing website or URL see FAQ 30.

AuthKeywordsFile=authorized.txt
File containing keywords of domain names that, after resolved, authorizes the client to surf past the welcome page.
The contents of the file needs to include one or several complex/unique domain names to be treated as the "key" that allows users to browse past the RedirectIP= page. These do not have to be actual domain names registered on the Internet, you can make them up. Use SimpleDNS= if you want a made up domain name to resolve to an IP. When a client does a DNS lookup for a matching domain name the client will be marked as Authorized.
The system should work like this... (adapt it to your needs; payment page, password, registration, etc.)
A) user joins the network, B) user gets DHCP lease including DNS Redirector as the DNS server, C) user starts browser and sees your terms and conditions page, D) user clicks a link to accept the agreement, E) user gets forwarded to another page that says "Welcome to the Internet" and includes a clear image referenced at http://surfon.dnsredirctrl.com/clear.gif, F) the browser does a DNS lookup for surfon.dnsredirctrl.com G) DNS Redirector finds that surfon.dnsredirctrl.com matches the domain name specified in the AuthKeywordsFile, H) user can now browse the Internet freely.

AlwaysKeywordsFile=always.txt
File containing keywords of domain names that clients are always allowed to visit, even if they have not been authorized.
In a paid HotSpot scenario you would add the domain name(s) of your payment processor to this file so users can visit the site in order to pay for access and then become authorized. See FAQ 122. Leave this setting blank if you are not going to use it.

AuthClientsFile=authclients.txt
File containing IPs of local network clients that are always allowed to surf, even if they have not been authorized.
Useful for static-IP machines on the same LAN as the hotspot that shouldn't have to pay or become authorized to surf; such as a kiosk, the IT manager, back office, or receptionist's computer. Leave this setting blank if you are not going to use it. Note: This function is for special circumstances only, in most cases the public/hotspot network should be completely separate from the internal/office network as shown in Network Examples.

BlockedIP=192.168.0.2, 192.168.8.2
Domain names matched in the BlockedKeywordsFile= below will resolve to this IP, where your blocked page is hosted.
If content filtering is not going to be used leave this setting blank. This must be an IP address, not a URL. When specifying BlockedIP= then BlockedKeywordsFile= is also required. See the Hosted Pages section for setting up a page at this IP address.

BlockResponse=Lookup
Valid options are:
Lookup - resolves to the BlockedIP only if the domain name is real (does a lookup at the DNSServerIP= first)
Fast - resolves to the BlockedIP even if the domain name does not exist

BlockedKeywordsFile=blocked.txt
File containing keywords of domain names that clients cannot visit.
To automate the updating of keywords see FAQ 52. To block everything see FAQ 5. If blocking is not going to be used leave this setting blank. When specifying BlockedKeywordsFile= you must also specify BlockedIP= and host a website at that IP or web surfing will be slow.

AllowedKeywordsFile=allowed.txt
File containing keywords of domain names that clients are allowed to visit.
Sometimes good blocking keywords can prevent clients from reaching legitimate content, this list corrects that. See FAQ 112. If blocking is not going to be used leave this setting blank.

BypassBlockFile=bypassblock.txt
File containing keywords of domain names that, after resolved, allows the client to view blocked content.
The contents of the file needs to include one or several complex/unique domain names to be treated as the "key" that allows users to browse past the BlockedIP= page. These do not have to be actual domain names registered on the Internet, you can make them up. Use SimpleDNS= if you want a made up domain name to resolve to an IP. Note that after blocking is off you will need to close and open any browser windows, this is necessary to clear the browser's DNS cache for websites visited prior, otherwise those sites may still be blocked. Restarting DNS Redirector will turn blocking back on for all clients. By checking Blocking in the GUI or implementing ResetClientFile= you can turn blocking back on per-client. Note that a client who visits a BypassBlockFile= domain name before a AuthKeywordsFile= domain name will be able to browse freely, but will not set Authorized=True in the GUI. If blocking is not going to be used leave this setting blank.

ResetClientFile=resetclient.txt
File containing keywords of domain names that, after resolved, causes DNS Redirector to forget the client. This removes the client from the online clients list; de-authorizes the client, re-enables the block, and executes the LeaveAction if set.

ActionNumber=0
Perform the JoinAction specified below; 1 means every time, 2 means for every 2nd client who joins, 3 for every 3rd client who joins, etc.
If actions are not going to be used leave this set to 0.

JoinType=Online
Valid options are:
Online - executes JoinAction for any client that starts resolving through DNS Redirector
Auth - executes JoinAction only when a client becomes authorized
Both - executes JoinAction when a new client starts resolving through DNS Redirector, and again when that client becomes authorized
Only client's who authorize themselves trigger the action, clients specified in the AuthClientsFile= or clients manually marked as Authorized in the GUI will not trigger the JoinAction.

JoinAction=
File you want to launch or execute when a client joins the network. This could be a .exe, .wav, .bat or other script. If a join action is not desired then leave this blank. The client's IP is passed as a variable after the command for use with a third-party script or application, see FAQ 62. When running as a service (dnsrsvc.exe) it may be necessary to specify the full path to the file, for example C:\DNSREDIR\join.bat

LeaveAction=
File you want to launch or execute when a client leaves the network, used only when ActionNumber=1. This could be a .exe, .wav, .bat or other script. If a leave action is not desired then leave this blank. The client's IP is passed as a variable after the command for use with a third-party script or application. When running as a service (dnsrsvc.exe) it may be necessary to specify the full path to the file, for example C:\DNSREDIR\leave.bat

ClientTimeout=20
Interval in minutes before an active client is considered gone or left the network, based on the last DNS query received. This removes the client from the online clients list; depending on the features enabled it de-authorizes the client, re-enables the block, and executes the LeaveAction if set.

MinToTray=False
Set this True so when the GUI is minimized it will go to the system tray area instead.

CloseToTray=False
Set this True so when X is pressed (as if to normally close the GUI) it will stay running and go to the system tray area instead. When set True the GUI is also not displayed on startup but rather loads directly to the system tray.

Hosted Pages

Using IIS on the same server as DNS Redirector to host the welcome and/or blocked pages is suggested. Optionally, you can declare the IP of another web server that is internal or external to the DNS Redirector network. IIS on a non-server OS has restrictions, such configuration is not supported or recommended. Using SimpleHTTP or Apache HTTP Server may be appropriate in some cases.

Depending on the features enabled in DNS Redirector you may need multiple sites, each requiring its own IP address. Add multiple IP addresses to the same NIC under the Advanced button in TCP/IP properties.

verify ASP and SSI components are installed with IIS (see screenshot for IIS6 or IIS7)

If RedirectIP=192.168.0.3 complete the following steps...
create a folder for the site root, such as C:\Inetpub\welcome

in IIS Manager create a site: (see details for IIS6 or IIS7)
running at 192.168.0.3 | port 80 | no Host header | path set as the folder created above

for IIS6: leave checked "Allow anonymous access to this Web site" | leave checked "Read" | check "Run scripts (such as ASP)"
extract a sample welcome page to the folder created above
set the Default Document as: welcome.asp (must be listed first, it is suggested to remove all other default documents)

set the following custom errors: (see details for IIS6 or IIS7)
HTTP Error: 403.1 | Message Type: URL | URL: /welcome.asp
HTTP Error: 404 | Message Type: URL | URL: /welcome.asp
HTTP Error: 414 | Message Type: URL | URL: /welcome.asp

If BlockedIP=192.168.0.2 complete the following steps...
create a folder for the site root, such as C:\Inetpub\blocked

in IIS Manager create a site: (see details for IIS6 or IIS7)
running at 192.168.0.2 | port 80 | no Host header | path set as the folder created above

for IIS6: leave checked "Allow anonymous access to this Web site" | leave checked "Read" | check "Run scripts (such as ASP)"
extract a sample blocked page to the folder created above
set the Default Document as: blocked.asp (must be listed first, it is suggested to remove all other default documents)

set the following custom errors: (see details for IIS6 or IIS7)
HTTP Error: 403.1 | Message Type: URL | URL: /blocked.asp
HTTP Error: 404    | Message Type: URL | URL: /blocked.asp
HTTP Error: 414    | Message Type: URL | URL: /blocked.asp
download: REG-UrlSegmentMaxLength.zip then open the .reg file
     this is necessary so certain blocked content is replaced correctly, or follow these manual instructions:
     open regedit and navigate to HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters
     edit or create DWORD "UrlSegmentMaxLength" and set to "450" (see kb820129)

for every site created above...

add the HTTP Header: "Cache-Control: no-store, no-cache, post-check=0, pre-check=0" (see screenshot for IIS6 or IIS7)
     META tags which preventing caching (as included in sample pages) are required in addition to this HTTP Header (see rfc2616-sec14.9 and msdn)

on IIS6 when ASP.NET is installed ensure the version is set to 2.x or later (see screenshot)

on IIS7 under Error Pages, Edit Feature Settings, set "Custom error pages" (see screenshot)

Enable Parent Paths (see screenshot for IIS6 or IIS7)

check NTFS permissions on the root folder (see screenshot for IIS6 or IIS7)
     (see kb812614 / kb981949)

verify the site is running, type: http://[IP from above] in a browser on this server and on a client computer

License

Your license purchase is good forever in this one working location (on 1 server), meaning there are no renewal/maintenance/subscription fees for the software to keep working. You are entitled to free version upgrades within 2 years of your date of purchase. If you decide you need the latest version after 2 years you may purchase at a 10% discount. Updates to keyword lists and the updater program are free to all license holders.

Since DNS is critical to the operation of any network, and we don't want to aggravate system administrators, there are no activation or renewal techniques built into the licensed version. The software does not 'phone home' at any time with the exception of voluntarily using updater, of which the only function is keyword list retrieval.

Your license should be big enough to support your network, see FAQ 98.

For IT consultants or other systems integrators: When purchasing the software on behalf of your customer enter their name/company in the second step of the online order. This is necessary to apply the license to the end-customer. Reselling or bundling is forbidden without prior written approval.

For the complete software license agreement see: dnsredirector.com/license