diff --git a/source/clear-linux/concepts/mixer-about.rst b/source/clear-linux/concepts/mixer-about.rst index 7515a995..1caf3764 100644 --- a/source/clear-linux/concepts/mixer-about.rst +++ b/source/clear-linux/concepts/mixer-about.rst @@ -1,14 +1,23 @@ .. _mixer-about: Mixer -####### +##### -Mixing refers to composing a custom, versioned image of |CLOSIA| for a specific use case. While upstream |CL| provides options to install bundles for various capabilities, some developers and OSVs may wish to either augment the operating system with functionality from their own packages or modify the structure of current bundles. Mixing offers a method to add capabilities while retaining the ability to stay up to date with an upstream version of |CL|. +Mixing refers to composing a custom, versioned image of |CL-ATTR| for a +specific use case. While upstream |CL| provides options to install bundles +for various capabilities, some developers and OSVs may wish to either +augment the operating system with functionality from their own packages +or modify the structure of current bundles. Mixing offers a method to add +capabilities while retaining the ability to stay up to date with an upstream +version of |CL|. -Mixing is a multi-step process that starts with installing the mixer bundle using swupd. You will also need a working knowledge of :abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a detailed guide on how to create a |CL| mix, visit :ref:`mixer`. +Mixing is a multi-step process that starts with installing the mixer bundle +using swupd. You will also need a working knowledge of +:abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a +detailed guide on how to create a |CL| mix, visit :ref:`mixer`. -Related Concepts -================ +Related topics +============== * :ref:`swupd-about` * :ref:`bundles-about` diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index f132c229..ef1d9ee0 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -3,35 +3,35 @@ Software update ############### -|CLOSIA| does software updates differently than traditional Linux-based -operating systems. Where traditional distributions rely on packages for -software deployment, |CL| uses the concept of a "bundle" for -deployment. Traditional Linux packages provide a particular utility or -library; |CL| bundles provide all necessary packages to enable a +|CL-ATTR| does software updates differently than traditional Linux-based +operating systems. Where traditional distributions rely on packages for +software deployment, |CL| uses the concept of a "bundle" for +deployment. Traditional Linux packages provide a particular utility or +library; |CL| bundles provide all necessary packages to enable a specific function. -With |CL|, updating equates to an entirely new OS version with a -specific set of bundles, as compared to a package-based distribution in -which packages may be updated individually. |CL| updates are +With |CL|, updating equates to an entirely new OS version with a +specific set of bundles, as compared to a package-based distribution in +which packages may be updated individually. |CL| updates are efficient, updating only changed files instead of entire packages. -System administrators can customize or add bundles to the OS, while still -taking advantage of a controlled update stream. This enables system +System administrators can customize or add bundles to the OS, while still +taking advantage of a controlled update stream. This enables system administrators to focus on the pieces that make their deployment unique. Bundles ======= -While we use packages to manage compiling source code into installable -binaries, we do not deploy software through packages. Instead, we use bundles -to deploy software, where each bundle encapsulates a particular functionality --- functionality that is enabled by composing all the required upstream -open-source projects and packages into one logical unit: a bundle. This +While we use packages to manage compiling source code into installable +binaries, we do not deploy software through packages. Instead, we use bundles +to deploy software, where each bundle encapsulates a particular functionality +-- functionality that is enabled by composing all the required upstream +open-source projects and packages into one logical unit: a bundle. This simplifies installing features on |CL|. -For additional resources regarding available bundles, useful bundle commands, -and compatible |CL| kernels, visit our :ref:`bundles-about` +For additional resources regarding available bundles, useful bundle commands, +and compatible |CL| kernels, visit our :ref:`bundles-about` page. @@ -65,8 +65,8 @@ describe the versions of all the software on the OS. Each build is composed of a specific set of bundles made from a particular version of packages. This matters on a daily basis to system administrators, who need to determine which of their systems do not have the latest security -fixes, or which combinations of software have been tested. Every release -of the same number is guaranteed to contain the same versions of software, +fixes, or which combinations of software have been tested. Every release +of the same number is guaranteed to contain the same versions of software, so there's no ambiguity between two systems running the same version of |CL|. @@ -76,20 +76,20 @@ Updating Another notable difference between package-based distributions and |CL| is how updates are managed. On a package-based OS, system administrators update each individual package or piece of software to a newer (or older!) version. With -|CL|, an update translates to an entirely new OS version, containing one -or many updates. It is not possible to update a piece of the system while +|CL|, an update translates to an entirely new OS version, containing one +or many updates. It is not possible to update a piece of the system while remaining on the same version of |CL|. How is this useful? Although it seems, at first, like a huge restriction or limitation, this method has many non-obvious benefits. Imagine a cloud environment composed of numerous machines. Here, a homogeneous set of software makes sense -- from the system administrator's level down to the -user level. Homogeneous systems allow users to focus on their contributions -and/or code, rather than configuring environments or worrying about -synchronizing versions and updates. At the system admin level, it ensures +user level. Homogeneous systems allow users to focus on their contributions +and/or code, rather than configuring environments or worrying about +synchronizing versions and updates. At the system admin level, it ensures security is tighter and makes it far easier to monitor and update patches. -|CL| promotes regular updating of the OS and will automatically check +|CL| promotes regular updating of the OS and will automatically check for updates and apply them by default. To learn how to run an update of your system, visit our :ref:`swupd-guide` page. @@ -98,9 +98,9 @@ To learn how to run an update of your system, visit our :ref:`swupd-guide` page. Update speed ============ -Software updates with |CL| are also efficient. Bundles simply describe -a set of files, and the update technology updates *only* files that actually -changed by using binary-delta technology for efficiency [1]_. Operating systems +Software updates with |CL| are also efficient. Bundles simply describe +a set of files, and the update technology updates *only* files that actually +changed by using binary-delta technology for efficiency [1]_. Operating systems that use packages as the unit of deployment require full package updates (thus hogging resources), even when one small file in that package has changed. @@ -128,5 +128,5 @@ a controlled update stream. To learn more about mixing, visit our :ref:`mixer-about` page. -.. [1] The software update technology for |CLOSIA| was first presented at the +.. [1] The software update technology for |CL-ATTR| was first presented at the Linux Plumbers conference in 2012. diff --git a/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst b/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst index c0966c09..560e56e3 100644 --- a/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst +++ b/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst @@ -58,7 +58,7 @@ Follow these steps to install |CL| on the target system: #. Reboot the target system. #. The |CL| boot menu will start as shown in figure 1. - Select :guilabel:`Clear Linux OS for Intel Architecture` and press the + Select :guilabel:`Clear Linux OS` and press the :kbd:`Enter` key or wait five seconds to automatically select it. .. figure:: figures/bare-metal-install-1.png diff --git a/source/clear-linux/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst index 9b819057..2f0bced2 100644 --- a/source/clear-linux/guides/deploy-at-scale.rst +++ b/source/clear-linux/guides/deploy-at-scale.rst @@ -1,21 +1,21 @@ .. _deploy-at-scale.rst: -Deploying |CL| at Scale -####################### +Deploy at Scale +############### -Once you are comfortable with `Clear Linux concepts`_, your next step -as a system administrator is to understand how to deploy Clear Linux* -at scale in your environment. +Once you are comfortable with |CL-ATTR| :ref:`concepts `, your next step +as a system administrator is to understand how to deploy |CL| +at scale in your environment. In this document the term *endpoint* refers to a system targeted for |CL| installation, whether that is a datacenter system or unit deployed in -field. +field. .. note:: This is not a replacement or blueprint for designing your own IT - operating environment. - + operating environment. + Your |CL| deployment should complement the existing environment and available tools. It is assumed foundational core IT dependencies of your environment, such as your network, are healthy and scaled to suit the @@ -27,27 +27,27 @@ field. Pick a |CL| usage and update strategy ===================================== -Different business scenarios call for different deployment methodologies. -|CLOSIA| offers the flexibility to continue consuming the upstream |CL| +Different business scenarios call for different deployment methodologies. +|CL| offers the flexibility to continue consuming the upstream |CL| distribution or the option to fork away from the |CL| distribution and -act as your own :abbr:`OSV (Operating System Vendor)`. +act as your own :abbr:`OSV (Operating System Vendor)`. Below are overviews of both approaches and some considerations. Option #1: Use the |CL| as the upstream origin (mixin) ------------------------------------------------------ -This approach is *easier to adopt* by relying on the |CL| upstream for -packaging updates for you to deploy. +This approach is *easier to adopt* by relying on the |CL| upstream for +packaging updates for you to deploy. Custom software or packages that are not available in a preformed bundle -can be added using the `mixin process`_ to form a custom bundle. -If custom bundles are needed, you will be responsible for maintaining -the custom bundle(s) and testing between |CL| releases in your environment, -while the rest of the operating system and preformed bundles come from the +can be added using the `mixin process`_ to form a custom bundle. +If custom bundles are needed, you will be responsible for maintaining +the custom bundle(s) and testing between |CL| releases in your environment, +while the rest of the operating system and preformed bundles come from the |CL| upstream. - -#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated + +#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated to coordinate software updates. #. With autoupdate enabled, |CL| is updated daily, however you may wish to @@ -56,70 +56,70 @@ while the rest of the operating system and preformed bundles come from the yourself which is realistic with the operational expectations of your environment. -#. Use a web caching proxy for |CL| updates for devices connected to - a local area network (LAN), like a datacenter, to increase the speed - and resiliency of updates from the |CL| update servers. - - Your caching proxy server is just like any other web application. +#. Use a web caching proxy for |CL| updates for devices connected to + a local area network (LAN), like a datacenter, to increase the speed + and resiliency of updates from the |CL| update servers. + + Your caching proxy server is just like any other web application. |WEB-SERVER-SCALE| Option #2: Create your own Linux distribution (mix) --------------------------------------------------- -This approach forks away from the |CL| upstream and has you act as your own -:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to -create customized images based on |CL|. This is a level of responsibility -that requires having more infrastructure and processes to adopt. In return, +This approach forks away from the |CL| upstream and has you act as your own +:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to +create customized images based on |CL|. This is a level of responsibility +that requires having more infrastructure and processes to adopt. In return, this approach *offers you a high degree of control and customization*. -* Development systems which are generating bundles and updates should be - sufficiently performant for the task and separate from the swupd update +* Development systems which are generating bundles and updates should be + sufficiently performant for the task and separate from the swupd update webservers which are serving update content to production machines. -* swupd update webservers which are serving update content to +* swupd update webservers which are serving update content to production machines (see `mixer process`_ for more information) should be - appropriately scaled. + appropriately scaled. - Your swupd update server is just like any other web application. - |WEB-SERVER-SCALE| + Your swupd update server is just like any other web application. + |WEB-SERVER-SCALE| Adopt an agile methodology -------------------------- The cloud, and other scaled deployments, are all about flexibility and speed. -It only makes sense that any |CL| deployment strategy should follow suit. +It only makes sense that any |CL| deployment strategy should follow suit. -Manually rebuilding your own bundles or mix for every release is not -sustainable at a large scale. A |CL| deployment pipeline should be agile -enough to validate and produce new versions with speed. Whether or not those -updates actually make their way to your production can be separate -business decision. However this *ability to frequently roll new versions* of -software to your endpoints is an important prerequisite. +Manually rebuilding your own bundles or mix for every release is not +sustainable at a large scale. A |CL| deployment pipeline should be agile +enough to validate and produce new versions with speed. Whether or not those +updates actually make their way to your production can be separate +business decision. However this *ability to frequently roll new versions* of +software to your endpoints is an important prerequisite. -You own the validation and lifecycle of the OS and should treat it like any +You own the validation and lifecycle of the OS and should treat it like any other software development lifecycle. Below are some pointers: * Thoroughly understand the custom software packages that you will need to integrate with |CL| and maintain along with their dependencies. -* Setup a path to production for building |CL| based images. At minimum this +* Setup a path to production for building |CL| based images. At minimum this should include: - * A development clr-on-clr environment to test building packages and - bundles for |CL| systems. + * A development clr-on-clr environment to test building packages and + bundles for |CL| systems. - * A pre-production environment to deploy |CL| versions to before - production + * A pre-production environment to deploy |CL| versions to before + production * Employ a continuous integration and continuous deployment (CI/CD) philosophy in order to: - - Automatically pull custom packages as they are updated from their - upstream projects or vendors. + - Automatically pull custom packages as they are updated from their + upstream projects or vendors. - - Generate |CL| bundles and potentially bootable images with your - customizations, if any. + - Generate |CL| bundles and potentially bootable images with your + customizations, if any. - - Measure against metrics and indicators which are relevant to your + - Measure against metrics and indicators which are relevant to your business (e.g. performance, power, etc) from release to release. - Integrate with your organization's governance processes, such as change @@ -128,92 +128,93 @@ other software development lifecycle. Below are some pointers: Versioning Infrastructure ------------------------- -|CL| version numbers are very important as they apply to the whole +|CL| version numbers are very important as they apply to the whole infrastructure stack from OS components to libraries and -applications. +applications. -Good record keeping is important, so you should keep a detailed registry +Good record keeping is important, so you should keep a detailed registry and history of previously deployed versions and their contents. With a glance at the |CL| version numbers deployed, you should be -able to tell if your Clear systems are patched against a +able to tell if your Clear systems are patched against a particular security vulnerability or incorporate a critical new feature. - + Pick an image distribution strategy =================================== -Once you have decided on a usage and update strategy, you should understand -*how* |CL| will be deployed to your endpoints. In a large scale -deployment, interactive installers should be avoided in favor of automated +Once you have decided on a usage and update strategy, you should understand +*how* |CL| will be deployed to your endpoints. In a large scale +deployment, interactive installers should be avoided in favor of automated installations or prebuilt images. -There are many well-known ways to install an operating system at scale. Each -have their own benefits, and one may lend itself easier in your environment +There are many well-known ways to install an operating system at scale. Each +have their own benefits, and one may lend itself easier in your environment depending on the resources available to you. -See the `reference of Clear Linux image types`_ - +See the available :ref:`image-types`. + Below are some common ways to install |CL| to systems at scale: Baremetal --------- -Preboot Execution Environments (PXE) or other +Preboot Execution Environments (PXE) or other out-of-band booting options are one way to distribute |CL| to physical baremetal systems on a LAN. -This option works well if your customizations are fairly small in size -and infrastructure can be stateless. +This option works well if your customizations are fairly small in size +and infrastructure can be stateless. -The |CL| `downloads page`_ offers a Live Image that can be deployed as +The |CL| `downloads page`_ offers a live image that can be deployed as a PXE boot server if one doesn't already exist in your environment. Also see -`documentation on installing Clear Linux on bare metal systems`_ +documentation on how to :ref:`bare-metal-install`. -Cloud Instances or Virtual Machines +Cloud Instances or Virtual Machines ----------------------------------- -Image templates in the form of cloneable disks are an effective way to -distribute |CL| for virtual machine environments, whether on-premises or -hosted by a Cloud Solution Provider (CSP). -When used in concert with cloud VM migration features, -this can be a good option for allowing your applications a degree of high -availability and workload mobility; VMs can be restarted on a cluster of -hypervisor host or moved between datacenters transparently. +Image templates in the form of cloneable disks are an effective way to +distribute |CL| for virtual machine environments, whether on-premises or +hosted by a Cloud Solution Provider (CSP). -The |CL| `downloads page`_ offers example prebuilt VM images and is -readily available on popular CSPs. Also see -`documentation on installing Clear Linux in VMs`_. +When used in concert with cloud VM migration features, +this can be a good option for allowing your applications a degree of high +availability and workload mobility; VMs can be restarted on a cluster of +hypervisor host or moved between datacenters transparently. + +The |CL| `downloads page`_ offers example prebuilt VM images and is +readily available on popular CSPs. Also see +documentation on how to :ref:`virtual-machine-install`. Containers ---------- -Containerization platforms allow images to be pulled from a -repository and deployed repeatedly as isolated containers. +Containerization platforms allow images to be pulled from a +repository and deployed repeatedly as isolated containers. -Containers with a |CL| image can be a good option to blueprint and ship -your application, including all its dependencies, as an artifact while -allowing you or your customers to dynamically orchestrate and scale +Containers with a |CL| image can be a good option to blueprint and ship +your application, including all its dependencies, as an artifact while +allowing you or your customers to dynamically orchestrate and scale applications. -|CL| is capable of running a Docker host, has a container image which can +|CL| is capable of running a Docker host, has a container image which can be pulled from DockerHub, or can be built as a customized container. For more information visit the `containers page`_. Considerations with stateless systems ===================================== -An important |CL| concept is statelessness and partitioning of system data -from user data. This concept can change the way you think about an at scale +An important |CL| concept is statelessness and partitioning of system data +from user data. This concept can change the way you think about an at scale deployment. Backup strategy --------------- -A |CL| system and its infrastructure should be considered a commodity and +A |CL| system and its infrastructure should be considered a commodity and be easily reproducible. Avoid focusing on backing up the operating system -itself or default values. +itself or default values. -Instead, focus on backing up what's important and unique - the application -and data. In other words, only focus on backing up critical areas like +Instead, focus on backing up what's important and unique - the application +and data. In other words, only focus on backing up critical areas like `/home`, `/etc`, and `/var`. Meaningful Logging & Telemetry @@ -222,16 +223,16 @@ Meaningful Logging & Telemetry Offload logging and telemetry from endpoints to external servers, so it is persistent and can be accessed on another server when an issue occurs. -* Remote syslogging in |CL| is available through the - `systemd journal-remote service`_ +* Remote syslogging in |CL| is available through the + `systemd journal-remote service`_ -* |CL| offers a `native telemetry solution`_ which can be a powerful tool - for a large deployment to quickly crowdsource issues of interest. Take +* |CL| offers a `native telemetry solution`_ which can be a powerful tool + for a large deployment to quickly crowdsource issues of interest. Take advantage of this feature with careful consideration of the target audience and the kind of data that would be valuable, and expose events - appropriately. + appropriately. - Your telemetry server is just like any other web application. + Your telemetry server is just like any other web application. |WEB-SERVER-SCALE| Orchestration and Configuration Management @@ -240,47 +241,43 @@ Orchestration and Configuration Management In cloud environments, where systems can be ephemeral, being able to configure and maintain generic instances is valuable. -|CL| offers an efficient cloud-init style solution, `micro-config-drive`_, +|CL| offers an efficient cloud-init style solution, `micro-config-drive`_, through the *os-cloudguest* bundles which allow you to configure many Day 1 -tasks such as setting hostname, creating users, or placing -SSH keys in an automated way at boot. For more information on -automating configuration during deployment of |CL| endpoints see +tasks such as setting hostname, creating users, or placing +SSH keys in an automated way at boot. For more information on +automating configuration during deployment of |CL| endpoints see the `documentation on bulk provisioning`_ . - -A configuration management tool is useful for maintaining consistent system -and application-level configuration. Ansible\* is offered through the + +A configuration management tool is useful for maintaining consistent system +and application-level configuration. Ansible\* is offered through the *sysadmin-hostmgmt* bundle as a configuration management and automation -tool. +tool. Cloud-native applications ------------------------- -An Infrastructure OS can design for good behavior, but it is ultimately up -to applications to make agile design choices. Applications deployed -on |CL| should aim to be host-aware but not depend on any specific host to +An Infrastructure OS can design for good behavior, but it is ultimately up +to applications to make agile design choices. Applications deployed +on |CL| should aim to be host-aware but not depend on any specific host to run. References should be relative and dynamic when possible. -The application architecture should incorporate an appropriate tolerance for -infrastructure outages. Don't just keep stateless design as a noted feature. -Continuously test its use; Automate its use by redeploying |CL| and -application on new hosts. This naturally minimizes configuration drift, +The application architecture should incorporate an appropriate tolerance for +infrastructure outages. Don't just keep stateless design as a noted feature. +Continuously test its use; Automate its use by redeploying |CL| and +application on new hosts. This naturally minimizes configuration drift, challenges your monitoring systems, and business continuity plans. -.. _`Clear Linux concepts`: https://clearlinux.org/documentation/clear-linux/concepts .. _`mixin process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixin .. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer -.. _`reference of Clear Linux image types`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/image-types -.. _`documentation on installing Clear Linux on bare metal systems`: https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install .. _`downloads page`: https://download.clearlinux.org/image/ -.. _`documentation on installing Clear Linux in VMs`: https://clearlinux.org/documentation/clear-linux/get-started/virtual-machine-install .. _`containers page`: https://clearlinux.org/containers .. _`systemd journal-remote service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html .. _`native telemetry solution`: https://clearlinux.org/features/telemetry .. _`micro-config-drive`: https://github.com/clearlinux/micro-config-drive .. _`documentation on bulk provisioning`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/bulk-provision -.. |WEB-SERVER-SCALE| replace:: - There are many well-known ways to achieve a scalable and resilient web +.. |WEB-SERVER-SCALE| replace:: + There are many well-known ways to achieve a scalable and resilient web server for this purpose, however implementation details are not in the scope of this document. In general, they should be close to your endpoints, highly available, and easy to scale with a load balancer when diff --git a/source/clear-linux/guides/guides.rst b/source/clear-linux/guides/guides.rst index f6d33320..aebc38e8 100644 --- a/source/clear-linux/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -3,11 +3,11 @@ Guides ###### -Our Guides: +Our Guides: -* Provide a critical, fundamental understanding of |CL| features +* Provide a critical, fundamental understanding of |CL-ATTR| features * Show you how to leverage the full feature set of |CL| -* Enhance your productivity when using |CL| +* Enhance your productivity when using |CL| The following guides provide step-by-step instructions for tasks that come diff --git a/source/clear-linux/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst index d408aebf..fc0582d9 100644 --- a/source/clear-linux/guides/maintenance/developer-workstation.rst +++ b/source/clear-linux/guides/maintenance/developer-workstation.rst @@ -3,42 +3,39 @@ Developer Workstation ##################### -Overview -******** +*Developer Workstation* helps you find the :ref:`bundles-about` you need to +start your |CL-ATTR| development project. -*Developer Workstation* helps you find the :ref:`bundles-about` you need to -start your |CL| development project. - -Before continuing, we recommend that you learn how to use +Before continuing, we recommend that you learn how to use :ref:`swupd `. Visit our :ref:`swupd-about` page to understand how |CL| simplifies software versioning compared to other Linux\* -distributions. +distributions. Workstation Setup -================= +***************** -This guide helps you understand the minimum bundles required to get started. -After installing them, you can add more bundles relevant to your use case. -To run any process required for Clear Linux development, you can add the +This guide helps you understand the minimum bundles required to get started. +After installing them, you can add more bundles relevant to your use case. +To run any process required for |CL| development, you can add the large bundle :ref:`*os-clr-on-clr* `. However, given how many packages this bundle contains, you may want instead to deploy a leaner -OS with only those bundles relevant to your project. Developer Workstation -responds to this need. +OS with only those bundles relevant to your project. Developer Workstation +responds to this need. -Use Table 1, *Clear Linux Developer Profiles*, to identify the *minimum -required bundles* to get started developing based on your role or project. -While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point. +Use Table 1, *Developer Profiles*, to identify the *minimum +required bundles* to get started developing based on your role or project. +While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point. -.. list-table:: **Table 1. Clear Linux Developer Profiles** +.. list-table:: **Table 1. Developer Profiles** :widths: 20, 20, 20, 20 :header-rows: 1 - * - Clear Linux Bundle - - *Internet of Things (IoT)* + * - |CL| Bundle + - *Internet of Things (IoT)* - *System Administrator* - *Client/Cloud/Web Developer* - - * - `editors` + + * - `editors` - ✓ - ✓ - ✓ @@ -52,60 +49,60 @@ While your role may not neatly fit in one of these categories, consider using Ta - ✓ - ✓ - ✓ - + * - `webserver-basic` - - + - - ✓ - - ✓ - + - ✓ + * - `application-server` - - + - - ✓ - ✓ - + * - `database-basic` - - + - - ✓ - ✓ - + * - `desktop-autostart` - ✓ - ✓ - ✓ * - `dev-utils` - - - - + - + - - ✓ `swupd` search -============== +************** We recommend trying out :ref:`swupd search `, to learn the -commands to search for and add bundles relevant to your project. +commands to search for and add bundles relevant to your project. -:ref:`swupd-search` shows you how to: +:ref:`swupd-search` shows you how to: -* Use `swupd` to search for bundles +* Use `swupd` to search for bundles * Use `swupd` to add bundles Core Concepts -============= +************* -We recommend that you understand these core concepts in |CL| *before* -developing your project. +We recommend that you understand these core concepts in |CL| *before* +developing your project. * :ref:`Bundles ` * :ref:`Software update ` * :ref:`Mixer ` -* :ref:`Autospec ` +* :ref:`Autospec ` Other resources for developers ----------------------------------- -* `Developer Tooling Framework for Clear Linux`_ -* `Clear Linux Bundles`_ +* `Developer Tooling Framework`_ for |CL| +* `Bundle definition files`_ -.. _Clear Linux Bundles: https://github.com/clearlinux/clr-bundles +.. _Bundle definition files: https://github.com/clearlinux/clr-bundles -.. _Developer Tooling Framework for Clear Linux: https://github.com/clearlinux/common +.. _Developer Tooling Framework: https://github.com/clearlinux/common diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index e48e272b..288ada71 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -4,7 +4,7 @@ Create and enable a new user space ################################## This section provides steps to complete the following basic setup tasks for -a newly installed |CLOSIA| system: +a newly installed |CL-ATTR| system: * Create a new user. * Update the OS to its most current version using `swupd`. @@ -51,7 +51,7 @@ Install the `sysadmin-basic` bundle: We provide the full list of bundles and packages installed with the `sysadmin-basic`_ bundle. Additionally, we have listed -`all Clear Linux bundles`_, active or deprecated. Click any bundle on the +`all bundles`_ for |CL|, active or deprecated. Click any bundle on the list to view the manifest of the bundle. Set up a new user and add the new user to the `wheel` group @@ -88,7 +88,7 @@ Install a GUI to test `sudo` privileges .. note:: If you are following this sequence after just setting up the - pre-configured VMware\* virtual machine from the repo, you must + pre-configured VMware\* virtual machine from the repo, you must :ref:`increase virtual disk size` or the following step will fail. @@ -136,7 +136,7 @@ system. .. _`sysadmin-basic`: https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic -.. _`all Clear Linux bundles`: +.. _`all bundles`: https://github.com/clearlinux/clr-bundles/tree/master/bundles .. _`wheel group`: diff --git a/source/clear-linux/guides/maintenance/hostname.rst b/source/clear-linux/guides/maintenance/hostname.rst index 04c7108e..ce539009 100644 --- a/source/clear-linux/guides/maintenance/hostname.rst +++ b/source/clear-linux/guides/maintenance/hostname.rst @@ -3,15 +3,15 @@ Modify hostname on |CL-ATTR| ############################ -This guide describes how to modify and view the hostname of your +This guide describes how to modify and view the hostname of your |CL-ATTR| system. -By default, |CL| installations have a machine generated name, which is a -long string of letters and numbers. The generated name is fine for computers -but is not human-friendly. Administrators and users will often want to rename -their machines with a name that is easier to remember, type, and search -for. Renaming a machine also makes it easier to identify, by including -meaningful data in the name. The following examples show human-friendly machine +By default, |CL| installations have a machine generated name, which is a +long string of letters and numbers. The generated name is fine for computers +but is not human-friendly. Administrators and users will often want to rename +their machines with a name that is easier to remember, type, and search +for. Renaming a machine also makes it easier to identify, by including +meaningful data in the name. The following examples show human-friendly machine names: * *regression-test* @@ -21,12 +21,12 @@ names: Set your hostname ***************** -|CL| uses the :command:`hostnamectl` command to display and modify the machine -name. :command:`hostnamectl` is part of the **os-core** bundle, which provides -a basic Linux\* user space and utilities. +|CL| uses the :command:`hostnamectl` command to display and modify the machine +name. :command:`hostnamectl` is part of the **os-core** bundle, which provides +a basic Linux\* user space and utilities. -This example sets the hostname to *telemetry-test-2-h15*, to identify a -|CL| telemetry test machine on the second floor at grid location H15. +This example sets the hostname to *telemetry-test-2-h15*, to identify a +|CL| telemetry test machine on the second floor at grid location H15. Make sure to reboot after setting a new hostname. .. code-block:: bash @@ -36,14 +36,14 @@ Make sure to reboot after setting a new hostname. .. note:: - There are three types of hostname: *static*, *transient*, and *pretty*. - The most common is the static hostname. Static hostnames must be between - two and 63 characters long, must start and end with a letter or number, - and may contain letters (case-insensitive), numbers, dashes, or dots. + There are three types of hostname: *static*, *transient*, and *pretty*. + The most common is the static hostname. Static hostnames must be between + two and 63 characters long, must start and end with a letter or number, + and may contain letters (case-insensitive), numbers, dashes, or dots. - If the static hostname exists, it is used to generate the transient hostname, - which is maintained by the kernel. The transient hostname can be changed - by DHCP or mDNS at runtime. + If the static hostname exists, it is used to generate the transient hostname, + which is maintained by the kernel. The transient hostname can be changed + by DHCP or mDNS at runtime. The pretty hostname is a free-form UTF8 name used for presentation to the user. @@ -70,5 +70,5 @@ You should see output similar to: Kernel : Linux 4.18.8-632.native Architecture : x86-64 - + **Congratulations!** You successfully modified the hostname of your |CL| system. diff --git a/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst index a676e615..287be71b 100644 --- a/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst +++ b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst @@ -1,18 +1,18 @@ .. _increase-virtual-disk-size: -Increase virtual disk size of a Clear Linux\* image -################################################### +Increase virtual disk size of a |CL-ATTR| image +############################################### -|CLOSIA| prebuilt images come in different sizes, ranging from 300 MB to 20 +|CL-ATTR| prebuilt images come in different sizes, ranging from 300 MB to 20 GB. This guide describes how to increase the size of your prebuilt |CL| image if you need more capacity. .. contents:: This guide will cover: -Determine the partition order and sizes of the prebuilt image +Determine the partition order and sizes of the prebuilt image ************************************************************* -There are two methods to find the order and sizes of partitions virtual disk +There are two methods to find the order and sizes of partitions virtual disk of your prebuilt |CL| image. In both examples, the prebuilt Hyper-V image has a disk size of 8.5 GB with / @@ -28,7 +28,7 @@ execute the :command:`lsblk` command as shown below: sudo lsblk -An example output of the :command:`lsblk` command: +An example output of the :command:`lsblk` command: .. code-block:: console @@ -36,16 +36,16 @@ An example output of the :command:`lsblk` command: sda 8:0 0 8.5G 0 disk ├─sda1 8:1 0 512M 0 part ├─sda2 8:2 0 32M 0 part [SWAP] - └─sda3 8:3 0 8G 0 part / + └─sda3 8:3 0 8G 0 part / An example of this can also be seen in Figure 1. -Checking :file:`config.json` used to build the image +Checking :file:`config.json` used to build the image ---------------------------------------------------- -The second method to determine partition to check the :file:`config.json` +The second method to determine partition to check the :file:`config.json` file used to create prebuilt image, located in the `releases`_ repository. -For example, to find the size of the Hyper-V\* image version number 20450, +For example, to find the size of the Hyper-V\* image version number 20450, follow these steps: #. Go to the `releases`_ repository. @@ -74,17 +74,17 @@ follow these steps: Increase virtual disk size ************************** -Once you have determined the disk and partition to be increased, you are +Once you have determined the disk and partition to be increased, you are ready to perform the actual increase of the disk, partition, and filesystem. Power off VM and increase virtual disk size: -------------------------------------------- -To increase the virtual disk size for a prebuilt image, perform the steps +To increase the virtual disk size for a prebuilt image, perform the steps below: #. Shut down your VM if it is running. -#. Use the process defined by your hypervisor +#. Use the process defined by your hypervisor or cloud provider to increase the virtual disk size of your |CL| VM. #. Power up the VM. @@ -95,7 +95,7 @@ Resize the partition of the virtual disk: #. Log in to an account with root privileges. #. Open a terminal emulator. -#. Add the |CL| `storage-utils` bundle to install the +#. Add the |CL| `storage-utils` bundle to install the :command:`parted` and :command:`resize2fs` tools. .. code-block:: bash @@ -121,7 +121,7 @@ Resize the partition of the virtual disk: Fix/Ignore? - #. Enter :command:`resizepart [partition number]` where + #. Enter :command:`resizepart [partition number]` where *[partition number]* is the partition number of the partition to modify. #. Enter :command:`yes` when prompted. #. Enter the new `End` size. @@ -142,18 +142,18 @@ Resize the partition of the virtual disk: .. figure:: figures/increase-virtual-disk-size-1.png :scale: 100 % - :alt: Increase root partition size + :alt: Increase root partition size Figure 1: Increase root partition size. -Resize the filesytem +Resize the filesytem -------------------- #. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where *[modified partition name]* is the partition that was changed in `parted`. #. Run the :command:`df -h` to verify that the filesystem size has - increased. + increased. Figure 2 depicts the described steps to resize the partition of the virtual disk from 8.5GB to 20GB. @@ -164,6 +164,6 @@ Resize the filesytem Figure 2: Increase root filesystem size after partition has been expanded. Congratulations! You have resized the disk, partition, and filesystem. At -this point, the increase in disk capacity is usable. +this point, the increase in disk capacity is usable. .. _releases: https://download.clearlinux.org/releases/ \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/mixin.rst b/source/clear-linux/guides/maintenance/mixin.rst index 862332b2..75e2c488 100644 --- a/source/clear-linux/guides/maintenance/mixin.rst +++ b/source/clear-linux/guides/maintenance/mixin.rst @@ -3,7 +3,7 @@ Create and add custom bundles to your upstream Clear Linux system ################################################################# -|CLOSIA| offers many curated bundles that you can install on your system to +|CL-ATTR| offers many curated bundles that you can install on your system to create your desired capabilities. If the available upstream bundles do not meet your needs, you can create and add your own custom bundles to your system using one of two methods. Note: Upstream refers to the official diff --git a/source/clear-linux/guides/maintenance/swupd-guide.rst b/source/clear-linux/guides/maintenance/swupd-guide.rst index db0ba772..ea0bab61 100644 --- a/source/clear-linux/guides/maintenance/swupd-guide.rst +++ b/source/clear-linux/guides/maintenance/swupd-guide.rst @@ -5,7 +5,7 @@ Use swupd *swupd* manages the software update capability of |CL-ATTR|. It can check for valid system updates and, if found, download and install them. It can also -perform verification of the system software. +perform verification of the system software. |CL| uses :ref:`bundles ` as the base abstraction for installing functionality on top of the core operating system. Use the `swupd` @@ -18,7 +18,7 @@ This guide assumes: * The device is able to connect to the release infrastructure http://update.clearlinux.org -.. contents:: +.. contents:: :local: :depth: 2 @@ -54,7 +54,7 @@ Current OS version and update server info: Enable or disable automatic updates =================================== -|CL| updates are automatic by default but can be set to occur only +|CL| updates are automatic by default but can be set to occur only on demand. To verify your current auto-update setting: .. code-block:: bash @@ -105,7 +105,7 @@ to, overwritten, removed, or modified (e.g., permissions). sudo swupd verify -All directories that are watched by `swupd` are verified according to +All directories that are watched by `swupd` are verified according to the manifest data and hash mismatches are flagged as follows: .. code-block:: console @@ -113,7 +113,7 @@ the manifest data and hash mismatches are flagged as follows: Verifying version 23300 Verifying files ...0% - Hash mismatch for file: /usr/bin/chardetect + Hash mismatch for file: /usr/bin/chardetect ... ... Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py @@ -124,7 +124,7 @@ the manifest data and hash mismatches are flagged as follows: In this case, python packages that were installed on top of the default install were flagged as mismatched. `swupd` can be directed to ignore -or fix issues based on :ref:`command line options `. +or fix issues based on :ref:`command line options `. Fixing hash mismatches ====================== @@ -138,7 +138,7 @@ ignore files or directories matching `/usr/lib/python`: .. code-block:: bash - sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python + sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python Bundles ******* @@ -150,7 +150,7 @@ You can list all of the bundles currently installed on the system .. code-block:: bash - sudo swupd bundle-list --all + sudo swupd bundle-list --all Finding a bundle containing a binary ==================================== @@ -160,7 +160,7 @@ binary. Note that it may be present in multiple bundles: .. code-block:: bash - swupd search -b + swupd search -b Adding a bundle =============== diff --git a/source/clear-linux/guides/maintenance/swupd-search.rst b/source/clear-linux/guides/maintenance/swupd-search.rst index 835775ab..45764a65 100644 --- a/source/clear-linux/guides/maintenance/swupd-search.rst +++ b/source/clear-linux/guides/maintenance/swupd-search.rst @@ -1,54 +1,54 @@ -.. _swupd-search: +.. _swupd-search: Use swupd search to find bundles ################################ This document explains how to use `swupd search` to find and add -bundles in |CL-ATTR|. +bundles in |CL-ATTR|. Assumptions *********** -This guide assumes you: +This guide assumes you: -* Possess a basic knowledge of :ref:`swupd ` -* Understand :ref:`how swupd differs ` from - other Linux\* distributions +* Possess a basic knowledge of :ref:`swupd ` +* Understand :ref:`how swupd differs ` from + other Linux\* distributions * May :ref:`mixer` to produce a custom distribution/image -How do I search for a bundle? +How do I search for a bundle? ***************************** -Use `swupd search` to locate the bundle where the application binary exists. +Use `swupd search` to locate the bundle where the application binary exists. Example: Kata\* Containers ========================== -Containers have revolutionized the way we manage cloud infrastructure. -Traditional containers often share the same OS kernel, which raises -security concerns. Instead, with Kata Containers, each container has its own -kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a -lightweight, fast, and secure option for app/container management. +Containers have revolutionized the way we manage cloud infrastructure. +Traditional containers often share the same OS kernel, which raises +security concerns. Instead, with Kata Containers, each container has its own +kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a +lightweight, fast, and secure option for app/container management. -In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_: +In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_: `containers-virt`. Also, check out our tutorial: :ref:`kata`. -We need to find *kata* containers in a bundle. How do we search for it? +We need to find *kata* containers in a bundle. How do we search for it? -#. Enter :command:`swupd search`, followed by 'kata' as the search term: +#. Enter :command:`swupd search`, followed by 'kata' as the search term: .. code-block:: bash sudo swupd search kata - .. note:: + .. note:: `swupd search` downloads |CL| manifest data and searches for - matching paths. Enter only one term, or hyphenated term, per + matching paths. Enter only one term, or hyphenated term, per search. Use the command :command:`man swupd` to learn more. #. Alternatively, if you want to search binaries only, add the `-b` - flag: + flag: .. code-block:: bash @@ -56,15 +56,15 @@ We need to find *kata* containers in a bundle. How do we search for it? .. note:: - `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results. + `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results. - Only the base bundle is returned. In |CL|, *bundles* can contain - other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*. + Only the base bundle is returned. In |CL|, *bundles* can contain + other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*. If your search does not produce results on a specific term when using - the `-b` flag, abbreviate the search term. For example, if you search - for *kubernetes* and it does not show results, instead abbreviate the - term to *kube* to show results. + the `-b` flag, abbreviate the search term. For example, if you search + for *kubernetes* and it does not show results, instead abbreviate the + term to *kube* to show results. #. Optionally, you can review our `bundles`_ or individual `packages`_ @@ -82,7 +82,7 @@ We need to find *kata* containers in a bundle. How do we search for it? .. note:: - If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed. + If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed. #. Add the bundle `containers-virt`: @@ -94,11 +94,11 @@ We need to find *kata* containers in a bundle. How do we search for it? To add multiple bundles simply add a space followed by the bundle name. -#. When prompted, enter your password. +#. When prompted, enter your password. #. Upon successful installation, your console should show similar data: - - .. code-block:: console + + .. code-block:: console Downloading packs... @@ -123,11 +123,11 @@ Learn how to: * :ref:`kata_migration` -* :ref:`swupd-guide` +* :ref:`swupd-guide` * :ref:`Show all available bundles ` -* :ref:`Remove bundles` +* :ref:`Remove bundles` .. _Kata Containers: https://clearlinux.org/blogs/clear-linux-os-announces-support-kata-containers @@ -135,6 +135,6 @@ Learn how to: .. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles - .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles + .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles - .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages + .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages diff --git a/source/clear-linux/guides/maintenance/time.rst b/source/clear-linux/guides/maintenance/time.rst index 4a8b75dd..25ee141b 100644 --- a/source/clear-linux/guides/maintenance/time.rst +++ b/source/clear-linux/guides/maintenance/time.rst @@ -3,7 +3,7 @@ Set the time ############ -|CLOSIA| uses the `systemd-timesyncd.service` daemon to synchronize time. +|CL-ATTR| uses the `systemd-timesyncd.service` daemon to synchronize time. This guide describes how to reset the time in your |CL| system when the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached. diff --git a/source/clear-linux/guides/maintenance/validate-signatures.rst b/source/clear-linux/guides/maintenance/validate-signatures.rst index 1a99afc6..65668884 100644 --- a/source/clear-linux/guides/maintenance/validate-signatures.rst +++ b/source/clear-linux/guides/maintenance/validate-signatures.rst @@ -3,7 +3,7 @@ Validate signatures ################### -|CLOSIA| offers a way to validate the content of an image or an update. All +|CL-ATTR| offers a way to validate the content of an image or an update. All validation of content works by creating and signing a hash. A valid signature creates a chain of trust. A broken chain of trust, seen as an invalid signature, means the content is not valid. @@ -21,7 +21,7 @@ For the outlined steps, the installer image of the latest release of |CL| is used for illustrative purposes. You may use any image of |CL| you choose. #. Download the image, the signature of the SHA512 sum of the image, and the - Clear Linux certificate used for signing the SHA512 sum. + |CL| certificate used for signing the SHA512 sum. .. code-block:: console @@ -29,16 +29,16 @@ used for illustrative purposes. You may use any image of |CL| you choose. curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz # Signature of SHA512 sum of image curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig - # Clear Linux certificate + # Certificate curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem -#. Generate the SHA256 sum of the Clear Linux certificate. +#. Generate the SHA256 sum of the |CL| certificate. .. code-block:: console sha256sum ClearLinuxRoot.pem -#. Ensure the generated SHA256 sum of the Clear Linux certificate matches the +#. Ensure the generated SHA256 sum of the |CL| certificate matches the following SHA256 sum to verify the integrity of the certificate. .. code-block:: console @@ -52,7 +52,7 @@ used for illustrative purposes. You may use any image of |CL| you choose. sha512sum clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out #. Ensure the signature of the SHA512 sum of the image was created using the - Clear Linux certificate. This validates the image is trusted and it has not + |CL| certificate. This validates the image is trusted and it has not been modified. .. code-block:: console diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 5f4b1009..bcc0fcac 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -3,8 +3,8 @@ Build a custom |CL-ATTR| based Docker container image ####################################################### -The official base |CL-ATTR| container image is published on Docker\* Hub and -is updated on a regular basis. This guide contains the steps to build a +The official base |CL-ATTR| container image is published on Docker\* Hub and +is updated on a regular basis. This guide contains the steps to build a custom container image. Prerequisites @@ -111,7 +111,7 @@ Build the base container image .. note:: * :file:`os-core` provides the minimal Linux namespace. - * :file:`os-core-update` provides the basic suite for running the |CLOSIA| + * :file:`os-core-update` provides the basic suite for running the |CL| updater. #. Optionally, you can include additional bundles with the base image. diff --git a/source/clear-linux/guides/network/dpdk.rst b/source/clear-linux/guides/network/dpdk.rst index 2f8d4127..112dfe13 100644 --- a/source/clear-linux/guides/network/dpdk.rst +++ b/source/clear-linux/guides/network/dpdk.rst @@ -25,7 +25,7 @@ drivers, sample applications, and tools for fast packet processing. Prerequisites ************* -* Two platforms using |CLOSIA| release `13330`_ or higher. +* Two platforms using |CL-ATTR| release `13330`_ or higher. * Both images must include the :file:`kernel-native bundle`. * Install the :file:`network-basic-dev` bundle with the command: @@ -130,7 +130,7 @@ NICs to DPDK modules to run DPDK applications. Set hugepages (Platforms A and B) ********************************* -|CLOSIA| supports `hugepages` for the large memory pool allocation used for +|CL| supports `hugepages` for the large memory pool allocation used for packet buffers. #. Set the number of hugepages. @@ -264,7 +264,7 @@ machines control the NICs on the host. sudo curl -O https://download.clearlinux.org/image/start_qemu.sh -#. Download a bare-metal image of |CLOSIA| and rename it as :file:`clear.img`. +#. Download a bare-metal image of |CL| and rename it as :file:`clear.img`. #. Look for an Ethernet\* device entry that contains vendor and device ID: @@ -283,7 +283,7 @@ machines control the NICs on the host. host. -#. Unbind the NICs from the host to do pass-through with virtual machines. |CLOSIA| +#. Unbind the NICs from the host to do pass-through with virtual machines. |CL| supports this action. The commands take the format: .. code-block:: bash diff --git a/source/clear-linux/guides/network/ipxe-install.rst b/source/clear-linux/guides/network/ipxe-install.rst index 2a6585ef..ad58f584 100644 --- a/source/clear-linux/guides/network/ipxe-install.rst +++ b/source/clear-linux/guides/network/ipxe-install.rst @@ -1,9 +1,9 @@ .. _ipxe-install: -Install Clear Linux over the network with iPXE -################################################ +Install |CL-ATTR| over the network with iPXE +############################################ -This guide describes how to install Clear Linux\* using :abbr:`PXE (Pre-boot +This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot Execution Environment)`. PXE is an industry standard that describes client-server interaction with diff --git a/source/clear-linux/guides/network/network-bonding.rst b/source/clear-linux/guides/network/network-bonding.rst index 1b601748..1f19f0eb 100644 --- a/source/clear-linux/guides/network/network-bonding.rst +++ b/source/clear-linux/guides/network/network-bonding.rst @@ -6,7 +6,7 @@ Combine multiple interfaces with network bonding Network bonding combines multiple network interfaces into a single logical interface to provide redundancy and bandwidth aggregation. -|CLOSIA| includes Linux bonding_ and team_ drivers. This guide describes how +|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how to configure systemd to use the `bonding` driver. The example demonstrates how to: diff --git a/source/clear-linux/guides/network/network.rst b/source/clear-linux/guides/network/network.rst index 5df83dcb..30846ade 100644 --- a/source/clear-linux/guides/network/network.rst +++ b/source/clear-linux/guides/network/network.rst @@ -4,7 +4,7 @@ Network guide ############# This guide provides step-by-step instructions for common tasks associated with -the configuration, administration, and use of networks in the |CLOSIA|. +the configuration, administration, and use of networks in the |CL-ATTR|. .. toctree:: :maxdepth: 1 diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst index 8de6f3ef..ac0138a0 100644 --- a/source/clear-linux/guides/network/vnc.rst +++ b/source/clear-linux/guides/network/vnc.rst @@ -1,10 +1,10 @@ .. _vnc: -Remote-desktop to a Clear Linux host using VNC +Remote-desktop to a |CL-ATTR| 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. +that allows you to connect via remote-desktop to your |CL-ATTR| host. This guide shows you how to: @@ -15,13 +15,13 @@ This guide shows you how to: * 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 -******************************************************************** +Install the VNC server and misc. components on your 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. +* `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. Follow these steps: @@ -35,16 +35,16 @@ Follow these steps: #. Install the |CL| bundles. .. code-block:: console - + # swupd bundle-add desktop-autostart vnc-server #. Reboot your |CL| host. -Configure a VNC-server-start method on your Clear Linux host -************************************************************ +Configure a VNC-server-start method on your host +************************************************ -There are three methods you can use to configure and start the VNC server on -your host: +There are three methods you can use to configure and start the VNC server on +your |CL| host: .. list-table:: Table 1: VNC-server-start Configuration Methods :widths: 10,20,20,20 @@ -55,14 +55,14 @@ your host: - `Method 2`: Automatically start a VNC session via a systemd service script - `Method 3`: Create 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 connect to it by + - This is the traditional method where you SSH into the |CL| host, manually + start a VNC session to get a display ID, and 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 make a VNC connection and supply + - The system administrator sets up a systemd service script for you with + a pre-assigned display ID. You 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 see + When you make a VNC connection to the |CL| host, you see the GDM login screen and authenticate as if you are local. * - Who configures VNC settings? - You @@ -82,10 +82,10 @@ your host: - No. Use |CL| account username and password through GDM -Although all three methods can coexist on the same |CL| host, we recommend -you pick a method that suits your needs. +Although all three methods can coexist 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 +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 @@ -94,18 +94,18 @@ 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. +#. 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 + .. code-block:: console - $ vncserver + $ vncserver Example output: - .. code-block:: console + .. code-block:: console $ vncserver @@ -123,15 +123,15 @@ You (and each user) must perform these steps to initialize your VNC settings. 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. + 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 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. + 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. -#. Kill the active VNC session for the time being with the - :command:`vncserver -kill :[display ID]` command. Substitute [display ID] +#. 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 @@ -140,22 +140,22 @@ You (and each user) must perform these steps to initialize your VNC settings. .. note:: - If you do not recall the active session display ID, use the - :command:`vncserver -list` command to find it. + 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. + * 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 -preassigned unique display ID. +set up a systemd service file for all intended VNC users with their own +preassigned unique display ID. #. Log in and get root privileges. @@ -163,7 +163,7 @@ preassigned unique display ID. $ sudo -s -#. Make sure the user accounts already exist. Use the following command to +#. Make sure the user accounts already exist. Use the following command to list all users. @@ -180,8 +180,8 @@ preassigned unique display ID. #. 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`. + 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 @@ -203,12 +203,12 @@ preassigned unique display ID. [Install] WantedBy=multi-user.target - EOF + EOF -#. Have each user log into their account and set a VNC password with +#. 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 +#. 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 @@ -217,29 +217,29 @@ preassigned unique display ID. # 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 # systemctl | grep vnc - The example below shows 2 VNC sessions that were successfully started for + 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 # 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 +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. +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. #. Log in and get root privileges. @@ -253,7 +253,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc # 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 @@ -307,7 +307,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc 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 @@ -315,20 +315,20 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc # 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 # systemctl | grep vnc - The example below shows the xvnc.socket is running. + The example below 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 + system-xvnc.slice loaded active active system-xvnc.slice See the `vncserver` Man page for additional information. @@ -336,15 +336,15 @@ 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. +Perform the steps below to add these apps to your client system. Install a VNC viewer app ======================== -On |CL|: +On |CL|: .. code-block:: console @@ -354,9 +354,9 @@ On Ubuntu, Mint: .. code-block:: console - # apt-get install xtightvncviewer + # apt-get install xtightvncviewer -On Fedora: +On Fedora: .. code-block:: console @@ -365,38 +365,38 @@ On Fedora: On Windows: * Install `RealVNC for Windows`_ - + On macOS: -* Install `RealVNC for macOS`_ +* Install `RealVNC for macOS`_ Install an SSH client ===================== -* On most Linux distros (Clear Linux, Ubuntu, Mint, Fedora, etc.) and macOS, +* On most Linux distros (|CL|, 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 -*************************************************** +Establish a VNC connection to your host +*************************************** -Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection: +Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection: -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 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 +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. +If you chose `Method 3`, proceed to the +:ref:`connect-to-vnc-session` below. -SSH into your Clear Linux host and launch VNC -============================================= +SSH into your host and launch VNC +================================= -#. SSH into your Clear Linux host +#. SSH into your |CL| host #. On Linux distros and macOS: @@ -409,8 +409,8 @@ SSH into your Clear Linux host and launch VNC #. 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. + #. Enter the IP address of your |CL| host in the + :guilabel:`Host Name (or IP address)` field. #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. #. Click the :guilabel:`Open` button. @@ -420,8 +420,8 @@ SSH into your Clear Linux host and launch VNC Figure 1: Putty - configure SSH session settings -#. Log in with your |CL| username and password. Do not use your VNC - password. +#. Log in with your |CL| username and password. Do not use your VNC + password. #. Start a VNC session. .. code-block:: console @@ -440,35 +440,35 @@ SSH into your Clear Linux host and launch VNC Log file is /home/vnc-user-c/.vnc/clr-linux:3.log #. 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. + the VNC viewer app to establish the connection. The above example shows + the display ID is 3. .. 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: + 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. +#. You can now end the SSH connection by logging out. This does + not terminate your active VNC session. .. _connect-to-vnc-session: 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: +For `Method 1` and `Method 2`, you must connect to a specific active session +or display ID using one of two options: * Use a fully-qualified VNC port number, which consists of the default VNC server port (5900) plus the display ID -* Use the display ID +* Use the display ID -For example, if the display ID is 3, it can be specified as `5903` or just +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. @@ -483,22 +483,22 @@ number. #. Enter your credentials. * For `Method 1` and `Method 2`, enter your VNC password. No username is - required. + 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. + VNC if you are logged in locally and vice versa. **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 +#. Enter the IP address of the |CL| host and the fully-qualified VNC port number. - The following screenshot shows connecting to |CL| host + 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 @@ -512,7 +512,7 @@ number. #. Enter your credentials. * For `Method 1` and `Method 2`, enter your VNC password. No username is - required. + required. * For `Method 3`, enter your |CL| account username and password through GDM. @@ -520,8 +520,8 @@ 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` + +`Optional: Configure RealVNC Image Quality` ------------------------------------------- To increase the RealVNC viewer image quality, manually change the `ColorLevel` value. Follow these steps: @@ -546,16 +546,16 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` -Terminate a VNC connection to your Clear Linux host -*************************************************** +Terminate a VNC connection to your host +*************************************** -For `Method 1` and `Method 2`, once started, a VNC session remains active +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. +#. SSH into your |CL| host. #. Open a terminal emulator. -#. Find the active VNC session display ID with the command +#. Find the active VNC session display ID with the command :command:`vncserver -list`. .. code-block:: console @@ -581,7 +581,7 @@ truly terminate an active VNC session, follow these steps: Encrypt VNC traffic through an SSH tunnel ***************************************** -By default, VNC traffic is not encrypted. Figure 6 shows an example warning +By default, VNC traffic is not encrypted. Figure 6 shows an example warning from RealVNC Viewer. .. figure:: figures/vnc/vnc-6.png @@ -592,13 +592,13 @@ from RealVNC Viewer. To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps: -#. Configure the VNC server to only accept connection from localhost by +#. 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, +#. 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 @@ -622,11 +622,11 @@ For `Method 1`: localhost # alwaysshared -#. If an active session exists, kill it, and then restart it. +#. 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 +#. 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: @@ -657,12 +657,12 @@ For `Method 2`: For `Method 3`: -#. No change is needed to the :file:`xvnc@service` script. +#. No change is needed to the :file:`xvnc@service` script. 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: - + command like this: + .. code-block:: console $ netstat -plant @@ -673,7 +673,7 @@ For `Method 3`: 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. +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 % @@ -681,8 +681,8 @@ any host as specified by the `0.0.0.0`'s. This is before the `-localhost` optio 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 @@ -698,23 +698,23 @@ Set up an SSH tunnel from your client system to your |CL| host .. code-block:: console - $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ + $ 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:: + .. note:: * `-L` specifies that [client port number] on the localhost (on the - client side) is forwarded to [fully-qualified VNC port number] + 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 + * 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 + * 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. @@ -722,28 +722,28 @@ Set up an SSH tunnel from your client system to your |CL| host **On Windows:** #. Launch Putty. -#. Specify the |CL| VNC host to connect to. - - #. Under the :guilabel:`Category` section, select :guilabel:`Session`. +#. 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. + #. Enter the IP address of your |CL| 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 + #. Under the :guilabel:`Category` section, go to :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`. - - #. In the :guilabel:`Source port` field, enter an available client + + #. 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 + + #. 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 @@ -756,7 +756,7 @@ Set up an SSH tunnel from your client system to your |CL| host Connect to a VNC session through an SSH tunnel ============================================== -After you have set up an SSH tunnel, follow these instructions to connect to +After you have set up an SSH tunnel, follow these instructions to connect to your VNC session. **On Linux distros:** @@ -776,13 +776,13 @@ your VNC session. .. 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:: + .. note:: - RealVNC will still warn that the connection is not encrypted even - though its traffic is going through the SSH tunnel. You can ignore + 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 for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/