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