1.\" $OpenBSD: nc.1,v 1.53 2010/02/23 23:00:52 schwarze 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 February 23, 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 46DdEhklnorStUuvz 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 fib 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. 161When 162.It Fl o 163.Dq Once-only mode . 164By default, 165.Nm 166does not terminate on EOF condition on input, 167but continues until the network side has been closed down. 168Specifying 169.Fl o 170will make it terminate on EOF as well. 171.It Fl P Ar proxy_username 172Specifies a username to present to a proxy server that requires authentication. 173If no username is specified then authentication will not be attempted. 174Proxy authentication is only supported for HTTP CONNECT proxies at present. 175.It Fl p Ar source_port 176Specifies the source port 177.Nm 178should use, subject to privilege restrictions and availability. 179It is an error to use this option in conjunction with the 180.Fl l 181option. 182.It Fl r 183Specifies that source and/or destination ports should be chosen randomly 184instead of sequentially within a range or in the order that the system 185assigns them. 186.It Fl S 187Enables the RFC 2385 TCP MD5 signature option. 188.It Fl s Ar source_ip_address 189Specifies the IP of the interface which is used to send the packets. 190It is an error to use this option in conjunction with the 191.Fl l 192option. 193.It Fl T Ar ToS 194Specifies IP Type of Service (ToS) for the connection. 195Valid values are the tokens 196.Dq lowdelay , 197.Dq throughput , 198.Dq reliability , 199or an 8-bit hexadecimal value preceded by 200.Dq 0x . 201.It Fl t 202Causes 203.Nm 204to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests. 205This makes it possible to use 206.Nm 207to script telnet sessions. 208.It Fl U 209Specifies to use 210.Ux Ns -domain 211sockets. 212.It Fl u 213Use UDP instead of the default option of TCP. 214.It Fl V Ar fib 215Set the routing table (FIB). 216The default is 0. 217.It Fl v 218Have 219.Nm 220give more verbose output. 221.It Fl w Ar timeout 222If a connection and stdin are idle for more than 223.Ar timeout 224seconds, then the connection is silently closed. 225The 226.Fl w 227flag has no effect on the 228.Fl l 229option, i.e.\& 230.Nm 231will listen forever for a connection, with or without the 232.Fl w 233flag. 234The default is no timeout. 235.It Fl X Ar proxy_protocol 236Requests that 237.Nm 238should use the specified protocol when talking to the proxy server. 239Supported protocols are 240.Dq 4 241(SOCKS v.4), 242.Dq 5 243(SOCKS v.5) 244and 245.Dq connect 246(HTTPS proxy). 247If the protocol is not specified, SOCKS version 5 is used. 248.It Xo 249.Fl x Ar proxy_address Ns Oo : Ns 250.Ar port Oc 251.Xc 252Requests that 253.Nm 254should connect to 255.Ar hostname 256using a proxy at 257.Ar proxy_address 258and 259.Ar port . 260If 261.Ar port 262is not specified, the well-known port for the proxy protocol is used (1080 263for SOCKS, 3128 for HTTPS). 264.It Fl z 265Specifies that 266.Nm 267should just scan for listening daemons, without sending any data to them. 268It is an error to use this option in conjunction with the 269.Fl l 270option. 271.El 272.Pp 273.Ar hostname 274can be a numerical IP address or a symbolic hostname 275(unless the 276.Fl n 277option is given). 278In general, a hostname must be specified, 279unless the 280.Fl l 281option is given 282(in which case the local host is used). 283.Pp 284.Ar port 285can be a single integer or a range of ports. 286Ranges are in the form nn-mm. 287In general, 288a destination port must be specified, 289unless the 290.Fl U 291option is given 292(in which case a socket must be specified). 293.Sh CLIENT/SERVER MODEL 294It is quite simple to build a very basic client/server model using 295.Nm . 296On one console, start 297.Nm 298listening on a specific port for a connection. 299For example: 300.Pp 301.Dl $ nc -l 1234 302.Pp 303.Nm 304is now listening on port 1234 for a connection. 305On a second console 306.Pq or a second machine , 307connect to the machine and port being listened on: 308.Pp 309.Dl $ nc 127.0.0.1 1234 310.Pp 311There should now be a connection between the ports. 312Anything typed at the second console will be concatenated to the first, 313and vice-versa. 314After the connection has been set up, 315.Nm 316does not really care which side is being used as a 317.Sq server 318and which side is being used as a 319.Sq client . 320The connection may be terminated using an 321.Dv EOF 322.Pq Sq ^D . 323.Sh DATA TRANSFER 324The example in the previous section can be expanded to build a 325basic data transfer model. 326Any information input into one end of the connection will be output 327to the other end, and input and output can be easily captured in order to 328emulate file transfer. 329.Pp 330Start by using 331.Nm 332to listen on a specific port, with output captured into a file: 333.Pp 334.Dl $ nc -l 1234 \*(Gt filename.out 335.Pp 336Using a second machine, connect to the listening 337.Nm 338process, feeding it the file which is to be transferred: 339.Pp 340.Dl $ nc host.example.com 1234 \*(Lt filename.in 341.Pp 342After the file has been transferred, the connection will close automatically. 343.Sh TALKING TO SERVERS 344It is sometimes useful to talk to servers 345.Dq by hand 346rather than through a user interface. 347It can aid in troubleshooting, 348when it might be necessary to verify what data a server is sending 349in response to commands issued by the client. 350For example, to retrieve the home page of a web site: 351.Bd -literal -offset indent 352$ echo -n "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80 353.Ed 354.Pp 355Note that this also displays the headers sent by the web server. 356They can be filtered, using a tool such as 357.Xr sed 1 , 358if necessary. 359.Pp 360More complicated examples can be built up when the user knows the format 361of requests required by the server. 362As another example, an email may be submitted to an SMTP server using: 363.Bd -literal -offset indent 364$ nc localhost 25 \*(Lt\*(Lt EOF 365HELO host.example.com 366MAIL FROM:\*(Ltuser@host.example.com\*(Gt 367RCPT TO:\*(Ltuser2@host.example.com\*(Gt 368DATA 369Body of email. 370\&. 371QUIT 372EOF 373.Ed 374.Sh PORT SCANNING 375It may be useful to know which ports are open and running services on 376a target machine. 377The 378.Fl z 379flag can be used to tell 380.Nm 381to report open ports, 382rather than initiate a connection. 383For example: 384.Bd -literal -offset indent 385$ nc -z host.example.com 20-30 386Connection to host.example.com 22 port [tcp/ssh] succeeded! 387Connection to host.example.com 25 port [tcp/smtp] succeeded! 388.Ed 389.Pp 390The port range was specified to limit the search to ports 20 \- 30. 391.Pp 392Alternatively, it might be useful to know which server software 393is running, and which versions. 394This information is often contained within the greeting banners. 395In order to retrieve these, it is necessary to first make a connection, 396and then break the connection when the banner has been retrieved. 397This can be accomplished by specifying a small timeout with the 398.Fl w 399flag, or perhaps by issuing a 400.Qq Dv QUIT 401command to the server: 402.Bd -literal -offset indent 403$ echo "QUIT" | nc host.example.com 20-30 404SSH-1.99-OpenSSH_3.6.1p2 405Protocol mismatch. 406220 host.example.com IMS SMTP Receiver Version 0.84 Ready 407.Ed 408.Sh EXAMPLES 409Open a TCP connection to port 42 of host.example.com, using port 31337 as 410the source port, with a timeout of 5 seconds: 411.Pp 412.Dl $ nc -p 31337 -w 5 host.example.com 42 413.Pp 414Open a UDP connection to port 53 of host.example.com: 415.Pp 416.Dl $ nc -u host.example.com 53 417.Pp 418Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the 419IP for the local end of the connection: 420.Pp 421.Dl $ nc -s 10.1.2.3 host.example.com 42 422.Pp 423Open a TCP connection to port 42 of host.example.com using IPsec ESP for 424incoming and outgoing traffic. 425.Pp 426.Dl $ nc -E host.example.com 42 427.Pp 428Open a TCP connection to port 42 of host.example.com using IPsec ESP for 429outgoing traffic only. 430.Pp 431.Dl $ nc -e 'out ipsec esp/transport//require' host.example.com 42 432.Pp 433Create and listen on a 434.Ux Ns -domain 435socket: 436.Pp 437.Dl $ nc -lU /var/tmp/dsocket 438.Pp 439Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4, 440port 8080. 441This example could also be used by 442.Xr ssh 1 ; 443see the 444.Cm ProxyCommand 445directive in 446.Xr ssh_config 5 447for more information. 448.Pp 449.Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42 450.Pp 451The same example again, this time enabling proxy authentication with username 452.Dq ruser 453if the proxy requires it: 454.Pp 455.Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42 456.Sh EXIT STATUS 457.Ex -std 458.Sh SEE ALSO 459.Xr cat 1 , 460.Xr setfib 1 , 461.Xr ssh 1 , 462.Xr tcp 4 463.Sh AUTHORS 464Original implementation by *Hobbit* 465.Aq hobbit@avian.org . 466.br 467Rewritten with IPv6 support by 468.An Eric Jackson Aq ericj@monkey.org . 469.Sh CAVEATS 470UDP port scans will always succeed 471(i.e. report the port as open), 472rendering the 473.Fl uz 474combination of flags relatively useless. 475