SSH Extension and Terminal Widget User Guide. Version 1.0

Transcription

1 SSH Extension and Terminal Widget User Guide Version 1.0 0

2 Software Change Log... 1 Introduction and Installation... 1 About the SSH Extension and Terminal Widget... 1 Installing the SSH Extension and Terminal Widget... 1 Configuration and Usage: SSH Extension... 3 Configuration... 3 Usage... 5 Configuration and Usage: Terminal Widget... 6 Configuration... 6 Usage... 7 Known Limitations and Compatibility... 8 Limitations... 8 Compatibility... 8 Document Revision History... 8

3 Software Change Log Version Release Date Changes 1.0 1/19/2016 Initial Release Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and ThingWorx users can easily add new functionality into the system in a seamless manner. Extensions can be Service (function/method) libraries, Connector Templates, Widgets, and more. This document provides installation and usage instructions for the SSH Extension and the terminal widget. About the SSH Extension and Terminal Widget The SSH Extension allows you to configure Thingworx entities to connect to a remote SSH (Secure shell) server for the purposes of executing commands on that server. Both password, and key based authentication are supported. For this to work, the remote SSH server should be able to listen for SSH client connections. Most Linux distributions comes with OpenSSH, the most popular SSH implementation, as the default option. For more information on how to configure the SSH server and create advanced user access control lists consult the SSH server documentation. In the OpenSSH case, you can find the online manual here: The SSH Extension allows you to use ThingWorx Composer to create a thing that implements the SshServerTemplate thing template. The thing entity contains the configuration information for and implements the following services 1. ExecuteCommand 2. AttemptLogin The Terminal widget provides a visually pleasing way of displaying and executing commands. Although designed to be used together with the SSH extension, it is a completely separate entity. Installing the SSH Extension and Terminal Widget

4 1. From a web browser, launch ThingWorx Composer. 1

5 2. Log into ThingWorx Composer as an administrator. 3. Go to Import/Export > Import. 4. Click Choose File and select sshextension.zip 5. Click Import. Note: If an Import Successful message does not appear, contact your ThingWorx System Administrator. Note: 6. Click Yes to refresh Composer after importing the final extension. 2

6 7. Now that all of the entities have been imported, verify that SshServerTemplate Thing Template is available. 3

7 Configuration and Usage: SSH Extension Configuration 1. Create a new thing and select the SshServerTemplate from the Thing Template list. 2. Under Entity Information for the new thing, click Configuration, and then Edit. Be sure to save the entity when editing is complete. 4

8 3. Fill out the SSH Server Connection Parameters,based on the specifications of the SSH Server. a. SSH Server: The address of the server. Can be an IP address or a hostname. b. SSH Server Port: port of the server. Default is 22, the SSH default port. c. SSH User: The user name to provide when connecting to the SSH server. It must be a preexisting SSH user. d. SSH Account Password: (Optional) The password to provide for password based authentication. e. Connection Timeout: The number of milliseconds to wait for the connection to be established.. f. KeepAlive Timeout: The number of milliseconds to wait for commands to be sent to the server before automatically disconnecting. A new connection is automatically established when a new command is sent. For authentication you can either supply an SSH Account Password, or a private key that is located in a file Repository. For Key based authentication: Repository: File repository where the private key is saved. Private Key: The name of the private key file. This key is in the OpenSSH format. Keys in the Putty format can easily be converted, using the puttygen tool. Private key Passphrase: (Optional) The passphrase to decrypt a password protected private key file. 4. Save the SSH thing. 5

9 Usage To use the SSH Extension, invoke any one of the aforementioned services, either through testing, script, or a mashup. Input parameters for the services are listed below. AttemptLogin o username: The username used for authentication. If itis not supplied, the username o from the configuration table is used. password: The password used for authentication. If itis not supplied, the password or private key specified in the configuration table is used. ExecuteCommand o command: The command to execute. You can supply any valid command that ca be o o executed by the shell on the remote server. Interactive commands are not supported, as this service needs to wait for the commands to finish before returning. username: The username used for authentication. If itis not supplied, the username from the configuration table is used. password: The password used for authentication. If itis not supplied, the password or private key specified in the configuration table is used. Important Connection Notes The SSH extension requires a server that is correctly configured to listen for incoming SSH connections. The underlying connection is closed automatically when the time period that is specified in the KeepAlive Timeout configuration parameter expires. The connection is then opened on demand. This behavior keeps the connection from stalling. Also, please remember the following: The user account must be configured on the server. Authentication can be done via password or public key. If no password is specified, authentication via private key is attempted. If the user has read only access, only a subset of the services are available to that user. To avoid connection issues, it is recommended that firewalls be disabled on the remote server. It is recommended that you use this Extension with a server that is running OpenSSH. 6

10 Configuration and Usage: Terminal Widget To use the Terminal Widget, you must first add it to a mashup. This widget provides a way to execute commands and display the results in an interface that is familiar to users. Although designed to complement the SSH extension, you can use this widget separately. Configuration The following widget properties are available: NextCommand: Contains the next command to be executed. Can be bound as a source or a target. LastCommandResult: Contains the result of the last command. When set dynamically, it is displayed in the terminal. Can be bound as a target. isauthenticated: If set to true, the user is not promptedto enter a username and password. If set to false, user is required to log in at runtime Username: The username required to execute commands. Password: The password required to execute commands BackgroundStyle: Configure the look and feel of the widget. The Background color, Foreground color and TextSize properties are used. The widget generates the following events: CommandTyped: Fired when the user presses Enter. AuthenticationAttempt: Fired after the user 7

11 enters the username and password. The widget provides the following services: Clear: Clears the screen contents. 8

12 Usage The bindings between the Terminal widget and the SSH extension that you need to set up for the SSH Thing and the Terminal Widget are displayed in the following figure The bindings required to just execute commands are displayed in the figure below: To set up these bindings, follow these: 1. Create a mashup. Drag and drop a Layout (optional), and then drag and drop the Terminal widget. 2. Add the SSH thing on the right hand panel. 3. Connect the CommandTyped and AuthenticationAttempt events of the widget to the ExecuteCommand and AttemptLogin services of the SSH thing, respectively. 4. Connect the NextCommand property of the widget to the command parameter of the ExecuteCommand service of SSH thing. 5. Connect the Username property of the widget to the username parameter of both the 9

13 ExecuteCommand and AttemptLogin services of the thing. 6. Connect the Password property of the widget to the password parameter of both the ExecuteCommand and AttemptLogin services of the thing. 10

14 7. Drag result under the returned data of the AttemptLogin service of the SSH thing to the isauthenicated property of the widget. 8. Drag result under the returned data of the ExecuteCommand service of the SSH thing to the LastCommandResult property of the widget. 9. Save your mashup. Once you have set up the mashup, you should be able to connect to the remote SSH server and execute commands, as shown in the following figure: Known Limitations and Compatibility Limitations This extension does not support interactive commands. Any commands that are executed must return a result and must not wait for user input Compatibility This extension has been tested for compatibility with the following versions of the ThingWorx Platform and of the Java JRE: ThingWorx Platform Version Java JRE Version ThingWorx Java version 7, update 79 ThingWorx Java version 8, update 65 ThingWorx Java version 8, update 66 Document Revision History 11

15 Revision Date Version Description of Change 1/19/ Initial release 12