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