aboutsummaryrefslogtreecommitdiff
path: root/usr.bin/nc/nc.1
diff options
context:
space:
mode:
Diffstat (limited to 'usr.bin/nc/nc.1')
-rw-r--r--usr.bin/nc/nc.1585
1 files changed, 585 insertions, 0 deletions
diff --git a/usr.bin/nc/nc.1 b/usr.bin/nc/nc.1
new file mode 100644
index 0000000..fff5857
--- /dev/null
+++ b/usr.bin/nc/nc.1
@@ -0,0 +1,585 @@
+.\" $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 46cDdFhklNnrStUuvz
+.Op Fl C Ar certfile
+.Op Fl e Ar name
+.Op Fl H Ar hash
+.Op Fl I Ar length
+.Op Fl i Ar interval
+.Op Fl K Ar keyfile
+.Op Fl M Ar ttl
+.Op Fl m Ar minttl
+.Op Fl O Ar length
+.Op Fl o Ar staplefile
+.Op Fl P Ar proxy_username
+.Op Fl p Ar source_port
+.Op Fl R Ar CAfile
+.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 Fl Z Ar peercertfile
+.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 C Ar certfile
+Load the public key part of the TLS peer certificate from
+.Ar certfile ,
+in PEM format.
+Requires
+.Fl c .
+.It Fl c
+Use TLS to connect or listen.
+Cannot be used together with any of the options
+.Fl FuU .
+.It Fl D
+Enable debugging on the socket.
+.It Fl d
+Do not attempt to read from stdin.
+.It Fl e Ar name
+Only accept the TLS peer certificate if it contains the
+.Ar name .
+Requires
+.Fl c .
+If not specified,
+.Ar destination
+is used.
+.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 c
+or
+.Fl U .
+.It Fl H Ar hash
+Only accept the TLS peer certificate if its hash returned from
+.Xr tls_peer_cert_hash 3
+matches
+.Ar hash .
+Requires
+.Fl c
+and cannot be used with
+.Fl T Cm noverify .
+.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 Ar keyfile
+Load the TLS private key from
+.Ar keyfile ,
+in PEM format.
+Requires
+.Fl c .
+.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.
+Cannot be used together with any of the options
+.Fl psxz .
+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 o Ar staplefile
+During the TLS handshake, load data to be stapled from
+.Ar staplefile ,
+which is expected to contain an OCSP response from an OCSP server in
+DER format.
+Requires
+.Fl c
+and
+.Fl C .
+.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.
+Cannot be used together with
+.Fl l .
+.It Fl R Ar CAfile
+Load the root CA bundle for TLS certificate verification from
+.Ar CAfile ,
+in PEM format, instead of
+.Pa /etc/ssl/cert.pem .
+Requires
+.Fl c .
+.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 l
+or
+.Fl x .
+.It Fl T Ar keyword
+Change the IPv4 TOS/IPv6 traffic class value or the TLS options.
+.Pp
+For TLS options,
+.Ar keyword
+may be one of:
+.Cm noverify ,
+which disables certificate verification;
+.Cm noname ,
+which disables certificate name checking;
+.Cm clientcert ,
+which requires a client certificate on incoming connections; or
+.Cm muststaple ,
+which requires the peer to provide a valid stapled OCSP response
+with the handshake.
+The following TLS options specify a value in the form of a
+.Ar key Ns = Ns Ar value
+pair:
+.Cm ciphers ,
+which allows the supported TLS ciphers to be specified (see
+.Xr tls_config_set_ciphers 3
+for further details);
+.Cm protocols ,
+which allows the supported TLS protocols to be specified (see
+.Xr tls_config_parse_protocols 3
+for further details).
+Specifying TLS options requires
+.Fl c .
+.Pp
+For the IPv4 TOS/IPv6 traffic class value,
+.Ar keyword
+may be one of
+.Cm critical ,
+.Cm inetcontrol ,
+.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 any of the options
+.Fl cFx .
+.It Fl u
+Use UDP instead of TCP.
+Cannot be used together with
+.Fl c
+or
+.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 Ar peercertfile
+Save the peer certificates to
+.Ar peercertfile ,
+in PEM format.
+Requires
+.Fl c .
+.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 .
+.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 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.
+For example:
+.Bd -literal -offset indent
+$ nc -z 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.
+.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 TCP connection to port 443 of www.example.com, and negotiate TLS with
+any supported TLS protocol version and "compat" ciphers:
+.Pp
+.Dl $ nc -cv -T protocols=all -T ciphers=compat www.example.com 443
+.Pp
+Open a TCP connection to port 443 of www.google.ca, and negotiate TLS.
+Check for a different name in the certificate for validation:
+.Pp
+.Dl $ nc -cv -e adsf.au.doubleclick.net www.google.ca 443
+.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 .
+.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.