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