Clarified the docs and help screen about what a 'cmd' is

This also changes the descriptions of several options to note that they accept
a "command"; change the description of --client-connect and --client-disconnect
indicate that the temporary file's path is passed as the last argument to the
command, not the first argument; and Adds a description of --route-pre-down to
the descriptions of the other --route options.

[DS: This patch is based on parts of the options.c.diff and the complete
     openvpn.8.diff patch sent to the mailing list - where these docs changes
     are merged together into this patch]

Signed-off-by: Jonathan K. Bullard <jkbullard@gmail.com>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: CAEsd45RkyJw6yUk1Jwkip70HkCjKYoU+V=do3N7SH7JOaHBZdw@mail.gmail.com
URL: http://article.gmane.org/gmane.network.openvpn.devel/6194
Signed-off-by: David Sommerseth <davids@redhat.com>

2 files changed, 120 insertions, 61 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index ee46de6..24b1a2c 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -612,12 +612,21 @@ option.
 .\"*********************************************************
 .TP
 .B \-\-ipchange cmd
-Execute shell command
+Run command
 .B cmd
 when our remote ip-address is initially authenticated or
 changes.
 
-Execute as:
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+When
+.B cmd
+is executed two arguments are appended after any arguments specified in
+.B cmd
+, as follows:
 
 .B cmd ip_address port_number
 
@@ -632,14 +641,6 @@ script instead.
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.
 
-Note that
-.B cmd
-can be a shell command with multiple arguments, in which
-case all OpenVPN-generated arguments will be appended
-to
-.B cmd
-to build a command line which will be passed to the script.
-
 If you are running in a dynamic IP address environment where
 the IP addresses of either peer could change without notice,
 you can use this script, for example, to edit the
@@ -1047,17 +1048,32 @@ for the TAP-Win32 adapter to come up before adding routes.
 .\"*********************************************************
 .TP
 .B \-\-route-up cmd
-Execute shell command
+Run command
 .B cmd
 after routes are added, subject to
 .B \-\-route-delay.
 
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.
+.\"*********************************************************
+.TP
+.B \-\-route-pre-down cmd
+Run command
+.B cmd
+before routes are removed upon disconnection.
 
-Note that
 .B cmd
-can be a shell command with multiple arguments.
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+See the "Environmental Variables" section below for
+additional parameters passed as environmental variables.
 .\"*********************************************************
 .TP
 .B \-\-route-noexec
@@ -1691,10 +1707,19 @@ memory available to other applications.
 .\"*********************************************************
 .TP
 .B \-\-up cmd
-Shell command to run after successful TUN/TAP device open
+Run command
+.B cmd
+after successful TUN/TAP device open
 (pre
 .B \-\-user
-UID change).  The up script is useful for specifying route
+UID change).
+
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+The up command is useful for specifying route
 commands which route IP traffic destined for
 private subnets which exist at the other
 end of the VPN connection into the tunnel.
@@ -1714,13 +1739,11 @@ execute as:
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.
 
-Note that
-.B cmd
-can be a shell command with multiple arguments, in which
-case all OpenVPN-generated arguments will be appended
-to
+Note that if
 .B cmd
-to build a command line which will be passed to the shell.
+includes arguments, all OpenVPN-generated arguments will be appended
+to them to build an argument list with which the executable will be
+called.
 
 Typically,
 .B cmd
@@ -1796,12 +1819,20 @@ i.e. the receipt of the first authenticated packet from the peer.
 .\"*********************************************************
 .TP
 .B \-\-down cmd
-Shell command to run after TUN/TAP device close
+Run command
+.B cmd
+after TUN/TAP device close
 (post
 .B \-\-user
 UID change and/or
 .B \-\-chroot
-).  Called with the same parameters and environmental
+).
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+Called with the same parameters and environmental
 variables as the
 .B \-\-up
 option above.
@@ -2029,7 +2060,7 @@ options.
 Become a daemon after all initialization functions are completed.
 This option will cause all message and error output to
 be sent to the syslog file (such as /var/log/messages),
-except for the output of shell scripts and
+except for the output of scripts and
 ifconfig commands,
 which will go to /dev/null unless otherwise redirected.
 The syslog redirection occurs immediately at the point
@@ -2949,20 +2980,29 @@ In the absence of this option, OpenVPN will disconnect a client instance
 upon connection of a new client having the same common name.
 .\"*********************************************************
 .TP
-.B \-\-client-connect script
+.B \-\-client-connect cmd
 Run
-.B script
-on client connection.  The script is passed the common name
+.B command cmd
+on client connection.
+
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+The command is passed the common name
 and IP address of the just-authenticated client
 as environmental variables (see environmental variable section
-below).  The script is also passed
-the pathname of a freshly created temporary file as $1
-(i.e. the first command line argument), to be used by the script
+below).  The command is also passed
+the pathname of a freshly created temporary file as the last argument
+(after any arguments specified in
+.B cmd
+), to be used by the command
 to pass dynamically generated config file directives back to OpenVPN.
 
 If the script wants to generate a dynamic config file
 to be applied on the server when the client connects,
-it should write it to the file named by $1.
+it should write it to the file named by the last argument.
 
 See the
 .B \-\-client-config-dir
@@ -2977,7 +3017,7 @@ returns a non-zero error status, it will cause the client
 to be disconnected.
 .\"*********************************************************
 .TP
-.B \-\-client-disconnect
+.B \-\-client-disconnect cmd
 Like
 .B \-\-client-connect
 but called on client instance shutdown.  Will not be called
@@ -2989,11 +3029,19 @@ successful (0) status returns.
 
 The exception to this rule is if the
 .B \-\-client-disconnect
-script or plugins are cascaded, and at least one client-connect
+command or plugins are cascaded, and at least one client-connect
 function succeeded, then ALL of the client-disconnect functions for
 scripts and plugins will be called on client instance object deletion,
 even in cases where some of the related client-connect functions returned
 an error status.
+
+The
+.B \-\-client-disconnect
+command is passed the same pathname as the corresponding
+.B \-\-client-connect
+command as its last argument. (after any arguments specified in
+.B cmd
+).
 .B 
 .\"*********************************************************
 .TP
@@ -3176,12 +3224,18 @@ and
 .\"*********************************************************
 .TP
 .B \-\-learn-address cmd
-Run script or shell command
+Run command
 .B cmd
 to validate client virtual addresses or routes.
 
 .B cmd
-will be executed with 3 parameters:
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
+Three arguments will be appended to any arguments in
+.B cmd
+as follows:
 
 .B [1] operation \-\-
 "add", "update", or "delete" based on whether or not
@@ -3215,15 +3269,20 @@ policies with regard to the client's high-level common name,
 rather than the low level client virtual addresses.
 .\"*********************************************************
 .TP
-.B \-\-auth-user-pass-verify script method
+.B \-\-auth-user-pass-verify cmd method
 Require the client to provide a username/password (possibly
 in addition to a client certificate) for authentication.
 
-OpenVPN will execute
-.B script
-as a shell command to validate the username/password
+OpenVPN will run
+.B command cmd
+to validate the username/password
 provided by the client.
 
+.B cmd
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
 If
 .B method
 is set to "via-env", OpenVPN will call
@@ -4451,7 +4510,7 @@ username/password.  It is always cached.
 .\"*********************************************************
 .TP
 .B \-\-tls-verify cmd
-Execute shell command
+Run command
 .B cmd
 to verify the X509 name of a
 pending TLS connection that has otherwise passed all other
@@ -4464,16 +4523,16 @@ test).
 .B cmd
 should return 0 to allow the TLS handshake to proceed, or 1 to fail.
 
-Note that
 .B cmd
-is a command line and as such may (if enclosed in quotes) contain
-whitespace separated arguments.  The first word of
-.B cmd
-is the shell command to execute and the remaining words are its
-arguments.
+consists of a path to script (or executable program), optionally
+followed by arguments. The path and arguments may be single- or double-quoted
+and/or escaped using a backslash, and should be separated by one or more spaces.
+
 When
 .B cmd
-is executed two arguments are appended, as follows:
+is executed two arguments are appended after any arguments specified in
+.B cmd
+, as follows:
 
 .B cmd certificate_depth subject
 
@@ -6145,7 +6204,7 @@ access any machine on the 10.0.1.0/24 subnet
 over the secure tunnel (or vice versa).
 
 In a production environment, you could put the route command(s)
-in a shell script and execute with the
+in a script and execute with the
 .B \-\-up
 option.
 .\"*********************************************************
diff --git a/src/openvpn/options.c b/src/openvpn/options.c
index 076b229..5da2eb6 100644
--- a/src/openvpn/options.c
+++ b/src/openvpn/options.c
@@ -166,7 +166,7 @@ static const char usage_message[] =
   "                  Set n=\"infinite\" to retry indefinitely.\n"
   "--float         : Allow remote to change its IP address/port, such as through\n"
   "                  DHCP (this is the default if --remote is not used).\n"
-  "--ipchange cmd  : Execute shell command cmd on remote ip address initial\n"
+  "--ipchange cmd  : Run command cmd on remote ip address initial\n"
   "                  setting or change -- execute as: cmd ip-address port#\n"
   "--port port     : TCP/UDP port # for both local and remote.\n"
   "--lport port    : TCP/UDP port # for local (default=%d). Implies --bind.\n"
@@ -223,8 +223,8 @@ static const char usage_message[] =
   "                  adding routes (may be 0).  If not specified, routes will\n"
   "                  be added immediately after tun/tap open.  On Windows, wait\n"
   "                  up to w seconds for TUN/TAP adapter to come up.\n"
-  "--route-up cmd  : Execute shell cmd after routes are added.\n"
-  "--route-pre-down cmd  : Execute shell cmd before routes are removed.\n"
+  "--route-up cmd  : Run command cmd after routes are added.\n"
+  "--route-pre-down cmd : Run command cmd before routes are removed.\n"
   "--route-noexec  : Don't add routes automatically.  Instead pass routes to\n"
   "                  --route-up script using environmental variables.\n"
   "--route-nopull  : When used with --client or --pull, accept options pushed\n"
@@ -311,17 +311,17 @@ static const char usage_message[] =
 #endif
   "--mlock         : Disable Paging -- ensures key material and tunnel\n"
   "                  data will never be written to disk.\n"
-  "--up cmd        : Shell cmd to execute after successful tun device open.\n"
+  "--up cmd        : Run command cmd after successful tun device open.\n"
   "                  Execute as: cmd tun/tap-dev tun-mtu link-mtu \\\n"
   "                              ifconfig-local-ip ifconfig-remote-ip\n"
   "                  (pre --user or --group UID/GID change)\n"
   "--up-delay      : Delay tun/tap open and possible --up script execution\n"
   "                  until after TCP/UDP connection establishment with peer.\n"
-  "--down cmd      : Shell cmd to run after tun device close.\n"
+  "--down cmd      : Run command cmd after tun device close.\n"
   "                  (post --user/--group UID/GID change and/or --chroot)\n"
-  "                  (script parameters are same as --up option)\n"
-  "--down-pre      : Call --down cmd/script before TUN/TAP close.\n"
-  "--up-restart    : Run up/down scripts for all restarts including those\n"
+  "                  (command parameters are same as --up option)\n"
+  "--down-pre      : Run --down command before TUN/TAP close.\n"
+  "--up-restart    : Run up/down commands for all restarts including those\n"
   "                  caused by --ping-restart or SIGUSR1\n"
   "--user user     : Set UID to user after initialization.\n"
   "--group group   : Set GID to group after initialization.\n"
@@ -452,7 +452,7 @@ static const char usage_message[] =
   "                  the authenticated username as the common name,\n"
   "                  rather than the common name from the client cert.\n"
   "--auth-user-pass-verify cmd method: Query client for username/password and\n"
-  "                  run script cmd to verify.  If method='via-env', pass\n"
+  "                  run command cmd to verify.  If method='via-env', pass\n"
   "                  user/pass via environment, if method='via-file', pass\n"
   "                  user/pass via temporary file.\n"
   "--opt-verify    : Clients that connect with options that are incompatible\n"
@@ -464,8 +464,8 @@ static const char usage_message[] =
   "--client-to-client : Internally route client-to-client traffic.\n"
   "--duplicate-cn  : Allow multiple clients with the same common name to\n"
   "                  concurrently connect.\n"
-  "--client-connect cmd : Run script cmd on client connection.\n"
-  "--client-disconnect cmd : Run script cmd on client disconnection.\n"
+  "--client-connect cmd : Run command cmd on client connection.\n"
+  "--client-disconnect cmd : Run command cmd on client disconnection.\n"
   "--client-config-dir dir : Directory for custom client config files.\n"
   "--ccd-exclusive : Refuse connection unless custom client config is found.\n"
   "--tmp-dir dir   : Temporary directory, used for --client-connect return file and plugin communication.\n"
@@ -475,7 +475,7 @@ static const char usage_message[] =
   "--tcp-queue-limit n : Maximum number of queued TCP output packets.\n"
   "--tcp-nodelay   : Macro that sets TCP_NODELAY socket flag on the server\n"
   "                  as well as pushes it to connecting clients.\n"
-  "--learn-address cmd : Run script cmd to validate client virtual addresses.\n"
+  "--learn-address cmd : Run command cmd to validate client virtual addresses.\n"
   "--connect-freq n s : Allow a maximum of n new connections per s seconds.\n"
   "--max-clients n : Allow a maximum of n simultaneously connected clients.\n"
   "--max-routes-per-client n : Allow a maximum of n internal routes per client.\n"
@@ -609,7 +609,7 @@ static const char usage_message[] =
   "--askpass [file]: Get PEM password from controlling tty before we daemonize.\n"
   "--auth-nocache  : Don't cache --askpass or --auth-user-pass passwords.\n"
   "--crl-verify crl ['dir']: Check peer certificate against a CRL.\n"
-  "--tls-verify cmd: Execute shell command cmd to verify the X509 name of a\n"
+  "--tls-verify cmd: Run command cmd to verify the X509 name of a\n"
   "                  pending TLS connection that has otherwise passed all other\n"
   "                  tests of certification.  cmd should return 0 to allow\n"
   "                  TLS handshake to proceed, or 1 to fail.  (cmd is\n"