diff options
Diffstat (limited to 'usr.bin/nc/nc.1')
| -rw-r--r-- | usr.bin/nc/nc.1 | 585 |
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. |