1.\" $OpenBSD: nc.1,v 1.55 2010/07/25 07:51:39 guenther 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 July 25, 2010 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_ip_address 48.Op Fl T Ar ToS 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 hostname 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 65or UDP. 66It can open TCP connections, send UDP packets, listen on arbitrary 67TCP and UDP ports, do port scanning, and deal with both IPv4 and 68IPv6. 69Unlike 70.Xr telnet 1 , 71.Nm 72scripts nicely, and separates error messages onto standard error instead 73of sending them to standard output, as 74.Xr telnet 1 75does with some. 76.Pp 77Common uses include: 78.Pp 79.Bl -bullet -offset indent -compact 80.It 81simple TCP proxies 82.It 83shell-script based HTTP clients and servers 84.It 85network daemon testing 86.It 87a SOCKS or HTTP ProxyCommand for 88.Xr ssh 1 89.It 90and much, much more 91.El 92.Pp 93The options are as follows: 94.Bl -tag -width Ds 95.It Fl 4 96Forces 97.Nm 98to use IPv4 addresses only. 99.It Fl 6 100Forces 101.Nm 102to use IPv6 addresses only. 103.It Fl D 104Enable debugging on the socket. 105.It Fl d 106Do not attempt to read from stdin. 107.It Fl E 108Shortcut for 109.Qo 110.Li "-e 'in ipsec esp/transport//require'" 111.Li "-e 'out ipsec esp/transport//require'" 112.Qc , 113which enables IPsec ESP transport mode in both 114directions. 115.It Fl e 116If IPsec support is available, then one can specify the IPsec policies 117to be used using the syntax described in 118.Xr ipsec_set_policy 3 . 119This flag can be specified up to two times, as typically one policy for 120each direction is needed. 121.It Fl h 122Prints out 123.Nm 124help. 125.It Fl I Ar length 126Specifies the size of the TCP receive buffer. 127.It Fl i Ar interval 128Specifies a delay time interval between lines of text sent and received. 129Also causes a delay time between connections to multiple ports. 130.It Fl k 131Forces 132.Nm 133to stay listening for another connection after its current connection 134is completed. 135It is an error to use this option without the 136.Fl l 137option. 138.It Fl l 139Used to specify that 140.Nm 141should listen for an incoming connection rather than initiate a 142connection to a remote host. 143It is an error to use this option in conjunction with the 144.Fl p , 145.Fl s , 146or 147.Fl z 148options. 149Additionally, any timeouts specified with the 150.Fl w 151option are ignored. 152.It Fl n 153Do not do any DNS or service lookups on any specified addresses, 154hostnames or ports. 155.It Fl -no-tcpopt 156Disables the use of TCP options on the socket, by setting the boolean 157TCP_NOOPT 158socket option. 159.It Fl O Ar length 160Specifies the size of the TCP send buffer. 161.It Fl P Ar proxy_username 162Specifies a username to present to a proxy server that requires authentication. 163If no username is specified then authentication will not be attempted. 164Proxy authentication is only supported for HTTP CONNECT proxies at present. 165.It Fl p Ar source_port 166Specifies the source port 167.Nm 168should use, subject to privilege restrictions and availability. 169It is an error to use this option in conjunction with the 170.Fl l 171option. 172.It Fl r 173Specifies that source and/or destination ports should be chosen randomly 174instead of sequentially within a range or in the order that the system 175assigns them. 176.It Fl S 177Enables the RFC 2385 TCP MD5 signature option. 178.It Fl s Ar source_ip_address 179Specifies the IP of the interface which is used to send the packets. 180It is an error to use this option in conjunction with the 181.Fl l 182option. 183.It Fl T Ar ToS 184Specifies IP Type of Service (ToS) for the connection. 185Valid values are the tokens 186.Dq lowdelay , 187.Dq throughput , 188.Dq reliability , 189or an 8-bit hexadecimal value preceded by 190.Dq 0x . 191.It Fl t 192Causes 193.Nm 194to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests. 195This makes it possible to use 196.Nm 197to script telnet sessions. 198.It Fl U 199Specifies to use 200.Ux Ns -domain 201sockets. 202.It Fl u 203Use UDP instead of the default option of TCP. 204.It Fl V Ar rtable 205Set the routing table 206.Pq Dq FIB 207to be used. 208The default is 0. 209.It Fl v 210Have 211.Nm 212give more verbose output. 213.It Fl w Ar timeout 214If a connection and stdin are idle for more than 215.Ar timeout 216seconds, then the connection is silently closed. 217The 218.Fl w 219flag has no effect on the 220.Fl l 221option, i.e.\& 222.Nm 223will listen forever for a connection, with or without the 224.Fl w 225flag. 226The default is no timeout. 227.It Fl X Ar proxy_protocol 228Requests that 229.Nm 230should use the specified protocol when talking to the proxy server. 231Supported protocols are 232.Dq 4 233(SOCKS v.4), 234.Dq 5 235(SOCKS v.5) 236and 237.Dq connect 238(HTTPS proxy). 239If the protocol is not specified, SOCKS version 5 is used. 240.It Xo 241.Fl x Ar proxy_address Ns Oo : Ns 242.Ar port Oc 243.Xc 244Requests that 245.Nm 246should connect to 247.Ar hostname 248using a proxy at 249.Ar proxy_address 250and 251.Ar port . 252If 253.Ar port 254is not specified, the well-known port for the proxy protocol is used (1080 255for SOCKS, 3128 for HTTPS). 256.It Fl z 257Specifies that 258.Nm 259should just scan for listening daemons, without sending any data to them. 260It is an error to use this option in conjunction with the 261.Fl l 262option. 263.El 264.Pp 265.Ar hostname 266can be a numerical IP address or a symbolic hostname 267(unless the 268.Fl n 269option is given). 270In general, a hostname must be specified, 271unless the 272.Fl l 273option is given 274(in which case the local host is used). 275.Pp 276.Ar port 277can be a single integer or a range of ports. 278Ranges are in the form nn-mm. 279In general, 280a destination port must be specified, 281unless the 282.Fl U 283option is given 284(in which case a socket must be specified). 285.Sh CLIENT/SERVER MODEL 286It is quite simple to build a very basic client/server model using 287.Nm . 288On one console, start 289.Nm 290listening on a specific port for a connection. 291For example: 292.Pp 293.Dl $ nc -l 1234 294.Pp 295.Nm 296is now listening on port 1234 for a connection. 297On a second console 298.Pq or a second machine , 299connect to the machine and port being listened on: 300.Pp 301.Dl $ nc 127.0.0.1 1234 302.Pp 303There should now be a connection between the ports. 304Anything typed at the second console will be concatenated to the first, 305and vice-versa. 306After the connection has been set up, 307.Nm 308does not really care which side is being used as a 309.Sq server 310and which side is being used as a 311.Sq client . 312The connection may be terminated using an 313.Dv EOF 314.Pq Sq ^D . 315.Sh DATA TRANSFER 316The example in the previous section can be expanded to build a 317basic data transfer model. 318Any information input into one end of the connection will be output 319to the other end, and input and output can be easily captured in order to 320emulate file transfer. 321.Pp 322Start by using 323.Nm 324to listen on a specific port, with output captured into a file: 325.Pp 326.Dl $ nc -l 1234 \*(Gt filename.out 327.Pp 328Using a second machine, connect to the listening 329.Nm 330process, feeding it the file which is to be transferred: 331.Pp 332.Dl $ nc host.example.com 1234 \*(Lt filename.in 333.Pp 334After the file has been transferred, the connection will close automatically. 335.Sh TALKING TO SERVERS 336It is sometimes useful to talk to servers 337.Dq by hand 338rather than through a user interface. 339It can aid in troubleshooting, 340when it might be necessary to verify what data a server is sending 341in response to commands issued by the client. 342For example, to retrieve the home page of a web site: 343.Bd -literal -offset indent 344$ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80 345.Ed 346.Pp 347Note that this also displays the headers sent by the web server. 348They can be filtered, using a tool such as 349.Xr sed 1 , 350if necessary. 351.Pp 352More complicated examples can be built up when the user knows the format 353of requests required by the server. 354As another example, an email may be submitted to an SMTP server using: 355.Bd -literal -offset indent 356$ nc localhost 25 \*(Lt\*(Lt EOF 357HELO host.example.com 358MAIL FROM:\*(Ltuser@host.example.com\*(Gt 359RCPT TO:\*(Ltuser2@host.example.com\*(Gt 360DATA 361Body of email. 362\&. 363QUIT 364EOF 365.Ed 366.Sh PORT SCANNING 367It may be useful to know which ports are open and running services on 368a target machine. 369The 370.Fl z 371flag can be used to tell 372.Nm 373to report open ports, 374rather than initiate a connection. 375For example: 376.Bd -literal -offset indent 377$ nc -z host.example.com 20-30 378Connection to host.example.com 22 port [tcp/ssh] succeeded! 379Connection to host.example.com 25 port [tcp/smtp] succeeded! 380.Ed 381.Pp 382The port range was specified to limit the search to ports 20 \- 30. 383.Pp 384Alternatively, it might be useful to know which server software 385is running, and which versions. 386This information is often contained within the greeting banners. 387In order to retrieve these, it is necessary to first make a connection, 388and then break the connection when the banner has been retrieved. 389This can be accomplished by specifying a small timeout with the 390.Fl w 391flag, or perhaps by issuing a 392.Qq Dv QUIT 393command to the server: 394.Bd -literal -offset indent 395$ echo "QUIT" | nc host.example.com 20-30 396SSH-1.99-OpenSSH_3.6.1p2 397Protocol mismatch. 398220 host.example.com IMS SMTP Receiver Version 0.84 Ready 399.Ed 400.Sh EXAMPLES 401Open a TCP connection to port 42 of host.example.com, using port 31337 as 402the source port, with a timeout of 5 seconds: 403.Pp 404.Dl $ nc -p 31337 -w 5 host.example.com 42 405.Pp 406Open a UDP connection to port 53 of host.example.com: 407.Pp 408.Dl $ nc -u host.example.com 53 409.Pp 410Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the 411IP for the local end of the connection: 412.Pp 413.Dl $ nc -s 10.1.2.3 host.example.com 42 414.Pp 415Open a TCP connection to port 42 of host.example.com using IPsec ESP for 416incoming and outgoing traffic. 417.Pp 418.Dl $ nc -E host.example.com 42 419.Pp 420Open a TCP connection to port 42 of host.example.com using IPsec ESP for 421outgoing traffic only. 422.Pp 423.Dl $ nc -e 'out ipsec esp/transport//require' host.example.com 42 424.Pp 425Create and listen on a 426.Ux Ns -domain 427socket: 428.Pp 429.Dl $ nc -lU /var/tmp/dsocket 430.Pp 431Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4, 432port 8080. 433This example could also be used by 434.Xr ssh 1 ; 435see the 436.Cm ProxyCommand 437directive in 438.Xr ssh_config 5 439for more information. 440.Pp 441.Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42 442.Pp 443The same example again, this time enabling proxy authentication with username 444.Dq ruser 445if the proxy requires it: 446.Pp 447.Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42 448.Sh EXIT STATUS 449.Ex -std 450.Sh SEE ALSO 451.Xr cat 1 , 452.Xr setfib 1 , 453.Xr ssh 1 , 454.Xr tcp 4 455.Sh AUTHORS 456Original implementation by *Hobbit* 457.Aq hobbit@avian.org . 458.br 459Rewritten with IPv6 support by 460.An Eric Jackson Aq ericj@monkey.org . 461.Sh CAVEATS 462UDP port scans will always succeed 463(i.e. report the port as open), 464rendering the 465.Fl uz 466combination of flags relatively useless. 467