NxFilter Tutorial
V2.1.5, Modifed on 2017/06/25

We are recruiting translators of NxFilter tutorial for other languages. We can reward you with a free license. To become a translator, contact us using 'support @ nxfilter.org'.

1. Getting started

2. JahasFilter

3. Blacklist and domain categorization

4. Authentication

5. GUI overview

6. Working with an agent

7. NxCloud

8. Customization or rebranding of NxFilter and its clients

9. NxClassifier

10. NxFilter as a DNS server

11. Misc

12. FAQ
System requirements
- Windows, Linux, FreeBSD or other OS having Java(JRE) 1.7 or higher installed.
- 512 MB RAM.
- 4 GB of free disk space.
- UDP/53, TCP/80, TCP/443 ports.

* You can run NxFilter with lesser hardware but we recommend you to have more than 1 GB of system memory and 40 GB of disk space especially when you have more than 1,000 users.

* At default NxFilter uses up to 512 MB of system memory. This might not be enough for a bigger site. To allocate more memory to NxFilter, read Performance tuning guide part of this tutorial.

- Go index -
Which one to install
We have four variations of NxFilter.

1. NxFilter v4
You can use it for any purpose including commercial one. You can build your own product based on it. Modification, rebranding, redistribution is permitted by its license. Trial license for Jahaslist for 30 days without restriction and free 20 user license for Jahaslist included.

2. JahasFilter
A stripped down version of NxFilter for personal, non-commercial use. It includes an unlimited license for Jahaslist.

3. NxCloud
Another variation of NxFilter for multi-tenancy cloud filtering business.

4. NxFilter v3
Older version of NxFilter supporting Shallalist. Personal, non-commercial use only.

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

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 the following login screen your NxFilter is up and running. The initial login name and password is 'admin' and 'admin'.

- Go index -
Install NxFilter on Ubuntu Linux
We have a 'deb' package for installing NxFilter on Ubuntu Linux. To install it, install Java first. Download the package using 'wget', and then install it using 'dpkg'. Then start it from the Systemd script which is installed with the package.

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 '192.168.0.100' type 'http://192.168.0.100/admin' into the address bar of your browser. The initial admin name and password is 'admin' and 'admin'.

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

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

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

sudo start nxfilter
sudo stop nxfilter

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

    - Rob Asher's NxFilter-RPMs

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

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

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

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

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

4. Run 'startup.sh'.

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

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

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

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

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

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

4. Run 'startup.bat'.

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

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

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

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

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

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

2. Stop NxFilter.

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

4. Start NxFilter.

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

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

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

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

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

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

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

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

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

- Go index -
When NxFilter not starting
When you find your NxFilter not starting, the first thing you need to do is checking '/nxfilter/log/nxfilter.log' file. You can find some information about the cause of the 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 the 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 the system and you need to have the proper environment variables for Java.

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 you need to include the path into the environment variables for your system.

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

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

- Go index -
What is JahasFilter
JahasFilter is a stripped down version of NxFilter for home users and casual users. We noticed that many people having difficulties understanding how to use NxFilter. So we came up with JahasFilter. We removed some of advanced features from NxFilter to make it easy to use and we named it "JahasFilter".

* We ship an unlimited free license of Jahaslist in the package of JahasFilter.

* JahasFilter is only for personal, non-commercial use.

- Go index -
Install JahasFilter
Basically, JahasFilter is a variation of NxFilter. To install and how to set up, you can do the same thing as NxFilter.

- Install NxFilter on Windows
- Start and stop NxFilter
- Client DNS setup

* On Windows, JahasFilter installer installs it into 'c:/jahasfilter.

* When you install it as a Windows service, use 'net start JahasFilter' and 'net stop JahasFilter' to start and stop it as a service.

- Go index -
How to use JahasFilter
Since JahasFilter is still NxFilter internally, you can use it in the same way as NxFilter. But for the people having not enough experience with filtering, we will give you some ideas of how to use it.

How to block Facebook using JahasFilter

After you have your client PCs using JahasFilter as the only DNS server for them, go to 'User & Policy > Policy' on admin GUI and edit 'Default' policy and block 'Social Networking' category.

* It might take some time for your policy to be applied as your clients have their own DNS cache.

Authentication with JahasFilter

Unlike NxFilter, JahasFilter supports IP based authentication only. And there's one thing different from NxFilter's way of IP based authentication. Since we have seen so many people tried to associate a user to an IP address without enabling authentication we made the IP association working without authentication enabled on JahasFilter. This means you can identify or view your users with their username and apply a policy when you create a user on JahasFilter GUI and associate the user to an IP or IP range.

However, it is user identification. It's not authentication yet. Users not having associated IP or unknown users will be able to use your network still. If you want to block these unknown users, go to 'Config > Setup' and enable 'Block Unknown User'. Then only the users having username and associated IP will be able to use your network.

* We have a preference of IP based authentication. Single IP association comes first and then smaller IP range. You can make some exception to your filtering policy using this rule. For example, you can associate '192.168.0.1 ~ 192.168.0.255' to a user named 'everyone' and associate '192.168.0.100' to 'manager' and assign a different policy on him/her.

When you have Active Directory

For the simplicity, JahasFilter doens't support Active Directory integration. But it doesn't mean that you can't use JahasFilter in your Active Directory environment. You still can make JahasFilter to be working along with your MS DNS server. What you need to do is to bypass your local domain or Active Directory domain to your MS DNS server. For example, if you have 'nxfilter.local' as your Active Directory domain on '192.168.0.x' network and the IP of your MS DNS server is '192.168.0.254'. On 'DNS > Setup > Local DNS',

- Local DNS Server : 192.168.0.254
- Local Domain : nxfilter.local,0.168.192.in-addr.arpa

Your filtering will be working without breaking your Active Directory.

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

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

For more about NxClassifier and Jahaslist, read NxClassifier section.

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

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

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

3. Shallalist
NxFilter v3 supports Shallalist. Free for non-commercial use only. It is maintained on www.shallalist.de.

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

- Go index -
Reclassification on blacklist
You can add domains directly into system categories. It works like the domains added into custom categories. Even if you have the same domain classified differently in your blacklist your custom classification overrides it. So the effect of it 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' and the other one is using the popup reclassification form by clicking a domain on 'Logging > Request'.

- Go index -
Updating Shallalist
* Shallalist is supported by NxFilter v3 only.

NxFilter provides an auto-update script for Shallalist. To update Shallalist, stop NxFilter and run '/nxfilter/bin/update-sh.sh'. Depending on your Internet speed it may take several minutes to finish the whole process.

If you need to update it manually, download http://www.shallalist.de/Downloads/shallalist.tar.gz and extract it into '/nxfilter/shallalist1/BL'. Then run 'update-sh.sh /nxfilter/shallalist1/BL' command.

cd /nxfilter/bin
./update-sh.sh /nxfilter/shallalist1/BL

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

Why authentication

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

Which authentication

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

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

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

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

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

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

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

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

What is Active Directory integration

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

User importation

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

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

Single sign-on with Active Directory

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

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

MS DNS server and NxFilter

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

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

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

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

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

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

An examplary deployment scenario

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

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

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

For Chromebook, you can try NxBlock. It is a Chrome extension and you can use it as a remote filtering agent or single sign-on agent for Active Directory.

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

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

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

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

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

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

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

Follow the steps below to launch NxLogon from GPO.

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

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

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

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

    

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

    

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

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

    

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

    

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

    

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

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

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

Install and run NxMapper

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

* NxMapper needs to be installed on a domain controller.

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

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

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

Differences from using NxLogon

Although it is a lot easier to be compared to using NxLogon, NxMapper also has its own limit.

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

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

Terminal server exclusion

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

- Go index -
Single sign-on with Active Directory, OpenLDAP using NxClient
NxClient is basically a remote user filtering client for mobile workers with their own laptops. But you can use it for single sign-on against Active Directory or OpenLDAP. One good thing is that since there is Mac OS version of NxClient you can have single sign-on from Mac OS.

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

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

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

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

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

- Go index -
Custom login script for single sign-on
Currently NxFilter supports single sign-on with Active Directory. However some people want more than that. For example, you might want to have single sign-on with OpenLDAP.

NxFilter supports an API set for creating login session through HTTP protocol. You need to write your custom login script to call some webpage on NxFilter's built-in webserver. And then your users don't need to go through any login prompt.

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

You can call the webpage this way.

http://192.168.0.100/example/login_user.jsp?ip=192.168.0.100&uname=john

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

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

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

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

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

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

This is the order of authentication methods.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Config > Setup > Syslog

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

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

- Syslog Port
UDP port of 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 enabled 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 this, 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 the admin GUI using the domain you set up. 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. Otherwise you need to register your admin domain to your own DNS server.

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

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

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

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

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

Config > Admin

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

* 'Client Password' is for remote filtering agent setup. We use it to access NxBlock setup page.

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

Config > Alert

NxFilter sends an email for recent blocking or access violation. If you want to send an alert email to 'admin @ nxfilter.org' from 'alert200 @ gmail.com' on 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 some system related incidents. But 'CC Recipients' is only for recent blocking.

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

Config > Allowed IP

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

Config > Backup

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

Config > Block Page

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

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

Config > Cluster

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

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

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

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

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

- Use Persistent Cache
NxFilter can keep up to 1 million DNS responses in its DB. When you have enough number of persistent cache you will not lose your 'Internet Connection' even if there is a nationwide DNS outage. Your users will be able to use the Internet mostly.

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

DNS > Setup > Local DNS

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

- Local Domain
When you have a domain which you want to forward 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 subdomain already.

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

- Use Local DNS
Enable local DNS.

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

DNS > Setup > Misc

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

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

DNS > Zone File

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

DNS > Redirection

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

DNS > Zone Transfer

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

DNS > Dynamic DNS

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

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

Creating a user

You can create a user on 'User & Group > User'. There are 3 types of users in NxFilter

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

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

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

Properties of a user

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

Testing a user

When you have an LDAP imported user you may have multiple groups and policies for a user. As a result it becomes difficult to figure out which policy a user fall 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 > Group' you can set up a policy for the group by editing its properties. You also can assign members to the group.

Importing users and groups from Active Directory, OpenLDAP, eDirectory

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

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

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

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

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

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

- Go index -
GUI - Policy & Rule
With NxFilter you can have multiple filtering policies 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 query and response to communicate to each other.

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

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

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

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

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

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

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

* Safe-search enforcing for Yahoo requires a local proxy agent running on user system.

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

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

- Disable Application Control
Disable application control on policy level.

- Disable Proxy Filtering
Disable proxy filtering for on policy level.

- Logging Only
Monitoring user activity without blocking them.

- Blocked Categories
You can block domains by categories.

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

Define a free-time

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

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

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

Application Control

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

Proxy Filtering

NxFilter provides HTTP proxy filtering through NxClient. For more details, read Proxy filtering with NxClient part of this tutorial.

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

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

* To include subdomains into a category use asterisk.

    ex) *.nxfilter.org

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

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

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

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

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

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

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

* You can use an asterisk to include subdomains.

    ex) *.nxfilter.org

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

When you login to your admin GUI you will see the dashboard of NxFilter. There are several charts for showing a summary for the last 2 hours. On 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. And then it flushes the data once a minute. If there is a request for the same domain from the same user in a minute it only increases the count for the data. So 'request-sum' means the sum of all the requests and 'request-cnt' means the count for all the unique data.

Logging

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

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

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

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

    ex) [nxfilter], [192.168.0.100]

Report

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

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

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

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

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

4. NxUpdate
Dynamic IP updater for NxFilter.

5. NxBlock
Remote filtering agent and single sign-on agent for Chromebook.

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

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

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

Installation of NxClient

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

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

* NxClient is a Windows or Mac daemon program. It starts at system startup automatically.

* When you install NxClient on Mac OS X, read Installing NxClient or NxUpdate on Mac OS X on this tutorial.

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

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

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

Signals of NxClient

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

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

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

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

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

Fail-safe measure for NxClient

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

Auto-switch between local filtering and remote filtering

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

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

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

Uninstalling NxClient

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

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

Silent install

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

For silent install,

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

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

/server=192.168.0.100
/token=2P1WQ6VF

This is the final form of the command.

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

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

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

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

NxUpdate has basically the same structure as NxClient. You can install it in the same way as NxClient.

* It sends START, STOP and IPUPDATE signals.

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

Writing your own NxUpdate

We use DNS protocol for the communication between NxFilter and NxUpdate. This means you can write your own NxUpdate as long as you can run 'nslookup' or if you can send a DNS query.

If you send an IP update query against NxFilter from your Windows command prompt using nslookup,

nslookup GKSYEJYG.ipupdate.signal.nxfilter.org. 192.168.0.100

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

We use the following signals.

- 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 have two kinds of responses from NxFilter.

- 127.100.100.1 : Error.
- 127.100.100.100 : Success.

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

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

How it works

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

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

Supported options

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

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

* Mac OS version of NxClient doesn't support 'Block by process name'.

Enable application control only for specific users

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

Logging blocked application

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

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

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

Execution Interval

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

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

How it works

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

Supported options

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

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

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

* Currently the proxy filtering supports Internet Explorer, Chrome, Firefox.

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

4. Blocked Keyword in URL
Keyword filtering against URL.

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

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

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

Enable proxy filtering only for specific users

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

Logging

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

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

- Go index -
Installing NxClient or NxUpdate on Mac OS X
We provide a Mac OS installer for NxClient and NxUpdate. You can install them as you do with our Windows installer. You set up connection values and do 'Test' and 'Start'.

When you want to run its setup program after installation, you need to run 'setup-mac.sh' script inside the installation directory. If it is NxClient it will be installed into '/Library/nxclient' so you'd need to run the following command.

sudo /Library/nxclient/setup-mac.sh

When you start and stop it manually,

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

When you uninstall it,

sudo /Library/nxclient/uninstall-mac.sh

- Go index -
NxBlock for Chromebook
NxBlock is our remote filtering agent for Chromebook. It also can be used as a single sign-on agent in a local network.

Installation of NxBlock

NxBlock is basically a Chrome extension. You can install it from Chrome Web Store. Download it from the following link.

     - Download NxBlock from Chrome Web Store

Filtering policy of NxBlock

NxBlock shares the policy on 'Policy & Rule > Proxy Filtering' with NxClient. It updates its policy periodically by 'Agent Policy Update Period' on 'Config > Setup'

Connection to NxFilter

After you install it, you can see NxBlock on your extension setup panel of Chrome or 'chrome://extensions'. There is 'options' link under NxBlock icon. When you click the icon you will be on NxBlock setup page. You need to set up these parameters.

- Sever IP : The IP address of your NxFilter.
- Login Token : A login token associated to a user on NxFilter.

Once you set up these parameters you can test the connectivity using 'Test' button. And then use 'Save' button to save and reload the new configuration.

Password protection of your setup

You can hide your NxBlock setup page from your users by having password login procedure. Once you set up a password and enable it, the users will be blocked from accessing NxBlock setup page and 'chrome://extension'.

* You can use your 'Client Password' on 'Config > Admin' to access NxBlock setup page once its connection to server is established.

User identification

We use login token and Google account to identify users. Suppose you create a user named 'student' on NxFilter and install and set up 10 NxBlock on 10 Chromebooks with the login token of 'student' user. If the users on each Chromebook doesn't login to Google they will be appeared on NxFilter side as 'student'. But if one of them login to Google using 'john1234@gmail.com' for example, then he/she will be appeared as 'student_john1234' on NxFilter log view.
Central configuration for mass installation

When you do mass installation for NxBlock the problem is that you don't want to set up its connection parameters one by one. If you just use it as a single sign-on agent in your local network it might be fine without the connection parameters but if you want to use it for remote filtering you must set these parameters.

To solve this problem, we have a way for setting up these values centrally. We use Chrome's start page function for this. You write a webpage containing some common config values and then make the webpage to be Chrome's start page on Google admin console. Then everytime your users start their Chrome they will set up themselves with the values.

When you write the webpage you add a meta tag like the followings,

<meta name='nxblock' content='192.168.0.100:HW00IYKW:1'>

We have 3 parameters separated by colons. The first one is NxFilter's IP address and the second one is a login token and the last one is about locking or unlocking Chrome's extension setup page.

On Google admin side,

1. From the main dashboard, go to Device Management > Chrome > User Settings.

2. Select the organizational unit to which you want the settings to apply.

3. Find 'Pages to Load on Startup'.

4. Enter the URL for the web page containing NxBlock configuration meta tag.

5. Click the 'Save Changes' button.

Single sign-on in your local network

NxBlock works as a single sign-on agent on a local network. We use Google account for single sign-on and we made a simple rule for this. If you login to your Chromebook with 'john1234@gmail.com' and have 'john1234' user on NxFilter then you get the single sign-on.

While the concept of single sign-on with NxBlock is easy and simple but we might have some problem with Chromebook. It tries to open webpages or make DNS queries before NxBlock starts. This means it tries to access websites before NxBlock creates a login session for it and it leads to get redirected to NxFilter's login-page or DNS failures for several websites.

The solution is to use a temporary username for the IP range to cover all your Chromebook users. On NxFilter, 'Login by IP range' comes after 'Login by IP session'. Suppose you create a user 'bemyguest' which covers 192.168.0.1 ~ 192.168.0.100. If there is a Chromebook using an IP address in the range it becomes 'bemyguest' on NxFilter and after NxBlock starts it appears with Google account or single sign-on username.

* Google supports Active Directory and LDAP sync with 'Google Apps Directory Sync'. If you need AD integration for your Chrombook read this, Google Apps Directory Sync

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

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

     - Download NxForward from Chrome Web Store

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

- Go index -
What is NxCloud?
NxCloud is a fully rebrandable multi-tenancy cloud based DNS filter software. It is based on NxFilter and inherited the most of the features of NxFilter. You can build your own cloud filtering service using NxCloud.

These are the features only available on NxCloud.

Multi-level admin

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

On NxCloud there are 3 kinds of users.

Admin > Operator > User

'Admin' is actually the administrator of NxCloud. 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 it is something like a sub-admin on NxCloud. They can create and manage their own users and policies.

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

Creating an operator

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

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

Operator GUI

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

Operator and user

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

Operator specific dashboard and report

Each operator has their own dashboard and report on their GUI.

Operator specific free-time

Each operator can define their own free-time and they can set up work-time policies and free-time policies for their users.

Operator specific whitelist and blacklist

Your operators can have their own whitelist/blacklist based on domain name. But you still have the global whitelist/blacklist on your admin GUI. So you can have more flexibility to deal with these whitelist and blacklist.

Operator specific alert email

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

* You need to set up the global alert email first to send operator specific alert emails. 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 shows the default block-page by admin.

Authentication over cloud

NxClient, NxBlock still works against NxCloud. This means that you can differentiate users behind their router and you can apply a specific policy on a specific user. NxCloud also supports NxRelay that is a relaying DNS server being installed behind a router and lets you apply policies based on a private IP or IP range in your network.

Dynamic IP updater

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

Dynamic DNS association

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

Rebranding or customization of GUI

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

- Go index -
Install NxCloud
NxCloud is basically a modified NxFilter. You can install and run NxCloud in the same way as NxFilter.

But unlike NxFilter, after you install it, you can't use it as your DNS server right away. This is because NxCloud is a multi-tenancy program for commercial service. You are not supposed to use it for your internal network. Your clients use it for their network. So you need to create an account for your client first.

On NxCloud there are 3 kinds of users.

Admin > Operator > User

'Admin' is you and an operator is your customer and a user is the user in your 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 create an operator, there will be a default user and default policy for the operator with the same name as the operator. And the default password for the operator is also the name of the operator. Once you create an operator you can login using the operator account to set up a user for testing.

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

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

2. Login redirection disabled at default
You still can use password based login with NxCloud but if you use that on a public network you can be a target of DDOS attack. You'd better disable it on a public network. When you disable it NxCloud silently drops the DNS request packets from unknown source IP addresses.

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

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

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

To address this 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's needs.

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

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

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

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

The JSP code would look like the followings.

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

OperatorDao dao = new OperatorDao();
dao.insert(data);
%>

If you need to update the properties of an operator.

<%
OperatorDao dao = new OperatorDao();

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

If you need to suspend an operator.

<%
OperatorDao dao = new OperatorDao();

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

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

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

* NxRelay requires to run with NxCloud v3.4.2 or later.

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 even if you lose the connection to NxCloud your network will be working fine. And you will not have an issue with Active Directory integration or local domain resolving as all the queries will be resolved by your local DNS server.

* Since it is a DNS server you can have fail-safe and load balance easily. Install multiple NxRelay servers and make them as the primary and secondary DNS servers of your network.

* 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

1. Download its zip package.

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

On CMD,

cd c:/nxrelay/bin
instsvc.bat
net start NxRelay

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

Install it on Linux as a Systemd service

1. Download its zip package.

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

On command line,

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

To stop it,

sudo systemctl stop nxrelay.service

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

How to set it up

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

For example,

server = 192.168.0.100
token = BSYEB28O
local_dns = 8.8.8.8,8.8.4.4
local_domain =

When you have these config values in the config file, your NxCloud server IP is '192.168.0.100' and the login token is 'BSYEB28O' and your local DNS server or the existing DNS server is '8.8.8.8' and '8.8.4.4'. If you have some domains to bypass from filtering you can add them as the 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'.

Which policy to apply

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

Scipts included

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

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

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

For Windows,

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

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

nxrelay.service

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

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

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

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

    ex) zop,policy,free_time.jsp

Structure of web application directory

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

/nxfilter/webapps
- error
- example
- img
- include
- lib
- WEB-INF

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

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

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

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

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

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

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

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

We have 'WEB-INF' as 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. You'd better 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 this directory as the root directory of NxFilter's webserver, you need to add the following line into your 'cfg.properties' file.

    www_dir = myweb

Then restart your NxFilter.

- Go index -
GUI - Using Dao and Data classes
On 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' file 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;

dao.insert(data);
%>

To delete a data when its ID is 12,

<%
WhitelistDomainDao dao = new WhitelistDomainDao();
dao.delete(12);
%>

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;
dao.update(data);
%>

Lastly, to list data.

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

Accessing data field

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

<%
UserData data = new UserDao().selectOne(1);
out.println(data.name)
%>

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

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

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

appname = MyFilter

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

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

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

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

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

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

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

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

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

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

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

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

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

Making your own Windows installer

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

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

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

Making your own Mac OS installer

We use 'Packages' from http://s.sudre.free.fr for building our Mac OS installer. When you run our installer, it will create its own directory under '/Library' and copy a 'conf/plist.default' file into '/Library/LaunchDaemons' with a new name like 'org.nxfilter.nxclient.plist' to run it as a daemon. and then it runs 'setup-mac.sh' inside its installation directory to launch its setup program. When you uninstall it, you need to run 'uninstall-mac.sh' inside the installation directory manually.

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

Changing application name

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

Replacing icon file and default setup value

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

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

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

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

Writing your own setup program or GUI

If you can build your own package, to build and include your own setup program is also a possible option. On our setup programs there are some input controls and buttons. For input controls, we read the values from 'conf/cfg.properties' file.

And when you click the buttons that are 'SAVE', 'TEST', 'START', 'STOP', we do some action with the updated config values. With 'SAVE' button we save the config values into 'conf/cfg.properties' file. For 'START' and 'STOP' buttons, if it is on Windows we use 'net start' and 'net stop' commands as we install our agent as a service. On Mac OS, we use '/bin/launchstl' command with a Plist file we copied into '/Library/LaunchDaemons' directory.

So when you make a setup program for NxClient on Windows, you need to run these commands with 'START' and 'STOP' buttons,

net start NxClient
net stop NxClient

If it is on Mac OS,

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

For 'TEST' button, you can run 'bin/test.bat' or 'bin/test.sh' script. Before you run the test script you have to save the config values first.

After you run the test script you can get some messages with the following exit codes.

0 = Success
-1 = Invalid config values
-2 = Connection error
-3 = Login error

* For NxMapper, we have 'test.exe' instead of 'bin/test.bat'.

* For NxMapper, we don't have the login error code as there is no login process.

Customization of NxRelay

We don't provide an installer or a setup program for NxRelay as we don't think it is for an ordinary Windows user. But its structure is almost same as NxFilter. You have enough knowledge to make an installer package for it if you already read the previous part of this tutorial.

Limitation

Building your own installers and changing the names of the client softwares will do what you want to do 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 don'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. All in all it is our software and you just customize it, so it is inevitable to have some limitation.

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

* NxClassifier requires a valid Jahaslist license.

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

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

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

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

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

However with NxClassifier,

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

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

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

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

4. Jahaslist keeps growing.
We only ship a baselist in NxFilter package as we want to make the size of NxFilter package small. It covers the major sites only. But with the aide of dynamic classification by NxClassifier it keeps growing and they are only for the actual websites your users are visiting.

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

- Go index -
GUI for NxClassifier

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

Setup > Classifier Setup

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

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

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

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

- Classified Data Retention Days : NxClassifier makes the classification result log for the recently classified websites. NxClassifier doesn't do the classification against the already classified websites or the websites having classification result log without an error.

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

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

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

Classified

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

* With 'VIEW' button you can view the details of the log and with 'TEST' button you do 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.

Excluded

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 have NxClassifier trying to classify an excluded domain you would need to delete it from the list first.

Jahaslist

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

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

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

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

Test Run

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

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

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

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

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

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

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

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

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

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

- Category : Associated category for a rule.

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

- Go index -
Performance tuning for NxClassifier
NxClassifier works with multiple worker threads. We run two worker threads for NxClassifier at default. When you want to increase its performance you can increase the number of threads by setting up the value for 'classifier_num' parameter on '/nxfilter/conf/cfg.properties' file.

classifier_num = 8

And when you have a cluster for NxFilter, NxClassifier also gets clustered. With this feature you also can have a dedicated node for classification. You run 16 threads for classification on one node and you set 'classifier_num' to zero on all the other nodes.

The other thing you need to think about would be the optimization of your classification ruleset. If you have a bigger ruleset NxClassifier needs to consume more CPU power.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- Go index -
To avoid of having DDOS attack
When you put NxFilter on the Internet you might be under DDOS attack. Once you are under DDOS attack or the other kinds of DNS attack you could have a massive traffic to your NxFilter. Your NxFilter can't handle all the traffic and eventually it will look like almost dead and you will get the 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. Being unknown to NxFilter, these attackers will get your NxFilter redirection IP as a DNS response always.

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

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

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

Creating a cluster

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

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

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

Starting clustered NxFilter

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

Load balancing and fail-safe

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

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

When a cluster node down

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

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

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

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

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

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

Access control for slave nodes

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

Monitoring slave node state

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

Session sharing between cluster nodes

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

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

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

    no_share_session = 1

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

- Go index -
Bandwidth control with NxFilter
NxFilter supports per-user based bandwidth control by utilizing NetFlow data. The idea is simple. NxFilter associates NetFlow data from a router to its user login session based on IP address and if there is a user consumed bandwidth over the limit you set, 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 other protocols including HTTP, FTP, IM, Skype, Torrent and any other protocols 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 the destination IP address of a NetFlow data should be associated to an IP address of a logged-in user on NxFilter. Secondly, NxFilter ignores the internal traffic. This means either the source or the destination IP address needs to be a public IP address. This is because you are only interested in inboud or outbound traffic to the Internet. And lastly, NxFilter keeps only TCP/UDP data.

* Currently NxFilter supports NetFlow v5 only.

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

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

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

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

The other method we can think of would be detecting the domains abnormaly long. When we tested top 100,000 domains by Alexa all the domains except 142 domains were shorter than 30 characters. But there are abnormal domains trying to look like an URL of a target website. This is an example from www.phishtank.com which is trying to look like a webpage of www.ebay.co.uk but actually it i s 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 query from your client PC. In most cases your client PC doesn't need to make a DNS query for any other record than 'A', 'AAAA', 'PTR' , 'CNAME'.

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

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

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

- Go index -
Syslog exportation
NxFilter provides Syslog exportation function. The exported data is a character string separated by '|'. For example, if you have the following Syslog data,

NXFILTER|2013-01-28 10:53:23|Y|www.bbc.co.uk|pwuser|192.168.0.101|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 : 192.168.0.101
- Policy : admin
- Category : news
- Blocked reason : Blocked by admin
- DNS query type : 33
- Group : mygrp

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

* NxFilter v3 doesn't send 'Group'.

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

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

Memory size

At default NxFilter uses up to 512 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 something like,

    java -Djava.net.preferIPv4Stack=true -Xmx512m

If you want to increase it to 1 GB then change '-Xmx512m' to '-Xmx1024m'.

* When you run NxFilter as a Windows service you need to modify '--JvmMx=512' part in 'c:/nxfilter/bin/instsvc.bat'. And then reinstall the service with the increased memory size. When you reinstall it, uninstall the service with 'unstsvc.bat' first and then reinstall it by running 'instsvc.bat'.

* 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 reporting features. You can view all the logging data and daily, weekly report and per-user report. However this kind of reporting consumes a lot of disk space. When you have a bigger size of reporting data your system might experience a performance issue.

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

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

Increase the number of request handlers

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

    rh_num = 16

Using local recursive DNS server

One of the possible cause of performance degrading for NxFilter would be the latency to its upstream server. This is not the case when you have just several hundred users as NxFilter has its own caching. But if you have several thousand users this could be an issue. So we added local recursive DNS option.

However, this doesn't mean that NxFilter does recursive DNS query by itself. Rather you install a recursive DNS server into the server having NxFilter already installed and make NxFilter to use the recursive DNS server as its upstream DNS server. If you install something like MaraDNS's Deadwood recursive DNS server and set it to listen to UDP/10053 on '127.0.0.1' then you add the following line into '/nxfilter/conf/cfg.properties' file.

    local_resolver_port = 10053

And then restart NxFilter.

Disable data sharing between cluster nodes

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

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

    http://192.168.0.100/admin?rpw=pass1234

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

- Go index -
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 me 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 then you can bypass logging on NxFilter traffic DB. To bypass it, set 'Log Retention Days' on 'Config > Setup' to 0. If you use NxFilter v3, add 'syslog_only = 1' into /nxfilter/conf/cfg.properties file.

- Go index -
FAQ
These are frequently asked questions about NxFilter.

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 a virtual host. 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 in a webpage. This is especially true when it comes to a big portal site. Those URLs are based on DNS as well. If you try to access a blocked website using an IP address, you will get just a brocken webpage.

* NxFilter can block IP host in URL with its local proxy agents.

- Go index -

It doesn't get blocked/unblocked right away.

This is most likely from the DNS cache on your system. If you are on a Windows system there are two kinds of DNS caches. One is from your browser and the other is 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 it 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 DNS cache from Windows expires in a day at the maximum. Of course it depends on TTL from 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 blocked eventually. So in practice, this is not a problem as you don't need to block/unblock a site many times a day.

- Go index -

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

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

- Go index -

How NxFilter determin which policy to apply for a user?

You can assign a policy to a user directly. If a user belongs to a group then a group policy overrides a user policy. 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 apply 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 & Group > User'.

- Go index -

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

Add '*.facebook.com' into 'Whitelist > Domain' and check 'Admin Block' option.

- Go index -

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

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

- Go index -

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

Create a user or a group for your sales department and define a free-time in 'Policy & Rule > Free Time' then assign a free-time policy which is more lenient to the user or group.

- Go index -

How do I change NxFilter's webserver port?

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

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

http_port = 80
https_port = 443

After you change the ports, restart NxFilter.

- Go index -

How do I reset admin password?

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

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

- Go index -

Can I bind NxFilter to a specific IP address?

You might want to bind NxFilter to a specific IP address to avoid of having a 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 '0.0.0.0' NxFilter will listen on all the IP addresses of your system but if you set it to a specific IP address NxFilter will listen on the specified IP address only.

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

- Go index -

How do I bypass my local domain?

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

- Go index -

Can I use an exact matching keyword for log search?

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

    ex) [john], [192.168.0.1]

- Go index -

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

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

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

- Go index -

How do I apply my own SSL certificate?

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

keystore_file = conf/myown.keystore
keystore_pass = 123456

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

- Go index -

How do I enable debug mode?

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

- Go index -

How do I hide SSL warning?

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 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 config 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. Othewise your HTTPS request will be timed out immediately.

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

- Go index -

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

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

- Go index -

How do I bypass logging completely?

For internal purpose, the minimum log retention period you can set is 3 days. But you can bypass logging completely by setting 'syslog_only' option on '/nxfilter/conf/cfg.properties' file. If you set this option without having Syslog exportation setup then NxFilter bypasses logging and not sending Syslog data as it doesn't know where to send it.

To enable 'syslog_only' option add the following line on '/nxfilter/conf/cfg.properties' file,

syslog_only = 1

* You still get the counting data but the actual logging data will not be stored into your traffic DB.

- Go index -

How to set up a time zone.

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

-Duser.timezone=Europe/Rome

- Go index -

My Browsers keep restarting after NxClient starting.

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

- Go index -

How do I force a user to logout?

We don't have it on GUI. But in most cases, people want to force a user to logout when they leave their PC and they want to force the next user to login with his/her own username. For this, you can use the logout domain on 'Config > Setup'. You write a batch script for IE to visit the domain and make it running when a user logoff from his/her system.

@echo off
start http://logout.example.com

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

@echo off
nslookup logout.signal.nxfilter.org.

- Go index -

NxFilter stops working after 'Queue full' error.

You get 'Queue full' error when you lose the Internet connection or the connection to your upstream server. It happens as NxFilter can't process the DNS request in its queue. NxFilter is supposed to resume its job when its connection restored. However, on some system it doesn't resume the job after the connection restored. And the problem is that when we say 'connection' there's no actual connection as we are working on UDP. It is not happening on every system and we couldn't track down the source of the problem yet.

The solution to this problem is restarting NxFilter. And if you can restart NxFilter automatically when it gets 'Queue full' error that would be the best. As of v3.4.4, we introduced 'queue_full_exit' option on '/nxfilter/conf/cfg.properties' file. On the file, when you add the line below,

queue_full_exit = 1

your NxFilter will exit when it gets 'Queue full' error and you can restart it. For example, if you are on a Linux system you can use the respawn option of Upstart or Systemd for restarting NxFilter.

* As of v3.4.6, when you set up 'Config > Alert' you get an alert email for 'Queue full' error.

- Go index -

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

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

* Safe-search enforcing for Yahoo requires a local proxy agent running on user system.

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

- Go index -

What is 'Too many requests' error?

Since we found that there were people trying to use NxFilter behind a router several times we do license checking by request counting. On our statistics so far, one user makes up to 1,000 requests a day. We added 2,000 requests as a buffer 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 allow 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 checking.

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

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

- Go index -