Invoke-SSH Cmdlet

Parameters   Output Objects   Configuration Settings  

The Invoke-SSHcmdlet is used to remotely execute a command on an SSH server.

Syntax

Invoke-SSH [parameters]

Remarks

This cmdlet establishes a Secure Shell (SSH) connection to a server and starts up the user's default shell. Using the cmdlet is very simple. The destination is specified by Server, and both user (default) and public-key authentication is supported. In order to use user authentication, set the Credential parameter. For public-key authentication, first set the AuthMode parameter to 'publickey'. Then set the UserName parameter and specify the certificate with CertStoreType, CertStore, and CertSubject. The cmdlet can also be used by specifying an SSH connection created from the Connect-SSH cmdlet.

Command contains the command you wish to execute on the remote machine. The output of the command is returned in one or more Shell objects. The exit code from the command that is executed will be returned in the LastExitCode variable.

The cmdlets support pipeline input for some of their parameters. Prebuilding an object and piping it to the cmdlet is very useful, but should be used with caution to prevent security conflicts. Steps have been taken to decrease the risk of a possibly accidental pipe to the cmdlet, for instance, the Credential parameter cannot be piped to the cmdlet and must be specified manually.

# execute a command using user authentication.
Invoke-SSH -server SSH_SERVER -credential $mycred -command ls
# execute a command using public key authentication.
Invoke-SSH -server SSH_Server -user myusername -AuthMode publickey -CertStoreType pemkey -CertStore C:\mypath\id_rsa -CertPassword "password" -CertSubject "*" -command ls
# execute a command using an already established SSH connection from the Connect-SSH cmdlet
Invoke-SSH $ssh_connection -command ls
# execute a command using raw shell access instead of SExec
Invoke-SSH -server SSH_SERVER -credential $mycred -command 'ls -l' -EOL "`n" -ShellPrompt = '$ '

Connection Handling

This cmdlet supports persistent connections through the Connection parameter. To establish a new SSH connection, use the Connect-SSH cmdlet. To close the connection, use the Disconnect-SSH cmdlet.