diff options
Diffstat (limited to '')
| -rw-r--r-- | README | 215 |
1 files changed, 196 insertions, 19 deletions
@@ -2,27 +2,32 @@ NAME sshexec - run a command through ssh(1) with normal command syntax SYNOPSIS - sshexec [{ [ssh=ssh-command] [dir=directory] }] [ssh-option] ... - destination command [argument] ... + sshexec [{ [ssh=ssh-command] [dir=directory] [cd=(strict|lax)] + [[fd]{>,>>,>|,<,<>}[&]=file] [asis=asis-marker + [nasis=asis-count]] }] [ssh-option] ... destination + command [argument] ... DESCRIPTION The sshexec utility is a wrapper for SSH that makes it easy to - run commands directly in the SSH command. + run commands directly in the SSH command line. sshexec passes any argument after } to ssh-command (ssh if not - specified), and only modifies command [argument] ... and inserts - extra arguments after destination (it may also add a -- argument - immediately before destination) to cause the remote shell it - change working directory to directory, if specified, and execute - the provided command and arguments as a regular command rather - than as shell code joined by together by spaces. + specified), but it rewrites command and the arguments into one + argument that can be passed into ssh(1) to describe each argument + as a separate argument. It may also rewrite destination to remove + information that is not supported by ssh(1) and insert extra + arguments after it (it may also add a -- argument immediately + before destination) to cause the remote shell to change working + directory to directory, if specified, and execute the provided + command and arguments as a regular command rather than as shell + code joined together by spaces. OPTIONS sshexec options may be placed at the very beginning enclosed with the arguments { and }. sshexec options, if any, shall be placed in the same { }-group. Any other option will be passed as is to the ssh(1) utility or ssh-command. The sshexec utility - has a build it list of options recognised by the ssh(1) utility + has a built-in list of options recognised by the ssh(1) utility and will not allow anything matching this list. The sshexec utility does not allow mixing options and operands: no option may be placed after destination, such options will be treated @@ -39,22 +44,194 @@ OPTIONS In the remote, change working directory to directory before executing command. + cd=strict + Fail without executing the command if it's not possible + to set directory as the remote working directory. + + cd=lax + Continue (but warn) executing the command even if it's + not possible to set directory as the remote working + directory. + + [fd]>=file + After changing working directory (assuming one is + specified), create or truncate the specified file and + open it for writing, using file descriptor number fd. + (Default fd is 1 (standard output).) + + [fd]>>=file + After changing working directory (assuming one is + specified), create the specified file if it does not + exist and open it for writing in append-mode, using + file descriptor number fd. (Default fd is 1 + (standard output).) + + [fd]>|=file + After changing working directory (assuming one is + specified), create the specified file, but fail if it + already exists, and open it for writing, using file + descriptor number fd. (Default fd is 1 (standard + output).) + + [fd]<=file + After changing working directory (assuming one is + specified), open the specified file, for reading, using + file descriptor number fd. (Default fd is 0 (standard + input).) + + [fd]<>=file + After changing working directory (assuming one is + specified), open the specified file, for reading and + writing, creating it if it does not already exist, + using file descriptor number fd. (Default fd is 0 + (standard input).) + + [fd]{>,>>,>|}&=file + Duplicate the file descriptor fd giving the new file + descriptor the number file. (Default fd is 1 (standard + output).) + + [fd]{>,>>,>|}&=- + Close the file descriptor fd. (Default fd is 1 + (standard output).) + + [fd]{<,<>}&=file + Duplicate the file descriptor fd giving the new file + descriptor the number file. (Default fd is 0 (standard + input).) + + [fd]{<,<>}&=- + Close the file descriptor fd. (Default fd is 0 + (standard input).) + + asis=asis-marker + Any argument equal to asis-marker will be skipped over + and instead the next argument (regardless of whether + it too is equal to asis-marker) will be interpreted as a + raw shell code string that shall be inserted without + escaping. + + nasis=asis-count + If specified, asis-marker shall only have its specified + effect up to asis-count times. + OPERANDS The following operands are supported: destination - This operand is passed as is (without validation) to - the ssh(1) utility. The ssh(1) utility will expect it - the be either in the form [user@]hostname or in the - form ssh://[user@]hostname[:port]. + The destination to connect and log into. It shall be + either in the form [user@]hostname[:directory] or in the + form ssh[exec]://[user@]hostname[:port][/directory]. + + user shall be the name of the remote user. If not + specified, the name of the local user running the + utility will be used. + + hostname shall be the address to the remote machine. + + port shall be the port or service name for the port + to connect to on the remote machine. + + directory shall be the directory to change the remote + working directory. This is an alternative (with the + exact same behaviour) to the dir option and cannot be + combined with it. command [argument] ... Whereas the ssh(1) utility would simply join the command and argument arguments with a space between each of - them as pass it to the remote shell for execution, the - sshexec utility forces the remote shell to treat each - of the as separate arguments and cause the shell to - executing them as a non-builtin command. + them and pass the result to the remote shell for execution, + the sshexec utility forces the remote shell to treat each + of them as a separate argument and causes the shell to + execute them as a non-builtin command. + + command must not contain an equals sign (=) or be just + a dash ("-"). + +ENVIRONMENT VARIABLES + The following environment variables affect the execution of + sshexec: + + PATH + Default. See to the Base Definitions volume of POSIX.1-2017, + Section 8.3, Other Environment Variables. This environment + variable affects where the sshexec utility can find the + ssh(1) utility or ssh-command. + + SSHEXEC_SSH + If set and non-empty, it overrides the default value of + ssh-command from ssh to the value of the variable. + + SSHEXEC_OPTS_NO_ARG + List of options that sshexec shall interpret as ssh(1) + options that do not have any argument. (Default is + 46AaCfGgKkMNnqsTtVvXxYy, meaning the options -4, -6, -A, + -a, -C, -f, -G, -g, -K, -k, -M, -N, -n, -q, -s, -T, -t, + -V, -v, -X, -x, -Y, and -y.) + + SSHEXEC_OPTS_ARG + List of options that sshexec shall interpret as ssh(1) + options that have an argument. (Default is + BbcDEeFIiJLlmOoPpQRSWw, meaning the options -B, -b, -c, + -D, -E, -e, -F, -I, -i, -J, -L, -l, -m, -O, -o, -P, -p, + -Q, -R, -S, -W, and -w.) + + SSHEXEC_OPTS_OPT_ATTACHED_ARG + List of options that sshexec shall interpret as ssh(1) + options that have an argument only if there are + additional characters after the option character in the + same command line argument. (Default is the empty + string, meaning no options.) + + SSHEXEC_OPTS_OPT_ARG + List of options that sshexec shall interpret as ssh(1) + options that have an argument if there are additional + characters after the option character in the same + command line argument or if argument is followed + directly by another argument which does not start with + a dash (-). (Default is the empty string, meaning no + options.) + + SSHEXEC_LONG_OPTS_NO_ARG + Space-separated list of long options that sshexec shall + interpret as ssh(1) options that do not have any + argument unless it is followed directly by an equals + sign (=) in the same command line argument. Options + that do not start with two dashes (--) are silently + ignored. (Default is the empty string, meaning no + options.) + + SSHEXEC_LONG_OPTS_ARG + Space-separated list of long options that sshexec shall + interpret as ssh(1) options that have an argument that + must either be specified in the next command line + argument or after an equals sign (=) the shall directly + follow the option string in the same command line + argument. Options that do not start with two dashes + (--) are silently ignored. (Default is the empty string, + meaning no options.) + + SSHEXEC_LONG_OPTS_OPT_ARG + Space-separated list of long options that sshexec shall + interpret as ssh(1) options that have an argument if + it is the option string is is directly followed by + equals sign (=) in the same command line argument or if + argument is followed directly by another argument which + does not start with a dash (-). Options that do not + start with two dashes (--) are silently ignored. + (Default is the empty string, meaning no options.) + + Other environment variables may affect the execution of the + ssh(1) utility. + +BUGS + The remote shell must be sufficiently similar to sh(1posix). + Namely, it must support the cd builtin command and the commands + exec and printf is expected by POSIX. Additionally, it must + support "$( )", ' ', and &&, and argument separation with the + SP character. The remote shell must also not treat any + alphanumeric character, underscore (_) or slash (/) as special + characters. SEE ALSO - ssh(1) + ssh(1), sshcd(1) |