- sort options and SYNOPSIS

- better document which options do/don't work together
- add sections showing some possible uses of nc
- code (comment) typos
- sync usage() and help

suggestions/improvements from otto@
ok deraadt@

2 files changed, 226 insertions, 94 deletions

diff --git a/src/usr.bin/nc/nc.1 b/src/usr.bin/nc/nc.1
index 5bf4480433..64a1dbbc8b 100644
--- a/src/usr.bin/nc/nc.1
+++ b/src/usr.bin/nc/nc.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: nc.1,v 1.27 2004/01/22 13:28:46 markus Exp $
+.\"     $OpenBSD: nc.1,v 1.28 2004/02/20 10:53:10 jmc Exp $
 .\"
 .\" Copyright (c) 1996 David Sacerdote
 .\" All rights reserved.
@@ -30,18 +30,21 @@
 .Os
 .Sh NAME
 .Nm nc
-.Nd "arbitrary TCP and UDP connections and listens"
+.Nd arbitrary TCP and UDP connections and listens
 .Sh SYNOPSIS
 .Nm nc
-.Op Fl 46hklnrtuvzSU
+.Op Fl 46hklnrStUuvz
 .Op Fl i Ar interval
-.Op Fl p Ar source port
-.Op Fl s Ar source ip address
-.Op Fl x Ar proxy address Op :port
+.Op Fl p Ar source_port
+.Op Fl s Ar source_ip_address
 .Op Fl w Ar timeout
-.Op Fl X Ar socks version
+.Op Fl X Ar socks_version
+.Oo Xo
+.Fl x Ar proxy_address Ns Oo : Ns
+.Ar port Oc Oc
+.Xc
 .Op Ar hostname
-.Op Ar port[s]
+.Op Ar port Ns Bq Ar s
 .Sh DESCRIPTION
 The
 .Nm
@@ -69,7 +72,7 @@ Common uses include:
 .It
 simple TCP proxies
 .It
-shell\-script based HTTP clients and servers
+shell-script based HTTP clients and servers
 .It
 network daemon testing
 .It
@@ -98,24 +101,41 @@ Forces
 .Nm
 to stay listening for another connection after its current connection
 is completed.
+It is an error to use this option without the
+.Fl l
+option.
 .It Fl l
 Used to specify that
 .Nm
 should listen for an incoming connection rather than initiate a
 connection to a remote host.
+It is an error to use this option in conjunction with the
+.Fl p ,
+.Fl s ,
+or
+.Fl z
+options.
 .It Fl n
 Do not do any DNS or service lookups on any specified addresses,
 hostnames or ports.
-.It Fl p Ar port
+.It Fl p Ar source_port
 Specifies the source port
 .Nm
 should use, subject to privilege restrictions and availability.
+It is an error to use this option in conjunction with the
+.Fl l
+option.
 .It Fl r
 Specifies that source and/or destination ports should be chosen randomly
 instead of sequentially within a range or in the order that the system
 assigns them.
-.It Fl s Ar hostname/ip address
+.It Fl S
+Enables the RFC 2385 TCP MD5 signature option.
+.It Fl s Ar source_ip_address
 Specifies the IP of the interface which is used to send the packets.
+It is an error to use this option in conjunction with the
+.Fl l
+option.
 .It Fl t
 Causes
 .Nm
@@ -123,6 +143,8 @@ to 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
+Specifies to use Unix Domain Sockets.
 .It Fl u
 Use UDP instead of the default option of TCP.
 .It Fl v
@@ -143,72 +165,182 @@ will listen forever for a connection, with or without the
 .Fl w
 flag.
 The default is no timeout.
-.It Fl x Ar proxy address Op :port
+.It Fl X Ar socks_version
+Requests that
+.Nm
+should use the specified version of the SOCKS protocol when talking to
+a SOCKS proxy.
+SOCKS versions 4 and 5 are currently supported.
+If the version is not specified, SOCKS version 5 is used.
+.It Xo
+.Fl x Ar proxy_address Ns Oo : Ns
+.Ar port Oc
+.Xc
 Requests that
 .Nm
 should connect to
 .Ar hostname
-using a SOCKS proxy at address and port.
-If port is not specified, port 1080 is used.
+using a SOCKS proxy at
+.Ar proxy_address
+and
+.Ar port .
+If
+.Ar port
+is not specified, port 1080 is used.
 .It Fl z
 Specifies that
 .Nm
 should just scan for listening daemons, without sending any data to them.
-.It Fl S
-Enables the RFC 2385 TCP MD5 signature option.
-.It Fl U
-Specifies to use Unix Domain Sockets.
-.It Fl X Ar version
-Requests that
-.Nm
-should use the specified version of the SOCKS protocol when talking to
-a SOCKS proxy.
-If version is not specified, SOCKS version 5 is used.
+It is an error to use this option in conjunction with the
+.Fl l
+option.
 .El
+.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 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:
+.Pp
+.Dl $ echo \&"GET\&" | nc host.example.com 80
+.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
+not to initiate a connection,
+together with the
+.Fl v
+.Pq verbose
+flag,
+to report open ports.
+For example:
+.Bd -literal -offset indent
+$ nc -vz 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
-.Bl -tag -width x
-.It Li "$ nc hostname 42"
-Open a TCP connection to port 42 of hostname.
-.It Li "$ nc -p 31337 hostname 42"
-Open a TCP connection to port 42 of hostname, and use port 31337 as
-the source port.
-.It Li "$ nc -w 5 hostname 42"
-Open a TCP connection to port 42 of hostname, and timeout after
-five seconds while attempting to connect.
-.It Li "$ nc -u hostname 53"
-Open a UDP connection to port 53 of hostname.
-.It Li "$ nc -s 10.1.2.3 example.host 42"
+Open a TCP connection to port 42 of hostname, using port 31337 as
+the source port, with a timeout of 5 seconds:
+.Pp
+.Dl $ nc -p 31337 -w 5 hostname 42
+.Pp
+Open a UDP connection to port 53 of hostname:
+.Pp
+.Dl $ nc -u hostname 53
+.Pp
 Open a TCP connection to port 42 of example.host using 10.1.2.3 as the
-IP for the local end of the connection.
-.It Li "$ nc -v hostname 42"
-Open a TCP connection to port 42 of hostname, displaying some
-diagnostic messages on stderr.
-.It Li "$ nc -v -z hostname 20-30"
-Attempt to open TCP connections to ports 20 through 30 of
-hostname, and report which ones
-.Nm
-was able to connect to.
-.It Li "$ nc -v -u -z -w 3 hostname 20-30"
+IP for the local end of the connection:
+.Pp
+.Dl $ nc -s 10.1.2.3 example.host 42
+.Pp
 Send UDP packets to ports 20-30 of example.host, and report which ones
-did not respond with an ICMP packet after three seconds.
-.It Li "$ nc -l 3000"
-Listen on TCP port 3000, and once there is a connection, send stdin to
-the remote host, and send data from the remote host to stdout.
-.It Li "$ echo foobar | nc hostname 1000"
-Connect to port 1000 of hostname, send the string "foobar"
-followed by a newline, and move data from port 1000 of hostname to
-stdout until hostname closes the connection.
-.It Li "$ nc -U /var/tmp/dsocket"
-Connect to a Unix Domain Socket.
-.It Li "$ nc -lU /var/tmp/dsocket"
-Create and listen on a Unix Domain Socket.
-.El
+responded with an ICMP packet after three seconds:
+.Pp
+.Dl $ nc -uvz -w 3 hostname 20-30
+.Pp
+Create and listen on a Unix Domain Socket:
+.Pp
+.Dl $ nc -lU /var/tmp/dsocket
 .Sh SEE ALSO
-.Xr cat 1 ,
-.Xr telnet 1
+.Xr cat 1
 .Sh AUTHORS
 Original implementation by *Hobbit*
 .Aq hobbit@avian.org .
-.Pp
-Rewritten with IPv6 support by Eric Jackson
-.Aq ericj@monkey.org .
+.br
+Rewritten with IPv6 support by
+.An Eric Jackson Aq ericj@monkey.org .
diff --git a/src/usr.bin/nc/netcat.c b/src/usr.bin/nc/netcat.c
index beca89e01c..505cbd77b1 100644
--- a/src/usr.bin/nc/netcat.c
+++ b/src/usr.bin/nc/netcat.c
@@ -1,4 +1,4 @@
-/* $OpenBSD: netcat.c,v 1.66 2004/01/31 21:09:15 henning Exp $ */
+/* $OpenBSD: netcat.c,v 1.67 2004/02/20 10:53:10 jmc Exp $ */
 /*
  * Copyright (c) 2001 Eric Jackson <ericj@monkey.org>
  *
@@ -63,7 +63,7 @@
 int     iflag;                                  /* Interval Flag */
 int     kflag;                                  /* More than one connect */
 int     lflag;                                  /* Bind to local port */
-int     nflag;                                  /* Dont do name lookup */
+int     nflag;                                  /* Don't do name look up */
 char   *pflag;                                  /* Localport flag */
 int     rflag;                                  /* Random ports flag */
 char   *sflag;                                  /* Source Address */
@@ -216,7 +216,7 @@ main(int argc, char *argv[])
         if (!lflag && kflag)
                 errx(1, "must use -l with -k");
 
-        /* Initialize addrinfo structure */
+        /* Initialize addrinfo structure. */
         if (family != AF_UNIX) {
                 memset(&hints, 0, sizeof(struct addrinfo));
                 hints.ai_family = family;
@@ -261,7 +261,7 @@ main(int argc, char *argv[])
                 if (family == AF_UNIX)
                         s = unix_listen(host);
 
-                /* Allow only one connection at a time, but stay alive */
+                /* Allow only one connection at a time, but stay alive. */
                 for (;;) {
                         if (family != AF_UNIX)
                                 s = local_listen(host, uport, hints);
@@ -315,10 +315,10 @@ main(int argc, char *argv[])
         } else {
                 int i = 0;
 
-                /* construct the portlist[] array */
+                /* Construct the portlist[] array. */
                 build_ports(uport);
 
-                /* Cycle through portlist, connecting to each port */
+                /* Cycle through portlist, connecting to each port. */
                 for (i = 0; portlist[i] != NULL; i++) {
                         if (s)
                                 close(s);
@@ -334,7 +334,7 @@ main(int argc, char *argv[])
 
                         ret = 0;
                         if (vflag || zflag) {
-                                /* For UDP, make sure we are connected */
+                                /* For UDP, make sure we are connected. */
                                 if (uflag) {
                                         if (udptest(s) == -1) {
                                                 ret = 1;
@@ -342,7 +342,7 @@ main(int argc, char *argv[])
                                         }
                                 }
 
-                                /* Don't lookup port if -n */
+                                /* Don't look up port if -n. */
                                 if (nflag)
                                         sv = NULL;
                                 else {
@@ -368,7 +368,7 @@ main(int argc, char *argv[])
 
 /*
  * unix_connect()
- * Return's a socket connected to a local unix socket. Return's -1 on failure.
+ * Returns a socket connected to a local unix socket. Returns -1 on failure.
  */
 int
 unix_connect(char *path)
@@ -399,7 +399,7 @@ unix_connect(char *path)
 
 /*
  * unix_listen()
- * create a unix domain socket, and listen on it.
+ * Create a unix domain socket, and listen on it.
  */
 int
 unix_listen(char *path)
@@ -407,7 +407,7 @@ unix_listen(char *path)
         struct sockaddr_un sun;
         int s;
 
-        /* create unix domain socket */
+        /* Create unix domain socket. */
         if ((s = socket(AF_UNIX, SOCK_STREAM, 0)) < 0)
                 return (-1);
 
@@ -435,8 +435,8 @@ unix_listen(char *path)
 
 /*
  * remote_connect()
- * Return's a socket connected to a remote host. Properly bind's to a local
- * port or source address if needed. Return's -1 on failure.
+ * Returns a socket connected to a remote host. Properly binds to a local
+ * port or source address if needed. Returns -1 on failure.
  */
 int
 remote_connect(char *host, char *port, struct addrinfo hints)
@@ -453,7 +453,7 @@ remote_connect(char *host, char *port, struct addrinfo hints)
                     res0->ai_protocol)) < 0)
                         continue;
 
-                /* Bind to a local port or source address if specified */
+                /* Bind to a local port or source address if specified. */
                 if (sflag || pflag) {
                         struct addrinfo ahints, *ares;
 
@@ -497,8 +497,8 @@ remote_connect(char *host, char *port, struct addrinfo hints)
 
 /*
  * local_listen()
- * Return's a socket listening on a local port, binds to specified source
- * address. Return's -1 on failure.
+ * Returns a socket listening on a local port, binds to specified source
+ * address. Returns -1 on failure.
  */
 int
 local_listen(char *host, char *port, struct addrinfo hints)
@@ -507,7 +507,7 @@ local_listen(char *host, char *port, struct addrinfo hints)
         int s, ret, x = 1;
         int error;
 
-        /* Allow nodename to be null */
+        /* Allow nodename to be null. */
         hints.ai_flags |= AI_PASSIVE;
 
         /*
@@ -570,7 +570,7 @@ readwrite(int nfd)
         pfd[0].fd = nfd;
         pfd[0].events = POLLIN;
 
-        /* Setup STDIN FD */
+        /* Set up STDIN FD. */
         pfd[1].fd = wfd;
         pfd[1].events = POLLIN;
 
@@ -620,7 +620,7 @@ readwrite(int nfd)
         }
 }
 
-/* Deal with RFC854 WILL/WONT DO/DONT negotiation */
+/* Deal with RFC 854 WILL/WONT DO/DONT negotiation. */
 void
 atelnet(int nfd, unsigned char *buf, unsigned int size)
 {
@@ -657,7 +657,7 @@ atelnet(int nfd, unsigned char *buf, unsigned int size)
 /*
  * build_ports()
  * Build an array or ports in portlist[], listing each port
- * that we should try to connect too.
+ * that we should try to connect to.
  */
 void
 build_ports(char *p)
@@ -673,7 +673,7 @@ build_ports(char *p)
                 *n = '\0';
                 n++;
 
-                /* Make sure the ports are in order: lowest->highest */
+                /* Make sure the ports are in order: lowest->highest. */
                 hi = (int)strtoul(n, &endp, 10);
                 if (hi <= 0 || hi > PORT_MAX || *endp != '\0')
                         errx(1, "port range not valid");
@@ -687,7 +687,7 @@ build_ports(char *p)
                         lo = cp;
                 }
 
-                /* Load ports sequentially */
+                /* Load ports sequentially. */
                 for (cp = lo; cp <= hi; cp++) {
                         portlist[x] = calloc(1, PORT_MAX_LEN);
                         if (portlist[x] == NULL)
@@ -696,7 +696,7 @@ build_ports(char *p)
                         x++;
                 }
 
-                /* Randomly swap ports */
+                /* Randomly swap ports. */
                 if (rflag) {
                         int y;
                         char *c;
@@ -722,7 +722,7 @@ build_ports(char *p)
 /*
  * udptest()
  * Do a few writes to see if the UDP port is there.
- * XXX - Better way of doing this? Doesn't work for IPv6
+ * XXX - Better way of doing this? Doesn't work for IPv6.
  * Also fails after around 100 ports checked.
  */
 int
@@ -746,9 +746,6 @@ help(void)
         fprintf(stderr, "\tCommand Summary:\n\
         \t-4            Use IPv4\n\
         \t-6            Use IPv6\n\
-        \t-S            Enable the TCP MD5 signature option\n\
-        \t-U            Use UNIX domain socket\n\
-        \t-X vers\t     SOCKS version (4 or 5)\n\
         \t-h            This help text\n\
         \t-i secs\t     Delay interval for lines sent, ports scanned\n\
         \t-k            Keep inbound sockets open for multiple connects\n\
@@ -756,11 +753,14 @@ help(void)
         \t-n            Suppress name/port resolutions\n\
         \t-p port\t     Specify local port for remote connects\n\
         \t-r            Randomize remote ports\n\
+        \t-S            Enable the TCP MD5 signature option\n\
         \t-s addr\t     Local source address\n\
         \t-t            Answer TELNET negotiation\n\
+        \t-U            Use UNIX domain socket\n\
         \t-u            UDP mode\n\
         \t-v            Verbose\n\
         \t-w secs\t     Timeout for connects and final net reads\n\
+        \t-X vers\t     SOCKS version (4 or 5)\n\
         \t-x addr[:port]\tSpecify socks proxy address and port\n\
         \t-z            Zero-I/O mode [used for scanning]\n\
         Port numbers can be individual or ranges: lo-hi [inclusive]\n");
@@ -770,9 +770,9 @@ help(void)
 void
 usage(int ret)
 {
-        fprintf(stderr, "usage: nc [-46SUhklnrtuvz] [-i interval] [-p source port]\n");
-        fprintf(stderr, "\t  [-s ip address] [-w timeout] [-X vers] [-x proxy address [:port]]\n");
-        fprintf(stderr, "\t  [hostname] [port[s...]]\n");
+        fprintf(stderr, "usage: nc [-46hklnrStUuvz] [-i interval] [-p source_port] [-s source_ip_address]\n");
+        fprintf(stderr, "\t  [-w timeout] [-X socks_version] [-x proxy_address[:port]] [hostname]\n");
+        fprintf(stderr, "\t  [port[s]]\n");
         if (ret)
                 exit(1);
 }