NxFilter Tutorial
1. Getting started

2. Blacklist and domain categorization

3. Authentication

4. GUI overview

5. Working with an agent

6. NxCloud

7. Customization or rebranding of NxFilter and its clients

8. NxClassifier

9. NxFilter as a DNS server

10. Misc

11. Video tutorials on Youtube

12. FAQ
System requirements
- Windows, Linux, FreeBSD or other OS having Java 7 or 8 installed.
- 768 MB RAM.
- 4 GB of free disk space.
- UDP/53, TCP/80, TCP/443 ports.

* OpenJDK 9 makes a problem with our embedded webserver. We recommend you to use OpenJDK 8 when you want to run NxFilter with OpenJDK.

* At default, NxFilter uses up to 768 MB of system memory. This might not be enough when you have several thousand users. To allocate more memory to NxFilter, read Performance tuning guide part of this tutorial.

- Go index -
Install NxFilter on Windows
We provide a Windows installer. When you download and run 'nxfilter-x.x.x.exe' you will have a screen like below.

* We have a video tutorial on Youtube - View Youtube tutorial!

After you follow several steps on the installer, it will try to create a Windows service for NxFilter. If you see the following message you have NxFilter successfully installed.

To access its admin GUI, start your browser and type 'http://localhost/admin' into the address bar. Or if you created a desktop icon during the installation process you can click it. If you see a login screen like below, your NxFilter is up and running. The initial login name and password is 'admin' and 'admin'.

- Go index -
Install NxFilter on Ubuntu Linux
We have a 'deb' package for installing NxFilter on Ubuntu Linux. To install it, after you install Java, download the package using 'wget', and then install it using 'dpkg'. Then start it from the Systemd script bundled with the package.

* We have a video tutorial on Youtube - View Youtube tutorial!

* OpenJDK 9 makes a problem with our embedded webserver. We recommend you to run NxFilter with OpenJDK 8.

sudo apt-get install openjdk-8-jre
wget http://www.nxfilter.org/download/nxfilter-4.0.2.deb
sudo dpkg -i nxfilter-4.0.2.deb
sudo systemctl enable nxfilter.service
sudo systemctl start nxfilter.service

To access its admin GUI, start your browser, if you install it on '' type '' into the address bar of your browser. The initial admin name and password is 'admin' and 'admin'.

When you update NxFilter using a 'deb' package and if you update it to v4.0.3 use the following commands,

sudo systemctl stop nxfilter.service
sudo dpkg -i nxfilter-4.0.3.deb
sudo systemctl start nxfilter.service

On older version of Ubuntu system you might be using Upstart instead of Systemd. We install an Upstart script as well. You need to use the following commands to start and stop NxFilter service.

sudo start nxfilter
sudo stop nxfilter

To remove NxFilter,

sudo dpkg -r nxfilter

- Go index -
Install NxFilter on Raspberry PI 3 with Raspbian
We ignored Raspberry PI so far as its memory size was not big enough in our thought. However, Raspberry PI 3 came with 1 GB of memory and it is enough to run NxFilter against several hundred users. We uploaded a video tutorial for demonstrating how to install NxFilter on Raspberry Pi 3 with Raspbian Linux.

As you know Raspbian is based on Debian Linux as Ubuntu Linux. So you can install it and manage it in the same way as we explained on Install NxFilter on Ubuntu Linux on this tutorial. The only difference was that we installed Oracle JDK 8 instead of OpenJDK. We did the following steps on the Youtube tutorial video.

1. See if Java installed on your system using 'java -version' command.
- Install Java if you don't have it.
- We install it using 'sudo apt-get install oracle-java8-jdk'.

2. Download nxfilter-4.x.x.deb from NxFilter homepage.
- We use wget for downloading the package.

3. Install it using 'sudo dpkg -i nxfilter-4.x.x.deb'.

4. Enable and start NxFilter service using the commands below.
- sudo systemctl enable nxfilter.service
- sudo systemctl start nxfilter.service

5. Wait for NxFilter building its Jahaslist database.
- Monitor its log file using 'tail -f /nxfilter/log/nxfilter.log'.
- Depending on your disk access speed, it may take several minutes.

6. Login to NxFilter GUI using a browser.
- Initial login credential is 'admin / admin'.

7. See if your block redirection IP correctly updated on 'Config > Setup'.

8. See if you have more than 1.8 million domains classified in Jahaslist DB on 'Classifier > Jahaslist'.

- Go index -
Install NxFilter using RPM
Rob Asher have built RPM packages for NxFilter. He distributes his RPM packages from the following site.

    - Rob Asher's NxFilter-RPMs

* These RPM packages will take care of all the dependencies including Java.

- Go index -
Install NxFilter on other Linux
When you install NxFilter on Linux system in general,
- You need to have root permission.
- Make sure that your system has Java 7 or 8 installed.
- You can start NxFilter as a daemon use '-d' option with 'startup.sh'.

* OpenJDK 9 makes a problem with our embedded webserver. We recommend you to use OpenJDK 8 when you want to run NxFilter with OpenJDK.

1. Download 'nxfilter-x.x.x.zip' file from www.nxfilter.org.

2. Extract the zip file into '/nxfilter'.

3. Go to '/nxfilter/bin' and run 'chmod +x *.sh'.

4. Run 'startup.sh'.

5. To access its admin GUI, start your browser, if you install it on '' type '' into the address bar of your browser. The initial admin name and password is 'admin' and 'admin'.

* You might want to start NxFilter automatically at your system startup. On one of our Linux systems we have '/nxfilter/bin/startup.sh -d' in '/etc/rc.local' script. You need to use '-d' option for running NxFilter as a daemon.

- Go index -
Install NxFilter on Windows manually
This is about how to install NxFilter on Windows manually using a 'zip' package. You still can make it a Windows service with a batch script included in the package.

1. Download 'nxfilter-x.x.x.zip' file.

2. Extract the zip file into 'c:/nxfilter'.

3. Go to 'c:/nxfilter/bin''.

4. Run 'startup.bat'.

5. To access its admin GUI, start your browser, type 'http://localhost/admin' into the address bar of your browser. The initial admin name and password is 'admin' and 'admin'.

* If you want to install NxFilter as a Windows service run 'c:/nxfilter/bin/instsvc.bat'. It will create 'NxFilter' service. When you uninstall it run 'c:/nxfilter/bin/unstsvc.bat'.

* To run NxFilter as a service 'net start NxFilter'. To stop it 'net stop NxFilter'.

* Use 'net start NxCloud' and 'net stop NxCloud' for NxCloud.

- Go index -
Updating NxFilter
We provide a Windows installer and packages for some Linux distributions for installaing and updating NxFilter. While it is convenient, sometimes you have to do it with a 'zip' package. When you update NxFilter using a 'zip' package,

1. Download 'nxfilter-x.x.x.zip' file.

2. Stop NxFilter.

3. Extract the zip file into the directory NxFilter installed.

4. Start NxFilter.

- Go index -
Start and stop NxFilter
There are several utility scripts for NxFilter in '/nxfilter/bin' directory.

- To start NxFilter : startup.sh
- To stop NxFilter : shutdown.sh
- To see if it is running : ping.sh

On Windows, use '.bat' files instead of '.sh' files.

* When you run it as a Windows service use 'net start NxFilter' to start and 'net stop NxFilter' to stop.

* Use 'net start NxCloud' and 'net stop NxCloud' for NxCloud.

- Go index -
Client DNS setup
After you install NxFilter, you want to monitor and filter Internet activity in your network. To monitor and filter Internet activity you need to make NxFilter to be the only DNS server for your network.

The simplest way of setting up a DNS server for your users would be modifying the network setup on OS level like the above. But you don't want to set up all the PCs in your network one by one. So the best way would be using a DHCP server. You just need to modify DNS server address on your DHCP server setup and then your users will be using NxFilter as their DNS server.

If you have a firewall you can force your users to use NxFilter as their DNS server by blocking outgoing traffic on UDP/53, TCP/53 port. Now NxFilter became the only DNS server your users can use.

- Go index -
When NxFilter not starting
When you find your NxFilter not starting, the first thing you need to do is checking '/nxfilter/log/nxfilter.log' file. You can find some information about the cause of your problem. The other things you might want to check out would be the port collision problem and Java installation. NxFilter uses UDP/53, TCP/80, TCP/443. This means NxFilter itself is a DNS server and a webserver. So if you have another DNS server or webserver running on the same system NxFilter will not start.

About the Java installation, if you use NxFilter's Windows installer, in most cases you will not have any problem but if you install NxFilter manually or if you start it manually not using Windows service you might have some Java related problems. To avoid of having this kind of problem there should be Java installed on your system with proper environment variables.

If you are on a Windows system having properly configured Java, you will see this kind of message on command prompt when you type 'java'.

On Windows system you can set these environment variables.

JAVA_HOME = C:\Program Files\Java\jre7
PATH = %JAVA_HOME%\bin;C:\bin

If it is on Linux, NxFilter will try to find 'java' in '/usr/bin' first and then '/usr/local/bin' so if you don't have 'java' in these directories you need to modify the script files in '/nxfilter/bin' directory or include the path into the environment variables for your system.

To set up 'PATH' system variable for Java you can follow the instruction from the link below.

    - http://java.com/en/download/help/path.xml

- Go index -
What is a blacklist?
A blacklist is a database of categorized domains. This is an essential part for a DNS filter for blocking websites by categories. NxFilter supports several blacklists.

1. Jahaslist
Jahaslist is the default blacklist option for NxFilter. It supports dynamic classification by NxClassifier. NxClassifier is the integrated auto-classification engine for NxFilter.

For more about NxClassifier and Jahaslist, read NxClassifier section.

* We ship 30 day trial license and a free 20 user license for Jahaslist in NxFilter package. Once you install NxFilter, you can use Jahaslist without any restriction for 30 days. After the 30 days of trial it becomes a free 20 user license.

2. Cloudlist
We outsource a third party cloud based blacklist option. It has more than 30 million domains classified already and does dynamic classification. Since it is on cloud, you don't need to import or update anything.

* As of v4.1.3, NxFilter includes 30 day trial license of Cloudlist for 50 users.

3. Globlist
Globlist is a new free blacklist option from NxFiter v4.2.0. It has more than 400,000 domains classified into 3 categories that are Ads, Phishing/Malware and Porn. It does auto-update on background. Globlist works on global policy level only.

- Go index -
Using Jahaslist, Cloudlist
Jahaslist and Cloudlist blacklist options are commercial. You can find out more of them and buy licenses on the following links.

- Go index -
Reclassification on blacklist
You can reclassify domains into any system/custom category. Your custom classification overrides the existing classification. So the effect of custom classification is immediate. No need to report it back to somewhere and wait to see it updated.

There are two ways of reclassification. One is to add domains on 'Category > System' or 'Category > Custom' and the other one is using the popup reclassification form by clicking a domain on 'Logging > Request'.

- Go index -
NxFilter and authentication
NxFilter provides several authentication methods including single sign-on with Active Directory integration.

Why authentication

When you install NxFilter first time you only have one policy and it applies to everybody in your network. But what if you are working for a school as a systems administrator and you want to apply a policy based on user and group. For students, a stricter policy and for teachers, a bit lenient policy. Now you need to differentiate users. That's when you need to enable authentication.

Which authentication

NxFilter supports several ways of authentication. You can choose one of them or mix and match some of them.

1. IP based authentication
This is the simplest form of authentication. When you use a static IP address for your client PC this might be the best choice. Just associate an IP address of a client PC to a user you create on NxFilter GUI. You also can associate an IP range to a user.

* Many people try to use IP based authentication without enabling authentication on 'Config > Setup'. But IP based authentication is still a method of authentication so you must enable it first.

2. Password based authentication
When you enable authentication, NxFilter blocks any user trying to access the Internet with its login-page unless they already logged-in or having IP an address associated to them. To go through the login-page your users need to enter their username and password. You can set a password for each user on NxFilter GUI.

3. LDAP based authentication
If you integrate NxFilter into OpenLDAP or Active Directory, your users can go through the login-page using their LDAP credentials. To use this feature, you need to import your users from your LDAP server first.

4. Login token based authentication
NxFilter has a special concept called 'Login Token'. This is used for remote user filtering. This login token is being created for each user when you create or import users. You use it to differentiate users for remote user filtering with NxClient or for dynamic IP update with NxUpdate.

5. Single sign-on against Active Directory
Many people want to filter their users transparently. Or you don't want to show any login prompt to your users. NxFilter provides Active Directory integration. Once you implement it, your users don't need to go through NxFilter's login-page and your users will be appeared on NxFilter GUI with their Active Directory username and group.

- Go index -
Active Directory integration in general
NxFilter supports Active Directory integration. We tried to make it simple and easy but some people still find it hard to understand. So we want to explain what is Active Directory integration for NxFilter and when to use it and how to implement it at conceptual level.

What is Active Directory integration

One of the reasons why people want to integrate NxFilter into Active Directory is that they want to apply filtering policies based on Active Directory user and group. They also don't want to have their users going through any extra login step to use the Internet except when they login to their own PC. So for NxFilter, 'Active Directory integration' means using the same user account from your Active Directory to differentiate users on NxFilter and having single sign-on with your Active Directory.

User importation

Now we know what is Active Directory integration and why we need it. But how to do that? On NxFilter, the first thing you need to do for implementing Active Directory integration is to import the users and groups from Active Directory. It means you need to let NxFilter be aware of your users and groups. You can do that on 'User > Active Directory'.

After you import your users and groups, your users will be able to use their Active Directory credentials on NxFilter's login-page. So we already achieved Active Directory integration to a certain level.

Single sign-on with Active Directory

We can say that we achieved Active Directory integration as your users can use their Active Directory credentials on NxFilter's login-page. However, your users don't want to go through the login-page so the next thing you need to do is implementing single sign-on with your Active Directory. To impelment single sign-on, you will need an agent program working with NxFilter. We have several agents that are NxLogon, VxLogon, NxMapper, NxClient. You can use just one of them or mix and match them to complement each other.

* For more information, read single sign-on or agent related parts of this tutorial.

MS DNS server and NxFilter

When you deploy NxFilter in an Active Directory environment you might be worrying about the possibility of breaking the integrity of Active Directory as NxFilter is a DNS server and the role of a DNS server in Active Directory is very important. But we don't disable or replace the existing Active Directory DNS server. Our approach is to work with the existing Active Directory DNS server in cooperation. So you have to maintain your existing MS DNS server even though you use NxFilter as the DNS server for your network.

1. Where to install it
Some people try to install NxFilter on their domain controller. But you already have a DNS server there. It is your MS DNS server. It would be better to install it on another system to avoid of having a port collision problem.

If you have to install it on your domain controller, watch our Youtube video tutorial for that, Install NxFilter on Windows server without having DNS port collision

2. Dynamic host update
MS DNS server in Active Directory does a lot of things. It lets the hosts in Active Directory find the location of resources using SRV records. And it maintains a DNS zone for every hosts. It does dynamic host IP update when you change an IP address of a system. To keep all these things working, NxFilter bypasses the internal DNS queries for Active Directory domain to MS DNS server automatically.

3. Which upstream server for NxFilter
You might have a question about which DNS server you should use as an upstream server for NxFilter because you already have a DNS server that is your MS DNS server. You can use any DNS server as an upstream DNS server for your NxFilter including your MS DNS server. NxFilter still forwards your Active Directory internal DNS queries to your MS DNS server. So you can use whichever DNS server you think the best.

4. Manual setup for MS DNS server
After you import Active Directory users and groups, NxFilter tries to work with your MS DNS server automatically based on your Active Directory importation setup but sometimes you want to have a different settings for your MS DNS server. Or you may want to have a redundancy for your MS DNS server. In that case, you can do all these things on the edit page of your Active Directory importation setup. For having redundancy, you can add multiple DNS servers separated by commas.

* You might need to allow 'Nonsecure Dynamic Update' on your MS DNS zone properties for NxFilter to update the IP addresses of the hosts in your MS DNS zone.

An exemplary deployment scenario

Lastly, we will give you an exemplary deployment scenario. Suppose that we are in a company environment. Many Windows PCs and some Macbooks and recently we bought several Chromebooks. And people bring their own iPhones and Android phones. And plus, we have several Linux servers for our own website and file sharing. There are some mobile workers using company laptops. Some are using Windows and some are using Macbooks. And you want to filter all of them whether they are inside office or outside office with their Active Directory accounts.

The first thing you need to do is to set up Active Directory user and group importation. And then use NxLogon for these Windows PCs. But NxLogon doesn't work with Macbooks. For these Macbooks you can use NxMapper. Install and run it on your domain controller.

And then you want to deal with these mobile workers. You can install NxClient on their laptops. NxClient is basically a remote filtering agent for NxFilter but it will try to do single sign-on when it is in your local Active Directory.

For your servers, you better not to filter them and set them up with static IP addresses and use another DNS server for them or put them under a policy allowing everything. You don't need to block anything from them normally.

For your iPhone and Android phones, just let them go through NxFilter's login-page.

- Go index -
Single sign-on with Active Directory using NxLogon
When you have Active Directory you want to have single sign-on against it and not showing any extra login prompt to your users. For this, we have an agent program that is NxLogon. When you run NxLogon on a user PC it creates and refreshes a login session for the user on NxFilter.

However, you don't want to install this program on every PC in your network. So we use a logon script on GPO(Group Policy Object). This logon script is being executed whenever a user logon to Active Directory and launches NxLogon on each user's PC.

* If you want to have single sign-on against Active Directory you firstly need to import users and groups from your Active Directory. To import users and groups, read GUI - User

* NxLogon uses TCP/19002 port to talk to NxFilter.

* If you think using GPO is to difficult for you, you can go with NxMapper.

Follow the steps below to launch NxLogon from GPO.

1. Download nxlogon-x.x.zip package from www.nxfilter.org.

2. Modify IP address in 'nxlogon.bat' to point NxFilter. If you use clustering you can add multiple server IP addresses separated by spaces.

3. Open 'Administrative Tools > Active Directory Users and Computers' on your DC.

4. Open 'Group Policy Manager' on 'Server Manager > Tools'.


5. Click 'Edit' button on 'Default Domain Policy' and then go to 'User configuration > Policies > Windows Settings > Scripts (Logon/Logoff)'.


6. Click 'Logon' and click 'Add' and then click 'Browse' button. You will see 'Logon' directory to select file. Copy your 'nxlogon.bat' and 'nxlogon.exe' from NxLogon package into 'Logon' directory. You can drag and drop the files into the directory.

7. Select 'nxlogon.bat' which you copied into 'Logon' directory as a logon script to add.


8. Now every time a user logon to his/her system 'logon.bat' will be executed and it will launch 'nxlogon.exe'. You can see the process running on Windows task manager.


9. You can see the result from NxFilter side. It creates user login session when it gets a request from NxLogon.


* If you want to remove login session immediately after user logout use 'nxlogoff.bat' as a logoff script in GPO.

- Go index -
Single sign-on with Active Directory using VxLogon
We introduced a script version of NxLogon which is named 'VxLogon'. We noticed that some users having problem with NxLogon as it's an EXE file and their anti-virus softwares making false positives with it. So we wrote a script version of NxLogon using VBScript. It is simpler and easier to deploy. VxLogon is supported as of v4.1.8 of NxFilter.

How to run it

To run it, you need to activate it on 'Config > VxLogon' on NxFilter GUI first and then register 'vxlogon.vbs' from VxLogon package as a Windows logon script on GPO.

* If you are not familiar with GPO and logon script read Single sign-on with Active Directory using NxLogon.

* Unlike NxLogon, you don't need to specify server IP for VxLogon.

Security problem

With VxLogon, to make things easier and simpler, we use DNS protocol as the communication protocol between VxLogon and NxFilter. As a result, some of your users might be smart enough to find a way of logging-in with another username to acquire an alleviated permission as the protocol exposed in a script file from our VxLogon package. To prevent this kind of problem, we added an additional security procedure for activating VxLogon. We defined two special domains for logon and logoff with VxLogon.

On 'Config > VxLogon',

- Logon Domain : vxlogon.example.com
- Logoff Domain : vxlogoff.example.com

You can redefine these domains. After you change the domains you also need to edit the following 2 files in VxLogon package.

- vxlogon.vbs
- vxlogoff.bat

In the files, you have the special domains and you need to change them to yours.

* Since we use 'nslookup' internally, you have to keep the trailing dot when you change the domains.


If you run 'vxlogon.vbs' on CMD you will not see any output as it will run by 'wscript' which is the default VBSCript engine on Windows. If you want to verify your deployment with logging, run it with 'cscript' command,

cscript vxlogon.vbs

And run NxFilter on CMD as well so that you can monitor what is going on NxFilter side.

- Go index -
Single sign-on with Active Directory using NxMapper
While using NxLogon is still the best solution for Active Directory single sign-on but some people find it difficult to set up all these GPO and logon script things. So we offer an easier way of implementing single sign-on against Active Directory. When you install and run NxMapper on your domain controller it will grab username and IP address pair when a user logon and creates a login session on NxFilter.

* If you want to have single sign-on against Active Directory you firstly need to import users and groups from your Active Directory. To import users and groups, read GUI - User

Install and run NxMapper

We offer a Windows installer for NxMapper. It will install NxMapper as a Windows service. After you install it, you will have its setup program running.

* NxMapper needs to be installed on a domain controller.

* You can add multiple IP addresses separated by commas if you run a cluster of NxFilter.

* NxMapper uses TCP/19002 port to talk to NxFilter.

After you modify the config values, test your setup first and then start it.

Differences from using NxLogon

Although it is a lot easier to be compared to using NxLogon, NxMapper also has its own limit. The login session created by NxMapper can be expired. While NxLogon refreshes its login session on evey minutes, NxMapper creates or refreshes a login session only when there is a user activity on a domain controller. Once the session expires your users will be redirected to NxFilter's login-page. To avoid of having this kind of problem, you can increase the session timeout value on 'Config > Setup > Block and Authentication > Login session TTL'.

* Login session created by NxMapper can be expired as NxMapper doesn't refresh it. But NxFilter also refreshes it on server side whenever it gets a DNS request from a user. So it doesn't expire as long as your users using the Internet.

Terminal server exclusion

When we use NxMapper we might have a problem with Windows terminal server. If there are multiple users on one system the IP address of the system will be associated to the user whose action detected lastly by NxMapper. It means your users can be appeared on NxFilter with a different username. To prevent having this kind of problem, the best solution would be creating an IP based user for your terminal server.

- Go index -
Single sign-on with Active Directory, OpenLDAP using NxClient
NxClient is basically a remote user filtering client for mobile workers with their own laptops. But you can use it for single sign-on against Active Directory or OpenLDAP.

If you already tried to use NxClient you already know that single sign-on using NxClient is possible with its 'Login Token' concept. But with this approach one problem is that it is almost impossible to set up several hundreds of NxClient installations with their own 'Login Token'.

So we provide a way of running NxClient on a local network without setting up an unique login token to each client PC. What you need to do is to install NxClient using a common login token for all the client PCs. Then when it starts it will look for its server that is NxFilter on the local network and if it finds one it will try to create a login session for the current logged-in user or console username.

* For NxClient to be able to detect your NxFilter, you have to use NxFilter as the DNS server for your client PC.

* If you use NxClient only for single sign-on you can install it without a login token and a server IP.

To find out more about NxClient, read NxClient and remote user filtering

- Go index -
Custom login script for single sign-on
NxFilter supports single sign-on with Active Directory. However some people want more than that. For example, you might want to have single sign-on with OpenLDAP. To accomodate that kind of request, NxFilter supports an API set for creating login session through HTTP protocol. You can write your own custom login script to call some webpage on NxFilter's built-in webserver. And then your users don't need to go through any login prompt.

We have an example on '/nxfilter/webapps/example/login_user.jsp'. Initially the access of the page is restricted to localhost only for security reason but you can edit the JSP page to allow HTTP requests from your local network.

You can call the webpage this way.

As you see above, there are two parameters being passed. One is the IP address of your user and the other one is an associated username. The username should be imported or created on NxFilter side already.

One thing you need to consider when you write your own login script is that it might be better to call the webpage periodically. There is a session timeout concept in NxFilter. If there is no activity from a logged-in user for certain amount of time the login session will be expired. So if you don't want to show NxFilter's login-page to your users, you would need to refresh the login session periodically.

On JSP pages, we use 'UserLoginDao' class for manipulating login session. It has the following methods.

- createIpSession(String ip, String uname) : Creating a login session with an IP and username.
- deleteIpSession(String ip) : Deleting a login session with an IP.
- findUser(String ip) : You can find a logged-in username by its associated IP address.

All the example JSP pages are in '/nxfilter/webapps/example' directory.

- Go index -
The order of authentication methods
NxFilter supports multiple authentication methods. So you could have some collisions between these authentication methods. For example, what if a user having an associated IP also falls into an IP range which is associated to a different user? Or what if a user passed NxFilter login-page is in an IP range which is associated to another user? To address this issue, we have a sequential order for the authentication methods.

This is the order of authentication methods.

1. Single IP association
Single IP association comes first so that you can exclude some systems from IP range association or allow some users to login without login prompt.

2. IP session
'IP session' is a login session being created and maintained on NxFilter by its single sign-on agent or login-page. This comes at second.

3. IP range association
When you need to allow anonymous users to access the Internet without any login process you associate the IP range to cover whole network to a user. But you still can differentiate users by single IP association or the login session. So the IP range association comes at last.

We have 'Most specific IP range comes first' rule for ordering IP range users. If there are overlapped IP ranges, the smaller IP range will be applied before the others.

- Go index -
GUI - Config
These are mostly system configuration parameters for NxFilter.
Config > Setup > Block and Authentication

- Block Redirection IP
This is the IP address of NxFilter itself. If there is a blocked DNS request, it will be redirected to this IP address. It is supposed to be populated automatically during the installation process.

* When you use clustering, you can add multiple block redirection IP addresses separated by commas for redundancy.

- External Redirection IP
When you use a remote filtering agent, you might need to use a different 'Block Redirection IP' for the remote filtering agent since it is outside your network. If you leave this one empty NxFilter will use 'Block Redirection IP' for redirecting the remote filtering agent.

- IPv6 Redirection IP
As of v4.0.5, NxFilter uses IPv4 over IPv6 as its IPv6 block redirection IP automatically. So normally you don't need to set this up. But sometimes you want to override it by manual setup.

- Enable Authentication
After you enable this option, any unauthenticated user will be redirected to NxFilter's login-page. Your users will be forced to login to use the Internet.

- Login Domain
You can access NxFilter's login-page using a domain defined here.

- Logout Domain
You can clear out a user login session using a domain defined here.

- Login Session TTL
NxFilter keeps a login session after a user login. But this login session needs to be expired eventually. It is especially required when there is a shared PC by several users. If a user doesn't make any DNS request for the specified amount of time defined here, his/her login session expires and the user needs to login again.

- Disable Login Redirection
With this option enabled, NxFilter doesn't do login redirection. All the DNS packests from unauthenticated users will be dropped. This option is for hiding your server from attackers when you deploy your server on the Internet.

Config > Setup > Syslog

NxFilter supports Syslog exportation of its log data. You can build your own reporting system with this feature or you can monitor all the logging in a real-time manner.

- Syslog Host
The host IP address to which you want to send Syslog data.

- Syslog Port
UDP port of a target host.

- Export Blocked Only
With this option, NxFilter sends the log data of blocked DNS request only.

- From Each Node
At default, Clustered NxFilter sends Syslog data only through its master node. When you enable this option, each node exports its own data.

- Enable Remote Logging
Enable Syslog exportation.

Config > Setup > NetFlow

NxFilter supports bandwidth control. This is possible by importing NetFlow data.
To find out more, read Bandwidth control with NxFilter

- Router IP
The IP address of a device sending NetFlow data to NxFilter.

- Listen Port
The UDP port number of NetFlow collector.

- Run Collector
Run NetFlow collector. After change this option, you need to restart NxFilter.

Config > Setup > Misc

- Admin Domain
You can access NxFilter admin GUI using a domain defined here. For example, if you use 'admin.nxfilter.org' as your admin domain you can access your admin GUI by typing 'http://admin.nxfilter.org/admin' into your browser address bar.

* This only works when you use NxFilter as your DNS server.

- Bypass Microsoft Update
You don't want to block Microsoft update with your filtering. Enabling this option means bypassing 'microsoft.com' and 'windowsupdate.com' and their subdomains.

- Logging Retention Period
If you keep your log data too long it may cause a disk space problem. You can set how long NxFilter keeps its log data here.

- SSL Only to Admin GUI
When you want to allow only HTTPS access to your admin GUI enable this option. Once you enable this option, you will be redirected to the SSL port automatically even if you try to use HTTP protocol.

- Auto Backup
NxFilter makes a backup file for its configuration into '/nxfilter/backup' directory on '01:00' everyday. The name of the backup file starts with 'auto-' prefix. You can have up to 30 backups.

- Agent Policy Update Period
NxFilter provides several agent programs for application control and remote user filtering. These agents fetch their policies periodically. You can set up the policy update period for them here.

Config > Admin

You can change admin name and password for GUI login here.

* 'Report Password' is for report manager to access the logging/reporting related menus on GUI.

Config > Alert

NxFilter sends an email for recent blocking or access violation. If you want to send an alert email to 'admin @ nxfilter.org' from 'alert200 @ gmail.com' every 15 minutes then the setup would look like the below.

- Admin Email : admin @ nxfilter.org
- SMTP Host : smtp:gmail.com
- SMTP Host : 465
- SMTP SSL : on
- SMTP User : alert200
- SMTP Password : ********
- Alert Period : Every 15 minutes

* When you set this up, NxFilter also sends alert emails for system related incidents. But 'CC Recipients' is only for access violation or blocking on filtering.

* You can set up the categories you want to get alerted with when a domain gets blocked.

Config > Allowed IP

NxFilter has IP based access restriction function for its DNS, GUI, login redirection. You may need to use this feature when you put your NxFilter on a public IP address. You can make whitelist/blacklist way of ACL here.

Config > Backup

You can create and download a backup file for the current configuration of NxFilter manually.

Config > Block Page

This is the setup for custom block-page, login-page, welcome-page. When you edit your block-page you can use the following variables populated by NxFilter for making your block-page more informative.

- #{domain} : Blocked domain
- #{reason} : Reason for block
- #{user} : Logged-in username
- #{group} : Groups of the logged-in user
- #{policy} : The applied policy
- #{category} : Categories of the blocked domain

Config > VxLogon

VxLogon is a script version of Active Directory single sign-on agent for NxFilter. It is supported from v4.1.8 of NxFilter.

- Logon Domain
Special domain defined for logon signal of VxLogon. When you chage this you need to change the domain in 'vxlogon.vbs' of VxLogon package.

- Logon Domain
Special domain defined for logoff signal of VxLogon. When you chage this you need to change the domain in 'vxlogoff.bat' of VxLogon package.

- Use VxLogon
Enable or disable VxLogon support.

Config > Cluster

NxFilter has a built-in clustering. You can make your NxFilter to be a master node or a slave node in a cluster. After you change the values in cluster setup you need to restart your NxFilter to apply the new settings.

- Go index -
NxFilter is basically a DNS server with filtering ability. These are DNS service related configuration parameters.
DNS > Setup > DNS Setup

- Upstream DNS server
NxFilter works as a forwarding DNS server. You need to have at least one upstream DNS server for NxFilter.

- Upstream DNS Query Timeout
Timeout for a DNS query to your upstream DNS server.

- Response Cache Size
NxFilter has its own cache for DNS query result from its upstream server. Generally speaking, the bigger cache would be better for performance. Currently the default size is 200,000 and it is enough for most cases.

- Use Persistent Cache
NxFilter can keep up to 1 million DNS responses in its DB. When you have enough number of persistent cache you will not lose your 'Internet Connection' even if there is a nationwide DNS outage as NxFilter work with its persistent cache.

- Use Negative Cache
At default, NxFilter doesn't keep a negative response in its cache. With this option, NxFilter will keep a negative reponse such as 'Server Failure' or 'Non-existent Domain' up to 15 minutes.

- Minimal Responses
You can send only 'Answer' records in a DNS response of NxFilter and ignore 'Additional' and 'Authority' section for reducing DNS packet size and improving server performance.

DNS > Setup > Local DNS

- Local DNS Server
When you have a local DNS server for resolving your local domain add your local DNS server IP address here. You can add multiple IP addresses separated by commas for redundancy.

- Local Domain
When you have a domain which you want to bypass to your local DNS server add the domain here. You can add multiple domains separated by commas.

* Don't use '*' or any wildcard for a local domain. It includes its subdomains already.

- Local DNS Query Timeout
Timeout for a DNS query to your local DNS server.

- Use Local DNS
Enable local DNS.

* If you set up a local DNS server for you local domain, all the DNS queries for your local domain will be bypassed from authentication, filtering and logging.

DNS > Setup > DNS Over HTTPS

- HTTPS DNS Server
NxFilter supports Cloudflare and Google HTTPS DNS servers.

- HTTPS DNS Query Timeout
Timeout for a DNS query to your HTTPS DNS server.

- Fail-safe With UDP/53
You can make NxFilter querying again using UDP/53 protocol when there's a failure with HTTPS DNS server.


DNS > Setup > Misc

- Drop Hostname Without Domain
When you use NxFilter or NxCloud on cloud you don't need to deal with hostname only domains.

- Drop PTR For Private IP
Drop reverse lookup for private IP addresses. You might need this option when you run NxFilter on cloud.

DNS > Zone File

When you use NxFilter as an authoritative DNS server you would need to set up a zone file. We use the same format as a BIND zone file. To find out more, read Authoritative DNS server part of this tutorial.

DNS > Redirection

Domain to IP or domain to domain redirection is possible with NxFilter. It works like a custom DNS record.

DNS > Zone Transfer

In some situation, you need to import a DNS zone from another DNS server. Once you add a zone-transfer setup here, NxFilter imports the DNS zone every minute using IXFR protocol.

DNS > Dynamic DNS

NxFilter supports dynamic DNS service. For howto, read Dynamic DNS service part of this tutorial.

- Go index -
GUI - User
You can create or import users and groups here. NxFilter supports user importation from Active Directory and OpenLDAP, eDirectory.

Creating a user

There are 3 types of users you can create on NxFilter

1. IP user
It has an associated IP address or an IP range and will be authenticated based on IP address.

2. Password user
If you set a password for a user it becomes a password user. You can use the password on the login-page of NxFilter.

3. LDAP user
When you import users from your LDAP servers or Active Directory they become LDAP users. They can use LDAP or Active Directory user credentials on NxFilter's login-page.

Properties of a user

- Password : The password for login through NxFilter's login-page.
- Work-time Policy : The policy being applied when it is not in a free-time.
- Free-time Policy : The policy being applied during a free-time. You can define a free-time on 'Policy > Free Time'.
- Expiration Date : The expiration date for a user account.
- Login Token : The token for remote user filtering or remote user authentication. It is created when a user created or imported.

Testing a user

When you have an LDAP imported user you may have multiple groups and policies for a user. As a result it becomes difficult to figure out which policy a user falls into. To find out which is the 'Applied Policy' for a user, use 'TEST' button on the user list. It fetches the state of a user from NxFilter in a real-time manner.

* You can use this test view to find out how much quota or bandwidth consumed by a user or to reset quota or bandwidth for a user.

Creating a group

After you create a group on 'User > Group', you can set up a policy for the group by editing its properties. You also can assign members to the group.

Importing users and groups from Active Directory, OpenLDAP, eDirectory

You import users and groups from Active Directory on 'User > Active Directory'. For example, if you have your Active Directory with the following setup.

- Domain controller :
- Domain : nxfilter.local
- Admin username : Administrator

Then create an Active Directory importation setup with the following details.

- Host :
- Admin : Administrator@nxfilter.local
- Password : your-password
- Base DN : cn=users,dc=nxfilter,dc=local
- Domain : nxfilter.local

After having an Active Directory importation setup you can import users and groups with 'IMPORT' button. You also can set up a periodical import by selecting an auto-sync interval.

* Use 'TEST' button when you want to test the connection between NxFilter and your domain controller with your importation setup.

- Go index -
GUI - Policy
With NxFilter you can have multiple filtering policies in your network based on user and group.

Creating a policy

When you install NxFilter, there is only one policy that is 'Default'. This policy will be applied to everybody if you don't make any change on NxFilter setup. If you want to apply a different policy for a specific user or group you need to create another policy and enable authentication.

Editing a policy

After you create a policy you can modify its properties.

- Priority Points
If there are multiple policies associated to one user then the policy having the biggest points will be applied.

- Enable Filter
If you disable this option there will be no blocking from the policy.

- Block All
Block everything on policy level.

- Block Unclassified
Block unclassified domains.

- Ad-remove
Block domains in 'Ads' category of Jahaslist with a blank block-page.

* This is useful when you want to remove embedded adverts without showing NxFilter's block-page.

- Max Domain Length
There are some malwares using domain name itself as a message protocol. These domains are abnormally long while the length of most domains are under 30 characters. You can set a limit for the length of a domain to block these abnormal domains. To prevent having false positives NxFilter doesn't apply 'Max Domain Length' against 100,000 well known domains.

- Block Covert Channel
Some malwares or botnets are using DNS protocol as their communication tool. They are using DNS queries and responses to communicate with each other.

- Block Mailer Worm
Normally you are not supposed to see MX query from your client PC. When NxFilter finds MX type query from your client PC, it will be regarded from some malware trying to send emails.

- Allow 'A' Record Only
This is the most strict way of filtering malwares and botnets employing DNS protocol as their communication tool. If you are an ordinary office worker you don't need to use any special type of DNS record. With this option enabled, NxFilter allows A, AAAA, PTR, CNAME only and the other types of DNS records will be blocked.

- Quota
NxFilter has quota-time feature. You can allow your users to browse some websites for a certain amount of time. You can set the amount of time here.

- Quota All
Apply quota to all domains including unclassified domains.

- Bandwidth Limit
You can set the bandwidth consumtion limit for a user.

This feature requires to import NetFlow data from your router or firewall. To find out more, read Bandwidth control with NxFilter on this tutorial.

- Safe-search
Enforcing safe-search against Google, Bing, Youtube.

* At the moment, switching between 'Moderate' and 'Strict' makes difference only for Youtube.

- Block-time
You can set policy specific block-time.

- Disable Application Control
Disable application control on policy level.

- Disable Remote Filtering
Disable remote filtering on policy level.

- Logging Only
Monitoring user activity without blocking them.

- Blocked Categories
You can block domains by categories.

- Quotaed Categories
If you check some categories in 'Quotaed Categories' then your users can access the websites in the categories for the amount of time you specified with 'Quota' above. When a user consumed up his quota his/her DNS requests for those sites will be blocked.

Define a free-time

Global free-time can be defined on 'Policy > Free Time'. If you assign a free-time policy to a user, it will be applied during the time defined here.

* If the start-time is bigger than the end-time then it will break into 'end-time ~ 24:00' and '00:00 ~ start-time' on the same day.

* We have group specific free-time and policy specific block-time. Make your own free-time policy based on all of these.

Application Control

NxFilter provides application control through NxClient. For more details, read Application control with NxClient part of this tutorial.

Remote Filtering

NxFilter provides remote user filtering through NxClient. For more details, read Remote filtering with NxClient part of this tutorial.

- Go index -
GUI - Category
On NxFilter, there are system categories and custom categories. System categories are already defined by your blacklist DB. But you can create your own custom categories. You can add domains into these system/custom categories and block domains by these categories.

Currently, NxFilter supports several blacklist options. If you want to find out more, read Blacklist and domain categorization part of this tutorial.

* To include subdomains into a category use an asterisk.

    ex) *.nxfilter.org

* If you want to find out which category a domain falls into, use 'Category > Domain Test'.

- Go index -
GUI - Whitelist
This is for making a whitelist/blacklist by a domain or a keyword.

- Bypass Authentication : When you want to allow your users to access some sites without authentication use this option.

- Bypass Filtering : To exclude some domains from your filtering check this option.

- Bypass Logging : When you have too many log data for a domain which you are not interested in, you can bypass logging for the domain with this option.

- Admin Block : To block some domains without setting up a policy use this option. This option overrides 'Bypass Filtering'.

- Drop Packet : When you want to completely ignore and not to respond requests for a specific domain check this option.

* You can use an asterisk to include subdomains.

    ex) *.nxfilter.org

- Go index -
GUI - Dashboard, Logging, Report
NxFilter keeps its log data up to 400 days and you can generate a daily, weekly, per-user report based on the log data.

When you login to your admin GUI you will see the dashboard of NxFilter. There are several charts for showing a summary for the last 2 hours. At the bottom of the dashboard, you can see 10 recent block logs for the last 12 hours.

* The difference between 'request-sum' and 'request-cnt' is from NxFilter's logging system. To reduce the amount of disk access, NxFilter keeps all the log data into its memory space before it flushes out the data once a minute. If there is a request for the same domain from the same user in a minute it only increases the count for the data. So 'request-sum' means the sum of all the requests and 'request-cnt' means the count for all the unique data.


You can search user request log with various conditions on 'Logging > Request'. Logging data is being updated once in a minute to reduce the load on DB.

On 'Logging > Signal' you can view the log of the signals from the agents of NxFilter.

On 'Logging > NetFlow' you can view the NetFlow data imported.

* Use square brackets for the exact matching keyword on log search.

    ex) [nxfilter], []


NxFilter generates a daily, weekly, per-user report.

- Go index -
Differences between agents
NxFilter has several agents. Some are for single sign-on with Active Directory. Some are for remote user filtering and dynamic IP update. Some of them can be used for application control and remote filtering.

1. NxLogon and VxLogon
Single sign-on agent for Active Directory. You can launch it from a logon script on GPO. VxLogon is a script version of NxLogon

2. NxMapper
Another option for single sign-on with Active Directory. You install and run it on a domain controller.

3. NxClient
Remote user filtering agent of NxFilter. When you have a mobile worker or home worker working remotely you can install NxClient on his/her laptop.

4. NxUpdate
Dynamic IP updater for NxFilter.

5. NxForward
Block-page forwarder on HTTPS for Chrome.

- Go index -
NxClient and remote user filtering
NxFilter provides a remote user filtering client software that is NxClient. Once you install NxClient on a user system, you can filter and monitor the Internet activity from the user system on your NxFilter GUI centrally regardless of its location.

* You need to open TCP/80 port on NxFilter side.

Installation of NxClient

After you install it using NxClient installer, you will have its setup program running. There are 'Server IP' and 'Login Token' parameters and you need to set them up with new values.

* On NxFilter, every user has a login token. You can find it on 'User > User > EDIT'.

* NxClient is a Windows service program. It starts at system startup automatically.

After you modify the config value, test your setup first and then start it. You can check if it is working by viewing 'Logging > Signal' on NxFilter GUI. There will be signals from NxClient.

* You can add multiple server IP addresses separated by commas if you run a cluster of NxFilter.

* After you install NxClient, to change its config parameters run 'C:/Program Files/nxclient/setup.exe'.

Signals of NxClient

When it comes to remote user filtering, the most tricky part would be how to force users to be filtered. Nobody wants to get filtered and they are away from your office. If they use their personal PC then you can not filter them anyway. But when they use a company laptop you still can filter them by installing NxClient on their system.

However, what if they uninstall or stop NxClient? NxClient is running as a service and it doesn't provide an uninstaller for 'Add/Remove programs' in control panel. So if your users don't have enough privilege they can't uninstall it.

But sometimes you need to give your users 'Local Administrator' privilege. In that case, it's not possible to stop your users from uninstalling NxClient. So we defined several signals with which you can find out what is happening on a user system. NxClient sends these signals.

- START : When NxClient starts, it sends START signal to NxFilter.
- STOP : When NxClient stops, it sends STOP signal to NxFilter.
- PING : NxClient sends PING signal to NxFilter every 5 minutes.

You can view these signals on 'Logging > Signal' on NxFilter GUI.

Fail-safe measure for NxClient

When NxClient can't connect to its server and doesn't know which domain to block or allow, it bypasses filtering temporarily before it gets the connection restored. This is because your users need to be able to use the Internet anyway. If you use clustering, you can specify multiple server IP addresses on its setup for redundacy.

Auto-switch between local filtering and remote filtering

When you use NxClient on your mobile worker's laptop you might have a problem with your filtering policy when they are staying in the office. Your mobile worker might be filtered twice. One from NxClient, one from your local NxFilter. And he/she might be required to go through the login-page of NxFilter.

To address this issue, NxClient does auto-switch between local filtering and remote filtering. This means that NxClient can find NxFilter in a local network and when it is on your local network it stops its remote filtering. Plus, it has its own NxLogon module doing single sign-on in your local network.

* If you don't like this auto-switch behavior you can add 'no_switch = 1' into 'C:/Program Files/nxclient/conf/cfg.properties'.

Uninstalling NxClient

To prevent an accidental uninstallation by your user, NxClient doesn't provide an uninstaller on 'Add/Remove programs' in control panel. When you uninstall NxClient you need to do it manually with the following steps.

- Run 'C:/Program Files/nxclient/bin/unstsvc.bat'.
- Delete 'C:/Program Files/nxclient' folder.

Silent install

Some people want to install NxClient on multiple PCs using GPO or PDQ deployment. For this, we have the silent install option for NxClient.

For silent install,

/silent : Runs the installer in silent mode (The progress window is displayed).
/verysilent : Very silent mode. No windows are displayed.

And you can specify 'Server IP' and 'Login Token',


This is the final form of the command.

    nxclient-6.0-win.exe /verysilent /server= /token=2P1WQ6VF

* You can build your own MSI package using MSI wrapper from http://www.exemsi.com.

* When you install Java silently as a prerequisite for NxClient it might not be starting. This is mostly because you don't have 'PATH' environment variable for Java.

- Go index -
NxUpdate and dynamic IP update
When you have a client system using dynamic IP address and you want to associate its IP address to a specific user, try NxUpdate on the system. It will create and refresh an IP based login session on NxFilter for an associated user.

* It sends START, STOP and IPUPDATE signals.

* When you enable dynamic DNS service on NxFilter you can use NxUpdate as its dynamic DNS client.

Writing your own NxUpdate

We use HTTP protocol for the communication between NxFilter and NxUpdate.

You can send an IP update signal using the following URL,

'GKSYEJYG' is a login token of a user and 'ipupdate.signal.nxfilter.org' is the special domain for 'IPUPDATE' signal. '' is the IP address of your NxFilter.

We use the signals below.

- start.signal.nxfilter.org : 'START' signal.
- stop.signal.nxfilter.org : 'STOP' signal.
- ipupdate.signal.nxfilter.org : 'IPUPDATE' signal.

* You need to add a login token of a user to these signals for user identification.

When we send these signals we can get two kinds of responses from NxFilter.

- : Error.
- : Success.

You don't need to send 'START' or 'STOP' signal if you want to go simple. Sending 'IPUPDATE' would be enough.

* We send 'IPUPDATE' signal every 15 seconds as the client IP address can be changed. But we write its log on server side once in 5 minutes to reduce the size of traffic DB.

- Go index -
Application control with NxClient
NxFilter supports application control with NxClient. You can block unwanted programs by setting up your application control policy on NxFilter GUI and you can find out who tried to run the blocked programs on your log view.

How it works

After you define your application control policy on 'Policy > Application Control', NxClient retrieves the policy periodically.

* You can adjust the policy update period by changing the value for 'Config > Setup > Agent Policy Update Period'.

Supported options

1. Block by port scanning
NxClient detects UltraSurf and Tor processes by port scanning. This means even if your users change the process name or run them from a USB stick you can find and block them.

2. Block by process name
You can block a process running by its name. This works based on keyword matching against process name. When you add blocked keywords on GUI and NxClient finds the matching process name, it will kill the process.

Enable application control only for specific users

Basically the application control of NxFilter supposed to be a global policy. But you can disable it on policy level by using 'Disable Application Control' option on a policy.

Logging blocked application

NxFilter is basically a DNS filter, And its log data format was designed for showing allowed/blocked DNS request. To accommodate the log data about a blocked application, NxFilter introduced these special domains and rules.

- ultrasurf.port.app : UltraSurf has been blocked by port scanning.
- tor.port.app : Tor has been blocked by port scanning.
- chrome.exe.pname.app : Chrome has been blocked by its process name.

* When you enable 'Block UltraSurf' and there is UltraSurf extension for Chrome or other extensions having proxy permission installed on Chrome, NxClient kills Chrome process and sends 'ultrasurf.chrome.app' signal.

Execution Interval

Finding and blocking application may cause some amount of CPU load. If you don't want to cause too much load for your client PC, increase the value for 'Execution Interval' on 'Policy > Application Control'.

- Go index -
Remote filtering with NxClient
NxClient has a local web proxy module for HTTP protocol level filtering.

How it works

Firstly, define your remote filtering policy on 'Policy > Remote Filtering'. After NxClient started on user system, it will filter HTTP traffic by setting up itself as a local proxy server. NxClient retrieves its policy periodically by 'Agent Policy Update Period' on 'Config > Setup'.

Supported options

1. Block HTTPS
You can block all the HTTPS traffic if you want.

2. Block IP Host
Blocking HTTP requests with IP host in URL.

3. Block Other Browser
NxFilter's remote filtering is being activated through the system proxy settings. Internet Explorer and Chrome are using the system proxy already and many other applications are also using the system proxy. But there are some applications trying to make a direct connection to the Internet and resulting in bypassing filtering. With this option enabled, NxClient will block any program making direct HTTP connection to the Internet.

* Currently, remote filtering supports Internet Explorer, Chrome, Firefox.

* You can allow direct HTTP access to some application using 'Excluded keywords' on 'Policy > Application Control'. Basically it is for application control, but it also bypasses 'Other Browser'.

4. Blocked Keyword in URL
Keyword filtering against URL.

5. IE Proxy Bypass
NxClient bypasses the domains you have on 'Whitelist > Domain' with 'Bypass Filtering' option. But it will be only applied on HTTP protocol on Windows. When you need to bypass other protocols than HTTP or the sites using other ports than TCP/80, add those sites here. They will be appended to the system proxy bypass list on Windows.

6. Query Cache TTL
NxClient keeps its query result for allowing/blocking a domain for 60 seconds at default for faster browsing. But if you are on a slow connection, you could have some slowness in your browsing. In that case, it might be a help to increase this value.

* When you increase the value for 'Query Cache TTL', keep in mind that your policy change will be reflected after the cache expires.

Enable remote filtering only for specific users

Remote filtering of NxFilter works globally. But you can disable it on policy level by using 'Disable Remote Filtering' option on a policy.


You only get domain level log data as we are working on a DNS filter. But you will see a detailed block reason on the block-page as below.

Domain: www.google.com
Reason: Blocked by proxy, url_kw=game

- Go index -
NxForward to show block-page on HTTPS
When you are blocked on HTTPS protocol you get an SSL warning instead of your block-page. This is natural as your browser tries to protect you from 'Man in the Middle' attack. But it is annoying anyway as we know it is blocked by our filtering policy. We have a solution for Chrome browser. When you install NxForward which is a Chrome extension, it will bypass the SSL warning on Chrome browser.

You can install NxForward from Chrome Web Store. Download it from the following link.

- Download NxForward from Chrome Web Store

* You might think that it is dangerous to hide this kind of security warning. But NxForward doesn't hide every SSL warning. It only happens when NxFilter actually blocks an HTTPS website.

- Go index -
What is NxCloud?
NxCloud is a fully rebrandable multi-tenancy cloud based DNS filter software. It is developed based on NxFilter and inheriting most of the features of NxFilter. Plus, we added many new features only available on NxCloud to satisfy cloud business providers. You can build your own cloud filtering service with NxCloud.

These are the key features only available on NxCloud.

Multi-level admin

If you want to build your own cloud service, one of the essential factors would be being able to create accounts for your customers and your customers need to be able to set up their own policy on their own GUI.

On NxCloud there are 3 kinds of users.

Admin > Operator > User

'Admin' is the administrator of NxCloud or the account for yourself. It has almost the same GUI as NxFilter but being an administrator you can create operator accounts. These operator accounts are for your customers and they are something like sub-admin accounts on NxCloud. They can create and manage their own users and policies.

* For easier management of operators, you can access any operator account with 'Magic Password'. At default it is 'magic1023'.

Creating an operator

To create an operator you need to login to NxCloud GUI with admin permission. On 'Operator' menu you can create an operator. When you create an operator NxCloud creates a default user and a default policy for the operator with the same name.

You can change the maximum number of users and policies an operator can create. This means you can have several levels of your service based on the permission for an operator.

Operator GUI

On NxCloud, each operator has their own GUI. If you login to NxCloud GUI with an operator account you will be on the operator mode GUI. It is a bit more restrictive compared to the admin GUI as you only can manipulate the operator specific parameters.

Operator and user

Operators can create their users and apply policies based on user authentication. Users can be authenticated based on IP address or using some agents.

Operator specific dashboard and report

Each operator has their own dashboard and report.

Operator specific free-time

Each operator can set up their own free-time and work-time policies.

Operator specific whitelist and blacklist

Your operators can have their own whitelist/blacklist based on domain name. But you still have a global whitelist/blacklist on your admin GUI.

Operator specific alert email

NxCloud sends an alert email about the recent blocking incidents to each operator. Operators can set up their own email addresses to receive the email and define alert period on their GUI.

* You need to set up a global alert email first to send an operator specific alert email. You can set it up on 'Config > Alert'.

Operator specific block-page

Each operator can have their own block-page. If there is no block-page defined by operator, NxCloud will show the default block-page by admin.

Authentication over cloud

NxCloud supports IP based authentication against users behind a router with NxRelay. This means that you can apply different policies based on IP or IP range and you also can find out the exact number of users behind a router. With NxRelay, you also can implement Active Directory integration over cloud. If you need a simpler solution to apply a different policy for single user, you can go with NxClient.

Dynamic IP updater

Many of your clients will be using your DNS filtering service from a dynamic IP address. You need a dynamic IP updater. We have NxUpdate for that.

Dynamic DNS association

Some of your clients may have dynamic domains for their network. You can associate a domain to a user on NxCloud instead of using NxUpdate.

Rebranding or customization of GUI

Its GUI layer is designed for easy customization. The GUI layer is separated from its core part. You just need to modify all the JSP pages in '/nxcloud/webapps' directory. These JSP files have a naming rule corresponding to NxCloud GUI menu structure. So it is easy to find which file you need to modify.

- Go index -
Install NxCloud
NxCloud is basically a modified NxFilter. You can install and run NxCloud in the same way as NxFilter. But unlike NxFilter, after you install it, you can't use it as your DNS server right away. This is because NxCloud is a multi-tenancy program for commercial service. You are not supposed to use it for your internal network. Your clients or customers use it for their network. So you need to create an account for your client first.

On NxCloud there are 3 kinds of users.

Admin > Operator > User

'Admin' is you and an operator is your customer and a user is the user in your client's network. An admin manages operator accounts and an operator manages the end users and policies. So you need to create an operator first. To create an operator, login to NxCloud GUI as admin and then go to 'Operator' menu. You can create an operator there.

After you create an operator, there will be a default user and default policy for the operator with the same name as the operator. And the default password for the operator is also the name of the operator. Once you create an operator, you can login to an operator GUI using the operator account to set up a user for testing.

* You need to associate your IP address to the default user of your first operator to test it.

- Go index -
Differences from running NxFilter
1. Authentication enabled always
You don't want to make your service available to everybody for free. You want to service it to your paid customers only. So the authentication is enabled by default.

2. Login redirection disabled at default
You still can use password based login with NxCloud but if you use that on a public network you can be a target of DDOS attack. It is better to disable it on a public network. When you disable it, NxCloud silently drops a DNS request from an unknown source IP address.

3. Magic password for accessing operator GUI
As an administrator of NxCloud, sometimes you would need to access an operator GUI for technical support purpose. For that reason, NxCloud has one more password for admin. It is called 'Magic Password'. With this password, you can access any operator's GUI. The default magic password is 'magic1023' and you can change it on 'Config > Admin'.

- Go index -
Business account and home account
When you build a cloud based filtering service, one of the problems you have is to find out the exact number of users behind a router. It may be possible when there is some kind of agent installed and running behind a router and NxCloud supports several agents for that. However, many of your customers don't need to differentiate users and they just want to have one global policy for everybody. It means you don't know how many users they have.

To solve this problem, we limit the request count for a user. Currently one user can make 3,000 requests a day. This is more than enough considering a user makes under 1,000 requests a day according to our statistics so far. However, we may have another issue from this request count limit approach. If you have a customer using your service in their home they probably have several Internet accessing devices and have several family members but not wanting to pay for multiple users. In that case this 3,000 daily request limit is too small for them.

To address this 'Home User' issue, we introduced the concept of operator type. There are 2 kinds of operator types on NxCloud. One is 'Business' and the other is 'Home'. Business type operators are nothing special. They can create as many users as they want and each of the users has 3,000 request limit. But if they are home type operators, they can create up to 5 users only while they have 12,000 extra request count. This means their first user has 15,000 request count limit. Normally, they don't need to create additional users as the number is enough to cover their family needs.

* On NxCloud, you can adjust the amount of requests your operator can make by setting up 'Max User' value for an operator. When an operator gets 'Too many requests' error, you wil be notified by an email and you can reset their request counting on operator edit page.

- Go index -
Writing your own billing system for NxCloud
When you service NxCloud commercially, you want to have an automated billing system. Since its GUI layer is exposed as JSP pages, it is not that difficult for you to build your own builling system with NxCloud.

To build your own billing system, you need to be able to create, edit an operator which is your client account on your service. You should be able to do these actions on your custom JSP pages. Suppose that you need to create an operator with these properties.

- Name : triton
- Password : triton1234
- Email : tmail0487@yahoo.com
- Max user : 3
- Max user IP : 3
- Max policy : 3
- Max whitelist : 20
- Max free-time : 10

The JSP code would look like below.

OperatorData data = new OperatorData();
data.name = ”triton”;
data.passwd = ”triton1234”;
data.email = ”tmail0487@yahoo.com”;
data.maxUser = 3;
data.maxUserIp = 3;
data.maxPolicy = 3;
data.maxWhitelist = 20;
data.maxFreeTime = 10;

OperatorDao dao = new OperatorDao();

If you need to update the properties of an operator,

OperatorDao dao = new OperatorDao();

OperatorData data = dao.selectOneByName(”triton”);
data.maxUser = 5;
data.maxUserIp = 5;
data.maxPolicy = 5;

If you need to suspend an operator,

OperatorDao dao = new OperatorDao();

OperatorData data = dao.selectOneByName(”triton”);
data.stopFlag = true;

* There is a separated section for GUI customization on this tutorial and we also provide Javadoc for building your own custom GUI.

- Go index -
NxRelay to differentiate users behind a router
NxRelay is a relaying DNS server for NxCloud. With NxRelay you can associate a private IP or IP range to a user on NxCloud This means that you can apply different filtering policies based on private IP and IP range behind a router from your cloud filter service.

* NxFilter also supports NxRelay as of v4.2.3.
How it works

NxRelay itself is a forwarding DNS server. It does filtering by querying NxCloud and it works as a DNS server by forwarding DNS queries to your local DNS server. For NxRelay, NxCloud is not its upstream DNS server. Rather, it's a policy server. Its upstream server is your existing DNS server or MS DNS server if you are on Active Directory. This means that even if you lose the connection to NxCloud, your network will not have a DNS failure. And you will not have an issue with Active Directory integration as all the Active Directory DNS queries will be resolved by your MS DNS server.

* It sends 'START' and 'PING' signals. You can verify if it works on 'Logging > Signal' on NxCloud GUI.

Install it on Windows as a Windows service

* As of v2.4, we offer a Windows installer and setup GUI for NxRelay. You can install it as a service with the installer and you can change its config parameters on the setup GUI. When you install it using the installer, it will be installed into 'C:\Program Files\nxrelay'

When you install NxRelay service on Windows manually,

1. Download its zip package.

2. Extract it into 'c:/nxrelay'.


cd c:/nxrelay/bin
net start NxRelay

* Before you start it, you need to modify its config parameters in 'c:/nxrelay/conf/cfg.properties'.

Install it on Linux as a Systemd service

1. Download its zip package.

2. Extract it into '/opt/nxrelay'.

On command line,

cd /opt/nxrelay
sudo chmod +x bin/*.sh
sudo cp script/nxrelay.service /lib/systemd/system/nxrelay.service
sudo systemctl enable nxrelay.service
sudo systemctl start nxrelay.service

To stop it,

sudo systemctl stop nxrelay.service

* Before you start it, you need to modify its config parameters in '/opt/nxrelay/conf/cfg.properties'.

How to set it up

You need one of your NxCloud server IP and a login token from one of your user accounts. It has all of its config parameters in '/opt/nxrelay/conf/cfg.properties'.

For example,

server =
token = BSYEB28O
local_dns =,
local_domain = mydomain.local

When you have these config values in the config file, your NxCloud server IP is '' and the login token is 'BSYEB28O' and your local DNS server or existing DNS server is '' and ''. If you have some domains to bypass from filtering you can add them as a comma separated value of 'local_domain'.

After you modify the config file, restart NxRelay. And then make them as the only DNS server for your network.

* You can add multiple NxCloud server IP addresses separated by commas.

* You can verify your config values and the connectivity by running '/opt/nxrelay/bin/test.sh'.

Config parameters

NxRelay support these parameters on '/opt/nxrelay/conf/cfg.properties',

- server : Your cloud filtering server that is NxCloud or NxFilter.

- token : Login token of a user from your filtering server.

- local_dns : Your local DNS server or Active Directory DNS server doing actual DNS resolving.

- local_domain : Domains to be bypassed to your local DNS server. You can add multiple domains separated by commas.

- listen_ip : When you have a port collision on UDP/53, use this parameter to listen on a specific IP address.

- run_mapper : NxRelay has an integrated NxMapper modul to send Active Directory login username when you install it on a domain controller.

Which policy to apply

When you run NxRelay as the DNS server for your network it starts filtering with the policy associated to the login token you set up in the config file. But that is just a default policy for NxRelay. You can apply a different policy based on IP addresses. On NxCloud's operator GUI, create a user and associate a private IP address or IP range in your network to the user. Now the users on the associated IP address or IP address range will be under the policy of the user you created on NxCloud GUI.

Scripts included

In '/opt/nxrelay/bin' there are several scripts included.

startup.sh - Starting NxRelay.
shutdown.sh - Stopping NxRelay.
test.sh - Test the connectivity to NxCloud.
ping.sh - Test if it is running.

* We have '.bat' versions of these script for Windows.

For Windows,

instsvc.bat - Installing 'NxRelay' service.
unstsvc.bat - Uninstall 'NxRelay' service.

For Ubuntu Linux, we have a Systemd script in '/opt/nxrelay/script',


Active Directory integration over cloud with NxRelay

You can have Active Directory integration over cloud using NxRelay. As of v2.4, when you install NxRelay on a domain controller, it can detect and send Active Directory logged-in username to its server. NxFilter and NxCloud both support Active Directory integration using NxRelay.

* NxRelay is a relaying DNS server which is originally developed for NxCloud to differentiate users behind a router based on private IP.

These are the conditions to impelment Active Directory integration over cloud.

1. Install NxRelay on a domain controller.
In order for NxRelay to detect logged-in username, you have to install it on a domain controller. However, you may have a port collision problem with your existing MS DNS on your domain controller. In that case, you can add one more IP address on your server and bind your MS DNS server to one IP address and NxRelay to the other IP address.

2. Use your Active Directory DNS server as your local DNS server.
In Active Directory, DNS is playing a very important role. Not to break anything with your Active Directory integration, you should use your MS DNS server as the 'Local DNS' or resolving DNS server of NxRelay and bypass your Active Directory domain as 'Local Domain' of NxRelay.

3. Import users and groups from Active Directory over cloud.
Like a locally installed NxFilter, you need to import users and groups to your NxFilter server. Since your NxFilter resides on cloud, you need to open a TCP port to your Active Directory domain controller for LDAP importation.

* You need to open TCP/389 for LDAP importation normally but you can change the port on Active Directory setup page on NxFilter.

You can have Active Directory integration over cloud on full scale using NxRelay in conjunction with NxFilter but when you do it with NxCloud, the result would be a bit different. On NxCloud, we don't support user importation from Active Directory. So it's not a full scale Active Directory integration yet. It still shows Active Directory username in the form of 'tokenname_username' on your log-view so that you can find out who is who. But you have to create a user by yourself if you want to apply a policy based on an Active Directory username.

For example, if you have 'john100' user on your Active Directory and you installed NxRelay with the login token of 'myrelay' user on your NxCloud operator GUI. You will see the DNS request log from 'john100' under 'myrelay_john100' username. But if you want to apply a different policy to 'john100' user, you need to create 'john100' user on your NxCloud operator GUI.

* On NxCloud, user detection by Active Directory logged-in username comes before user detection by IP association.

- Go index -
Before you customize NxFilter
* If you want to customize or rebrand NxFilter for your business purpose, use NxFilter v4 or NxCloud.

Now, we will talk about how to customize or rebrand NxFilter and its client softwares with your own brand. Firstly, we will show you how to customize its GUI. And then we will talk about the other parts you might be interested in. Lastly, we will show you how to rebrand the client softwares of NxFilter.

- Go index -
GUI - Directory structure and naming rule
The GUI layer of NxFilter was designed for easy customization. It is completely separated from its core part. And it has a naming convention corresponding to its menu structure so that you can find the file you need to modify easily. For example, if you want to modify 'Policy > Free Time' on NxFilter menu the file you need to edit is '/nxfilter/webapps/policy,free_time.jsp'.

* In NxCloud's case, it has operator specific menu. If a JSP file is for operator specific menu then it has 'zop' prefix.

    ex) zop,policy,free_time.jsp

Structure of web application directory

We put all the JSP pages into '/nxfilter/webapps' and we don't use any subdirectory for keeping JSP pages. This is for simplicity and easy understanding. Everything you need to modify is in '/nxfilter/webapps' directory. It has the following structure.

- error
- example
- img
- include
- lib

In 'webapps/error' directory, we have the error pages for HTTP error codes. If you want to have an error page for a specific HTTP error code you can define it on '/webapps/WEB-INF/web.xml'.

* We use HTTP 404 error for special purpose. You shouldn't define any error page for HTTP 404 error.

In 'webapps/example' directory, we have some example JSP pages for custom login module.

In 'webapps/img', we keep the image files for webpages.

In 'webapps/include', we have common JSP files to be included into the other JSP files. These are for library functions and navigation menus and initialization code for JSP pages.

* '/include/lib.jsp' is a common library file for all JSP files. It has some utility functions for web development and it executes the initialization code for JSP pages and does authentication checking as well.

* We don't include '/include/lib.jsp' directly. It is being included when we include '/include/top.jsp'.

In 'webapps/lib', we have CSS and javascript files.

We have 'WEB-INF' since we use an embedded Tomcat as NxFilter's built-in webserver.

Separating your customized GUI into another directory

When you customize NxFilter GUI, it is not a good idea to modify the original files directly. It would be better to keep it for future reference and create another directory and copy all the files inside '/nxfilter/webapps' into the new directory and then modify these copied files. To make things easier, NxFilter supports 'www_dir' option on '/nxfilter/conf/cfg.properties' file.

When you have your own custom GUI in '/nxfilter/myweb' directory and you want to use it as the root directory of NxFilter's webserver, you need to add the following line into your 'cfg.properties' file.

    www_dir = myweb

Then restart your NxFilter.

- Go index -
GUI - Using Dao and Data classes
In typical web programming, dealing with DB is almost everything. We are using 'Data Access Object' and 'Data Object' for manipulating DB.
Common methods for a data access object

We have some common methods for most data access object classes. For example, on 'policy,policy.jsp' we use PolicyDao and PolicyData class for manipulating policies. PolicyDao has these methods.

public int selectCount() : The number of policies.
public List selectList() : Fetching policies as a list.
public PolicyData selectOne(int id) : Fetching one policy by ID column.
public boolean insert(PolicyData data) : Insert a new policy.
public boolean update(PolicyData data) : Update a existing policy.
public boolean delete(int id) : Delete a policy by ID column.

Every policy data has its own unique ID which is a number and we use this ID for finding, updating a policy data.

Insert, delete, update, select data

If we want to modify 'whitelist,domain.jsp', we have to use WhitelistDomainDao and WhitelistData classes.

To insert a new data,

WhitelistDomainDao dao = new WhitelistDomainDao();

WhitelistData data = new WhitelistData();
data.domain = "*.nxfilter.org";
data.bypassAuth = true;
data.bypassFilter = true;


To delete a data when its ID is 12,

WhitelistDomainDao dao = new WhitelistDomainDao();

To select a data when its ID is 12,

WhitelistDomainDao dao = new WhitelistDomainDao();
WhitelistData data = dao.selectOne(12);

And to update the selected data,

data.bypassFilter = false;

Lastly, to list data.

WhitelistDomainDao dao = new WhitelistDomainDao();
List dataList = dao.selectList();
for(WhitelistData data : dataList){
    out.println(data.domain + "<br>");

Accessing data field

Many Java developers are using 'get' and 'set' accessors for encapsulation and for having some additional data processing like validation. But for simplicity, we use a public field directly in most cases. For example, you get an instance of UserData and uses its 'name' property like the code below,

UserData data = new UserDao().selectOne(1);

However, there are some data classes having methods starting with 'get'. These methods are mostly about formatting. We have 'ctime' property for RequestData which we use on 'Logging > Request'. If you use it directly you get '201507081415' but when you use its 'getCtime()' method you get '07/08 14:14'.

- Go index -
GUI - Javadoc for Dao and Data classes
We have Javadoc for 'dao' and 'data' packages.

- Go index -
OEM properties
We support 'oem.properties' file for NxFilter to accomodate some business specific requirements. If you have 'oem.properties' file into '/nxfilter/conf' with the follwing value,

appname = MyFilter

1. NxFilter adds 'MYFILTER' prefix to its Syslog message.

2. When NxFilter sends an alert email, it adds 'MyFilter' as the prefix of the subject.

* When you define 'appname' in 'oem.properties', NxFilter doesn't send update notification emails anymore. This is because you might have your own version system for your modified NxFilter.

- Go index -
Templates for email and block-page
NxFilter sends alert emails to its administrator. Mostly it is about access violation for the blocked sites but there are emails about a clustering node failure or a license violation. We have two email templates for these alert emails.

- /nxfilter/conf/tpl/access_violation.ftl
- /nxfilter/conf/tpl/alert_email.ftl

In '/nxfilter/conf/tpl' directory, you also can find the templates for block-page, login-page and welcome-page. These templates are being used when you first install NxFilter to populate its DB or when you click 'RESTORE-DEFAULT' button on 'Config > Block Page' on NxFilter GUI.

- Go index -
Other things you may be interested in
You might want to replace or remove our 'readme.txt' and 'license.txt' with your own files. You can do that but you still need to keep our 'license.txt' file somewhere. We keep all the third party licenses in 'third-party-license.txt' and you also can add our license into that file. About our 'readme.txt', you can remove it or replace it with your own.

There are links to our online tutorial in '/nxfilter/tutorial.html' and '/nxfilter/bin/tutorial.bat'. You can remove files when you make your own package for your customized NxFilter.

The other thing you would need to think about would be icon files. There are two icon files. One for Windows program icon and the other one is for favicon of its admin webpage. You can remove '/nxfilter/nxd.ico' and '/nxfilter/webapps/favicon.ico' or replace them with your own icon files.

* You should not remove our license file or any third party license.

- Go index -
Making your own install packages for client softwares
You can make your own packages for our client programs that are NxClient, NxUpdate, NxMapper, NxLogon, etc.

For NxLogon, since it is a simple Windows console application without installer you just need to replace several files from the original zip file and make your own zip file for them. You can change its name as well. When you change its name you also need to change the contents of the included batch files but these are all straight forward.

However, it is a bit different for NxClient and NxUpdate, NxMapper as these softwares require you to make your own installers.

Making your own Windows installer

In our case, we use Inno Setup from http://www.jrsoftware.org to build Windows installers. When you install NxClient, NxUpdate and NxMapper, they will create their own directories inside 'C:\Program Files (x86)' and register them as Windows services. For example, when you run NxClient installer, we copy all the required files into 'C:/Program Files (x86)/nxclient' and then we run 'bin/instsvc.bat' under the installation directory to register it as a Windows service and then we run 'bin/setup.bat' at the end of the installation process to run its setup program.

* The zip files we use to build our installer packages are on our older package download page.

* When you uninstall them, run 'bin/unstsvc.bat' to unregister them from Windows service list.

Changing application name

When you customize our client programs, one of the things you want to do might be changing the names of the client programs on their setup GUI. We have 'conf/appname' file for that purpose under the installation directory. When you change the name inside the file, the new name will be appeared on the setup program.

Replacing icon file and default setup value

When you want to use your own icon, the icon file is 'nxd.ico' inside the installation directory and it is a merged icon file for 16x16 and 32x32 and 48x48 icons. At the moment it is only for Windows Installer and setup program.

* For Java version NxClient, you need to add one more icon file which is 'nxd16.png'. It's 16x16 PNG file for its setup GUI.

One of the other things you might want to do is to change the default connection values to the server. You can change the default values for 'Server IP' and 'Login Token' on the setup program by modifying 'conf/cfg.default' file.

* 'conf/cfg.default' file will be copied into 'conf/cfg.properties' file when you run the setup program first time or during the installation process.


Building your own installers and changing the names of the client softwares will do what you want mostly. But there is something you can't touch or change. We have some internal code having 'nxfilter' signature. This is important as we need to have a unique signature to diffrentiate signals from our agents.

And you shouldn't remove our license or any third party license from the package. Otherwise that is a license violation. You can have your own license file but you need to keep our license somewhere.

- Go index -
What is NxClassifier
NxClassifier is the NxFilter's integrated auto-classification engine for Jahaslist. It does dynamic classification against the websites visited by your users based on keyword matching and scoring system. You can define or modify its classification ruleset as you like using your own language.

* NxClassifier requires a valid Jahaslist license.

- Go index -
Why NxClassifier
There are two kinds of classification methods we can use to build a blacklist. One is auto-classification and the other one is human classification. Auto-classification does the job at very fast speed but it is not as accurate as human classification. And human classification costs a lot of money as you need to hire real people. So the best method would be the combination of both or at least having a human verification process for the auto-classification result.

Most of these auto-classification engines do their job based on a keyword matching system with a keyword dictionary or some kind of ruleset. So we need an effective keyword dictionary or ruleset for an auto-classification engine to produce a satisfiable result. But we can have different opinions on which keyword belongs to where and how one keyword important to be compared to the others.

Moreover, we also can have a different opinion on the classification of a site. For example, 'www.stackoverflow.com ' is a community and can be classified into 'Forum' category but also can be classified into 'Computer/Technology' category as they are focusing on computer and technologies. And yet they are one of 'Business/Service' websites. We can classify it into all of them if we allow multi-categories for a site. But in that case, in our filtering business we face another problem. What if we want to block 'Forum' but allowing 'Computer/Technology'? We get an unexpected result.

Another one, at the moment we speak English but it is not the only language we use in the world. There are numerous non-English websites. So we need keyword dictionaries for other languages as well. But who is going to build all these dictionaries for all the other languages? And if we do human classification or verification, we need to hire people being able to speak those languages too. So things are getting bigger and complicated. Nobody can afford it. And that's why we have many false positives for these blacklists and we can't be satisfied with any blacklist 100%.

Lastly, no matter how big it is, a blacklist can't cover the whole Internet. Even if you have a huge file in the effort of trying to cover the whole Internet, how many websites in the file could be useful for you? Your users will never visit most of the websites in it as they are not written in your own language even.

However with NxClassifier,

1. You can build your own ruleset.
This means that you can build your own classification ruleset for your own language. You are the best one for filtering the websites in your own language.

2. We don't allow multi-categorization.
One site can be classified into only one category. No more confusion from multi-categorization.

* The reason for these blacklist providers having multi-categories for one site is not just that they want to reflect real world ambiguity. They want to use it for other markets, something like advertising market. That's why they need to have multi-categorization. But it is no good for us in most cases.

3. You can do recategorization instantly.
No need to make a recategorization request to a blacklist provider and wait for them to accept your request. You can modify your own blacklist as you like.

4. Jahaslist keeps growing.
As of v4.2.2, we ship more than 2 million domains classified with NxFilter package. With the aide of dynamic classification by NxClassifier, it keeps growing.

5. You can share the result with others.
Once you build your own blacklist using NxClassifier you can share it with others. Not only the blacklist. You can share your classification ruleset.

- Go index -
GUI for NxClassifier

We have 'NxClassifier' top menu on GUI. It has the following sub-menus.

Setup > Classifier Setup

- DNS Test Timeout : NxClassifier only classifies the existing domains. So it does DNS testing first when it needs to classify a domain.

- HTTP Connection Timeout : After DNS testing, now it needs to download a webpage to analyze. This is the connection timeout value for HTTP connection.

- HTTP Read Timeout : This is the data read timeout value after you have an HTTP connection.

* If you make these timeout values too big you might have a performance degrading for NxClassifier.

- Classified Data Retention Days : NxClassifier makes the classification result log for recently classified domains. NxClassifier doesn't do the classification against the already classified domains.

- Keep HTML Text : NxClassifier extracts text from the first page of a website and keep it for reclassification. But this requires more disk space so you can decide to keep the text or not.

- Disable Domain Pattern Analyzer : NxFilter has a domain calssification process based on domain patterns. If a domain can be classified by this domain pattern analyzer NxClassifier doesn't try to classify the domain by other methods.

- Disable Classification : You can disable classification if you want.


This is the classification result log by NxClassifier. It will show you the recently classified domains and how they got classified or unclassified. Based on this classification result, you can improve your classification ruleset.

* With 'VIEW' button, you can view the details of the log and with 'TEST' button, you run the actual classification process for a domain with your current ruleset.

* If you want to apply a new classification ruleset against the already classified sites, use 'RECLASSIFY ALL' button.


We exclude the domains making certain errors during the classification process. For example, if we have 403 response from a website we don't need to try to classify it as we can't access the website. Or if we get an image file or some other type of file instead of a text or HTML file we will exclude it.

* Since we don't delete these excluded domains if you want to let NxClassifier try to classify an excluded domain, you would need to delete it from the list first.


You can view the contents of Jahaslist and modify it directly here. But we don't recommend you to do reclassification here unless it is a mass importation of domains. We keep Jahaslist in a separated DB file and NxFilter doesn't do auto-backup for it. So it is better to use 'Category > System' for reclassification as it is being stored into the main config DB.

* When you do reclassification on 'Logging > Request' or 'NxClassifier > Classified', your reclassification data goes into 'Category > System'.

* When you export Jahaslist, NxFilter merges your custom classified domains from 'Category > System' into Jahaslist and then export the merged result into a file.

* When you import or add another Jahaslist, use 'IMPORT' button.

Test Run

After you add your own classification rules, you want to see how effective they are. You can do a test run for your classification ruleset against a website here.

* 'Test Run' doesn't do actual classification. If you want to classify a domain you need to make a DNS query for the domain against NxFilter.

- Go index -
Understanding NxClassifier workflow
You need to understand the workflow of NxClassifier before you can build an effective classification ruleset for you.

NxClassifier itself is a multi-threaded program integrated into NxFilter. When NxFilter finds an unclassified domain requested, it adds the domain into the process queue of NxClassifier. NxClassifier does DNS test to see if the domain actually exists and then it tries to see if there is a website for the domain. If there is a website for the domain, NxClassifier downloads its first page and parses its title, description and the text.

Once NxClassifier gets the details of a website then it runs the data through its classification ruleset. While running through its ruleset, if it finds an exactly matched rule it stops there and classify the domain to the associated category to the rule. Otherwise, it adds up the points from the matching rules and classify the domain into the category which has the biggest score.

- Go index -
What is a classification rule
Now we need to understand how to make a classification rule. A classification rule consists of the following factors.

- Keyword : Matching keyword. In reality, it is a regular expression.

- Target : You can apply your keyword against the domain, title, description and text of a website.

* We get the title, description and text of a website's first page.

- Points : You can set a different points to a rule by its importance. The minimum points to be classified is 100 and the maximum points is 1,000.

- Category : Associated category for a rule.

* When you want to have an 'Exclude Keyword' for a category, set a negative number as the points for the keyword which you want to excelude. For example, you associate 'movie' keyword to 'Entertainment' category but you don't want to classify the websites you can download movies to 'Entertainment'. Then you associate 'download' keyword to 'Entertainment' with a negative number points.

- Go index -
NxFilter as a DNS server
NxFilter is basically a forwarding, caching DNS server with filtering ability. But you also can use it as an authoritative DNS server. And it also supports dynamic DNS service.

- Go index -
Forwarding DNS server
When you install NxFilter first time, it is already ready for working as a forwarding DNS server. It uses Google DNS server as its upstream DNS server at default. You can change it on 'DNS > Setup'.

- Go index -
Caching DNS server
NxFilter has its own cache for the DNS response from its upstream server. This means when you use a public DNS server for your network, NxFilter can boost up your network speed by reducing the traffic to the public DNS server as your client PCs don't need to talk to the public DNS server.

NxFilter also supports 'Persistent Cache' since v4.1.1. It keeps DNS response cache for major websites and frequently queried domains in its database. When NxFilter loses its connection to its upstream server, it uses its persistent cache. With this feature, you will not lose the Internet even if there is a nationwide DNS outage.

- Go index -
Authoritative DNS server
NxFilter can be working as an authoritative DNS server.

1. Zone File
We use the same format of zone file as BIND. You create a zone file for a domain on 'DNS > Zone File'. And then you can add your hosts into the DNS zone by editing it on GUI.

2. To put it on the Internet
Since NxFilter is a DNS filter with authentication, when you use it as an autoritative DNS server there are several things you would need to think about.

- Authentication
You must enable authentication especially when you put NxFilter on the Internet to avoid of being a target of DDOS attack. But the problem is that if you enable authetication, these anonymous users querying your domain will be redirected to the login-page of NxFilter. To allow the anonymous DNS query against your domain, you need to bypass authentication for your domain.

- Filtering
NxFilter is a DNS filter so your domain might be blocked by NxFilter for some reason. This will lead to a failure of resolving the domain you want to service. To avoid of having this kind of problem, you need to bypass filtering for your domain.

- Too many log data
You could have too many log data for your domain as a result of DDOS attack. I might be better to bypass logging for your domain.

* You can set up a whitelist for your domain with some bypass options but you also can do that using the bypass options of a zone file you created on GUI.

3. Clustering
When you build a cluster of NxFilter, your slave nodes will be working as an authoritative DNS server with the settings from the master node. You don't need to set up a secondary DNS server for redundancy. It is already clustered.

- Go index -
Dynamic DNS service
NxFilter supports dynamic DNS. You can build a 'DynDNS' like service with NxFilter if you want.

To service dynamic DNS, you need to set a domain on 'DNS > Dynamic DNS > Dynamic DNS Domain' and then enable the service. If you want to service it publicly or on the Internet, you will have to have an authoritative DNS zone on 'DNS > Zone File' for your dynamic DNS domain.

Once you set up everything on the server side, you need to install a dynamic DNS client on your client system. We use NxUpdate for this. On NxUpdate, you set up a server IP that is the IP address of your NxFilter and a login token associated to a username. The associated username will be the hostname.

For example, if you have 'example.com' as your dynamic DNS domain and you install NxUpdate on a client system with a login token which is associated to 'myhost' user. Then once your NxUpdate starts working you can access the system using 'myhost.example.com'.

* Dynamic DNS service requires to enable authentication on 'Config > Setup'.

* You can view the list of dynamic domains being serviced on 'DNS > Dynamic DNS'.

- Go index -
To avoid of having DDOS attack
When you put NxFilter on the Internet, you might be under DDOS attack. Once you are under DDOS attack or the other kinds of DNS attack you could have a massive traffic to your NxFilter. Your NxFilter can't handle all the traffic and eventually it will look like almost dead and you will get error logs about 'Queue full'.

To avoid of having this kind of problem, the best thing is to hide your DNS server or not responding to these attackers with a valid DNS response. To hide your NxFilter from these attackers, you can enable authentication firstly. NxFilter will respond to the DNS queries from an unauthenticated user or unknown source IP address with its 'Block Rediretion IP'.

However, they still may think that there is a DNS server to attack as they get a response anyway. To hide it from these attackers completely, we need to drop the packets from these anonymous users silently. For this purpose, you can enable 'Disable Login Redirection' on 'Config > Setup' and NxFilter will drop the packets from these attackers.

* On NxCloud, we have 'Enable Login Redirection' on 'Config > Setup'.

- Go index -
Clustering with NxFilter
NxFilter has built-in clustering for load balancing and fail-safe. Once you have a master node you can add up to 4 slave nodes to your cluster. All the slave nodes in your cluster share the setup from their master node. So you can control everything on your master node.

Creating a cluster

To create a cluster, the first thing you need to do is to set up a master node. On 'Config > Cluster', you can make one of your NxFilter installations to be your master node. And then you can add the other NxFilter installations as the slave nodes to your mater node. You need to restart NxFilter after change your cluster setup.

* Clustering requires TCP/19002, TCP/19003, TCP/19004 ports opened on the master node.

* On some Linux systems, you need to add an entry for your master node IP on '/etc/hosts' file of your master node. Otherwise, your slave might not be able to connect to your master node.

Starting clustered NxFilter

When you start NxFilter cluster, start your master node first and then your slave nodes. This is because your slave nodes need to download the initial setup from their master node when they start.

Load balancing and fail-safe

One good thing about a DNS filter is that there is already a way of load balancing and fail-safe existing. Make your master node to be the primary DNS server and your slave node to be the secondary DNS server in your network. Then you have load balancing and fail-safe.

* If you want to have load balancing and fail-safe for your block-page and login-page or policy update for NxFilter's agents, you need to set multiple block redirection IP addresses separated by commas on 'Config > Setup'.

When a cluster node down

When a slave node down, the other nodes will not be affected. When your master node down, you still don't lose your filtering unless you restart your slave node before you restore the master node. But there are several things need to be aware of.

* If you set up the alert email on 'Config > Alert', you will receive an email when a cluster node down.

1. Login redirection will not be working
When your master node down, we can't share the login session between cluster nodes. This means your login-page will not be working correctly. So we don't redirect users to the login-page.

2. Unauthenticated users will be bypassed
If we don't redirect 'Password Users' to the login-page they can't login. But we don't want to let them lose the Internet. So we bypass filtering for these unauthenticated users when your master node down. If you don't want to bypass filtering for any users even if your master node down try to have a default user covering whole IP range of your network.

* NxCloud's case is a bit different. It drops the requests from unauthenticated users as login redirection is not a default option for NxCloud and the users on NxCloud mostly use other authentication methods.

3. Multiple server IP addresses with an agent
If you use our agent programs with multiple server IP addresses for fail-safe, they will still be working.

Access control for slave nodes

If you add all your slave node IP addresses into 'Config > Cluster', any attempt to join a slave node from an unknown source IP address will be blocked.

Monitoring slave node state

You can view connection state of your slave nodes on 'Config > Cluster'. Once you set up your cluster then your slave nodes will be appeared with the last contact time on the page. It is also showing each node's request, block, user, client-ip count information. These counter information will be set to 0 on midnight or when you restart NxFilter.

Session sharing between cluster nodes

We share data between cluster nodes. For example, we share login session so that you don't need to login twice to master and slave node. And we share quota-time and bandwidth consumption data as well. But this could be a reason for performance degrading when you have busy servers as it increases the amount of communication between nodes.

If you don't want to share these data, you can disable authentication and not to use quota-time and bandwidth control. But you may want to have authentication even if you need to login twice. And in reality, this login session sharing is only for the login-page. If you don't use password login, you are not going to have any problem. NxLogon and NxMapper, NxClient can talk to multiple NxFilter servers. And IP based authentication works fine without session sharing.

To disable session sharing while you keeping authentication enabled, add this line into '/nxfilter/conf/cfg.properties'.

    no_share_session = 1

* You need to set up 'no_share_session' option on all nodes.

- Go index -
Bandwidth control with NxFilter
NxFilter supports per-user based bandwidth control by utilizing NetFlow data from a router. The idea is simple. NxFilter associates NetFlow data to user login IP address and if there is a user consumed up bandwidth over the limit you set on a policy, NxFilter blocks all the DNS requests from the user.

Good thing is that this is not just about HTTP traffic. Since NxFilter uses NetFlow data, you can monitor and block HTTP, FTP, IM, Skype, Torrent and any other protocol working on TCP/UDP.

To enable bandwidth control, you need to have a router or firewall supporting NetFlow version 5 in your network and you need to make them sending NetFlow data to NxFilter. And then run NxFilter's built-in NetFlow collector on 'Config > Setup > NetFlow'. After that, you can set up a bandwidth limit on a policy.

There are several rules for NxFilter to import NetFlow data. Firstly, either the source or destination IP address of a NetFlow data should be associated to an IP address of a logged-in user on NxFilter. Secondly, NxFilter ignores internal traffic. This means either the source or destination IP address needs to be a public IP address. This is because you are only interested in inboud or outbound traffic to the Internet. And lastly, NxFilter keeps only TCP/UDP data.

* Currently, NxFilter supports NetFlow v5 only.

- Go index -
Detecting and preventing malware/botnet activity with NxFilter
One of the features of NxFilter is to be able to detect and block malware/botnet activity by analyzing DNS packets. In reality, malwares and botnets are another form of network client or server programs. They are also heavily relying on DNS protocol to find their masters or peers to communicate with or the victims to attack.

For example, if you have a spambot in your network, the spambot will make a lot of DNS queries for MX records of their target domains to send emails. But normally, your client PC doesn't need to make MX queries unless they have a mail server running on it.

Another example would be the botnets using 'TXT' record or other DNS records as their communication tool. These are real world examples of malwares using DNS protocol as their communication tool.

ex1) Trojan.Spachanel was using SPF record.
ex2) W32.Morto was using TXT record.

The other method we can think of would be detecting the domains abnormaly long. When we tested top 100,000 domains by Alexa all the domains except 142 domains were shorter than 30 characters. But there are abnormal domains trying to look like an URL of a target website. This is an example from www.phishtank.com which is trying to look like a webpage of www.ebay.co.uk but actually it is a phishing domain.

ex1) cgi.ebay.co.uk-item-css.ebay-motors.session.id-sj3mzbasf3k12z581668115.login-wpadmin-sw.buyitnow.sign-in.secure-process657943sddh53zix34235hj65rj.xml.config-page.overview.buyer-protection-jsp.wpcs.spiridus-magic.org

So detecting botnet/malware by analyzing DNS packet could be an effective technique we can think of. NxFilter provides these blocking options on its policy setup.

- Max Domain Length
- Block Covert Channel
- Block Mailer Worm
- Allow 'A' Record Only

But you can say that the most effective way of preventing malware/botnet in your network would be allowing only 'A' record and some common types of DNS queries from your client PC. In most cases, your client PC doesn't need to make a DNS query for any other record than 'A', 'AAAA', 'PTR' , 'CNAME'.

- Go index -
Removing embedded adverts in webpages
There are webpages having embedded adverts from other domains. One of the problems for blocking these adverts with NxFilter would be having a mangled webpage as a result of blocking. Your block-page replaces the embedded adverts.

To avoid of having this kind of problem, there are two ways of removing embedded adverts with NxFilter. One is to block it using 'Ad-remove' option on a policy. With this option enabled, NxFilter blocks a domain in 'Ads' category with a blank block-page. The other method is using a special category in 'Category > Custom' that is 'ad-remove'. If you add a domain into the category and block the category somewhere, NxFilter blocks the domain with a blank block-page.

* After you add a domain into 'ad-remove' category, you need to block the category on a policy or block the domain somewhere otherwise it will not be blocked.

- Go index -
Performance tuning guide
Although NxFilter is designed to handle several thousands users easily there are several factors you can adjust to get the best performance from NxFilter.

Memory size

At default, NxFilter uses up to 768 MB RAM. This is enough for most users. But if you allocate a bigger memory to NxFilter you can expect a better performance. In NxFilter startup scripts, '/nxfilter/bin/startup.sh' or 'c:/nxfilter/bin/startup.bat' you have a start option like below,

    java -Djava.net.preferIPv4Stack=true -Xmx768m

If you want to increase it to 2 GB then change '-Xmx768m' to '-Xmx2048m'.

* If you have enough memory for NxFilter, you might want to use '-server' option for starting Java. It requires more memory but you will get a better performance.

* When you run NxFilter older than v4.1.8 as a Windows service, you need to modify 'c:/nxfilter/bin/instsvc.bat' and unregister/register its service using 'unstsvc.bat' and 'instsvc.bat'.

Disk space and reducing the amount of log data

NxFilter has various reporting features. You can view all the logging data and daily, weekly report and per-user report. However, this kind of reporting consumes a lot of disk space. When you have a bigger size of reporting data your system may experience a performance degrading.

If you have more than several hundred users, it might be better to have at least 10 GB of disk space for traffic DB. Or to save the disk space, you can reduce the size of traffic DB. To reduce the size of traffic DB, you can adjust the value for 'Log Retention Days' on 'Config > Setup'.

The other way of reducing the amount of traffic data is to make a whitelist with 'Bypass Logging' option for the domains you are not interested in.

Increase the number of request handlers

NxFilter is a multi-threaded program. It has worker threads processing client DNS requests. The default number of request handler is 8 and it is enough for most cases. But if you think your NxFilter responding slowly, you can try to increase it. To increase it to 16, add the following line into '/nxfilter/conf/cfg.properties' and restart NxFilter.

    rh_num = 16

Disable session data sharing between cluster nodes

When you have a clustered NxFilter group, there is a massive amount of communication between your clustering nodes for data sharing. This could be a performance degrading factor when you have busy servers. To reduce the amount of communication between clustering nodes, read Clustering with NxFilter section on this tutorial.

To avoid of having 'Database Connection Bottleneck'

In NxFilter clustering, a slave node is supposed to use or share the database of its master node. It is because we don't want to have any inconsistency between the configuration of clustering nodes. However, when you have busy servers, you can have too many database connections from your slave nodes to your master node and that may degrade performance of your clustered NxFilter systems.

For main configuration database, we don't have this problem as we load the database into the memory space of each node. But for a blacklist database, you still can have 'Database Connection Bottleneck' problem as we can't keep it in memory space for its huge size. We can tell that this may happen when you have more than 3,000 users.

One solution is to use a cloud based blacklist database as each NxFilter node has its own connection to these cloud based servers and it keeps its own cache for the classification queries. Another solution is to separate database connection to each node. For Jahaslist, we support 'use_local_jahaslist' option on its config file. To enable the option, add the line below into '/nxfilter/conf/cfg.properties' of a slave node and restart it.

    use_local_jahaslist = 1

Now your slave node will use its own local Jahaslist database. There's still a slight possibility of having inconsistency between your cluster nodes but it will be minimal as NxClassifier works with the same ruleset from its master node and it will try to copy the same classification from its master node when it finds an unclassified domain.

* Before you enable 'use_local_jahaslist' option on a slave node, it's better to copy your Jahaslist database from your master node. You can use 'EXPORT' and 'IMPORT' buttons on 'Classifier > Jahaslist' on GUI. Or you can directly copy '/nxfilter/db/jahaslist.h2.db' from your master node. When you copy it directly, you need to stop NxFilter first.

- Go index -
Syslog exportation
NxFilter supports Syslog exportation. The exported data is a character string separated by '|'. For example, if you have a Syslog data like below,

NXFILTER|2013-01-28 10:53:23|Y|www.bbc.co.uk|pwuser||admin|news|Blocked by admin|33|mygrp

It can be parsed into these values,

- Prefix : NXFILTER
- Date : 2013-01-28 10:53:23
- Block yes/no : Y
- Domain : www.bbc.co.uk
- User : pwuser
- Client IP :
- Policy : admin
- Category : news
- Blocked reason : Blocked by admin
- DNS query type : 33
- Group : mygrp

* With NxCloud, you get operator name instead of 'Group'.

* To import Syslog data into Graylog read Separate logging/reporting using Graylog.

* As of v4.2.6, NxCloud sends one more IP that is 'Local IP' from NxRelay at the end of the Syslog exportation string.

- Go index -
Separate logging/reporting using Graylog
When you have more than several thousand users, you might need to separate NxFilter's logging and reporting as it causes heavy load on your system. There are many specialized tools for logging/reporting and we will show you how to use one of them that is Graylog with NxFilter.

1. Download a content pack for Graylog from the link below.
    - nxfilter-graylog-example.zip

2. On Graylog GUI, import the content pack inside the zip file.
    - System > Content Packs > Import content pack

3. After import it, you will see 'NxFilter' content pack appeared.
    - Click 'NxFilter', select 'nxfilter-graylog-example' and apply it.

4. We use UDP/1514 port for Graylog input.

5. On NxFilter GUI, Go to 'Config > Setup > Syslog', change 'Syslog Port' to 1514.
    - And change 'Syslog Host' as well.

6. Restart NxFilter and you will see your dashboard getting populated.
    - Select 'NxFilter 2 hours' dashboard on Graylog GUI.

After you build your own logging/reporting on Graylog, you can bypass logging on NxFilter traffic DB completely. To bypass it, set 'Log Retention Days' on 'Config > Setup' to 0.

- Go index -
Report manager permission
We have a password based authentication to 'Logging' and 'Report' top menus on GUI. You can set this password up on 'Config > Admin > Report Password'. And you can create this kind of link,

When you click the link, you will acquire the permission to view everything under 'Logging' and 'Report' and will be forwarded to 'Report > Daily'

- Go index -
Bypassing Internet Censorship with DNS Over HTTPS
These days, we are getting Internet Censorship everywhere. When you use a public DNS or a DNS server from an ISP company there may be Internet Censorship being done on your DNS requests. There are people even arguing that some of those free Internet filtering services are actually being run by a law enforcement authority and they are tapping out on you. And you want to protect your users from Internet Censorship.

For those of you worrying about Internet Censorship, we added 'DNS Over HTTPS' with v4.2.6 of NxFilter. You can use Cloudflare or Google HTTPS DNS server as your upstream DNS server. And all of your DNS queries will be encrypted by SSL. Nobody can hijack your DNS requests to the Internet.

You can enable 'DNS Over HTTPS' on 'DNS > Setup'. About the options, read GUI - DNS

- Go index -
I can bypass NxFilter by accessing websites using IP address.

There are people saying that DNS filtering is useless as they can access a website using IP address. This is a very naive thought and simply not true. In today's Internet environment, most websites are running on virtual hosts. This means there are multiple websites on one IP address. You can't access these websites without using a domain.

And the other thing you need to think about is that there are many URLs embedded in a webpage. This is especially true when it comes to a big portal site. Those URLs are based on DNS as well. If you try to access a blocked website using an IP address, you will get just a brocken webpage in most cases.

- Go index -

It doesn't get blocked/unblocked right away.

This is most likely from the DNS cache on your system. If you are on a Windows system there are two kinds of DNS caches. One from your browser and another from your Windows OS. Before the cache expires, your policy change for blocking/unblocking will not be working. Both caches expire eventually but you might want to clear them out immediately. If it is a browser cache you can clear it out by restarting your browser.

If you want to clear out your Windows DNS cache, use the following command on CMD.

ipconfig /flushdns

Normally, a DNS cache expires in a day at the maximum. Of course, it depends on TTL from a DNS record but I have not seen it being bigger than 86,400 seconds(1 day) usually. About browser cache, it may take several minutes to get expired. But it will be expired and your filtering policy will be working eventually. So in practice, this is not a problem as you don't need to block/unblock a website many times a day.

- Go index -

How do I force a user to be filtered by NxFilter?

If you have a firewall in your network, it is a simple task. You just need to block outgoing UDP/53, TCP/53 traffic except from NxFilter. And then use DHCP to set up NxFilter to be the DNS server for your network. Now, NxFilter became the only DNS server that your users can use and their DNS setup to point NxFilter will be done automatically.

- Go index -

How NxFilter determin which policy to be applied for a user?

You can assign a policy to a user directly. If a user doesn't have any policy and belongs to a group you can assign a polcy on group level. This is simple so far. But when you import users from Active Directory there might be users belonging to multiple groups. You don't know which policy to be applied to a user in this case.

To solve this problem, we introduced 'Priority Points' on a policy. If there are multiple groups and if they have several different policies, the policy having the highest priority points will be applied. When you want to find out which policy being applied to a user, use 'TEST' button on 'User > User'.

- Go index -

What is the quickest way of blocking 'facebook.com'?

Add '*.facebook.com' on 'Whitelist > Domain' with 'Admin Block' option.

- Go index -

I want to block 'facebook.com' only for my students.

You need to be able to differentiate your students on NxFilter with authentication first. And then block 'Social Networking' category on a policy when you use Jahaslist. Then assign the policy to the user or group associated to your students.

- Go index -

I want to allow sales department to use the Internet freely at lunchtime.

1. Create a user or a group for your sales department.

2. Define a free-time in 'Policy > Free Time' for the lunchtime in your company.

3. Create a policy not blocking anything.

4. Assign the policy as the free-time policy of the user or group.

- Go index -

How do I change NxFilter's webserver port?

You can change HTTP/HTTPS listening ports on NxFilter. However, when you change HTTP port you will lose your block-page redirection. It is because when NxFilter redirects a user on HTTP, there needs to be something waiting for the browser on TCP/80 port.

To change the ports, you need to modify these two parameters on '/nxfilter/conf/cfg.properties' file.

http_port = 80
https_port = 443

After you change the ports, restart NxFilter.

- Go index -

How do I reset admin password?

We have '/nxfilter/bin/reset-pw.sh' script to reset admin password. Once you run the script, the admin name and password will be reset to 'admin'. You need to run the script while NxFilter running.

* There is '/nxfilter/bin/reset-acl.sh' to reset the access restriction to GUI as well.

- Go index -

Can I bind NxFilter to a specific IP address?

You might want to bind NxFilter to a specific IP address to avoid of having port collision problem. You can bind NxFilter to a specific IP address using 'listen_ip' parameter in '/nxfilter/conf/cfg.properties' file. If you set it to '' NxFilter will listen on all the IP addresses of your system but if you set it to a specific IP address, NxFilter will listen on the specified IP address only.

* Even if you bind NxFilter to a specific IP address, you can not run multiple NxFilter on the same machine. This is because NxFilter needs to bind several ports on localhost for internal communication.

- Go index -

How do I bypass my local domain from filtering?

On 'DNS > Setup', You can set your local DNS server and local domain. With this setup, if there are DNS queries for your local domain, NxFilter forwards the queries to your local DNS server and bypass authentication, filtering and logging.

- Go index -

Can I use an exact matching keyword for log search?

You can use square brackets for exact matching on log search.

    ex) [john], []

- Go index -

Why do I need to re-login after lunch break?

Your login session has been expired. If there is no activity(DNS query) from your PC for a certain amount of time your login session expires. You can increase the value for 'Login Session TTL' on 'Config > Setup'.

* If you use single sign-on with Active Directory you can avoid of having this problem.

- Go index -

How do I apply my own SSL certificate?

We use an embedded Tomcat 7.x as the built-in webserver for NxFilter. If you want to apply your own SSL certificate with Tomcat, there are two parameters you need to set in Tomcat config file. One is 'keystoreFile' and the other one is 'keystorePass'. However, we don't have a separated config file for Tomcat. We use '/nxfilter/conf/cfg.properties' file to set these parameters.

keystore_file = conf/myown.keystore
keystore_pass = 123456

* About how to build a keystore file, read Tomcat manual.

- Go index -

How do I enable debugging?

When there is something wrong with NxFilter, the first thing you can do is to find out what is going on exactly with its system log data. NxFilter keeps its system log data inside '/nxfilter/log' directory. If you need more detailed log data, enable debugging on '/nxfilter/conf/log4j.properties'. Change 'INFO' to 'DEBUG' inside the file and restart NxFilter.

- Go index -

How do I hide SSL warning?

* If it's for Chrome browser, we can show your block-page on HTTPS protocol with NxForward. To find out more, read NxForward to show block-page on HTTPS part on this tutorial.

When a browser being redirected on HTTPS, it warns users that they are being redirected. This is for preventing 'Man in the Middle' attack. That is why you get an SSL warning page instead of NxFilter block-page. But many people want to hide the warning message for some reason. While we still can't show the block-page on HTTPS but you can hide it by changing HTTPS port of NxFilter. If you use a non-standard HTTPS port, your users will only see 'Connection Error' message.

To change HTTPS port, modify the following line on '/nxfilter/conf/cfg.properties' file.

https_port = 443

Now, we can hide the SSL warning but there's one problem with this approach. Some users reported that their browsing became slower as their browsers need to wait for the timeout events for some embedded websites. So we introduced one more option that is 'hide_ssl_warning'.

hide_ssl_warning = 1

When you set this option on the '/nxfilter/conf/cfg.properties' file, the timeout will be done immediately.

* If you want to access your admin GUI and login-page using HTTPS protocol while you have 'hide_ssl_warninig' option enabled, you have to change the value of 'https_port' to be a non-standard port. Otherwise, your HTTPS request will be timed out immediately.

- Go index -

I don't see any username on 'Logging > Request'.

The first thing you need to check would be 'Enable Authentication' option on 'Config > Setup'. Some people don't understand that they need to enable authentication before implementing any authentication method.

- Go index -

How to set up a time zone.

Some of our users reported that they have a different time zone on NxFilter from the system. This happens mostly on CentOS. When you need to set up a time zone for NxFilter manually. You can do that on JVM level. On '/nxfilter/bin/startup.sh' set the following parameter.


- Go index -

My Browsers keep restarting after NxClient starting.

NxClient is a local proxy so it needs to update the system proxy settings to redirect HTTP/HTTPS traffic of your browser to itself. And after it updates the proxy settings, it needs to restart your browser to apply the changes. But you might have another Windows program preventing the update or doing the update for itself. You have a race condition here. To fix it, you have to disable one of them.

- Go index -

How do I force a user to logout?

We don't have it on GUI. But in most cases, people want to force a user to logout when they leave their PC and they want to force the next user to login with his/her own username. For this, you can use our logout signal domain that is 'logout.signal.nxfilter.org'. Make a DNS query against it using 'nslookup' and the login session associated with the IP address of the system on which you run 'nslookup' will be deleted.

nslookup logout.signal.nxfilter.org.

- Go index -

What is 'Queue full' error?

You get 'Queue full' error when NxFilter can't process the DNS request in its job queue fast enough. It can happen when you lose the network connection to your upstream server or when you have too many requests for your system performance. If it is caused by a network connection problem it will be solved after your connection restored.

* NxFilter introduced 'Persistent Cache' as of v4.1.1. NxFilter works with Persistent Cache when it loses its connection to its upstream servers. So your NxFilter will be working even if you lose your upstream server connection.

If you don't have a network connection problem then you might need to do some tweaks on your system. If you have more than 1,000 users, you may need to increase memory allocation to NxFilter. If you use clustering and have more than 3,000 users it might be from 'Database Connection Bottleneck' problem. We have Performance tuning guide on this tutorial to deal with these problems.

- Go index -

How do I restrict porn on Google, Youtube search result?

You can force safe-search from NxFilter. We have 'Safe-search' option on a policy.

* Switching between 'Moderate' and 'Strict' makes a difference only for Youtube.

- Go index -

Can I bypass a specific user from filtering and logging?

You might want to bypass some of your users form filtering and logging. With v4.1.4, we added an option for bypassing filering/logging based on client IP address. You can add the client IP addresses you want to bypass from filtering and logging on 'Config > Allowed IP > Bypass All'.

- Go index -

Can I install NxFilter on my Active Directory domain controller?

Some people want to install NxFilter on their Active Directory domain controller. It is ideal if you don't want to have one more hardware or VM. However, a domain controller usually has its own MS DNS server and that makes a port collision problem with NxFilter. The solution is to add one more IP on your domain controller and have your MS DNS server listening only one IP address and have your NxFilter listening on another IP address.

For example, if you want to have your NxFilter listening on '' only, you need to modify the value of 'listen_ip' parameter on 'c:/nxfilter/conf/cfg.properties' file.

    listen_ip =

* We have a video tutorial for this on Youtube - View Youtube tutorial!

- Go index -

How can I calculate the number of users for a commercial license?

NxFilter counts the number of unique usernames and client IP addresses on daily basis. If one of them exceeds your licensed user number, any unlicensed user will be appeared being blocked on your log view. However, since it is a warning measure this blocking is not actually happening on user side.

* To find out the number of users in your network, view the usage report for the last 30 days on 'Report > Usage'.

* NxFilter also counts the request number. About request counting, read What is 'Too many requests' error?

- Go index -

What is 'Too many requests' error?

Since we found that there were people trying to use NxFilter behind a router several times we do license checking by request counting. On our statistics so far, one user makes up to 1,000 requests a day. We added 2,000 requests as redundancy on it. So we allow one user to make up to 3,000 requests a day. This is more than enough considering most DNS filter companies allowing under 1,500 requests per-user a day.

This license protection by request counting is especially needed for our cloud business partners as they can have a customer trying to put several thousand users under one username and depleting all their system resource. It is not just for protecting our business, it is also for protecting our partner's business.

* We have request-sum and request-cnt. We use request-cnt which is smaller for license restriction.

* We only count 'A' type DNS query for license restriction.

* Before you buy your license, you might want to check the numbers on 'Report > Usage'. It is the usage report for the past 30 days.

- Go index -

How do I add more users on my license?

You can add any number of users on your existing license. When you add more users, you only need to pay for the remaining period on your license. Suppose that you want to add 100 users after spending 6 months on your license then you only need to pay 50% of your new purchase. To add more user on your license, contact us using 'support @ nxfilter.org'.

- Go index -

My Internet connection gets faster after I install NxFilter.

It's because you now have a DNS caching server in your network. Before you install NxFilter, your users were making DNS queries against 'google.com' over and over again. When you use a public DNS server from the Internet, this means your users sending UDP packets to somewhere on the Internet and waiting for the response so many times a day. But after you install NxFilter, once a DNS response stored into NxFilter's DNS response cache, your users will get their DNS response directly from NxFilter. So there will be no latency from a public DNS server on the Internet and your users will be experiencing a faster Internet connection.

- Go index -

Can I bypass authentication on NxCloud?

On NxCloud, we need to know who is who first as everything needs to belong to an operator. However, some people want to let their users resolving some domains without identification process. In that case, you can do 'Total Bypass' for a domain. When you whitelist a domain on admin GUI with 'Bypass Filtering' and 'Bypass Logging' flags, it becomes 'Total Bypass' and it also bypasses authentication.

Does NxFilter support IPv6?

Yes, it does. You can get an IPv6 address as a DNS response or you can point NxFilter as your DNS server using an IPv6 address. However, we disabled its socket server on IPv6 address at default. The reason why we made it not listening on IPv6 is that if we accept DNS requests on both IPv4 and IPv6, you may need to login twice when you use authentication. It's because that when you logged-in over IPv4 and then make a DNS request over IPv6 we can't find your login session as we created it with your IPv4 address. Plus, IPv6 is not so human readable so most of our users don't use it in their authentication scheme yet. So we disabled IPv6 listening at the moment.

If you want to enable IPv6 listening on NxFilter, set the value of 'java.net.preferIPv4Stack' to 'false' in '/nxfilter/bin/startup.sh'.

    java -Djava.net.preferIPv4Stack=false -Xmx768m -cp $NX_HOME/nxd.jar:$NX_HOME//lib/*: nxd.Main

- Go index -

How to update it from v3 to v4?

There are some users wanting to update their NxFilter v3 to v4. Basically, there shouldn't be any problem with that but since some of them are using Shallalist which is not supported by v4 they may have a problem. If you update it from v3 to v4 keeping Shallalist option, you will not be able to start up NxFilter. So you have to change it to Jahaslist or one of other blacklist options supported by v4 before you update it. If you have other options on GUI you can do it easily but if you don't have any other option you can choose on GUI you can do it manually on '/nxfilter/conf/cfg.properties'. Change the value of 'blacklist_type' to 5 like below,

    blacklist_type = 5

- Go index -