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