123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582 |
- .\" $OpenBSD: nc.1,v 1.95 2020/02/12 14:46:36 schwarze Exp $
- .\"
- .\" Copyright (c) 1996 David Sacerdote
- .\" All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. The name of the author may not be used to endorse or promote products
- .\" derived from this software without specific prior written permission
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- .\"
- .Dd $Mdocdate: February 12 2020 $
- .Dt NC 1
- .Os
- .Sh NAME
- .Nm nc
- .Nd arbitrary TCP and UDP connections and listens
- .Sh SYNOPSIS
- .Nm nc
- .Op Fl 46bCDdFhklNnrStUuvZz
- .Op Fl I Ar length
- .Op Fl i Ar interval
- .Op Fl M Ar ttl
- .Op Fl m Ar minttl
- .Op Fl O Ar length
- .Op Fl P Ar proxy_username
- .Op Fl p Ar source_port
- .Op Fl q Ar seconds
- .Op Fl s Ar sourceaddr
- .Op Fl T Ar keyword
- .Op Fl V Ar rtable
- .Op Fl W Ar recvlimit
- .Op Fl w Ar timeout
- .Op Fl X Ar proxy_protocol
- .Op Fl x Ar proxy_address Ns Op : Ns Ar port
- .Op Ar destination
- .Op Ar port
- .Sh DESCRIPTION
- The
- .Nm
- (or
- .Nm netcat )
- utility is used for just about anything under the sun involving TCP,
- UDP, or
- .Ux Ns -domain
- sockets.
- It can open TCP connections, send UDP packets, listen on arbitrary
- TCP and UDP ports, do port scanning, and deal with both IPv4 and
- IPv6.
- Unlike
- .Xr telnet 1 ,
- .Nm
- scripts nicely, and separates error messages onto standard error instead
- of sending them to standard output, as
- .Xr telnet 1
- does with some.
- .Pp
- Common uses include:
- .Pp
- .Bl -bullet -offset indent -compact
- .It
- simple TCP proxies
- .It
- shell-script based HTTP clients and servers
- .It
- network daemon testing
- .It
- a SOCKS or HTTP ProxyCommand for
- .Xr ssh 1
- .It
- and much, much more
- .El
- .Pp
- The options are as follows:
- .Bl -tag -width Ds
- .It Fl 4
- Use IPv4 addresses only.
- .It Fl 6
- Use IPv6 addresses only.
- .It Fl b
- Allow broadcast.
- .It Fl C
- Send CRLF as line-ending. Each line feed (LF) character from the input
- data is translated into CR+LF before being written to the socket. Line
- feed characters that are already preceded with a carriage return (CR)
- are not translated. Received data is not affected.
- .It Fl D
- Enable debugging on the socket.
- .It Fl d
- Do not attempt to read from stdin.
- .It Fl F
- Pass the first connected socket using
- .Xr sendmsg 2
- to stdout and exit.
- This is useful in conjunction with
- .Fl X
- to have
- .Nm
- perform connection setup with a proxy but then leave the rest of the
- connection to another program (e.g.\&
- .Xr ssh 1
- using the
- .Xr ssh_config 5
- .Cm ProxyUseFdpass
- option).
- Cannot be used with
- .Fl U .
- .It Fl h
- Print out the
- .Nm
- help text and exit.
- .It Fl I Ar length
- Specify the size of the TCP receive buffer.
- .It Fl i Ar interval
- Sleep for
- .Ar interval
- seconds between lines of text sent and received.
- Also causes a delay time between connections to multiple ports.
- .It Fl k
- When a connection is completed, listen for another one.
- Requires
- .Fl l .
- When used together with the
- .Fl u
- option, the server socket is not connected and it can receive UDP datagrams from
- multiple hosts.
- .It Fl l
- Listen for an incoming connection rather than initiating a
- connection to a remote host.
- The
- .Ar destination
- and
- .Ar port
- to listen on can be specified either as non-optional arguments, or with
- options
- .Fl s
- and
- .Fl p
- respectively.
- Cannot be used together with
- .Fl x
- or
- .Fl z .
- Additionally, any timeouts specified with the
- .Fl w
- option are ignored.
- .It Fl M Ar ttl
- Set the TTL / hop limit of outgoing packets.
- .It Fl m Ar minttl
- Ask the kernel to drop incoming packets whose TTL / hop limit is under
- .Ar minttl .
- .It Fl N
- .Xr shutdown 2
- the network socket after EOF on the input.
- Some servers require this to finish their work.
- .It Fl n
- Do not perform domain name resolution.
- If a name cannot be resolved without DNS, an error will be reported.
- .It Fl O Ar length
- Specify the size of the TCP send buffer.
- .It Fl P Ar proxy_username
- Specifies a username to present to a proxy server that requires authentication.
- If no username is specified then authentication will not be attempted.
- Proxy authentication is only supported for HTTP CONNECT proxies at present.
- .It Fl p Ar source_port
- Specify the source port
- .Nm
- should use, subject to privilege restrictions and availability.
- .It Fl q Ar seconds
- after EOF on stdin, wait the specified number of
- .Ar seconds
- and then quit. If
- .Ar seconds
- is negative, wait forever (default). Specifying a non-negative
- .Ar seconds
- implies
- .Fl N .
- .It Fl r
- Choose source and/or destination ports randomly
- instead of sequentially within a range or in the order that the system
- assigns them.
- .It Fl S
- Enable the RFC 2385 TCP MD5 signature option.
- .It Fl s Ar sourceaddr
- Set the source address to send packets from,
- which is useful on machines with multiple interfaces.
- For
- .Ux Ns -domain
- datagram sockets, specifies the local temporary socket file
- to create and use so that datagrams can be received.
- Cannot be used together with
- .Fl x .
- .It Fl T Ar keyword
- Change the IPv4 TOS/IPv6 traffic class value.
- .Ar keyword
- may be one of
- .Cm critical ,
- .Cm inetcontrol ,
- .Cm lowcost ,
- .Cm lowdelay ,
- .Cm netcontrol ,
- .Cm throughput ,
- .Cm reliability ,
- or one of the DiffServ Code Points:
- .Cm ef ,
- .Cm af11 No ... Cm af43 ,
- .Cm cs0 No ... Cm cs7 ;
- or a number in either hex or decimal.
- .It Fl t
- Send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
- This makes it possible to use
- .Nm
- to script telnet sessions.
- .It Fl U
- Use
- .Ux Ns -domain
- sockets.
- Cannot be used together with
- .Fl F
- or
- .Fl x .
- .It Fl u
- Use UDP instead of TCP.
- Cannot be used together with
- .Fl x .
- For
- .Ux Ns -domain
- sockets, use a datagram socket instead of a stream socket.
- If a
- .Ux Ns -domain
- socket is used, a temporary receiving socket is created in
- .Pa /tmp
- unless the
- .Fl s
- flag is given.
- .It Fl V Ar rtable
- Set the routing table to be used.
- .It Fl v
- Produce more verbose output.
- .It Fl W Ar recvlimit
- Terminate after receiving
- .Ar recvlimit
- packets from the network.
- .It Fl w Ar timeout
- Connections which cannot be established or are idle timeout after
- .Ar timeout
- seconds.
- The
- .Fl w
- flag has no effect on the
- .Fl l
- option, i.e.\&
- .Nm
- will listen forever for a connection, with or without the
- .Fl w
- flag.
- The default is no timeout.
- .It Fl X Ar proxy_protocol
- Use
- .Ar proxy_protocol
- when talking to the proxy server.
- Supported protocols are
- .Cm 4
- (SOCKS v.4),
- .Cm 5
- (SOCKS v.5)
- and
- .Cm connect
- (HTTPS proxy).
- If the protocol is not specified, SOCKS version 5 is used.
- .It Fl x Ar proxy_address Ns Op : Ns Ar port
- Connect to
- .Ar destination
- using a proxy at
- .Ar proxy_address
- and
- .Ar port .
- If
- .Ar port
- is not specified, the well-known port for the proxy protocol is used (1080
- for SOCKS, 3128 for HTTPS).
- An IPv6 address can be specified unambiguously by enclosing
- .Ar proxy_address
- in square brackets.
- A proxy cannot be used with any of the options
- .Fl lsuU .
- .It Fl Z
- DCCP mode.
- .It Fl z
- Only scan for listening daemons, without sending any data to them.
- Cannot be used together with
- .Fl l .
- .El
- .Pp
- .Ar destination
- can be a numerical IP address or a symbolic hostname
- (unless the
- .Fl n
- option is given).
- In general, a destination must be specified,
- unless the
- .Fl l
- option is given
- (in which case the local host is used).
- For
- .Ux Ns -domain
- sockets, a destination is required and is the socket path to connect to
- (or listen on if the
- .Fl l
- option is given).
- .Pp
- .Ar port
- can be specified as a numeric port number or as a service name.
- Port ranges may be specified as numeric port numbers of the form
- .Ar nn Ns - Ns Ar mm .
- In general,
- a destination port must be specified,
- unless the
- .Fl U
- option is given.
- .Sh CLIENT/SERVER MODEL
- It is quite simple to build a very basic client/server model using
- .Nm .
- On one console, start
- .Nm
- listening on a specific port for a connection.
- For example:
- .Pp
- .Dl $ nc -l 1234
- .Pp
- .Nm
- is now listening on port 1234 for a connection.
- On a second console
- .Pq or a second machine ,
- connect to the machine and port being listened on:
- .Pp
- .Dl $ nc 127.0.0.1 1234
- .Pp
- There should now be a connection between the ports.
- Anything typed at the second console will be concatenated to the first,
- and vice-versa.
- After the connection has been set up,
- .Nm
- does not really care which side is being used as a
- .Sq server
- and which side is being used as a
- .Sq client .
- The connection may be terminated using an
- .Dv EOF
- .Pq Sq ^D .
- .Pp
- There is no
- .Fl c
- or
- .Fl e
- option in this netcat, but you still can execute a command after connection
- being established by redirecting file descriptors. Be cautious here because
- opening a port and let anyone connected execute arbitrary command on your
- site is DANGEROUS. If you really need to do this, here is an example:
- .Pp
- On
- .Sq server
- side:
- .Pp
- .Dl $ rm -f /tmp/f; mkfifo /tmp/f
- .Dl $ cat /tmp/f | /bin/sh -i 2>&1 | nc -l 127.0.0.1 1234 > /tmp/f
- .Pp
- On
- .Sq client
- side:
- .Pp
- .Dl $ nc host.example.com 1234
- .Dl $ (shell prompt from host.example.com)
- .Pp
- By doing this, you create a fifo at /tmp/f and make nc listen at port 1234
- of address 127.0.0.1 on
- .Sq server
- side, when a
- .Sq client
- establishes a connection successfully to that port, /bin/sh gets executed
- on
- .Sq server
- side and the shell prompt is given to
- .Sq client
- side.
- .Pp
- When connection is terminated,
- .Nm
- quits as well. Use
- .Fl k
- if you want it keep listening, but if the command quits this option won't
- restart it or keep
- .Nm
- running. Also don't forget to remove the file descriptor once you don't need
- it anymore:
- .Pp
- .Dl $ rm -f /tmp/f
- .Pp
- .Sh DATA TRANSFER
- The example in the previous section can be expanded to build a
- basic data transfer model.
- Any information input into one end of the connection will be output
- to the other end, and input and output can be easily captured in order to
- emulate file transfer.
- .Pp
- Start by using
- .Nm
- to listen on a specific port, with output captured into a file:
- .Pp
- .Dl $ nc -l 1234 \*(Gt filename.out
- .Pp
- Using a second machine, connect to the listening
- .Nm
- process, feeding it the file which is to be transferred:
- .Pp
- .Dl $ nc -N host.example.com 1234 \*(Lt filename.in
- .Pp
- After the file has been transferred, the connection will close automatically.
- .Sh TALKING TO SERVERS
- It is sometimes useful to talk to servers
- .Dq by hand
- rather than through a user interface.
- It can aid in troubleshooting,
- when it might be necessary to verify what data a server is sending
- in response to commands issued by the client.
- For example, to retrieve the home page of a web site:
- .Bd -literal -offset indent
- $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
- .Ed
- .Pp
- Note that this also displays the headers sent by the web server.
- They can be filtered, using a tool such as
- .Xr sed 1 ,
- if necessary.
- .Pp
- More complicated examples can be built up when the user knows the format
- of requests required by the server.
- As another example, an email may be submitted to an SMTP server using:
- .Bd -literal -offset indent
- $ nc [\-C] localhost 25 \*(Lt\*(Lt EOF
- HELO host.example.com
- MAIL FROM:\*(Ltuser@host.example.com\*(Gt
- RCPT TO:\*(Ltuser2@host.example.com\*(Gt
- DATA
- Body of email.
- \&.
- QUIT
- EOF
- .Ed
- .Sh PORT SCANNING
- It may be useful to know which ports are open and running services on
- a target machine.
- The
- .Fl z
- flag can be used to tell
- .Nm
- to report open ports,
- rather than initiate a connection. Usually it's useful to turn on verbose
- output to stderr by use this option in conjunction with
- .Fl v
- option.
- .Pp
- For example:
- .Bd -literal -offset indent
- $ nc \-zv host.example.com 20-30
- Connection to host.example.com 22 port [tcp/ssh] succeeded!
- Connection to host.example.com 25 port [tcp/smtp] succeeded!
- .Ed
- .Pp
- The port range was specified to limit the search to ports 20 \- 30, and is
- scanned by increasing order (unless the
- .Fl r
- flag is set).
- .Pp
- You can also specify a list of ports to scan, for example:
- .Bd -literal -offset indent
- $ nc \-zv host.example.com http 20 22-23
- nc: connect to host.example.com 80 (tcp) failed: Connection refused
- nc: connect to host.example.com 20 (tcp) failed: Connection refused
- Connection to host.example.com port [tcp/ssh] succeeded!
- nc: connect to host.example.com 23 (tcp) failed: Connection refused
- .Ed
- .Pp
- The ports are scanned by the order you given (unless the
- .Fl r
- flag is set).
- .Pp
- Alternatively, it might be useful to know which server software
- is running, and which versions.
- This information is often contained within the greeting banners.
- In order to retrieve these, it is necessary to first make a connection,
- and then break the connection when the banner has been retrieved.
- This can be accomplished by specifying a small timeout with the
- .Fl w
- flag, or perhaps by issuing a
- .Qq Dv QUIT
- command to the server:
- .Bd -literal -offset indent
- $ echo "QUIT" | nc host.example.com 20-30
- SSH-1.99-OpenSSH_3.6.1p2
- Protocol mismatch.
- 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
- .Ed
- .Sh EXAMPLES
- Open a TCP connection to port 42 of host.example.com, using port 31337 as
- the source port, with a timeout of 5 seconds:
- .Pp
- .Dl $ nc -p 31337 -w 5 host.example.com 42
- .Pp
- Open a UDP connection to port 53 of host.example.com:
- .Pp
- .Dl $ nc -u host.example.com 53
- .Pp
- Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
- IP for the local end of the connection:
- .Pp
- .Dl $ nc -s 10.1.2.3 host.example.com 42
- .Pp
- Create and listen on a
- .Ux Ns -domain
- stream socket:
- .Pp
- .Dl $ nc -lU /var/tmp/dsocket
- .Pp
- Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
- port 8080.
- This example could also be used by
- .Xr ssh 1 ;
- see the
- .Cm ProxyCommand
- directive in
- .Xr ssh_config 5
- for more information.
- .Pp
- .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
- .Pp
- The same example again, this time enabling proxy authentication with username
- .Dq ruser
- if the proxy requires it:
- .Pp
- .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
- .Sh SEE ALSO
- .Xr cat 1 ,
- .Xr ssh 1
- .Sh AUTHORS
- Original implementation by
- .An *Hobbit* Aq Mt hobbit@avian.org .
- .br
- Rewritten with IPv6 support by
- .An Eric Jackson Aq Mt ericj@monkey.org .
- .br
- Modified for Debian port by Aron Xu
- .Aq aron@debian.org .
- .Sh CAVEATS
- UDP port scans using the
- .Fl uz
- combination of flags will always report success irrespective of
- the target machine's state.
- However,
- in conjunction with a traffic sniffer either on the target machine
- or an intermediary device,
- the
- .Fl uz
- combination could be useful for communications diagnostics.
- Note that the amount of UDP traffic generated may be limited either
- due to hardware resources and/or configuration settings.
|