1.\" $OpenBSD: nc.1,v 1.93 2018/12/27 17:45:36 jmc 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: December 27 2018 $ 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 source 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 do any DNS or service lookups on any specified addresses, 196hostnames or ports. 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 source 232Send packets from the interface with the 233.Ar source 234IP address. 235For 236.Ux Ns -domain 237datagram sockets, specifies the local temporary socket file 238to create and use so that datagrams can be received. 239Cannot be used together with 240.Fl l 241or 242.Fl x . 243.It Fl T Ar keyword 244Change the IPv4 TOS/IPv6 traffic class value or the TLS options. 245.Pp 246For TLS options, 247.Ar keyword 248may be one of: 249.Cm noverify , 250which disables certificate verification; 251.Cm noname , 252which disables certificate name checking; 253.Cm clientcert , 254which requires a client certificate on incoming connections; or 255.Cm muststaple , 256which requires the peer to provide a valid stapled OCSP response 257with the handshake. 258The following TLS options specify a value in the form of a 259.Ar key Ns = Ns Ar value 260pair: 261.Cm ciphers , 262which allows the supported TLS ciphers to be specified (see 263.Xr tls_config_set_ciphers 3 264for further details); 265.Cm protocols , 266which allows the supported TLS protocols to be specified (see 267.Xr tls_config_parse_protocols 3 268for further details). 269Specifying TLS options requires 270.Fl c . 271.Pp 272For the IPv4 TOS/IPv6 traffic class value, 273.Ar keyword 274may be one of 275.Cm critical , 276.Cm inetcontrol , 277.Cm lowdelay , 278.Cm netcontrol , 279.Cm throughput , 280.Cm reliability , 281or one of the DiffServ Code Points: 282.Cm ef , 283.Cm af11 No ... Cm af43 , 284.Cm cs0 No ... Cm cs7 ; 285or a number in either hex or decimal. 286.It Fl t 287Send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests. 288This makes it possible to use 289.Nm 290to script telnet sessions. 291.It Fl U 292Use 293.Ux Ns -domain 294sockets. 295Cannot be used together with any of the options 296.Fl cFx . 297.It Fl u 298Use UDP instead of TCP. 299Cannot be used together with 300.Fl c 301or 302.Fl x . 303For 304.Ux Ns -domain 305sockets, use a datagram socket instead of a stream socket. 306If a 307.Ux Ns -domain 308socket is used, a temporary receiving socket is created in 309.Pa /tmp 310unless the 311.Fl s 312flag is given. 313.It Fl V Ar rtable 314Set the routing table to be used. 315.It Fl v 316Produce more verbose output. 317.It Fl W Ar recvlimit 318Terminate after receiving 319.Ar recvlimit 320packets from the network. 321.It Fl w Ar timeout 322Connections which cannot be established or are idle timeout after 323.Ar timeout 324seconds. 325The 326.Fl w 327flag has no effect on the 328.Fl l 329option, i.e.\& 330.Nm 331will listen forever for a connection, with or without the 332.Fl w 333flag. 334The default is no timeout. 335.It Fl X Ar proxy_protocol 336Use 337.Ar proxy_protocol 338when talking to the proxy server. 339Supported protocols are 340.Cm 4 341(SOCKS v.4), 342.Cm 5 343(SOCKS v.5) 344and 345.Cm connect 346(HTTPS proxy). 347If the protocol is not specified, SOCKS version 5 is used. 348.It Fl x Ar proxy_address Ns Op : Ns Ar port 349Connect to 350.Ar destination 351using a proxy at 352.Ar proxy_address 353and 354.Ar port . 355If 356.Ar port 357is not specified, the well-known port for the proxy protocol is used (1080 358for SOCKS, 3128 for HTTPS). 359An IPv6 address can be specified unambiguously by enclosing 360.Ar proxy_address 361in square brackets. 362A proxy cannot be used with any of the options 363.Fl lsuU . 364.It Fl Z Ar peercertfile 365Save the peer certificates to 366.Ar peercertfile , 367in PEM format. 368Requires 369.Fl c . 370.It Fl z 371Only scan for listening daemons, without sending any data to them. 372Cannot be used together with 373.Fl l . 374.El 375.Pp 376.Ar destination 377can be a numerical IP address or a symbolic hostname 378(unless the 379.Fl n 380option is given). 381In general, a destination must be specified, 382unless the 383.Fl l 384option is given 385(in which case the local host is used). 386For 387.Ux Ns -domain 388sockets, a destination is required and is the socket path to connect to 389(or listen on if the 390.Fl l 391option is given). 392.Pp 393.Ar port 394can be specified as a numeric port number or as a service name. 395Port ranges may be specified as numeric port numbers of the form 396.Ar nn Ns - Ns Ar mm . 397In general, 398a destination port must be specified, 399unless the 400.Fl U 401option is given. 402.Sh CLIENT/SERVER MODEL 403It is quite simple to build a very basic client/server model using 404.Nm . 405On one console, start 406.Nm 407listening on a specific port for a connection. 408For example: 409.Pp 410.Dl $ nc -l 1234 411.Pp 412.Nm 413is now listening on port 1234 for a connection. 414On a second console 415.Pq or a second machine , 416connect to the machine and port being listened on: 417.Pp 418.Dl $ nc 127.0.0.1 1234 419.Pp 420There should now be a connection between the ports. 421Anything typed at the second console will be concatenated to the first, 422and vice-versa. 423After the connection has been set up, 424.Nm 425does not really care which side is being used as a 426.Sq server 427and which side is being used as a 428.Sq client . 429The connection may be terminated using an 430.Dv EOF 431.Pq Sq ^D . 432.Sh DATA TRANSFER 433The example in the previous section can be expanded to build a 434basic data transfer model. 435Any information input into one end of the connection will be output 436to the other end, and input and output can be easily captured in order to 437emulate file transfer. 438.Pp 439Start by using 440.Nm 441to listen on a specific port, with output captured into a file: 442.Pp 443.Dl $ nc -l 1234 \*(Gt filename.out 444.Pp 445Using a second machine, connect to the listening 446.Nm 447process, feeding it the file which is to be transferred: 448.Pp 449.Dl $ nc -N host.example.com 1234 \*(Lt filename.in 450.Pp 451After the file has been transferred, the connection will close automatically. 452.Sh TALKING TO SERVERS 453It is sometimes useful to talk to servers 454.Dq by hand 455rather than through a user interface. 456It can aid in troubleshooting, 457when it might be necessary to verify what data a server is sending 458in response to commands issued by the client. 459For example, to retrieve the home page of a web site: 460.Bd -literal -offset indent 461$ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80 462.Ed 463.Pp 464Note that this also displays the headers sent by the web server. 465They can be filtered, using a tool such as 466.Xr sed 1 , 467if necessary. 468.Pp 469More complicated examples can be built up when the user knows the format 470of requests required by the server. 471As another example, an email may be submitted to an SMTP server using: 472.Bd -literal -offset indent 473$ nc localhost 25 \*(Lt\*(Lt EOF 474HELO host.example.com 475MAIL FROM:\*(Ltuser@host.example.com\*(Gt 476RCPT TO:\*(Ltuser2@host.example.com\*(Gt 477DATA 478Body of email. 479\&. 480QUIT 481EOF 482.Ed 483.Sh PORT SCANNING 484It may be useful to know which ports are open and running services on 485a target machine. 486The 487.Fl z 488flag can be used to tell 489.Nm 490to report open ports, 491rather than initiate a connection. 492For example: 493.Bd -literal -offset indent 494$ nc -z host.example.com 20-30 495Connection to host.example.com 22 port [tcp/ssh] succeeded! 496Connection to host.example.com 25 port [tcp/smtp] succeeded! 497.Ed 498.Pp 499The port range was specified to limit the search to ports 20 \- 30. 500.Pp 501Alternatively, it might be useful to know which server software 502is running, and which versions. 503This information is often contained within the greeting banners. 504In order to retrieve these, it is necessary to first make a connection, 505and then break the connection when the banner has been retrieved. 506This can be accomplished by specifying a small timeout with the 507.Fl w 508flag, or perhaps by issuing a 509.Qq Dv QUIT 510command to the server: 511.Bd -literal -offset indent 512$ echo "QUIT" | nc host.example.com 20-30 513SSH-1.99-OpenSSH_3.6.1p2 514Protocol mismatch. 515220 host.example.com IMS SMTP Receiver Version 0.84 Ready 516.Ed 517.Sh EXAMPLES 518Open a TCP connection to port 42 of host.example.com, using port 31337 as 519the source port, with a timeout of 5 seconds: 520.Pp 521.Dl $ nc -p 31337 -w 5 host.example.com 42 522.Pp 523Open a TCP connection to port 443 of www.example.com, and negotiate TLS with 524any supported TLS protocol version and "compat" ciphers: 525.Pp 526.Dl $ nc -cv -T protocols=all -T ciphers=compat www.example.com 443 527.Pp 528Open a TCP connection to port 443 of www.google.ca, and negotiate TLS. 529Check for a different name in the certificate for validation: 530.Pp 531.Dl $ nc -cv -e adsf.au.doubleclick.net www.google.ca 443 532.Pp 533Open a UDP connection to port 53 of host.example.com: 534.Pp 535.Dl $ nc -u host.example.com 53 536.Pp 537Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the 538IP for the local end of the connection: 539.Pp 540.Dl $ nc -s 10.1.2.3 host.example.com 42 541.Pp 542Create and listen on a 543.Ux Ns -domain 544stream socket: 545.Pp 546.Dl $ nc -lU /var/tmp/dsocket 547.Pp 548Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4, 549port 8080. 550This example could also be used by 551.Xr ssh 1 ; 552see the 553.Cm ProxyCommand 554directive in 555.Xr ssh_config 5 556for more information. 557.Pp 558.Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42 559.Pp 560The same example again, this time enabling proxy authentication with username 561.Dq ruser 562if the proxy requires it: 563.Pp 564.Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42 565.Sh SEE ALSO 566.Xr cat 1 , 567.Xr ssh 1 568.Sh AUTHORS 569Original implementation by 570.An *Hobbit* Aq Mt hobbit@avian.org . 571.br 572Rewritten with IPv6 support by 573.An Eric Jackson Aq Mt ericj@monkey.org . 574.Sh CAVEATS 575UDP port scans using the 576.Fl uz 577combination of flags will always report success irrespective of 578the target machine's state. 579However, 580in conjunction with a traffic sniffer either on the target machine 581or an intermediary device, 582the 583.Fl uz 584combination could be useful for communications diagnostics. 585Note that the amount of UDP traffic generated may be limited either 586due to hardware resources and/or configuration settings. 587