1 .\" $OpenBSD: nc.1,v 1.73 2016/06/28 17:35:14 jca Exp $
3 .\" Copyright (c) 1996 David Sacerdote
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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
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.
28 .Dd $Mdocdate: June 28 2016 $
33 .Nd arbitrary TCP and UDP connections and listens
36 .Op Fl 46cDdFhklNnrStUuvz
46 .Op Fl P Ar proxy_username
47 .Op Fl p Ar source_port
53 .Op Fl X Ar proxy_protocol
54 .Op Fl x Ar proxy_address Ns Op : Ns Ar port
62 utility is used for just about anything under the sun involving TCP,
66 It can open TCP connections, send UDP packets, listen on arbitrary
67 TCP and UDP ports, do port scanning, and deal with both IPv4 and
72 scripts nicely, and separates error messages onto standard error instead
73 of sending them to standard output, as
79 .Bl -bullet -offset indent -compact
83 shell-script based HTTP clients and servers
85 network daemon testing
87 a SOCKS or HTTP ProxyCommand for
93 The options are as follows:
98 to use IPv4 addresses only.
102 to use IPv6 addresses only.
104 Specifies the filename from which the public key part of the TLS
105 certificate is loaded, in PEM format.
106 May only be used with TLS.
108 If using a TCP socket to connect or listen, use TLS.
109 Illegal if not using TCP sockets.
111 Enable debugging on the socket.
113 Do not attempt to read from stdin.
115 Specify the name that must be present in the peer certificate when using TLS.
116 Illegal if not using TLS.
118 Pass the first connected socket using
121 This is useful in conjunction with
125 perform connection setup with a proxy but then leave the rest of the
126 connection to another program (e.g.\&
133 Specifies the required hash string of the peer certificate when using TLS.
134 The string format required is that used by
135 .Xr tls_peer_cert_hash 3 .
136 Illegal if not using TLS, and may not be used with -T noverify.
142 Specifies the size of the TCP receive buffer.
144 Specifies a delay time interval between lines of text sent and received.
145 Also causes a delay time between connections to multiple ports.
147 Specifies the filename from which the private key
148 is loaded in PEM format.
149 May only be used with TLS.
153 to stay listening for another connection after its current connection
155 It is an error to use this option without the
158 When used together with the
160 option, the server socket is not connected and it can receive UDP datagrams from
165 should listen for an incoming connection rather than initiate a
166 connection to a remote host.
167 It is an error to use this option in conjunction with the
173 Additionally, any timeouts specified with the
177 Set the TTL / hop limit of outgoing packets.
179 Ask the kernel to drop incoming packets whose TTL / hop limit is under
183 the network socket after EOF on the input.
184 Some servers require this to finish their work.
186 Do not do any DNS or service lookups on any specified addresses,
189 Specifies the size of the TCP send buffer.
190 .It Fl P Ar proxy_username
191 Specifies a username to present to a proxy server that requires authentication.
192 If no username is specified then authentication will not be attempted.
193 Proxy authentication is only supported for HTTP CONNECT proxies at present.
194 .It Fl p Ar source_port
195 Specifies the source port
197 should use, subject to privilege restrictions and availability.
198 It is an error to use this option in conjunction with the
202 Specifies the filename from which the root CA bundle for certificate
203 verification is loaded, in PEM format.
204 Illegal if not using TLS.
206 .Pa /etc/ssl/cert.pem .
208 Specifies that source and/or destination ports should be chosen randomly
209 instead of sequentially within a range or in the order that the system
212 Enables the RFC 2385 TCP MD5 signature option.
214 Specifies the IP of the interface which is used to send the packets.
217 datagram sockets, specifies the local temporary socket file
218 to create and use so that datagrams can be received.
219 It is an error to use this option in conjunction with the
223 Change IPv4 TOS value or TLS options.
228 which allows legacy TLS protocols;
230 which disables certificate verification;
232 which disables certificate name checking; or
234 which requires a client certificate on incoming connections.
235 It is illegal to specify TLS options if not using TLS.
246 or one of the DiffServ Code Points:
250 or a number in either hex or decimal.
254 to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
255 This makes it possible to use
257 to script telnet sessions.
263 Use UDP instead of the default option of TCP.
266 sockets, use a datagram socket instead of a stream socket.
269 socket is used, a temporary receiving socket is created in
275 Set the routing table to be used.
279 give more verbose output.
281 Connections which cannot be established or are idle timeout after
286 flag has no effect on the
290 will listen forever for a connection, with or without the
293 The default is no timeout.
294 .It Fl X Ar proxy_protocol
297 should use the specified protocol when talking to the proxy server.
298 Supported protocols are
306 If the protocol is not specified, SOCKS version 5 is used.
307 .It Fl x Ar proxy_address Ns Op : Ns Ar port
318 is not specified, the well-known port for the proxy protocol is used (1080
319 for SOCKS, 3128 for HTTPS).
323 should just scan for listening daemons, without sending any data to them.
324 It is an error to use this option in conjunction with the
330 can be a numerical IP address or a symbolic hostname
334 In general, a destination must be specified,
338 (in which case the local host is used).
341 sockets, a destination is required and is the socket path to connect to
347 can be a specified as a numeric port number, or as a service name.
348 Ports may be specified in a range of the form nn-mm.
350 a destination port must be specified,
354 .Sh CLIENT/SERVER MODEL
355 It is quite simple to build a very basic client/server model using
357 On one console, start
359 listening on a specific port for a connection.
365 is now listening on port 1234 for a connection.
367 .Pq or a second machine ,
368 connect to the machine and port being listened on:
370 .Dl $ nc 127.0.0.1 1234
372 There should now be a connection between the ports.
373 Anything typed at the second console will be concatenated to the first,
375 After the connection has been set up,
377 does not really care which side is being used as a
379 and which side is being used as a
381 The connection may be terminated using an
385 The example in the previous section can be expanded to build a
386 basic data transfer model.
387 Any information input into one end of the connection will be output
388 to the other end, and input and output can be easily captured in order to
389 emulate file transfer.
393 to listen on a specific port, with output captured into a file:
395 .Dl $ nc -l 1234 \*(Gt filename.out
397 Using a second machine, connect to the listening
399 process, feeding it the file which is to be transferred:
401 .Dl $ nc -N host.example.com 1234 \*(Lt filename.in
403 After the file has been transferred, the connection will close automatically.
404 .Sh TALKING TO SERVERS
405 It is sometimes useful to talk to servers
407 rather than through a user interface.
408 It can aid in troubleshooting,
409 when it might be necessary to verify what data a server is sending
410 in response to commands issued by the client.
411 For 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
416 Note that this also displays the headers sent by the web server.
417 They can be filtered, using a tool such as
421 More complicated examples can be built up when the user knows the format
422 of requests required by the server.
423 As another example, an email may be submitted to an SMTP server using:
424 .Bd -literal -offset indent
425 $ nc localhost 25 \*(Lt\*(Lt EOF
426 HELO host.example.com
427 MAIL FROM:\*(Ltuser@host.example.com\*(Gt
428 RCPT TO:\*(Ltuser2@host.example.com\*(Gt
436 It may be useful to know which ports are open and running services on
440 flag can be used to tell
442 to report open ports,
443 rather than initiate a connection.
445 .Bd -literal -offset indent
446 $ nc -z host.example.com 20-30
447 Connection to host.example.com 22 port [tcp/ssh] succeeded!
448 Connection to host.example.com 25 port [tcp/smtp] succeeded!
451 The port range was specified to limit the search to ports 20 \- 30.
453 Alternatively, it might be useful to know which server software
454 is running, and which versions.
455 This information is often contained within the greeting banners.
456 In order to retrieve these, it is necessary to first make a connection,
457 and then break the connection when the banner has been retrieved.
458 This can be accomplished by specifying a small timeout with the
460 flag, or perhaps by issuing a
462 command to the server:
463 .Bd -literal -offset indent
464 $ echo "QUIT" | nc host.example.com 20-30
465 SSH-1.99-OpenSSH_3.6.1p2
467 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
470 Open a TCP connection to port 42 of host.example.com, using port 31337 as
471 the source port, with a timeout of 5 seconds:
473 .Dl $ nc -p 31337 -w 5 host.example.com 42
475 Open a TCP connection to port 443 of www.google.ca, and negotiate TLS.
476 Check for a different name in the certificate for validation.
478 .Dl $ nc -v -c -e adsf.au.doubleclick.net www.google.ca 443
480 Open a UDP connection to port 53 of host.example.com:
482 .Dl $ nc -u host.example.com 53
484 Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
485 IP for the local end of the connection:
487 .Dl $ nc -s 10.1.2.3 host.example.com 42
489 Create and listen on a
493 .Dl $ nc -lU /var/tmp/dsocket
495 Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
497 This example could also be used by
503 for more information.
505 .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
507 The same example again, this time enabling proxy authentication with username
509 if the proxy requires it:
511 .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
516 Original implementation by *Hobbit*
517 .Aq Mt hobbit@avian.org .
519 Rewritten with IPv6 support by
520 .An Eric Jackson Aq Mt ericj@monkey.org .
522 UDP port scans using the
524 combination of flags will always report success irrespective of
525 the target machine's state.
527 in conjunction with a traffic sniffer either on the target machine
528 or an intermediary device,
531 combination could be useful for communications diagnostics.
532 Note that the amount of UDP traffic generated may be limited either
533 due to hardware resources and/or configuration settings.