aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2023-11-18 09:47:41 +0100
committerMattias Andrée <maandree@kth.se>2023-11-18 09:47:41 +0100
commit6ce43bc074547933ba43ffe7bbcc7ba1f324c727 (patch)
tree7ec35476a806dbcef00e5afee041cb4e416041ac
parentFix reported usage syntax (diff)
downloadsshexec-6ce43bc074547933ba43ffe7bbcc7ba1f324c727.tar.gz
sshexec-6ce43bc074547933ba43ffe7bbcc7ba1f324c727.tar.bz2
sshexec-6ce43bc074547933ba43ffe7bbcc7ba1f324c727.tar.xz
Add man page
Signed-off-by: Mattias Andrée <maandree@kth.se>
-rw-r--r--sshexec.1141
1 files changed, 133 insertions, 8 deletions
diff --git a/sshexec.1 b/sshexec.1
index 905c656..b734c5b 100644
--- a/sshexec.1
+++ b/sshexec.1
@@ -6,8 +6,8 @@ sshexec - run a command through ssh(1) with normal command syntax
.SH SYNOPSIS
.B sshexec
.RB [ {
-.RI [\fBssh=\fP ssh-command ]
-.RI [\fBdir=\fP directory ]
+.RI [\fBssh= ssh-command ]
+.RI [\fBdir= directory ]
.BR } ]
[ssh-option] ...\,
.I destination
@@ -15,13 +15,115 @@ sshexec - run a command through ssh(1) with normal command syntax
.RI [ argument ]\ ...\,
.SH DESCRIPTION
-TODO
+The
+.B sshexec
+utility is a wrapper for SSH that makes it easy to run commands
+directly in the SSH command.
+
+.B sshexec
+passes any argument after
+.B }
+to
+.I ssh-command
+.RB ( ssh
+if not specified), and only modifies
+.I command
+.RB [ argument ]\ ...\,
+and inserts extra arguments after
+.I destination
+(it may also add a
+.B --
+argument immediately before
+.IR destination )
+to cause the remote shell it change working directory to
+.IR directory ,
+if specified, and execute the provided
+.I command
+and
+.IR argument s
+as a regular command rather than as shell code joined
+by together by spaces.
.SH OPTIONS
-TODO
+.B sshexec
+options may be placed at the very beginning enclosed with
+the arguments
+.B {
+and
+.BR } .
+.B sshexec
+options, if any, shall be placed in the same
+.B {
+.BR } -group.
+Any other option will be passed as is to the
+.BR ssh (1)
+utility or
+.IR ssh-command .
+The
+.B sshexec
+utility has a build it list of options recognised by the
+.BR ssh (1)
+utility and will not allow anything matching this list.
+The
+.B sshexec
+utility does not allow mixing options and operands: no
+option may be placed after
+.IR destination ,
+such options will be treated as the
+.I command
+or an
+.IR argument .
+.PP
+The following
+.B sshexec
+options are supported:
+.TP
+.BI ssh= ssh-command
+Instead of looking for
+.B ssh
+in
+.IR PATH ,
+the
+.B sshexec
+utility shall use
+.IR ssh-command ,
+which it will look for in
+.I PATH
+if it is only a file name (does not contain a slash
+.RB ( / )).
+.TP
+.BI dir= directory
+In the remote, change working directory to
+.I directory
+before executing
+.IR command .
.SH OPERANDS
-TODO
+The following operands are supported:
+.TP
+.I destination
+This operand is passed as is (without validation) to the
+.BR ssh (1)
+utility. The
+.BR ssh (1)
+utility will expect it the be either in the form
+.RI [ user\fP\fB@ ] hostname
+or in the form
+.BR ssh:// [\fIuser @ ]\fIhostname\fP[ : \fIport\fP].
+.TP
+.IR command \ [ argument ]\ ...\,
+Whereas the
+.BR ssh (1)
+utility would simply join the
+.I command
+and
+.I argument
+arguments with a space between each of them as pass it
+to the remote shell for execution, the
+.B 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.
.SH STDIN
The
@@ -40,9 +142,13 @@ Default. See to the Base Definitions volume of POSIX.1-2017, Section 8.3, Other
This environment variable affects where the
.B sshexec
utility can find the
-.B ssh
+.BR ssh (1)
utility or
.IR ssh-command .
+.PP
+Other environment variables may affect the execution of the
+.BR ssh (1)
+utility.
.SH ASYNCHRONOUS EVENTS
Default.
@@ -67,7 +173,7 @@ None.
The
.B sshexec
utility exits with the exit status of the
-.B ssh
+.BR ssh (1)
utility or with 255 if an error occurred.
.SH CONSEQUENCES OF ERRORS
@@ -86,7 +192,26 @@ None.
None.
.SH BUGS
-None.
+The remote shell must be sufficiently similar to
+.BR sh (1posix).
+Namely, it must support the
+.B cd
+builtin command and the commands
+.B exec
+and
+.B printf
+is expected by POSIX. Additionally, it must support
+.BR \(dq$(\ )\(dq ,
+.BR \(aq\ \(aq ,
+and
+.BR && ,
+and argument separation with the SP character.
+The remote shell must also not treat any alphanumeric
+character, underscore
+.RB ( _ )
+or slash
+.RB ( / )
+as special characters.
.SH FUTURE DIRECTIONS
None.