contrib/netcat/nc.1

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