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