Doc: Describe using OpenSSH connections

...to connect to embedded Linux devices.

Change-Id: Icd4196a25cf99928d929c70df17cd0f7e271abf6
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

7 files changed, 73 insertions, 18 deletions

diff --git a/doc/images/qtcreator-linux-device-configurations.png b/doc/images/qtcreator-linux-device-configurations.png
index fc8398ef8c..0f73327aef 100644
--- a/doc/images/qtcreator-linux-device-configurations.png
+++ b/doc/images/qtcreator-linux-device-configurations.png
diff --git a/doc/images/qtcreator-screenshot-devconf-linux.png b/doc/images/qtcreator-screenshot-devconf-linux.png
index cb69dca7b3..2696c7f99c 100644
--- a/doc/images/qtcreator-screenshot-devconf-linux.png
+++ b/doc/images/qtcreator-screenshot-devconf-linux.png
diff --git a/doc/images/qtcreator-ssh-key-configuration.png b/doc/images/qtcreator-ssh-key-configuration.png
index 0f001702b9..aac22732bd 100644
--- a/doc/images/qtcreator-ssh-key-configuration.png
+++ b/doc/images/qtcreator-ssh-key-configuration.png
diff --git a/doc/images/qtcreator-ssh-options.png b/doc/images/qtcreator-ssh-options.png
new file mode 100644
index 0000000000..4300960532
--- /dev/null
+++ b/doc/images/qtcreator-ssh-options.png
diff --git a/doc/src/linux-mobile/linuxdev-keys.qdocinc b/doc/src/linux-mobile/linuxdev-keys.qdocinc
index 99fe973bd6..826611994c 100644
--- a/doc/src/linux-mobile/linuxdev-keys.qdocinc
+++ b/doc/src/linux-mobile/linuxdev-keys.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -24,6 +24,50 @@
 ****************************************************************************/
 
 /*!
+
+//! [configuring ssh]
+    \section2 Configuring SSH Connections
+
+    SSH connections are established via an OpenSSH client running in master
+    mode, if possible. Connection sharing is enabled by default to allow
+    sharing multiple sessions over a single SSH connection. This way, a
+    connection is only established once and then re-used by subsequent run
+    and deploy procedures, saving connection setup overhead particularly
+    with embedded devices. Because connection sharing is not supported on
+    Windows, a new SSH connection is created for each deploy or run procedure.
+
+    To create SSH connections, you must install the \l{https://www.openssh.com/}
+    {OpenSSH} suite, which includes the ssh, sftp, and ssh-keygen tools on the
+    development PC.
+
+    To tell \QC where it can find the tools, specify the paths to the
+    directories where the tools are installed in \uicontrol Tools >
+    \uicontrol Options > \uicontrol Devices > \uicontrol SSH:
+
+    \image qtcreator-ssh-options.png
+
+    \list
+        \li Deselect the \uicontrol {Enable connection sharing} check box to
+            create a new SSH connection for each deploy and run procedure. This
+            option is grayed on Windows, where connection sharing is not
+            supported.
+        \li In the \uicontrol {Connection sharing timeout} field, specify the
+            timeout for reusing the SSH connection in minutes.
+        \li In the \uicontrol {Path to ssh executable} field, enter the path
+            to the directory where the OpenSSH executable is installed.
+        \li In the \uicontrol {Path to sftp executable} field, enter the path
+            to the directory where the SFTP executable is installed.
+        \li In the \uicontrol {Path to ssh-askpass executable} field, enter the
+            path to the directory where the ssh-askpass executable is installed.
+            Usually, you can use the default path that points to the
+            implementation of the tool delivered with \QC, qtc-askpass.
+        \li In the \uicontrol {Path to ssh-keygen executable} field, enter the
+            path to the directory where the ssh-keygen executable is installed.
+    \endlist
+
+//! [configuring ssh]
+
+
 //! [generating ssh keys]
 
     \section2 Generating SSH Keys
@@ -39,7 +83,7 @@
     \list 1
 
         \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Devices
-            > \uicontrol {Create New}.
+            > \uicontrol Devices > \uicontrol {Create New}.
 
             \image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog"
 
diff --git a/doc/src/linux-mobile/linuxdev-processes.qdocinc b/doc/src/linux-mobile/linuxdev-processes.qdocinc
index 8525f8e0e4..a8e2195e3a 100644
--- a/doc/src/linux-mobile/linuxdev-processes.qdocinc
+++ b/doc/src/linux-mobile/linuxdev-processes.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -30,10 +30,10 @@
 
     You can view processes running on devices and kill them. Select
     \uicontrol Tools > \uicontrol Options > \uicontrol Devices >
-    \uicontrol {Remote Processes}.
+    \uicontrol Devices > \uicontrol {Show Running Processes}.
 
-    You can filter the processes by name in the \uicontrol {List of Processes}
-    dialog.
+    You can filter the processes by name or ID in the
+    \uicontrol {List of Processes} dialog.
 
     To update the process list, select \uicontrol {Update List}.
 
diff --git a/doc/src/linux-mobile/linuxdev.qdoc b/doc/src/linux-mobile/linuxdev.qdoc
index 85d415f565..7f711192e0 100644
--- a/doc/src/linux-mobile/linuxdev.qdoc
+++ b/doc/src/linux-mobile/linuxdev.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2018 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -50,13 +50,21 @@
     add devices and select them in the \QC \l{glossary-buildandrun-kit}{kit}.
 
     You use a wizard to create the connections. You can edit the settings later
-    in \uicontrol Tools > \uicontrol Options > \uicontrol Devices.
+    in \uicontrol Tools > \uicontrol Options > \uicontrol Devices >
+    \uicontrol Devices.
 
     \image qtcreator-linux-device-configurations.png "Devices dialog"
 
-    You can protect the connections between \QC and a device by using
-    either a password or an SSH key. If you do not have an SSH key, you can
-    create it in \QC. For more information, see \l {Generating SSH Keys}.
+    You can protect the connections between \QC and a device by using an
+    \l{https://www.openssh.com/}{OpenSSH} connection. OpenSSH is a
+    connectivity tool for remote login using the SSH protocol. The OpenSSH
+    suite is not delivered with \QC, so you must download it and install it
+    on the development PC. Then, you must configure the paths to the tools in
+    \QC. For more information, see \l {Configuring SSH Connections}.
+
+    You need either a password or an SSH public and private key pair for
+    authentication. If you do not have an SSH key, you can use the ssh-keygen
+    tool to create it in \QC. For more information, see \l {Generating SSH Keys}.
 
     To configure connections between \QC and an embedded Linux device and to
     specify build and run settings for the device:
@@ -78,8 +86,9 @@
 
             \list 1
 
-                \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Devices
-                    > \uicontrol Add > \uicontrol {Generic Linux Device}
+                \li Select \uicontrol Tools > \uicontrol Options >
+                    \uicontrol Devices > \uicontrol Devices > \uicontrol Add >
+                    \uicontrol {Generic Linux Device}
                     > \uicontrol {Start Wizard}.
 
                     \image qtcreator-screenshot-devconf-linux.png "Connection Data wizard"
@@ -96,11 +105,12 @@
                     application as.
                     This value will be available in the variable \c %{Device:UserName}.
 
-                \li In the \uicontrol {The authentication type} field, select whether
-                    to use \uicontrol Password or \uicontrol Key authentication, and enter
-                    the user's password or the file that contains the user's
-                    private key.
-                    The latter will be available in the variable \c %{Device:PrivateKeyFile}.
+                \li In the \uicontrol {The authentication type} field, select
+                    \uicontrol Default to use the currently displayed private
+                    key file for authentication. Select \uicontrol {Specific Key}
+                    to use some other key, and enter the path to the file that
+                    contains the private key in the field below. This value will
+                    be available in the variable \c %{Device:PrivateKeyFile}.
 
                 \li  Click \uicontrol {Next} to create the connection.
 
@@ -137,6 +147,7 @@
 
     \endlist
 
+    \include linux-mobile/linuxdev-keys.qdocinc configuring ssh
     \include linux-mobile/linuxdev-keys.qdocinc generating ssh keys
     \include linux-mobile/linuxdev-processes.qdocinc managing device processes
 */