Adding upstream version 1.44.3.upstream/1.44.3

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 207 insertions, 62 deletions

diff --git a/packaging/installer/methods/kickstart.md b/packaging/installer/methods/kickstart.md
index bdead412e..b21f4dde9 100644
--- a/packaging/installer/methods/kickstart.md
+++ b/packaging/installer/methods/kickstart.md
@@ -17,18 +17,31 @@ import TabItem from '@theme/TabItem';
 
 ![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_by_url_pattern&options=unaligned&dimensions=kickstart&group=sum&after=-3600&label=last+hour&units=kickstart%20downloads&value_color=orange&precision=0) ![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_by_url_pattern&options=unaligned&dimensions=kickstart&group=sum&after=-86400&label=today&units=kickstart%20downloads&precision=0)
 
-This page covers detailed instructions on using and configuring the automatic one-line installation script named
-`kickstart.sh`.
+`kickstart.sh` is the recommended way of installing Netdata.
 
-The kickstart script works on all Linux distributions and macOS environments. By default, automatic nightly updates are enabled. If you are installing on macOS, make sure to check the [install documentation for macOS](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/macos.md) before continuing.
+This script works on all Linux distributions and macOS environments, by detecting the optimal method of installing Netdata directly to the operating system (it will never install a docker image of Netdata - to run Netdata in a container [check Installing with Docker](https://learn.netdata.cloud/docs/installing/docker)).
 
+If you are installing on macOS, make sure to check the [install documentation for macOS](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/macos.md) before continuing.
+
+
+## Verify script integrity
+
+To use `md5sum` to verify the integrity of the `kickstart.sh` script you will download using the one-line command above,
+run the following:
+
+```bash
+[ "<checksum-will-be-added-in-documentation-processing>" = "$(curl -Ss https://my-netdata.io/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
+```
+
+If the script is valid, this command will return `OK, VALID`.
+
+
+## Installation
 
 > :bulb: Tip
 >
 > If you are unsure whether you want nightly or stable releases, read the [installation guide](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#nightly-vs-stable-releases).  
 
-> If you want to turn off [automatic updates](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-updates), use the `--no-updates` option. You can find more installation options below.
-
 To install Netdata, run the following as your normal user:
 
 <Tabs>
@@ -49,6 +62,7 @@ To install Netdata, run the following as your normal user:
 > If you plan to also connect the node to Netdata Cloud, make sure to replace `YOUR_CLAIM_TOKEN` with the claim token of your space,
 > and `YOUR_ROOM_ID` with the ID of the room you are willing to connect the node to.
 
+
 ## What does `kickstart.sh` do?
 
 The `kickstart.sh` script does the following after being downloaded and run using `sh`:
@@ -68,48 +82,116 @@ The `kickstart.sh` script does the following after being downloaded and run usin
 
 The `kickstart.sh` script accepts a number of optional parameters to control how the installation process works:
 
-- `--non-interactive`: Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run.
-- `--interactive`: Act as if running interactively, even if automatic detection indicates a run is non-interactive.
-- `--dont-wait`: Synonym for `--non-interactive`
-- `--dry-run`: Show what the installer would do, but don’t actually do any of it.
-- `--dont-start-it`: Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
-- `--release-channel`: Specify a particular release channel to install from. Currently supported release channels are:
+### destination directory
+
+- `--install-prefix`
+  Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
+- `--old-install-prefix`
+  Specify the custom local build's installation prefix that should be removed.
+
+### interactivity
+
+The script automatically detects if it is running interactively, on a user's terminal, or headless in a CI/CD environment. These are options related to overriding this behavior.
+
+- `--non-interactive` or `--dont-wait`
+  Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run. Use this option when installing Netdata agent with a provisioning tool or in CI/CD.
+- `--interactive`
+   Act as if running interactively, even if automatic detection indicates a run is non-interactive.
+
+### release channel
+
+By default, the script installs the nightly channel of Netdata, providing you with the most recent Netdata. For production systems where stability is more important than new features, we recommend using the stable channel.
+
+- `--release-channel`
+  Specify a particular release channel to install from. Currently supported release channels are:
   - `nightly`: Installs a nightly build (this is currently the default).
   - `stable`: Installs a stable release.
   - `default`: Explicitly request whatever the current default is.
-- `--nightly-channel`: Synonym for `--release-channel nightly`.
-- `--stable-channel`: Synonym for `--release-channel stable`.
-- `--auto-update`: Enable automatic updates (this is the default).
-- `--no-updates`: Disable automatic updates.
-- `--disable-telemetry`: Disable anonymous statistics.
-- `--native-only`: Only install if native binary packages are available.
-- `--static-only`: Only install if a static build is available.
-- `--build-only`: Only install using a local build.
-- `--disable-cloud`: For local builds, don’t build any of the cloud code at all. For native packages and static builds,
-    use runtime configuration to disable cloud support.
-- `--require-cloud`: Only install if Netdata Cloud can be enabled. Overrides `--disable-cloud`.
-- `--install-prefix`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
-- `--install-version`: Specify the version of Netdata to install.
-- `--old-install-prefix`: Specify the custom local build's installation prefix that should be removed.
-- `--local-build-options`: Specify additional options to pass to the installer code when building locally. Only valid if `--build-only` is also specified.
-- `--static-install-options`: Specify additional options to pass to the static installer code. Only valid if --static-only is also specified.
-- `--claim-token`: Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node
-  after the install.
-- `--claim-rooms`: Specify a comma-separated list of tokens for each War Room this node should appear in.
-- `--claim-proxy`: Specify a proxy to use when connecting to the cloud in the form of `http://[user:pass@]host:ip` for an HTTP(S) proxy.
-  See [connecting through a proxy](https://github.com/netdata/netdata/blob/master/claim/README.md#connect-through-a-proxy) for details.
-- `--claim-url`: Specify a URL to use when connecting to the cloud. Defaults to `https://app.netdata.cloud`.
-- `--override-distro`: Override the distro detection logic and assume the system is using a specific Linux distribution and release. Takes a single argument consisting of the values of the `ID`, `VERSION_ID`, and `VERSION_CODENAME` fields from `/etc/os-release` for the desired distribution.
-
-The following options are mutually exclusive and specifiy special operations other than trying to install Netdata normally or update an existing install:
-
-- `--reinstall`: If there is an existing install, reinstall it instead of trying to update it. If there is not an existing install, install netdata normally.
-- `--reinstall-even-if-unsafe`: If there is an existing install, reinstall it instead of trying to update it, even if doing so is known to potentially break things (for example, if we cannot detect what type of installation it is). If there is not an existing install, install Netdata normally.
-- `--reinstall-clean`: If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
-- `--uninstall`: Uninstall an existing installation of Netdata. Fails if there is no existing install.
-- `--claim-only`: If there is an existing install, only try to claim it without attempting to update it. If there is no existing install, install and claim Netdata normally.
-- `--repositories-only`: Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
-- `--prepare-offline-install-source`: Instead of insallling the agent, prepare a directory that can be used to install on another system without needing to download anything. See our [offline installation documentation](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/offline.md) for more info.
+- `--nightly-channel`
+  Synonym for `--release-channel nightly`.
+- `--stable-channel`
+  Synonym for `--release-channel stable`.
+- `--install-version`
+  Specify the exact version of Netdata to install.
+
+### install type
+
+By default the script will prefer native builds when they are available, and then static builds. It will fallback to build from source when all others are not available.
+
+- `--native-only`
+   Only install if native binary packages are available. It fails otherwise.
+- `--static-only`
+  Only install if a static build is available. It fails otherwise.
+   When installing a static build, the parameter `--static-install-options` can provide additional options to pass to the static installer code.
+- `--build-only`
+  Only install using a local build. It fails otherwise.
+  When it builds from source, the parameter `--local-build-options` can be used to give additional build options.
+
+### automatic updates
+
+By default the script installs a cron job to automatically update Netdata to the latest version of the release channel used.
+
+- `--auto-update`
+  Enable automatic updates (this is the default).
+- `--no-updates`
+  Disable automatic updates (not recommended).
+
+### Netdata Cloud related options
+
+By default, the kickstart script will provide a Netdata agent installation that can potentially communicate with Netdata Cloud, if of course the Netdata agent is further configured to do so.
+
+- `--claim-token`
+  Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node after the install. This will enable, connect and claim the Netdata agent, to Netdata Cloud.
+- `--claim-url`
+  Specify a URL to use when connecting to the cloud. Defaults to `https://app.netdata.cloud`. Use this option to change the Netdata Cloud URL to point to your Netdata Cloud installation.
+- `--claim-rooms`
+  Specify a comma-separated list of tokens for each War Room this node should appear in.
+- `--claim-proxy`
+  Specify a proxy to use when connecting to the cloud in the form of `http://[user:pass@]host:ip` for an HTTP(S) proxy. See [connecting through a proxy](https://github.com/netdata/netdata/blob/master/claim/README.md#connect-through-a-proxy) for details.
+- `--claim-only`
+  If there is an existing install, only try to claim it without attempting to update it. If there is no existing install, install and claim Netdata normally.
+- `--require-cloud`
+  Only install if Netdata Cloud can be enabled.
+- `--disable-cloud`
+  For local builds, don’t build any of the Netdata Cloud code at all. For native packages and static builds, use runtime configuration to disable Netdata Cloud support.
+
+### anonymous telemetry
+
+By default, the agent is sending anonymous telemetry data to help us take identify the most common operating systems and the configurations Netdata agents run. We use this information to prioritize our efforts towards what is most commonly used by our community.
+
+- `--disable-telemetry`
+  Disable anonymous statistics.
+
+### reinstalling
+
+- `--reinstall`
+  If there is an existing install, reinstall it instead of trying to update it. If there is not an existing install, install netdata normally.
+- `--reinstall-even-if-unsafe`
+  If there is an existing install, reinstall it instead of trying to update it, even if doing so is known to potentially break things (for example, if we cannot detect what type of installation it is). If there is not an existing install, install Netdata normally.
+- `--reinstall-clean`
+  If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
+
+### uninstall
+
+- `--uninstall`
+  Uninstall an existing installation of Netdata. Fails if there is no existing install.
+
+### other options
+- `--dry-run`
+  Show what the installer would do, but don’t actually do any of it.
+- `--dont-start-it`
+  Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
+- `--override-distro`
+  Override the distro detection logic and assume the system is using a specific Linux distribution and release. Takes a single argument consisting of the values of the `ID`, `VERSION_ID`, and `VERSION_CODENAME` fields from `/etc/os-release` for the desired distribution.
+
+The following options are mutually exclusive and specify special operations other than trying to install Netdata normally or update an existing install:
+
+- `--repositories-only`
+  Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
+- `--prepare-offline-install-source`
+  Instead of insallling the agent, prepare a directory that can be used to install on another system without needing to download anything. See our [offline installation documentation](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/offline.md) for more info.
+
+### environment variables
 
 Additionally, the following environment variables may be used to further customize how the script runs (most users
 should not need to use special values for any of these):
@@ -123,7 +205,7 @@ should not need to use special values for any of these):
 - `DISABLE_TELEMETRY`: If set to a value other than 0, behave as if `--disable-telemetry` was specified.
 
 
-### Native packages
+## Native packages
 
 We publish official DEB/RPM packages for a number of common Linux distributions as part of our releases and nightly
 builds. These packages are available for 64-bit x86 systems. Depending on the distribution and release they may
@@ -133,7 +215,7 @@ default installation method. This allows you to handle Netdata updates as part o
 If you want to enforce the usage of native packages and have the installer return a failure if they are not available,
 you can do so by adding `--native-only` to the options you pass to the installer.
 
-### Static builds
+## Static builds
 
 We publish pre-built static builds of Netdata for Linux systems. Currently, these are published for 64-bit x86, ARMv7,
 AArch64, and POWER8+ hardware. These static builds are able to operate in a mostly self-contained manner and only
@@ -144,7 +226,7 @@ will be used by default for installation.
 If you want to enforce the usage of a static build and have the installer return a failure if one is not available,
 you can do so by adding `--static-only` to the options you pass to the installer.
 
-### Local builds
+## Local builds
 
 For systems which do not have available native packages or static builds, we support building Netdata locally on
 the system it will be installed on. When using this approach, the installer will attempt to install any required
@@ -153,14 +235,3 @@ dependencies for building Netdata, though this may not always work correctly.
 If you want to enforce the usage of a local build (perhaps because you require a custom installation prefix,
 which is not supported with native packages or static builds), you can do so by adding `--build-only` to the
 options you pass to the installer.
-
-## Verify script integrity
-
-To use `md5sum` to verify the integrity of the `kickstart.sh` script you will download using the one-line command above,
-run the following:
-
-```bash
-[ "<checksum-will-be-added-in-documentation-processing>" = "$(curl -Ss https://my-netdata.io/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
-```
-
-If the script is valid, this command will return `OK, VALID`.
diff --git a/packaging/installer/methods/manual.md b/packaging/installer/methods/manual.md
index 789f8aaab..269b67c1a 100644
--- a/packaging/installer/methods/manual.md
+++ b/packaging/installer/methods/manual.md
@@ -22,6 +22,9 @@ To install the latest git version of Netdata, please follow these 2 steps:
 
 ## Prepare your system
 
+Before you begin, make sure that your repo and the repo's submodules are clean from any previous builds and up to date.
+Otherwise, [perform a cleanup](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/manual.md#perform-a-cleanup-in-your-netdata-repo)
+
 Use our automatic requirements installer (_no need to be `root`_), which attempts to find the packages that
 should be installed on your system to build and run Netdata. It supports a large variety of major Linux distributions
 and other operating systems and is regularly tested. You can find this tool [here](https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh) or run it directly with `bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh)`. Otherwise read on for how to get requires packages manually:
@@ -226,3 +229,20 @@ Our current build process unfortunately has some issues when using certain confi
 If the installation fails with errors like `/bin/ld: externaldeps/libwebsockets/libwebsockets.a(context.c.o): relocation R_X86_64_32 against '.rodata.str1.1' can not be used when making a PIE object; recompile with -fPIC`, and you are trying to build with `clang` on Linux, you will need to build Netdata using GCC to get a fully functional install. 
 
 In most cases, you can do this by running `CC=gcc ./netdata-installer.sh`.
+
+
+### Perform a cleanup in your netdata repo
+
+The Netdata repo consist of the main git tree and it's submodules. Either working on a fork or on the main repo you need to make sure that there
+are no "leftover" artifacts from previous builds and that your submodules are up to date to the **corresponding checkouts**.
+
+> #### Important: Make sure that you have commited any work in progress, before you proceed the with the clean up instruction below
+
+
+```sh
+git clean -dfx && git submodule foreach 'git clean -dfx' && git submodule update --recursive --init
+```
+
+
+> Note: In previous builds, you may have created artifacts belonging to an another user (e.g root), so you may need to run
+> each of the _git clean_ commands as sudoer.
diff --git a/packaging/installer/methods/packages.md b/packaging/installer/methods/packages.md
index 914920444..d49e21394 100644
--- a/packaging/installer/methods/packages.md
+++ b/packaging/installer/methods/packages.md
@@ -23,10 +23,10 @@ and fail if it cannot do so.
 
 
 > ### Note
-> 
+>
 > In July 2022, we switched hosting of our native packages from Package Cloud to self-hosted repositories.
-> We still maintain the Package cloud repositories, but they are not guaranteed to work and may be removed 
-> without prior warning. 
+> We still maintain the Package cloud repositories, but they are not guaranteed to work and may be removed
+> without prior warning.
 >
 > When selecting a repository configuration package, note that the version 2 packages provide configuration for
 > our self-hosted repositories, and then version 1 packages provide configuration for Package Cloud.
@@ -44,7 +44,9 @@ repositories at that top level:
 
 Within each top level group of repositories, there are directories for each supported group of distributions:
 
-- `el`: Is for Red Hat Enterprise Linux and binary compatible distros, such as CentOS, Alma Linux, and Rocky Linux.
+- `amazonlinux`: Is for Amazon Linux and binary compatible distros.
+- `el`: Is for Red Hat Enterprise Linux and binary compatible distros that are not covered by other repos, such
+  as CentOS, Alma Linux, and Rocky Linux.
 - `fedora`: Is for Fedora and binary compatible distros.
 - `ol`: Is for Oracle Linux and binary compatible distros.
 - `opensuse`: Is for openSUSE and binary compatible distros.
@@ -64,6 +66,13 @@ appropriate repository configuration package from https://repo.netdata.cloud/rep
 directly on the target system using the system package manager. This will ensure any packages needed to use the
 repository are also installed, and will help enable a seamless transition if we ever need to change our infrastructure.
 
+> ### Note
+>
+> On RHEL and other systems that use the `el` repostiroies, some of the dependencies for Netdata can only be found
+> in the EPEL repository, which is not enabled or installed by default on most of these systems. This additional
+> repository _should_ be pulled in automatically by our repository config packages, but if it is not you may need
+> to manually install `epel-release` to be able to successfully install the Netdata packages.
+
 ## Manual setup of DEB packages.
 
 Netdata’s official DEB repositories are hosted at https://repo.netdata.cloud/repos. We provide four groups of
@@ -99,3 +108,44 @@ If you are explicitly configuring a system to use our repositories, the recommen
 appropriate repository configuration package from https://repo.netdata.cloud/repos/repoconfig and install it
 directly on the target system using the system package manager. This will ensure any packages needed to use the
 repository are also installed, and will help enable a seamless transition if we ever need to change our infrastructure.
+
+## Local mirrors of the official Netdata repositories
+
+Local mirrors of our official repositories can be created in one of two ways:
+
+1. Using the standard tooling for mirroring the type of repository you want a local mirror of, such as Aptly for
+   APT repositories, or reposync for RPM repositories. For this approach, please consult the documentation for
+   the specific tool you are using for info on how to mirror the repositories.
+2. Using a regular website mirroring tool, such as GNU wget’s `--mirror` option. For this approach, simply point
+   your mirroring tool at `https://repo.netdata.cloud/repos/`, and everything should just work.
+
+We do not provide official support for mirroring our repositories,
+but we do have some tips for anyone looking to do so:
+
+- Our `robots.txt` file explicitly disallows indexing, so if you’re using a regular website mirroring tool,
+  you wil need to tell it to ignore `robots.txt` (for example, if using GNU wget, add `-e robots=off` to the
+  options you pass) to ensure that it actually retrieves everything.
+- Excluding special cases of caching proxies (such as apt-cacher-ng), our repository configuration packages _DO NOT_
+  work with custom local mirrors. Thus, you will need to manually configure your systems to use your local mirror.
+- Packages are published as they are built, with 64-bit x86 packages being built first, followed by 32-bit x86,
+  and then non-x86 packages in alphabetical order of the CPU architecture. Because of the number of different
+  packages being built, this means that packages for a given nightly build or stable release are typically published
+  over the course of a few hours, usually starting about 15-20 minutes after the build or release is started.
+- Repository metadata is updated every hour on the hour, and the process may take anywhere from a few seconds to
+  more than 20 minutes. Because of this, it makes little sense to sync your mirror more frequently than once an hour,
+  and it’s generally preferred to start syncing at least 30 minutes into the hour.
+- A full mirror of all of our repositories currently requires up to 100 GB of storage space, though the exact
+  amount of space needed fluctuates over time. Because of this, users seeking to mirror our repositories are
+  encouraged to mirror only those repositories they actually need instead of mirroring everything.
+- If syncing daily (or less frequently), some time between 05:00 and 08:00 UTC each day is usually the saftest
+  time to do so, as publishing nightly packages will almost always be done by this point, and publishing of stable
+  releases typically happens after that time window.
+- If you intend to use our existing GPG signatures on the repository metadata and packages, you probably also want
+  a local copy of our public GPG key, which can be fetched from `https://repo.netdata.cloud/netdatabot.gpg.key`.
+
+## Public mirrors of the official Netdata repositories
+
+There are no official public mirrors of our repositories.
+
+If you wish to provide a public mirror of our official repositories, you are free to do so, but we kindly ask that
+you make it clear to your users that your mirror is not an official mirror of our repositories.
diff --git a/packaging/installer/methods/source.md b/packaging/installer/methods/source.md
index 7b6b88d4b..8f34218a2 100644
--- a/packaging/installer/methods/source.md
+++ b/packaging/installer/methods/source.md
@@ -50,7 +50,11 @@ which the the build system will link statically into Netdata. These
 libraries and their header files must be copied into specific locations
 in the source tree to be used.
 
+Before you begin, make sure that your repo and the repo's submodules are clean from any previous builds and up to date.
+Otherwise, [perform a cleanup](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/manual.md#perform-a-cleanup-in-your-netdata-repo)
+
 ### Netdata cloud
+
 #### JSON-C
 
 Netdata requires the use of JSON-C for JSON parsing when using Netdata