To link serial port ttyS0 to another serial port:
socat /dev/ttyS0,raw,echo=0,crnl /dev/ttyS1,raw,echo=0,crnl
To get time from time server:
socat TCP:time.nist.gov:13 -
To forward local http port to remote http port:
socat TCP-LISTEN:80,fork TCP:www.domain.org:80
To forward terminal to the serial port COM1:
socat READLINE,history=$HOME/.cmd_history /dev/ttyS0,raw,echo=0,crnl
On the server-side: socat TCP-LISTEN:port filename To send file fro the server: socat TCP:hostname:port filename
socat - TCP4:www.domain.org:80
Transfers data between STDIO (-) and a TCP4 connection to port 80 of host www.domain.org. This example results in an interactive connection similar to telnet or netcat. The stdin terminal parameters are not changed, so you may close the relay with ^D or abort it with ^C.
socat -d -d READLINE,history=$HOME/.http_history \
TCP4:www.domain.org:www,crnl
This is similar to the previous example, but you can edit the current line in a bash like manner (READLINE) and use the history file .http_history; socat prints messages about progress (-d -d). The port is specified by service name (www), and correct network line termination characters (crnl) instead of NL are used.
socat TCP4-LISTEN:www TCP4:www.domain.org:www
Installs a simple TCP port forwarder. With TCP4-LISTEN it listens on local port "www" until a connection comes in, accepts it, then connects to the remote host (TCP4) and starts data transfer. It will not accept a second connection.
socat -d -d -lmlocal2 \
TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \
TCP4:www.domain.org:80,bind=myaddr2
TCP port forwarder, each side bound to another local IP address (bind). This example handles an almost arbitrary number of parallel or consecutive connections by forking a new process after each accept(). It provides a little security by sudoing to user nobody after forking; it only permits connections from the private 10 network (range); due to reuseaddr, it allows immediate restart after master processes termination, even if some child sockets are not completely shut down. With -lmlocal2, socat logs to stderr until successfully reaching the accept loop. Further logging is directed to syslog with facility local2.
socat TCP4-LISTEN:5555,fork,tcpwrap=script \
EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
A simple server that accepts connections (TCP4-LISTEN) and forks a new child process for each connection; every child acts as single relay. The client must match the rules for daemon process name "script" in /etc/hosts.allow and /etc/hosts.deny, otherwise it is refused access (see "man 5 hosts_access"). For EXECuting the program, the child process chroots to /home/sandbox, sus to user sandbox, and then starts the program /home/sandbox/bin/myscript. Socat and myscript communicate via a pseudo tty (pty); myscripts stderr is redirected to stdout, so its error messages are transferred via socat to the connected client.
socat EXEC:"mail.sh [email protected]",fdin=3,fdout=4 \
TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
mail.sh is a shell script, distributed with socat, that implements a simple SMTP client. It is programmed to "speak" SMTP on its FDs 3 (in) and 4 (out). The fdin and fdout options tell socat to use these FDs for communication with the program. Because mail.sh inherits stdin and stdout while socat does not use them, the script can read a mail body from stdin. Socat makes alias1 your local source address (bind), cares for correct network line termination (crnl) and sends at most 512 data bytes per packet (mss).
socat - /dev/ttyS0,raw,echo=0,crnl
Opens an interactive connection via the serial line, e.g. for talking with a modem. raw and echo set ttyS0's terminal parameters to practicable values, crnl converts to correct newline characters. Consider using READLINE instead of `-'.
socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
With UNIX-LISTEN, socat opens a listening UNIX domain socket /tmp/.X11-unix/X1. This path corresponds to local XWindow display :1 on your machine, so XWindow client connections to DISPLAY=:1 are accepted. Socat then speaks with the SOCKS4 server host.victim.org that might permit sourceport 20 based connections due to an FTP related weakness in its static IP filters. Socat pretends to be invoked by socksuser nobody, and requests to be connected to loopback port 6000 (only weak sockd configurations will allow this). So we get a connection to the victims XWindow server and, if it does not require MIT cookies or Kerberos authentication, we can start work. Please note that there can only be one connection at a time, because TCP can establish only one session with a given set of addresses and ports.
socat -u /tmp/readdata,seek-end=0,ignoreeof -
This is an example for unidirectional data transfer (-u). Socat transfers data from file /tmp/readdata (implicit address GOPEN), starting at its current end (seek-end=0 lets socat start reading at current end of file; use seek=0 or no seek option to first read the existing data) in a "tail -f" like mode (ignoreeof). The "file" might also be a listening UNIX domain socket (do not use a seek option then).
(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
socat - EXEC:'ssh -l user server',pty,setsid,ctty
EXECutes an ssh session to server. Uses a pty for communication between socat and ssh, makes it ssh's controlling tty (ctty), and makes this pty the owner of a new process group (setsid), so ssh accepts the password from socat.
socat -u TCP4-LISTEN:3334,reuseaddr,fork \
OPEN:/tmp/in.log,creat,append
Implements a simple network based message collector. For each client connecting to port 3334, a new child process is generated (option fork). All data sent by the clients are appended to the file /tmp/in.log. If the file does not exist, socat creats it. Option reuseaddr allows immediate restart of the server process.
socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,setsid,ctty
Wraps a command line history (READLINE) around the EXECuted ftp client utility. This allows editing and reuse of FTP commands for relatively comfortable browsing through the ftp directory hierarchy. The password is echoed! pty is required to have ftp issue a prompt. Nevertheless, there may occur some confusion with the password and FTP prompts.
socat PTY,link=$HOME/dev/vmodem0,raw,echo=0,waitslave exec:'
Generates a pseudo terminal device (PTY) on the client that can be reached under the symbolic link $HOME/dev/vmodem0. An application that expects a serial line or modem can be configured to use $HOME/dev/vmodem0; its traffic will be directed to a modemserver via ssh where another socat instance links it with /dev/ttyS0.
socat TCP4-LISTEN:2022,reuseaddr,fork \
PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
starts a forwarder that accepts connections on port 2022, and directs them through the proxy daemon listening on port 3128 (proxyport) on host proxy, using the CONNECT method, where they are authenticated as "user" with "pass" (proxyauth). The proxy should establish connections to host www.domain.org on port 22 then.
echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
creates a 100GB sparse file; this requires a file system type that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and the resulting file can consume some disk space with just its inodes (reiserfs: 2MB; ext2:16KB).
socat tcp-l:7777,reuseaddr,fork system:filan -i 0 -s >&2,nofork
listens for incoming TCP connections on port 7777. For each accepted connection, invokes a shell. This shell has its stdin and stdout directly connected to the TCP socket (nofork). The shell starts filan and lets it print the socket addresses to stderr (your terminal window).
echo -e
functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch to make the squid executable from Cygwin run under Windows, actual per May 2004).
socat - tcp:www.blackhat.org:31337,readbytes=1000
connect to an unknown service and prevent being flooded.
// Examples for using socat (and filan)
//"$" means normal user, "#" requires privileges, "//" starts a comment
/////////////////////////////////////////////////////////////////////////////// // similar to netcat
// connect to 10.1.1.1 on port 80 and relay to and from stdio $ socat - TCP:10.1.1.1:80 # similar to "netcat 10.1.1.1 80"
// listen on port 25, wait for an incoming connection, use CR+NL on this // connection, relay data to and from stdio; // then emulate a mailserver by hand :-)
// listen on port 25, wait for an incoming connection, use CR+NL on this // connection, relay data to and from stdio, but have line editing and history; // then emulate a mailserver by hand :-)
// provide a transient history enabled front end to stupid line based // interactive programs $ socat readline exec:"nslookup",pty,ctty,setsid,echo=0 // same works for ftp (but password is not hidden)
// you may also use a file based history list $ socat readline,history=.nslookup_hist exec:"nslookup",pty,ctty,setsid,echo=0 // using ~ as abbreviation for $HOME does not work!
// poor mans 'telnetd' replacement
// and here an appropriate client: $ socat -,raw,echo=0 tcp:172.16.181.130:2023 // use ssl with client and server certificate for improved security; // replace /bin/login by /bin/bash when using SSL client authentication, can be // run without root then
// this is a cool trick, proposed by Christophe Lohr, to dump communications to // two files; it would also work for other manipulations (recode, compress...) // and it might also work with netcat ;-) $ socat TCP-LISTEN:5555 SYSTEM:'tee l2r | socat - "TCP:remote:5555" | tee r2l'
/////////////////////////////////////////////////////////////////////////////// // emergence solution because usleep(1) is not always available // this will "sleep" for 0.1s $ socat -T 0.1 pipe pipe
/////////////////////////////////////////////////////////////////////////////// // a very primitive HTTP/1.0 echo server (problems: sends reply headers before // request; hangs if client does not shutdown - HTTP keep-alive) // wait for a connection on port 8000; do not wait for request, but immediately // start a shell that sends reply headers and an empty line; then echo all // incoming data back to client $ socat TCP-LISTEN:8000,crlf SYSTEM:"echo HTTP/1.0 200; echo Content-Type: text/plain; echo; cat"
// a less primitive HTTP echo server that sends back not only the reqest but
// also server and client address and port. Might have portability issues with
// echo
./socat -T 1 -d -d tcp-l:10081,reuseaddr,fork,crlf system:"echo -e "\"HTTP/1.0 200 OK\\nDocumentType: text/html\\n\\ndate: $(date)
server:$SOCAT_SOCKADDR:$SOCAT_SOCKPORT
client: $SOCAT_PEERADDR:$SOCAT_PEERPORT\\n
\""; cat; echo -e "\"\\n\"""
/////////////////////////////////////////////////////////////////////////////// // for communicating with an attached modem, I had reasonable results with // following command line. Required privileges depend on device mode. // after leaving socat, type "sane". // replace /dev/ttyS0 by the correct serial line or with /dev/modem $ socat readline /dev/ttyS0,raw,echo=0,crlf // or $ socat readline /dev/ttyS0,raw,echo=0,crlf,nonblock // then enter "at$"
/////////////////////////////////////////////////////////////////////////////// // relay TCP port 80 from everywhere (internet, intranet, dmz) through your // firewall to your DMZ webserver (like plug-gw) // listen on port 80; whenever a connection is made, fork a new process (parent // process keeps accepting connections), su to nobody, and connect to // www.dmz.mydomain.org on port 80. // attention: this is a substitute for a reverse proxy without providing // application level security.
socat TCP-LISTEN:80,reuseaddr,fork,su=nobody TCP:www.dmz.mydomain.org:80
// Note: parent process keeps running as root, su after forking
/////////////////////////////////////////////////////////////////////////////// // relay mail from your DMZ server through your firewall. // accept connections only on dmz interface and allow connections only from // smtp.dmz.mydomain.org. // the advantages over plug-gw and other relays are: // * you can bind to an IP address (even an alias), therefore enhance security // * in your OS you can create several IP aliases and bind another socat daemon // to each, making several application servers addressable // * lots of options, like switching user, chroot, IP performance tuning // * no need for inetd
socat -lm -d -d TCP-LISTEN:25,bind=fw.dmz.mydomain.org,fork,su=nobody,range=smtp.dmz.mydomain.org/32 TCP:smtp.intra.mydomain.org:25
/////////////////////////////////////////////////////////////////////////////// // convert line terminator in ascii streams, stdin to stdout // use unidirectional mode, convert nl to crnl $ socat -u - -,crlf // or cr to nl $ socat -u -,cr -
// save piped data similar to 'tee': // copies stdin to stdout, but writes everything to the file too $ socat -,echo=0 open:/tmp/myfile,create,trunc,ignoreeof!!/tmp/myfile
/////////////////////////////////////////////////////////////////////////////// // intrusion testing
// found an XWindow Server behind IP filters with FTP data hole? (you are // lucky!) // prepare your host:
// relay a pseudo display :1 on your machine to victim:0
// and try to take a screendump (must be very lucky - when server has not even // host based authentication!)
// you sit behind a socks firewall that has IP filters but lazily allows socks // connections to loopback and has only host based X11 security. // like above, but from your inside client:
// or for the HTTP proxy:
/////////////////////////////////////////////////////////////////////////////// // forms of stdin with stdout, all equivalent $ socat echo - $ socat echo STDIO $ socat echo STDIN!!STDOUT $ socat echo STDIO!!STDIO $ socat echo -!!- $ socat echo FD:0!!FD:1 $ socat echo 0!!1 $ socat echo /dev/stdin!!/dev/stdout // if your OS provides these
/////////////////////////////////////////////////////////////////////////////// // some echo address examples $ socat - PIPE $ socat - PIPE:/tmp/pipi // other version of echo $ socat - PIPE:/tmp/pipi,nonblock!!/tmp/pipi // other version of echo $ socat - EXEC:/bin/cat // another echo $ socat - SYSTEM:/bin/cat // another echo $ socat - TCP:loopback:7 // if inetd echo/TCP service activated $ socat - UDP:loopback:7 // if inetd echo/UDP service activated $ socat - /tmp/hugo,trunc,ignoreeof!!/tmp/hugo // with delay $ socat - UDP:loopback:2000,bind=:2000 // self "connection" $ socat - TCP:loopback:2000,bind=:2000 // Linux bug?
// Linux might drop packets with less than 8 bytes payload)
/////////////////////////////////////////////////////////////////////////////// // unidirectional data transfer $ socat -u - - // like "tail -f", but start with showing all file contents $ socat -u FILE:/var/log/syslog.debug,ignoreeof - // like "tail -f", but do not show existing file contents $ socat -u FILE:/var/log/syslog.debug,ignoreeof,seek-end - // write to new file, create with given permission and group (must be member) - race condition with group!!! $ socat -u - CREATE:/tmp/outfile1,group=floppy,perm=0640 // // for an existing file /tmp/outfile1
/////////////////////////////////////////////////////////////////////////////// // file handling $ socat - FILE:/tmp/outfile1,ignoreeof!!FILE:/tmp/outfile1,append // prints outfile1, then echoes input and protocols into file (appends to old data)
/////////////////////////////////////////////////////////////////////////////// // unix socket handling
// create a listening unix socket $ rm -f /tmp/mysocket; socat UNIX-LISTEN:/tmp/mysocket - // from another terminal, connect to this socket $ socat UNIX:/tmp/mysocket - // then transfer data bidirectionally
/////////////////////////////////////////////////////////////////////////////// // transport examples
// socks relay (externally socksify applications); // your ssh client and OS are not socksified, but you want to pass a socks // server with ssh: $ socat TCP-LISTEN:10022,fork SOCKS4:socks.mydomain.org:ssh-serv:22 $ ssh -p 10022 loopback // or better define a ProxyCommand in ~/.ssh/config: ProxyCommand socat - SOCKS:socks.mydomain.org:%h:%p // and with proxy: ProxyCommand socat - PROXY:proxy.mydomain.org:%h:%p,proxyport=8000
/////////////////////////////////////////////////////////////////////////////// // application examples
// run sendmail daemon with your favorite network options
// local mail delivery over UNIX socket - no SUID program required
$ socat - /tmp/postoffice
/////////////////////////////////////////////////////////////////////////////// // uses of filan // see what your operating system opens for you $ filan // or if that was too detailled $ filan -s // see what file descriptors are passed via exec function $ socat - EXEC:filan,nofork $ socat - EXEC:filan $ socat - EXEC:filan,pipes,stderr $ socat - EXEC:filan,pipes $ socat - EXEC:filan,pty // see what's done by your shell and with option "pipes" $ socat - SYSTEM:filan,pipes // see if gdb gives you an equivalent environment or opens some files for your program $ gdb ./filan (gdb) r (gdb) r -s
/////////////////////////////////////////////////////////////////////////////// // want to use chat from the ppp package? // note: some OS's do not need "-e" for echo to print control characters // note: chat might send bytes one by one // with AIX, a similar program is available under the name "pppdial" $ socat -d -d tcp:localhost:25,crlf,nodelay exec:'/usr/sbin/chat -v -s ""220 "" ""HELO loopback"" ""250 "" ""MAIL FROM: hugo@localhost"" ""250 "" ""RCPT TO: root"" ""250 "" ""DATA"" ""354 "" ""test1'$(echo -e "\r.")'"" ""250 "" ""QUIT"" ""221 ""',pty,echo=0,cr
////////////////////////////////////////////////////////////////////////////// // IP6
/////////////////////////////////////////////////////////////////////////////// // application server solutions // run a program (here: /bin/sh) chrooted, unprivileged; // parent process stays in real / running as root
// make a program available on the network chrooted, unprivileged; // parent process stays in / running as root // script path is already chrooted
./socat -lm -d -d TCP-LISTEN:5555,fork EXEC:/bin/myscript,chroot=/home/sandbox,su=sandbox,pty,stderr
// to avoid terminal problems, you might - instead of telnet - connect using $ socat -,icanon=0,echo=0 tcp:target:5555; reset
// access local display from ssh server, when ssh port forwarding is disabled // socat must be installed on ssh server host // might have to use xauth... // this example is one-shot because ssh can handle only one channel xterm1$ socat -d -d exec:"ssh www.dest-unreach.org rm -f /tmp/.X11-unix/X9; ~/bin/socat -d -d unix-l:/tmp/.X11-unix/X9,fork -" unix:/tmp/.X11-unix/X0 xterm2$ ssh target target$ DISPLAY=:9 myxapplication
// touch with perms: // no race condition for perms (applied with creat() call) $ socat -u /dev/null creat:/tmp/tempfile,perm=0600
// touch with owner and perms: // race condition before changing owner, but who cares - only root may access
// invoke an interactive ssh with exec // first example passes control chars (^C etc.) to remote server as usual socat -,echo=0,raw exec:'ssh server',pty,setsid,ctty // second example interprets control chars on local command line socat -,echo=0,icanon=0 exec:'ssh server',pty,setsid,ctty // afterwards, type "reset"!
// convince ssh to provide an "interactive" shell to your script // three main versions for entering password: // 1) from your TTY; have 10 seconds to enter password: (sleep 10; echo "ls"; sleep 1) |socat - exec:'ssh server',pty // 2) from XWindows (DISPLAY !); again 10 seconds (sleep 10; echo "ls"; sleep 1) |socat - exec:'ssh server',pty,setsid // 3) from script (sleep 5; echo PASSWORD; echo ls; sleep 1) |./socat - exec:'ssh server',pty,setsid,ctty
// download with proxy CONNECT // use echo -e if required for \n $ (echo -e "CONNECT 128.129.130.131:80 HTTP/1.0\n"; sleep 5; echo -e "GET /download/file HTTP/1.0\n"; sleep 10) |socat -d -d -t 3600 - tcp:proxy:8080,crlf
// retrieve a file from an sshd site with sourceforge style entry menu; // fill in your personal values; cat lets you enter your password (will be // visible on screen) $ (sleep 10; read pass; echo $pass; sleep 10; echo M; sleep 5; echo cat FILENAME; sleep 10) |./socat -d -d -ly - EXEC:'ssh -c 3des -l USER cf.sourceforge.net',pty,setsid,ctty |tee FILENAME
// multicast community on local network: start the following command on all // participating hosts; like a conference call:
socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0,bindtodevice=eth0
// or $ socat -d -d -d -d - udp-datagram:224.0.0.2:6666,bind=:6666,ip-add-membership=224.0.0.2:eth0 // possible reasons for failure: // iptables or other filters (open your filters as required) // packets leave via wrong interface (set route: ...) // socket bound to specific address
//============================================================================= // GENERIC FUNCTION CALLS
// ioctl(): open CD drive (given value valid on Linux) // on my Linux system I find in /usr/include/linux/cdrom.h the define: // #define CDROMEJECT 0x5309 /* Ejects the cdrom media */ // the following command makes something like ioctl(fd, CDROMEJECT, NULL) // (don't care about the read error): $ socat /dev/cdrom,o-nonblock,ioctl-void=0x5309 -
// setsockopt(): SO_REUSEADDR // the following command performs - beyond lots of overhead - something like: // myint=1; setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &myint, sizeof(myint)) $ socat -u udp-recv:7777,setsockopt-int=1:2:1 - // setsockopt(): SO_BINDTODEVICE
// ways to apply SO_BINDTODEVICE without using the special socat address option // so-bindtodevice: // with string argument: $ sudo ./socat tcp-l:7777,setsockopt-string=1:25:eth0 pipe // with binary argument: $ sudo ./socat tcp-l:7777,setsockopt-bin=1:25:x6574683000 pipe
===============================================================================
// not tested, just ideas, or have problems
// traverse firewall for making internal telnet server accessible for outside // telnet client, when only outbound traffic (syn-filter) is allowed: // on external client run "double server". this process waits for a // connection from localhost on port 10023, and, when it is established, waits // for a connection from anywhere to port 20023: ext$ socat -d TCP-LISTEN:10023,range=localhost TCP-LISTEN:20023 // on internal server run double client: int$ socat -d TCP:localhost:23 TCP:extclient:10023 // or, with socks firewall: int$ socat -d TCP:localhost:23 SOCKS:socksserver:extclient:10023 // login with: ext$ telnet localhost 20023
// you can make a double server capable of handling multiple instances: ext$ socat -d TCP-LISTEN:10023,range=localhost,fork TCP-LISTEN:20023,reuseaddr
// access remote display via ssh, when ssh port forwarding is disabled $ socat -d -d EXEC:"ssh target socat - UNIX:/tmp/.X11-unix/X0" TCP-LISTEN:6030 $ xclock -display localhost:30
// relay multiple webserver addresses through your firewall into your DMZ: // make IP aliases on your firewall, and then:
// and for improved security:
// proxy an arbitrary IP protocol over your firewall (answers won't work)
// proxy an unsupported IP protocol over your firewall, point to point // end points see firewall interfaces as IP peers!
// note that, for IPsec, you might face problems that are known with NAT