1. Getting started

2. Domain categorization

3. Authentication

4. GUI overview

5. Working with agents

6. NxCloud

7. Customization or rebranding of NxFilter and its clients

8. NxClassifier

9. Misc

10. FAQ

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

- Go to index -

We provide a Windows installer. You also can install it manually.

Download and run 'nxfilter-x.x.x.x.exe' and you will see the following window.

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

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

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

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

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

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

4. Run 'startup.bat'.

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

- Go to index -

You can run NxFilter on Linux or other Unix like OS. We provide a Deb package for Ubuntu Linux and there're RPM and Docker. You also can install it using a zip file from us. We have a 'deb' package for installing NxFilter on Ubuntu Linux. To install it, after you install Java, download the package using 'wget', and then install it using 'dpkg'. Then start it from the Systemd script bundled with the package.

You can view the installation process using the following command,

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

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

To remove NxFilter,

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

To use Google DNS for your system,

Rob Asher has built an RPM repository for NxFilter packages. His RPM packages take care of Java installation and all the dependencies.

    - Rob Asher's RPM repository for NxFilter packages

To install NxFilter using 'yum' command, install Rob Asher's RPM repository first,

Then you can install NxFilter this way,

There are other packages as well,

Charles Gunzelman has built Docker images for NxFilter. He distributes his Docker images from the following site:

    - Charles Gunzelman's NxFilter Docker images

When you run NxFilter as a Docker container, use the following command,

When you install NxFilter on Linux in general,

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

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

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

4. Run 'startup.sh'.

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

- Go to index -

Rob Asher wrote a script installing NxFilter and its dependencies on pfSense. You can easily install NxFilter on your pfSense or Netgate box. There is a Github page for his install script:

    - Rob Asher's Github page for NxFilter install script on pfSense

- Go to index -

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

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

2. Stop NxFilter.

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

4. Start NxFilter.

- Go to index -

There are several utility scripts for NxFilter in '/nxfilter/bin' directory.

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

- Go to index -

After you install NxFilter, you will want to monitor and filter Internet activity in your network. To monitor and filter Internet activity, you need to make NxFilter the only DNS server for your network.

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

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

- Go to index -

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

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

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

On Windows system, you can set these environment variables.

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

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

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

- Go to index -

Domain categorization is an essential part of a DNS filter for blocking websites by categories. NxFilter supports several domain categorization options.

1. Jahaslist

2. Cloudlist

3. Globlist

- Go to index -

Jahaslist and Cloudlist options are commercial. You can find out more about them and buy their licenses at the following links.

- Go to index -

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

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

- Go to index -

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

Why authentication

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

Which authentication

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

1. IP based authentication

2. Password based authentication

3. LDAP based authentication

4. Login token based authentication

5. Single sign-on against Active Directory

- Go to index -

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

What is Active Directory integration?

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

User importation

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

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

Single sign-on with Active Directory

Your users can use their Active Directory credentials on NxFilter's login page. However, they don't want to go through NxFilter's login page. So the next thing you need to do is to implement single sign-on. Now you need one of our agent programs working with NxFilter. We have several agents: NxLogon, VxLogon, NxMapper, CxLogon. You can use just one of them or mix and match them to complement each other.

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 since NxFilter is a DNS server and the role of a DNS server in Active Directory is very important. But we don't disable or replace the existing MS DNS server. Our approach is to work with the existing DNS server in cooperation. So you have to maintain your existing MS DNS server even though you use NxFilter as the DNS server for your network.

1. Where to install it

2. Dynamic host update

3. Which upstream server for NxFilter

4. Manual setup for MS DNS server

- Go to index -

We provide several single sign-on agents for NxFilter. There are pros and cons for these agents.

1. NxMapper

2. NxLogon

3. VxLogon

4. CxLogon

5. Custom login script

- Go to index -

NxMapper is a Windows service program that you can install and run on a domain controller. It will detect user logon events and create login sessions on NxFilter.

Install and run NxMapper

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

'Server IP' is your NxFilter IP address. When you check 'Refresh Session', it will refresh the login session it creates on NxFilter.

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

- Go to index -

NxLogon is a console program without an installer. When you run it on a user PC, it creates and refreshes a login session on NxFilter for the logged-in user on the system it is running on. However, you don't want to copy and run this program on every PC manually. So we use a logon script on Group Policy Object (GPO). This logon script will be executed whenever a user logon to Active Directory and launches NxLogon on each user's PC.

Follow the steps below to launch NxLogon from GPO.

1. Download nxlogon-x.x.zip.

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

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

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

    

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

    

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

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

    

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

    

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

    

- Go to index -

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

How to run it

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

Security problem

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

On 'User > VxLogon',

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

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

Troubleshooting

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

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

- Go to index -

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

How it works

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

CxLogon for Windows

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

CxLogon for Mac OS

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

When you start and stop it manually,

To uninstall it,

- Go to index -

As of v4.3.4.3, NxFilter supports single sign-on by 802.1x Wi-Fi authentication with its built-in RADIUS accounting server. This means you can have single sign-on for smartphones and other mobile networking devices in your network. Since you can import users and groups from Active Directory, Google G Suite LDAP you can have your users to be appeared on NxFilter with their AD or Google usernames. How it works

We use RADIUS accounting protocol to pick up usernames from Wi-Fi authentication. NxFilter works as a RADIUS accounting server and you need to set your Wi-Fi router to send RADIUS accounting requests to NxFilter. One thing to note is that NxFilter doesn't do RADIUS authentication by itself. You do RADIUS authentication with your own authentication server. If you are in an Active Directory environment your authentication server would be your Windows Network Policy Server. So NxFilter doesn't break your RADIUS authentication chain.

GUI Options

After changing these option on GUI, you have to restart NxFilter.

- Accounting Port

- Shared Secret

- Enable Logout

- Auto-register For New User

- Default Group For New User

- Local Domain

- Use RADIUS

Active Directory integration

Firstly, import users and groups from your Active Directory on 'User > Active Directory'. After that, you need to set up NxFilter's integrated RADIUS accounting server on 'User > RADIUS'. Mostly you don't need to change anything on there except Shared Secret. Lastly, you implement 802.1x authentication with your Wi-Fi router and Windows NPS (Network Policy Server).

This is the capture image of our NPS setup.

G Suite LDAP and OpenLDAP integration

It's nothing different form Active Directory integration. You import users and groups from G Suite LDAP or OpenLDAP on 'User > OpenLDAP' and then you set up your router and your RADIUS authentication server and then send RADIUS accounting requests to NxFilter.

Delay for getting the first contact

There will be several seconds of delay for getting the first RADIUS accounting request after a user logged in by Wi-Fi authentication. One problem is that your users might get blocked by NxFilter as unauthenticated users. The solution is to define a default user for covering all the IP addresses in your network. Create a user on NxFilter GUI and associate an IP range covering your network to the user. Your Wi-Fi authenticated users will be appeared as the default user for several seconds before NxFilter receiving the first RADIUS accounting request and then they will be appeared with their own usernames.

Auto-register for new users

You may have some guest users temporarily using your network through 802.1x Wi-Fi authentication by a third party authentication service like Eduroam. They are not in your user database, but they are authenticated users. You want to allow them to use your network but monitor them with their usernames and apply a policy to them as a group. If you have only small number of visitors, you can do this by issuing temporary usernames to these guest users. But if there are hundreds of them coming and going, you don't want to do it manually.

For this kind of situation, we have 'Auto-register For New User' option. With this option enabled, when NxFilter finds a new username in an RADIUS accounting request, it will create a user with the new username in its database. You also can set a default group for these new users with 'Default Group For New User' option. For the filtering policy for these users, you can set a policy to the default group.

- Go to index -

For those of you wanting to implement single sign-on with OpenLDAP, eDirectory, Radius, etc, we provide an API set for creating login session through HTTP protocol. You can write your own custom login script to call a webpage on NxFilter's built-in webserver.

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

You can call the webpage this way.

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

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

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

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

- Go to index -

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

This is the order of authentication methods.

1. Single IP association

2. IP session

3. IP range association

- Go to index -

These are mostly system-wide settings for NxFilter. Config > Setup > Block and Authentication

- Block Redirection IP

- External Redirection IP

- IPv6 Redirection IP

- Enable Authentication

- Login Domain

- Logout Domain

- Login Session TTL

- Disable Login Redirection

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

- Syslog Port

- Export Blocked Only

- From Each Node

- Enable Remote Logging

Config > Setup > NetFlow

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

- Router IP

- Listen Port

- Run Collector

Config > Setup > Misc

- Admin Domain

- Bypass Microsoft Update

- Logging Retention Period

- SSL Only to Admin GUI

- Auto Backup

Config > Admin

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

Config > Alert

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

Config > Allowed IP

NxFilter has an IP based access restriction for its DNS, GUI, login redirection.

Config > Backup

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

Config > Block Page

You can set up your own block page, login page, welcome page. When you edit your block page you can use the following variables populated by NxFilter for making your block page more informative.

Config > Cluster

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

- Go to index -

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

- Upstream DNS server

- Upstream DNS Query Timeout

- Response Cache Size

- Use Persistent Cache

- Use Negative Cache

- Minimal Responses

- Minimum Cache TTL

- Block Cache TTL

DNS > Setup > Local DNS

- Local DNS Server

- Local Domain

- Local DNS Query Timeout

- Use Local DNS

DNS > Setup > DNS Over HTTPS

- HTTPS DNS Server

- HTTPS DNS Query Timeout

- Fail-safe With UDP/53

- Use HTTPS DNS

DNS > Setup > Misc

- Drop Hostname Without Domain

- Drop Reverse Lookup For Private IP

- Allow Reverse Lookup For Server IP

DNS > Zone File

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

DNS > Redirection

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

DNS > Zone Transfer

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

- Go to index -

You can create or import users and groups here. NxFilter supports user importation from Active Directory and OpenLDAP.

Creating a user

There are 3 types of users you can create on NxFilter.

1. IP user

2. Password user

3. LDAP user

Properties of a user

- Password : The password for login through NxFilter's login page.
- Work-time Policy : The policy to be applied when it is not in a free-time.
- Free-time Policy : The policy to be applied during a free-time. You can define free-time on 'Policy > Free Time'.
- Expiration Date : The expiration date for a user account.
- Login Token : The token for Remote Filtering. It is created when a user created or imported.
- Group : You can set a group for a user if you created the user on NxFilter GUI manually.

Testing a user

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

Creating a group

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

Importing users and groups from Active Directory, OpenLDAP

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

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

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.

User > RADIUS

This is for Single sign-on by 802.1x Wi-Fi authentication.

User > VxLogon

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

- Logon Domain

- Logon Domain

- Use VxLogon

User > Login Request

When you use CxLogon for single sign-on and if there is a new username detected by CxLogon, NxFilter will add a login request here. Once you approve a new login request, a new user will be created on NxFilter with the new username. For more details, read Single sign-on using CxLogon.

- Go to index -

You can have multiple filtering policies in your network based on user and group.

Creating a policy

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

Editing a policy

After you create a policy you can modify its properties.

- Priority Points

- Enable Filter

- Block All

- Block Unclassified

- Ad-remove

- Max Domain Length

- Block Covert Channel

- Block Mailer Worm

- Allow 'A' Record Only

- Quota

- Quota All

- Bandwidth Limit

- Safe Search

- Block-time

- Logging Only

- Blocked Categories

- Quotaed Categories

Define free-time

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

NxClient

NxFilter supports Remote Filtering and Application Control by NxClient. For more details, read NxClient and Remote Riltering.

Chromebook

NxFilter supports Remote Filtering for Chromebook. For more details, read CxBlock for Chromebook filtering.

- Go to index -

On NxFilter, there are system categories and custom categories. System categories are already defined by your domain categorization database. 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 domain categorization options. If you want to find out more, read Domain categorization database.

- Go to index -

This is for making a whitelist/blacklist by a domain or a keyword.

- Bypass Authentication : To allow your users to access some sites without authentication, use this option.

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

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

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

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

- Go to index -

NxFilter keeps its log data up to 400 days and generates a daily, weekly and a user level report based on the log data. Dashboard

On the dashboard of NxFilter, There are several charts for showing the summary for the last 2 hours. At the bottom of the dashboard, you can see 10 recent block logs for the last 12 hours.

Logging

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

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

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

Report

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

- Go to index -

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

Installation of NxClient

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

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

Signals of NxClient

We defined several signals with which you can find out what is happening on a user system. NxClient sends these signals.

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

Fail-safe measure for NxClient

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

Auto-switch between local filtering and remote filtering

When you use NxClient on your mobile worker's laptop you might have a problem with your filtering policy when they are staying in the office. Your mobile worker might be filtered twice. One from NxClient, one from your local NxFilter.

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

Uninstalling NxClient

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

Silent install

For those of you wanting to install NxClient on multiple PCs using GPO or PDQ deployment, we have silent install options.

For silent install,

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

This is the final form of the command.

- Go to index -

NxClient has a web proxy module and does HTTP/HTTPS filtering by setting up itself to be the system web proxy server of your user system.

Supported options

1. Block IP Host

2. Block Other Browser

3. IE Proxy Bypass

4. Query Cache TTL

- Go to index -

NxFilter supports Application Control by NxClient. You can block unwanted programs and find out who tried to run those blocked programs.

Supported options

1. Block UltraSurf

2. Block Port

3. Blocked Process Name

4. Excluded Keywords

5. Execution Interval

Logging blocked application

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

- Go to index -

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

Writing your own NxUpdate

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

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

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

We use the signals below.

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

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

You can send an IP update signal using 'nslookup' command,

- Go to index -

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

You can install NxForward from Chrome Web Store.

- Download NxForward from Chrome Web Store

- Go to index -

CxBlock is a remote filtering agent for Chromebook. Is used to be called 'NxBlock' but we had to change its name as we changed its protocol. We will not be able to use WebSocket protocol for NxBlock in future for a dependency problem with the embedded webserver for NxFilter. Eventually NxBlock will be retired and you need to replace it with CxBlock as soon as possible.

Installation of CxBlock

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

     - Download CxBlock from Chrome Web Store

Filtering policy of CxBlock

You can set up its policy on 'Policy > Chromebook'.

Connection to NxFilter

After you install it, you need to set up the following parameters on its setup page,

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 CxBlock 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 CxBlock setup page and 'chrome://extension'.

User identification

We use Login Token and Google Account to identify users. Suppose you create a user named 'student' on NxFilter and install CxLogon to 100 CxBlock with the login token of 'student' user. Before they login to Google they will appear on NxFilter log view as 'student'. But if one of them login to Google using 'john1234@gmail.com' for example, then he/she will appear as 'student_john1234' on NxFilter log view. Central configuration for mass installation

When you do mass installation for CxBlock, you don't want to set up its connection parameters one by one. To make things easier, we have a way for setting up these values centrally. We use Chrome's start page function. 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 config values.

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

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 Console,

Single sign-on for Chromebook

Since you can import users and groups from G Suite LDAP, you may want to implement single sign-on for Chromebook in your network. We added NxLogon module into CxBlock. So when a user is in your local network, the NxLogon module will be in action and it will create a login session for the user.

- Go to index -

When you install NxFilter on cloud or use NxCloud, one problem is to differentiate users behind a router as you want to apply a different policy to some users. We have several solutions for that. You can use NxRelay for IP based authentication or AD integration over cloud. And you also can use NxClient for single user.

However, if it's about just several users or without Active Directory, running NxRelay might be too heavy as it requires an extra hardware to runs on. If you go with NxClient, another problem is that you have to set a different DNS server other than your NxFilter/NxCloud for it and it makes a loop hole for your users.

Now we offer NxLocal which is a local DNS server running on a client system. It's a scaled down NxRelay for single user. Since this one runs on a user system like NxClient, you don't need a dedicated system for it. And this one does 'DNS Over HTTPS' so you don't need to set any DNS server for it.

Installation of NxLocal

When you install it using NxLocal installer, you will see its setup program running. There are 'Server IP' and 'Login Token' parameters and you need to set them up with your own values.

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

Signals of NxLocal

We defined several signals with which you can find out what is going on a user system. NxLocal sends these signals.

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

Policy and username

You set a login token for NxLocal setup and there's a user being tied to the token. So it will be appeared on NxFilter log-view with the username of its token user and will be under the policy of its token user. However, regarding username, we want to show you the system logged-in username as well. So NxLocal detects the currently logged-in username on the system it is running on and send it to its server. It will be look like 'tokenname_username'.

For example, you create a user 'nxlocal' on NxFilter side and there's user 'john100' on the client system on which NxLocal runs. Then the usernam on NxFilter log-view would be'nxlocal_john100' and it will be under the policy of 'nxlocal' user. With this feature, you can have group based filtering policy on NxCloud which doesn't have Group concept. You can create a user 'group1' and install several NxLocal with the token of 'group1' and then you get usernames like 'group1_john100' and 'group1_jane100' on your log-view under the same policy.

Fail-safe measure for NxLocal

NxLocal itself is a DNS server. So when it stops working you can't resolve any DNS queries on the system it runs on. But for NxLocal, NxFilter/NxCloud on cloud is just a policy server. Even if it can't connect its policy server it will be working as a DNS server forwarding its DNS queries to its upstream server through HTTPS protocol. We use 'DNS Over HTTPS' by Cloudflare as its upstream server. So you are not going to lose your DNS resolving as long as it can do 'DNS Over HTTPS' against Cloudflare.

NxLocal as a remote filtering agent

You can use NxLocal as a remote filtering agent instead of NxClient. Its filtering will be working in any place while it can connect its policy server that is your NxFilter or NxCloud server. It might be better than NxClient as it works on DNS level and NxClient which only can block HTTP/HTTPS traffic. However, they may block 'DNS Over HTTPS' in some sites and in that case, you will lose DNS resolving.

Local DNS server and local domain

You may have some local domains to be resolved by your local DNS servers. In that case, you can bypass those domains to your local DNS server by setting some parameters on 'C:/Program Files/nxlocal/cfg.properties' file. When your local domain is 'mydomain.local' and your local DNS server IP is '192.168.0.200' you can add the following lines to the file.

Uninstalling NxLocal

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

Silent install

For those of you wanting to install NxLocal on multiple PCs using GPO or PDQ deployment, we have silent install options.

For silent install,

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

This is the final form of the command.

- Go to index -

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

These are the key features only available on NxCloud.

Multi-level admin

When you build your own cloud service, one of the essential factors would be to be able to create accounts for your customers and let your customers set up their own policies on their own GUI.

On NxCloud there are 3 kinds of users.

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

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.

Operator GUI

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

Operator and user

Operators can create their users and apply policies based on user authentication. Users can be authenticated based on IP address or using one of our agent programs.

Operator specific dashboard and report

Each operator has their own dashboard and report.

Operator specific free-time

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

Operator specific whitelist and blacklist

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

Operator specific alert email

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

Operator specific block page

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

Use authentication over cloud

NxCloud supports IP based authentication against users behind a router with NxRelay. This means that you can apply different policies based on IP or IP range and you also can find out the exact number of users behind a router.

Active Directory integration over cloud

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

Dynamic IP Updater

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

Dynamic domain association

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

- Go to index -

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

On NxCloud, there are 3 kinds of users.

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

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

- Go to index -

1. Authentication is enabled always

2. Login redirection is disabled at default

3. Magic password for accessing operator GUI

- Go to index -

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

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

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

- Go to index -

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

How it works

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

Install it on Windows as a Windows service

We provide a Windows installer and setup program for NxRelay. It will install it as a Windows service and let you set it up on its GUI.

If you need to install NxRelay service on Windows manually,

1. Download its zip package.

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

On CMD,

Install it on Linux as a Systemd service

1. Download its zip package.

2. Extract it into '/nxrelay'.

On command line,

To stop it,

How to set it up

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

For example,

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 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 a comma separated value of 'local_domain'.

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

Config parameters

NxRelay supports the following parameters on '/nxrelay/conf/cfg.properties',

Which policy to apply

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

Scripts included

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

For Windows we have 2 more,

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

Active Directory integration over cloud using NxRelay

Active Directory integration over cloud is possible by NxRelay. When you install NxRelay on a domain controller in your Active Directory, it can detect and send logged-in usernames to its server. NxFilter and NxCloud both support Active Directory integration over cloud using NxRelay.

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

1. Install NxRelay on a domain controller.

2. Use your Active Directory DNS server as your local DNS server.

3. Import users and groups from Active Directory over cloud.

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

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

- Go to index -

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

- Go to index -

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

Structure of the web application directory

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

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

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.

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

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

Separating your customized GUI into another directory

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

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

    www_dir = myweb

Then restart your NxFilter.

- Go to index -

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

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

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,

To delete a data when its ID is 12,

To select a data when its ID is 12,

And to update the selected data,

Lastly, to list data.

Accessing data field

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

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

- Go to index -

We have Javadoc for 'dao' and 'data' packages.

- Go to index -

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

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.

- Go to index -

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

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

- Go to index -

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

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

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

- Go to index -

For NxLogon, since it is a simple Windows console application in a zip file you just need to replace several files from the original zip file and make your own zip file including them. You can change its name as well. When you change its name you also need to change the contents of the included batch files.

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

What we do with a Windows installer

For example, when you install NxClient, we copy all the required files into 'C:/Program Files (x86)/nxclient' and then we run 'bin/instsvc.bat' under the installation directory to register it as a Windows service and run 'bin/setup.bat' at the end of the installation process to run its setup program.

Changing application name

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

Replacing the icon file and the default setup values

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

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

Limitation

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

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

- Go to index -

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

- Go to index -

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

Setup > Classifier Setup

- DNS Test Timeout : NxClassifier only classifies the existing domains. So it does DNS testing first.

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

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

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

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

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

- Disable Cloud Classification : When NxClassifier fails to classify a domain, Jahastech's cloud based classifier will try to classify it.

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

Classified

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

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.

Jahaslist

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

Test Run

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

- Go to index -

Now we need to understand how to make a classification rule. A classification rule consists of the following parts.

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

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

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

- Go to index -

You can download and merge the public blocklists from the Internet into Jahaslist and Globlist overnight automatically on 'Classifier > Blocklist'.

- Format of the blocklist : Host file format or domains separated by new lines. Basically, all the blocklists from https://firebog.net will be working.

- Priority Points : There may be duplicated domains in your blocklists associated to different categories. You can make a specific blocklist to be downloaded and merged before others by setting higher priority points.

However, we don't merge every domain from your blocklists into Jahaslist. There are many false positives and non-existent domains in these public blocklists so we exclude some domains by the following rules.

1. If it's a non-existent domain.

2. If it's already in Jahaslist.

3. If it's in 100,000 well known domain list.

- Go to index -

NxFilter is basically a forwarding, caching DNS server with filtering ability. But you also can use it as an authoritative DNS server.

Authoritative DNS server

NxFilter can be working as an authoritative DNS server.

1. Zone File

2. To put it on the Internet

3. Clustering

To avoid of having DNS attack

When you put NxFilter on the Internet, it can be under a DNS attack. Once you are under a DNS attack you will have massive traffic to your NxFilter. Your NxFilter can't handle all the traffic and eventually it will look like almost dead and you will get error logs about 'Queue full'.

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

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

- Go to index -

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

Creating a cluster

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

Starting NxFilter cluster

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

Load balancing and fail-safe

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

Redundancy for block redireciton

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

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

    block_node_ip = 192.168.0.100

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.

1. Login redirection will not be working

2. Unauthenticated users will be bypassed

3. Multiple server IP addresses with an agent

Access control for a slave node

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

Monitoring the connection state

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

- Go to index -

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

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

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

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

- Go to index -

NxFilter can detect and block malware/botnet activity by analyzing DNS packets. In reality, malwares and botnets are some form of network client or server programs. They are also heavily relying on DNS protocol to find their masters or peers to communicate with or the victims to attack.

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

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

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

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.

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

- Go to index -

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

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

- Go to index -

Although NxFilter is designed to handle several thousand users easily there are several parameters you can adjust to get the best performance.

Memory size

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

    java -Djava.net.preferIPv4Stack=true -Xmx768m

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

Disk space and reducing the amount of log data

NxFilter has various logging/reporting features. These kinds of features require a lot of disk space. When you have a huge size of reporting data your system may experience a performance degrading.

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

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

Increase the number of request handlers

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

    rh_num = 16

Client cache TTL

NxFilter can manipulate client cache TTL. On 'DNS > DNS Setup', there are 'Minimum Cache TTL' and 'Block Cache TTL'. You can increase these values to reduce the amount of DNS queries from your client systems.

To avoid of having 'Database Connection Bottleneck'

In NxFilter clustering, a slave node is supposed to use or share the database of its master node for not having any inconsistency between the nodes. However, when you have busy servers, you can have too many database connections from your slave nodes to your master node and that may degrade the performance.

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

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

    use_local_jahaslist = 1

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

- Go to index -

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

It can be parsed into these values,

- Go to index -

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

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

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

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

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

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

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

- Go to index -

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

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

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

You can enable 'DNS Over HTTPS' on 'DNS > Setup'.

- Go to index -

I can bypass NxFilter by accessing websites using IP address.

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

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

- Go to index -

It doesn't get blocked/unblocked right away.

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

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

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

- Go to index -

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

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

- Go to index -

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

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

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

- Go to index -

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

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

- Go to index -

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

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

- Go to index -

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

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

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

3. Create a policy not blocking anything.

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

- Go to index -

How do I change NxFilter's webserver port?

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

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

After you change the ports, restart NxFilter.

- Go to index -

How do I reset admin password?

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

- Go to index -

Can I bind NxFilter to a specific IP address?

You might want to bind NxFilter to a specific IP address to avoid of having port collision problem. You can bind NxFilter to a specific IP address using 'listen_ip' parameter in '/nxfilter/conf/cfg.properties' file. If you set it to '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.

- Go to index -

How do I bypass my local domain from filtering?

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

- Go to index -

Can I use an exact matching keyword for log search?

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

    ex) [john], [192.168.0.1]

- Go to index -

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

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

- Go to index -

How do I apply my own SSL certificate?

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

- Go to index -

How do I enable debugging?

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

- Go to index -

How do I hide SSL warning?

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.

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

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

- Go to index -

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

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

- Go to index -

How to set up a time zone.

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

- Go to index -

My Browsers keep restarting after NxClient starting.

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

- Go to index -

How do I force a user to logout?

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

- Go to index -

What is 'Queue full' error?

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

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

- Go to index -

How to block porn on Google, Youtube search result?

You can force Safe Search from NxFilter. We have Safe Search option on a policy.

- Go to index -

Can I bypass a specific user from filtering and logging?

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

- Go to index -

Can I install NxFilter on my Active Directory domain controller?

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

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

    listen_ip = 192.168.0.100

- Go to index -

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

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

The daily request number for one user allowed by NxFilter is 3,000. On our statistics so far, one user makes up to 1,000 requests a day. We added 2,000 requests as redundancy on it. So it becomes 3,000 requests a day. For request counting, we only count 'A' type DNS query.

- Go to index -

What is 'Too many requests' error?

We count request number for license protection and you are making more DNS requests than the permitted number by your license. Read How can I calculate the number of users for a commercial license?

- Go to index -

How do I add more users on my license?

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

- Go to index -

My Internet connection gets faster after I install NxFilter.

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

- Go to index -

Can I bypass authentication on NxCloud?

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

Does NxFilter support IPv6?

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

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

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

- Go to index -

How to update it from v3 to v4?

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

    blacklist_type = 5

How do I utilize the public blocklists from the Internet?

As of v4.3.3.7 of NxFilter, you can use the public blocklists from the Internet for filtering. If it's a host file or a file containing domains separated by new lines, you can download and merge it on 'Classifier > Blocklist' overnight automatically. To find out more, read Merging the blocklists from the Internet.

- Go to index -

How do I import users and groups from G Suite LDAP?

You can import users and groups from G Suite LDAP using our OpenLDAP connection setup. To find out more, read Google's GSuite Secure LDAP import to NxFilter.

- Go to index -