Skip to content
Switch branches/tags

Build Status

How to use this python script ?

  1. change your dns server to
$ vi /etc/resolve.conf  
  1. restart the network
$ sudo /etc/init.d/networking restart
  1. run the script
$ sudo python -f tcpdns.json.example
  1. stop the daemon process
$ sudo python -s


usage: [-h] -f CONFIG_JSON [-d]


optional arguments:
  -h, --help      show this help message and exit
  -f CONFIG_JSON  Json config file
  -d              Print debug message
  -s              Stop tcp dns proxy daemon

Configuration file

    "socket_timeout": 20,
    "host": "",
    "port": 53,
    "tcp_dns_server": ["",
    "udp_dns_server": [""],
    "enable_server_switch": true,
    "speed_test": true,
    "enable_lru_cache": true,
    "lru_cache_size"  : 500,
    "udp_mode"        : false,
    "daemon_process"  : false,
    "internal_dns_server": [""],
    "internal_domain": ["*intra*"],
    "private_host"    : {"*": ""}
  • enable_server_switch: switch dns servers if network is slow
  • speed_test : test dns server speed on startup
  • enable_lru_cache : use lru cache to store dns server responses
  • udp_mode : use udp dns procotol, default is tcp dns protocol
  • daemon_process : daemon process on *nix platform
  • internal_dns_server : internal dns server on internal network
  • internal_domain : internal domains which use internal dns server to get ip address
  • private_host : like /etc/hosts on *nix platform



python moudules


Super-quick installation

Linux system

  chmod +x ./

Windows system

Use tcpdns.exe in win directory.

Manual Installation

Ubuntu or Debian installation guide

  1. Use the following commands to install python modules

      sudo apt-get install libevent-dev
      sudo apt-get install python-pip
      sudo pip install gevent
      sudo pip install python-daemon
  2. Pull the submodule source code.

      cd Tcp-DNS-proxy
      git submodule update --init --recursive

Windows installation guide

In order to build gevent library you should install Visual Studio, although can run perfectly without python gevent. If you cannot run "C:\Python27\Scripts\pip.exe" in the CMD, you can try "C:\Python27\python.exe -m pip".

  1. Pull the submodule source code.

      cd Tcp-DNS-proxy
      git submodule update --init --recursive
  2. install python 2.7.9

  3. Install pip.exe

    Download from, execute the following commands:

  4. install greenlet

    C:\Python27\Scripts\pip.exe install greenlet
  5. install Microsoft Visual C++ Compiler for Python 2.7

Download link

  1. Install python gevent

    C:\Python27\Scripts\pip.exe install gevent
  2. install pyinstaller

    C:\Python27\Scripts\pip.exe install pyinstaller
  3. execute toexe.bat


This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see