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