From 687aa3abcc419b0282df063badaa29676c030918 Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Fri, 19 Jul 2019 18:40:27 -0700 Subject: [PATCH] Initial commit for translation clean up (network and telemetry guides) (#650) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kristal Dale 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 Updates per requested changes on PR. Signed-off-by: Kristal Dale Minor revision to use :file: for directories referenced in deploy-at-scale.rst Signed-off-by: Kristal Dale Minor clean-up on network-related files. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/deploy-at-scale.rst | 186 ++++++------- .../guides/network/custom-clear-container.rst | 25 +- source/clear-linux/guides/network/dpdk.rst | 41 +-- .../guides/network/ipxe-install.rst | 40 +-- .../guides/network/network-bonding.rst | 28 +- source/clear-linux/guides/network/vnc.rst | 263 +++++++++--------- .../guides/telemetrics/telem-guide.rst | 243 ++++++++-------- 7 files changed, 424 insertions(+), 402 deletions(-) diff --git a/source/clear-linux/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst index 938c47f8..3c5270c8 100644 --- a/source/clear-linux/guides/deploy-at-scale.rst +++ b/source/clear-linux/guides/deploy-at-scale.rst @@ -3,30 +3,33 @@ Deploy at Scale ############### -Once you are comfortable with |CL-ATTR| :ref:`concepts `, your -next step as a system administrator is to understand how to deploy |CL| -at scale in your environment. - -In this document the term *endpoint* refers to a system targeted for -|CL| installation, whether that is a datacenter system or unit deployed in -field. - -.. 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 diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 88ac8e7c..d3657c10 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -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 diff --git a/source/clear-linux/guides/network/dpdk.rst b/source/clear-linux/guides/network/dpdk.rst index 51f9d202..5b1ccc65 100644 --- a/source/clear-linux/guides/network/dpdk.rst +++ b/source/clear-linux/guides/network/dpdk.rst @@ -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 `. 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: +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 diff --git a/source/clear-linux/guides/network/ipxe-install.rst b/source/clear-linux/guides/network/ipxe-install.rst index 1e12fd3c..70e6e7fa 100644 --- a/source/clear-linux/guides/network/ipxe-install.rst +++ b/source/clear-linux/guides/network/ipxe-install.rst @@ -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 diff --git a/source/clear-linux/guides/network/network-bonding.rst b/source/clear-linux/guides/network/network-bonding.rst index 1f19f0eb..41ba15b9 100644 --- a/source/clear-linux/guides/network/network-bonding.rst +++ b/source/clear-linux/guides/network/network-bonding.rst @@ -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 diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst index ac0138a0..a734a782 100644 --- a/source/clear-linux/guides/network/vnc.rst +++ b/source/clear-linux/guides/network/vnc.rst @@ -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`:** diff --git a/source/clear-linux/guides/telemetrics/telem-guide.rst b/source/clear-linux/guides/telemetrics/telem-guide.rst index 09610cd7..aa68b3aa 100644 --- a/source/clear-linux/guides/telemetrics/telem-guide.rst +++ b/source/clear-linux/guides/telemetrics/telem-guide.rst @@ -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