Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ptunnel(8)		     Yellow Lemon Software		    ptunnel(8)

       ptunnel - tunnel	TCP connections	over ICMP echo request/reply packets.

       ptunnel	-p  proxy_address  -lp listen_port -da destination_address -dp
       dest_port [-c network_device] [-v verbosity] [-f	file] [-udp] [-syslog]

       ptunnel [-c network_device] [-v verbosity] [-f file]  [-udp]  [-syslog]
       [-daemon	file]

       ptunnel [-u] [-x	password] [-setuid user] [-setgid group] [-chroot dir]
       [-setcon	context]

       ptunnel -h

       ptunnel is an application that allows you to reliably tunnel  TCP  con-
       nections	 to  a	remote host using ICMP echo request and	reply packets,
       commonly	known as ping requests and  replies.  At  first	 glance,  this
       might  seem like	a rather useless thing to do, but it can actually come
       in handy	in some	cases. The following example illustrates the main  mo-
       tivation	in creating ptunnel:

       Setting:	You're on the go, and stumble across an	open wireless network.
       The network gives you an	IP address, but	won't let you send TCP or  UDP
       packets	out  to	 the  rest of the internet, for	instance to check your
       mail. What to do? By chance, you	discover that the network  will	 allow
       you to ping any computer	on the rest of the internet. With ptunnel, you
       can utilize this	feature	to check your mail, or do  other  things  that
       require TCP.

       Client options:

       -p proxy_address
	      Specify the host on which	the proxy is running.

       -lp listen_port
	      Specifies	 the port on which the client will listen for incoming
	      TCP connections.

       -da destination_addr
	      Specifies	the address to which you want  your  packets  tunneled
	      after  reaching  the proxy when in client	mode, or restricts the
	      destination packets can be forwarded to when in server mode.

       -dp destination_port
	      Specifies/restrict the port that the proxy should	tunnel the TCP
	      connection to.

       Shared options:

       -c network_device
	      Specify the network interface to capture packets from. Note that
	      packet capturing isn't always necessary, but you should try this
	      if you experience	problems with ptunnel.

       -v verbosity
	      Controls	the  verbosity	level. -1 is no	output,	0 shows	errors
	      only, 1 shows info messages, 2 gives  more  output,  3  provides
	      even  more  output, level	4 displays debug info and level	5 dis-
	      plays absolutely everything,  including  the  nasty  details  of
	      sends and	receives.

       -udp   Enables  tunneling over UDP port 53 (DNS)	instead	of using ICMP.
	      This will	only work if your proxy	can accept incoming traffic on
	      port  53,	 and  the  client is able to send data to the proxy on
	      port 53. Note that this option does not wrap ptunnel's  data  in
	      DNS-compliant  packets.  This  option  must be given on both the
	      proxy and	client side for	things to work correctly.

       -syslog (Not available on Windows.)
	      Changes logging to use the built-in syslog fascility.

       -daemon file (Not available on Windows.)
	      Run in background, writing PID in	file.

       -u     Attempts to run ptunnel without privileges. This doesn't usually
	      work!  On	UNIX systems please consider using the following three
	      options instead:

       -setuid user (Not available on Windows.)
	      When started in privileged mode, drop down to user's  rights  as
	      soon as possible.

       -setgid group (Not available on Windows.)
	      When  started in privileged mode,	drop down to group's rights as
	      soon as possible.

       -chroot dir (Not	available on Windows.)
	      When started in privileged mode, restrict	 file  access  to  the
	      specified	directory.

       -setcon context (Not available on Windows.)
	      Set SELinux context when all there is left to do are network I/O
	      operations.  In order to be able to  combine  with  -chroot  you
	      will have	to `mount --bind /proc /chrootdir/proc`

       -x password
	      Specifies	 a  password or	passphrase to use. This	will allow you
	      to protect the proxy from	use by others who don't	know the pass-
	      word. It needs to	be specified on	both proxy and client.

       -f file
	      Specifies	 a  log	file. If you specify -syslog, syslog is	always
	      used instead.

       -h     Displays brief usage information.

       The following assumes that ptunnel is run as root, both	on  the	 proxy
       and  client.  To	 tunnel	 ssh connections from the client machine via a
       proxy running on to	the computer,
       the following command line would	be used:

       ptunnel -p -lp 8000	-da -dp 22

       An  ssh	connection  to	can now	be established as fol-

       ssh -p 8000 localhost

       If ssh complains	about potential	man-in-the-middle attacks, simply  re-
       move  the offending key from the	known_hosts file. The warning/error is
       expected	if you have previously ssh'd to	your local computer (i.e., ssh
       localhost), or you have used ptunnel to forward ssh connections to dif-
       ferent hosts.

       Of course, for all of this to work, you need to start the proxy on your
       proxy-computer ( Doing this is very simple:


       If  you	find  that  the	 proxy	isn't working, you will	need to	enable
       packet capturing	on the main network device. Currently this  device  is
       assumed	to  be an ethernet-device (i.e., ethernet or wireless).	Packet
       capturing is enabled by giving the -c switch, and supplying the	device
       name  to	 capture  packets on (for instance eth0	or en1). The same goes
       for the client. On Mac OS X, packet capturing must  always  be  enabled
       (both for proxy and client), as resent packets won't be received	other-

       To protect yourself from	others using your proxy, you can  protect  ac-
       cess  to	 it with a password using the <tt>-x</tt> switch. The password
       is never	sent in	the clear, but keep in mind that  it  may  be  visible
       from  tools  like top or	ps, which can display the command line used to
       start an	application.

       ptunnel does not	exit until forced to do	so by an interrupt (Ctrl-C) or
       if it crashes.

       ptunnel	currently  does	 not handle packet capturing on	network	inter-
       faces other than	ethernet or wireless correctly.

       Daniel Stoedle (

       Windows port: Mike Miller (

       SELinux support:	Sebastien Raveau (

       Patches:	Joe McKenzie, Steffen Wendzel and StalkR.

       ptunnel is licensed under the BSD License.

       The ptunnel homepage is currently located here:

       The freshmeat project page is located here:

       Please take the time to rate ptunnel if you find	it useful. Thanks!

Version	0.72		       September 5, 2011		    ptunnel(8)


Want to link to this manual page? Use this URL:

home | help