SSH Connection

Utilities Targets Requires: signed in

Configure secure SSH access to the target device.

Configures communication with the display over SSH — key files, login names, etc. for communicating securely with the shell on the target. This is used for Prep Target, as well as other tools such as viewing journals. Host Name / IP is shared with Toolkit Connection — changing it here changes it there too.

Fields: Host Name / IP, Login Name, SSH Key File (to create one, use the Project Editor to generate a DeviceKey, added to your ~/.ssh/), and Signing Key (to create one, use the Project Editor to generate a SigningKey for app signing).

While this tab is selected, the Actions panel becomes SSH Actions, offering Lock Target and Unlock Target in addition to Add/Remove Display.

The same address and login name also let anyone on the network connect to the display over SSH — until the target is locked. See Connecting over SSH below.

Connecting over SSH

Watch video walkthrough

1. To connect to the display over SSH — here with WinSCP — you need its address and login name. Both are on the SSH Connection tab: note the Host Name / IP — here, 192.168.7.1 — and the Login Name — here, root.

   

2. Open WinSCP. In the Login dialog, with New Site selected, leave File protocol set to SFTP — the SSH File Transfer Protocol, which runs over SSH.

   

3. Enter the Host Name / IP from the toolkit as Host name, leave Port number at 22, and enter the Login Name as User name. Click Login.

   

4. The first time you connect to a display, WinSCP warns that the server is unknown and asks whether to add its host key to the cache. Check that the address shown is your display's, then click Accept. WinSCP remembers the key, so this doesn't appear again for the same display.

   

5. On an unlocked display, WinSCP connects without asking for a password — the status bar shows SFTP-3. The left pane shows your PC (here, the PackageOutput folder) and the right pane shows the display's file system, starting in /home/root/. Drag files between the panes to copy them.

   

Lock Target

Watch video walkthrough

1. Lock Target replaces the display's password-less logins with a key: afterwards, only someone holding the matching private key can connect over SSH. First choose the key. On the SSH Connection tab, click SSH Key File.

   

2. The list shows every key found in your ~/.ssh folder. Select the device key to lock with — here, DeviceDemoKey, created in New Device Key.

   

3. With the key selected, click Lock Target in SSH Actions.

   

4. A confirmation explains what it does: disables password-based logins, and installs device and application keys (if selected). Click Yes.

   

5. The app switches to Console while it adds the key to the display. This only takes a moment.

   

6. It then returns to the SSH Connection tab with a Lock Display Complete dialog. Click Ok.

   

7. Back on the SSH Connection tab, SSH Key File now shows OpenView instead of the key you chose — you'll fix that after the reboot. Click Console to review the full log.

   

8. The log confirms Device Locked to KeyFile with the path to DeviceDemoKey, and that the target is now available over SSH as root@OpenView. Close the Console with its X.

   

9. The lock doesn't take effect until the display restarts — until then, it still accepts password-less logins. Click the Reboot Display icon at the bottom right.

   

10. Once the display reconnects, SSH Key File still shows OpenView: after a lock, the toolkit switches it to a key named after the connection, even though you locked with a different key. Click it to change it back.

    

11. The list now includes OpenView as well, even though no key file by that name exists. Select the key you locked with — here, DeviceDemoKey — so the toolkit's own SSH actions, such as Prep Target and Unlock Target, can still connect.

    

12. The display is now locked. It only accepts SSH logins using DeviceDemoKey — connecting without the key is refused.

    

Connect with a Key

Watch video walkthrough

1. Once a display is locked, connecting over SSH needs the private key it was locked with — here, DeviceDemoKey (see Download Key to get it onto your machine). In WinSCP's Login dialog, enter the display's Host name and User name as in Connecting over SSH, then click Advanced....

   

2. In Advanced Site Settings, click Authentication under SSH.

   

3. Click the ... button next to Private key file.

   

4. The file picker only lists PuTTY (.ppk) keys by default, but the toolkit saves keys in OpenSSH format. Browse to your ~/.ssh/Ahsoka folder and change the file type to All Files.

   

5. Select the private key — DeviceDemoKey, not DeviceDemoKey.pub — and click Open.

   

6. WinSCP only uses PuTTY-format keys, so it offers to convert this one. Click OK.

   

7. Save the converted copy next to the original — here, DeviceDemoKey.ppk — then click Save. The original key file isn't changed.

   

8. WinSCP confirms the key was converted and saved. Click OK.

   

9. Private key file now points at the .ppk file. Click OK to close Advanced Site Settings.

   

10. Back in the Login dialog, click Login.

    

11. WinSCP connects using the key, with no password, and the right pane shows the display's /home/root/ folder.

    

Unlock Target

Watch video walkthrough

1. Unlock Target reverses Lock Target: it leaves any keys in place but allows password-less logins again. It connects to the display with the key it's locked with, so check that SSH Key File shows that key — here, DeviceDemoKey. Then click Unlock Target.

   

2. A confirmation explains that it leaves any keys in place but allows standard logins. Click Yes.

   

3. There's no progress screen or completion dialog — the app stays on the SSH Connection tab. Click Console to see what happened.

   

4. The log shows Beginning Device Unlock Process and Device Unlocked. Close the Console with its X.

   

5. Like the lock, the unlock doesn't take effect until the display restarts — until then, it still only accepts logins with the key. Click the Reboot Display icon at the bottom right.

   

6. Once the display reconnects, it's unlocked: it accepts SSH logins as root without a key or password again, as in Connecting over SSH. Unlike Lock Target, SSH Key File keeps the key you had selected.