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