From d62859980c30362b36b7338fc99fe76e4ecb2cbd Mon Sep 17 00:00:00 2001 From: "Jonathan K. Bullard" Date: Sat, 31 Mar 2012 07:47:34 -0400 Subject: 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 Acked-by: Gert Doering Message-Id: CAEsd45RkyJw6yUk1Jwkip70HkCjKYoU+V=do3N7SH7JOaHBZdw@mail.gmail.com URL: http://article.gmane.org/gmane.network.openvpn.devel/6194 Signed-off-by: David Sommerseth --- doc/openvpn.8 | 155 ++++++++++++++++++++++++++++++++++---------------- src/openvpn/options.c | 26 ++++----- 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" -- cgit