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