From e83216f6a28869abc8979a34f79a1eb4c3d1d0d3 Mon Sep 17 00:00:00 2001 From: Tasos Katsoulas Date: Tue, 13 Jun 2023 14:25:12 +0300 Subject: Init attempt to provide an error prone FAQ for kickstart signed-off-by: Tasos Katsoulas --- packaging/installer/INSTALL-DEBUG.md | 86 ++++++++++++++++++++++++++++++++++++ packaging/installer/kickstart.sh | 7 ++- 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 packaging/installer/INSTALL-DEBUG.md diff --git a/packaging/installer/INSTALL-DEBUG.md b/packaging/installer/INSTALL-DEBUG.md new file mode 100644 index 0000000000..0ea57eef03 --- /dev/null +++ b/packaging/installer/INSTALL-DEBUG.md @@ -0,0 +1,86 @@ +# Troubleshoot problems during Agent installation and known issues + +#### Older distributions (Ubuntu 14.04, Debian 8, CentOS 6) and OpenSSL + +If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS +6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old +versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which +helps securely encrypt SSL connections. + +If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit +with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to +man-in-the-middle attacks. + +#### Known issues with the yum package manager + +In most of the RPM distros that use yum package manager, Our kickstart script is trying to set up our private repo +to ship the packages and install the native packages of Netdata. Open-source package maintainers also ship Netdata Agent +on their distro repos. To instruct the package manager to fetch packages from our repos, we rely upon a concept called +priorities. The yum package manager needs the `yum-plugin-priorities` package for the package manager to start +respecting priority rules. Consider installing this plugin, before running the kickstart script. + +```sh +sudo yum install yum-plugin-priorities +``` + +#### CentOS 6 and CentOS 8 + +To install the Agent on certain CentOS and RHEL systems, you must enable non-default repositories, such as EPEL or +PowerTools, to gather hard dependencies. See +the [CentOS 6](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/manual.md#centos--rhel-6x) and +[CentOS 8](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/manual.md#centos--rhel-8x) +sections for more information. + +#### Access to file is not permitted + +If you see an error similar to `Access to the file is not permitted: /usr/share/netdata/web//index.html` when you try to +visit the Agent dashboard at `http://NODE:19999`, you need to update Netdata's permissions to match those of your +system. + +Run `ls -la /usr/share/netdata/web/index.html` to find the file's permissions. You may need to change this path based on +the error you're seeing in your browser. In the below example, the file is owned by the user `root` and the group +`root`. + +```bash +ls -la /usr/share/netdata/web/index.html +-rw-r--r--. 1 root root 89377 May 5 06:30 /usr/share/netdata/web/index.html +``` + +These files need to have the same user and group used to install your Netdata. Suppose you installed Netdata with user +`netdata` and group `netdata`, in this scenario you will need to run the following command to fix the error: + +```bash +# chown -R netdata.netdata /usr/share/netdata/web +``` + +## Unknown install-type (F050C) + +The unknown install type is a Netdata Agent deployment we can be certain how it was installed. To that end, +we don't attempt to make any automated/scripted changes to not affect your system adversely. + +### Which type of Netdata deployments are characterized as "Unknown" + +In a nutshell, whatever package/binary/deployment was not shipped by the Netdata team. This category includes: + +- Native packages shipped by community repos. +- Custom docker files (from private forks) + +### Troubleshoot + +#### Native deployments from open-source package maintainers + +In cases like these, we can't guarantee that everything will work as expected or that the integrations with other +Netdata products (such as the Netdata Cloud) will be seamless. If you choose to receive the Netdata Agent from +your distribution official repos, you need to disable any auto-update feature of the Netdata Agent (for +instance from the cron scheduler) and rely on your package manager (manual or automated updates). + +Otherwise, you need to remove the packages installed (via your package manager) and follow +our [official instructions](https://learn.netdata.cloud/docs/install-the-netdata-agent/) to deploy the Agent. + +## Native packages fail to be installed, Netdata repo conflict + +We ship Netdata Agent via our private repo `https://repo.netdata.cloud/repos/`. In this repo, we ship two different +channels of packages ([Nightly & Stable](https://github.com/netdata/netdata/edit/master/packaging/installer/README.md#nightly-vs-stable-releases)) +which are mutually excluded. In a nutshell, when you peak the version of the Agents which serve your needs, you only +receive updates on this particular channel. In cases when you decided that a Chanel doesn't serve your needs and you want +to change, you need to manually delete the repo you track at the moment from your package manager. diff --git a/packaging/installer/kickstart.sh b/packaging/installer/kickstart.sh index 53d94fa14c..90ca1ea9ae 100755 --- a/packaging/installer/kickstart.sh +++ b/packaging/installer/kickstart.sh @@ -42,7 +42,7 @@ RELEASE_INFO_URL="https://repo.netdata.cloud/releases" REPOCONFIG_DEB_URL_PREFIX="https://repo.netdata.cloud/repos/repoconfig" REPOCONFIG_RPM_URL_PREFIX="https://repo.netdata.cloud/repos/repoconfig" TELEMETRY_URL="https://us-east1-netdata-analytics-bi.cloudfunctions.net/ingest_agent_events" - +TROUBLESHOOTING_GUIDE_URL="https://learn.netdata.cloud/docs/installing/installation-troubleshoot-actions" # ====================================================================== # Defaults for environment variables @@ -426,18 +426,23 @@ cleanup() { deferred_warnings() { if [ -n "${NETDATA_WARNINGS}" ]; then + printf >&2 "%s\n" "The following non-fatal warnings or errors were encountered:" # shellcheck disable=SC2059 printf >&2 "${NETDATA_WARNINGS}" + printf >&2 "\n" + printf >&2 "%s\n" "You can consult the guide to common installation problems in our documentation ${TROUBLESHOOTING_GUIDE_URL}" printf >&2 "\n\n" fi } fatal() { + troubleshoot_guide_url="https://learn.netdata.cloud/docs/installing/installation-troubleshoot-actions" deferred_warnings printf >&2 "%s\n\n" "${TPUT_BGRED}${TPUT_WHITE}${TPUT_BOLD} ABORTED ${TPUT_RESET} ${1}" printf >&2 "%s\n" "For community support, you can connect with us on:" support_list + printf >&2 "%s\n" "Or you can consult the guide to common installation problems in our documentation ${TROUBLESHOOTING_GUIDE_URL}" telemetry_event "INSTALL_FAILED" "${1}" "${2}" cleanup trap - EXIT -- cgit v1.2.3