Connect using SSH

  • Article

You can use OpenSSH to connect to your Factory OS test devices and VMs and run commands or transfer files. OpenSSH (Secure Shell) is a standard protocol for secure terminal connections.

You can use SSH to connect to all Factory OS images

WDP topology showing you can connect via ssh from a remote pc

What you need to connect using SSH

To connect to a device using SSH, you'll have need:

  • The SSH server started on your Factory OS device
  • An SSH client on your technician PC. Windows 10 includes an SSH client that's installed by default.
  • The IP address of the device you're connecting to. In Factory OS, get the IP address from the main screen of the Factory Composer app, or in the top-right corner of Factory Orchestrator.
  • Authentication configured for SSH. This can be either:
    • A username and password
    • A keypair

Start the SSH server

On images that include the WindowsCoreNonProductionFM feature manifest, you can add the WCOS_OPENSSH_AUTOSTART feature to automatically start the SSH server.

If your image isn't configured to automatically start the SSH server, you can use Windows Device Portal to manually start the SSH server.

  1. Open a browser on your technician PC and navigate to the URL of your Factory OS device.
  2. Once connected to Device Portal, navigate to the SSH tab in the left-hand pane. The SSH tab is at the bottom of the list.
  3. Select Enable SSH.

Connecting using a name and password

To be able to connect using a username and password, you have to first configure a username and password. Configuring an SSH username and password depends on the Factory OS product that you're using.

Username and password in Factory OS

Factory OS includes a built-in administrator account that you can use to connect with SSH:

  • Username: FactoryUser
  • Password: WindowsCore

You can customize the username and password with the SSHUsername and SSHPassword settings in the settings customization framework.

Connecting using a key pair

If you have a key pair for SSH (see your SSH client documentation for details), you can use it instead of a username and password.

You'll need a public key in OpenSSH format. Run ssh-keygen.exe on your technician PC to generate one. ssh-keygen is included with Windows.

Create a keypair

  1. From a Command prompt on your technician PC, run ssh-keygen.exe to generate a public and private keypair. When you run this command, you can choose to save the keys to a location on your PC, and also set a password:

    ssh-keygen

    This command will prompt you for the following information, and provide output similar to the following:

    Enter file in which to save the key (C:\Users\User/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\User/.ssh/id_rsa.
Your public key has been saved in C:\Users\User/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:<SHA245> user@COMPUTER
The key's randomart image is:
+---[RSA 2048]----+
|     .o oo=+.+OB |
|     ..o.... =B+o|
|      .o ++ +oo*o|
|       ... +.o+..|
|      . S   oo.+.|
|       . .   .+.E|
|        .    ... |
|                 |
|                 |
+----[SHA256]-----+

  2. Navigate to the the folder where you stored your keys, you'll see a private key that has no extension and a public key that has a .pub extension.

  3. Open the public key file with a text editor. The public key isn't sensitive. Here's what they look like:

    ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAiez5r6NN01TK5yFPCV34Po4UdsMej4Gbl441SAzGihcE3eV7bSnLRR32RKH8T6ZQ2eZSZ1zPD6xkGnBE0CXvlHLP76nva4AaoCoPAEDIbNKLVmPiKn6U6MDlkass6TFrfOBlsY3m+rZyWJipZEFLrptvqli72lkWttUNfwgu8CJKMBbjGsd4HS3EFwCrSsKqI2MBKk7SO3+DNrwAPUWK9O/hT/mqARMMMbD/zM0BrHZ/U9mc3w/x2y2awpONJF9yVjfXAvG6JTrB+Bh6pr2BYccmVAwPmXkQM+3HrFjS7nfSZnjBQE3YD6PTZfT7Qs6V15CoCvIaoRQs0AEBJLK53Q== rsa-key-20180427

  4. Copy the contents of your public key to the clipboard.

  5. Connect to your WCOS device with Device Portal. Naveigate to the SSH tab in the left-pane, and copy the public key from your clipboard into the box titled Public Key for your desired user.

Connect

Once you have authenication configured, you can connect to your Factory OS device:

  1. Open a Command prompt window on your technician PC.

  2. Connect to the device:

    1. To connect using a username and password:
    ssh user@192.168.1.2

    Where user is the username you chose when setting up SSH, and 192.168.1.2 is your Factory OS device's IP address.

    1. To connect using a key pair
    ssh -i C:\Users\User/.ssh/id_rsa user@192.168.1.2

    Where C:\Users\User/.ssh/id_rsa id your private key, user is the username you chose when setting up SSH, and 192.168.1.2 is your Factory OS device's IP address.

  3. Enter the password for your user if you're connecting with a username and password, or if you configured your key to require a password.

Secure FTP

You can use SSH for file transfer, over the sftp protocol. If you've enabled SSH on your Factory OS device, you'll also be able to connect with sftp.

WinSCP is the most popular GUI Client for file transfer over sftp in Windows. Follow the documentation to learn how to use it.

If you prefer a command-line tool, you can use sftp and scp:

sftp:

usage: sftp [-46aCfpqrv] [-B buffer_size] [-b batchfile] [-c cipher]
         [-D sftp_server_path] [-F ssh_config] [-i identity_file] [-l limit]
         [-o ssh_option] [-P port] [-R num_requests] [-S program]
         [-s subsystem | sftp_server] destination

scp:

usage: scp [-346BCpqrv] [-c cipher] [-F ssh_config] [-i identity_file]
          [-l limit] [-o ssh_option] [-P port] [-S program] source ... target

The above utilities are included in Windows and can be run by launching a Command prompt.