ssh.utils (version 1.0)

run.remote: Functions to run commands remotely via ssh and capture output.

Description

run.withwarn - Evaluates the expression (e.g. a function call) and returns the result with additional atributes:

• num.warnings - number of warnings occured during the evaluation
• last.message - the last warning message

Otherwise, run.withwarn is similar to base::supressWarnings

run.remote - Runs the command locally or remotely using ssh.

Usage

run.withwarn(expr)
run.remote(cmd, remote = "", intern = T, stderr.redirect = T, verbose = F)

Arguments

expr

Expression to be evaluated.

cmd

Command to run. If run locally, quotes should be escaped once. If run remotely, quotes should be escaped twice.

remote

Remote machine specification for ssh, in format such as user@server that does not require interactive password entry. For local execution, pass an empty string "" (default).

intern

Useful for debugging purposes: if there's an error in the command, the output of the remote command is lost. Re-running with intern=FALSE causes the output to be printed to the console. Normally, we want to capture output and return it.

stderr.redirect

When TRUE appends 2>&1 to the command. Generally, one should use that to capture STDERR output with intern=TRUE, but this should be set to FALSE if the command manages redirection on its own.

verbose

When TRUE prints the command.

Value

run.remote returns a list containing the results of the command execution, error codes and messages.

• cmd.error - flag indicating if a warning was issued because command exited with non-zero code
• cmd.out - the result of the command execution. If there was no error, this contains the output as a character array, one value per line, see system. If there was an error (as indicated by cmd.error), this most likely contains the error message from the command itself. The elapsed.time attribute contains the elapsed time for the command in seconds.
• warn.msg - the warning message when cmd.error is TRUE.

Warnings are really errors here so the error flag is set if there are warnings.Additionally, cmd.out has the elapsed.time, num.warnings and, if the number of warnings is greater than zero, last.warning attributes.

Details

In run.remote the remote commands are enclosed in wrappers that allow to capture output. By default stderr is redirected to stdout. If there's a genuine error, e.g., the remote command does not exist, the output is not captured. In this case, one can see the output by setting intern to FALSE. However, when the command is run but exits with non-zero code, run.remote intercepts the generated warning and saves the output.

The remote command will be put inside double quotes twice, so all quotes in cmd must be escaped twice: \\". However, if the command is not remote, i.e., remote is NULL or empty string, quotes should be escaped only once.

If the command itself redirects output, the stderr.redirect flag should be set to FALSE.

Examples

## Not run: 
# ## Error handling:
# remote = ""
# command = "ls /abcde"
# res <- run.remote(cmd=command, remote=remote)
# if (res$cmd.error)
# {
#    stop(paste(paste(res$cmd.out, collapse="\n"), res$warn.msg, sep="\n"))
# }
# # Error: ls: /abcde: No such file or directory
# # running command 'ls /abcde  2>&1 ' had status 1
# 
# ## Fetching result of a command on a remote server
# 
# # Get the file size in bytes
# res <- run.remote("ls -la myfile.csv | awk '{print \\$5;}'", remote = "me@myserver")
# res
# # $cmd.error
# # [1] FALSE
# #
# # $cmd.out
# # [1] "42"
# # attr(,"num.warnings")
# # [1] 0
# # attr(,"elapsed.time")
# # elapsed
# # 1.063
# #
# # $warn.msg
# # NULL
# 
# file.length <- as.integer(res$cmd.out)
# ## End(Not run)