src/dragonfly/nc.1

   1 .\"     $OpenBSD: nc.1,v 1.40 2005/07/17 19:18:47 jmc 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 June 25, 2001
  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 46DdhklnrtUuvz
  38 .Op Fl i Ar interval
  39 .Op Fl p Ar source_port
  40 .Op Fl s Ar source_ip_address
  41 .Op Fl w Ar timeout
  42 .Op Fl X Ar proxy_protocol
  43 .Oo Xo
  44 .Fl x Ar proxy_address Ns Oo : Ns
  45 .Ar port Oc Oc
  46 .Xc
  47 .Op Ar hostname
  48 .Op Ar port Ns Bq Ar s
  49 .Ek
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 (or
  54 .Nm netcat )
  55 utility is used for just about anything under the sun involving TCP
  56 or UDP.
  57 It can open TCP connections, send UDP packets, listen on arbitrary
  58 TCP and UDP ports, do port scanning, and deal with both IPv4 and
  59 IPv6.
  60 Unlike
  61 .Xr telnet 1 ,
  62 .Nm
  63 scripts nicely, and separates error messages onto standard error instead
  64 of sending them to standard output, as
  65 .Xr telnet 1
  66 does with some.
  67 .Pp
  68 Common uses include:
  69 .Pp
  70 .Bl -bullet -offset indent -compact
  71 .It
  72 simple TCP proxies
  73 .It
  74 shell-script based HTTP clients and servers
  75 .It
  76 network daemon testing
  77 .It
  78 a SOCKS or HTTP ProxyCommand for
  79 .Xr ssh 1
  80 .It
  81 and much, much more
  82 .El
  83 .Pp
  84 The options are as follows:
  85 .Bl -tag -width Ds
  86 .It Fl 4
  87 Forces
  88 .Nm
  89 to use IPv4 addresses only.
  90 .It Fl 6
  91 Forces
  92 .Nm
  93 to use IPv6 addresses only.
  94 .It Fl D
  95 Enable debugging on the socket.
  96 .It Fl d
  97 Do not attempt to read from stdin.
  98 .It Fl h
  99 Prints out
 100 .Nm
 101 help.
 102 .It Fl i Ar interval
 103 Specifies a delay time interval between lines of text sent and received.
 104 Also causes a delay time between connections to multiple ports.
 105 .It Fl k
 106 Forces
 107 .Nm
 108 to stay listening for another connection after its current connection
 109 is completed.
 110 It is an error to use this option without the
 111 .Fl l
 112 option.
 113 .It Fl l
 114 Used to specify that
 115 .Nm
 116 should listen for an incoming connection rather than initiate a
 117 connection to a remote host.
 118 It is an error to use this option in conjunction with the
 119 .Fl p ,
 120 .Fl s ,
 121 or
 122 .Fl z
 123 options.
 124 Additionally, any timeouts specified with the
 125 .Fl w
 126 option are ignored.
 127 .It Fl n
 128 Do not do any DNS or service lookups on any specified addresses,
 129 hostnames or ports.
 130 .It Fl p Ar source_port
 131 Specifies the source port
 132 .Nm
 133 should use, subject to privilege restrictions and availability.
 134 It is an error to use this option in conjunction with the
 135 .Fl l
 136 option.
 137 .It Fl r
 138 Specifies that source and/or destination ports should be chosen randomly
 139 instead of sequentially within a range or in the order that the system
 140 assigns them.
 141 .It Fl s Ar source_ip_address
 142 Specifies the IP of the interface which is used to send the packets.
 143 It is an error to use this option in conjunction with the
 144 .Fl l
 145 option.
 146 .It Fl t
 147 Causes
 148 .Nm
 149 to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
 150 This makes it possible to use
 151 .Nm
 152 to script telnet sessions.
 153 .It Fl U
 154 Specifies to use Unix Domain Sockets.
 155 .It Fl u
 156 Use UDP instead of the default option of TCP.
 157 .It Fl v
 158 Have
 159 .Nm
 160 give more verbose output.
 161 .It Fl w Ar timeout
 162 If a connection and stdin are idle for more than
 163 .Ar timeout
 164 seconds, then the connection is silently closed.
 165 The
 166 .Fl w
 167 flag has no effect on the
 168 .Fl l
 169 option, i.e.\&
 170 .Nm
 171 will listen forever for a connection, with or without the
 172 .Fl w
 173 flag.
 174 The default is no timeout.
 175 .It Fl X Ar proxy_version
 176 Requests that
 177 .Nm
 178 should use the specified protocol when talking to the proxy server.
 179 Supported protocols are
 180 .Dq 4
 181 (SOCKS v.4),
 182 .Dq 5
 183 (SOCKS v.5)
 184 and
 185 .Dq connect
 186 (HTTPS proxy).
 187 If the protocol is not specified, SOCKS version 5 is used.
 188 .It Xo
 189 .Fl x Ar proxy_address Ns Oo : Ns
 190 .Ar port Oc
 191 .Xc
 192 Requests that
 193 .Nm
 194 should connect to
 195 .Ar hostname
 196 using a proxy at
 197 .Ar proxy_address
 198 and
 199 .Ar port .
 200 If
 201 .Ar port
 202 is not specified, the well-known port for the proxy protocol is used (1080
 203 for SOCKS, 3128 for HTTPS).
 204 .It Fl z
 205 Specifies that
 206 .Nm
 207 should just scan for listening daemons, without sending any data to them.
 208 It is an error to use this option in conjunction with the
 209 .Fl l
 210 option.
 211 .El
 212 .Pp
 213 .Ar hostname
 214 can be a numerical IP address or a symbolic hostname
 215 (unless the
 216 .Fl n
 217 option is given).
 218 In general, a hostname must be specified,
 219 unless the
 220 .Fl l
 221 option is given
 222 (in which case the local host is used).
 223 .Pp
 224 .Ar port Ns Op Ar s
 225 can be single integers or ranges.
 226 Ranges are in the form nn-mm.
 227 In general,
 228 a destination port must be specified,
 229 unless the
 230 .Fl U
 231 option is given
 232 (in which case a socket must be specified).
 233 .Sh CLIENT/SERVER MODEL
 234 It is quite simple to build a very basic client/server model using
 235 .Nm .
 236 On one console, start
 237 .Nm
 238 listening on a specific port for a connection.
 239 For example:
 240 .Pp
 241 .Dl $ nc -l 1234
 242 .Pp
 243 .Nm
 244 is now listening on port 1234 for a connection.
 245 On a second console
 246 .Pq or a second machine ,
 247 connect to the machine and port being listened on:
 248 .Pp
 249 .Dl $ nc 127.0.0.1 1234
 250 .Pp
 251 There should now be a connection between the ports.
 252 Anything typed at the second console will be concatenated to the first,
 253 and vice-versa.
 254 After the connection has been set up,
 255 .Nm
 256 does not really care which side is being used as a
 257 .Sq server
 258 and which side is being used as a
 259 .Sq client .
 260 The connection may be terminated using an
 261 .Dv EOF
 262 .Pq Sq ^D .
 263 .Sh DATA TRANSFER
 264 The example in the previous section can be expanded to build a
 265 basic data transfer model.
 266 Any information input into one end of the connection will be output
 267 to the other end, and input and output can be easily captured in order to
 268 emulate file transfer.
 269 .Pp
 270 Start by using
 271 .Nm
 272 to listen on a specific port, with output captured into a file:
 273 .Pp
 274 .Dl $ nc -l 1234 \*(Gt filename.out
 275 .Pp
 276 Using a second machine, connect to the listening
 277 .Nm
 278 process, feeding it the file which is to be transferred:
 279 .Pp
 280 .Dl $ nc host.example.com 1234 \*(Lt filename.in
 281 .Pp
 282 After the file has been transferred, the connection will close automatically.
 283 .Sh TALKING TO SERVERS
 284 It is sometimes useful to talk to servers
 285 .Dq by hand
 286 rather than through a user interface.
 287 It can aid in troubleshooting,
 288 when it might be necessary to verify what data a server is sending
 289 in response to commands issued by the client.
 290 For example, to retrieve the home page of a web site:
 291 .Bd -literal -offset indent
 292 $ echo -n "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
 293 .Ed
 294 .Pp
 295 Note that this also displays the headers sent by the web server.
 296 They can be filtered, using a tool such as
 297 .Xr sed 1 ,
 298 if necessary.
 299 .Pp
 300 More complicated examples can be built up when the user knows the format
 301 of requests required by the server.
 302 As another example, an email may be submitted to an SMTP server using:
 303 .Bd -literal -offset indent
 304 $ nc localhost 25 \*(Lt\*(Lt EOF
 305 HELO host.example.com
 306 MAIL FROM: \*(Ltuser@host.example.com\*(Gt
 307 RCPT TO: \*(Ltuser2@host.example.com\*(Gt
 308 DATA
 309 Body of email.
 310 \&.
 311 QUIT
 312 EOF
 313 .Ed
 314 .Sh PORT SCANNING
 315 It may be useful to know which ports are open and running services on
 316 a target machine.
 317 The
 318 .Fl z
 319 flag can be used to tell
 320 .Nm
 321 to report open ports,
 322 rather than initiate a connection.
 323 For example:
 324 .Bd -literal -offset indent
 325 $ nc -z host.example.com 20-30
 326 Connection to host.example.com 22 port [tcp/ssh] succeeded!
 327 Connection to host.example.com 25 port [tcp/smtp] succeeded!
 328 .Ed
 329 .Pp
 330 The port range was specified to limit the search to ports 20 \- 30.
 331 .Pp
 332 Alternatively, it might be useful to know which server software
 333 is running, and which versions.
 334 This information is often contained within the greeting banners.
 335 In order to retrieve these, it is necessary to first make a connection,
 336 and then break the connection when the banner has been retrieved.
 337 This can be accomplished by specifying a small timeout with the
 338 .Fl w
 339 flag, or perhaps by issuing a
 340 .Qq Dv QUIT
 341 command to the server:
 342 .Bd -literal -offset indent
 343 $ echo "QUIT" | nc host.example.com 20-30
 344 SSH-1.99-OpenSSH_3.6.1p2
 345 Protocol mismatch.
 346 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
 347 .Ed
 348 .Sh EXAMPLES
 349 Open a TCP connection to port 42 of host.example.com, using port 31337 as
 350 the source port, with a timeout of 5 seconds:
 351 .Pp
 352 .Dl $ nc -p 31337 -w 5 host.example.com 42
 353 .Pp
 354 Open a UDP connection to port 53 of host.example.com:
 355 .Pp
 356 .Dl $ nc -u host.example.com 53
 357 .Pp
 358 Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
 359 IP for the local end of the connection:
 360 .Pp
 361 .Dl $ nc -s 10.1.2.3 host.example.com 42
 362 .Pp
 363 Create and listen on a Unix Domain Socket:
 364 .Pp
 365 .Dl $ nc -lU /var/tmp/dsocket
 366 .Pp
 367 Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
 368 port 8080.
 369 This example could also be used by
 370 .Xr ssh 1 ;
 371 see the
 372 .Cm ProxyCommand
 373 directive in
 374 .Xr ssh_config 5
 375 for more information.
 376 .Pp
 377 .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
 378 .Sh SEE ALSO
 379 .Xr cat 1 ,
 380 .Xr ssh 1
 381 .Sh AUTHORS
 382 Original implementation by *Hobbit*
 383 .Aq hobbit@avian.org .
 384 .br
 385 Rewritten with IPv6 support by
 386 .An Eric Jackson Aq ericj@monkey.org .
 387 .Sh CAVEATS
 388 UDP port scans will always succeed
 389 (i.e. report the port as open),
 390 rendering the
 391 .Fl uz
 392 combination of flags relatively useless.