1.\" $OpenBSD: nc.1,v 1.60 2012/02/07 12:11:43 lum Exp $ 2.\" 3.\" Copyright (c) 1996 David Sacerdote 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd October 4, 2011 31.Dt NC 1 32.Os 33.Sh NAME 34.Nm nc 35.Nd arbitrary TCP and UDP connections and listens 36.Sh SYNOPSIS 37.Nm nc 38.Bk -words 39.Op Fl 46DdEhklnrStUuvz 40.Op Fl e Ar IPsec_policy 41.Op Fl I Ar length 42.Op Fl i Ar interval 43.Op Fl -no-tcpopt 44.Op Fl O Ar length 45.Op Fl P Ar proxy_username 46.Op Fl p Ar source_port 47.Op Fl s Ar source 48.Op Fl T Ar toskeyword 49.Op Fl V Ar rtable 50.Op Fl w Ar timeout 51.Op Fl X Ar proxy_protocol 52.Oo Xo 53.Fl x Ar proxy_address Ns Oo : Ns 54.Ar port Oc 55.Xc Oc 56.Op Ar destination 57.Op Ar port 58.Ek 59.Sh DESCRIPTION 60The 61.Nm 62(or 63.Nm netcat ) 64utility is used for just about anything under the sun involving TCP, 65UDP, or 66.Ux Ns -domain 67sockets. 68It can open TCP connections, send UDP packets, listen on arbitrary 69TCP and UDP ports, do port scanning, and deal with both IPv4 and 70IPv6. 71Unlike 72.Xr telnet 1 , 73.Nm 74scripts nicely, and separates error messages onto standard error instead 75of sending them to standard output, as 76.Xr telnet 1 77does with some. 78.Pp 79Common uses include: 80.Pp 81.Bl -bullet -offset indent -compact 82.It 83simple TCP proxies 84.It 85shell-script based HTTP clients and servers 86.It 87network daemon testing 88.It 89a SOCKS or HTTP ProxyCommand for 90.Xr ssh 1 91.It 92and much, much more 93.El 94.Pp 95The options are as follows: 96.Bl -tag -width Ds 97.It Fl 4 98Forces 99.Nm 100to use IPv4 addresses only. 101.It Fl 6 102Forces 103.Nm 104to use IPv6 addresses only. 105.It Fl D 106Enable debugging on the socket. 107.It Fl d 108Do not attempt to read from stdin. 109.It Fl E 110Shortcut for 111.Qo 112.Li "-e 'in ipsec esp/transport//require'" 113.Li "-e 'out ipsec esp/transport//require'" 114.Qc , 115which enables IPsec ESP transport mode in both 116directions. 117.It Fl e 118If IPsec support is available, then one can specify the IPsec policies 119to be used using the syntax described in 120.Xr ipsec_set_policy 3 . 121This flag can be specified up to two times, as typically one policy for 122each direction is needed. 123.It Fl h 124Prints out 125.Nm 126help. 127.It Fl I Ar length 128Specifies the size of the TCP receive buffer. 129.It Fl i Ar interval 130Specifies a delay time interval between lines of text sent and received. 131Also causes a delay time between connections to multiple ports. 132.It Fl k 133Forces 134.Nm 135to stay listening for another connection after its current connection 136is completed. 137It is an error to use this option without the 138.Fl l 139option. 140.It Fl l 141Used to specify that 142.Nm 143should listen for an incoming connection rather than initiate a 144connection to a remote host. 145It is an error to use this option in conjunction with the 146.Fl p , 147.Fl s , 148or 149.Fl z 150options. 151Additionally, any timeouts specified with the 152.Fl w 153option are ignored. 154.It Fl n 155Do not do any DNS or service lookups on any specified addresses, 156hostnames or ports. 157.It Fl -no-tcpopt 158Disables the use of TCP options on the socket, by setting the boolean 159TCP_NOOPT 160socket option. 161.It Fl O Ar length 162Specifies the size of the TCP send buffer. 163.It Fl P Ar proxy_username 164Specifies a username to present to a proxy server that requires authentication. 165If no username is specified then authentication will not be attempted. 166Proxy authentication is only supported for HTTP CONNECT proxies at present. 167.It Fl p Ar source_port 168Specifies the source port 169.Nm 170should use, subject to privilege restrictions and availability. 171It is an error to use this option in conjunction with the 172.Fl l 173option. 174.It Fl r 175Specifies that source and/or destination ports should be chosen randomly 176instead of sequentially within a range or in the order that the system 177assigns them. 178.It Fl S 179Enables the RFC 2385 TCP MD5 signature option. 180.It Fl s Ar source 181Specifies the IP of the interface which is used to send the packets. 182For 183.Ux Ns -domain 184datagram sockets, specifies the local temporary socket file 185to create and use so that datagrams can be received. 186It is an error to use this option in conjunction with the 187.Fl l 188option. 189.It Fl T Ar toskeyword 190Change IPv4 TOS value. 191.Ar toskeyword 192may be one of 193.Ar critical , 194.Ar inetcontrol , 195.Ar lowdelay , 196.Ar netcontrol , 197.Ar throughput , 198.Ar reliability , 199or one of the DiffServ Code Points: 200.Ar ef , 201.Ar af11 ... af43 , 202.Ar cs0 ... cs7 ; 203or a number in either hex or decimal. 204.It Fl t 205Causes 206.Nm 207to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests. 208This makes it possible to use 209.Nm 210to script telnet sessions. 211.It Fl U 212Specifies to use 213.Ux Ns -domain 214sockets. 215.It Fl u 216Use UDP instead of the default option of TCP. 217For 218.Ux Ns -domain 219sockets, use a datagram socket instead of a stream socket. 220If a 221.Ux Ns -domain 222socket is used, a temporary receiving socket is created in 223.Pa /tmp 224unless the 225.Fl s 226flag is given. 227.It Fl V Ar rtable 228Set the routing table 229.Pq Dq FIB 230to be used. 231The default is 0. 232.It Fl v 233Have 234.Nm 235give more verbose output. 236.It Fl w Ar timeout 237Connections which cannot be established or are idle timeout after 238.Ar timeout 239seconds. 240The 241.Fl w 242flag has no effect on the 243.Fl l 244option, i.e.\& 245.Nm 246will listen forever for a connection, with or without the 247.Fl w 248flag. 249The default is no timeout. 250.It Fl X Ar proxy_protocol 251Requests that 252.Nm 253should use the specified protocol when talking to the proxy server. 254Supported protocols are 255.Dq 4 256(SOCKS v.4), 257.Dq 5 258(SOCKS v.5) 259and 260.Dq connect 261(HTTPS proxy). 262If the protocol is not specified, SOCKS version 5 is used. 263.It Xo 264.Fl x Ar proxy_address Ns Oo : Ns 265.Ar port Oc 266.Xc 267Requests that 268.Nm 269should connect to 270.Ar destination 271using a proxy at 272.Ar proxy_address 273and 274.Ar port . 275If 276.Ar port 277is not specified, the well-known port for the proxy protocol is used (1080 278for SOCKS, 3128 for HTTPS). 279.It Fl z 280Specifies that 281.Nm 282should just scan for listening daemons, without sending any data to them. 283It is an error to use this option in conjunction with the 284.Fl l 285option. 286.El 287.Pp 288.Ar destination 289can be a numerical IP address or a symbolic hostname 290(unless the 291.Fl n 292option is given). 293In general, a destination must be specified, 294unless the 295.Fl l 296option is given 297(in which case the local host is used). 298For 299.Ux Ns -domain 300sockets, a destination is required and is the socket path to connect to 301(or listen on if the 302.Fl l 303option is given). 304.Pp 305.Ar port 306can be a single integer or a range of ports. 307Ranges are in the form nn-mm. 308In general, 309a destination port must be specified, 310unless the 311.Fl U 312option is given. 313.Sh CLIENT/SERVER MODEL 314It is quite simple to build a very basic client/server model using 315.Nm . 316On one console, start 317.Nm 318listening on a specific port for a connection. 319For example: 320.Pp 321.Dl $ nc -l 1234 322.Pp 323.Nm 324is now listening on port 1234 for a connection. 325On a second console 326.Pq or a second machine , 327connect to the machine and port being listened on: 328.Pp 329.Dl $ nc 127.0.0.1 1234 330.Pp 331There should now be a connection between the ports. 332Anything typed at the second console will be concatenated to the first, 333and vice-versa. 334After the connection has been set up, 335.Nm 336does not really care which side is being used as a 337.Sq server 338and which side is being used as a 339.Sq client . 340The connection may be terminated using an 341.Dv EOF 342.Pq Sq ^D . 343.Sh DATA TRANSFER 344The example in the previous section can be expanded to build a 345basic data transfer model. 346Any information input into one end of the connection will be output 347to the other end, and input and output can be easily captured in order to 348emulate file transfer. 349.Pp 350Start by using 351.Nm 352to listen on a specific port, with output captured into a file: 353.Pp 354.Dl $ nc -l 1234 \*(Gt filename.out 355.Pp 356Using a second machine, connect to the listening 357.Nm 358process, feeding it the file which is to be transferred: 359.Pp 360.Dl $ nc host.example.com 1234 \*(Lt filename.in 361.Pp 362After the file has been transferred, the connection will close automatically. 363.Sh TALKING TO SERVERS 364It is sometimes useful to talk to servers 365.Dq by hand 366rather than through a user interface. 367It can aid in troubleshooting, 368when it might be necessary to verify what data a server is sending 369in response to commands issued by the client. 370For example, to retrieve the home page of a web site: 371.Bd -literal -offset indent 372$ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80 373.Ed 374.Pp 375Note that this also displays the headers sent by the web server. 376They can be filtered, using a tool such as 377.Xr sed 1 , 378if necessary. 379.Pp 380More complicated examples can be built up when the user knows the format 381of requests required by the server. 382As another example, an email may be submitted to an SMTP server using: 383.Bd -literal -offset indent 384$ nc localhost 25 \*(Lt\*(Lt EOF 385HELO host.example.com 386MAIL FROM:\*(Ltuser@host.example.com\*(Gt 387RCPT TO:\*(Ltuser2@host.example.com\*(Gt 388DATA 389Body of email. 390\&. 391QUIT 392EOF 393.Ed 394.Sh PORT SCANNING 395It may be useful to know which ports are open and running services on 396a target machine. 397The 398.Fl z 399flag can be used to tell 400.Nm 401to report open ports, 402rather than initiate a connection. 403For example: 404.Bd -literal -offset indent 405$ nc -z host.example.com 20-30 406Connection to host.example.com 22 port [tcp/ssh] succeeded! 407Connection to host.example.com 25 port [tcp/smtp] succeeded! 408.Ed 409.Pp 410The port range was specified to limit the search to ports 20 \- 30. 411.Pp 412Alternatively, it might be useful to know which server software 413is running, and which versions. 414This information is often contained within the greeting banners. 415In order to retrieve these, it is necessary to first make a connection, 416and then break the connection when the banner has been retrieved. 417This can be accomplished by specifying a small timeout with the 418.Fl w 419flag, or perhaps by issuing a 420.Qq Dv QUIT 421command to the server: 422.Bd -literal -offset indent 423$ echo "QUIT" | nc host.example.com 20-30 424SSH-1.99-OpenSSH_3.6.1p2 425Protocol mismatch. 426220 host.example.com IMS SMTP Receiver Version 0.84 Ready 427.Ed 428.Sh EXAMPLES 429Open a TCP connection to port 42 of host.example.com, using port 31337 as 430the source port, with a timeout of 5 seconds: 431.Pp 432.Dl $ nc -p 31337 -w 5 host.example.com 42 433.Pp 434Open a UDP connection to port 53 of host.example.com: 435.Pp 436.Dl $ nc -u host.example.com 53 437.Pp 438Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the 439IP for the local end of the connection: 440.Pp 441.Dl $ nc -s 10.1.2.3 host.example.com 42 442.Pp 443Open a TCP connection to port 42 of host.example.com using IPsec ESP for 444incoming and outgoing traffic. 445.Pp 446.Dl $ nc -E host.example.com 42 447.Pp 448Open a TCP connection to port 42 of host.example.com using IPsec ESP for 449outgoing traffic only. 450.Pp 451.Dl $ nc -e 'out ipsec esp/transport//require' host.example.com 42 452.Pp 453Create and listen on a 454.Ux Ns -domain 455stream socket: 456.Pp 457.Dl $ nc -lU /var/tmp/dsocket 458.Pp 459Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4, 460port 8080. 461This example could also be used by 462.Xr ssh 1 ; 463see the 464.Cm ProxyCommand 465directive in 466.Xr ssh_config 5 467for more information. 468.Pp 469.Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42 470.Pp 471The same example again, this time enabling proxy authentication with username 472.Dq ruser 473if the proxy requires it: 474.Pp 475.Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42 476.Sh EXIT STATUS 477.Ex -std 478.Sh SEE ALSO 479.Xr cat 1 , 480.Xr setfib 1 , 481.Xr ssh 1 , 482.Xr tcp 4 483.Sh AUTHORS 484Original implementation by *Hobbit* 485.Aq hobbit@avian.org . 486.br 487Rewritten with IPv6 support by 488.An Eric Jackson Aq ericj@monkey.org . 489.Sh CAVEATS 490UDP port scans using the 491.Fl uz 492combination of flags will always report success irrespective of 493the target machine's state. 494However, 495in conjunction with a traffic sniffer either on the target machine 496or an intermediary device, 497the 498.Fl uz 499combination could be useful for communications diagnostics. 500Note that the amount of UDP traffic generated may be limited either 501due to hardware resources and/or configuration settings. 502