SSH Extension and Terminal Widget User Guide Version 1.0 0
Copyright 2016 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively PTC ) are subject to the copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC. UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy. Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software. United States Governments Rights PTC software products and software documentation are commercial items as that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014) for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1 (a) (Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer software documentation) (FEB 2014) for the Department of Defense, PTC software products and software documentation are provided to the U.S. Government under the PTC commercial license agreement. Use, duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in the applicable PTC software license agreement. PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA ii
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 iii
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: http://www.openssh.com/manual.html. 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 1. From a web browser, launch ThingWorx Composer. 1
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. 7. Now that all of the entities have been imported, verify that SshServerTemplate Thing Template is available. 2
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. 3
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. 4
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 from the configuration table is used. o 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 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. o username: The username used for authentication. If itis not supplied, the username from the configuration table is used. o 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. 5
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 enters the username and password. The widget provides the following services: Clear: Clears the screen contents. 6
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 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. 7
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 6.0.4 Java version 7, update 79 ThingWorx 6.5.0 Java version 8, update 65 ThingWorx 6.6.2 Java version 8, update 66 Document Revision History Revision Date Version Description of Change 1/19/2016 1.0 Initial release 8