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:
Kristal Dale
2019-07-19 18:40:27 -07:00
committed by michael vincerra
parent b9e5806856
commit 687aa3abcc
7 changed files with 424 additions and 402 deletions
+93 -93
View File
@@ -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
+23 -18
View File
@@ -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
+132 -131
View File
@@ -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