Longer Socat examples are now splitted into two or three lines; improved CSS
diff --git a/CHANGES b/CHANGES
index cd7b5ef..09231a8 100644
--- a/CHANGES
+++ b/CHANGES
@@ -77,12 +77,15 @@
Syntax and semantics of some options (esp.unlink-close) were not clear.
Thanks to Anthony Chavez for reporting this and making suggestions.
-Documentation:
socat-tun.html described TCP as tunnel medium but this does not keep
packet boundaries. Changed to UDP.
Added examples for DCCP client and server.
+ Complex Socat examples are now displayed in two or three lines for
+ better overview.
+ dest-unreach.css stylesheet has been improved to support this.
+
Testing:
Idea: EXEC,SYSTEM addresses can keep packet boundaries when option
socktype=<val-of-SOCK_DGRAM>
diff --git a/EXAMPLES b/EXAMPLES
index 83d38de..51b10ff 100644
--- a/EXAMPLES
+++ b/EXAMPLES
@@ -5,84 +5,104 @@
//"$" means normal user, "#" requires privileges, "//" starts a comment
///////////////////////////////////////////////////////////////////////////////
-// similar to netcat
+// Similar to netcat
-// connect to 10.1.1.1 on port 80 and relay to and from stdio
+// Connect to 10.1.1.1 on port 80 and relay to and from stdio
$ socat - TCP:10.1.1.1:80 # similar to "netcat 10.1.1.1 80"
-// listen on port 25, wait for an incoming connection, use CR+NL on this
+// Listen on port 25, wait for an incoming connection, use CR+NL on this
// connection, relay data to and from stdio;
// then emulate a mailserver by hand :-)
# socat - TCP-LISTEN:25,crlf
-// listen on port 25, wait for an incoming connection, use CR+NL on this
+// Listen on port 25, wait for an incoming connection, use CR+NL on this
// connection, relay data to and from stdio, but have line editing and history;
// then emulate a mailserver by hand :-)
-# socat readline TCP-LISTEN:25,crlf
+# socat READLINE TCP-LISTEN:25,crlf
-// provide a transient history enabled front end to stupid line based
+// Provide a transient history enabled front end to stupid line based
// interactive programs
-$ socat readline exec:"nslookup",pty,ctty,setsid,echo=0
-// same works for ftp (but password is not hidden)
+$ socat \
+ READLINE \
+ EXEC:"nslookup",pty,ctty,setsid,echo=0
+// Same works for ftp (but password is not hidden)
-// you may also use a file based history list
-$ socat readline,history=.nslookup_hist exec:"nslookup",pty,ctty,setsid,echo=0
-// using ~ as abbreviation for $HOME does not work!
+// You may also use a file based history list
+$ socat \
+ READLINE,history=.nslookup_hist \
+ EXEC:"nslookup",pty,ctty,setsid,echo=0
+// Using ~ as abbreviation for $HOME does not work!
-// poor mans 'telnetd' replacement
-# socat tcp-l:2023,reuseaddr,fork exec:/bin/login,pty,setsid,setpgid,stderr,ctty
+// Poor mans 'telnetd' replacement
+# socat \
+ TCP-L:2023,reuseaddr,fork \
+ EXEC:/bin/login,pty,setsid,setpgid,stderr,ctty
// and here an appropriate client:
-$ socat -,raw,echo=0 tcp:172.16.181.130:2023
-// use ssl with client and server certificate for improved security;
+$ socat \
+ -,raw,echo=0 \
+ TCP:172.16.181.130:2023
+// Use ssl with client and server certificate for improved security;
// replace /bin/login by /bin/bash when using SSL client authentication, can be
// run without root then
-// this is a cool trick, proposed by Christophe Lohr, to dump communications to
+// This is a cool trick, proposed by Christophe Lohr, to dump communications to
// two files; it would also work for other manipulations (recode, compress...)
// and it might also work with netcat ;-)
-$ socat TCP-LISTEN:5555 SYSTEM:'tee l2r | socat - "TCP:remote:5555" | tee r2l'
+$ socat \
+ TCP-LISTEN:5555 \
+ SYSTEM:'tee l2r | socat - "TCP:remote:5555" | tee r2l'
///////////////////////////////////////////////////////////////////////////////
-// emergence solution because usleep(1) is not always available
+// Emergence solution because usleep(1) is not always available
// this will "sleep" for 0.1s
-$ socat -T 0.1 pipe pipe
+$ socat -T 0.1 PIPE PIPE
///////////////////////////////////////////////////////////////////////////////
-// a very primitive HTTP/1.0 echo server (problems: sends reply headers before
+// A very primitive HTTP/1.0 echo server (problems: sends reply headers before
// request; hangs if client does not shutdown - HTTP keep-alive)
// wait for a connection on port 8000; do not wait for request, but immediately
// start a shell that sends reply headers and an empty line; then echo all
// incoming data back to client
-$ socat TCP-LISTEN:8000,crlf SYSTEM:"echo HTTP/1.0 200; echo Content-Type\: text/plain; echo; cat"
+$ socat \
+ TCP-LISTEN:8000,crlf \
+ SYSTEM:"echo HTTP/1.0 200; echo Content-Type\: text/plain; echo; cat"
-// a less primitive HTTP echo server that sends back not only the reqest but
+// A less primitive HTTP echo server that sends back not only the reqest but
// also server and client address and port. Might have portability issues with
// echo
-./socat -T 1 -d -d tcp-l:10081,reuseaddr,fork,crlf system:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/html\\\n\\\n<html>date: \$\(date\)<br>server:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT<br>client: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n<pre>\\\"\"; cat; echo -e \"\\\"\\\n</pre></html>\\\"\""
+$ socat -T 1 -d -d \
+ TCP-L:10081,reuseaddr,fork,crlf \
+ SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/html\\\n\\\n<html>date: \$\(date\)<br>server:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT<br>client: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n<pre>\\\"\"; cat; echo -e \"\\\"\\\n</pre></html>\\\"\""
///////////////////////////////////////////////////////////////////////////////
-// for communicating with an attached modem, I had reasonable results with
+// For communicating with an attached modem, I had reasonable results with
// following command line. Required privileges depend on device mode.
-// after leaving socat, type "sane".
-// replace /dev/ttyS0 by the correct serial line or with /dev/modem
-$ socat readline /dev/ttyS0,raw,echo=0,crlf
+// After leaving socat, type "sane".
+// Replace /dev/ttyS0 by the correct serial line or with /dev/modem
+$ socat \
+ READLINE \
+ /dev/ttyS0,raw,echo=0,crlf
// or
-$ socat readline /dev/ttyS0,raw,echo=0,crlf,nonblock
+$ socat \
+ READLINE \
+ /dev/ttyS0,raw,echo=0,crlf,nonblock
// then enter "at$"
///////////////////////////////////////////////////////////////////////////////
-// relay TCP port 80 from everywhere (internet, intranet, dmz) through your
+// Relay TCP port 80 from everywhere (internet, intranet, dmz) through your
// firewall to your DMZ webserver (like plug-gw)
-// listen on port 80; whenever a connection is made, fork a new process (parent
-// process keeps accepting connections), su to nobody, and connect to
+// Listen on port 80; whenever a connection is made, fork a new process (parent
+// Process keeps accepting connections), su to nobody, and connect to
// www.dmz.mydomain.org on port 80.
-// attention: this is a substitute for a reverse proxy without providing
+// Attention: this is a substitute for a reverse proxy without providing
// application level security.
-# socat TCP-LISTEN:80,reuseaddr,fork,su=nobody TCP:www.dmz.mydomain.org:80
+# socat \
+ TCP-LISTEN:80,reuseaddr,fork,su=nobody \
+ TCP:www.dmz.mydomain.org:80
// Note: parent process keeps running as root, su after forking
///////////////////////////////////////////////////////////////////////////////
-// relay mail from your DMZ server through your firewall.
+// Relay mail from your DMZ server through your firewall.
// accept connections only on dmz interface and allow connections only from
// smtp.dmz.mydomain.org.
// the advantages over plug-gw and other relays are:
@@ -91,49 +111,59 @@
// to each, making several application servers addressable
// * lots of options, like switching user, chroot, IP performance tuning
// * no need for inetd
-# socat -lm -d -d TCP-LISTEN:25,bind=fw.dmz.mydomain.org,fork,su=nobody,range=smtp.dmz.mydomain.org/32 TCP:smtp.intra.mydomain.org:25
+# socat -lm -d -d \
+ TCP-LISTEN:25,bind=fw.dmz.mydomain.org,fork,su=nobody,range=smtp.dmz.mydomain.org/32 \
+ TCP:smtp.intra.mydomain.org:25
///////////////////////////////////////////////////////////////////////////////
-// convert line terminator in ascii streams, stdin to stdout
+// Convert line terminator in ascii streams, stdin to stdout
// use unidirectional mode, convert nl to crnl
$ socat -u - -,crlf
// or cr to nl
$ socat -u -,cr -
-// save piped data similar to 'tee':
+// Save piped data similar to 'tee':
// copies stdin to stdout, but writes everything to the file too
-$ socat -,echo=0 open:/tmp/myfile,create,trunc,ignoreeof!!/tmp/myfile
+$ socat \
+ -,echo=0 \
+ OPEN:/tmp/myfile,create,trunc,ignoreeof!!/tmp/myfile
///////////////////////////////////////////////////////////////////////////////
-// intrusion testing
+// Intrusion testing
-// found an XWindow Server behind IP filters with FTP data hole? (you are
+// Found an XWindow Server behind IP filters with FTP data hole? (you are
// lucky!)
// prepare your host:
# rm -f /tmp/.X11-unix/X1
// relay a pseudo display :1 on your machine to victim:0
-# socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork TCP:host.victim.org:6000,sp=20 &
+# socat \
+ UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
+ TCP:host.victim.org:6000,sp=20 &
// and try to take a screendump (must be very lucky - when server has not even
// host based authentication!)
# xwd -root -display :1 -silent >victim.xwd
-// you sit behind a socks firewall that has IP filters but lazily allows socks
+// You sit behind a socks firewall that has IP filters but lazily allows socks
// connections to loopback and has only host based X11 security.
// like above, but from your inside client:
-# socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork SOCKS4:firewall:loopback:6000
+# socat \
+ UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
+ SOCKS4:firewall:loopback:6000
// or for the HTTP proxy:
-# socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork PROXY:firewall:loopback:6000
+# socat \
+ UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
+ PROXY:firewall:loopback:6000
///////////////////////////////////////////////////////////////////////////////
// forms of stdin with stdout, all equivalent
-$ socat echo -
-$ socat echo STDIO
-$ socat echo STDIN!!STDOUT
-$ socat echo STDIO!!STDIO
-$ socat echo -!!-
-$ socat echo FD:0!!FD:1
-$ socat echo 0!!1
-$ socat echo /dev/stdin!!/dev/stdout // if your OS provides these
+$ socat PIPE -
+$ socat PIPE STDIO
+$ socat PIPE STDIN!!STDOUT
+$ socat PIPE STDIO!!STDIO
+$ socat PIPE -!!-
+$ socat PIPE FD:0!!FD:1
+$ socat PIPE 0!!1
+$ socat PIPE /dev/stdin!!/dev/stdout // when your OS provides these
///////////////////////////////////////////////////////////////////////////////
// some echo address examples
@@ -153,9 +183,9 @@
///////////////////////////////////////////////////////////////////////////////
// unidirectional data transfer
$ socat -u - -
-// like "tail -f", but start with showing all file contents
+// like "tail -f", but start with showing all file contents:
$ socat -u FILE:/var/log/syslog.debug,ignoreeof -
-// like "tail -f", but do not show existing file contents
+// like "tail -f", but do not show existing file contents:
$ socat -u FILE:/var/log/syslog.debug,ignoreeof,seek-end -
// write to new file, create with given permission and group (must be member) - race condition with group!!!
$ socat -u - CREATE:/tmp/outfile1,group=floppy,perm=0640
@@ -165,26 +195,28 @@
///////////////////////////////////////////////////////////////////////////////
-// file handling
+// File handling
$ socat - FILE:/tmp/outfile1,ignoreeof!!FILE:/tmp/outfile1,append // prints outfile1, then echoes input and protocols into file (appends to old data)
///////////////////////////////////////////////////////////////////////////////
-// unix socket handling
+// UNIX socket handling
-// create a listening unix socket
+// Create a listening unix socket
$ rm -f /tmp/mysocket; socat UNIX-LISTEN:/tmp/mysocket -
-// from another terminal, connect to this socket
+// From another terminal, connect to this socket
$ socat UNIX:/tmp/mysocket -
// then transfer data bidirectionally
///////////////////////////////////////////////////////////////////////////////
-// transport examples
+// Transport examples
-// socks relay (externally socksify applications);
+// Socks relay (externally socksify applications);
// your ssh client and OS are not socksified, but you want to pass a socks
// server with ssh:
-$ socat TCP-LISTEN:10022,fork SOCKS4:socks.mydomain.org:ssh-serv:22
+$ socat \
+ TCP-LISTEN:10022,fork \
+ SOCKS4:socks.mydomain.org:ssh-serv:22
$ ssh -p 10022 loopback
// or better define a ProxyCommand in ~/.ssh/config:
ProxyCommand socat - SOCKS:socks.mydomain.org:%h:%p
@@ -192,127 +224,153 @@
ProxyCommand socat - PROXY:proxy.mydomain.org:%h:%p,proxyport=8000
///////////////////////////////////////////////////////////////////////////////
-// application examples
+// Application examples
// run sendmail daemon with your favorite network options
-# socat TCP-LISTEN:25,fork,ip-ttl=4,ip-tos=7,tcp-maxseg=576 EXEC:"/usr/sbin/sendmail -bs",nofork
+# socat \
+ TCP-LISTEN:25,fork,ip-ttl=4,ip-tos=7,tcp-maxseg=576 \
+ EXEC:"/usr/sbin/sendmail -bs",nofork
-// local mail delivery over UNIX socket - no SUID program required
-# socat UNIX-LISTEN:/tmp/postoffice,fork,perm-early=0666 EXEC:"/usr/sbin/sendmail -bs"
+// Local mail delivery over UNIX socket - no SUID program required
+# socat \
+ UNIX-LISTEN:/tmp/postoffice,fork,perm-early=0666 \
+ EXEC:"/usr/sbin/sendmail -bs"
$ socat - /tmp/postoffice
///////////////////////////////////////////////////////////////////////////////
-// uses of filan
-// see what your operating system opens for you
+// Uses of filan
+// See what your operating system opens for you
$ filan
// or if that was too detailled
$ filan -s
-// see what file descriptors are passed via exec function
-$ socat - EXEC:filan,nofork
-$ socat - EXEC:filan
-$ socat - EXEC:filan,pipes,stderr
-$ socat - EXEC:filan,pipes
-$ socat - EXEC:filan,pty
+// See what file descriptors are passed via exec function
+$ socat - EXEC:"filan -s",nofork
+$ socat - EXEC:"filan -s"
+$ socat - EXEC:"filan -s",pipes,stderr
+$ socat - EXEC:"filan -s",pipes
+$ socat - EXEC:"filan -s",pty
// see what's done by your shell and with option "pipes"
-$ socat - SYSTEM:filan,pipes
+$ socat - SYSTEM:"filan -s",pipes
// see if gdb gives you an equivalent environment or opens some files for your program
$ gdb ./filan
-(gdb) r
(gdb) r -s
+(gdb) r
///////////////////////////////////////////////////////////////////////////////
-// want to use chat from the ppp package?
-// note: some OS's do not need "-e" for echo to print control characters
-// note: chat might send bytes one by one
-// with AIX, a similar program is available under the name "pppdial"
-$ socat -d -d tcp:localhost:25,crlf,nodelay exec:'/usr/sbin/chat -v -s "\"220 \"" "\"HELO loopback\"" "\"250 \"" "\"MAIL FROM: <hugo@localhost>\"" "\"250 \"" "\"RCPT TO: root\"" "\"250 \"" "\"DATA\"" "\"354 \"" "\"test1'$(echo -e "\r.")'\"" "\"250 \"" "\"QUIT\"" "\"221 \""',pty,echo=0,cr
+// Want to use chat from the ppp package?
+// Note: some OS's do not need "-e" for echo to print control characters
+// Note: chat might send bytes one by one
+// With AIX, a similar program is available under the name "pppdial"
+$ socat -d -d \
+ TCP:localhost:25,crlf,nodelay \
+ EXEC:'/usr/sbin/chat -v -s "\"220 \"" "\"HELO loopback\"" "\"250 \"" "\"MAIL FROM: <hugo@localhost>\"" "\"250 \"" "\"RCPT TO: root\"" "\"250 \"" "\"DATA\"" "\"354 \"" "\"test1'$(echo -e "\r.")'\"" "\"250 \"" "\"QUIT\"" "\"221 \""',pty,echo=0,cr
//////////////////////////////////////////////////////////////////////////////
// IP6
-# socat readline TCP6:[::1]:21 # if your inetd/ftp is listening on ip6
+# socat \
+ READLINE \
+ TCP6:[::1]:21 # if your inetd/ftp is listening on ip6
//////////////////////////////////////////////////////////////////////////////
// VSOCK
-# start a linux VM with cid=21
+# Start a linux VM with cid=21
# qemu-system-x86_64 -m 1G -smp 2 -cpu host -M accel=kvm \
# -drive if=virtio,file=/path/to/fedora.img,format=qcow2 \
# -device vhost-vsock-pci,guest-cid=21
# guest listens on port 1234 and host connects to it
-guest$ socat - vsock-listen:1234
-host$ socat - vsock-connect:21:1234
+guest$ socat - VSOCK-LISTEN:1234
+host$ socat - VSOCK-CONNECT:21:1234
-# host (well know CID_HOST = 2) listens on port 4321 and guest connects to it
-host$ socat - vsock-listen:4321
-guest$ socat - vsock-connect:2:4321
+# Host (well know CID_HOST = 2) listens on port 4321 and guest connects to it
+host$ socat - VSOCK-LISTEN:4321
+guest$ socat - VSOCK-CONNECT:2:4321
///////////////////////////////////////////////////////////////////////////////
-// application server solutions
-// run a program (here: /bin/sh) chrooted, unprivileged;
+// Application server solutions
+// Run a program (here: /bin/sh) chrooted, unprivileged;
// parent process stays in real / running as root
# socat -d -d - EXEC:/bin/sh,chroot=/home/sandbox,su=sandbox,pty
-// make a program available on the network chrooted, unprivileged;
+// Make a program available on the network chrooted, unprivileged;
// parent process stays in / running as root
// script path is already chrooted
-# ./socat -lm -d -d TCP-LISTEN:5555,fork EXEC:/bin/myscript,chroot=/home/sandbox,su=sandbox,pty,stderr
-// to avoid terminal problems, you might - instead of telnet - connect using
-$ socat -,icanon=0,echo=0 tcp:target:5555; reset
+# ./socat -lm -d -d \
+ TCP-LISTEN:5555,fork \
+ EXEC:/bin/myscript,chroot=/home/sandbox,su=sandbox,pty,stderr
+// To avoid terminal problems, you might - instead of telnet - connect using
+$ socat \
+ -,icanon=0,echo=0 \
+ TCP:target:5555; reset
-// access local display from ssh server, when ssh port forwarding is disabled
-// socat must be installed on ssh server host
-// might have to use xauth...
-// this example is one-shot because ssh can handle only one channel
-xterm1$ socat -d -d exec:"ssh www.dest-unreach.org rm -f /tmp/.X11-unix/X9; ~/bin/socat -d -d unix-l\:/tmp/.X11-unix/X9\,fork -" unix:/tmp/.X11-unix/X0
+// Access local display from ssh server, when ssh port forwarding is disabled
+// Socat must be installed on ssh server host
+// Might have to use xauth...
+// This example is one-shot because ssh can handle only one channel
+xterm1$ socat -d -d \
+ EXEC:"ssh www.dest-unreach.org rm -f /tmp/.X11-unix/X9; ~/bin/socat -d -d unix-l\:/tmp/.X11-unix/X9\,fork -" \
+ UNIX:/tmp/.X11-unix/X0
xterm2$ ssh target
target$ DISPLAY=:9 myxapplication
-// touch with perms:
+// Touch with perms:
// no race condition for perms (applied with creat() call)
-$ socat -u /dev/null creat:/tmp/tempfile,perm=0600
+$ socat -u \
+ /dev/null \
+ CREAT:/tmp/tempfile,perm=0600
-// touch with owner and perms:
+// Touch with owner and perms:
// race condition before changing owner, but who cares - only root may access
-# socat -u /dev/null creat:/tmp/tempfile,user=user1,perm=0600
+# socat -u \
+ /dev/null \
+ CREAT:/tmp/tempfile,user=user1,perm=0600
-// invoke an interactive ssh with exec
-// first example passes control chars (^C etc.) to remote server as usual
-socat -,echo=0,raw exec:'ssh server',pty,setsid,ctty
-// second example interprets control chars on local command line
-socat -,echo=0,icanon=0 exec:'ssh server',pty,setsid,ctty
+// Invoke an interactive ssh with EXEC
+// First example passes control chars (^C etc.) to remote server as usual
+socat \
+ -,echo=0,raw \
+ EXEC:'ssh server',pty,setsid,ctty
+// Second example interprets control chars on local command line
+socat \
+ -,echo=0,icanon=0 \
+ EXEC:'ssh server',pty,setsid,ctty
// afterwards, type "reset"!
-// convince ssh to provide an "interactive" shell to your script
+// Convince ssh to provide an "interactive" shell to your script
// three main versions for entering password:
// 1) from your TTY; have 10 seconds to enter password:
-(sleep 10; echo "ls"; sleep 1) |socat - exec:'ssh server',pty
+(sleep 10; echo "ls"; sleep 1) |socat - EXEC:'ssh server',pty
// 2) from XWindows (DISPLAY !); again 10 seconds
-(sleep 10; echo "ls"; sleep 1) |socat - exec:'ssh server',pty,setsid
+(sleep 10; echo "ls"; sleep 1) |socat - EXEC:'ssh server',pty,setsid
// 3) from script
-(sleep 5; echo PASSWORD; echo ls; sleep 1) |./socat - exec:'ssh server',pty,setsid,ctty
+(sleep 5; echo PASSWORD; echo ls; sleep 1) |./socat - EXEC:'ssh server',pty,setsid,ctty
-// download with proxy CONNECT
+// Download with proxy CONNECT
// use echo -e if required for \n
-$ (echo -e "CONNECT 128.129.130.131:80 HTTP/1.0\n"; sleep 5; echo -e "GET
-/download/file HTTP/1.0\n"; sleep 10) |socat -d -d -t 3600 - tcp:proxy:8080,crlf
+$ (echo -e "CONNECT 128.129.130.131:80 HTTP/1.0\n"; sleep 5; echo -e "GET /download/file HTTP/1.0\n"; sleep 10) |
+socat -d -d -t 3600 - tcp:proxy:8080,crlf
-// retrieve a file from an sshd site with sourceforge style entry menu;
+// Retrieve a file from an sshd site with sourceforge style entry menu;
// fill in your personal values; cat lets you enter your password (will be
// visible on screen)
-$ (sleep 10; read pass; echo $pass; sleep 10; echo M; sleep 5; echo cat FILENAME; sleep 10) |./socat -d -d -ly - EXEC:'ssh -c 3des -l USER cf.sourceforge.net',pty,setsid,ctty |tee FILENAME
+$ (sleep 10; read pass; echo $pass; sleep 10; echo M; sleep 5; echo cat FILENAME; sleep 10) |
+./socat -d -d -ly - EXEC:'ssh -c 3des -l USER cf.sourceforge.net',pty,setsid,ctty |
+tee FILENAME
-// multicast community on local network: start the following command on all
+// Multicast community on local network: start the following command on all
// participating hosts; like a conference call:
-# socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0,bindtodevice=eth0
+# socat -d -d -d -d - \
+ UDP-DATAGRAM:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0,bindtodevice=eth0
// or
-$ socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0
-// possible reasons for failure:
+$ socat -d -d -d -d - \
+ UDP-DATAGRAM:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0
+// Possible reasons for failure:
// iptables or other filters (open your filters as required)
-// packets leave via wrong interface (set route: ...)
-// socket bound to specific address
+// Packets leave via wrong interface (set route: ...)
+// Socket bound to specific address
//=============================================================================
// GENERIC FUNCTION CALLS
@@ -320,59 +378,79 @@
// ioctl(): open CD drive (given value valid on Linux)
// on my Linux system I find in /usr/include/linux/cdrom.h the define:
// #define CDROMEJECT 0x5309 /* Ejects the cdrom media */
-// the following command makes something like ioctl(fd, CDROMEJECT, NULL)
+// The following command makes something like ioctl(fd, CDROMEJECT, NULL)
// (don't care about the read error):
$ socat /dev/cdrom,o-nonblock,ioctl-void=0x5309 -
// setsockopt(): SO_REUSEADDR
-// the following command performs - beyond lots of overhead - something like:
+// The following command performs - beyond lots of overhead - something like:
// myint=1; setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &myint, sizeof(myint))
-$ socat -u udp-recv:7777,setsockopt-int=1:2:1 -
+$ socat -u UDP-RECV:7777,setsockopt-int=1:2:1 -
// setsockopt(): SO_BINDTODEVICE
-// ways to apply SO_BINDTODEVICE without using the special socat address option
+// Ways to apply SO_BINDTODEVICE without using the special socat address option
// so-bindtodevice:
// with string argument:
-$ sudo ./socat tcp-l:7777,setsockopt-string=1:25:eth0 pipe
+$ sudo socat TCP-L:7777,setsockopt-string=1:25:eth0 PIPE
// with binary argument:
-$ sudo ./socat tcp-l:7777,setsockopt-bin=1:25:x6574683000 pipe
+$ sudo socat TCP-L:7777,setsockopt-bin=1:25:x6574683000 PIPE
===============================================================================
-// not tested, just ideas, or have problems
+// Not tested, just ideas, or have problems
-// traverse firewall for making internal telnet server accessible for outside
+// Traverse firewall for making internal telnet server accessible for outside
// telnet client, when only outbound traffic (syn-filter) is allowed:
// on external client run "double server". this process waits for a
// connection from localhost on port 10023, and, when it is established, waits
// for a connection from anywhere to port 20023:
-ext$ socat -d TCP-LISTEN:10023,range=localhost TCP-LISTEN:20023
+ext$ socat -d \
+ TCP-LISTEN:10023,range=localhost \
+ TCP-LISTEN:20023
// on internal server run double client:
-int$ socat -d TCP:localhost:23 TCP:extclient:10023
+int$ socat -d \
+ TCP:localhost:23 \
+ TCP:extclient:10023
// or, with socks firewall:
-int$ socat -d TCP:localhost:23 SOCKS:socksserver:extclient:10023
+int$ socat -d \
+ TCP:localhost:23 \
+ SOCKS:socksserver:extclient:10023
// login with:
ext$ telnet localhost 20023
-// you can make a double server capable of handling multiple instances:
-ext$ socat -d TCP-LISTEN:10023,range=localhost,fork TCP-LISTEN:20023,reuseaddr
+// YOU can make a double server capable of handling multiple instances:
+ext$ socat -d \
+ TCP-LISTEN:10023,range=localhost,fork \
+ TCP-LISTEN:20023,reuseaddr
-// access remote display via ssh, when ssh port forwarding is disabled
-$ socat -d -d EXEC:"ssh target socat - UNIX:/tmp/.X11-unix/X0" TCP-LISTEN:6030
+// Access remote display via ssh, when ssh port forwarding is disabled
+$ socat -d -d \
+ EXEC:"ssh target socat - UNIX:/tmp/.X11-unix/X0" \
+ TCP-LISTEN:6030
$ xclock -display localhost:30
-// relay multiple webserver addresses through your firewall into your DMZ:
-// make IP aliases on your firewall, and then:
-# socat -d -d TCP-L:80,bind=fw-addr1,fork TCP:dmz-www1:80
-# socat -d -d TCP-L:80,bind=fw-addr2,fork TCP:dmz-www2:80
+// Relay multiple webserver addresses through your firewall into your DMZ:
+// Make IP aliases on your firewall, and then:
+# socat -d -d \
+ TCP-L:80,bind=fw-addr1,fork \
+ TCP:dmz-www1:80
+# socat -d -d \
+ TCP-L:80,bind=fw-addr2,fork \
+ TCP:dmz-www2:80
// and for improved security:
-# socat -d -d TCP-L:80,bind=fw-addr3,su=nobody,fork TCP:dmz-www3:80
+# socat -d -d \
+ TCP-L:80,bind=fw-addr3,su=nobody,fork \
+ TCP:dmz-www3:80
-// proxy an arbitrary IP protocol over your firewall (answers won't work)
-# socat -d -d IP:0.0.0.0:150,bind=fwnonsec IP:sec-host:150,bind=fwsec
+// Proxy an arbitrary IP protocol over your firewall (answers won't work)
+# socat -d -d \
+ IP:0.0.0.0:150,bind=fwnonsec \
+ IP:sec-host:150,bind=fwsec
-// proxy an unsupported IP protocol over your firewall, point to point
+// Proxy an unsupported IP protocol over your firewall, point to point
// end points see firewall interfaces as IP peers!
-# socat -d -d IP:nonsec-host:150,bind=fwnonsec IP:sec-host:150,bind=fwsec
+# socat -d -d \
+ IP:nonsec-host:150,bind=fwnonsec \
+ IP:sec-host:150,bind=fwsec
// note that, for IPsec, you might face problems that are known with NAT
diff --git a/doc/dest-unreach.css b/doc/dest-unreach.css
index 61a8dac..0f37c54 100644
--- a/doc/dest-unreach.css
+++ b/doc/dest-unreach.css
@@ -1,9 +1,28 @@
table {
- empty-cells:show;
+ empty-cells: show;
}
-.frame { border-style:solid; border-width:4px; border-color:black; }
-.shell { font-family:Courier;
- padding:2px; padding-left:6px; padding-right:6px;
- border-style:solid; border-width:1px; border-color:gray;
- color:lightgreen; background-color:black;
+
+.shell {
+ display: block;
+ font-family: Courier;
+ padding: 6px;
+ padding-top: 10px;
+ padding-bottom: 4px;
+ border: 3px solid grey;
+ color: lightgreen;
+ background-color: black;
+ text-align: left;
+ white-space: pre;
+}
+
+.error {
+ display: inline;
+ block-size: auto;
+ font-family: monospace;
+ background-color: #e08080;
+ border: 4px;
+ padding: 2px;
+ padding-right: 4px;
+ border-style: ridge;
+ border-color: #e08080;
}
diff --git a/doc/socat-genericsocket.html b/doc/socat-genericsocket.html
index c30a8db..0525696 100644
--- a/doc/socat-genericsocket.html
+++ b/doc/socat-genericsocket.html
@@ -62,17 +62,19 @@
returns it to the client:
</p>
-<span class="frame"><span class="shell">
-socat TCP4-LISTEN:4096,reuseaddr,type=6,prototype=33 exec:'tr A-Z a-z',pty,raw,echo=0
-</span></span>
+<span class="shell">socat \
+ TCP4-LISTEN:4096,reuseaddr,type=6,prototype=33 \
+ EXEC:'tr A-Z a-z',pty,raw,echo=0
+</span>
<p>A simple client that sends some upper case characters to the server via DCCP
and prints what the server returns:
</p>
-<span class="frame"><span class="shell">
-echo ABCD |socat - TCP4-CONNECT:localhost:4096,type=6,prototype=33
-</span></span>
+<span class="shell">echo ABCD | \
+ socat - \
+ TCP4-CONNECT:localhost:4096,type=6,prototype=33
+</span>
<p>We choose the TCP4 addresses as base because it best matches the DCCP
requirements:
@@ -98,7 +100,7 @@
If the service codes on server and client do not match the <tt>connect()</tt>
operation fails with error:<p>
-<table border="1" bgcolor="e08080"><tr><td><tt>... E connect(3, AF=2 127.0.0.1:4096, 16): Invalid request code</tt></td></tr></table>
+<span class="error">... E connect(3, AF=2 127.0.0.1:4096, 16): Invalid request code</span>
<p>Please note that this examples works with IPv6 as well, you just need to
replace the TCP4 words with TCP6, and the IPv4 socket address with an
@@ -132,20 +134,18 @@
ping command:
</p>
-<span class="frame"><span class="shell">
-aecho 65280.243
-</span></span>
+<span class="shell">aecho 65280.243
+</span>
<p>If you get an error like:
</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>Device or resource busy</tt></td></tr></table>
+<span class="error">Device or resource busy</span>
<p>then try to restart <tt>atalkd</tt>:</p>
-<span class="frame"><span class="shell">
-/etc/init.d/atalkd restart
-</span></span>
+<span class="shell">/etc/init.d/atalkd restart
+</span>
<p>When <tt>aecho</tt> works like <tt>ping</tt> you are ready for the next step.
</p>
@@ -155,17 +155,19 @@
<p>We start a socat process with a receiver and echo service:
</p>
-<span class="frame"><span class="shell">
-socat SOCKET-RECVFROM:5:2:0:x40x00x0000x00x00x0000000000000000 PIPE
-</span></span>
+<span class="shell">socat \
+ SOCKET-RECVFROM:5:2:0:x40x00x0000x00x00x0000000000000000 \
+ PIPE
+</span>
<p>Then, in another shell on the same host, we start a client socket process
that sends data to the server and gets the answer:
</p>
-<span class="frame"><span class="shell">
-echo ABCD |socat - SOCKET-DATAGRAM:5:2:0:x40x00xff00xf3x00x0000000000000000
-</span></span>
+<span class="shell">echo ABCD | \
+ socat - \
+ SOCKET-DATAGRAM:5:2:0:x40x00xff00xf3x00x0000000000000000
+</span>
<p>The client process should print the data.
</p>
@@ -314,9 +316,8 @@
see what is available on your system:
</p>
-<span class="frame"><span class="shell">
-nmap -sO localhost
-</span></span>
+<span class="shell">nmap -sO localhost
+</span>
<p>
<small>Copyright: Gerhard Rieger 2008</small><br>
diff --git a/doc/socat-multicast.html b/doc/socat-multicast.html
index 8bf9fcb..5077088 100644
--- a/doc/socat-multicast.html
+++ b/doc/socat-multicast.html
@@ -61,10 +61,10 @@
servers would also respond to other clients' requests.</p>
<p>Multicast server:</p>
-
-<span class="frame"><span class="shell">
-socat UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork EXEC:hostname
-</span></span>
+<div class="shell">socat \
+ UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork \
+ EXEC:hostname
+</div>
<p>
This command receives multicast packets addressed to 224.1.0.1 and forks a
child process for each. The child processes may each send one or more reply
@@ -75,9 +75,10 @@
<p>Multicast client:</p>
-<span class="frame"><span class="shell">
-socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24
-</span></span>
+<span class="shell">socat \
+ STDIO \
+ UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24
+</span>
<p>
This process transfers data from stdin to the multicast address, and transfers
packets received from the local network to stdout. It does not matter in which
@@ -101,9 +102,10 @@
<p>Broadcast server:</p>
-<span class="frame"><span class="shell">
-socat UDP4-RECVFROM:6666,broadcast,fork EXEC:hostname
-</span></span>
+<span class="shell">socat \
+ UDP4-RECVFROM:6666,broadcast,fork \
+ EXEC:hostname
+</span>
<p>
This command receives packets addressed to a local broadcast address and forks
a child process for each. The child processes may each send one or more reply
@@ -113,9 +115,10 @@
<p>Broadcast client:</p>
-<span class="frame"><span class="shell">
-socat STDIO UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24
-</span></span>
+<span class="shell">socat \
+ STDIO \
+ UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24
+</span>
<p>
This process transfers data from stdin to the broadcast address, and transfers
packets received from the local network to stdout. It does not matter in which
@@ -143,9 +146,10 @@
that will communicate symmetrically, so each process can send messages that are
received by all the other ones.</p>
-<span class="frame"><span class="shell">
-socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,bind=:6666,range=192.168.10.0/24,ip-add-membership=224.1.0.1:192.168.10.2
-</span></span>
+<span class="shell">socat \
+ STDIO \
+ UDP4-DATAGRAM:224.1.0.1:6666,bind=:6666,range=192.168.10.0/24,ip-add-membership=224.1.0.1:192.168.10.2
+</span>
<p>
This command is valid for host 192.168.10.2; adapt this address to the
particular interface addresses of the hosts.
@@ -167,9 +171,10 @@
<p>Just as with multicast, it is possible to combine broadcast sender and
receiver in one socat address.</p>
-<span class="frame"><span class="shell">
-socat STDIO UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast
-</span></span>
+<span class="shell">socat \
+ STDIO \
+ UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast
+</span>
<p>
Starting this process opens a socket on port 6666 that will receive packets
directed to a local broadcast addresses. Only packets with matching source
@@ -213,8 +218,9 @@
<h3>Routing</h3>
<p>
When you receive an error like:</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>... E sendto(3, 0x80c2e44, 4,
-0, AF=2 224.1.0.1:6666, 16): Network is unreachable</tt></td></tr></table>
+<span class="error">
+ ... E sendto(3, 0x80c2e44, 4, 0, AF=2 224.1.0.1:6666, 16): Network is unreachable
+</span>
<p>you have a routing problem. The (Linux) IP stack seems to handle multicast
addresses just like unicast addresses when determining their route (interface
and gateway), i.e. the routing table needs an entry that somehow matches the
@@ -224,9 +230,8 @@
interface with the default route if it is specified.</p>
<p>
Set a multicast/broadcast route with the following command (Linux):</p>
-<span class="frame"><span class="shell">
-route add -net 224.0.0.0/3 gw 192.168.10.2
-</span></span>
+<span class="shell">route add -net 224.0.0.0/3 gw 192.168.10.2
+</span>
<a name="ALLSYSTEMS"></a>
<h3>ALL-SYSTEMS multicast address</h3>
@@ -318,17 +323,20 @@
Example: Start a receiver of the following form (tried on Linux):
</p>
-<span class="frame"><span class="shell">
-socat -u UDP-RECVFROM:8888,reuseaddr,ip-add-membership=224.1.0.1:192.168.10.2,ip-pktinfo,fork SYSTEM:export
-</span></span>
+<span class="shell">socat -u \
+ UDP-RECVFROM:8888,reuseaddr,ip-add-membership=224.1.0.1:192.168.10.2,ip-pktinfo,fork \
+ SYSTEM:export
+</span>
<p>
Then send a multicast packet from the client:
</p>
-<span class="frame"><span class="shell">
-echo |socat -u STDIO UDP-DATAGRAM:224.1.0.1:8888
-</span></span>
+<span class="shell">echo | \
+ socat -u \
+ STDIO \
+ UDP-DATAGRAM:224.1.0.1:8888
+</span>
<p>
On the server the following text should appear (only interesting lines shown):
diff --git a/doc/socat-openssltunnel.html b/doc/socat-openssltunnel.html
index 99d644e..d4965a4 100644
--- a/doc/socat-openssltunnel.html
+++ b/doc/socat-openssltunnel.html
@@ -39,22 +39,21 @@
<p>Perform the following steps on a trusted host where OpenSSL is
installed. It might as well be the client or server host themselves.</p>
<p>Prepare a basename for the files related to the server certificate:</p>
-<span class="frame"><span class="shell">FILENAME=server</span></span>
+<span class="shell">FILENAME=server</span>
<p>Generate a public/private key pair:</p>
-<span class="frame"><span class="shell">openssl genrsa -out $FILENAME.key 2048</span></span>
+<span class="shell">openssl genrsa -out $FILENAME.key 2048</span>
<p>Generate a self signed certificate:</p>
-<span class="frame"><span class="shell">
-openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span></span>
+<span class="shell">openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span>
<p>You will be prompted for your country code, name etc.; you may quit all prompts
with the ENTER key, except for the Common Name which must be exactly the name or IP address of the server that the client will use.</p>
<p>Generate the PEM file by just appending the key and certificate files:<p>
-<span class="frame"><span class="shell">cat $FILENAME.key $FILENAME.crt >$FILENAME.pem</span></span>
+<span class="shell">cat $FILENAME.key $FILENAME.crt >$FILENAME.pem</span>
<p>The files that contain the private key should be kept secret, thus adapt
their permissions:<p>
-<span class="frame"><span class="shell">chmod 600 $FILENAME.key $FILENAME.pem</span></span>
+<span class="shell">chmod 600 $FILENAME.key $FILENAME.pem</span>
<p>Now bring the file <tt>server.pem</tt> to the SSL server, e.g. to directory
<tt>$HOME/etc/</tt>, using a secure channel like USB memory stick or SSH. Keep
@@ -68,7 +67,7 @@
<h3>Generate a client certificate</h3>
<p>First prepare a different basename for the files related to the client certificate:</p>
-<span class="frame"><span class="shell">FILENAME=client</span></span>
+<span class="shell">FILENAME=client</span>
<p>Repeat the procedure for certificate generation described above. A special common name is not required.
Copy <tt>client.pem</tt> to the SSL client, and <tt>client.crt</tt> to the
@@ -81,7 +80,9 @@
ceritificate and private key, and <tt>cafile=...</tt> points to the file
containing the certificate of the peer; we trust clients only if they can proof
that they have the related private key (OpenSSL handles this for us):<p>
-<span class="frame"><span class="shell">socat OPENSSL-LISTEN:4433,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt PIPE</span></span>
+<span class="shell">socat \
+ OPENSSL-LISTEN:4433,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt \
+ PIPE</span>
<p>After starting this command, socat should be listening on port 4433, but
will require client authentication.</p>
@@ -89,7 +90,8 @@
<p>Substitute your <tt>tcp-connect</tt> or <tt>tcp</tt> address keyword with
<tt>openssl-connect</tt> or just <tt>ssl</tt> and here too add the
<tt>cert</tt> and <tt>cafile</tt> options:<p>
-<span class="frame"><span class="shell">socat STDIO OPENSSL-CONNECT:server.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
+<span class="shell">socat STDIO \
+ OPENSSL-CONNECT:server.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span>
<p>This command should establish a secured connection to the server
process.</p>
@@ -99,21 +101,23 @@
to be adapted; <tt>ip6name.domain.org</tt> is assumed to resolve to the IPv6
address of the server:</p>
<p>Server:</p>
-<span class="frame"><span class="shell">socat
-OPENSSL-LISTEN:4433,<b style="color:yellow">pf=ip6</b>,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt PIPE</span></span>
+<span class="shell">socat \
+ OPENSSL-LISTEN:4433,<b style="color:yellow">pf=ip6</b>,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt \
+ PIPE</span>
<p>Client:</p>
-<span class="frame"><span class="shell">socat STDIO OPENSSL-CONNECT:<b style="color:yellow">ip6name</b>.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
+<span class="shell">socat STDIO \
+ OPENSSL-CONNECT:<b style="color:yellow">ip6name</b>.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span>
<h2>Troubleshooting</h2>
<h3>Test OpenSSL Integration</h3>
<p>
If you get error messages like this:</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>... E unknown device/address "openssl-listen"</tt></td></tr></table>
+<span class="error">... E unknown device/address "OPENSSL-LISTEN"</span>
<p>your socat executable probably does not have the OpenSSL library linked in.
Check socat's compile time configuration with the following command:</p>
-<span class="frame"><span class="shell">socat -V |grep SSL</span></span>
+<span class="shell">socat -V |grep SSL</span>
<p>Positive output:
<tt>#define WITH_OPENSSL 1</tt><br>
Negative output:
diff --git a/doc/socat-tun.html b/doc/socat-tun.html
index ab04f56..0f0ef64 100644
--- a/doc/socat-tun.html
+++ b/doc/socat-tun.html
@@ -53,14 +53,20 @@
<h3>TUN Server</h3>
-<span class="frame"><span class="shell">socat -d -d UDP-LISTEN:11443,reuseaddr TUN:192.168.255.1/24,up</span></span>
+<span class="shell">socat -d -d \
+ UDP-LISTEN:11443 \
+ TUN:192.168.255.1/24,up
+</span>
<p>After starting this command, socat will wait for a connection and then
create a TUN pseudo network device with address 192.168.255.1; the bit number
specifies the mask of the network that is pretended to be connected on this
interface.</p>
<h3>TUN Client</h3>
-<span class="frame"><span class="shell">socat UDP:1.2.3.4:11443 TUN:192.168.255.2/24,up</span></span>
+<span class="shell">socat \
+ UDP:1.2.3.4:11443 \
+ TUN:192.168.255.2/24,up
+</span>
<p>This command should establish a connection to the server and create the TUN
device on the client.</p>
@@ -85,17 +91,17 @@
<h3>Test TUN integration</h3>
<p>
If you get error messages like this:</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>... E unknown device/address "tun"</tt></td></tr></table>
+<span class="error">... E unknown device/address "tun"</span>
<p>your socat executable probably does not provide TUN/TAP support. Potential
reasons: you are not on Linux or are using an older version of socat.
</p>
<h3>Missing kernel support</h3>
<p>An error message like:</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>... E open("/dev/net/tun", 02, 0666): No such file or directory</tt></td></tr></table>
+<span class="error">... E open("/dev/net/tun", 02, 0666): No such file or directory</span>
<p>indicates that your kernel either needs to load the tun module or does not
have TUN/TAP support compiled in. Try to load the module:</p>
-<span class="frame"><span class="shell">modprobe tun</span></span>
+<span class="shell">modprobe tun</span>
<p>and check
for /dev/net/tun. If that does not succeed you need to
rebuild your kernel with the appropriate configuration (probably under
@@ -104,14 +110,14 @@
<h3>TUN cloning device permissions</h3>
<p>An error message like:</p>
-<table border="1" bgcolor="#e08080"><tr><td><tt>... E open("/dev/net/tun", 02, 0666): Permission denied</tt></td></tr></table>
+<span class="error">... E open("/dev/net/tun", 02, 0666): Permission denied</span>
<p>indicates that you do not have permission to read or write the TUN cloning
device. Check its permission and ownership.</p>
<h3>Interface down</h3>
<p>If no error occurs but the pings do not work check if the network devices
have been created:</p>
-<span class="frame"><span class="shell">ifconfig tun0</span></span>
+<span class="shell">ifconfig tun0</span>
<p>The output should look like:</p>
<pre>
tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
@@ -128,7 +134,7 @@
<h3>Routing</h3>
<p></p>
-<span class="frame"><span class="shell">netstat -an |fgrep 192.168.255</span></span>
+<span class="shell">netstat -an |fgrep 192.168.255</span>
<p>The output should look like:</p>
<pre>
192.168.255.0 0.0.0.0 255.255.255.0 U 0 0 0 tun0
diff --git a/doc/socat.yo b/doc/socat.yo
index e39ec64..64c1851 100644
--- a/doc/socat.yo
+++ b/doc/socat.yo
@@ -12,6 +12,8 @@
manpage(socat)(1)()()()
+htmlcommand(<link rel="stylesheet" type="text/css" href="dest-unreach.css">)
+
whenhtml(
label(CONTENTS)
manpagesection(CONTENTS)
@@ -664,8 +666,8 @@
link(pf)(OPTION_PROTOCOL_FAMILY), and sends a CONNECT
request for hostname:port. If the proxy grants access and succeeds to
connect to the target, data transfer between socat and the target can
- start. Note that the traffic need not be HTTP but can be an arbitrary
- protocol. nl()
+ start (link(example)(EXAMPLE_PROXY_CONNECT)).
+ Note that the traffic need not be HTTP but can be an arbitrary protocol. nl()
Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(HTTP)(GROUP_HTTP),link(RETRY)(GROUP_RETRY) nl()
Useful options:
link(proxyport)(OPTION_PROXYPORT),
@@ -1687,13 +1689,14 @@
Unlinks (removes) the file after opening it to make it inaccessible for
other processes after a short race condition.
label(OPTION_UNLINK_CLOSE)dit(bf(tt(unlink-close[=<bool>])))
- Removes the addresses file system entry when closing the address.
+ Controls removal of the addresses file system entry when closing the address.
For link(named pipes)(ADDRESS_NAMED_PIPE),
link(UNIX domain sockets)(ADDRESS_UNIX_LISTEN),
and the link(symbolic links)(OPTION_SYMBOLIC_LINK) of link(pty addresses)(ADDRESS_PTY),
- the default is 1; for link(created files)(ADDRESS_CREAT),
+ the default is remove (1); for link(created files)(ADDRESS_CREAT),
link(opened files)(ADDRESS_OPEN), and
- link(generic opened files)(ADDRESS_GOPEN) the default is 0.
+ link(generic opened files)(ADDRESS_GOPEN) the default is keep (0).
+ Setting this option to 1 removes the entry, 0 keeps it. No value means 1.
enddit()
startdit()enddit()nl()
@@ -2065,7 +2068,7 @@
These options apply to UNIX domain based addresses.
startdit()
-label(OPTION_UNIX_TIGHTSOCKLEN)dit(bf(tt(unix-tightsocklen=[0|1])))
+label(OPTION_UNIX_TIGHTSOCKLEN)dit(bf(tt(unix-tightsocklen[=(0|1)])))
On socket operations, pass a socket address length that does not include the
whole code(struct sockaddr_un) record but (besides other components) only
the relevant part of the filename or abstract string. Default is 1.
@@ -3115,8 +3118,18 @@
startdit()
+COMMENT(I could not find a way to have these multiline examples with yodl,
+code() and verbatim() failed miserably...)
+COMMENT(Thus this tedious hack for now)
+
label(EXAMPLE_ADDRESS_TCP4_CONNECT)
-dit(bf(tt(socat - TCP4:www.domain.org:80)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - TCP4:www.domain.org:80\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - TCP4:www.domain.org:80</div>)
transfers data between link(STDIO)(ADDRESS_STDIO) (-) and a
link(TCP4)(ADDRESS_TCP4_CONNECT) connection to port 80 of host
@@ -3128,12 +3141,16 @@
label(EXAMPLE_OPTION_HISTORY)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat -d -d READLINE,history=$HOME/.http_history \\
-TCP4:www.domain.org:www,crnl\fP)
+mancommand(\fBsocat -d -d \\)
+mancommand(\.RS)
+mancommand(\fBREADLINE,history=$HOME/.http_history \\
+ TCP4:www.domain.org:www,crnl\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat -d -d READLINE,history=$HOME/.http_history \</strong><br>
-<strong>TCP4:www.domain.org:www,crnl</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat -d -d \
+ READLINE,history=$HOME/.http_history \
+ TCP4:www.domain.org:www,crnl</div>)
this is similar to the previous example, but you can edit the current line in a
bash like manner (link(READLINE)(ADDRESS_READLINE)) and use the
@@ -3143,8 +3160,21 @@
(link(crnl)(OPTION_CRNL)) instead of NL are used.
+COMMENT((bf(tt(socat TCP4-LISTEN:www TCP4:www.domain.org:www))))
+
label(EXAMPLE_ADDRESS_TCP4_LISTEN)
-dit(bf(tt(socat TCP4-LISTEN:www TCP4:www.domain.org:www)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:www \\
+ TCP4:www.domain.org:www\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ TCP4-LISTEN:www \
+ TCP4:www.domain.org:www</div>)
installs a simple TCP port forwarder. With
link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN) it listens on local port "www" until a
@@ -3159,14 +3189,16 @@
label(EXAMPLE_OPTION_RANGE)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat -d -d -lmlocal2 \\
-TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\
-TCP4:www.domain.org:80,bind=myaddr2\fP)
+mancommand(\fBsocat -d -d -lmlocal2 \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\
+ TCP4:www.domain.org:80,bind=myaddr2\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat -d -d -lmlocal2 \</strong><br>
-<strong>TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \</strong><br>
-<strong>TCP4:www.domain.org:80,bind=myaddr2</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat -d -d -lmlocal2 \
+ TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \
+ TCP4:www.domain.org:80,bind=myaddr2</div>)
TCP port forwarder, each side bound to another local IP address
(link(bind)(OPTION_BIND)). This example handles an almost
@@ -3190,12 +3222,16 @@
label(EXAMPLE_OPTION_STDERR)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat TCP4-LISTEN:5555,fork,tcpwrap=script \\
-EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:5555,fork,tcpwrap=script \\
+ EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat TCP4-LISTEN:5555,fork,tcpwrap=script \</strong><br>
-<strong>EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat \
+ TCP4-LISTEN:5555,fork,tcpwrap=script \
+ EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</div>)
a simple server that accepts connections
(link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN)) and link(fork)(OPTION_FORK)'s a new
@@ -3217,12 +3253,16 @@
label(EXAMPLE_OPTION_MSS)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\
-TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBEXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\
+ TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \</strong><br>
-<strong>TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat \
+ EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
+ TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512</div>)
file(mail.sh) is a shell script, distributed with socat(), that implements a
simple
@@ -3240,7 +3280,18 @@
label(EXAMPLE_ADDRESS_GOPEN)
label(EXAMPLE_OPTION_TERMIOS_RAWER)
label(EXAMPLE_OPTION_ESCAPE)
-dit(bf(tt(socat -,escape=0x0f /dev/ttyS0,rawer,crnl)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fB-,escape=0x0f \\
+ /dev/ttyS0,rawer,crnl\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ -,escape=0x0f \
+ /dev/ttyS0,rawer,crnl</div>)
opens an interactive connection via the serial line, e.g. for talking with a
modem. link(rawer)(OPTION_TERMIOS_RAWER) sets the console's and
@@ -3256,12 +3307,16 @@
label(EXAMPLE_OPTION_SOURCEPORT)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \\
-SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBUNIX-LISTEN:/tmp/.X11-unix/X1,fork \\
+ SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \</strong><br>
-<strong>SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat \
+ UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
+ SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20</div>)
with link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), socat() opens a listening
unixdomain() socket file(/tmp/.X11-unix/X1). This path corresponds
@@ -3281,7 +3336,18 @@
label(EXAMPLE_option_u)
label(EXAMPLE_OPTION_IGNOREEOF)
-dit(bf(tt(socat -u /tmp/readdata,seek-end=0,ignoreeof -)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat -u \\)
+mancommand(\.RS)
+mancommand(\fB/tmp/readdata,seek-end=0,ignoreeof \\)
+mancommand(\fBSTDIO\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat -u \
+ /tmp/readdata,seek-end=0,ignoreeof \
+ STDIO</div>)
this is an example for unidirectional data transfer
(link(-u)(option_u)). Socat() transfers data
@@ -3297,12 +3363,16 @@
label(EXAMPLE_OPTION_CTTY)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
-socat - EXEC:'ssh -l user server',pty,setsid,ctty\fP)
+mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | \\)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBEXEC:'ssh -l user server',pty,setsid,ctty\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |</strong><br>
-<strong>socat - EXEC:'ssh -l user server',pty,setsid,ctty</strong></code><dd>)
+htmlcommand(<hr><div class="shell">(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
+socat - \
+ EXEC:'ssh -l user server',pty,setsid,ctty</div>)
link(EXEC)(ADDRESS_EXEC)'utes an ssh session to server. Uses a link(pty)(OPTION_PTY) for communication between socat() and
ssh, makes it ssh's controlling tty (link(ctty)(OPTION_CTTY)),
@@ -3315,12 +3385,16 @@
label(EXAMPLE_OPTION_APPEND)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat -u TCP4-LISTEN:3334,reuseaddr,fork \\
-OPEN:/tmp/in.log,creat,append\fP)
+mancommand(\fBsocat -u \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:3334,reuseaddr,fork \\
+ OPEN:/tmp/in.log,creat,append\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat -u TCP4-LISTEN:3334,reuseaddr,fork \</strong><br>
-<strong>OPEN:/tmp/in.log,creat,append</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat -u \
+ TCP4-LISTEN:3334,reuseaddr,fork \
+ OPEN:/tmp/in.log,creat,append</div>)
implements a simple network based message collector.
For each client connecting to port 3334, a new child process is generated (option link(fork)(OPTION_FORK)).
@@ -3350,7 +3424,18 @@
)
label(EXAMPLE_OPTION_NOECHO)
-dit(bf(tt(socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,setsid,ctty)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBREADLINE,noecho='[Pp]assword:' \\
+ EXEC:'ftp ftp.server.com',pty,setsid,ctty\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ READLINE,noecho='[Pp]assword:' \
+ EXEC:'ftp ftp.server.com',pty,setsid,ctty</div>)
wraps a command line history (link(READLINE)(ADDRESS_READLINE)) around the link(EXEC)(ADDRESS_EXEC)'uted ftp client utility.
This allows editing and reuse of FTP commands for relatively comfortable
@@ -3366,12 +3451,16 @@
label(EXAMPLE_OPTION_NONBLOCK)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \\\bf)
-mancommand(\fBEXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"\fP)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBPTY,link=$HOME/dev/vmodem0,rawer,wait-slave \\
+ EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \</strong><br>
-<strong>EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat \
+ PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
+ EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</div>)
generates a pseudo terminal
device (link(PTY)(ADDRESS_PTY)) on the client that can be reached under the
@@ -3382,24 +3471,39 @@
file(/dev/ttyS0).
+label(EXAMPLE_PROXY_CONNECT)
mancommand(\.LP)
mancommand(\.nf)
-mancommand(\fBsocat TCP4-LISTEN:2022,reuseaddr,fork \\
-PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass\fP)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:2022,reuseaddr,fork \\
+ PROXY:proxy.local:www.domain.org:22,proxyport=3128,proxyauth=username:s3cr3t\fP)
+mancommand(\.RE)
mancommand(\.fi)
-htmlcommand(<dt><code><strong>socat TCP4-LISTEN:2022,reuseaddr,fork \</strong><br>
-<strong>PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass</strong></code><dd>)
+htmlcommand(<hr><div class="shell">socat \
+ TCP4-LISTEN:2022,reuseaddr,fork \
+ PROXY:proxy.local:www.domain.org:22,proxyport=3128,proxyauth=username:s3cr3t</div>)
starts a forwarder that accepts connections on port 2022, and directs them
through the link(proxy)(ADDRESS_PROXY_CONNECT) daemon listening on port 3128
-(link(proxyport)(OPTION_PROXYPORT)) on host proxy, using the
-CONNECT method, where they are authenticated as "user" with "pass" (link(proxyauth)(OPTION_PROXY_AUTHORIZATION)). The proxy
+(link(proxyport)(OPTION_PROXYPORT)) on host proxy.local, using the
+CONNECT method, where they are authenticated as "username" with "s3cr3t"
+(link(proxyauth)(OPTION_PROXY_AUTHORIZATION)). proxy.local
should establish connections to host www.domain.org on port 22 then.
label(EXAMPLE_ADDRESS_OPENSSL_CONNECT)
-dit(bf(tt(socat - SSL:server:4443,cafile=server.crt,cert=client.pem)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBSSL:server:4443,cafile=./server.crt,cert=./client.pem\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ SSL:server:4443,cafile=./server.crt,cert=./client.pem</div>)
is an OpenSSL client that tries to establish a secure connection to an SSL
server. Option link(cafile)(OPTION_OPENSSL_CAFILE) specifies a file that
@@ -3413,7 +3517,18 @@
label(EXAMPLE_ADDRESS_OPENSSL_LISTEN)
-dit(bf(tt(socat OPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBOPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=./server.pem,cafile=./client.crt \\
+ PIPE\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ OPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=./server.pem,cafile=./client.crt \
+ PIPE</div>)
is an OpenSSL server that accepts TCP connections, presents the certificate
from the file server.pem and forces the client to present a certificate that is
@@ -3424,16 +3539,38 @@
see the additional socat docu tt(socat-openssl.txt).
-dit(bf(tt(echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBecho |
+socat -u - \\)
+mancommand(\.RS)
+mancommand(\fBFILE:/tmp/bigfile,create,largefile,seek=100000000000\fP)
+mancommand(\.RE)
+mancommand(\.fi)
-creates a 100GB sparse file; this requires a file system type that
-supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of
+htmlcommand(<hr><div class="shell">echo |
+socat -u - \
+ FILE:/tmp/bigfile,create,largefile,seek=100000000000</div>)
+
+creates a 100GB+1B sparse file; this requires a file system type that
+supports this (ext2, ext3, ext4, reiserfs, xfs; not minix, vfat). The operation of
writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and
the resulting file can consume some disk space with just its inodes (reiserfs:
2MB; ext2: 16KB).
-dit(bf(tt(socat tcp-l:7777,reuseaddr,fork system:'filan -i 0 -s >&2',nofork)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP-L:7777,reuseaddr,fork \\
+ SYSTEM:'filan -i 0 -s >&2',nofork\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ TCP-L:7777,reuseaddr,fork \
+ SYSTEM:'filan -i 0 -s >&2',nofork</div>)
listens for incoming TCP connections on port 7777. For each accepted
connection, invokes a shell. This shell has its stdin and stdout directly
@@ -3441,20 +3578,51 @@
stderr (your terminal window).
-dit(bf(tt(echo -e "\0\14\0\0\c" |socat -u - file:/usr/bin/squid.exe,seek=0x00074420)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBecho -e "\\0\\14\\0\\0\\c" |
+socat -u - \\)
+mancommand(\.RS)
+mancommand(\fBFILE:/usr/bin/squid.exe,seek=0x00074420\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">echo -e "\0\14\0\0\c" |
+socat -u - \
+ FILE:/usr/bin/squid.exe,seek=0x00074420</div>)
functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to
-the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch
-to make the squid executable from Cygwin run under Windows, actual per May 2004).
+the executable /usr/bin/squid.exe at offset 0x00074420 (this was a real world patch
+to make the squid executable from Cygwin run under Windows, in 2004).
-dit(bf(tt(socat - tcp:www.blackhat.org:31337,readbytes=1000)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBTCP:www.blackhat.org:31337,readbytes=1000\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ TCP:www.blackhat.org:31337,readbytes=1000</div>)
connects to an unknown service and prevents being flooded.
label(EXAMPLE_END_CLOSE)
-dit(bf(tt(socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat -U \\)
+mancommand(\.RS)
+mancommand(\fBTCP:target:9999,end-close \\
+ TCP-L:8888,reuseaddr,fork\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat -U \
+ TCP:target:9999,end-close \
+ TCP-L:8888,reuseaddr,fork</div>)
merges data arriving from different TCP streams on port 8888 to just one stream
to target:9999. The link(end-close)(OPTION_END_CLOSE) option prevents the child
@@ -3465,7 +3633,18 @@
label(EXAMPLE_GENERIC_DCCP_SERVER)
-dit(bf(tt(socat TCP-LISTEN:10021,reuseaddr,socktype=6,protocol=33,fork PIPE)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP-LISTEN:10021,reuseaddr,socktype=6,protocol=33,fork \\
+ PIPE\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ TCP-LISTEN:10021,reuseaddr,socktype=6,protocol=33,fork \
+ PIPE</div>)
is a simple DCCP echo server. It uses socat()s TCP procedures, but changes the
socket type to SOCK_DCCP=6 (on Linux) and the IP protocol to IPPROTO_DCCP=33.
@@ -3474,21 +3653,49 @@
label(EXAMPLE_GENERIC_DCCP_CLIENT)
-dit(bf(tt(socat - TCP:<server>:10021,reuseaddr,socktype=6,protocol=33,fork)))
+
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBTCP:<server>:10021,reuseaddr,socktype=6,protocol=33,fork\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ TCP:<server>:10021,reuseaddr,socktype=6,protocol=33,fork</div>)
is a simple DCCP client. It uses socat()s TCP procedures, but changes the
socket type to SOCK_DCCP=6 (on Linux) and the IP protocol to IPPROTO_DCCP=33.
label(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT)
-dit(bf(tt(socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBUDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ UDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24</div>)
sends a broadcast to the network 192.168.1.0/24 and receives the replies of the
timeservers there. Ignores NTP packets from hosts outside this network.
label(EXAMPLE_ADDRESS_GENERIC_CLIENT)
-dit(bf(tt(socat - SOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBSOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ SOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000</div>)
is semantically equivalent to the link(previous
example)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), but all parameters are
@@ -3497,14 +3704,32 @@
label(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT)
-dit(bf(tt(socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBIP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8</div>)
sends a broadcast to the local NOEXPAND(network(s)) using protocol 44. Accepts replies
from the private address range only.
label(EXAMPLE_ADDRESS_UDP4_MULTICAST)
-dit(bf(tt(socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBUDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0</div>)
transfers data from stdin to the specified multicast address using UDP. Both
local and remote ports are 6666. Tells the interface eth0 to also accept
@@ -3516,7 +3741,18 @@
label(EXAMPLE_ADDRESS_TUN)
-dit(bf(tt(socat UDP:host2:4443 TUN:192.168.255.1/24,up)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBUDP:host2:4443 \\
+ TUN:192.168.255.1/24,up\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ UDP:host2:4443 \
+ TUN:192.168.255.1/24,up</div>)
establishes one side of a virtual (but not private!) network with host2 where a
similar process might run, with UDP-L and tun address 192.168.255.2. They can
@@ -3526,37 +3762,97 @@
label(EXAMPLE_ADDRESS_VSOCK)
-dit(bf(tt(socat - VSOCK-CONNECT:2:1234)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBVSOCK-CONNECT:2:1234\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ VSOCK-CONNECT:2:1234</div>)
establishes a VSOCK connection with the host (host is always reachable with
the well-know CID=2) on 1234 port.
-dit(bf(tt(socat - VSOCK-LISTEN:1234)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBVSOCK-LISTEN:1234\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ VSOCK-LISTEN:1234</div>)
listens for a VSOCK connection on 1234 port.
-dit(bf(tt(socat - VSOCK-CONNECT:31:4321,bind:5555)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat - \\)
+mancommand(\.RS)
+mancommand(\fBVSOCK-CONNECT:31:4321,bind:5555\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat - \
+ VSOCK-CONNECT:31:4321,bind:5555</div>)
establishes a VSOCK connection with the guest that have CID=31 on 1234 port,
binding the local socket to the 5555 port.
-dit(bf(tt(socat VSOCK-LISTEN:3333,reuseaddr,fork VSOCK-CONNECT:42,3333)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBVSOCK-LISTEN:3333,reuseaddr,fork \\
+ VSOCK-CONNECT:42,3333\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ VSOCK-LISTEN:3333,reuseaddr,fork \
+ VSOCK-CONNECT:42,3333</div>)
starts a forwarder that accepts VSOCK connections on port 3333, and directs
them to the guest with CID=42 on the same port.
-dit(bf(tt(socat VSOCK-LISTEN:22,reuseaddr,fork TCP:localhost:22)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBVSOCK-LISTEN:22,reuseaddr,fork \\
+ TCP:localhost:22\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ VSOCK-LISTEN:22,reuseaddr,fork \
+ TCP:localhost:22</div>)
forwards VSOCK connections from 22 port to the local SSH server.
Running this in a VM allows you to connect via SSH from the host using VSOCK,
as in the example below.
-dit(bf(tt(socat TCP4-LISTEN:22222,reuseaddr,fork VSOCK-CONNECT:33:22)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBTCP4-LISTEN:22222,reuseaddr,fork \\
+ VSOCK-CONNECT:33:22\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ TCP4-LISTEN:22222,reuseaddr,fork \
+ VSOCK-CONNECT:33:22</div>)
forwards TCP connections from 22222 port to the guest with CID=33 listening on
VSOCK port 22.
@@ -3565,7 +3861,18 @@
label(EXAMPLE_INTERFACE)
-dit(bf(tt(socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat \\)
+mancommand(\.RS)
+mancommand(\fBPTY,link=/var/run/ppp,rawer \\
+ INTERFACE:hdlc0\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat \
+ PTY,link=/var/run/ppp,rawer \
+ INTERFACE:hdlc0</div>)
circumvents the problem that pppd requires a serial device and thus might not
be able to work on a synchronous line that is represented by a network device.
@@ -3575,26 +3882,64 @@
label(EXAMPLE_HTTPECHO)
-dit(bf(tt(socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate: \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\"")))
+COMMENT( dit(bf(tt(socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate: \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\""))) )
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat -T 1 -d -d \\)
+mancommand(\.RS)
+mancommand(\fBTCP-L:10081,reuseaddr,fork,crlf \\
+ SYSTEM:"echo -e \\"\\\\\\"HTTP/1.0 200 OK\\\\\\nDocumentType: text/plain\\\\\\n\\\\\\ndate: \\$\\(date\\)\\\\\\nserver:\\$SOCAT_SOCKADDR:\\$SOCAT_SOCKPORT\\\\\\nclient: \\$SOCAT_PEERADDR:\\$SOCAT_PEERPORT\\\\\\n\\\\\\"\\"; cat; echo -e \\"\\\\\\"\\\\\\n\\\\\\"\\""\fP)
+mancommand(\.RE)
+mancommand(\.fi)
-creates a simple HTTP echo server: each HTTP client that connects gets a valid
+htmlcommand(<hr><div class="shell">socat -T 1 -d -d \
+ TCP-L:10081,reuseaddr,fork,crlf \
+ SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate: \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\""</div>)
+
+creates a very primitive HTTP echo server: each HTTP client that connects gets
+a valid
HTTP reply that contains information about the client address and port as it is
seen by the server host, the host address (which might vary on multihomed
servers), and the original client request.
label(EXAMPLE_ANCILLARY)
-dit(bf(tt(socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:'export; sleep 1' |grep SOCAT)))
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBsocat -d -d \\)
+mancommand(\.RS)
+mancommand(\fBUDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- \\
+ SYSTEM:'export; sleep 1' |\fP)
+mancommand(\.RE)
+mancommand(\fBgrep SOCAT\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">socat -d -d \
+ UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- \
+ SYSTEM:'export; sleep 1' |
+grep SOCAT</div>)
waits for an incoming UDP packet on port 9999 and prints the environment
variables provided by socat. On BSD based systems you have to replace
-link(tt(ip-pktinfo))(OPTION_IP_PKTINFO) with link(tt(ip-recvdstaddr))(OPTION_IP_RECVDSTADDR),link(tt(ip-recvif))(OPTION_IP_RECVIF). Especially interesting is
+link(tt(ip-pktinfo))(OPTION_IP_PKTINFO) with link(tt(ip-recvdstaddr))(OPTION_IP_RECVDSTADDR),link(tt(ip-recvif))(OPTION_IP_RECVIF). Especially of interest is
SOCAT_IP_DSTADDR: it contains the target address of the packet which may be a
unicast, multicast, or broadcast address.
-label(EXAMPLE_SSD)
-dit(bf(tt(echo -e "M-SEARCH * HTTP/1.1\nHOST: 239.255.255.250:1900\nMAN: \"ssdp:discover\"\nMX: 4\nST: \"ssdp:all\"\n" |socat - UDP-DATAGRAM:239.255.255.250:1900,crlf)))
+label(EXAMPLE_SSDP)
+mancommand(\.LP)
+mancommand(\.nf)
+mancommand(\fBecho -e "M-SEARCH * HTTP/1.1\\nHOST: 239.255.255.250:1900\\nMAN: \\"ssdp:discover\\"\\nMX: 4\\nST: \\"ssdp:all\\"\\n" |
+socat - \\)
+mancommand(\.RS)
+mancommand(\fBUDP-DATAGRAM:239.255.255.250:1900,crlf\fP)
+mancommand(\.RE)
+mancommand(\.fi)
+
+htmlcommand(<hr><div class="shell">echo -e "M-SEARCH * HTTP/1.1\nHOST: 239.255.255.250:1900\nMAN: \"ssdp:discover\"\nMX: 4\nST: \"ssdp:all\"\n" | \
+socat - \
+ UDP-DATAGRAM:239.255.255.250:1900,crlf</div>)
sends an SSDP (Simple Service Discovery Protocol) query to the local network
and collects and outputs the answers received.
