Rob Brown


dnsc - IO::Socket::DNS wrapper script


  dnsc --suffix=DNS_Suffix [ options ] <remote_host> [<remote_port>]


dnsc is intended as a demo script for the IO::Socket::DNS module. It creates a TCP tunnel to a dnsd server using only DNS queries. Note that this software is useless without a properly installed dnsd server running somewhere.



The PeerAddr to connect to. This connection will be proxied out through the IO::Socket::DNS::Server server. This setting is required.


The PeerPort to connect to. This <remote_port> specification can also be embedded in the <remote_host> argument after a ":", i.e., If none is specified, then it will just use the listen_port by default. You must specify either remote_port or listen_port.

--suffix <dns_suffix>

Specify domain ending for proxy queries. You can also use the DNS_SUFFIX environment variable instead of commandline option. This setting has no default so must be specified.

--listen_ip <IP.AD.RE.SS>

Which IP Address to listen for incoming connections on listen_port. If none is speficied, then all interfaces ( will be bound.

--listen_port <port>

Specify which port to forward to <remote_host>:<remote_port>. The <listen_ip> specification can also be embedded here by preceding it with a ":", i.e., --listen_port= If none is specified, then it will just default to <remote_port>.


Loop forever. Without this option, it just accepts one connection and exits. You can think of it like this: nc -l <listen_port> -e "nc <remote_host> <remote_port>"

But with --loop enabled, it behaves like the ssh "-L" option, i.e.:

  ssh -L<listen_port>:<remote_host>:<remote_port> ...

And allows multiple connections to be forwarded. Just hit CTRL-C when you want to break out of the --loop and stop forwarding connections.

--password <password>

Use this to connect to a password protected dnsd. None by default.


Enable verbosity to monitor activity or help debugging. This may be specified multiple times to increase verbosity.


Here are some various independent usage examples:

1. Forward a local connection to out through the dnsd tunnel running on dnsc --suffix 8080

2. One connection to will forward to on port 80 through the tunnel: dnsc --suffix --listen 80

3. Forward a connection on port 8888 through a password protected dnsd tunnel: dnsc --listen=8888 --password=LetMeIn 80

4. Assuming there is a SOCKS server running on that is permitted to connect to, this will behave as if the SOCKS server is running locally on port 1080. It will continue looping forever (until you hit CTRL-C) waiting for SOCKS clients to connect: dnsc --loop 1080

5. Forward one connection to port 2222 on localhost to the SSH server on the dnsd machine tunnelled through DNS. And enable verbosity for fun: dnsc -v -v -v --listen=

6. Act like there is an SSH server running here, but when someone connects to it, they end up on instead: export export DNS_PASSWORD=SeCrEt sudo dnsc 22


dnsd, IO::Socket::DNS


Rob Brown, <>


Copyright (C) 2011-2012 by Rob Brown

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.