PowerShell cmdlet for Porthole

Remotely control Linux Raspberry Pi from Windows PowerShell.

Porthole cmdlet for PowerShell provides all the functionality that a user has when using the graphical or CLI interface to Porthole.

Common tasks:

  • Automate scripts against a device or devices
  • Open a terminal from Windows PowerShell
  • Manage local portforwarding routes to remote devices
  • Query device status

For the impatient, here is the basic concept:

# Connect the local instance of Porthole to your Dataplicity account
PS > Register-Porthole
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

# Reboot a Raspberry Pi remotely
PS > Restart-PortholeDevice -Device 12345678-1234-1234-1234-123456789000
Rebooting device...
True

# Run a command on a Raspberry Pi remotely and get the result
PS > Invoke-PortholeCommand -Device 12345678-1234-1234-1234-123456789000 ^
                            "cat /proc/cpuinfo| grep Hardware"
StandardOutput
- -------------
Hardware        : BCM283...

# Forward port SSH (22) on a remote device to port 1022 on your local PC
PS> Add-PortholeForward -Device 12345678-1234-1234-1234-123456789000 ^ 
                        -LocalPort 1022 -RemotePort 22
Creating new forward...

DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

# Now you can SSH to your remote device by pointing # your favourite SSH 
# client to port 127.0.0.1:1022.

Device management

Get-PortholeDevices

Returns a list of all available devices.

Syntax

Get-PortholeDevices

Example usage

PS> Get-PortholeDevices
Checking devices...

DeviceName   : Boxy McBoxface
DeviceId     : 12345678-1234-1234-1234-123456789000
DeviceStatus : Online
MachineType  : Raspberry Pi 3 Model B
AgentVersion : 0.4.29

DeviceName   : debian1
DeviceId     : 12345678-1234-1234-1234-123456789001
DeviceStatus : Offline
MachineType  : Other linux device
AgentVersion : 0.4.29

DeviceName   : demo1
DeviceId     : 12345678-1234-1234-1234-123456789002
DeviceStatus : Online
MachineType  : Other linux device
AgentVersion : 0.4.27a2

Outputs

ParameterDescription
Device nameUser specified device name as defined in the attached Dataplicity account.
DeviceUnique Device API ID for the device.
Machine typeFriendly description of device type.

Examples include:
"Raspberry Pi Model Compute Module"
"Raspberry Pi Model B+"
"Other linux device"
Status"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.
Agent versionDataplicity Agent version reported by this device.

Example: 0.4.29

Get-PortholeDeviceStatus

Query the online status of all registered devices.

The "Device" parameter may be used to filter the search to a particular device.
Syntax

Get-PortholeDeviceStatus [-Device <String>]

Example usage

PS> Get-PortholeDeviceStatus
Checking devices...

DeviceName                 DeviceId                             DeviceStatus
- ---------                 - -------                             - -----------
Boxy McBoxface             12345678-1234-1234-1234-123456789000 Online
debian1                    12345678-1234-1234-1234-123456789001 Offline
demo1                      12345678-1234-1234-1234-123456789002 Online

Outputs

ParameterDescription
Device nameUser specified device name as defined in the attached Dataplicity account.
DeviceUnique Device API ID for the device.
Status"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.

Invoke-PortholeCommand

Remotely execute a command against a device.

Syntax

Invoke-PortholeCommand -Device <String> -Command <String>

Inputs

ParameterDescription
DeviceUnique Device API ID for the device.
CommandRemote command to execute.
Example: "cat /proc/cpuinfo"

Example usage

PS > Invoke-PortholeCommand -Device 12345678-1234-1234-1234-123456789000 ^
                            "cat /proc/cpuinfo| grep Hardware"
StandardOutput
- -------------
Hardware        : BCM283...

Outputs

ParameterDescription
Device nameUser specified device name as defined in the attached Dataplicity account.
DeviceUnique Device API ID for the device.
Status"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.

Invoke-PortholeDeviceTerminal

Opens an "SSH-like" terminal to a remote device from the PowerShell command prompt.

Syntax

Invoke-PortholeDeviceTerminal-Device <String>

Inputs

ParameterDescription
DeviceUnique Device API ID for the device.

Example usage

PS> Invoke-PortholeDeviceTerminal -Device 12345678-1234-1234-1234-123456789000

Restart-PortholeDevice

Remotely reboot a device.

Syntax

Restart-PortholeDevice -Device <String>

Inputs

ParameterDescription
DeviceUnique Device API ID for the device.

Example usage

PS> Restart-PortholeDevice-Device 12345678-1234-1234-1234-123456789000
Rebooting device...
True

Session management

Get-PortholeProfile

Returns the username for the currently attached Dataplicity account.

Syntax

Get-PortholeProfile

Example usage

PS> Get-PortholeProfile
Getting profile...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Outputs

ParameterDescription
UsernameUsername of the Dataplicity account attached to the local instance of Porthole.

Register-Porthole

Attaches the local instance of Porthole to a Dataplicity account.

This command does not accept parameters but will instead prompt for username, password, and two-factor security code (if required).

Syntax

Register-Porthole

Example usage

PS> Register-Porthole
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Update-PortholeToken

Updates the authorisation token used by the local instance of Porthole.

This function is probably not required if you are using Register-Porthole to request a Token with a username and password, but could be useful in production applications.

Syntax

Update-PortholeToken -Token <String>

Example usage

PS> Update-PortholeToken -Token <token>
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Unregister-Porthole

Detaches the local instance of Porthole from Dataplicity. The Porthole system service will be restarted and all open routes will be terminated.

Syntax

Unregister-Porthole

Example usage

PS> Unregister-Porthole
Are you sure you want to log out? [yes/no] [y/n]
y
Logging out...
Logged out successfully.

Port forwarding configuration

Add-PortholeForward

Inserts a new port forwarding entry to redirect a TCP port on a Dataplicity-enabled remote device to localhost.

Syntax

Add-PortholeForward -Device <String> -LocalPort <int> -RemotePort <int> [-IsLocalOnly <bool>]

Inputs

ParameterDescription
Device nameUser specified device name as defined in the attached Dataplicity account.
Local portLocal TCP port which is listening for connections to forward to the remote host.
Is local only"Yes" if the local port is available to localhost only.

"No" if the local port is listening on all local interfaces (and therefore is accessible from the local network).
DeviceUnique Device API ID for the device.
Remote portRemote TCP port where socket traffic on the local TCP port is to be redirected. Commonly '22' for SSH, '5901' for VNC.

Example usage

PS> Add-PortholeForward -Device 12345678-1234-1234-1234-123456789000 -LocalPort 1022 -RemotePort 22
Creating new forward...

DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

Get-PortholeForwards

Returns a list of all port forwards configured in the local instance of Porthole.

Syntax

Get-PortholeForwards

Example usage

PS> Get-PortholeForwards
DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

Outputs

ParameterDescription
Device nameUser specified device name as defined in the attached Dataplicity account.
Local portLocal TCP port which is listening for connections to forward to the remote host.
Is local only"Yes" if the local port is available to localhost only.

"No" if the local port is listening on all local interfaces (and therefore is accessible from the local network).
DeviceUnique Device API ID for the device.
Remote portRemote TCP port where socket traffic on the local TCP port is to be redirected. Commonly '22' for SSH, '5901' for VNC.

Remove-PortholeForward

Removes a existing port forwarding entry from the local instance of Porthole.

Syntax

Remove-PortholeForward -LocalPort <int>

Inputs

ParameterDescription
Local portLocal TCP port which is listening for connections to forward to the remote host.

Example usage

PS> Remove-PortholeForward -LocalPort 1022
RemovedForwardsCount
- -------------------
                   1