contrib/netcat/nc.1

   1 .\"     $OpenBSD: nc.1,v 1.60 2012/02/07 12:11:43 lum 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 October 4, 2011
  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 46DdEhklnrStUuvz
  40 .Op Fl e Ar IPsec_policy
  41 .Op Fl I Ar length
  42 .Op Fl i Ar interval
  43 .Op Fl -no-tcpopt
  44 .Op Fl O Ar length
  45 .Op Fl P Ar proxy_username
  46 .Op Fl p Ar source_port
  47 .Op Fl s Ar source
  48 .Op Fl T Ar toskeyword
  49 .Op Fl V Ar rtable
  50 .Op Fl w Ar timeout
  51 .Op Fl X Ar proxy_protocol
  52 .Oo Xo
  53 .Fl x Ar proxy_address Ns Oo : Ns
  54 .Ar port Oc
  55 .Xc Oc
  56 .Op Ar destination
  57 .Op Ar port
  58 .Ek
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 (or
  63 .Nm netcat )
  64 utility is used for just about anything under the sun involving TCP,
  65 UDP, or
  66 .Ux Ns -domain
  67 sockets.
  68 It can open TCP connections, send UDP packets, listen on arbitrary
  69 TCP and UDP ports, do port scanning, and deal with both IPv4 and
  70 IPv6.
  71 Unlike
  72 .Xr telnet 1 ,
  73 .Nm
  74 scripts nicely, and separates error messages onto standard error instead
  75 of sending them to standard output, as
  76 .Xr telnet 1
  77 does with some.
  78 .Pp
  79 Common uses include:
  80 .Pp
  81 .Bl -bullet -offset indent -compact
  82 .It
  83 simple TCP proxies
  84 .It
  85 shell-script based HTTP clients and servers
  86 .It
  87 network daemon testing
  88 .It
  89 a SOCKS or HTTP ProxyCommand for
  90 .Xr ssh 1
  91 .It
  92 and much, much more
  93 .El
  94 .Pp
  95 The options are as follows:
  96 .Bl -tag -width Ds
  97 .It Fl 4
  98 Forces
  99 .Nm
 100 to use IPv4 addresses only.
 101 .It Fl 6
 102 Forces
 103 .Nm
 104 to use IPv6 addresses only.
 105 .It Fl D
 106 Enable debugging on the socket.
 107 .It Fl d
 108 Do not attempt to read from stdin.
 109 .It Fl E
 110 Shortcut for
 111 .Qo
 112 .Li "-e 'in ipsec esp/transport//require'"
 113 .Li "-e 'out ipsec esp/transport//require'"
 114 .Qc ,
 115 which enables IPsec ESP transport mode in both
 116 directions.
 117 .It Fl e
 118 If IPsec support is available, then one can specify the IPsec policies
 119 to be used using the syntax described in
 120 .Xr ipsec_set_policy 3 .
 121 This flag can be specified up to two times, as typically one policy for
 122 each direction is needed.
 123 .It Fl h
 124 Prints out
 125 .Nm
 126 help.
 127 .It Fl I Ar length
 128 Specifies the size of the TCP receive buffer.
 129 .It Fl i Ar interval
 130 Specifies a delay time interval between lines of text sent and received.
 131 Also causes a delay time between connections to multiple ports.
 132 .It Fl k
 133 Forces
 134 .Nm
 135 to stay listening for another connection after its current connection
 136 is completed.
 137 It is an error to use this option without the
 138 .Fl l
 139 option.
 140 .It Fl l
 141 Used to specify that
 142 .Nm
 143 should listen for an incoming connection rather than initiate a
 144 connection to a remote host.
 145 It is an error to use this option in conjunction with the
 146 .Fl p ,
 147 .Fl s ,
 148 or
 149 .Fl z
 150 options.
 151 Additionally, any timeouts specified with the
 152 .Fl w
 153 option are ignored.
 154 .It Fl n
 155 Do not do any DNS or service lookups on any specified addresses,
 156 hostnames or ports.
 157 .It Fl -no-tcpopt
 158 Disables the use of TCP options on the socket, by setting the boolean
 159 TCP_NOOPT
 160 socket option.
 161 .It Fl O Ar length
 162 Specifies the size of the TCP send buffer.
 163 .It Fl P Ar proxy_username
 164 Specifies a username to present to a proxy server that requires authentication.
 165 If no username is specified then authentication will not be attempted.
 166 Proxy authentication is only supported for HTTP CONNECT proxies at present.
 167 .It Fl p Ar source_port
 168 Specifies the source port
 169 .Nm
 170 should use, subject to privilege restrictions and availability.
 171 It is an error to use this option in conjunction with the
 172 .Fl l
 173 option.
 174 .It Fl r
 175 Specifies that source and/or destination ports should be chosen randomly
 176 instead of sequentially within a range or in the order that the system
 177 assigns them.
 178 .It Fl S
 179 Enables the RFC 2385 TCP MD5 signature option.
 180 .It Fl s Ar source
 181 Specifies the IP of the interface which is used to send the packets.
 182 For
 183 .Ux Ns -domain
 184 datagram sockets, specifies the local temporary socket file
 185 to create and use so that datagrams can be received.
 186 It is an error to use this option in conjunction with the
 187 .Fl l
 188 option.
 189 .It Fl T Ar toskeyword
 190 Change IPv4 TOS value.
 191 .Ar toskeyword
 192 may be one of
 193 .Ar critical ,
 194 .Ar inetcontrol ,
 195 .Ar lowdelay ,
 196 .Ar netcontrol ,
 197 .Ar throughput ,
 198 .Ar reliability ,
 199 or one of the DiffServ Code Points:
 200 .Ar ef ,
 201 .Ar af11 ... af43 ,
 202 .Ar cs0 ... cs7 ;
 203 or a number in either hex or decimal.
 204 .It Fl t
 205 Causes
 206 .Nm
 207 to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
 208 This makes it possible to use
 209 .Nm
 210 to script telnet sessions.
 211 .It Fl U
 212 Specifies to use
 213 .Ux Ns -domain
 214 sockets.
 215 .It Fl u
 216 Use UDP instead of the default option of TCP.
 217 For
 218 .Ux Ns -domain
 219 sockets, use a datagram socket instead of a stream socket.
 220 If a
 221 .Ux Ns -domain
 222 socket is used, a temporary receiving socket is created in
 223 .Pa /tmp
 224 unless the
 225 .Fl s
 226 flag is given.
 227 .It Fl V Ar rtable
 228 Set the routing table
 229 .Pq Dq FIB
 230 to be used.
 231 The default is 0.
 232 .It Fl v
 233 Have
 234 .Nm
 235 give more verbose output.
 236 .It Fl w Ar timeout
 237 Connections which cannot be established or are idle timeout after
 238 .Ar timeout
 239 seconds.
 240 The
 241 .Fl w
 242 flag has no effect on the
 243 .Fl l
 244 option, i.e.\&
 245 .Nm
 246 will listen forever for a connection, with or without the
 247 .Fl w
 248 flag.
 249 The default is no timeout.
 250 .It Fl X Ar proxy_protocol
 251 Requests that
 252 .Nm
 253 should use the specified protocol when talking to the proxy server.
 254 Supported protocols are
 255 .Dq 4
 256 (SOCKS v.4),
 257 .Dq 5
 258 (SOCKS v.5)
 259 and
 260 .Dq connect
 261 (HTTPS proxy).
 262 If the protocol is not specified, SOCKS version 5 is used.
 263 .It Xo
 264 .Fl x Ar proxy_address Ns Oo : Ns
 265 .Ar port Oc
 266 .Xc
 267 Requests that
 268 .Nm
 269 should connect to
 270 .Ar destination
 271 using a proxy at
 272 .Ar proxy_address
 273 and
 274 .Ar port .
 275 If
 276 .Ar port
 277 is not specified, the well-known port for the proxy protocol is used (1080
 278 for SOCKS, 3128 for HTTPS).
 279 .It Fl z
 280 Specifies that
 281 .Nm
 282 should just scan for listening daemons, without sending any data to them.
 283 It is an error to use this option in conjunction with the
 284 .Fl l
 285 option.
 286 .El
 287 .Pp
 288 .Ar destination
 289 can be a numerical IP address or a symbolic hostname
 290 (unless the
 291 .Fl n
 292 option is given).
 293 In general, a destination must be specified,
 294 unless the
 295 .Fl l
 296 option is given
 297 (in which case the local host is used).
 298 For
 299 .Ux Ns -domain
 300 sockets, a destination is required and is the socket path to connect to
 301 (or listen on if the
 302 .Fl l
 303 option is given).
 304 .Pp
 305 .Ar port
 306 can be a single integer or a range of ports.
 307 Ranges are in the form nn-mm.
 308 In general,
 309 a destination port must be specified,
 310 unless the
 311 .Fl U
 312 option is given.
 313 .Sh CLIENT/SERVER MODEL
 314 It is quite simple to build a very basic client/server model using
 315 .Nm .
 316 On one console, start
 317 .Nm
 318 listening on a specific port for a connection.
 319 For example:
 320 .Pp
 321 .Dl $ nc -l 1234
 322 .Pp
 323 .Nm
 324 is now listening on port 1234 for a connection.
 325 On a second console
 326 .Pq or a second machine ,
 327 connect to the machine and port being listened on:
 328 .Pp
 329 .Dl $ nc 127.0.0.1 1234
 330 .Pp
 331 There should now be a connection between the ports.
 332 Anything typed at the second console will be concatenated to the first,
 333 and vice-versa.
 334 After the connection has been set up,
 335 .Nm
 336 does not really care which side is being used as a
 337 .Sq server
 338 and which side is being used as a
 339 .Sq client .
 340 The connection may be terminated using an
 341 .Dv EOF
 342 .Pq Sq ^D .
 343 .Sh DATA TRANSFER
 344 The example in the previous section can be expanded to build a
 345 basic data transfer model.
 346 Any information input into one end of the connection will be output
 347 to the other end, and input and output can be easily captured in order to
 348 emulate file transfer.
 349 .Pp
 350 Start by using
 351 .Nm
 352 to listen on a specific port, with output captured into a file:
 353 .Pp
 354 .Dl $ nc -l 1234 \*(Gt filename.out
 355 .Pp
 356 Using a second machine, connect to the listening
 357 .Nm
 358 process, feeding it the file which is to be transferred:
 359 .Pp
 360 .Dl $ nc host.example.com 1234 \*(Lt filename.in
 361 .Pp
 362 After the file has been transferred, the connection will close automatically.
 363 .Sh TALKING TO SERVERS
 364 It is sometimes useful to talk to servers
 365 .Dq by hand
 366 rather than through a user interface.
 367 It can aid in troubleshooting,
 368 when it might be necessary to verify what data a server is sending
 369 in response to commands issued by the client.
 370 For example, to retrieve the home page of a web site:
 371 .Bd -literal -offset indent
 372 $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
 373 .Ed
 374 .Pp
 375 Note that this also displays the headers sent by the web server.
 376 They can be filtered, using a tool such as
 377 .Xr sed 1 ,
 378 if necessary.
 379 .Pp
 380 More complicated examples can be built up when the user knows the format
 381 of requests required by the server.
 382 As another example, an email may be submitted to an SMTP server using:
 383 .Bd -literal -offset indent
 384 $ nc localhost 25 \*(Lt\*(Lt EOF
 385 HELO host.example.com
 386 MAIL FROM:\*(Ltuser@host.example.com\*(Gt
 387 RCPT TO:\*(Ltuser2@host.example.com\*(Gt
 388 DATA
 389 Body of email.
 390 \&.
 391 QUIT
 392 EOF
 393 .Ed
 394 .Sh PORT SCANNING
 395 It may be useful to know which ports are open and running services on
 396 a target machine.
 397 The
 398 .Fl z
 399 flag can be used to tell
 400 .Nm
 401 to report open ports,
 402 rather than initiate a connection.
 403 For example:
 404 .Bd -literal -offset indent
 405 $ nc -z host.example.com 20-30
 406 Connection to host.example.com 22 port [tcp/ssh] succeeded!
 407 Connection to host.example.com 25 port [tcp/smtp] succeeded!
 408 .Ed
 409 .Pp
 410 The port range was specified to limit the search to ports 20 \- 30.
 411 .Pp
 412 Alternatively, it might be useful to know which server software
 413 is running, and which versions.
 414 This information is often contained within the greeting banners.
 415 In order to retrieve these, it is necessary to first make a connection,
 416 and then break the connection when the banner has been retrieved.
 417 This can be accomplished by specifying a small timeout with the
 418 .Fl w
 419 flag, or perhaps by issuing a
 420 .Qq Dv QUIT
 421 command to the server:
 422 .Bd -literal -offset indent
 423 $ echo "QUIT" | nc host.example.com 20-30
 424 SSH-1.99-OpenSSH_3.6.1p2
 425 Protocol mismatch.
 426 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
 427 .Ed
 428 .Sh EXAMPLES
 429 Open a TCP connection to port 42 of host.example.com, using port 31337 as
 430 the source port, with a timeout of 5 seconds:
 431 .Pp
 432 .Dl $ nc -p 31337 -w 5 host.example.com 42
 433 .Pp
 434 Open a UDP connection to port 53 of host.example.com:
 435 .Pp
 436 .Dl $ nc -u host.example.com 53
 437 .Pp
 438 Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
 439 IP for the local end of the connection:
 440 .Pp
 441 .Dl $ nc -s 10.1.2.3 host.example.com 42
 442 .Pp
 443 Open a TCP connection to port 42 of host.example.com using IPsec ESP for
 444 incoming and outgoing traffic.
 445 .Pp
 446 .Dl $ nc -E host.example.com 42
 447 .Pp
 448 Open a TCP connection to port 42 of host.example.com using IPsec ESP for
 449 outgoing traffic only.
 450 .Pp
 451 .Dl $ nc -e 'out ipsec esp/transport//require' host.example.com 42
 452 .Pp
 453 Create and listen on a
 454 .Ux Ns -domain
 455 stream socket:
 456 .Pp
 457 .Dl $ nc -lU /var/tmp/dsocket
 458 .Pp
 459 Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
 460 port 8080.
 461 This example could also be used by
 462 .Xr ssh 1 ;
 463 see the
 464 .Cm ProxyCommand
 465 directive in
 466 .Xr ssh_config 5
 467 for more information.
 468 .Pp
 469 .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
 470 .Pp
 471 The same example again, this time enabling proxy authentication with username
 472 .Dq ruser
 473 if the proxy requires it:
 474 .Pp
 475 .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
 476 .Sh EXIT STATUS
 477 .Ex -std
 478 .Sh SEE ALSO
 479 .Xr cat 1 ,
 480 .Xr setfib 1 ,
 481 .Xr ssh 1 ,
 482 .Xr tcp 4
 483 .Sh AUTHORS
 484 Original implementation by *Hobbit*
 485 .Aq hobbit@avian.org .
 486 .br
 487 Rewritten with IPv6 support by
 488 .An Eric Jackson Aq ericj@monkey.org .
 489 .Sh CAVEATS
 490 UDP port scans using the
 491 .Fl uz
 492 combination of flags will always report success irrespective of
 493 the target machine's state.
 494 However,
 495 in conjunction with a traffic sniffer either on the target machine
 496 or an intermediary device,
 497 the
 498 .Fl uz
 499 combination could be useful for communications diagnostics.
 500 Note that the amount of UDP traffic generated may be limited either
 501 due to hardware resources and/or configuration settings.