diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-1.png b/source/clear-linux/guides/network/figures/vnc/vnc-1.png new file mode 100644 index 00000000..bb496aaf Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-1.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-10.png b/source/clear-linux/guides/network/figures/vnc/vnc-10.png new file mode 100644 index 00000000..be6751fc Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-10.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-11.png b/source/clear-linux/guides/network/figures/vnc/vnc-11.png new file mode 100644 index 00000000..0ba816b9 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-11.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-2.png b/source/clear-linux/guides/network/figures/vnc/vnc-2.png new file mode 100644 index 00000000..aa7561f7 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-2.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-3.png b/source/clear-linux/guides/network/figures/vnc/vnc-3.png new file mode 100644 index 00000000..29365e08 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-3.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-4.png b/source/clear-linux/guides/network/figures/vnc/vnc-4.png new file mode 100644 index 00000000..b3608289 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-4.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-5.png b/source/clear-linux/guides/network/figures/vnc/vnc-5.png new file mode 100644 index 00000000..ff56d089 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-5.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-6.png b/source/clear-linux/guides/network/figures/vnc/vnc-6.png new file mode 100644 index 00000000..5a808e34 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-6.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-7.png b/source/clear-linux/guides/network/figures/vnc/vnc-7.png new file mode 100644 index 00000000..a20e6c97 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-7.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-8.png b/source/clear-linux/guides/network/figures/vnc/vnc-8.png new file mode 100644 index 00000000..fa702cb4 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-8.png differ diff --git a/source/clear-linux/guides/network/figures/vnc/vnc-9.png b/source/clear-linux/guides/network/figures/vnc/vnc-9.png new file mode 100644 index 00000000..a8cafba4 Binary files /dev/null and b/source/clear-linux/guides/network/figures/vnc/vnc-9.png differ diff --git a/source/clear-linux/guides/network/network.rst b/source/clear-linux/guides/network/network.rst index d1c7357a..6c4da0d1 100644 --- a/source/clear-linux/guides/network/network.rst +++ b/source/clear-linux/guides/network/network.rst @@ -13,4 +13,5 @@ the configuration, administration, and use of networks in the |CLOSIA|. dpdk ovs-dpdk network-bonding - custom-clear-container \ No newline at end of file + custom-clear-container + vnc diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst new file mode 100644 index 00000000..a01b6657 --- /dev/null +++ b/source/clear-linux/guides/network/vnc.rst @@ -0,0 +1,840 @@ +.. _vnc: + +Remote-desktop to a Clear Linux host using VNC +############################################## + +:abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool that +you use to remote-desktop to your |CLOSIA| host. + +This guide shows you how to: + +* Install the VNC server and misc. components on your |CL| host. +* Configure a VNC-server-start method on your |CL| host. +* Install a VNC viewer app and an SSH client on your client system. +* Establish a VNC connection to your |CL| host. +* Terminate a VNC connection to your |CL| host. +* Encrypt VNC traffic through an SSH tunnel. + +Install the VNC server and misc. components on your Clear Linux host +******************************************************************** + +To make VNC work on your |CL| host, you need to install these bundles: + +* `desktop-autostart`: installs :abbr:`GDM (Gnome Desktop Manager)` and set + it to start automatically on boot. This also installs TigerVNC Viewer. +* `vnc-server`: installs the TigerVNC server. +* `openssh-server`: installs an SSH server. + +Follow these steps: + +#. Log into your |CL| host and get root privileges. + + .. code-block:: console + + $ sudo -s + +#. Install the |CL| bundles. + + .. code-block:: console + + # swupd bundle-add desktop-autostart vnc-server openssh-server + +#. Reboot your |CL| host. + +Configure a VNC-server-start method on your Clear Linux host +************************************************************ + +There are three methods you can use to configure and start the VNC server on +your host: + +.. list-table:: Table 1: VNC-server-start Configuration Methods + :widths: 10,20,20,20 + :header-rows: 1 + + * - Attribute + - `Method 1`: Manually start VNC session + - `Method 2`: Automatically start a VNC session via a systemd service script + - `Method 3`: Multi-user logins with authentication through GDM + * - Description + - This is the traditional method where you SSH into the |CL| host, manually + start a VNC session to get a display ID, and then you connect to it by + supplying the display ID. + - The system administrator sets up a systemd service script for you with + a pre-assigned display ID. You just make a VNC connection and supply + your pre-assigned display ID. + - The system adminstrator configures GDM to accept connection requests. + When you make a VNC connection to the |CL| host, you'll be presented with + the GDM login screen and you authenticate as if you're local. + * - Who configures VNC settings? + - You + - System adminstrator + - System adminstrator + * - Who starts VNC session? + - You + - Set to start automatically on boot by system administrator + - Set to start automatically on boot by system administrator + * - Who ends VNC sesssion? + - You + - You + - System administrator can disable VNC service altogether + * - Requires VNC password to authenticate? + - Yes + - Yes + - No. Use |CL| account username and password through GDM + + +Although all three methods can co-exist on the same |CL| host, we recommend +you pick a method that suits your needs. + +For simplicity, the rest of this guide refers to these methods as +`Method 1`, `Method 2`, and `Method 3`. + +Method 1: Manually start a VNC session +====================================== + +You (and each user) must perform these steps to initialize you VNC settings. + +#. Log in. +#. Open a terminal emulator. +#. Start VNC with the :command:`vncserver` command. Since this is your first + time starting VNC, it adds default configuration files and asks you to set + a VNC password. + + .. code-block:: console + + $ vncserver + + Example output: + + .. code-block:: console + + $ vncserver + + You will require a password to access your desktops. + + Password: + Verify: + Would you like to enter a view-only password (y/n)? n + xauth: file /home/vnc-user-a/.Xauthority does not exist + + New 'clr-linux:2 (vnc-user-a)' desktop is clr-linux:2 + + Creating default startup script /home/vnc-user-a/.vnc/xstartup + Creating default config /home/vnc-user-a/.vnc/config + Starting applications specified in /home/vnc-user-a/.vnc/xstartup + Log file is /home/vnc-user-a/.vnc/clr-linux:2.log + + Upon completion, you can find the default configuration files and the + password file hidden in the `.vnc` directory in your home directory. + + Also, a VNC session will start and show a unique display ID, which is the + number following the hostname and the colon `:`. In the above example, the + display ID is 2. In a later step, you will supply the display ID is to + your VNC viewer app so it knows which session to connect to. + +#. Kill the active VNC session for the time being with the + :command:`vncserver -kill :[display ID]` command. Substitute [display ID] + with your active VNC session display ID. For example: + + .. code-block:: console + + $ vncserver -kill :2 + + .. note:: + + If you don't recall the active session display ID, you can use the + :command:`vncserver -list` command to find it. + +#. Optional configurations: + + * To customize settings such as screen size, security type, etc., + modify the `%HOME/.vnc/config` file. + * To customize the applications to run at startup, + modify the `%HOME/.vnc/xstartup` file. + +Method 2: Automatically start a VNC session via a systemd service script +======================================================================== + +To configure VNC for this method, you must have root privileges. You will set +up a systemd service file for each intended VNC users with his or her own +pre-assigned unique display ID. + +#. Log in and get root privileges. + + .. code-block:: console + + $ sudo -s + +#. Make sure the user accounts already exit. Use the following command to + list all users. + + + .. code-block:: console + + # cut -d: -f1 /etc/passwd + +#. Create the path `/etc/systemd/system`. + + .. code-block:: console + + # mkdir -p /etc/systemd/system + +#. Create a systemd service script file :file:`vncserver@:[X].service`, where + [X] is the display ID, for each user in `/etc/systemd/system`. Each user + must be assigned a unique display ID. Be sure the correct username is entered + in the `User` field. Below is an example shows user `vnc-user-b` who is + assigned the display ID `5`. + + .. code-block:: console + + # cat > /etc/systemd/system/vncserver@:5.service << EOF + + [Unit] + Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5" + After=syslog.target network.target + + [Service] + Type=simple + User=vnc-user-b + PAMName=login + PIDFile=/home/%u/.vnc/%H%i.pid + ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :' + ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -alwaysshared -fg + ExecStop=/usr/bin/vncserver -kill %i + + [Install] + WantedBy=multi-user.target + + EOF + +#. Have each user log into his or her account and set a VNC password with + the :command:`vncpasswd` command before proceeding to the next step. + +#. Start the VNC service script and also set it to start automatically on + boot for each user. Substitute the [X] with the display ID. + + .. code-block:: console + + # systemctl daemon-reload + # systemctl start vncserver@:[X].service + # systemctl enable vncserver@:[X].service + +#. After starting the services, verify they are running. + + .. code-block:: console + + # systemctl | grep vnc + + Below is an example of 2 VNC sessions that were successfully started for + users `vnc-user-b` with display ID 5 and `vnc-user-c` with display ID 6. + + .. code-block:: console + + # systemctl | grep vnc + + vncserver@:5.services loaded active running VNC Remote Desktop Service for "vnc-user-b" with display ID "5" + vncserver@:6.services loaded active running VNC Remote Desktop Service for "vnc-user-c" with display ID "6" + system-vncserver.slice loaded active active system-vncserver.slice + +Method 3: Multi-user logins with authentication through GDM +=========================================================== + +For this method, VNC is configured as a systemd service that listens on port +5900 and GDM is configured to accept access requests from VNC. When you +make a VNC connection to your |CL| host, you'll be presented with the GDM login +screen and you authenticate as if you're local. You must have root privileges +to perform this configuration. + +#. Log in and get root privileges. + + .. code-block:: console + + $ sudo -s + +#. Create the path `/etc/systemd/system`. + + .. code-block:: console + + # mkdir -p /etc/systemd/system + +#. Create a systemd socket file :file:`xvnc.socket` and add the following: + + .. code-block:: console + + # cat > /etc/systemd/system/xvnc.socket << EOF + + [Unit] + Description=XVNC Server on port 5900 + + [Socket] + ListenStream=5900 + Accept=yes + + [Install] + WantedBy=sockets.target + + EOF + +#. Create a systemd service file :file:`xvnc@.service` and add the following: + + .. code-block:: console + + # cat > /etc/systemd/system/xvnc@.service << EOF + + [Unit] + Description=Daemon for each XVNC connection + + [Service] + ExecStart=-/usr/bin/Xvnc -inetd -query localhost -geometry 2000x1200 -once -SecurityTypes=None + User=nobody + StandardInput=socket + StandardError=syslog + + EOF + +#. Create the path `/etc/gdm`. + + .. code-block:: console + + # mkdir -p /etc/gdm + + +#. Create a GDM :file:`custom.conf` file and add the following: + + .. code-block:: console + + # cat > /etc/gdm/custom.conf << EOF + + [xdmcp] + Enable=true + Port=177 + + EOF + +#. Start the VNC socket script and also set it to start automatically on boot. + + .. code-block:: console + + # systemctl daemon-reload + # systemctl start xvnc.socket + # systemctl enable xvnc.socket + +#. After starting the socket, verify it is running. + + .. code-block:: console + + # systemctl | grep vnc + + Below is an example that shows the xvnc.socket is running. + + .. code-block:: console + + # systemctl | grep vnc + + xvnc.socket loaded active listening XVNC Server on port 5900 + system-xvnc.slice loaded active active system-xvnc.slice + +See the `vncserver` Man page for additional information. + +Install a VNC viewer app and an SSH client on your client system +**************************************************************** + +You need a VNC viewer app on your client system to connect to your |CL| host. +An SSH client is only needed if you chose to use `Method 1` or you plan to encrypt +your VNC traffic, which is discussed later in this guide. + +Follow these steps to add these apps to your client system. + +Install a VNC viewer app +======================== + +* On Linux distros (some examples): + + * |CL|: + + .. code-block:: console + + # swupd bundle-add desktop-autostart + + * Ubuntu, Mint: + + .. code-block:: console + + # apt-get install xtightvncviewer + + * Fedora: + + .. code-block:: console + + # dnf install tigervnc +* On Windows: + + * Install `RealVNC for Windows`_ + +* On macOS: + + * Install `RealVNC for macOS`_ or + * Use the built-in `Screen Sharing` app + +Install an SSH client +===================== + +* On most Linux distros (Clear Linux, Ubuntu, Mint, Fedora, etc.) and macOS, + SSH is built-in so you don't need to install it. +* On Windows, you can install `Putty`_. + +Establish a VNC connection to your Clear Linux host +*************************************************** + +Steps to establishing a VNC connection depends on which VNC-server-configuration +method you chose. + +If you chose `Method 1`, you must take a few extra steps by +SSH'ing into your |CL| host and then manually launching VNC. + +If you chose `Method 2`, get your pre-assigned VNC display ID from your system +administrator first and then proceed to the :ref:`connect-to-vnc-session` +section below. + +If you chose `Method 3`, simply proceed to the +:ref:`connect-to-vnc-session` below. + + +SSH into your Clear Linux host and launch VNC +============================================= + +#. SSH into your Clear Linux host. + + * On Linux distros and macOS: + + .. code-block:: console + + $ ssh [username]@[clear-linux-host-ip-address] + + * On Windows: + + #. Launch Putty. + #. Under the :guilabel:`Category` section, select :guilabel:`Session`. + See Figure 1. + #. Enter the IP address of your Clear Linux host in the + :guilabel:`Host Name (or IP address)` field. + #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. + + .. figure:: figures/vnc/vnc-1.png + :scale: 90 % + :alt: Putty - configure SSH session settings + + Figure 1: Putty - configure SSH session settings + + #. Click the :guilabel:`Open` button. + +#. Log in with your |CL| username and password (not with your VNC password). +#. Start a VNC session. + + .. code-block:: console + + $ vncserver + + + Example output: + + .. code-block:: console + + $ vncserver + + New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3 + + Starting applications specified in /home/vnc-user-c/.vnc/xstartup + Log file is /home/vnc-user-c/.vnc/clr-linux:3.log + +#. Take note of the generated display ID. You will input it into the VNC viewer + viewer app to establish the connection later. The above example shows + the display ID is 3. + + .. note:: + + VNC automatically picks a unique display ID unless you specify one. + To do that, you simply enter a unique number that is not already + in use after the colon. For example: + + .. code-block:: console + + $ vncserver :8 + +#. You can now end the SSH connection by logging out if you'd like. This will + not terminate your active VNC session. + +.. _connect-to-vnc-session: + +Connect to your VNC session +=========================== + +For `Method 1` and `Method 2`, you have to connect to a specific active session +(or display ID). There are two ways you can specify it. You can use a +fully-qualified VNC port number, which consists of the default VNC server port +(5900) plus the display ID or just simply the display ID. +For example: if the display ID is 3, it can be specified as `5903` or just as `3`. + +For `Method 3`, VNC does not expect a display ID. Just use `5900`. + +For simplicity, and to avoid confusions, the instructions below will only use +the fully-qualified VNC port number. + +#. Initiate the VNC connection: + + * On Linux distros: + + #. Open a terminal emulator and enter: + + .. code-block:: console + + $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] + + * On Windows and macOS (using RealVNC app): + + #. Start the RealVNC viewer app. See Figure 2. + #. Enter the IP address of the Clear Linux host and the fully-qualified + VNC port number. + + Here's a screenshot example which shows connecting to |CL| host + 192.168.25.54 with a fully-qualified VNC port number 5902. + + .. figure:: figures/vnc/vnc-2.png + :scale: 90 % + :alt: RealVNC Viewer + + Figure 2: RealVNC Viewer + + #. Press the :kbd:`Enter` key. + + .. note:: + + By default, the image quality setting in RealVNC viewer is low. + You can increase it by changing the `ColorLevel` value. + Follow these + steps: + + #. Right-click a connection node and select :guilabel:`Properties...`. + See Figure 3. + + .. figure:: figures/vnc/vnc-3.png + :scale: 90 % + :alt: RealVNC Viewer - change connection node properties + + Figure 3: RealVNC Viewer - change connection node properties + + #. Select the :guilabel:`Expert` tab. See Figure 4. + + .. figure:: figures/vnc/vnc-4.png + :scale: 90 % + :alt: RealVNC Viewer - change ColorLevel + + Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` + + #. Select the :guilabel:`ColorLevel` setting and change it to + your preferred setting. + + * On macOS (using the macOS built-in `Screen Sharing` app): + + .. note:: + + * Don't use the macOS `Screen Sharing` app for `Method 3` + because it only allows you to enter a VNC password. It doesn't + present the GDM login screen which gives you the ability to + select your username and enter a password as required for `Method 3` + to work. + * The built-in `Screen Sharing` app requires you to always use the + complete VNC port number (for example: `vnc://clear-linux-host-ip-address:5902` + instead of `vnc://clear-linux-host-ip-address:2`) when making a connection. + + #. Go to :guilabel:`Finder` > :guilabel:`Go` > :guilabel:`Connect to Server`. + #. Enter `vnc://[clear-linux-host-ip-address]:[fully-qualified VNC port number]` + in the :guilabel:`Server Address` field. See Figure 5. + + Here's a screenshot example which shows connecting to |CL| host + 192.168.25.54 with a fully-qualified VNC port number 5902. + + .. figure:: figures/vnc/vnc-5.png + :scale: 90 % + :alt: macOS Screen Sharing app + + Figure 5: macOS `Screen Sharing` app + + #. Click Connect. + +#. When connected, enter your credentials. + + * For `Method 1` and `Method 2`, enter your VNC password. No username + is required. + * For `Method 3`, enter your |CL| account username and password through + GDM. + +.. note:: + + With `Method 3`, you cannot remotely log into your |CL| host through VNC + if you're logged in locally and vice-versa. + +Terminate a VNC connection to your Clear Linux host +*************************************************** + +* For `Method 1` and `Method 2`, once started, a VNC session will remain active + on your |CL| host even if you close your VNC viewer app. If you want to truly + terminate an active VNC session, follow these steps: + + #. SSH into your Clear Linux host. + #. Open a terminal emulator. + #. Find the active VNC session display ID with the :command:`vncserver -list` + command. + + .. code-block:: console + + $ vncserver -list + + #. Terminate it with the :command:`vncserver -kill` command followed by a colon + and then the display ID. + + .. code-block:: console + + $ vncserver -kill :[display ID] + +* For `Method 3`, only the system administrator can stop and disable the VNC + service with these commands: + + .. code-block:: console + + # systemctl stop xvnc.socket + # systemctl disable xnvc.socket + + +Encrypt VNC traffic through an SSH tunnel +***************************************** + +By default, VNC traffic is not encrypted. Figure 6 shows an example warning +from RealVNC Viewer. + + .. figure:: figures/vnc/vnc-6.png + :scale: 90 % + :alt: RealVNC Viewer - Connection not encrypted warning + + Figure 6: RealVNC Viewer - Connection not encrypted warning + +To add security, VNC traffic can be routed through an SSH tunnel. + +This is accomplished by following these three steps: + +#. Configure the VNC server to only accept connection from localhost by + adding the `-localhost` option. +#. Set up an SSH tunnel between your client system and your |CL| host. + Your client system will forward traffic from the localhost (the client) + destined for a specified fully-qualified VNC port number (on the client) + to your |CL| host with the same port number. +#. The VNC viewer app on your client system will now connect to localhost, + instead of the IP address of your |CL| host. + +Configure VNC to only accept connection from localhost +====================================================== +* For `Method 1`: + + #. Edit the :file:`config` file located in `%HOME/.vnc` and uncomment the + `# localhost` line. It should look like this: + + .. code-block:: console + + ## Supported server options to pass to vncserver upon invocation can be listed + ## in this file. See the following manpages for more: vncserver(1) Xvnc(1). + ## Several common ones are shown below. Uncomment and modify to your liking. + ## + # securitytypes=vncauth,tlsvnc + # desktop=sandbox + # geometry=2000x1200 + localhost + # alwaysshared + + #. If an active session exists, kill it, and then restart it. + +* For `Method 2`: + + #. Edit the systemd service script :file:`vncserver@:[X].service` located in + `/etc/systemd/system` and add `-localhost` to the `ExecStart` line. + Here's an example for vncserver@:5.service: + + .. code-block:: console + + [Unit] + Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5" + After=syslog.target network.target + + [Service] + Type=simple + User=vnc-user-b + PAMName=login + PIDFile=/home/%u/.vnc/%H%i.pid + ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :' + ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -localhost -alwaysshared -fg + ExecStop=/usr/bin/vncserver -kill %i + + [Install] + WantedBy=multi-user.target + + #. Restart the service script: + + .. code-block:: console + + # systemctl daemon-load + # systemctl restart vncserver@:5.service + +* For `Method 3`: + + #. No change is needed to the :file:`xvnc@service` script. + +After you have restarted your VNC session, you can verify that it's only accepting +connection from localhost by using the :command:`netstat` command like this: + + .. code-block:: console + + $ netstat -plant + + .. note:: + + Add the |CL| `network-basic` bundle to get the :command:`netstat` command. + +Figure 7 is an example which shows two VNC sessions (5901 and 5905) accepting +connections from any host as specified by the `0.0.0.0`'s. This is before the +`-localhost` option was used. + +.. figure:: figures/vnc/vnc-7.png + :scale: 100 % + :alt: VNC session accepting connection from any host + + Figure 7: VNC sessions (5901 and 5905) accepting connections from any host + +Figure 8 is an example which shows two VNC sessions (5901 and 5905) only +accepting connections from localhost as specified by `127.0.0.1`'s. +This is after the `-localhost` option was added. + +.. figure:: figures/vnc/vnc-7.png + :scale: 100 % + :alt: VNC session only accepting connection from localhost + + Figure 8: VNC sessions (5901 and 5905) only accepting connections from localhost + +Set up an SSH tunnel from your client system to your |CL| host +============================================================== + +* On Linux distros and macOS: + + #. Open terminal emulator and enter: + + .. code-block:: console + + $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ + -N -f -l [username] [clear-linux-host-ip-address] + + #. Enter your |CL| account password (not your VNC password). + + .. note:: + + * `-L` specifies that [client port number] on the localhost + (on the client side) is forwarded to [fully-qualified VNC port + number] (on the server side). + * Replace `[client port number]` with an available client port number + (for example: 1234). For simplicity, you can make the + `[client port number]` the same as the `[fully-qualified VNC port number]`. + * Replace `[fully-qualified VNC port number]` with 5900 (default VNC + port) plus the display ID. For example, if the display ID is 2, + the fully-qualified VNC port number is is 5902. + * `-N` tells SSH to only forward ports and not execute a remote command. + * `-f` tells SSH to go into the background before command execution. + * `-l` specifies the username to log in as. + +* On Windows: + + #. Launch Putty. + #. Specify the |CL| VNC host to connect to. + + #. Under the :guilabel:`Category` section, select :guilabel:`Session`. + See Figure 1. + #. Enter the IP address of your Clear Linux host in the + :guilabel:`Host Name (or IP address)` field. + #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. + + #. Configure the SSH tunnel. See Figure 9 for an example. + + #. Under the :guilabel:`Category` section, go to + :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`. + #. In the :guilabel:`Source port` field, enter an available client + port number (for example: 1234). For simplicity, you can make the + `Source port` the same as the fully-qualified VNC port number. + #. In the :guilabel:`Destination` field, enter + `localhost:` plus the fully-qualified VNC port number. + #. Click the :guilabel:`Add` button. + + .. figure:: figures/vnc/vnc-9.png + :scale: 100 % + :alt: Putty - configure SSH tunnel + + Figure 9: Putty - configure SSH tunnel + + #. Click the :guilabel:`Open` button. + #. Enter your |CL| account password (not your VNC password). + +Connect to a VNC session through an SSH tunnel +============================================== + +After you have set up an SSH tunnel, follow these instructions to connect to +your VNC session. + +* On Linux distros: + + #. Open terminal emulator and enter: + + .. code-block:: console + + $ vncviewer localhost:[client port number] + +* On Windows and macOS (using RealVNC): + + #. Start the RealVNC viewer app. + #. Enter `localhost` and the fully-qualified VNC port number. See + Figure 10 for an example. + + .. figure:: figures/vnc/vnc-10.png + :scale: 100 % + :alt: RealVNC viewer app connecting to localhost:1234 + + Figure 10: RealVNC viewer app connecting to `localhost:1234` + + .. note:: + + RealVNC will still warn that the connection is not encrypted even + though its traffic is going through the SSH tunnel. You can ignore + this. + +* On macOS (using built-in `Screen Sharing` app): + + .. note:: + + * Don't use the macOS `Screen Sharing` app for `Method 3` + because it only allows you to enter a VNC password. It doesn't + present the GDM login screen which gives you the ability to + select your username and enter a password as required for `Method 3` + to work. + + #. Go to :guilabel:`Finder` > :guilabel:`Go` > :guilabel:`Connect to Server`. + #. Enter `vnc://localhost:[client port number]` in the + :guilabel:`Server Address` field. See Figure 11. + + .. figure:: figures/vnc/vnc-11.png + :scale: 100 % + :alt: macOS Screen Sharing app connecting to localhost:1234 + + Figure 11: macOS `Screen Sharing` app connecting to `localhost:1234` + + #. Click the :guilabel:`Connect` button. + #. Enter your VNC password. + + +.. _RealVNC for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/ +.. _RealVNC for macOS: https://www.realvnc.com/en/connect/download/viewer/macos/ +.. _Putty: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html +