SSH Remote

SSH Remote is an app that allows you to easily bind ssh commands to simple buttons.

Project Summary

Easy to set-up buttons supporting single or continuous commands or even entire scripts.
Multiple device profiles. Each target device has its own set of parameters.
Optionally, stored credentials in the form of either password or an rsa key pair. Storing the credentials is optional, for improved security you can reenter your credentials everytime you connect to a device.
Devices are pre-customizable and can display a custom logo. See the device file and button file customization for more information.
Simple permission concept: An admin mode allows modifications to devices and buttons, while the standard user can only “push the buttons”. You are able to set a separate password for both accounts!
A preprocessor can alter the output or help automate various tasks.

Device File

An SSH Remote device file is used to predefine the look and feel of a target device configured in the app. It is also the place to specify additional resources or a color scheme for your device. During the device configuration, you download an image file for a logo or script files from an online source.

Please note that everything defined in the device file is only downloaded once during creation and optionally on every device configuration change. There are no automatic updates and thus, changes in the device file might never reach your app, if you do not apply it manually.

The file is a text file with a simple format: every line is interpreted as a single item and the format of a line is as follows:

[Resource type]<Tab>[Resource path]

Please note: except for the separator tabs, no tab character (‘\t’) may be included in the file.

[Resource type] is the type of resource specified. It may only be one of the following values
- logo
  - [Resource path] specifies a logo file that will be displayed everytime this device is selected in the app. This item may only be specified once.
- init
  - [Resource path] specifies a script file with commands that will be executed once during device creation. This is useful for setting up firewall rules on the device or similiar configuration tasks. Of special interest is accepting SSH Remotes public key, if the key authentification method is used. In this case, this script file is the place to register the key on the target device. You may use the “$PUBLIC_KEY$” placeholder in the script file, which will be expanded to the unique public key used to connect to this specific device by the preprocessor. This item may only be specified once.
- buttons
  - [Resource path] specifies a button file which defines the starting set of buttons. Of course these buttons can later be added to or removed from using the normal operations of the app. Please see the link for a definition of the button file format. This item may only be specified once.
- script
  - [Resource path] specifies a script file to be downloaded to the app in order to be used as a script button. Please note that at this time, specifying a script file here is the only way to make it available to the app. This item may be specified multiple times.
- color1
  - [Resource path] is a color code in the format “#RRGGBB” which is used as the apps primary color when this device is selected. If you do not specify this or use a wrong format, the fallback Firesource color theme will be used.
- color2
  - [Resource path] is a color code in the format “#RRGGBB” which is used as the apps secondary color when this device is selected. If you do not specify this or use a wrong format, the fallback Firesource color theme will be used.
- color2
  - [Resource path] is a color code in the format “#RRGGBB” which is used as the apps accent color when this device is selected. If you do not specify this or use a wrong format, the fallback Firesource color theme will be used.
[Resource path] is the path to the resource file defined by [Resource type]. Please note, that this is a relative path from the current location and sub-paths are not allowed.
An example for a valid enty is

logo	firesource.png

If the device file is located at www.example.com/sshremote/mydevice.dev, then the logo file will be searched here: www.example.com/sshremote/firesource.png

An example for an invalid entry is

logo	logos/firesource.png

An example file might look like this:

logo	firesource.png
init	initfile.sh
script	myScript.sh
buttons	yayButtons.but

Button File Format

An SSH Remote button file is used to preconfigure buttons as part of the device file deployment. With this, you can quickly and easily define a set of buttons.

The format is similar to the device file: Each line in the file stands for one button and is formatted like this:

[Button name]<Tab>[Button command or script file]<Tab>[Button type]

Please note:
except for the separator tabs, no tab character (‘\t’) may be included in the file.

[Button name] is the name that will appear on the Button. It should be sufficiently short.
- Example: “Off”
[Button command or script file] is either the raw command that will be executed or the name of a script file. It is only interpreted as a script file if the button type is “Script” (see below). In commands or scripts, the preprocessor can be used.
- Example: “Set-Light -Color Black”
[Button type] can be one of the following:
- SingleCommand
  - A single command will be executed. After the command has been executed and the output collected, the connection will be severed.
- ShellCommand
  - A single command will be executed in shell mode. After the command has been executed, the connection will not be severed until either 10 minutes of silence have passed or the user terminates the command manually.
- Script
  - A script file will be loaded and the commands within will be executed on the target system. After the last command has been executed, the connection will be severed. In this case and this case only, the [Button command or script file] field will be interpreted as the name of the script file to load.
  - No subfolders or paths are allowed. This only references the name of a script file downloaded via the device file.

An example file that uses a fictional “Set-Light” command on a rasberry PI responsible for mood lighting might look like this:

Off	Set-Light -Color Black	SingleCommand
Pink	Set-Light -Color Pink	ShellCommand
AllRed	redScript.sh	Script

The Preprocessor

Starting with version 1.1, SSH Remote features a powerful preprocessor, which enables you to better control the output of your buttons and enables some target device independend features.

Below, you will find a list of preprocessor commands, that you can use in any kind of command (simple, shell or (mainly) script). The preprocessor will process the commands line by line and replace occurences in the exact same order as the commands are presented below. If a command is not recognized, it is not replaced. Empty lines are removed from the output after that.

Oder: 1

Command: $PUBLIC_KEY$
Replaced by: The public rsa key used to connect to the device
Remarks: Only useful when using key authentification. Otherwise, the command will be replaced by nothing

Oder: 2

Command: $TIME$
Replaced by: The current Time
Remarks: The format of the time string is
“Tue Jun 22 13:07:00 PDT 1999”

Oder: 3

Command: $RANDOM_INT(max)$
Replaced by: A random integer number between 0 (inlcusive) and max (exclusive)
Remarks: max must be an integer number.

Oder: 4

Command: $RANDOM_STRING(size)$
Replaced by: A random string consisting of size characters (upper and lower case letters, digits and the following special characters: -_ )
Remarks: size must be an integer number.

Oder: 5

Command: $SET variable=value$
Replaced by: Nothing
Remarks: Sets a preprocessor variable with the name variable to value.
Variables set this way are used in the next step in this and the following lines.

Oder: 6

Command: $variable$
Replaced by: The value of the variable
Remarks: See step 4

Oder: 7

Command: $OUTPUT=value$
Replaced by: Nothing
Remarks: If at least one of those commands is present, the normal output of the ssh commands will be supressed and instead, value will be displayed. Subsequent uses of this commands, will append to this output.

Oder: 8

Command: $SHARE_TEXT=value$
Replaced by: Nothing
Remarks: Opens the share selection and shares value as plain text with the target app.

Oder: 9

Command: $SHARE_FILE=value$
Replaced by: Nothing
Remarks: Opens the share selection and shares value as a text file with the target app.

Oder: 10

Command: $PRINT=value$
Replaced by: Nothing
Remarks: Prints value via android printing. Printing via android is only supported on android 4.4 and upwards!

Oder: 11

Command: $PRINTDIRECT=value$
Replaced by: Nothing
Remarks: Prints value via PrintHand directly without requiring further user actions. PrintHand Premium must be installed for this

Order	Command	Replaced by	Remarks
1	$PUBLIC_KEY$	The public rsa key used to connect to the device	Only useful when using key authentification. Otherwise, the command will be replaced by nothing
2	$TIME$	The current Time	The format of the time string is “Tue Jun 22 13:07:00 PDT 1999”
3	$RANDOM_INT(max)$	A random integer number between 0 (inlcusive) and max (exclusive)	max must be an integer number.
4	$RANDOM_STRING(size)$	A random string consisting of size characters (upper and lower case letters, digits and the following special characters: -_ )	size must be an integer number.
5	$SET variable=value$	Nothing	Sets a preprocessor variable with the name variable to value. Variables set this way are used in the next step in this and the following lines.
6	$variable$	The value of the variable	See step 4.
7	$OUTPUT=value$	Nothing	If at least one of those commands is present, the normal output of the ssh commands will be supressed and instead, value will be displayed. Subsequent uses of this commands, will append to this output.
8	$SHARE_TEXT=value$	Nothing	Opens the share selection and shares value as plain text with the target app.
9	$SHARE_FILE=value$	Nothing	Opens the share selection and shares value as a text file with the target app.
10	$PRINT=value$	Nothing	Prints value via android printing. Printing via android is only supported on android 4.4 and upwards!
11	$PRINTDIRECT=value$	Nothing	Prints value via PrintHand directly without requiring further user actionsPrintHand Premium must be installed for this

For demonstration purposes, below is a small sample file and the subsequent result after each step of the preprocessor.

$SET pwd=$RANDOM_STRING(5)$$
echo "$pwd$"
$OUTPUT=Password $pwd$ has been set.$

After the first step in line 1:

$SET pwd=tX32l$
echo "$pwd$"
$OUTPUT=Password $pwd$ has been set.$

After the second step in line 1:

echo "$pwd$"
$OUTPUT=Password $pwd$ has been set.$

After line 2:

echo "tX32l"
$OUTPUT=Password $pwd$ has been set.$

After the first step in line 3:

echo "tX32l"
$OUTPUT=Password tX32l has been set.$

Finally:

echo "tX32l"

The output of this script, if executed will be:

Password tX32l has been set.

User data is only stored in the app and transmitted to the target device when a connection is made. No data entered through the app will be transmitted to Firesource UG (haftungsbeschränkt) or a third party.

Thanks for Reading!

Get the App on Google Play