xref: /freebsd/contrib/netcat/nc.1 (revision de3deff65c5b407ab29b45780f2585b3bc24bbd6)
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