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