NxFilter Tutorial
Tutorial Index

NxRelay for whole network
NxRelay is a relaying DNS server for NxCloud. With NxRelay, you can associate a private to a user on NxCloud. This means that you can apply policies based on private IPs 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, you will not have a DNS failure. And you will not have an issue with Active Directory integration as all the Active Directory DNS queries will be resolved by your MS DNS server.

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


Installing on Windows
We provide a Windows installer and setup program for NxRelay. It will install NxRelay 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

3. Modify its config parameters in c:/nxrelay/conf/cfg.properties

On CMD,


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


Installing on Linux
1. Download its zip package.

We have an RPM package for NxRelay, To find out more, read Install NxRelay using RPM.

2. Extract it into /nxrelay.

On command line,


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

To stop it,


	sudo systemctl stop nxrelay.service

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


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

For example,


	server = 192.168.0.100
	token = BSYEB28O
	local_dns = 8.8.8.8,8.8.4.4
	local_domain = mydomain.local

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, verify your config values and the connectivity to the server by running /nxrelay/bin/test.sh. Then restart NxRelay and make it as the only DNS server for your network.

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

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


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

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

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

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

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

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

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

    ex) 0 = false, 1 = true

- use_https_query
With this option enabled, NxRelay will do its policy queries over HTTPS.

    ex) 0 = false, 1 = true

- https_query_port
Policy queries over HTTPS will use TCP/443 at default but if you need to use another port you can change it using this parameter.

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

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

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

- radius_accounting_port
The port to which you receive RADIUS accounting requests. We use UDP/1813 at default.

- radius_shared_secret
Shared secret string for your Wi-Fi router to communicate with NxRelay.

- radius_enable_logout
Destroy user login session when the status type of an accounting request is 'Stop'.

    ex) 0 = false, 1 = true

- use_radius
Run RADIUS account server.

    ex) 0 = false, 1 = true


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.


Utility scripts
In /nxrelay/bin  there are several utility scripts included.

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

We have .bat versions of these script for Windows.

For Windows we have 2 more,

  • instsvc.bat : Installing NxRelay service
  • unstsvc.bat : Uninstall NxRelay service

For Ubuntu Linux, we have a systemd script that is /nxrelay/script/nxrelay.service.


Active Directory integration over cloud
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 AD usernames to its server.

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

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

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

But 'Active Directory integration over cloud' is a bit different from when you do 'Active Directory integration' in your local network with NxFilter. 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 his DNS requests appearing with 'myrelay_john100' username on 'Logging > Request'. But if you want to apply a specific policy to 'john100' user, you need to create 'john100' user on your NxCloud operator GUI.

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


User detection by 802.1x WiFi authentication
NxRelay has an integrated RADIUS accounting server module. This module is the same one as the one we use with NxFilter for single sign-on by 802.1x WiFi authentication. But with NxRelay, it will send the usernames it detected to NxCloud. To understand how it works, read Single sign-on by 802.1x