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 may cause a problem with our embedded webserver. We recommend that you 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.

- Go to index -
Install NxFilter on Windows
We provide a Windows installer. When you download and run 'nxfilter-x.x.x.x.exe' you will see the following window.

* 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 are 'admin' and 'admin'.

- Go to 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 may cause 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 are '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

To remove NxFilter,

sudo dpkg -r nxfilter

On Ubuntu 18, 'systemd-resolved' service uses UDP/53. You have to disable it before you install NxFilter. To stop and disable it, run these commands,

sudo service systemd-resolved stop
sudo systemctl disable systemd-resolved.service

- Go to index -
Install NxFilter using RPM
Rob Asher has 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 to index -
Install NxFilter on other Linux
When you install NxFilter on Linux 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 may cause a problem with our embedded webserver. We recommend that you use OpenJDK 8 when you want to run NxFilter with OpenJDK.

1. Download 'nxfilter-x.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 are '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' command in '/etc/rc.local' script. You need to use '-d' option for running NxFilter as a daemon.

- Go to 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.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 are '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 to index -
Updating NxFilter
We provide a Windows installer and the 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.x.zip' file.

2. Stop NxFilter.

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

4. Start NxFilter.

- Go to 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 to index -
Client DNS setup
After you install NxFilter, you will want to monitor and filter Internet activity in your network. To monitor and filter Internet activity, you need to make NxFilter 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 at OS level like the above screenshot. 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 becomes the only DNS server your users can use.

- Go to 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 to index -
What is a blacklist?
A blacklist is a database of categorized domains. It is an essential part of 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 details about NxClassifier and Jahaslist, read NxClassifier section.

* We ship a 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 since 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 in the background. Globlist works on global policy level only.

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

- Go to index -
Reclassification of domains on blacklist
You can reclassify domains into any system/custom category. Your custom classification overrides the system 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 to index -
NxFilter and authentication
NxFilter provides several authentication methods including single sign-on with Active Directory integration.

Why authentication

When you install NxFilter for the 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? You may want to apply a stricter policy to your students and a bit lenient policy to the teachers and staffs. 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 that you created 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 are already logged-in or having an IP 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 an OpenLDAP or an Active Directory service, your users will be able to use their LDAP credentials on NxFilter's login page. To use this feature, you need to import 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 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 appear on NxFilter GUI with their Active Directory username and group.

- Go to 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 follow. So we want to explain what Active Directory integration is for NxFilter and when to use it and how to implement it at a 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 except when they login to their own PCs. 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 Active Directory.

User importation

Now we know what Active Directory integration is and why we need it. But how to do that? On NxFilter, the first thing you need to do is to import the users and groups from Active Directory. 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

Your users can use their Active Directory credentials on NxFilter's login page. However, they don't want to go through NxFilter's login page. So the next thing you need to do is to implement single sign-on. Now you need one of our agent programs working with NxFilter. We have several agents: NxLogon, VxLogon, NxMapper, CxLogon. 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 worried about the possibility of breaking the integrity of Active Directory since 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 MS DNS server. Our approach is to work with the existing 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
An 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 an 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 your MS DNS server. You can use any DNS server as an upstream DNS server for NxFilter including the 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. You can do those things on the edit page of your Active Directory importation setup. For having redundancy, 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.

- Go to index -
Differnces between single sign-on agents
We provide several single sign-on agents for NxFilter. There are pros and cons for these agents.

1. NxLogon
It's the oldest one we have been using. It needs to be launched by Group Policy Object (GPO) in Active Directory.

3. VxLogon
A script version of NxLogon to avoid of having trouble with some anti-virus softwares.

3. NxMapper
You can install it on a domain controller. Easier than NxLogon.

4. CxLogon
It works without Active Directory but you also can install it through GPO for Active Directory integration.

5. Custom login script
You can have single sign-on by writing your own script.

- Go to index -
Single sign-on with Active Directory using NxLogon
For those of you wanting to implement single sign-on with Active Directory, we have an agent program that is NxLogon. When you run NxLogon on a user PC it creates and refreshes a login session on NxFilter for the logged-in user on the system it is running on.

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

* Before you implement single sign-on against Active Directory, you need to import users and groups first. 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.

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 a 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 Active Directory, '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 with NxFilter logging. 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 to 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 since 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, you many have some users smart enough to find a way of logging-in with another username to acquire an alleviated permission because the protocol exposed in a script file. To prevent this kind of problem, we added an additional security procedure to activate 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 be able to see any output because 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 to 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 pick up a username and IP address pair from a user logon event and creates a login session on NxFilter.

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 see 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 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 every minutes, NxMapper just creates it and not refreshing it. 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.

- Go to index -
Single sign-on using CxLogon
CxLogon is the newest single sign-on agent for NxFilter introduced with v4.3 of NxFilter. Unlike NxLogon or NxMapper, You don't need to launch it from GPO or to run it on a domain controller. You just install it on a user system and it will create a login session on NxFilter with the logged-in username of the system it is running on. This means you can achieve single sing-on without Active Directory.

* You still can use it in an Active Directory environment.

How it works

Like the other single sign-on agent, you have to create a user on NxFilter before you use CxLogon. But unlike the other single sign-on agents, it will create a login request if there's no matching user for the logged-in username on the system it is running on. You can approve a login request on 'User > Login request' and a user will be created with the username which has been sent by CxLogon.

* You have to use NxFilter as the only DNS server in your network. Otherwise, CxLogon will not be able to find NxFilter.

CxLogon for Windows

When you install it on a user PC, it will be running as a Windows service. If you want to install it on multiple PCs at once, you can do it through GPO in Active Directory using the MSI package we provide.

CxLogon for Mac OS

We have a Mac OS installer for CxLogon. When you install it, it will create '/Library/cxlogon' directory and '/Library/LauachDaemon/org.nxfilter.cxlogon.plist' file to start it automatically at system startup.

To verify it running correctly,

sudo /Library/cxlogon/bin/test.sh

When you start and stop it manually,

sudo /bin/launchctl load -w /Library/LaunchDaemons/org.nxfilter.cxlogon.plist
sudo /bin/launchctl unload -w /Library/LaunchDaemons/org.nxfilter.cxlogon.plist

To uninstall it,

sudo /Library/cxlogon/uninstall-mac.sh

CxLogon for Chromebook

We provide a Chrome extension version of CxLogon for people having Chromebooks in their networks. One thing to note is that it starts working after your users launch their browsers. You may have some trouble if your Chromebooks need to access somewhere on the Internet before your users start CxLogon. As a workaround to this problem, you can create a default user associated to an IP range covering your local network and assign a policy having enough privilege to access those sites.

- Download CxLogon for Chromebook from Chrome Web Store

- Go to index -
Custom login script for single sign-on
For those of you wanting to implement single sign-on with OpenLDAP, eDirectory, Radius, etc, we provide 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.

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 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 a 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 a username.
- deleteIpSession(String ip) : Deleting a login session by an associated IP.
- findUser(String ip) : You can find a logged-in username by its associated IP.

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

- Go to index -
The order of authentication methods
NxFilter supports multiple authentication methods. So you could have a collision 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's 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 login some users without a 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, associate an IP range covering whole network to your default user. But you still can exclude a user from the IP range 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 to index -
GUI - Config
This is mostly system-wide settings 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' for IPv6 block redirection at default. 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.

- 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 will be expired 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 your log 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'.

- 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 HTTPS access only to your admin GUI, enable this option.

- 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.

Config > Admin

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

* 'Report Password' is for a 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 an IP based access restriction for its DNS, GUI, login redirection.

Config > Backup

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

Config > Block Page

You can set up your own 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 NxFilter to apply the new settings.

- Go to index -
NxFilter is basically a DNS server with filtering ability. This is for DNS service related settings.
DNS > Setup > DNS Setup

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

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

- Response Cache Size
NxFilter has its own cache for DNS responses from its upstream server. You can adjust the cache size. 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 a big enough persistent cache you will not lose your 'Internet Connection' even if there is a nationwide DNS outage because NxFilter will 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 response 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.

- Minimum Cache TTL
You can reduce the number of DNS requests from your clients by setting up a minimum cache TTL value. This only applies on A, AAAA, CNAME records.

- Block Cache TTL
The TTL value for NxFilter's block redirection response.

DNS > Setup > Local DNS

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

- Local Domain
When you have a domain 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, 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 an 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 the hostname only domains.

- Drop PTR For Private IP
Drop a 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.

DNS > Redirection

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

DNS > Zone Transfer

You may need to import a DNS zone from another DNS server. Once you add a zone-transfer setup here, NxFilter imports the DNS zone every minutes using IXFR protocol.

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

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 to be applied when it is not in a free-time.
- Free-time Policy : The policy to be 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.
- Group : You can set a group for a user if you created the user on NxFilter GUI manually.

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

You can 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 to verify your Active Directory importation setup.

- Go to index -
GUI - Policy
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 query. With this option enabled, NxFilter allows A, AAAA, PTR, CNAME only and the other types of DNS queries will be blocked.

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

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

- Bandwidth Limit
You can set a policy level bandwidth consumtion limit.

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

- 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 level block-time.

- 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/her quota the 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 a group specific free-time and policy specific block-time. Make your own free-time policy based on these options.


NxFilter supports remote user filtering and application control by NxClient. For more details, read NxClient and remote user filtering.

- Go to 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.

* 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 to index -
GUI - Whitelist
This is for making a whitelist/blacklist by a domain or a keyword.

- Bypass Authentication : 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.

- 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 the requests for a specific domain check this option.

* You can use an asterisk to include subdomains.

    ex) *.nxfilter.org

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

On the dashboard of NxFilter, There are several charts for showing the 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 in 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 DNS request log with various conditions on 'Logging > Request'. Logging data is being updated once in a minute to reduce the load of the system.

On 'Logging > Signal', you have the log of the signals from the agents of NxFilter.

On 'Logging > NetFlow', you have the NetFlow data imported.

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

    ex) [nxfilter], []


NxFilter generates a daily, weekly and a user level report.

- Go to 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 regardless of user location.

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

Installation of NxClient

When you install it using NxClient installer, you will see its setup program running. There are 'Server IP' and 'Login Token' parameters and you need to set them up with your own 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 values, 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.

* When you want to change its setup run 'C:/Program Files/nxclient/setup.exe'.

Signals of NxClient

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, 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 redundancy.

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.

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. It bypasses its remote filtering when it is in your local network. 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 Windows 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 a 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

- Go to index -
Proxy filtering by NxClient
NxClient has a web proxy module and does filtering by setting up itself to be the system web proxy server of your user system.

Supported options

1. Block IP Host
Blocking HTTP/HTTPS requests with an IP host in URLs.

2. Block Other Browser
Blocking programs making direct connections to the Internet bypassing the system web proxy.

* Currently, NxClient's proxy filtering supports Internet Explorer, Chrome, Firefox.

* Since we block a program using the application control module of NxClient, you can allow direct HTTP access to some application using 'Excluded keywords' on 'Application Control'.

3. IE Proxy Bypass
Since NxClient works as the system web proxy, you can use the bypass option on IE settings.

4. Query Cache TTL
NxClient keeps its filtering query results for 60 seconds at default for faster browsing. You can increase the value if you have a slow connection.

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

- Go to index -
Application control by NxClient
NxFilter supports application control by NxClient. You can block unwanted programs and find out who tried to run those blocked programs.

Supported options

1. Block UltraSurf
NxCleint detects UltraSurf by port scanning.

2. Block Port
NxCleint detects Tor by port scanning.

3. Blocked Process Name
You can block a process by its name. When you add a blocked keyword here and NxClient finds a matching process name, it will kill the process.

4. Excluded Keywords
You can add process names or keywords to bypass NxClient's process blocking.

5. Execution Interval
You can decide how frequently execute NxClient's process blocking.

Logging blocked application

We defined some special domains and rules for showing application control logging on NxFilter log view.

- 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.

- Go to index -
NxUpdate and dynamic IP update
NxUpdate is a dynamic IP updater for NxFilter. When you install it on a user system, you can associate it to a certain user using the login token of the user.

* It sends START, STOP and IPUPDATE signals to show you how it works. You can view these signals on 'Logging > Signal'.

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 to 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 since 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 and show you the block page you want to see.

You can install NxForward from Chrome Web Store.

- 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 to 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

When you build your own cloud service, one of the essential factors would be to be able to create accounts for your customers and let your customers set up their own policies 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 GUI 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 of an operator.

Operator GUI

On NxCloud, each operator has his/her 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 one of our agent programs.

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.

Use 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.

Active Directory integration over cloud

When you install NxRelay on a domain controller in an Active Directory evironment, it can send Active Directory username to NxCloud.

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 domain 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.

- Go to 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 customers use it for their network. So you need to create an account for your customer 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 customer'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 created 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 created 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 to index -
Differences from running NxFilter
1. Authentication is enabled always
You don't want to make your service available to everybody for free. You want to service it to your customers only. So the authentication is enabled by default.

2. Login redirection is disabled at default
You still can use password based login with NxCloud. But if you use it on a public network you can be a target of DNS attack. 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 need to access an operator GUI for a 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 to 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 one 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 a home environment. There will be several familiy members and they have multiple Internet accessing devices. But they wouldn't pay for multiple users. In that case, this 3,000 daily request limit is too small for the customer.

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 will be notified by an email and you can reset their request counting on operator edit page.

- Go to 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 IPs and IP ranges 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.

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 loads all of its config parameters from '/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 supports the following parameters on '/opt/nxrelay/conf/cfg.properties',

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

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

- local_dns : Your local DNS server or Active Directory DNS server doing the actual DNS resolving. If there's no DNS server specified here, we use and

- 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.

- use_https_dns : You can use Cloudflare HTTPS DNS server for DNS resolving since v2.4.7 of NxRelay.

    ex) 0 = false, 1 = true

- query_cache_ttl : NxRelay has 300 seconds cache for a query result from its policy server. You can set a number between 0 and 3600 seconds. It will reduce the communication to your policy server but your filtering policy change will be reflected after your cache expired.

    ex) 0 = bypass, 300 = 5 minutes, 1200 = 20 minutes

- run_mapper : NxRelay has an integrated NxMapper module 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 its config file. But that is just a default policy for NxRelay. You can apply a different policy based on a private IP address in your local network. On NxCloud's operator GUI, create a user and associate a private IP address or IP range 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 we have 2 more,

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.

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 server. 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 set your MS DNS server to be the 'Local DNS' of NxRelay and bypass your Active Directory domain as the '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 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 in 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 to index -
Before you customize NxFilter
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 to 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 an operator specific menu. If a JSP file is for an operator specific menu then it has 'zop' prefix.

    ex) zop,policy,free_time.jsp

Structure of the 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. 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 in '/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.

* '/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 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 'cfg.properties' file.

    www_dir = myweb

Then restart your NxFilter.

- Go to 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. 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 to index -
GUI - Javadoc for DAO and Data classes
We have Javadoc for 'dao' and 'data' packages.

- Go to 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 following 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 to index -
Templates for email and block page
NxFilter sends alert emails to its administrator. Mostly it is about the access violations 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 for when you install NxFilter for the first time to populate its DB or when you click 'RESTORE-DEFAULT' button on 'Config > Block Page' on NxFilter GUI.

- Go to 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 these files when you make your own package for your customized NxFilter.

The other thing you would need to think about would be the 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 to index -
Making your own install packages for client softwares
For NxLogon, since it is a simple Windows console application in a zip file you just need to replace several files from the original zip file and make your own zip file including 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.

However, it is a bit different for other client softwares having their own installers.

What we do with an Windows installer

For example, when you install NxClient, 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 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 a Windows service, run 'bin/unstsvc.bat' to unregister it from Windows service list.

Changing application name

When you customize one of our client programs, you may want to change its name on the setup GUI and its Windows service name. We have 'conf/appname' file for that under the installation directory. When you change the name inside the file, the new name will appear on the setup program and the Windows service name will be changed as well.

Replacing the icon file and the default setup values

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.

If you want to change the default setup values, you can change them by modifying 'conf/cfg.default' file.

* 'conf/cfg.default' file will be copied to 'conf/cfg.properties' file 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 to 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 a 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 to 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.

- 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.

- Classified Data Retention Days : NxClassifier keeps the classification result log for the recently classified domains. NxClassifier doesn't do the classification against these 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 the classification if you want.


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

* 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 the 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 do it on 'Category > System' as the reclassified domains will be stored into the main config DB.

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.

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

- 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.

- Go to 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.

- Go to 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'. 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 DNS attack. But the problem is that if you enable authetication, these anonymous users querying your domain will be redirected to NxFilter's logig page. To allow the anonymous DNS query against your domain, you need to bypass authentication for the 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 DNS attack. It 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 to index -
To avoid of having DNS attack
When you put NxFilter on the Internet, it can be under a DNS attack. Once you are under a DNS attack you will have 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 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.

- Go to index -
Clustering with NxFilter
NxFilter supports 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.

* We have 'Huge Cluster' option for NxCloud allowing 16 slave nodes in a cluster.

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 the 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 NxFilter cluster

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.

Redundancy for block redireciton

You can have multiple block redirection IP addresses separated by commas on 'Config > Setup' for redundancy. If you use NxCloud, you can do the block redirection to each slave node by setting up 'block_node_ip' on each slave node with its own IP.

For example, if you have a slave node on, add the following line into '/nxcloud/conf/cfg.properties' file.

    block_node_ip =

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 have an alert email setup 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 the entire IP range of your network.

* NxCloud's case is a bit different. It drops the requests from unauthenticated users because the 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 a slave node

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 the connection state

You can view the connection state of your slave nodes on 'Config > Cluster'. Once you set up your cluster then your slave nodes will be shown 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.

- Go to index -
Bandwidth control with NxFilter
NxFilter supports a user level bandwidth control by utilizing NetFlow data from a router. The idea is simple. NxFilter associates NetFlow data to a 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 an inboud or outbound traffic to the Internet. And lastly, NxFilter keeps only TCP/UDP data.

* Currently, NxFilter supports NetFlow v5 only.

- Go to index -
Detecting and preventing malware/botnet activity with NxFilter
NxFilter can detect and block malware/botnet activity by analyzing DNS packets. In reality, malwares and botnets are some 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 such kind of DNS queries.

Another example would be the botnets using 'TXT' record or other DNS records as their communication tool. These are the 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 to 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 on '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.

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

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' 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.

Disk space and reducing the amount of log data

NxFilter has various logging/reporting features. These kinds of features require a lot of disk space. When you have a huge 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 the traffic DB. Or to save the disk space, you can reduce the size of traffic DB. To reduce the size of the 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 multiple 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

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 for not having any inconsistency between the 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 the performance.

For main configuration database, we don't have this kind of problem since 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. 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 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 to 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 an 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 to 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 to 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 to 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'.

- Go to 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 broken webpage in most cases.

- Go to 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 to 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 becomes the only DNS server that your users can use and their DNS setup to point NxFilter will be done automatically.

- Go to index -

How NxFilter determine 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 policy 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 to index -

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

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

- Go to index -

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

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 to 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 to 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 to 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 to 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 to 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 to 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 to 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 to 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 to 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 to 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 in 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 to 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 to 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 to 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 to 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 to 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 in this tutorial to deal with these problems.

- Go to 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 to 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 filtering/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 to 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 to 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 appear 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 to 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 to 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 to 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 to 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 to 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 to index -