From 5e8976bfa1d7937c5ffde1af83c0ed164b507c53 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Fri, 23 Mar 2018 14:55:14 -0700 Subject: [PATCH 1/2] Flattens nested content in several sections to simplify use cases; fixes grammatical and stylistic errors. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/network/vnc.rst | 936 +++++++++++----------- 1 file changed, 468 insertions(+), 468 deletions(-) diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst index fdcfeac3..c81a7397 100644 --- a/source/clear-linux/guides/network/vnc.rst +++ b/source/clear-linux/guides/network/vnc.rst @@ -8,38 +8,38 @@ allows you to connect via 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 |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 configure VNC to work on your |CL| host, install these bundles: -* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets - it to start automatically on boot, and installs TigerVNC Viewer. -* `vnc-server`: Installs the TigerVNC server. -* `openssh-server`: Installs an SSH server. +* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets + it to start automatically on boot, and 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. +#. Log into your |CL| host and get root privileges. - .. code-block:: console + .. code-block:: console - $ sudo -s + $ sudo -s -#. Install the |CL| bundles. - - .. code-block:: console +#. Install the |CL| bundles. - # swupd bundle-add desktop-autostart vnc-server openssh-server + .. code-block:: console + + # swupd bundle-add desktop-autostart vnc-server openssh-server -#. Reboot your |CL| host. +#. Reboot your |CL| host. Configure a VNC-server-start method on your Clear Linux host ************************************************************ @@ -94,245 +94,242 @@ Method 1: Manually start a VNC session You (and each user) must perform these steps to initialize your 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. +#. 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 + .. code-block:: console - Example output: + $ vncserver - .. code-block:: console - - $ vncserver + Example output: - You will require a password to access your desktops. + .. code-block:: console - Password: - Verify: - Would you like to enter a view-only password (y/n)? n - xauth: file /home/vnc-user-a/.Xauthority does not exist + $ vncserver - New 'clr-linux:2 (vnc-user-a)' desktop is clr-linux:2 + You will require a password to access your desktops. - 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 + Password: + Verify: + Would you like to enter a view-only password (y/n)? n + xauth: file /home/vnc-user-a/.Xauthority does not exist - Upon completion, you can find the default configuration files and the - password file hidden in the `.vnc` directory in your home directory. + New 'clr-linux:2 (vnc-user-a)' desktop is clr-linux:2 - Also, a VNC session starts and shows 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 to - your VNC viewer app for connection. + 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 -#. 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: + Upon completion, you can find the default configuration files and the + password file hidden in the `.vnc` directory in your home directory. - .. code-block:: console + Also, a VNC session starts and shows 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 to + your VNC viewer app for connection. - $ vncserver -kill :2 +#. 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: - .. note:: + .. code-block:: console - If you do not recall the active session display ID, use the - :command:`vncserver -list` command to find it. + $ vncserver -kill :2 -#. Optional configurations: - - * To customize settings such as screen size, security type, etc., - modify the :file:`%HOME/.vnc/config` file. - * To customize the applications to run at startup, - modify the :file:`%HOME/.vnc/xstartup` file. + .. note:: + + If you do not recall the active session display ID, use the + :command:`vncserver -list` command to find it. + +#. Optional configurations: + + * To customize settings such as screen size, security type, etc., + modify the :file:`%HOME/.vnc/config` file. + * To customize the applications to run at startup, modify the + :file:`%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 all intended VNC users with their own +To configure VNC for this method, you must have root privileges. You will +set up a systemd service file for all intended VNC users with their own preassigned unique display ID. -#. Log in and get root privileges. +#. Log in and get root privileges. - .. code-block:: console + .. code-block:: console - $ sudo -s + $ sudo -s -#. Make sure the user accounts already exist. Use the following command to - list all users. +#. Make sure the user accounts already exist. Use the following command to + list all users. - .. code-block:: console + .. code-block:: console - # cut -d: -f1 /etc/passwd + # cut -d: -f1 /etc/passwd -#. Create the path :file:`/etc/systemd/system`. +#. Create the path :file:`/etc/systemd/system`. - .. code-block:: console + .. code-block:: console - # mkdir -p /etc/systemd/system + # 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 :file:`/etc/systemd/system`. Each user - must be assigned a unique display ID. Be sure the correct username is entered - in the `User` field. The example below shows user `vnc-user-b` who is - assigned the display ID `5`. +#. Create a systemd service script file :file:`vncserver@:[X].service`, + where [X] is the display ID, for each user in :file:`/etc/systemd/system` + Each user must be assigned a unique display ID. Be sure the correct + username is entered in the `User` field. The example below shows user + `vnc-user-b` who is assigned the display ID `5`. - .. code-block:: console + .. code-block:: console - # cat > /etc/systemd/system/vncserver@:5.service << EOF + # 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 + [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 + [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 + [Install] + WantedBy=multi-user.target - EOF + EOF -#. Have each user log into their account and set a VNC password with - the :command:`vncpasswd` command before proceeding to the next step. +#. Have each user log into their account and set a VNC password with + the :command:`vncpasswd` command before proceeding to the next step. -#. Start the VNC service script and set it to start automatically on - boot for each user. Replace the [X] with the display ID. +#. Start the VNC service script and set it to start automatically on + boot for each user. Replace the [X] with the display ID. - .. code-block:: console + .. code-block:: console - # systemctl daemon-reload - # systemctl start vncserver@:[X].service - # systemctl enable vncserver@:[X].service + # systemctl daemon-reload + # systemctl start vncserver@:[X].service + # systemctl enable vncserver@:[X].service -#. After starting the services, verify they are running. +#. After starting the services, verify they are running. - .. code-block:: console + .. code-block:: console - # systemctl | grep vnc + # systemctl | grep vnc - The example below shows 2 VNC sessions that were successfully started for - users `vnc-user-b` with display ID 5 and `vnc-user-c` with display ID 6. + The example below shows 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 + .. code-block:: console - # systemctl | grep vnc + # 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 + 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 are presented with the GDM login -screen and you authenticate as if you are local. You must have root privileges -to perform this configuration. +make a VNC connection to your |CL| host, you are presented with the GDM login screen and you authenticate as if you are local. You must have root privileges to perform this configuration. -#. Log in and get root privileges. +#. Log in and get root privileges. - .. code-block:: console + .. code-block:: console - $ sudo -s + $ sudo -s -#. Create the path :file:`/etc/systemd/system`. +#. Create the path :file:`/etc/systemd/system`. - .. code-block:: console + .. code-block:: console - # mkdir -p /etc/systemd/system + # mkdir -p /etc/systemd/system -#. Create a systemd socket file :file:`xvnc.socket` and add the following: +#. Create a systemd socket file :file:`xvnc.socket` and add the following: - .. code-block:: console + .. code-block:: console - # cat > /etc/systemd/system/xvnc.socket << EOF + # cat > /etc/systemd/system/xvnc.socket << EOF - [Unit] - Description=XVNC Server on port 5900 + [Unit] + Description=XVNC Server on port 5900 - [Socket] - ListenStream=5900 - Accept=yes + [Socket] + ListenStream=5900 + Accept=yes - [Install] - WantedBy=sockets.target + [Install] + WantedBy=sockets.target - EOF + EOF -#. Create a systemd service file :file:`xvnc@.service` and add the following: +#. Create a systemd service file :file:`xvnc@.service` and add the following: - .. code-block:: console + .. code-block:: console - # cat > /etc/systemd/system/xvnc@.service << EOF + # cat > /etc/systemd/system/xvnc@.service << EOF - [Unit] - Description=Daemon for each XVNC connection + [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 + [Service] + ExecStart=-/usr/bin/Xvnc -inetd -query localhost -geometry 2000x1200 -once -SecurityTypes=None + User=nobody + StandardInput=socket + StandardError=syslog - EOF + EOF -#. Create the path :file:`/etc/gdm`. +#. Create the path :file:`/etc/gdm`. - .. code-block:: console + .. code-block:: console - # mkdir -p /etc/gdm + # mkdir -p /etc/gdm -#. Create a GDM :file:`custom.conf` file and add the following: +#. Create a GDM :file:`custom.conf` file and add the following: - .. code-block:: console + .. code-block:: console - # cat > /etc/gdm/custom.conf << EOF + # cat > /etc/gdm/custom.conf << EOF - [xdmcp] - Enable=true - Port=177 + [xdmcp] + Enable=true + Port=177 - EOF + EOF -#. Start the VNC socket script and set it to start automatically on boot. +#. Start the VNC socket script and set it to start automatically on boot. - .. code-block:: console + .. code-block:: console - # systemctl daemon-reload - # systemctl start xvnc.socket - # systemctl enable xvnc.socket + # systemctl daemon-reload + # systemctl start xvnc.socket + # systemctl enable xvnc.socket -#. After starting the socket, verify it is running. +#. After starting the socket, verify it is running. - .. code-block:: console + .. code-block:: console - # systemctl | grep vnc + # systemctl | grep vnc - The example below shows the xvnc.socket is running. + The example below shows the xvnc.socket is running. - .. code-block:: console + .. code-block:: console - # systemctl | grep vnc + # systemctl | grep vnc - xvnc.socket loaded active listening XVNC Server on port 5900 - system-xvnc.slice loaded active active system-xvnc.slice + 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. @@ -340,49 +337,47 @@ 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. +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. Perform the steps below to add these apps to your client system. Install a VNC viewer app ======================== -* On Linux distros (some examples): +#. On |CL|: - * |CL|: - - .. code-block:: console - - # swupd bundle-add desktop-autostart + .. code-block:: console - * Ubuntu, Mint: + # swupd bundle-add desktop-autostart - .. code-block:: console +#. On Ubuntu, Mint: - # apt-get install xtightvncviewer + .. code-block:: console - * Fedora: + # apt-get install xtightvncviewer - .. code-block:: console +#. On Fedora: - # dnf install tigervnc + .. code-block:: console -* On Windows: + # dnf install tigervnc - * Install `RealVNC for Windows`_ +#. On Windows: -* On macOS: + * Install `RealVNC for Windows`_ + +#. On macOS: - * Install `RealVNC for macOS`_ or - * Use the built-in `Screen Sharing` app + * 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`_. +* 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 *************************************************** @@ -392,9 +387,9 @@ Depending on the VNC-server-configuration method chosen, use the appropriate VNC If you chose `Method 1`, you must take a few extra steps by using SSH to connect to your |CL| host and then manually launching VNC. -If you chose `Method 2`, get your preassigned VNC display ID from your system -administrator first and then proceed to the :ref:`connect-to-vnc-session` -section below. +If you chose `Method 2`, get your preassigned 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`, proceed to the :ref:`connect-to-vnc-session` below. @@ -403,66 +398,67 @@ If you chose `Method 3`, proceed to the SSH into your Clear Linux host and launch VNC ============================================= -#. SSH into your Clear Linux host. +SSH into your Clear Linux host +------------------------------ +#. On Linux distros and macOS: - * On Linux distros and macOS: + .. code-block:: console - .. code-block:: console + $ ssh [username]@[clear-linux-host-ip-address] - $ ssh [username]@[clear-linux-host-ip-address] +#. On Windows: - * 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 + * 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`. + * Click the :guilabel:`Open` button. - #. Click the :guilabel:`Open` button. + .. figure:: figures/vnc/vnc-1.png + :scale: 90 % + :alt: Putty - configure SSH session settings -#. Log in with your |CL| username and password. Do not use your VNC password. -#. Start a VNC session. - - .. code-block:: console - - $ vncserver + Figure 1: Putty - configure SSH session settings - Example output: - .. code-block:: console +#. Log in with your |CL| username and password. Do not use your VNC + password. +#. Start a VNC session. - $ vncserver + .. code-block:: console - New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3 + $ vncserver - Starting applications specified in /home/vnc-user-c/.vnc/xstartup - Log file is /home/vnc-user-c/.vnc/clr-linux:3.log + Example output: -#. Take note of the generated display ID, because you will input it into the VNC viewer - viewer app to establish the connection. The above example shows - the display ID is 3. + .. code-block:: console - .. note:: + $ vncserver - VNC automatically picks a unique display ID unless you specify one. - To specify a display ID, enter a unique number that is not already - in use after the colon. For example: + New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3 - .. code-block:: console + Starting applications specified in /home/vnc-user-c/.vnc/xstartup + Log file is /home/vnc-user-c/.vnc/clr-linux:3.log - $ vncserver :8 +#. Take note of the generated display ID because you will input it into + the VNC viewer app to establish the connection. The above example shows + the display ID is 3. -#. You can now end the SSH connection by logging out. This does - not terminate your active VNC session. + .. note:: + + VNC automatically picks a unique display ID unless you specify one. + To specify a display ID, 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. This does + not terminate your active VNC session. .. _connect-to-vnc-session: @@ -470,138 +466,141 @@ Connect to your VNC session =========================== For `Method 1` and `Method 2`, you must connect to a specific active session -or display ID using one of two options. You can use a -fully-qualified VNC port number, which consists of the default VNC server port -(5900) plus the display ID or you can use the display ID. -For example, if the display ID is 3, it can be specified as `5903` or just as `3`. +or display ID using one of two options: -For `Method 3`, VNC does not expect a display ID. Use `5900`. +* Use a fully-qualified VNC port number, which consists of the default VNC + server port (5900) plus the display ID +* Use the display ID -For simplicity, the instructions below use the fully-qualified VNC port number. +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. Use `5900`. For simplicity, the instructions below use the fully-qualified VNC port +number. -#. Initiate the VNC connection: - - * On Linux distros: +#. Initiate the VNC connection: - #. Open a terminal emulator and enter: - - .. code-block:: console + On Linux distros: - $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] + * Open a terminal emulator and enter: - * 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. - - The following screenshot 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 + .. code-block:: console - #. Press the :kbd:`Enter` key. + $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] - .. note:: + On Windows and macOS using `RealVNC` app: - By default, the image quality setting in RealVNC viewer is low. - You can increase it by changing the `ColorLevel` value as described - in the following steps: + * Start the RealVNC viewer app. See Figure 2. + * Enter the IP address of the Clear Linux host and the fully-qualified + VNC port number. - #. Right-click a connection node and select :guilabel:`Properties...`. - See Figure 3. + The following screenshot shows connecting to |CL| host + 192.168.25.54 with a fully-qualified VNC port number 5902. - .. figure:: figures/vnc/vnc-3.png - :scale: 90 % - :alt: RealVNC Viewer - change connection node properties + .. figure:: figures/vnc/vnc-2.png + :scale: 90 % + :alt: RealVNC Viewer - Figure 3: RealVNC Viewer - change connection node properties + Figure 2: RealVNC Viewer - #. Select the :guilabel:`Expert` tab. See Figure 4. + * Press the :kbd:`Enter` key. - .. figure:: figures/vnc/vnc-4.png - :scale: 90 % - :alt: RealVNC Viewer - change ColorLevel + .. note:: - Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` + By default, the image quality setting in RealVNC viewer is low. + You can increase it by changing the `ColorLevel` value as described + in the following steps: - #. Select the :guilabel:`ColorLevel` setting and change it to - your preferred setting. + Right-click a connection node and select :guilabel:`Properties...`. + See Figure 3. - * On macOS (using the macOS built-in `Screen Sharing` app): + .. figure:: figures/vnc/vnc-3.png + :scale: 90 % + :alt: RealVNC Viewer - change connection node properties - .. note:: + Figure 3: RealVNC Viewer - change connection node properties - * If you chose `Method 3`, you cannot use the macOS `Screen Sharing` app - because it only allows you to enter a VNC password. The app does not - 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. + Select the :guilabel:`Expert` tab. See Figure 4. - #. 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. - - The following screenshot shows connecting to |CL| host - 192.168.25.54 with a fully-qualified VNC port number 5902. + .. figure:: figures/vnc/vnc-4.png + :scale: 90 % + :alt: RealVNC Viewer - change ColorLevel - .. figure:: figures/vnc/vnc-5.png - :scale: 90 % - :alt: macOS Screen Sharing app + Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` - Figure 5: macOS `Screen Sharing` app + Select the :guilabel:`ColorLevel` setting and change it to your + preferred setting. - #. Click Connect. + On macOS using the built-in `Screen Sharing` app: -#. When connected, enter your credentials. + .. note:: - * 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. + If you chose `Method 3`, you cannot use the macOS `Screen Sharing` + app because it only allows you to enter a VNC password. The app + does not 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 when making a connection + (for example: `vnc://clear-linux-host-ip-address:5902` instead of + `vnc://clear-linux-host-ip-address:2`). -.. note:: + * 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. - With `Method 3`, you cannot remotely log into your |CL| host through VNC - if you are logged in locally and vice versa. + The following screenshot 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 are 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 remains 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: +For `Method 1` and `Method 2`, once started, a VNC session remains 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. +#. SSH into your Clear Linux host. +#. Open a terminal emulator. +#. Find the active VNC session display ID with the command + :command:`vncserver -list`. - .. code-block:: console + .. code-block:: console - $ vncserver -list + $ vncserver -list - #. Terminate it with the :command:`vncserver -kill` command followed by a colon - and the display ID. +#. Terminate it with the :command:`vncserver -kill` command followed by a + colon and the display ID. - .. code-block:: console + .. code-block:: console - $ vncserver -kill :[display ID] + $ vncserver -kill :[display ID] -* For `Method 3`, only the system administrator can stop and disable the VNC - service by using these commands: +#. For `Method 3`, only the system administrator can stop and disable the + VNC service by using these commands: - .. code-block:: console + .. code-block:: console - # systemctl stop xvnc.socket - # systemctl disable xnvc.socket + # systemctl stop xvnc.socket + # systemctl disable xnvc.socket Encrypt VNC traffic through an SSH tunnel @@ -610,171 +609,173 @@ 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:: figures/vnc/vnc-6.png + :scale: 90 % + :alt: RealVNC Viewer - Connection not encrypted warning - Figure 6: 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. +To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps: -This is accomplished by following these 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 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 :file:`%HOME/.vnc` and uncomment the - `# localhost` line. It should look like this: +For `Method 1`: - .. code-block:: console +#. Edit the :file:`config` file located in :file:`%HOME/.vnc` and uncomment + the `# localhost` line. It should look like this: - ## 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 + .. code-block:: console - #. If an active session exists, kill it, and then restart it. + ## 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 -* For `Method 2`: +#. If an active session exists, kill it, and then restart it. - #. Edit the systemd service script :file:`vncserver@:[X].service` located in - :file:`/etc/systemd/system` and add `-localhost` to the `ExecStart` line. - The example below uses vncserver@:5.service: +For `Method 2`: - .. code-block:: console +#. Edit the systemd service script :file:`vncserver@:[X].service` located in + :file:`/etc/systemd/system` and add `-localhost` to the `ExecStart` + line. The example below uses vncserver@:5.service: - [Unit] - Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5" - After=syslog.target network.target + .. code-block:: console - [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 + [Unit] + Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5" + After=syslog.target network.target - [Install] - WantedBy=multi-user.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 - #. Restart the service script: + [Install] + WantedBy=multi-user.target - .. code-block:: console +#. Restart the service script: - # systemctl daemon-load - # systemctl restart vncserver@:5.service + .. code-block:: console -* For `Method 3`: + # systemctl daemon-load + # systemctl restart vncserver@:5.service - #. No change is needed to the :file:`xvnc@service` script. +For `Method 3`: -After you have restarted your VNC session, you can verify that it only accepts -connections from localhost by using the :command:`netstat` command like this: +#. No change is needed to the :file:`xvnc@service` script. - .. code-block:: console + After you have restarted your VNC session, you can verify that it only + accepts connections from localhost by using the :command:`netstat` + command like this: + + .. code-block:: console - $ netstat -plant + $ netstat -plant - .. note:: + .. note:: - Add the |CL| `network-basic` bundle to get the :command:`netstat` command. + Add the |CL| `network-basic` bundle to get the :command:`netstat` + command. -Figure 7 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 7 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 + :scale: 100 % + :alt: VNC session accepting connection from any host Figure 7: VNC sessions (5901 and 5905) accepting connections from any host -Figure 8 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 used. +Figure 8 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 used. .. figure:: figures/vnc/vnc-8.png - :scale: 100 % - :alt: VNC session only accepting connection from localhost + :scale: 100 % + :alt: VNC session only accepting connection from localhost - Figure 8: VNC sessions (5901 and 5905) only accepting connections 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: +On Linux distros and macOS: - #. Open terminal emulator and enter: +#. Open terminal emulator and enter: - .. code-block:: console + .. code-block:: console - $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ - -N -f -l [username] [clear-linux-host-ip-address] + $ 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). +#. Enter your |CL| account password (not your VNC password). - .. note:: + .. 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. + * `-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: +On Windows: - #. Launch Putty. - #. Specify the |CL| VNC host to connect to. +#. 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`. + * 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. + * 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. + - 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:: figures/vnc/vnc-9.png + :scale: 100 % + :alt: Putty - configure SSH tunnel - Figure 9: Putty - configure SSH tunnel + Figure 9: Putty - configure SSH tunnel - #. Click the :guilabel:`Open` button. - #. Enter your |CL| account password (not your VNC password). + * Click the :guilabel:`Open` button. + * Enter your |CL| account password (not your VNC password). Connect to a VNC session through an SSH tunnel ============================================== @@ -782,54 +783,53 @@ 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: +On Linux distros: - #. Open terminal emulator and enter: +#. Open terminal emulator and enter: - .. code-block:: console + .. code-block:: console - $ vncviewer localhost:[client port number] + $ vncviewer localhost:[client port number] -* On Windows and macOS (using RealVNC): +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. +#. 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:: figures/vnc/vnc-10.png + :scale: 100 % + :alt: RealVNC viewer app connecting to localhost:1234 - Figure 10: RealVNC viewer app connecting to `localhost:1234` + Figure 10: RealVNC viewer app connecting to `localhost:1234` - .. note:: + .. 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 warning. + RealVNC will still warn that the connection is not encrypted even + though its traffic is going through the SSH tunnel. You can ignore + this warning. -* On macOS (using built-in `Screen Sharing` app): +On macOS using built-in `Screen Sharing` app: - .. note:: +.. note:: - * If you chose `Method 3`, you cannot use the macOS `Screen Sharing` app - because it only allows you to enter a VNC password. The app does not - 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. + If you chose `Method 3`, you cannot use the macOS `Screen Sharing` app + because it only allows you to enter a VNC password. The app does not + 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. +#. 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:: 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` + Figure 11: macOS `Screen Sharing` app connecting to `localhost:1234` - #. Click the :guilabel:`Connect` button. - #. Enter your VNC password. +#. Click the :guilabel:`Connect` button. +#. Enter your VNC password. .. _RealVNC for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/ From 41fc6c24f7cfeb4774050f6afc998f4f119b76e2 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Mon, 26 Mar 2018 16:37:12 -0700 Subject: [PATCH 2/2] Further flattens nested items overall. Omits use cases on mac using the built-in screen sharing. In Connect to your VNC session, includes steps 1-2 for each use case. Makes configuration of RealVNC optional section--instead of note. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/network/vnc.rst | 256 +++++++++------------- 1 file changed, 106 insertions(+), 150 deletions(-) diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst index c81a7397..2d962b5c 100644 --- a/source/clear-linux/guides/network/vnc.rst +++ b/source/clear-linux/guides/network/vnc.rst @@ -3,8 +3,8 @@ Remote-desktop to a Clear Linux host using VNC ############################################## -:abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool that -allows you to connect via remote-desktop to your |CLOSIA| host. +:abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool +that allows you to connect via remote-desktop to your |CLOSIA| host. This guide shows you how to: @@ -345,32 +345,31 @@ Perform the steps below to add these apps to your client system. Install a VNC viewer app ======================== -#. On |CL|: +On |CL|: - .. code-block:: console +.. code-block:: console - # swupd bundle-add desktop-autostart + # swupd bundle-add desktop-autostart -#. On Ubuntu, Mint: +On Ubuntu, Mint: - .. code-block:: console +.. code-block:: console - # apt-get install xtightvncviewer + # apt-get install xtightvncviewer -#. On Fedora: +On Fedora: - .. code-block:: console +.. code-block:: console - # dnf install tigervnc + # dnf install tigervnc -#. On Windows: +On Windows: - * Install `RealVNC for Windows`_ +* Install `RealVNC for Windows`_ -#. On macOS: +On macOS: - * Install `RealVNC for macOS`_ or - * Use the built-in `Screen Sharing` app +* Install `RealVNC for macOS`_ Install an SSH client ===================== @@ -398,31 +397,29 @@ If you chose `Method 3`, proceed to the SSH into your Clear Linux host and launch VNC ============================================= -SSH into your Clear Linux host ------------------------------- -#. On Linux distros and macOS: +#. SSH into your Clear Linux host - .. code-block:: console + #. On Linux distros and macOS: - $ ssh [username]@[clear-linux-host-ip-address] + .. code-block:: console -#. On Windows: + $ ssh [username]@[clear-linux-host-ip-address] - * 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`. - * Click the :guilabel:`Open` button. + #. On Windows: - .. figure:: figures/vnc/vnc-1.png - :scale: 90 % - :alt: Putty - configure SSH session settings - - Figure 1: Putty - configure SSH session settings + #. 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`. + #. Click the :guilabel:`Open` button. + .. figure:: figures/vnc/vnc-1.png + :scale: 90 % + :alt: Putty - configure SSH session settings + Figure 1: Putty - configure SSH session settings #. Log in with your |CL| username and password. Do not use your VNC password. @@ -476,90 +473,47 @@ 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. Use `5900`. For simplicity, the instructions below use the fully-qualified VNC port number. -#. Initiate the VNC connection: +Initiate VNC and Make a Connection +---------------------------------- - On Linux distros: +**On Linux distros:** - * Open a terminal emulator and enter: +#. Open a terminal emulator and enter: - .. code-block:: console + .. code-block:: console - $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] + $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] - On Windows and macOS using `RealVNC` app: +#. Enter your credentials. - * Start the RealVNC viewer app. See Figure 2. - * Enter the IP address of the Clear Linux host and the fully-qualified - VNC port number. - - The following screenshot 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. + * 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:: - By default, the image quality setting in RealVNC viewer is low. - You can increase it by changing the `ColorLevel` value as described - in the following steps: + With `Method 3`, you cannot remotely log into your |CL| host through + VNC if you are logged in locally and vice versa. - Right-click a connection node and select :guilabel:`Properties...`. - See Figure 3. +**On Windows and macOS using `RealVNC` app:** - .. figure:: figures/vnc/vnc-3.png - :scale: 90 % - :alt: RealVNC Viewer - change connection node properties +#. Start the RealVNC viewer app. See Figure 2. +#. Enter the IP address of the Clear Linux host and the fully-qualified + VNC port number. - Figure 3: RealVNC Viewer - change connection node properties + The following screenshot shows connecting to |CL| host + 192.168.25.54 with a fully-qualified VNC port number 5902. - Select the :guilabel:`Expert` tab. See Figure 4. + .. figure:: figures/vnc/vnc-2.png + :scale: 90 % + :alt: RealVNC Viewer - .. figure:: figures/vnc/vnc-4.png - :scale: 90 % - :alt: RealVNC Viewer - change ColorLevel + Figure 2: RealVNC Viewer - Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` +#. Press the :kbd:`Enter` key. - Select the :guilabel:`ColorLevel` setting and change it to your - preferred setting. - - On macOS using the built-in `Screen Sharing` app: - - .. note:: - - If you chose `Method 3`, you cannot use the macOS `Screen Sharing` - app because it only allows you to enter a VNC password. The app - does not 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 when making a connection - (for example: `vnc://clear-linux-host-ip-address:5902` instead of - `vnc://clear-linux-host-ip-address:2`). - - * 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. - - The following screenshot 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. +#. Enter your credentials. * For `Method 1` and `Method 2`, enter your VNC password. No username is required. @@ -570,6 +524,31 @@ number. With `Method 3`, you cannot remotely log into your |CL| host through VNC if you are logged in locally and vice versa. + +`Optional: Configure RealVNC Image Quality` +------------------------------------------- + +To increase the RealVNC viewer image quality, manually change the `ColorLevel` value. (Default image quality setting is low.) 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. + +#. Select the :guilabel:`ColorLevel` setting and change it to your + preferred setting. + + .. figure:: figures/vnc/vnc-4.png + :scale: 90 % + :alt: RealVNC Viewer - change ColorLevel + + Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` Terminate a VNC connection to your Clear Linux host *************************************************** @@ -717,7 +696,7 @@ Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from Set up an SSH tunnel from your client system to your |CL| host ============================================================== -On Linux distros and macOS: +**On Linux distros and macOS:** #. Open terminal emulator and enter: @@ -744,38 +723,39 @@ On Linux distros and macOS: * `-f` tells SSH to go into the background before command execution. * `-l` specifies the username to log in as. -On Windows: +**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`. + #. 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. +#. Configure the SSH tunnel. See Figure 9 for an example. - - Under the :guilabel:`Category` section, go to - :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`. + #. 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:`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. + #. 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:: figures/vnc/vnc-9.png + :scale: 100 % + :alt: Putty - configure SSH tunnel - Figure 9: Putty - configure SSH tunnel + Figure 9: Putty - configure SSH tunnel - * Click the :guilabel:`Open` button. - * Enter your |CL| account password (not your VNC password). +#. Click the :guilabel:`Open` button. +#. Enter your |CL| account password (not your VNC password). Connect to a VNC session through an SSH tunnel ============================================== @@ -783,7 +763,7 @@ 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: +**On Linux distros:** #. Open terminal emulator and enter: @@ -791,7 +771,7 @@ On Linux distros: $ vncviewer localhost:[client port number] -On Windows and macOS using `RealVNC`: +**On Windows and macOS using `RealVNC`:** #. Start the RealVNC viewer app. #. Enter `localhost` and the fully-qualified VNC port number. See Figure 10 @@ -809,30 +789,6 @@ On Windows and macOS using `RealVNC`: though its traffic is going through the SSH tunnel. You can ignore this warning. -On macOS using built-in `Screen Sharing` app: - -.. note:: - - If you chose `Method 3`, you cannot use the macOS `Screen Sharing` app - because it only allows you to enter a VNC password. The app does not - 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 -