mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-21 19:15:51 +00:00
Initial commit for translation clean up (network and telemetry guides) (#650)
Signed-off-by: Kristal Dale <kristal.dale@intel.com> Clean up in preparation for translations … - Standardize page formatting (use of intro sentence, TOC tree, etc) - Simplify intro sentences, remove idioms, etc - Standardize use of roles (remove use of `` and * for emphasis on special words or options) - Misc clean up (opportunistic) Signed-off-by: Kristal Dale <kristal.dale@intel.com> Updates per requested changes on PR. Signed-off-by: Kristal Dale <kristal.dale@intel.com> Minor revision to use :file: for directories referenced in deploy-at-scale.rst Signed-off-by: Kristal Dale <kristal.dale@intel.com> Minor clean-up on network-related files. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
committed by
michael vincerra
parent
b9e5806856
commit
687aa3abcc
@@ -3,30 +3,33 @@
|
||||
Deploy at Scale
|
||||
###############
|
||||
|
||||
Once you are comfortable with |CL-ATTR| :ref:`concepts <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.
|
||||
|
||||
.. note::
|
||||
|
||||
This is not a replacement or blueprint for designing your own IT
|
||||
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
|
||||
deployment.
|
||||
This guide describes deployment considerations and strategies when deploying
|
||||
|CL-ATTR| at scale in your environment.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
:depth: 1
|
||||
|
||||
Pick a |CL| usage and update strategy
|
||||
=====================================
|
||||
Overview
|
||||
********
|
||||
|
||||
In this guide the term *endpoint* refers to a system targeted for |CL|
|
||||
installation, whether that is a datacenter system or unit deployed in field.
|
||||
|
||||
.. note::
|
||||
|
||||
This guide is not a replacement or blueprint for designing your own IT
|
||||
operating environment.
|
||||
|
||||
Implementation details for a scale deployment are beyond the scope of this
|
||||
guide.
|
||||
|
||||
Your |CL| deployment should complement your existing environment and
|
||||
available tools. It is assumed core IT dependencies of your environment,
|
||||
such as your network, are healthy and scaled to suit the deployment.
|
||||
|
||||
Pick a usage and update strategy
|
||||
********************************
|
||||
|
||||
Different business scenarios call for different deployment methodologies.
|
||||
|CL| offers the flexibility to continue consuming the upstream |CL|
|
||||
@@ -36,27 +39,27 @@ act as your own :abbr:`OSV (Operating System Vendor)`.
|
||||
Below is an overview of some considerations.
|
||||
|
||||
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
|
||||
:abbr:`OSV (Operating System Vendor)` by leveraging the :ref:`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*.
|
||||
this approach *offers you a high degree of control and customization*. Consider:
|
||||
|
||||
* Development systems that generate bundles and updates should have
|
||||
sufficient performance for the task and separate from the swupd update
|
||||
sufficient performance for the task and be separate from the swupd update
|
||||
webservers that serve update content to production machines.
|
||||
|
||||
* swupd update webservers that serve update content to
|
||||
production machines (see `mixer process`_ for more information) should be
|
||||
appropriately scaled.
|
||||
* swupd update webservers that serve update content to production machines
|
||||
should be appropriately scaled. Specific implementation details for a scalable,
|
||||
resilient web server are beyond the scope of this document.
|
||||
|
||||
Your swupd update server is just like any other web application.
|
||||
|WEB-SERVER-SCALE|
|
||||
(See :ref:`mixer` for more information about update servers.)
|
||||
|
||||
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.
|
||||
|
||||
@@ -76,48 +79,47 @@ other software development lifecycle. Below are some pointers:
|
||||
* 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
|
||||
business (e.g. performance, power, etc) from release to release.
|
||||
- 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
|
||||
control.
|
||||
- Integrate with your organization's governance processes, such as change
|
||||
control.
|
||||
|
||||
Versioning Infrastructure
|
||||
-------------------------
|
||||
Versioning infrastructure
|
||||
=========================
|
||||
|
||||
|CL| version numbers are very important as they apply to the whole
|
||||
infrastructure stack from OS components to libraries and
|
||||
applications.
|
||||
infrastructure stack from OS components to libraries and applications.
|
||||
|
||||
Good record keeping is important, so you should keep a detailed registry
|
||||
and history of previously deployed versions and their contents.
|
||||
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
|
||||
particular security vulnerability or incorporate a critical new feature.
|
||||
With a glance at the |CL| version numbers deployed, you should be 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
|
||||
installations or prebuilt images.
|
||||
*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
|
||||
@@ -127,41 +129,40 @@ See the available :ref:`image-types`.
|
||||
|
||||
Below are some common ways to install |CL| to systems at scale:
|
||||
|
||||
Baremetal
|
||||
---------
|
||||
Bare metal
|
||||
==========
|
||||
|
||||
Preboot Execution Environments (PXE) or other
|
||||
out-of-band booting options are one way to distribute |CL|
|
||||
to physical baremetal systems on a LAN.
|
||||
Preboot Execution Environments (PXE) or other out-of-band booting options are
|
||||
one way to distribute |CL| to physical bare metal systems on a LAN.
|
||||
|
||||
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 how to :ref:`bare-metal-install-server`.
|
||||
|
||||
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.
|
||||
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`.
|
||||
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
|
||||
@@ -170,16 +171,17 @@ applications.
|
||||
|
||||
|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`_.
|
||||
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
|
||||
deployment.
|
||||
|
||||
Backup strategy
|
||||
---------------
|
||||
===============
|
||||
|
||||
A |CL| system and its infrastructure should be considered a commodity and
|
||||
be easily reproducible. Avoid focusing on backing up the operating system
|
||||
@@ -187,16 +189,16 @@ 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
|
||||
`/home`, `/etc`, and `/var`.
|
||||
:file:`/home`, :file:`/etc`, and :file:`/var`.
|
||||
|
||||
Meaningful Logging & Telemetry
|
||||
------------------------------
|
||||
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`_
|
||||
`systemd-journal-remote.service`_
|
||||
|
||||
* |CL| offers a :ref:`telem-guide`, which can be a powerful tool
|
||||
for a large deployment to quickly crowdsource issues of interest. Take
|
||||
@@ -204,11 +206,12 @@ persistent and can be accessed on another server when an issue occurs.
|
||||
and the kind of data that would be valuable, and expose events
|
||||
appropriately.
|
||||
|
||||
Your telemetry server is just like any other web application.
|
||||
|WEB-SERVER-SCALE|
|
||||
Like any web server, the telemetry server should be appropriately scaled and
|
||||
resilient. Specific implementation details for a scalable, resilient web
|
||||
server are beyond the scope of this document.
|
||||
|
||||
Orchestration and Configuration Management
|
||||
------------------------------------------
|
||||
Orchestration and configuration management
|
||||
==========================================
|
||||
|
||||
In cloud environments, where systems can be ephemeral, being able to
|
||||
configure and maintain generic instances is valuable.
|
||||
@@ -217,8 +220,8 @@ configure and maintain generic instances is valuable.
|
||||
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
|
||||
the `documentation on bulk provisioning`_ .
|
||||
automating configuration during deployment of |CL| endpoints see the
|
||||
:ref:`bulk-provision` guide.
|
||||
|
||||
A configuration management tool is useful for maintaining consistent system
|
||||
and application-level configuration. Ansible\* is offered through the
|
||||
@@ -226,7 +229,7 @@ and application-level configuration. Ansible\* is offered through the
|
||||
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
|
||||
@@ -239,13 +242,10 @@ 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.
|
||||
|
||||
.. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer
|
||||
.. _`downloads page`: https://clearlinux.org/downloads/
|
||||
.. _`containers page`: https://clearlinux.org/downloads/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
|
||||
.. _`Downloads`: https://clearlinux.org/downloads/
|
||||
.. _`Containers`: https://clearlinux.org/downloads/containers
|
||||
.. _`systemd-journal-remote.service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html
|
||||
.. _`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
|
||||
|
||||
@@ -3,9 +3,13 @@
|
||||
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
|
||||
custom container image.
|
||||
This guide contains the steps to build a custom container image. The official
|
||||
base |CL-ATTR| container image is published on Docker\* Hub and is updated on a
|
||||
regular basis.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
@@ -82,24 +86,25 @@ Build the base container image
|
||||
swupd bundle-add containers-basic
|
||||
systemctl start docker
|
||||
|
||||
#. Use `os-install` to download and install the bundles.
|
||||
#. Use :command:`os-install` to download and install the bundles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base
|
||||
|
||||
|
||||
The `swupd` example uses the following flags:
|
||||
The swupd example uses the following flags:
|
||||
|
||||
* :command:`os-install` tells `swupd` to download and install.
|
||||
* :command:`os-install` tells swupd to download and install.
|
||||
* :command:`-V / --version` specifies the version of the |CL| bundles.
|
||||
* :command:`--url` specifies the URL of the bundles repository.
|
||||
* :command:`--statedir` specifies the state directory where downloaded bundles
|
||||
and any state information are stored.
|
||||
* :command:`--no-boot-update` tells `swupd` to skip updating boot files because
|
||||
* :command:`--no-boot-update` tells swupd to skip updating boot files because
|
||||
boot files are not required for a container.
|
||||
|
||||
For more information on `swupd` flags, enter the :command:`swupd os-install -h` command.
|
||||
For more information on swupd flags, enter the :command:`swupd os-install -h`
|
||||
command.
|
||||
|
||||
Example output:
|
||||
|
||||
@@ -138,7 +143,7 @@ Build the base container image
|
||||
|
||||
.. note::
|
||||
|
||||
The `WARNING` message is expected and can be ignored.
|
||||
The WARNING message is expected and can be ignored.
|
||||
|
||||
#. Create a tarball and compress it.
|
||||
|
||||
@@ -269,7 +274,7 @@ Example output:
|
||||
|
||||
.. note::
|
||||
|
||||
The `WARNING` message can be ignored because systemd does not run inside
|
||||
The WARNING message can be ignored because systemd does not run inside
|
||||
a container.
|
||||
|
||||
Remove a bundle
|
||||
|
||||
@@ -3,12 +3,19 @@
|
||||
Use DPDK to send packets between platforms
|
||||
##########################################
|
||||
|
||||
This document describes how to send packets between two platforms in the
|
||||
simple configuration shown in :ref:`Figure 1 <f1>`. The example uses the
|
||||
:abbr:`Data Plane Development Kit (DPDK)`, which is a set of libraries,
|
||||
drivers, sample applications, and tools for fast packet processing.
|
||||
This guide describes how to send packets between two platforms.
|
||||
|
||||
.. _f1:
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Figure 1 shows how to send packets between two platforms in a simple
|
||||
configuration. The example uses the :abbr:`Data Plane Development Kit (DPDK)`,
|
||||
which is a set of libraries, drivers, sample applications, and tools for fast
|
||||
packet processing.
|
||||
|
||||
.. figure:: ./figures/pktgen_lw3fd.png
|
||||
:align: center
|
||||
@@ -16,18 +23,18 @@ drivers, sample applications, and tools for fast packet processing.
|
||||
|
||||
Figure 1: Environment for l3fwd DPDK application
|
||||
|
||||
This example uses the following DPDK components:
|
||||
This example uses the following DPDK components:
|
||||
|
||||
* pktgen: Traffic generator. See `pktgen documentation`_ for details.
|
||||
* pktgen: Traffic generator. See `pktgen`_ documentation for details.
|
||||
* l3fwd: Layer 3 forwarding example application. See
|
||||
`l3fwd documentation`_ for details.
|
||||
`l3fwd`_ documentation for details.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* 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:
|
||||
* Both images must include the :command:`kernel-native` bundle.
|
||||
* Install the :command:`network-basic-dev` bundle with the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -107,7 +114,7 @@ NICs to DPDK modules to run DPDK applications.
|
||||
sudo modprobe vfio-pci
|
||||
|
||||
#. Check the NIC status to determine which network cards are not
|
||||
busy. When another application is using them, the status shows `Active`,
|
||||
busy. When another application is using them, the status shows "Active",
|
||||
and those NICs cannot be bound.
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -160,9 +167,7 @@ Set up the physical environment (Platforms A and B)
|
||||
***************************************************
|
||||
|
||||
Connect the NICs on Platform A to the NICs on Platform B using the network
|
||||
cables as shown in :ref:`Figure 2<f2>`.
|
||||
|
||||
.. _f2:
|
||||
cables as shown in figure 2.
|
||||
|
||||
.. figure:: ./figures/pyshical_net.png
|
||||
|
||||
@@ -174,7 +179,7 @@ Run l3fwd application (Platform B)
|
||||
|
||||
The `l3fwd` application is one of the DPDK examples available when you
|
||||
install the :file:`dpdk-dev` bundle. `l3fwd` forwards packets from one
|
||||
NIC to another. For details, refer to the `l3fwd documentation`_.
|
||||
NIC to another. For details, refer to the `l3fwd`_ documentation.
|
||||
|
||||
#. Open the l3fwd example directory.
|
||||
|
||||
@@ -247,7 +252,7 @@ Run pktgen application (Platform A)
|
||||
|
||||
Pktgen> start 0-1
|
||||
|
||||
For more details, see the `pktgen documentation`_.
|
||||
For more details, see the `pktgen`_ documentation.
|
||||
|
||||
Appendix A: Use pass-through for virtual machines
|
||||
*************************************************
|
||||
@@ -343,5 +348,5 @@ machines control the NICs on the host.
|
||||
.. _dpdk.org NICs: http://dpdk.org/doc/nics
|
||||
.. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs
|
||||
.. _DPDK guide: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
|
||||
.. _l3fwd documentation: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html
|
||||
.. _pktgen documentation: http://pktgen-dpdk.readthedocs.io/en/latest/index.html
|
||||
.. _l3fwd: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html
|
||||
.. _pktgen: http://pktgen-dpdk.readthedocs.io/en/latest/index.html
|
||||
|
||||
@@ -1,10 +1,17 @@
|
||||
.. _ipxe-install:
|
||||
|
||||
Install |CL-ATTR| over the network with iPXE
|
||||
############################################
|
||||
Install over the network with iPXE
|
||||
##################################
|
||||
|
||||
This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot
|
||||
Execution Environment)`.
|
||||
Execution Environment)` over the network.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
PXE is an industry standard that describes client-server interaction with
|
||||
network-boot software and uses the DHCP and TFTP protocols. This guide shows one
|
||||
@@ -35,7 +42,7 @@ Prerequisites
|
||||
Before booting with iPXE, make the following preparations.
|
||||
|
||||
Connect the PXE server and PXE clients to a switch on a private network, as
|
||||
shown in Figure 2.
|
||||
shown in figure 2.
|
||||
|
||||
.. figure:: ./figures/network-boot-setup.png
|
||||
:alt: Network topology
|
||||
@@ -63,7 +70,8 @@ Configuration
|
||||
|
||||
To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh`
|
||||
script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional
|
||||
instructions on the script, refer to the guide on the `ICIS GitHub repository`_.
|
||||
instructions on the script, refer to the guide on the `ister-cloud-init-svc`_
|
||||
GitHub\* repository.
|
||||
|
||||
To set up |CL| manually, perform the steps below.
|
||||
|
||||
@@ -89,7 +97,7 @@ To set up |CL| manually, perform the steps below.
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Add the `pxe-server` bundle to your |CL| system. The bundle contains all
|
||||
#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all
|
||||
files needed to run a PXE server.
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -130,8 +138,8 @@ To set up |CL| manually, perform the steps below.
|
||||
boot
|
||||
EOF
|
||||
|
||||
#. The `pxe-server` bundle contains a lightweight web-server known as
|
||||
`nginx`. Create a configuration file for `nginx` to serve |CL| to PXE
|
||||
#. The :command:`pxe-server` bundle contains a lightweight web-server known as
|
||||
nginx. Create a configuration file for nginx to serve |CL| to PXE
|
||||
clients with the following contents:
|
||||
|
||||
.. code-block:: console
|
||||
@@ -152,18 +160,18 @@ To set up |CL| manually, perform the steps below.
|
||||
|
||||
.. note::
|
||||
|
||||
Create a separate `nginx` configuration file to serve network-bootable
|
||||
images on a non-standard port number. This action saves existing `nginx`
|
||||
Create a separate nginx configuration file to serve network-bootable
|
||||
images on a non-standard port number. This action saves existing nginx
|
||||
configurations.
|
||||
|
||||
#. Start `nginx` and enable the startup on boot option.
|
||||
#. Start nginx and enable the startup on boot option.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl start nginx
|
||||
sudo systemctl enable nginx
|
||||
|
||||
#. The `pxe-server` bundle contains a lightweight DNS server which
|
||||
#. The :command:`pxe-server` bundle contains a lightweight DNS server which
|
||||
conflicts with the DNS stub listener provided in `systemd-resolved`.
|
||||
Disable the DNS stub listener and temporarily stop `systemd-resolved`.
|
||||
|
||||
@@ -221,7 +229,7 @@ To set up |CL| manually, perform the steps below.
|
||||
sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
|
||||
sudo echo 1 > /proc/sys/net/ipv4/ip_forward
|
||||
|
||||
#. The `pxe-server` bundle contains iPXE firmware images that allow computers
|
||||
#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers
|
||||
without an iPXE implementation to perform an iPXE boot. Create a TFTP
|
||||
hosting directory and populate the directory with the iPXE firmware images
|
||||
with the following commands:
|
||||
@@ -231,7 +239,7 @@ To set up |CL| manually, perform the steps below.
|
||||
sudo mkdir -p $tftp_root
|
||||
sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
|
||||
|
||||
#. The `pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP
|
||||
#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP
|
||||
server known as `dnsmasq`. Create a configuration file for `dnsmasq`
|
||||
to listen on a dedicated IP address for those functions. PXE clients on
|
||||
the private network will use this IP address.
|
||||
@@ -252,7 +260,7 @@ To set up |CL| manually, perform the steps below.
|
||||
tftp-root=$tftp_root
|
||||
EOF
|
||||
|
||||
#. Add the options to host a DHCP server for PXE clients to the `dnsmasq`
|
||||
#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq`
|
||||
configuration file.
|
||||
|
||||
.. code-block:: console
|
||||
@@ -328,5 +336,5 @@ server that enables PXE clients to boot and install |CL| over the network.
|
||||
.. _iPXE:
|
||||
http://ipxe.org/
|
||||
|
||||
.. _ICIS GitHub repository:
|
||||
.. _ister-cloud-init-svc:
|
||||
https://github.com/clearlinux/ister-cloud-init-svc
|
||||
|
||||
@@ -3,19 +3,21 @@
|
||||
Combine multiple interfaces with network bonding
|
||||
################################################
|
||||
|
||||
This guide describes how to configure systemd to use the :command:`bonding`
|
||||
driver.
|
||||
|
||||
Network bonding combines multiple network interfaces into a single logical
|
||||
interface to provide redundancy and bandwidth aggregation.
|
||||
|
||||
|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how
|
||||
to configure systemd to use the `bonding` driver.
|
||||
|CL-ATTR| includes the Linux `Bonding driver`_ and `Team driver`_ .
|
||||
|
||||
The example demonstrates how to:
|
||||
|
||||
* Bond all four ports of a quad-port NIC in `802.3ad` mode.
|
||||
* Bond all four ports of a quad-port NIC in 802.3ad mode.
|
||||
|
||||
* Enable jumbo frames to optimize large data transfers on the local network.
|
||||
|
||||
Your NICs and network switch must support `802.3ad` mode and jumbo frames. The
|
||||
Your NICs and network switch must support 802.3ad mode and jumbo frames. The
|
||||
example explains how to configure your NICs for both features. Your switch may
|
||||
require additional configuration. See your switch documentation for details.
|
||||
|
||||
@@ -54,13 +56,13 @@ require additional configuration. See your switch documentation for details.
|
||||
MIIMonitorSec=1s
|
||||
LACPTransmitRate=fast
|
||||
|
||||
Refer to the systemd.netdev_ manpage for :file:`30-bond1.netdev` file
|
||||
Refer to the `systemd.netdev`_ manpage for :file:`30-bond1.netdev` file
|
||||
syntax. This example is based on Example 9 on the manpage. Modify the
|
||||
example for your configuration.
|
||||
|
||||
#. Configure the slave interfaces. Create a text file named
|
||||
:file:`30-bond1-enp1s0.network`. Assign the slave interfaces to the virtual
|
||||
`bond1` device and use the syntax shown in systemd.network_.
|
||||
`bond1` device and use the syntax shown in `systemd.network`_.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -117,16 +119,12 @@ require additional configuration. See your switch documentation for details.
|
||||
systemctl restart systemd-networkd
|
||||
|
||||
The `MTUBytes` settings do not take effect until you reboot or manually
|
||||
apply the settings with a utility such as `ifconfig`.
|
||||
apply the settings with a utility such as ifconfig.
|
||||
|
||||
.. _bonding:
|
||||
https://www.kernel.org/doc/Documentation/networking/bonding.txt
|
||||
.. _Bonding driver: https://www.kernel.org/doc/Documentation/networking/bonding.txt
|
||||
|
||||
.. _team:
|
||||
https://www.kernel.org/doc/Documentation/networking/team.txt
|
||||
.. _Team driver: https://www.kernel.org/doc/Documentation/networking/team.txt
|
||||
|
||||
.. _systemd.netdev:
|
||||
https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
|
||||
.. _systemd.netdev: https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
|
||||
|
||||
.. _systemd.network:
|
||||
https://www.freedesktop.org/software/systemd/man/systemd.network.html
|
||||
.. _systemd.network: https://www.freedesktop.org/software/systemd/man/systemd.network.html
|
||||
|
||||
@@ -1,42 +1,40 @@
|
||||
.. _vnc:
|
||||
|
||||
Remote-desktop to a |CL-ATTR| host using VNC
|
||||
##############################################
|
||||
Remote-desktop to a 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 |CL-ATTR| host.
|
||||
This guide describes how to use :abbr:`VNC (Virtual Network Computing)` to
|
||||
connect to a remote |CL-ATTR| host.
|
||||
|
||||
This guide shows you how to:
|
||||
VNC is a client-server GUI-based tool that allows you to connect via
|
||||
remote-desktop to your |CL| host.
|
||||
|
||||
* 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.
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
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
|
||||
* :command:`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.
|
||||
* :command:`vnc-server`: Installs the TigerVNC server.
|
||||
|
||||
Follow these steps:
|
||||
|
||||
#. Log into your |CL| host and get root privileges.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo -s
|
||||
sudo -s
|
||||
|
||||
#. Install the |CL| bundles.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# swupd bundle-add desktop-autostart vnc-server
|
||||
swupd bundle-add desktop-autostart vnc-server
|
||||
|
||||
#. Reboot your |CL| host.
|
||||
|
||||
@@ -51,9 +49,9 @@ your |CL| host:
|
||||
:header-rows: 1
|
||||
|
||||
* - Attribute
|
||||
- `Method 1`: Manually start a VNC session
|
||||
- `Method 2`: Automatically start a VNC session via a systemd service script
|
||||
- `Method 3`: Create multi-user logins with authentication through GDM
|
||||
- Method 1: Manually start a VNC session
|
||||
- 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
|
||||
@@ -86,7 +84,7 @@ 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
|
||||
`Method 1`, `Method 2`, and `Method 3`.
|
||||
Method 1, Method 2, and Method 3.
|
||||
|
||||
Method 1: Manually start a VNC session
|
||||
======================================
|
||||
@@ -99,16 +97,14 @@ You (and each user) must perform these steps to initialize your VNC settings.
|
||||
first time starting VNC, it adds default configuration files and asks you
|
||||
to set a VNC password.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver
|
||||
vncserver
|
||||
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ vncserver
|
||||
|
||||
You will require a password to access your desktops.
|
||||
|
||||
Password:
|
||||
@@ -124,19 +120,20 @@ You (and each user) must perform these steps to initialize your VNC settings.
|
||||
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.
|
||||
password file hidden in the :file:`.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
|
||||
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]
|
||||
with your active VNC session display ID. For example:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver -kill :2
|
||||
vncserver -kill :2
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -159,29 +156,29 @@ preassigned unique display ID.
|
||||
|
||||
#. Log in and get root privileges.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo -s
|
||||
sudo -s
|
||||
|
||||
#. Make sure the user accounts already exist. Use the following command to
|
||||
list all users.
|
||||
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# cut -d: -f1 /etc/passwd
|
||||
cut -d: -f1 /etc/passwd
|
||||
|
||||
#. Create the path :file:`/etc/systemd/system`.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# 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`.
|
||||
username is entered in the :guilabel:`User` field. The example below shows user
|
||||
vnc-user-b who is assigned the display ID 5.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -211,20 +208,20 @@ preassigned unique 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:: bash
|
||||
|
||||
# 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.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# 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.
|
||||
users vnc-user-b with display ID 5 and vnc-user-c with display ID 6.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -239,19 +236,21 @@ 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.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo -s
|
||||
sudo -s
|
||||
|
||||
#. Create the path :file:`/etc/systemd/system`.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# mkdir -p /etc/systemd/system
|
||||
mkdir -p /etc/systemd/system
|
||||
|
||||
#. Create a systemd socket file :file:`xvnc.socket` and add the following:
|
||||
|
||||
@@ -290,9 +289,9 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
|
||||
|
||||
#. Create the path :file:`/etc/gdm`.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# mkdir -p /etc/gdm
|
||||
mkdir -p /etc/gdm
|
||||
|
||||
|
||||
#. Create a GDM :file:`custom.conf` file and add the following:
|
||||
@@ -309,17 +308,17 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
|
||||
|
||||
#. Start the VNC socket script and set it to start automatically on boot.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# 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.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# systemctl | grep vnc
|
||||
systemctl | grep vnc
|
||||
|
||||
The example below shows the xvnc.socket is running.
|
||||
|
||||
@@ -330,13 +329,13 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
|
||||
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.
|
||||
See the vncserver Man page for additional information.
|
||||
|
||||
Install a VNC viewer app and an SSH client on your client system
|
||||
****************************************************************
|
||||
|
||||
You need a VNC viewer app on your client system to connect to your |CL| host.
|
||||
An SSH client is only needed if you chose to use `Method 1` or you plan to
|
||||
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.
|
||||
@@ -346,27 +345,27 @@ Install a VNC viewer app
|
||||
|
||||
On |CL|:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# swupd bundle-add desktop-autostart
|
||||
swupd bundle-add desktop-autostart
|
||||
|
||||
On Ubuntu, Mint:
|
||||
On Ubuntu\*, Mint\*:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# apt-get install xtightvncviewer
|
||||
apt-get install xtightvncviewer
|
||||
|
||||
On Fedora:
|
||||
On Fedora\*:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# dnf install tigervnc
|
||||
dnf install tigervnc
|
||||
|
||||
On Windows:
|
||||
On Windows\*:
|
||||
|
||||
* Install `RealVNC for Windows`_
|
||||
|
||||
On macOS:
|
||||
On macOS\*:
|
||||
|
||||
* Install `RealVNC for macOS`_
|
||||
|
||||
@@ -380,17 +379,17 @@ Install an SSH client
|
||||
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
|
||||
: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.
|
||||
* If you chose Method 3, proceed to the :ref:`connect-to-vnc-session` below.
|
||||
|
||||
|
||||
SSH into your host and launch VNC
|
||||
@@ -400,9 +399,9 @@ SSH into your host and launch VNC
|
||||
|
||||
#. On Linux distros and macOS:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ ssh [username]@[clear-linux-host-ip-address]
|
||||
ssh [username]@[clear-linux-host-ip-address]
|
||||
|
||||
#. On Windows:
|
||||
|
||||
@@ -420,20 +419,17 @@ SSH into your 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
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver
|
||||
vncserver
|
||||
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ vncserver
|
||||
|
||||
New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3
|
||||
|
||||
Starting applications specified in /home/vnc-user-c/.vnc/xstartup
|
||||
@@ -449,9 +445,9 @@ SSH into your host and launch VNC
|
||||
To specify a display ID, enter a unique number that is not already
|
||||
in use after the colon. For example:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver :8
|
||||
vncserver :8
|
||||
|
||||
#. You can now end the SSH connection by logging out. This does
|
||||
not terminate your active VNC session.
|
||||
@@ -461,38 +457,38 @@ SSH into your host and launch VNC
|
||||
Connect to your VNC session
|
||||
===========================
|
||||
|
||||
For `Method 1` and `Method 2`, you must connect to a specific active session
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**On Linux distros:**
|
||||
|
||||
#. Open a terminal emulator and enter:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number]
|
||||
vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number]
|
||||
|
||||
#. Enter your credentials.
|
||||
|
||||
* For `Method 1` and `Method 2`, enter your VNC password. No username is
|
||||
* 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
|
||||
* 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
|
||||
With Method 3, you cannot remotely log into your |CL| host through
|
||||
VNC if you are logged in locally and vice versa.
|
||||
|
||||
**On Windows and macOS using `RealVNC` app:**
|
||||
**On Windows and macOS using RealVNC app:**
|
||||
|
||||
#. Start the RealVNC viewer app. See Figure 2.
|
||||
#. Enter the IP address of the |CL| host and the fully-qualified
|
||||
@@ -511,20 +507,21 @@ number.
|
||||
|
||||
#. Enter your credentials.
|
||||
|
||||
* For `Method 1` and `Method 2`, enter your VNC password. No username is
|
||||
* 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
|
||||
* 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
|
||||
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:
|
||||
To increase the RealVNC viewer image quality, manually change the :guilabel:`ColorLevel`
|
||||
value. Follow these steps:
|
||||
|
||||
#. Right-click a connection node and select :guilabel:`Properties...`.
|
||||
See Figure 3.
|
||||
@@ -549,7 +546,7 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v
|
||||
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:
|
||||
|
||||
@@ -558,24 +555,24 @@ truly terminate an active VNC session, follow these steps:
|
||||
#. Find the active VNC session display ID with the command
|
||||
:command:`vncserver -list`.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver -list
|
||||
vncserver -list
|
||||
|
||||
#. Terminate it with the :command:`vncserver -kill` command followed by a
|
||||
colon and the display ID.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncserver -kill :[display ID]
|
||||
vncserver -kill :[display ID]
|
||||
|
||||
#. For `Method 3`, only the system administrator can stop and disable the
|
||||
#. For Method 3, only the system administrator can stop and disable the
|
||||
VNC service by using these commands:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# systemctl stop xvnc.socket
|
||||
# systemctl disable xnvc.socket
|
||||
systemctl stop xvnc.socket
|
||||
systemctl disable xnvc.socket
|
||||
|
||||
|
||||
Encrypt VNC traffic through an SSH tunnel
|
||||
@@ -590,10 +587,11 @@ from RealVNC Viewer.
|
||||
|
||||
Figure 6: RealVNC Viewer - Connection not encrypted warning
|
||||
|
||||
To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps:
|
||||
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
|
||||
adding the `-localhost` option.
|
||||
adding the :command:`-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)
|
||||
@@ -604,7 +602,7 @@ To add security, VNC traffic can be routed through an SSH tunnel. This is accomp
|
||||
Configure VNC to only accept connection from localhost
|
||||
======================================================
|
||||
|
||||
For `Method 1`:
|
||||
For Method 1:
|
||||
|
||||
#. Edit the :file:`config` file located in :file:`$HOME/.vnc` and uncomment
|
||||
the `# localhost` line. It should look like this:
|
||||
@@ -624,10 +622,10 @@ For `Method 1`:
|
||||
|
||||
#. If an active session exists, kill it, and then restart it.
|
||||
|
||||
For `Method 2`:
|
||||
For Method 2:
|
||||
|
||||
#. Edit the systemd service script :file:`vncserver@:[X].service` located in
|
||||
:file:`/etc/systemd/system` and add `-localhost` to the `ExecStart`
|
||||
:file:`/etc/systemd/system` and add :command:`-localhost` to the `ExecStart`
|
||||
line. The example below uses vncserver@:5.service:
|
||||
|
||||
.. code-block:: console
|
||||
@@ -650,12 +648,12 @@ For `Method 2`:
|
||||
|
||||
#. Restart the service script:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
# systemctl daemon-load
|
||||
# systemctl restart vncserver@:5.service
|
||||
systemctl daemon-load
|
||||
systemctl restart vncserver@:5.service
|
||||
|
||||
For `Method 3`:
|
||||
For Method 3:
|
||||
|
||||
#. No change is needed to the :file:`xvnc@service` script.
|
||||
|
||||
@@ -663,17 +661,18 @@ For `Method 3`:
|
||||
accepts connections from localhost by using the :command:`netstat`
|
||||
command like this:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ netstat -plant
|
||||
netstat -plant
|
||||
|
||||
.. note::
|
||||
|
||||
Add the |CL| `network-basic` bundle to get the :command:`netstat`
|
||||
Add the |CL| :command:`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.
|
||||
any host as specified by the `0.0.0.0`'s. This is before the
|
||||
:command:`-localhost` option was used.
|
||||
|
||||
.. figure:: figures/vnc/vnc-7.png
|
||||
:scale: 100 %
|
||||
@@ -681,7 +680,9 @@ 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
|
||||
:command:`-localhost` option was used.
|
||||
|
||||
.. figure:: figures/vnc/vnc-8.png
|
||||
:scale: 100 %
|
||||
@@ -696,9 +697,9 @@ Set up an SSH tunnel from your client system to your |CL| host
|
||||
|
||||
#. Open terminal emulator and enter:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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).
|
||||
@@ -763,9 +764,9 @@ your VNC session.
|
||||
|
||||
#. Open terminal emulator and enter:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ vncviewer localhost:[client port number]
|
||||
vncviewer localhost:[client port number]
|
||||
|
||||
**On Windows and macOS using `RealVNC`:**
|
||||
|
||||
|
||||
@@ -3,10 +3,7 @@
|
||||
Telemetrics
|
||||
###########
|
||||
|
||||
Telemetrics in |CL-ATTR| is a client and server solution used to collect
|
||||
data from running |CL| systems to help quickly identify and fix bugs in the
|
||||
OS. Both client and server are customizable, and an API is available on the
|
||||
client side for instrumenting your code for debug and analysis.
|
||||
This guide describes the |CL-ATTR| telemetry solution.
|
||||
|
||||
.. important::
|
||||
|
||||
@@ -17,17 +14,22 @@ client side for instrumenting your code for debug and analysis.
|
||||
|
||||
The telemetry functionality adheres to `Intel privacy policies`_ regarding
|
||||
the collection and use of :abbr:`PII (Personally Identifiable Information)`
|
||||
and is open source.
|
||||
Specifically, no intentionally identifiable information about the user or
|
||||
system owner is collected.
|
||||
and is open source.
|
||||
|
||||
No intentionally identifiable information about the user or system owner is
|
||||
collected.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Description
|
||||
***********
|
||||
Telemetrics in |CL| is a client and server solution used to collect
|
||||
data from running |CL| systems to help quickly identify and fix bugs in the
|
||||
OS. Both client and server are customizable, and an API is available on the
|
||||
client side for instrumenting your code for debug and analysis.
|
||||
|
||||
Telemetry, one of the key features of |CL|, enables developers to observe and
|
||||
proactively address issues in the OS before end users are impacted.
|
||||
@@ -57,7 +59,7 @@ Enabling the client is covered in this guide.
|
||||
Architecture
|
||||
============
|
||||
|
||||
|CL| telemetry has two fundamental components, which are shown in figure 1:
|
||||
|CL| telemetry has two fundamental components, which are shown in Figure 1:
|
||||
|
||||
* Client: generates and delivers records to the backend server via the network.
|
||||
|
||||
@@ -125,7 +127,7 @@ Scenarios
|
||||
|
||||
#. Save record data locally:
|
||||
|
||||
You can configure the telemetry client to save records locally. This is
|
||||
You can configure the telemetry client to save records locally. This is
|
||||
convenient when you want instant feedback during a development cycle, or to
|
||||
track system issues if you believe there is a machine specific problem. The
|
||||
client can be set not to send records at all, or to both keep the records
|
||||
@@ -141,7 +143,7 @@ Scenarios
|
||||
|
||||
#. Instrument your code with the libtelemetry API:
|
||||
|
||||
The ``telemetrics`` bundle includes the libtelemetry C library, which
|
||||
The :command:`telemetrics` bundle includes the libtelemetry C library, which
|
||||
exposes an API used by the telemprobd and telempostd daemons. You can use
|
||||
these in your applications as well. The API documentation is found in the
|
||||
:file:`telemetry.h` file in `Telemetrics client`_ repository.
|
||||
@@ -228,10 +230,10 @@ system.
|
||||
|
||||
To change how records are managed, copy the default
|
||||
:file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to
|
||||
:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
|
||||
:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
|
||||
:file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in
|
||||
the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need
|
||||
``root`` permissions to create and edit files in :file:`/etc`. For each
|
||||
root permissions to create and edit files in :file:`/etc`. For each
|
||||
example, and for any time you make changes to the configuration file, you must
|
||||
restart the client daemons to pick up the changes:
|
||||
|
||||
@@ -249,15 +251,15 @@ Use :command:`-h` or :command:`--help` to view usage options.
|
||||
#. Keep a local copy and send records to backend server:
|
||||
|
||||
To keep a local copy of the telemetry record and also send it on to the
|
||||
backend server, we will need to change the :guilabel:`
|
||||
record_retention_enabled` configuration key value to :guilabel:`true`.
|
||||
|
||||
backend server, we will need to change the
|
||||
:guilabel:`record_retention_enabled` configuration key value to
|
||||
:guilabel:`true`.
|
||||
|
||||
#. Keep all records -- don't send to backend server:
|
||||
|
||||
To keep records on the system without sending them to a backend server, set
|
||||
the :guilabel:`record_server_delivery_enabled` key value to
|
||||
:guilabel:`false`. Note that you will also need to ensure the
|
||||
:guilabel:`false`. Note that you will also need to ensure the
|
||||
:guilabel:`record_retention_enabled` configuration key value is set to
|
||||
:guilabel:`true` or the system will not keep local copies.
|
||||
|
||||
@@ -266,9 +268,9 @@ Use :command:`-h` or :command:`--help` to view usage options.
|
||||
This assumes you have set up a custom server according to the next example.
|
||||
|
||||
The server is identified by the :guilabel:`server` setting, and by default
|
||||
records are sent to the |CL| server :guilabel:`server=https://clr.
|
||||
telemetry.intel.com/v2/collector`. To change this, you can use an IP
|
||||
address or fully qualified domain name.
|
||||
records are sent to the |CL| server
|
||||
:guilabel:`server=https://clr.telemetry.intel.com/v2/collector`. To change
|
||||
this, you can use an IP address or fully qualified domain name.
|
||||
|
||||
|
||||
Set up a back-end server to collect telemetry records
|
||||
@@ -303,13 +305,13 @@ using the :ref:`bare-metal-install-server` getting started guide and:
|
||||
#. Before you install the telemetrics backend with the :file:`deploy.sh` script
|
||||
file in the next step, here is an explanation of the options to be specified:
|
||||
|
||||
* *-a install* to perform an install
|
||||
* *-d clr* to install to a |CL| distro
|
||||
* *-H localhost* to set the domain to localhost
|
||||
* :command:`-a install` to perform an install
|
||||
* :command:`-d clr` to install to a |CL| distro
|
||||
* :command:`-H localhost` to set the domain to localhost
|
||||
|
||||
.. caution::
|
||||
The :file:`deploy.sh` shell script has minimal error checking and makes
|
||||
several changes to your system. Be sure that the options you define on
|
||||
several changes to your system. Be sure that the options you define on
|
||||
the cmdline are correct before proceeding.
|
||||
|
||||
#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts`
|
||||
@@ -358,26 +360,24 @@ using the :ref:`bare-metal-install-server` getting started guide and:
|
||||
passwd: password updated successfully
|
||||
|
||||
Enter `postgres` for the current value of the password and then enter a new
|
||||
password, retype it to verify the new password and the
|
||||
:guilabel:`PostgreSQL` database password will be updated.
|
||||
password, retype it to verify the new password and the :guilabel:`PostgreSQL`
|
||||
database password will be updated.
|
||||
|
||||
#. After the installation is complete, you can use your web browser to view the
|
||||
new server by opening the browser on the system and typing in ``localhost``
|
||||
in the address bar. You should see a web page similar to the one shown in
|
||||
figure 1:
|
||||
new server by opening the browser on the system and typing in localhost
|
||||
in the address bar. You should see a web page similar to the one shown in
|
||||
Figure 2 below.
|
||||
|
||||
.. figure:: figures/telemetry-backend-1.png
|
||||
:alt: Telemetry UI
|
||||
|
||||
Figure 1: :guilabel:`Telemetry UI`
|
||||
|
||||
|
||||
Figure 2: :guilabel:`Telemetry UI`
|
||||
|
||||
Create records with telem-record-gen
|
||||
====================================
|
||||
|
||||
The telemetrics bundle provides a record generator tool called
|
||||
``telem-record-gen``. This tool can be used to create records from shell
|
||||
`telem-record-gen`. This tool can be used to create records from shell
|
||||
scripts or the command line when writing a probe in C is not desirable.
|
||||
Records are sent to the backend server, and can also be echoed to stdout.
|
||||
|
||||
@@ -470,7 +470,7 @@ Set a static machine id
|
||||
|
||||
The machine id reported by the telemetry client is rotated every three days
|
||||
for privacy reasons. If you wish to have a static machine id for testing
|
||||
purposes, you can opt in by creating a file named "opt-in-static-machine-id"
|
||||
purposes, you can opt in by creating a file named `opt-in-static-machine-id`
|
||||
in the directory :file:`/etc/telemetrics/`.
|
||||
|
||||
#. Create a directory `telemetrics`.
|
||||
@@ -489,7 +489,7 @@ in the directory :file:`/etc/telemetrics/`.
|
||||
|
||||
.. note::
|
||||
|
||||
The `machine id` is different than the system hostname.
|
||||
The machine ID is different than the system hostname.
|
||||
|
||||
Instrument your code with the libtelemetry API
|
||||
==============================================
|
||||
@@ -499,8 +499,8 @@ Prerequisites
|
||||
|
||||
Confirm that the telemetrics header file is located on the system at
|
||||
:file:`usr/include/telemetry.h` The `latest version`_ of the file can also be
|
||||
found on github for reference, but installing the `telemetry` bundle will
|
||||
install the header file that matches your |CL| version.
|
||||
found on github for reference, but installing the :command:`telemetry` bundle
|
||||
will install the header file that matches your |CL| version.
|
||||
|
||||
#. Includes and variables:
|
||||
|
||||
@@ -560,9 +560,8 @@ install the header file that matches your |CL| version.
|
||||
Type: char pointer
|
||||
Value: The payload to set
|
||||
|
||||
|
||||
|
||||
#. For this example, we'll set the payload to “hello” by using ``asprintf()``:
|
||||
#. For this example, we'll set the payload to “hello” by using
|
||||
:command:`asprintf()`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -570,21 +569,19 @@ install the header file that matches your |CL| version.
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
|
||||
|
||||
|
||||
The functions ``asprintf()`` and ``vasprintf()`` are analogs of
|
||||
``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string
|
||||
large enough to hold the output including the terminating null byte ('\0'),
|
||||
and return a pointer to it via the first argument. This pointer should be
|
||||
passed to ``free(3)`` to release the allocated storage when it is no longer
|
||||
needed.
|
||||
The functions :command:`asprintf()` and :command:`vasprintf()` are analogs of
|
||||
:command:`sprintf(3)` and :command:`vsprintf(3)`, except that they allocate a
|
||||
string large enough to hold the output including the terminating null byte
|
||||
('\0'), and return a pointer to it via the first argument. This pointer
|
||||
should be passed to :command:`free(3)` to release the allocated storage when
|
||||
it is no longer needed.
|
||||
|
||||
#. Create the new telemetry record:
|
||||
|
||||
The function ``tm_create_record()`` initializes a telemetry record and
|
||||
The function :command:`tm_create_record()` initializes a telemetry record and
|
||||
sets the severity and classification of that record, as well as the payload
|
||||
version number. The memory needed to store the telemetry record is allocated
|
||||
and should be freed with ``tm_free_record()`` when no longer needed.
|
||||
and should be freed with :command:`tm_free_record()` when no longer needed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -596,7 +593,7 @@ install the header file that matches your |CL| version.
|
||||
|
||||
#. Set the payload field of a telemetrics record:
|
||||
|
||||
The function ``tm_set_payload()`` attaches the provided telemetry record
|
||||
The function :command:`tm_set_payload()` attaches the provided telemetry record
|
||||
data to the telemetry record. The current maximum payload size is 8192b.
|
||||
|
||||
.. code-block:: console
|
||||
@@ -608,17 +605,17 @@ install the header file that matches your |CL| version.
|
||||
}
|
||||
free(payload);
|
||||
|
||||
The ``free()`` function frees the memory space pointed to by ptr, which
|
||||
must have been returned by a previous call to ``malloc()``, ``calloc()``,
|
||||
or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called
|
||||
before, undefined behavior occurs. If ptr is NULL, no operation is
|
||||
performed.
|
||||
The :command:`free()` function frees the memory space pointed to by `ptr`, which
|
||||
must have been returned by a previous call to :command:`malloc()`,
|
||||
:command:`calloc()`, or :command:`realloc()`. Otherwise, or if
|
||||
:command:`free(ptr)` has already been called before, undefined behavior
|
||||
occurs. If `ptr` is NULL, no operation is performed.
|
||||
|
||||
#. Send a record to the telemetrics daemon:
|
||||
|
||||
The function ``tm_send_record()`` delivers the record to the local
|
||||
``telemprobd(1)`` service. Since the telemetry record was allocated by
|
||||
the program it should be freed with ``tm_free_record()`` when it is no
|
||||
The function :command:`tm_send_record()` delivers the record to the local
|
||||
:command:`telemprobd(1)` service. Since the telemetry record was allocated by
|
||||
the program it should be freed with :command:`tm_free_record()` when it is no
|
||||
longer needed.
|
||||
|
||||
.. code-block:: console
|
||||
@@ -640,7 +637,7 @@ install the header file that matches your |CL| version.
|
||||
|
||||
#. A full sample application with compiling flags:
|
||||
|
||||
Create a new file test.c and add the following code:
|
||||
Create a new file :file:`test.c` and add the following code:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -724,7 +721,7 @@ Reference
|
||||
The telemetry API
|
||||
=================
|
||||
|
||||
Installing the ``telemetrics`` bundle includes the libtelemetry C library,
|
||||
Installing the :command:`telemetrics` bundle includes the libtelemetry C library,
|
||||
which exposes an API used by the telemprobd and telempostd daemons. You can
|
||||
use these in your applications as well. The API documentation is found in the
|
||||
:file:`telemetry.h` file in `Telemetrics client`_ repository.
|
||||
@@ -744,54 +741,63 @@ Configuration options
|
||||
|
||||
The client uses the following configuration options from the config file:
|
||||
|
||||
* **server**: This specifies the web server to which telempostd sends the
|
||||
telemetry records.
|
||||
* **socket_path**: This specifies the path of the unix domain socket on which
|
||||
the telemprobd listens for connections from the probes.
|
||||
* **spool_dir**: This configuration option is related to spooling. If the
|
||||
daemon is not able to send the telemetry records to the backend server due
|
||||
to reasons such as the network availability, then it stores the records in
|
||||
a spool directory. This option specifies the path of the spool directory.
|
||||
This directory should be owned by the same user as the daemon.
|
||||
* **record_expiry**: This is the time, in minutes, after which the records in
|
||||
the spool directory are deleted by the daemon.
|
||||
* **spool_process_time**: This specifies the time interval, in seconds, that
|
||||
the daemon waits for before checking the spool directory for records. The
|
||||
daemon picks up the records in the order of modification date and tries to
|
||||
send the record to the server. It sends a maximum of 10 records at a time.
|
||||
If it was able to send a record successfully, it deletes the record from the
|
||||
spool. If the daemon finds a record older than the "record_expiry" time, then
|
||||
it deletes that record. The daemon looks at a maximum of 20 records in a
|
||||
single spool run loop.
|
||||
* **rate_limit_enabled**: This determines whether rate-limiting is enabled
|
||||
or disabled. When enabled, there is a threshold on both records sent within
|
||||
a window of time, and record bytes sent within a window a time.
|
||||
* **record_burst_limit**: This is the maximum amount of records allowed to be
|
||||
passed by the daemon within the record_window_length of time. If set to -1,
|
||||
the rate-limiting for record bursts is disabled.
|
||||
* **record_window_length**: The time, in minutes (0-59), that establishes the
|
||||
window length for the record_burst_limit. For example, if
|
||||
record_burst_window=1000 and record_window_length=15, then no more than
|
||||
1000 records can be passed within any given fifteen-minute window.
|
||||
* **byte_burst_limit**: This is the maximum amount of bytes that can be
|
||||
passed by the daemon within the byte_window_length of time. If set to -1,
|
||||
the rate-limiting for byte bursts is disabled.
|
||||
* **byte_window_length**: This is the time, in minutes (0-59), that establishes
|
||||
the window length for the byte_burst_limit.
|
||||
* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting
|
||||
threshold has been reached. Currently the options are 'drop' or 'spool',
|
||||
with spool being the default. If spool is chosen, records will be spooled
|
||||
and sent at a later time.
|
||||
* **record_retention_enabled**: When this key is enabled (true) the daemon
|
||||
saves a copy of the payload on disk from all valid records. To avoid the
|
||||
excessive use of disk space only the latest 100 records are kept. The default
|
||||
value for this configuration key is false.
|
||||
* **record_server_delivery_enabled**: This key controls the delivery of
|
||||
records to server; when enabled (default value), the record will be posted to
|
||||
the address in the configuration file. If this configuration key is disabled
|
||||
(false), records will not be spooled or posted to backend. This configuration
|
||||
key can be used in combination with record_retention_enabled to keep copies
|
||||
of telemetry records locally only.
|
||||
server
|
||||
This specifies the web server to which telempostd sends the telemetry records.
|
||||
socket_path
|
||||
This specifies the path of the unix domain socket on which the telemprobd
|
||||
listens for connections from the probes.
|
||||
spool_dir
|
||||
This configuration option is related to spooling. If the daemon is not able
|
||||
to send the telemetry records to the backend server due to reasons such as
|
||||
the network availability, then it stores the records in a spool directory.
|
||||
This option specifies the path of the spool directory. This directory should
|
||||
be owned by the same user as the daemon.
|
||||
record_expiry
|
||||
This is the time, in minutes, after which the records in the spool directory
|
||||
are deleted by the daemon.
|
||||
spool_process_time
|
||||
This specifies the time interval, in seconds, that the daemon waits for
|
||||
before checking the spool directory for records. The daemon picks up the
|
||||
records in the order of modification date and tries to send the record to the
|
||||
server. It sends a maximum of 10 records at a time. If it was able to send a
|
||||
record successfully, it deletes the record from the spool. If the daemon
|
||||
finds a record older than the "record_expiry" time, then it deletes that
|
||||
record. The daemon looks at a maximum of 20 records in a single spool run loop.
|
||||
rate_limit_enabled
|
||||
This determines whether rate-limiting is enabled or disabled. When enabled,
|
||||
there is a threshold on both records sent within a window of time, and record
|
||||
bytes sent within a window a time.
|
||||
record_burst_limit
|
||||
This is the maximum amount of records allowed to be passed by the daemon
|
||||
within the record_window_length of time. If set to -1, the rate-limiting for
|
||||
record bursts is disabled.
|
||||
record_window_length
|
||||
The time, in minutes (0-59), that establishes the window length for the
|
||||
record_burst_limit. For example, if record_burst_window=1000 and
|
||||
record_window_length=15, then no more than 1000 records can be passed within
|
||||
any given fifteen-minute window.
|
||||
byte_burst_limit
|
||||
This is the maximum amount of bytes that can be passed by the daemon within
|
||||
the byte_window_length of time. If set to -1, the rate-limiting for byte
|
||||
bursts is disabled.
|
||||
byte_window_length
|
||||
This is the time, in minutes (0-59), that establishes the window length for
|
||||
the byte_burst_limit.
|
||||
rate_limit_strategy
|
||||
This is the strategy chosen once the rate-limiting threshold has been
|
||||
reached. Currently the options are 'drop' or 'spool', with spool being the
|
||||
default. If spool is chosen, records will be spooled and sent at a later time.
|
||||
record_retention_enabled
|
||||
When this key is enabled (true) the daemon saves a copy of the payload on
|
||||
disk from all valid records. To avoid the excessive use of disk space only
|
||||
the latest 100 records are kept. The default value for this configuration key
|
||||
is false.
|
||||
record_server_delivery_enabled
|
||||
This key controls the delivery of records to server; when enabled (default
|
||||
value), the record will be posted to the address in the configuration file.
|
||||
If this configuration key is disabled (false), records will not be spooled or
|
||||
posted to backend. This configuration key can be used in combination with
|
||||
record_retention_enabled to keep copies of telemetry records locally only.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -827,18 +833,18 @@ start/stop/restart
|
||||
------------------
|
||||
|
||||
The commands to start, stop and restart the telemetry services manage all
|
||||
required services and probes on the system. There is no need to separately
|
||||
start/stop/restart the two client daemons **telemprobd** and **telempostd**.
|
||||
The **restart** command option will call **telemctl stop** followed
|
||||
by **telemctl start** .
|
||||
required services and probes on the system. There is no need to separately
|
||||
start/stop/restart the two client daemons telemprobd and telempostd.
|
||||
The :command:`restart` command option will call :command:`telemctl stop`
|
||||
followed by :command:`telemctl start` .
|
||||
|
||||
is-active
|
||||
---------
|
||||
|
||||
The `is-active` option reports whether the two client daemons are active. This
|
||||
is useful to verify that the **opt-in** and **opt-out** options have taken
|
||||
effect, or to ensure that telemetry is functioning on the system. Note that
|
||||
both daemons are verified.
|
||||
The :command:`is-active` option reports whether the two client daemons are
|
||||
active. This is useful to verify that the :command:`opt-in` and
|
||||
:command:`opt-out` options have taken effect, or to ensure that telemetry is
|
||||
functioning on the system. Note that both daemons are verified.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -850,7 +856,6 @@ both daemons are verified.
|
||||
telempostd : active
|
||||
|
||||
|
||||
|
||||
.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/
|
||||
.. _latest version: https://github.com/clearlinux/telemetrics-client/tree/master/src
|
||||
.. _heartbeat probe: https://github.com/clearlinux/telemetrics-client/tree/master/src/probes/hello.c
|
||||
|
||||
Reference in New Issue
Block a user