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