bcollet/socat
1
0
Fork 0
mirror of https://repo.or.cz/socat.git synced 2024-12-22 15:32:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Longer Socat examples are now splitted into two or three lines; improved CSS

Browse source
This commit is contained in:
Gerhard Rieger 2023-04-02 20:55:22 +02:00
parent 7cbe0b645b
commit c3719e7603
8 changed files with 774 additions and 310 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
CHANGES
View file

@ -77,12 +77,15 @@ Documentation:
Syntax and semantics of some options (esp.unlink-close) were not clear. Syntax and semantics of some options (esp.unlink-close) were not clear.
Thanks to Anthony Chavez for reporting this and making suggestions. Thanks to Anthony Chavez for reporting this and making suggestions.
Documentation:
socat-tun.html described TCP as tunnel medium but this does not keep socat-tun.html described TCP as tunnel medium but this does not keep
packet boundaries. Changed to UDP. packet boundaries. Changed to UDP.
Added examples for DCCP client and server. 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: Testing:
Idea: EXEC,SYSTEM addresses can keep packet boundaries when option Idea: EXEC,SYSTEM addresses can keep packet boundaries when option
socktype=<val-of-SOCK_DGRAM> socktype=<val-of-SOCK_DGRAM>

370
EXAMPLES
View file

@ -5,84 +5,104 @@
//"$" means normal user, "#" requires privileges, "//" starts a comment //"$" 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" $ 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; // connection, relay data to and from stdio;
// then emulate a mailserver by hand :-) // then emulate a mailserver by hand :-)
# socat - TCP-LISTEN:25,crlf # 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; // connection, relay data to and from stdio, but have line editing and history;
// then emulate a mailserver by hand :-) // 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 // interactive programs
$ socat readline exec:"nslookup",pty,ctty,setsid,echo=0 $ socat \
// same works for ftp (but password is not hidden) 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 // You may also use a file based history list
$ socat readline,history=.nslookup_hist exec:"nslookup",pty,ctty,setsid,echo=0 $ socat \
// using ~ as abbreviation for $HOME does not work! READLINE,history=.nslookup_hist \
EXEC:"nslookup",pty,ctty,setsid,echo=0
// Using ~ as abbreviation for $HOME does not work!
// poor mans 'telnetd' replacement // Poor mans 'telnetd' replacement
# socat tcp-l:2023,reuseaddr,fork exec:/bin/login,pty,setsid,setpgid,stderr,ctty # socat \
TCP-L:2023,reuseaddr,fork \
EXEC:/bin/login,pty,setsid,setpgid,stderr,ctty
// and here an appropriate client: // and here an appropriate client:
$ socat -,raw,echo=0 tcp:172.16.181.130:2023 $ socat \
// use ssl with client and server certificate for improved security; -,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 // replace /bin/login by /bin/bash when using SSL client authentication, can be
// run without root then // 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...) // two files; it would also work for other manipulations (recode, compress...)
// and it might also work with netcat ;-) // 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 // 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) // request; hangs if client does not shutdown - HTTP keep-alive)
// wait for a connection on port 8000; do not wait for request, but immediately // 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 // start a shell that sends reply headers and an empty line; then echo all
// incoming data back to client // 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 // also server and client address and port. Might have portability issues with
// echo // 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. // following command line. Required privileges depend on device mode.
// after leaving socat, type "sane". // After leaving socat, type "sane".
// replace /dev/ttyS0 by the correct serial line or with /dev/modem // Replace /dev/ttyS0 by the correct serial line or with /dev/modem
$ socat readline /dev/ttyS0,raw,echo=0,crlf $ socat \
READLINE \
/dev/ttyS0,raw,echo=0,crlf
// or // or
$ socat readline /dev/ttyS0,raw,echo=0,crlf,nonblock $ socat \
READLINE \
/dev/ttyS0,raw,echo=0,crlf,nonblock
// then enter "at$" // 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) // firewall to your DMZ webserver (like plug-gw)
// listen on port 80; whenever a connection is made, fork a new process (parent // Listen on port 80; whenever a connection is made, fork a new process (parent
// process keeps accepting connections), su to nobody, and connect to // Process keeps accepting connections), su to nobody, and connect to
// www.dmz.mydomain.org on port 80. // 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. // 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 // 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 // accept connections only on dmz interface and allow connections only from
// smtp.dmz.mydomain.org. // smtp.dmz.mydomain.org.
// the advantages over plug-gw and other relays are: // the advantages over plug-gw and other relays are:
@ -91,49 +111,59 @@ $ socat readline /dev/ttyS0,raw,echo=0,crlf,nonblock
// to each, making several application servers addressable // to each, making several application servers addressable
// * lots of options, like switching user, chroot, IP performance tuning // * lots of options, like switching user, chroot, IP performance tuning
// * no need for inetd // * 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 // use unidirectional mode, convert nl to crnl
$ socat -u - -,crlf $ socat -u - -,crlf
// or cr to nl // or cr to nl
$ socat -u -,cr - $ 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 // 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!) // lucky!)
// prepare your host: // prepare your host:
# rm -f /tmp/.X11-unix/X1 # rm -f /tmp/.X11-unix/X1
// relay a pseudo display :1 on your machine to victim:0 // 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 // and try to take a screendump (must be very lucky - when server has not even
// host based authentication!) // host based authentication!)
# xwd -root -display :1 -silent >victim.xwd # 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. // connections to loopback and has only host based X11 security.
// like above, but from your inside client: // 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: // 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 // forms of stdin with stdout, all equivalent
$ socat echo - $ socat PIPE -
$ socat echo STDIO $ socat PIPE STDIO
$ socat echo STDIN!!STDOUT $ socat PIPE STDIN!!STDOUT
$ socat echo STDIO!!STDIO $ socat PIPE STDIO!!STDIO
$ socat echo -!!- $ socat PIPE -!!-
$ socat echo FD:0!!FD:1 $ socat PIPE FD:0!!FD:1
$ socat echo 0!!1 $ socat PIPE 0!!1
$ socat echo /dev/stdin!!/dev/stdout // if your OS provides these $ socat PIPE /dev/stdin!!/dev/stdout // when your OS provides these
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// some echo address examples // some echo address examples
@ -153,9 +183,9 @@ $ socat - TCP:loopback:2000,bind=:2000 // Linux bug?
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// unidirectional data transfer // unidirectional data transfer
$ socat -u - - $ 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 - $ 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 - $ 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!!! // 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 $ socat -u - CREATE:/tmp/outfile1,group=floppy,perm=0640
@ -165,26 +195,28 @@ $ socat -u - CREATE:/tmp/outfile1,group=floppy,perm=0640
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// 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) $ 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 - $ 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 - $ socat UNIX:/tmp/mysocket -
// then transfer data bidirectionally // 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 // your ssh client and OS are not socksified, but you want to pass a socks
// server with ssh: // 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 $ ssh -p 10022 loopback
// or better define a ProxyCommand in ~/.ssh/config: // or better define a ProxyCommand in ~/.ssh/config:
ProxyCommand socat - SOCKS:socks.mydomain.org:%h:%p ProxyCommand socat - SOCKS:socks.mydomain.org:%h:%p
@ -192,127 +224,153 @@ ProxyCommand socat - SOCKS:socks.mydomain.org:%h:%p
ProxyCommand socat - PROXY:proxy.mydomain.org:%h:%p,proxyport=8000 ProxyCommand socat - PROXY:proxy.mydomain.org:%h:%p,proxyport=8000
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// application examples // Application examples
// run sendmail daemon with your favorite network options // 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 // 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 \
UNIX-LISTEN:/tmp/postoffice,fork,perm-early=0666 \
EXEC:"/usr/sbin/sendmail -bs"
$ socat - /tmp/postoffice $ socat - /tmp/postoffice
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// uses of filan // Uses of filan
// see what your operating system opens for you // See what your operating system opens for you
$ filan $ filan
// or if that was too detailled // or if that was too detailled
$ filan -s $ filan -s
// see what file descriptors are passed via exec function // See what file descriptors are passed via exec function
$ socat - EXEC:filan,nofork $ socat - EXEC:"filan -s",nofork
$ socat - EXEC:filan $ socat - EXEC:"filan -s"
$ socat - EXEC:filan,pipes,stderr $ socat - EXEC:"filan -s",pipes,stderr
$ socat - EXEC:filan,pipes $ socat - EXEC:"filan -s",pipes
$ socat - EXEC:filan,pty $ socat - EXEC:"filan -s",pty
// see what's done by your shell and with option "pipes" // 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 // see if gdb gives you an equivalent environment or opens some files for your program
$ gdb ./filan $ gdb ./filan
(gdb) r
(gdb) r -s (gdb) r -s
(gdb) r
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// want to use chat from the ppp package? // Want to use chat from the ppp package?
// note: some OS's do not need "-e" for echo to print control characters // Note: some OS's do not need "-e" for echo to print control characters
// note: chat might send bytes one by one // Note: chat might send bytes one by one
// with AIX, a similar program is available under the name "pppdial" // 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 $ 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 // 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 // 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 \ # qemu-system-x86_64 -m 1G -smp 2 -cpu host -M accel=kvm \
# -drive if=virtio,file=/path/to/fedora.img,format=qcow2 \ # -drive if=virtio,file=/path/to/fedora.img,format=qcow2 \
# -device vhost-vsock-pci,guest-cid=21 # -device vhost-vsock-pci,guest-cid=21
# guest listens on port 1234 and host connects to it # guest listens on port 1234 and host connects to it
guest$ socat - vsock-listen:1234 guest$ socat - VSOCK-LISTEN:1234
host$ socat - vsock-connect:21:1234 host$ socat - VSOCK-CONNECT:21:1234
# host (well know CID_HOST = 2) listens on port 4321 and guest connects to it # Host (well know CID_HOST = 2) listens on port 4321 and guest connects to it
host$ socat - vsock-listen:4321 host$ socat - VSOCK-LISTEN:4321
guest$ socat - vsock-connect:2:4321 guest$ socat - VSOCK-CONNECT:2:4321
/////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
// application server solutions // Application server solutions
// run a program (here: /bin/sh) chrooted, unprivileged; // Run a program (here: /bin/sh) chrooted, unprivileged;
// parent process stays in real / running as root // parent process stays in real / running as root
# socat -d -d - EXEC:/bin/sh,chroot=/home/sandbox,su=sandbox,pty # 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 // parent process stays in / running as root
// script path is already chrooted // script path is already chrooted
# ./socat -lm -d -d TCP-LISTEN:5555,fork EXEC:/bin/myscript,chroot=/home/sandbox,su=sandbox,pty,stderr # ./socat -lm -d -d \
// to avoid terminal problems, you might - instead of telnet - connect using TCP-LISTEN:5555,fork \
$ socat -,icanon=0,echo=0 tcp:target:5555; reset 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 // Access local display from ssh server, when ssh port forwarding is disabled
// socat must be installed on ssh server host // Socat must be installed on ssh server host
// might have to use xauth... // Might have to use xauth...
// this example is one-shot because ssh can handle only one channel // 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 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 xterm2$ ssh target
target$ DISPLAY=:9 myxapplication target$ DISPLAY=:9 myxapplication
// touch with perms: // Touch with perms:
// no race condition for perms (applied with creat() call) // 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 // 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 // Invoke an interactive ssh with EXEC
// first example passes control chars (^C etc.) to remote server as usual // First example passes control chars (^C etc.) to remote server as usual
socat -,echo=0,raw exec:'ssh server',pty,setsid,ctty socat \
// second example interprets control chars on local command line -,echo=0,raw \
socat -,echo=0,icanon=0 exec:'ssh server',pty,setsid,ctty 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"! // 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: // three main versions for entering password:
// 1) from your TTY; have 10 seconds to enter 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 // 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 // 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 // use echo -e if required for \n
$ (echo -e "CONNECT 128.129.130.131:80 HTTP/1.0\n"; sleep 5; echo -e "GET $ (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) |
/download/file HTTP/1.0\n"; sleep 10) |socat -d -d -t 3600 - tcp:proxy:8080,crlf 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 // fill in your personal values; cat lets you enter your password (will be
// visible on screen) // 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: // 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 // or
$ socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0 $ socat -d -d -d -d - \
// possible reasons for failure: 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) // iptables or other filters (open your filters as required)
// packets leave via wrong interface (set route: ...) // Packets leave via wrong interface (set route: ...)
// socket bound to specific address // Socket bound to specific address
//============================================================================= //=============================================================================
// GENERIC FUNCTION CALLS // GENERIC FUNCTION CALLS
@ -320,59 +378,79 @@ $ socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=2
// ioctl(): open CD drive (given value valid on Linux) // ioctl(): open CD drive (given value valid on Linux)
// on my Linux system I find in /usr/include/linux/cdrom.h the define: // on my Linux system I find in /usr/include/linux/cdrom.h the define:
// #define CDROMEJECT 0x5309 /* Ejects the cdrom media */ // #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): // (don't care about the read error):
$ socat /dev/cdrom,o-nonblock,ioctl-void=0x5309 - $ socat /dev/cdrom,o-nonblock,ioctl-void=0x5309 -
// setsockopt(): SO_REUSEADDR // 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)) // 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 // 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: // so-bindtodevice:
// with string argument: // 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: // 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: // telnet client, when only outbound traffic (syn-filter) is allowed:
// on external client run "double server". this process waits for a // on external client run "double server". this process waits for a
// connection from localhost on port 10023, and, when it is established, waits // connection from localhost on port 10023, and, when it is established, waits
// for a connection from anywhere to port 20023: // 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: // 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: // 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: // login with:
ext$ telnet localhost 20023 ext$ telnet localhost 20023
// you can make a double server capable of handling multiple instances: // YOU can make a double server capable of handling multiple instances:
ext$ socat -d TCP-LISTEN:10023,range=localhost,fork TCP-LISTEN:20023,reuseaddr ext$ socat -d \
TCP-LISTEN:10023,range=localhost,fork \
TCP-LISTEN:20023,reuseaddr
// access remote display via ssh, when ssh port forwarding is disabled // 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 $ socat -d -d \
EXEC:"ssh target socat - UNIX:/tmp/.X11-unix/X0" \
TCP-LISTEN:6030
$ xclock -display localhost:30 $ xclock -display localhost:30
// relay multiple webserver addresses through your firewall into your DMZ: // Relay multiple webserver addresses through your firewall into your DMZ:
// make IP aliases on your firewall, and then: // 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 \
# socat -d -d TCP-L:80,bind=fw-addr2,fork TCP:dmz-www2:80 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: // 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) // 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 # 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! // 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 // note that, for IPsec, you might face problems that are known with NAT

31
doc/dest-unreach.css
View file

@ -1,9 +1,28 @@
table { table {
empty-cells:show; empty-cells: show;
} }
.frame { border-style:solid; border-width:4px; border-color:black; }
.shell { font-family:Courier; .shell {
padding:2px; padding-left:6px; padding-right:6px; display: block;
border-style:solid; border-width:1px; border-color:gray; font-family: Courier;
color:lightgreen; background-color:black; 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;
} }

47
doc/socat-genericsocket.html
View file

@ -62,17 +62,19 @@ href="#GENERIC_ADDRESSES">generic socket addresses</a>.
returns it to the client: returns it to the client:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat TCP4-LISTEN:4096,reuseaddr,type=6,prototype=33 exec:'tr A-Z a-z',pty,raw,echo=0 TCP4-LISTEN:4096,reuseaddr,type=6,prototype=33 \
</span></span> 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 <p>A simple client that sends some upper case characters to the server via DCCP
and prints what the server returns: and prints what the server returns:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">echo ABCD | \
echo ABCD |socat - TCP4-CONNECT:localhost:4096,type=6,prototype=33 socat - \
</span></span> TCP4-CONNECT:localhost:4096,type=6,prototype=33
</span>
<p>We choose the TCP4 addresses as base because it best matches the DCCP <p>We choose the TCP4 addresses as base because it best matches the DCCP
requirements: requirements:
@ -98,7 +100,7 @@ echo ABCD |socat - TCP4-CONNECT:localhost:4096,type=6,prototype=33
If the service codes on server and client do not match the <tt>connect()</tt> If the service codes on server and client do not match the <tt>connect()</tt>
operation fails with error:<p> 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 <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 replace the TCP4 words with TCP6, and the IPv4 socket address with an
@ -132,20 +134,18 @@ echo ABCD |socat - TCP4-CONNECT:localhost:4096,type=6,prototype=33
ping command: ping command:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">aecho 65280.243
aecho 65280.243 </span>
</span></span>
<p>If you get an error like: <p>If you get an error like:
</p> </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> <p>then try to restart <tt>atalkd</tt>:</p>
<span class="frame"><span class="shell"> <span class="shell">/etc/init.d/atalkd restart
/etc/init.d/atalkd restart </span>
</span></span>
<p>When <tt>aecho</tt> works like <tt>ping</tt> you are ready for the next step. <p>When <tt>aecho</tt> works like <tt>ping</tt> you are ready for the next step.
</p> </p>
@ -155,17 +155,19 @@ aecho 65280.243
<p>We start a socat process with a receiver and echo service: <p>We start a socat process with a receiver and echo service:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat SOCKET-RECVFROM:5:2:0:x40x00x0000x00x00x0000000000000000 PIPE SOCKET-RECVFROM:5:2:0:x40x00x0000x00x00x0000000000000000 \
</span></span> PIPE
</span>
<p>Then, in another shell on the same host, we start a client socket process <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: that sends data to the server and gets the answer:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">echo ABCD | \
echo ABCD |socat - SOCKET-DATAGRAM:5:2:0:x40x00xff00xf3x00x0000000000000000 socat - \
</span></span> SOCKET-DATAGRAM:5:2:0:x40x00xff00xf3x00x0000000000000000
</span>
<p>The client process should print the data. <p>The client process should print the data.
</p> </p>
@ -314,9 +316,8 @@ x7f000001 x0000000000000000</td></tr>
see what is available on your system: see what is available on your system:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">nmap -sO localhost
nmap -sO localhost </span>
</span></span>
<p> <p>
<small>Copyright: Gerhard Rieger 2008</small><br> <small>Copyright: Gerhard Rieger 2008</small><br>

68
doc/socat-multicast.html
View file

@ -61,10 +61,10 @@ multicast address, and the servers may send response packets. Note that the
servers would also respond to other clients' requests.</p> servers would also respond to other clients' requests.</p>
<p>Multicast server:</p> <p>Multicast server:</p>
<div class="shell">socat \
<span class="frame"><span class="shell"> UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork \
socat UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork EXEC:hostname EXEC:hostname
</span></span> </div>
<p> <p>
This command receives multicast packets addressed to 224.1.0.1 and forks a 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 child process for each. The child processes may each send one or more reply
@ -75,9 +75,10 @@ parallel.</p>
<p>Multicast client:</p> <p>Multicast client:</p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24 STDIO \
</span></span> UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24
</span>
<p> <p>
This process transfers data from stdin to the multicast address, and transfers 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 packets received from the local network to stdout. It does not matter in which
@ -101,9 +102,10 @@ Of these packets, socat handles only those matching the following criteria:
<p>Broadcast server:</p> <p>Broadcast server:</p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat UDP4-RECVFROM:6666,broadcast,fork EXEC:hostname UDP4-RECVFROM:6666,broadcast,fork \
</span></span> EXEC:hostname
</span>
<p> <p>
This command receives packets addressed to a local broadcast address and forks 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 a child process for each. The child processes may each send one or more reply
@ -113,9 +115,10 @@ parallel.</p>
<p>Broadcast client:</p> <p>Broadcast client:</p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat STDIO UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24 STDIO \
</span></span> UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24
</span>
<p> <p>
This process transfers data from stdin to the broadcast address, and transfers 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 packets received from the local network to stdout. It does not matter in which
@ -143,9 +146,10 @@ address. This allows to start processes on different hosts on the local network
that will communicate symmetrically, so each process can send messages that are that will communicate symmetrically, so each process can send messages that are
received by all the other ones.</p> received by all the other ones.</p>
<span class="frame"><span class="shell"> <span class="shell">socat \
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 STDIO \
</span></span> 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> <p>
This command is valid for host 192.168.10.2; adapt this address to the This command is valid for host 192.168.10.2; adapt this address to the
particular interface addresses of the hosts. particular interface addresses of the hosts.
@ -167,9 +171,10 @@ on the local network.
<p>Just as with multicast, it is possible to combine broadcast sender and <p>Just as with multicast, it is possible to combine broadcast sender and
receiver in one socat address.</p> receiver in one socat address.</p>
<span class="frame"><span class="shell"> <span class="shell">socat \
socat STDIO UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast STDIO \
</span></span> UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast
</span>
<p> <p>
Starting this process opens a socket on port 6666 that will receive packets Starting this process opens a socket on port 6666 that will receive packets
directed to a local broadcast addresses. Only packets with matching source directed to a local broadcast addresses. Only packets with matching source
@ -213,8 +218,9 @@ property of the incoming packet.
<h3>Routing</h3> <h3>Routing</h3>
<p> <p>
When you receive an error like:</p> When you receive an error like:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E sendto(3, 0x80c2e44, 4, <span class="error">
0, AF=2 224.1.0.1:6666, 16): Network is unreachable</tt></td></tr></table> ... 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 <p>you have a routing problem. The (Linux) IP stack seems to handle multicast
addresses just like unicast addresses when determining their route (interface addresses just like unicast addresses when determining their route (interface
and gateway), i.e. the routing table needs an entry that somehow matches the and gateway), i.e. the routing table needs an entry that somehow matches the
@ -224,9 +230,8 @@ For the same reason, multicast packets will probably leave your host on the
interface with the default route if it is specified.</p> interface with the default route if it is specified.</p>
<p> <p>
Set a multicast/broadcast route with the following command (Linux):</p> Set a multicast/broadcast route with the following command (Linux):</p>
<span class="frame"><span class="shell"> <span class="shell">route add -net 224.0.0.0/3 gw 192.168.10.2
route add -net 224.0.0.0/3 gw 192.168.10.2 </span>
</span></span>
<a name="ALLSYSTEMS"></a> <a name="ALLSYSTEMS"></a>
<h3>ALL-SYSTEMS multicast address</h3> <h3>ALL-SYSTEMS multicast address</h3>
@ -318,17 +323,20 @@ information about incoming packets.
Example: Start a receiver of the following form (tried on Linux): Example: Start a receiver of the following form (tried on Linux):
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">socat -u \
socat -u UDP-RECVFROM:8888,reuseaddr,ip-add-membership=224.1.0.1:192.168.10.2,ip-pktinfo,fork SYSTEM:export UDP-RECVFROM:8888,reuseaddr,ip-add-membership=224.1.0.1:192.168.10.2,ip-pktinfo,fork \
</span></span> SYSTEM:export
</span>
<p> <p>
Then send a multicast packet from the client: Then send a multicast packet from the client:
</p> </p>
<span class="frame"><span class="shell"> <span class="shell">echo | \
echo |socat -u STDIO UDP-DATAGRAM:224.1.0.1:8888 socat -u \
</span></span> STDIO \
UDP-DATAGRAM:224.1.0.1:8888
</span>
<p> <p>
On the server the following text should appear (only interesting lines shown): On the server the following text should appear (only interesting lines shown):

32
doc/socat-openssltunnel.html
View file

@ -39,22 +39,21 @@ client.</p>
<p>Perform the following steps on a trusted host where OpenSSL is <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> 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> <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> <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> <p>Generate a self signed certificate:</p>
<span class="frame"><span class="shell"> <span class="shell">openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span>
openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span></span>
<p>You will be prompted for your country code, name etc.; you may quit all prompts <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> 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> <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 &gt;$FILENAME.pem</span></span> <span class="shell">cat $FILENAME.key $FILENAME.crt &gt;$FILENAME.pem</span>
<p>The files that contain the private key should be kept secret, thus adapt <p>The files that contain the private key should be kept secret, thus adapt
their permissions:<p> 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 <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 <tt>$HOME/etc/</tt>, using a secure channel like USB memory stick or SSH. Keep
@ -68,7 +67,7 @@ are not critical.
<h3>Generate a client certificate</h3> <h3>Generate a client certificate</h3>
<p>First prepare a different basename for the files related to the client certificate:</p> <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. <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 Copy <tt>client.pem</tt> to the SSL client, and <tt>client.crt</tt> to the
@ -81,7 +80,9 @@ for the server, <tt>cert=...</tt> tells the program to the file containing its
ceritificate and private key, and <tt>cafile=...</tt> points to the file 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 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> 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 <p>After starting this command, socat should be listening on port 4433, but
will require client authentication.</p> will require client authentication.</p>
@ -89,7 +90,8 @@ will require client authentication.</p>
<p>Substitute your <tt>tcp-connect</tt> or <tt>tcp</tt> address keyword with <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>openssl-connect</tt> or just <tt>ssl</tt> and here too add the
<tt>cert</tt> and <tt>cafile</tt> options:<p> <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 <p>This command should establish a secured connection to the server
process.</p> process.</p>
@ -99,21 +101,23 @@ process.</p>
to be adapted; <tt>ip6name.domain.org</tt> is assumed to resolve to the IPv6 to be adapted; <tt>ip6name.domain.org</tt> is assumed to resolve to the IPv6
address of the server:</p> address of the server:</p>
<p>Server:</p> <p>Server:</p>
<span class="frame"><span class="shell">socat <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> 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> <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> <h2>Troubleshooting</h2>
<h3>Test OpenSSL Integration</h3> <h3>Test OpenSSL Integration</h3>
<p> <p>
If you get error messages like this:</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. <p>your socat executable probably does not have the OpenSSL library linked in.
Check socat's compile time configuration with the following command:</p> 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: <p>Positive output:
<tt>#define WITH_OPENSSL 1</tt><br> <tt>#define WITH_OPENSSL 1</tt><br>
Negative output: Negative output:

22
doc/socat-tun.html
View file

@ -53,14 +53,20 @@ the two socat instances; the TUN interfaces both have the same quality.
<h3>TUN Server</h3> <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 <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 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 specifies the mask of the network that is pretended to be connected on this
interface.</p> interface.</p>
<h3>TUN Client</h3> <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 <p>This command should establish a connection to the server and create the TUN
device on the client.</p> device on the client.</p>
@ -85,17 +91,17 @@ the <tt>ifconfig</tt> command.
<h3>Test TUN integration</h3> <h3>Test TUN integration</h3>
<p> <p>
If you get error messages like this:</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 <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. reasons: you are not on Linux or are using an older version of socat.
</p> </p>
<h3>Missing kernel support</h3> <h3>Missing kernel support</h3>
<p>An error message like:</p> <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 <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> 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 <p>and check
for /dev/net/tun. If that does not succeed you need to for /dev/net/tun. If that does not succeed you need to
rebuild your kernel with the appropriate configuration (probably under rebuild your kernel with the appropriate configuration (probably under
@ -104,14 +110,14 @@ reasons: you are not on Linux or are using an older version of socat.
<h3>TUN cloning device permissions</h3> <h3>TUN cloning device permissions</h3>
<p>An error message like:</p> <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 <p>indicates that you do not have permission to read or write the TUN cloning
device. Check its permission and ownership.</p> device. Check its permission and ownership.</p>
<h3>Interface down</h3> <h3>Interface down</h3>
<p>If no error occurs but the pings do not work check if the network devices <p>If no error occurs but the pings do not work check if the network devices
have been created:</p> 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> <p>The output should look like:</p>
<pre> <pre>
tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 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 @@ tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
<h3>Routing</h3> <h3>Routing</h3>
<p></p> <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> <p>The output should look like:</p>
<pre> <pre>
192.168.255.0 0.0.0.0 255.255.255.0 U 0 0 0 tun0 192.168.255.0 0.0.0.0 255.255.255.0 U 0 0 0 tun0

509
doc/socat.yo
View file

@ -12,6 +12,8 @@ def(Procan)(0)(bf(Procan))
manpage(socat)(1)()()() manpage(socat)(1)()()()
htmlcommand(<link rel="stylesheet" type="text/css" href="dest-unreach.css">)
whenhtml( whenhtml(
label(CONTENTS) label(CONTENTS)
manpagesection(CONTENTS) manpagesection(CONTENTS)
@ -664,8 +666,8 @@ label(ADDRESS_PROXY_CONNECT)dit(bf(tt(PROXY:<proxy>:<hostname>:<port>)))
link(pf)(OPTION_PROTOCOL_FAMILY), and sends a CONNECT link(pf)(OPTION_PROTOCOL_FAMILY), and sends a CONNECT
request for hostname:port. If the proxy grants access and succeeds to request for hostname:port. If the proxy grants access and succeeds to
connect to the target, data transfer between socat and the target can 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 start (link(example)(EXAMPLE_PROXY_CONNECT)).
protocol. nl() 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() 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: Useful options:
link(proxyport)(OPTION_PROXYPORT), link(proxyport)(OPTION_PROXYPORT),
@ -1687,13 +1689,14 @@ label(OPTION_UNLINK_LATE)dit(bf(tt(unlink-late[=<bool>])))
Unlinks (removes) the file after opening it to make it inaccessible for Unlinks (removes) the file after opening it to make it inaccessible for
other processes after a short race condition. other processes after a short race condition.
label(OPTION_UNLINK_CLOSE)dit(bf(tt(unlink-close[=<bool>]))) 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), For link(named pipes)(ADDRESS_NAMED_PIPE),
link(UNIX domain sockets)(ADDRESS_UNIX_LISTEN), link(UNIX domain sockets)(ADDRESS_UNIX_LISTEN),
and the link(symbolic links)(OPTION_SYMBOLIC_LINK) of link(pty addresses)(ADDRESS_PTY), 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(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() enddit()
startdit()enddit()nl() startdit()enddit()nl()
@ -2065,7 +2068,7 @@ label(GROUP_SOCK_UNIX)em(bf(UNIX option group))
These options apply to UNIX domain based addresses. These options apply to UNIX domain based addresses.
startdit() 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 On socket operations, pass a socket address length that does not include the
whole code(struct sockaddr_un) record but (besides other components) only whole code(struct sockaddr_un) record but (besides other components) only
the relevant part of the filename or abstract string. Default is 1. the relevant part of the filename or abstract string. Default is 1.
@ -3115,8 +3118,18 @@ manpagesection(EXAMPLES)
startdit() 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) 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 transfers data between link(STDIO)(ADDRESS_STDIO) (-) and a
link(TCP4)(ADDRESS_TCP4_CONNECT) connection to port 80 of host link(TCP4)(ADDRESS_TCP4_CONNECT) connection to port 80 of host
@ -3128,12 +3141,16 @@ label(EXAMPLE_ADDRESS_READLINE)
label(EXAMPLE_OPTION_HISTORY) label(EXAMPLE_OPTION_HISTORY)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat -d -d READLINE,history=$HOME/.http_history \\ mancommand(\fBsocat -d -d \\)
TCP4:www.domain.org:www,crnl\fP) mancommand(\.RS)
mancommand(\fBREADLINE,history=$HOME/.http_history \\
TCP4:www.domain.org:www,crnl\fP)
mancommand(\.RE)
mancommand(\.fi) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat -d -d READLINE,history=$HOME/.http_history \</strong><br> htmlcommand(<hr><div class="shell">socat -d -d &#x5C;
<strong>TCP4:www.domain.org:www,crnl</strong></code><dd>) READLINE,history=$HOME/.http_history &#x5C;
TCP4:www.domain.org:www,crnl</div>)
this is similar to the previous example, but you can edit the current line in a 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 bash like manner (link(READLINE)(ADDRESS_READLINE)) and use the
@ -3143,8 +3160,21 @@ progress (link(-d -d)(option_d_d)). The port is specified by service name
(link(crnl)(OPTION_CRNL)) instead of NL are used. (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) 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 &#x5C;
TCP4-LISTEN:www &#x5C;
TCP4:www.domain.org:www</div>)
installs a simple TCP port forwarder. With installs a simple TCP port forwarder. With
link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN) it listens on local port "www" until a link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN) it listens on local port "www" until a
@ -3159,14 +3189,16 @@ label(EXAMPLE_OPTION_SUBSTUSER)
label(EXAMPLE_OPTION_RANGE) label(EXAMPLE_OPTION_RANGE)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat -d -d -lmlocal2 \\ mancommand(\fBsocat -d -d -lmlocal2 \\)
TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\ mancommand(\.RS)
TCP4:www.domain.org:80,bind=myaddr2\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat -d -d -lmlocal2 \</strong><br> htmlcommand(<hr><div class="shell">socat -d -d -lmlocal2 &#x5C;
<strong>TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \</strong><br> TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr &#x5C;
<strong>TCP4:www.domain.org:80,bind=myaddr2</strong></code><dd>) TCP4:www.domain.org:80,bind=myaddr2</div>)
TCP port forwarder, each side bound to another local IP address TCP port forwarder, each side bound to another local IP address
(link(bind)(OPTION_BIND)). This example handles an almost (link(bind)(OPTION_BIND)). This example handles an almost
@ -3190,12 +3222,16 @@ label(EXAMPLE_OPTION_PTY)
label(EXAMPLE_OPTION_STDERR) label(EXAMPLE_OPTION_STDERR)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat TCP4-LISTEN:5555,fork,tcpwrap=script \\ mancommand(\fBsocat \\)
EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat TCP4-LISTEN:5555,fork,tcpwrap=script \</strong><br> htmlcommand(<hr><div class="shell">socat &#x5C;
<strong>EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</strong></code><dd>) TCP4-LISTEN:5555,fork,tcpwrap=script &#x5C;
EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</div>)
a simple server that accepts connections a simple server that accepts connections
(link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN)) and link(fork)(OPTION_FORK)'s a new (link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN)) and link(fork)(OPTION_FORK)'s a new
@ -3217,12 +3253,16 @@ label(EXAMPLE_OPTION_CRNL)
label(EXAMPLE_OPTION_MSS) label(EXAMPLE_OPTION_MSS)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\ mancommand(\fBsocat \\)
TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \</strong><br> htmlcommand(<hr><div class="shell">socat &#x5C;
<strong>TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512</strong></code><dd>) EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 &#x5C;
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 file(mail.sh) is a shell script, distributed with socat(), that implements a
simple simple
@ -3240,7 +3280,18 @@ at most 512 data bytes per packet (link(mss)(OPTION_MSS)).
label(EXAMPLE_ADDRESS_GOPEN) label(EXAMPLE_ADDRESS_GOPEN)
label(EXAMPLE_OPTION_TERMIOS_RAWER) label(EXAMPLE_OPTION_TERMIOS_RAWER)
label(EXAMPLE_OPTION_ESCAPE) 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 &#x5C;
-,escape=0x0f &#x5C;
/dev/ttyS0,rawer,crnl</div>)
opens an interactive connection via the serial line, e.g. for talking with a 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 modem. link(rawer)(OPTION_TERMIOS_RAWER) sets the console's and
@ -3256,12 +3307,16 @@ label(EXAMPLE_OPTION_SOCKSUSER)
label(EXAMPLE_OPTION_SOURCEPORT) label(EXAMPLE_OPTION_SOURCEPORT)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \\ mancommand(\fBsocat \\)
SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \</strong><br> htmlcommand(<hr><div class="shell">socat &#x5C;
<strong>SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20</strong></code><dd>) UNIX-LISTEN:/tmp/.X11-unix/X1,fork &#x5C;
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 with link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), socat() opens a listening
unixdomain() socket file(/tmp/.X11-unix/X1). This path corresponds unixdomain() socket file(/tmp/.X11-unix/X1). This path corresponds
@ -3281,7 +3336,18 @@ session with a given set of addresses and ports.
label(EXAMPLE_option_u) label(EXAMPLE_option_u)
label(EXAMPLE_OPTION_IGNOREEOF) 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 &#x5C;
/tmp/readdata,seek-end=0,ignoreeof &#x5C;
STDIO</div>)
this is an example for unidirectional data transfer this is an example for unidirectional data transfer
(link(-u)(option_u)). Socat() transfers data (link(-u)(option_u)). Socat() transfers data
@ -3297,12 +3363,16 @@ label(EXAMPLE_OPTION_SETSID)
label(EXAMPLE_OPTION_CTTY) label(EXAMPLE_OPTION_CTTY)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | \\)
socat - EXEC:'ssh -l user server',pty,setsid,ctty\fP) mancommand(\fBsocat - \\)
mancommand(\.RS)
mancommand(\fBEXEC:'ssh -l user server',pty,setsid,ctty\fP)
mancommand(\.RE)
mancommand(\.fi) mancommand(\.fi)
htmlcommand(<dt><code><strong>(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |</strong><br> htmlcommand(<hr><div class="shell">(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
<strong>socat - EXEC:'ssh -l user server',pty,setsid,ctty</strong></code><dd>) socat - &#x5C;
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 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)), ssh, makes it ssh's controlling tty (link(ctty)(OPTION_CTTY)),
@ -3315,12 +3385,16 @@ label(EXAMPLE_OPTION_CREAT)
label(EXAMPLE_OPTION_APPEND) label(EXAMPLE_OPTION_APPEND)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat -u TCP4-LISTEN:3334,reuseaddr,fork \\ mancommand(\fBsocat -u \\)
OPEN:/tmp/in.log,creat,append\fP) mancommand(\.RS)
mancommand(\fBTCP4-LISTEN:3334,reuseaddr,fork \\
OPEN:/tmp/in.log,creat,append\fP)
mancommand(\.RE)
mancommand(\.fi) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat -u TCP4-LISTEN:3334,reuseaddr,fork \</strong><br> htmlcommand(<hr><div class="shell">socat -u &#x5C;
<strong>OPEN:/tmp/in.log,creat,append</strong></code><dd>) TCP4-LISTEN:3334,reuseaddr,fork &#x5C;
OPEN:/tmp/in.log,creat,append</div>)
implements a simple network based message collector. 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)). For each client connecting to port 3334, a new child process is generated (option link(fork)(OPTION_FORK)).
@ -3350,7 +3424,18 @@ window size.
) )
label(EXAMPLE_OPTION_NOECHO) 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 &#x5C;
READLINE,noecho='[Pp]assword:' &#x5C;
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. 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 This allows editing and reuse of FTP commands for relatively comfortable
@ -3366,12 +3451,16 @@ label(EXAMPLE_OPTION_WAIT_SLAVE)
label(EXAMPLE_OPTION_NONBLOCK) label(EXAMPLE_OPTION_NONBLOCK)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \\\bf) mancommand(\fBsocat \\)
mancommand(\fBEXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \</strong><br> htmlcommand(<hr><div class="shell">socat &#x5C;
<strong>EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</strong></code><dd>) PTY,link=$HOME/dev/vmodem0,rawer,wait-slave &#x5C;
EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</div>)
generates a pseudo terminal generates a pseudo terminal
device (link(PTY)(ADDRESS_PTY)) on the client that can be reached under the device (link(PTY)(ADDRESS_PTY)) on the client that can be reached under the
@ -3382,24 +3471,39 @@ to a modemserver via ssh where another socat instance links it to
file(/dev/ttyS0). file(/dev/ttyS0).
label(EXAMPLE_PROXY_CONNECT)
mancommand(\.LP) mancommand(\.LP)
mancommand(\.nf) mancommand(\.nf)
mancommand(\fBsocat TCP4-LISTEN:2022,reuseaddr,fork \\ mancommand(\fBsocat \\)
PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass\fP) 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) mancommand(\.fi)
htmlcommand(<dt><code><strong>socat TCP4-LISTEN:2022,reuseaddr,fork \</strong><br> htmlcommand(<hr><div class="shell">socat &#x5C;
<strong>PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass</strong></code><dd>) TCP4-LISTEN:2022,reuseaddr,fork &#x5C;
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 starts a forwarder that accepts connections on port 2022, and directs them
through the link(proxy)(ADDRESS_PROXY_CONNECT) daemon listening on port 3128 through the link(proxy)(ADDRESS_PROXY_CONNECT) daemon listening on port 3128
(link(proxyport)(OPTION_PROXYPORT)) on host proxy, using the (link(proxyport)(OPTION_PROXYPORT)) on host proxy.local, using the
CONNECT method, where they are authenticated as "user" with "pass" (link(proxyauth)(OPTION_PROXY_AUTHORIZATION)). The proxy 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. should establish connections to host www.domain.org on port 22 then.
label(EXAMPLE_ADDRESS_OPENSSL_CONNECT) 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 - &#x5C;
SSL:server:4443,cafile=./server.crt,cert=./client.pem</div>)
is an OpenSSL client that tries to establish a secure connection to an SSL 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 server. Option link(cafile)(OPTION_OPENSSL_CAFILE) specifies a file that
@ -3413,7 +3517,18 @@ The first address ('-') can be replaced by almost any other socat address.
label(EXAMPLE_ADDRESS_OPENSSL_LISTEN) 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 &#x5C;
OPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=./server.pem,cafile=./client.crt &#x5C;
PIPE</div>)
is an OpenSSL server that accepts TCP connections, presents the certificate 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 from the file server.pem and forces the client to present a certificate that is
@ -3424,16 +3539,38 @@ For instructions on generating and distributing OpenSSL keys and certificates
see the additional socat docu tt(socat-openssl.txt). 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 htmlcommand(<hr><div class="shell">echo |
supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of socat -u - &#x5C;
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 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: the resulting file can consume some disk space with just its inodes (reiserfs:
2MB; ext2: 16KB). 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 &#x5C;
TCP-L:7777,reuseaddr,fork &#x5C;
SYSTEM:'filan -i 0 -s >&2',nofork</div>)
listens for incoming TCP connections on port 7777. For each accepted listens for incoming TCP connections on port 7777. For each accepted
connection, invokes a shell. This shell has its stdin and stdout directly connection, invokes a shell. This shell has its stdin and stdout directly
@ -3441,20 +3578,51 @@ connected to the TCP socket (link(nofork)(OPTION_NOFORK)). The shell starts fil
stderr (your terminal window). 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 - &#x5C;
FILE:/usr/bin/squid.exe,seek=0x00074420</div>)
functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to 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 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, actual per May 2004). 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 - &#x5C;
TCP:www.blackhat.org:31337,readbytes=1000</div>)
connects to an unknown service and prevents being flooded. connects to an unknown service and prevents being flooded.
label(EXAMPLE_END_CLOSE) 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 &#x5C;
TCP:target:9999,end-close &#x5C;
TCP-L:8888,reuseaddr,fork</div>)
merges data arriving from different TCP streams on port 8888 to just one stream 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 to target:9999. The link(end-close)(OPTION_END_CLOSE) option prevents the child
@ -3465,7 +3633,18 @@ connection).
label(EXAMPLE_GENERIC_DCCP_SERVER) 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 &#x5C;
TCP-LISTEN:10021,reuseaddr,socktype=6,protocol=33,fork &#x5C;
PIPE</div>)
is a simple DCCP echo server. It uses socat()s TCP procedures, but changes the 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. socket type to SOCK_DCCP=6 (on Linux) and the IP protocol to IPPROTO_DCCP=33.
@ -3474,21 +3653,49 @@ datagram protocol.
label(EXAMPLE_GENERIC_DCCP_CLIENT) 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 - &#x5C;
TCP:<server>:10021,reuseaddr,socktype=6,protocol=33,fork</div>)
is a simple DCCP client. It uses socat()s TCP procedures, but changes the 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. socket type to SOCK_DCCP=6 (on Linux) and the IP protocol to IPPROTO_DCCP=33.
label(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT) 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 - &#x5C;
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 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. timeservers there. Ignores NTP packets from hosts outside this network.
label(EXAMPLE_ADDRESS_GENERIC_CLIENT) 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 - &#x5C;
SOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000</div>)
is semantically equivalent to the link(previous is semantically equivalent to the link(previous
example)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), but all parameters are example)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), but all parameters are
@ -3497,14 +3704,32 @@ tt(SO_BROADCAST).
label(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT) 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 - &#x5C;
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 sends a broadcast to the local NOEXPAND(network(s)) using protocol 44. Accepts replies
from the private address range only. from the private address range only.
label(EXAMPLE_ADDRESS_UDP4_MULTICAST) 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 - &#x5C;
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 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 local and remote ports are 6666. Tells the interface eth0 to also accept
@ -3516,7 +3741,18 @@ operating system, bridges, or a badly configured switch.
label(EXAMPLE_ADDRESS_TUN) 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 &#x5C;
UDP:host2:4443 &#x5C;
TUN:192.168.255.1/24,up</div>)
establishes one side of a virtual (but not private!) network with host2 where a 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 similar process might run, with UDP-L and tun address 192.168.255.2. They can
@ -3526,37 +3762,97 @@ might thus cause packet loss.
label(EXAMPLE_ADDRESS_VSOCK) 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 - &#x5C;
VSOCK-CONNECT:2:1234</div>)
establishes a VSOCK connection with the host (host is always reachable with establishes a VSOCK connection with the host (host is always reachable with
the well-know CID=2) on 1234 port. 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 - &#x5C;
VSOCK-LISTEN:1234</div>)
listens for a VSOCK connection on 1234 port. 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 - &#x5C;
VSOCK-CONNECT:31:4321,bind:5555</div>)
establishes a VSOCK connection with the guest that have CID=31 on 1234 port, establishes a VSOCK connection with the guest that have CID=31 on 1234 port,
binding the local socket to the 5555 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 &#x5C;
VSOCK-LISTEN:3333,reuseaddr,fork &#x5C;
VSOCK-CONNECT:42,3333</div>)
starts a forwarder that accepts VSOCK connections on port 3333, and directs starts a forwarder that accepts VSOCK connections on port 3333, and directs
them to the guest with CID=42 on the same port. 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 &#x5C;
VSOCK-LISTEN:22,reuseaddr,fork &#x5C;
TCP:localhost:22</div>)
forwards VSOCK connections from 22 port to the local SSH server. 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, Running this in a VM allows you to connect via SSH from the host using VSOCK,
as in the example below. 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 &#x5C;
TCP4-LISTEN:22222,reuseaddr,fork &#x5C;
VSOCK-CONNECT:33:22</div>)
forwards TCP connections from 22222 port to the guest with CID=33 listening on forwards TCP connections from 22222 port to the guest with CID=33 listening on
VSOCK port 22. VSOCK port 22.
@ -3565,7 +3861,18 @@ Running this in the host, allows you to connect via SSH running
label(EXAMPLE_INTERFACE) 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 &#x5C;
PTY,link=/var/run/ppp,rawer &#x5C;
INTERFACE:hdlc0</div>)
circumvents the problem that pppd requires a serial device and thus might not 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. be able to work on a synchronous line that is represented by a network device.
@ -3575,26 +3882,64 @@ both devices. Use pppd on device tt(/var/run/ppp) then.
label(EXAMPLE_HTTPECHO) 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 &#x5C;
TCP-L:10081,reuseaddr,fork,crlf &#x5C;
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 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 seen by the server host, the host address (which might vary on multihomed
servers), and the original client request. servers), and the original client request.
label(EXAMPLE_ANCILLARY) 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 &#x5C;
UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- &#x5C;
SYSTEM:'export; sleep 1' |
grep SOCAT</div>)
waits for an incoming UDP packet on port 9999 and prints the environment 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 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 SOCAT_IP_DSTADDR: it contains the target address of the packet which may be a
unicast, multicast, or broadcast address. unicast, multicast, or broadcast address.
label(EXAMPLE_SSD) label(EXAMPLE_SSDP)
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))) 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" | &#x5C;
socat - &#x5C;
UDP-DATAGRAM:239.255.255.250:1900,crlf</div>)
sends an SSDP (Simple Service Discovery Protocol) query to the local network sends an SSDP (Simple Service Discovery Protocol) query to the local network
and collects and outputs the answers received. and collects and outputs the answers received.