Improve error and warning messages in the kickstart script. (#13825)

1 files changed, 41 insertions, 34 deletions

diff --git a/packaging/installer/kickstart.sh b/packaging/installer/kickstart.sh
index eee43f038f..e3bfac4edc 100755
--- a/packaging/installer/kickstart.sh
+++ b/packaging/installer/kickstart.sh
@@ -12,7 +12,6 @@ CLOUD_BUG_REPORT_URL="https://github.com/netdata/netdata-cloud/issues/new/choose
 DEFAULT_RELEASE_CHANNEL="nightly"
 DISCORD_INVITE="https://discord.gg/5ygS846fR6"
 DISCUSSIONS_URL="https://github.com/netdata/netdata/discussions"
-DISCUSSIONS_URL="https://github.com/netdata/netdata/discussions"
 DOCS_URL="https://learn.netdata.cloud/docs/"
 FORUM_URL="https://community.netdata.cloud/"
 KICKSTART_OPTIONS="${*}"
@@ -77,6 +76,13 @@ else
 fi
 
 # ======================================================================
+# Shared messages used in multiple places throughout the script.
+
+BADCACHE_MSG="Usually this is a result of an older copy of the file being cached somewhere upstream and can be resolved by retrying in an hour"
+BADNET_MSG="This is usually a result of a networking issue"
+ERROR_F0003="Could not find a usable HTTP client. Either curl or wget is required to proceed with installation."
+
+# ======================================================================
 # Core program logic
 
 main() {
@@ -532,7 +538,7 @@ check_for_remote_file() {
   elif command -v wget > /dev/null 2>&1; then
     wget -S --spider "${url}" 2>&1 | grep -q 'HTTP/1.1 200 OK' || return 1
   else
-    fatal "I need curl or wget to proceed, but neither of them are available on this system." F0003
+    fatal "${ERROR_F0003}" F0003
   fi
 }
 
@@ -547,7 +553,7 @@ download() {
   elif command -v wget > /dev/null 2>&1; then
     run wget -T 15 -O "${dest}" "${url}" || return 1
   else
-    fatal "I need curl or wget to proceed, but neither of them are available on this system." F0003
+    fatal "${ERROR_F0003}" F0003
   fi
 }
 
@@ -559,7 +565,7 @@ get_redirect() {
   elif command -v wget > /dev/null 2>&1; then
     run sh -c "wget --max-redirect=0 ${url} 2>&1 | grep Location | cut -d ' ' -f2  | grep -o '[^/]*$'" || return 1
   else
-    fatal "I need curl or wget to proceed, but neither of them are available on this system." F0003
+    fatal "${ERROR_F0003}" F0003
   fi
 }
 
@@ -571,7 +577,7 @@ safe_sha256sum() {
   elif command -v sha256sum > /dev/null 2>&1; then
     sha256sum "$@"
   else
-    fatal "I could not find a suitable checksum binary to use" F0004
+    fatal "Could not find a usable checksum tool. Either sha256sum, or a version of shasum supporting SHA256 checksums is required to proceed with installation." F0004
   fi
 }
 
@@ -586,7 +592,7 @@ get_system_info() {
       elif [ -s "/usr/lib/os-release" ] && [ -r "/usr/lib/os-release" ]; then
         os_release_file="/usr/lib/os-release"
       else
-        warning "Cannot find an os-release file ..."
+        warning "Cannot find usable OS release information. Native packages will not be available for this install."
       fi
 
       if [ -n "${os_release_file}" ]; then
@@ -673,7 +679,7 @@ confirm_root_support() {
     fi
 
     if [ -z "${ROOTCMD}" ]; then
-      fatal "We need root privileges to continue, but cannot find a way to gain them. Either re-run this script as root, or set \$ROOTCMD to a command that can be used to gain root privileges" F0201
+      fatal "We need root privileges to continue, but cannot find a way to gain them (we support sudo, doas, and pkexec). Either re-run this script as root, or set \$ROOTCMD to a command that can be used to gain root privileges." F0201
     fi
   fi
 }
@@ -722,11 +728,11 @@ update() {
       if [ -n "${EXIT_REASON}" ]; then
         fatal "Failed to update existing Netdata install at ${ndprefix}: ${EXIT_REASON}" "${EXIT_CODE}"
       else
-        fatal "Failed to update existing Netdata install at ${ndprefix}." U0000
+        fatal "Failed to update existing Netdata install at ${ndprefix}: Encountered an unhandled error in the updater. Further information about this error may be displayed above." U0000
       fi
     fi
   else
-    warning "Could not find a usable copy of the updater script."
+    warning "Could not find a usable copy of the updater script. We are unable to update this system in place."
     return 1
   fi
 }
@@ -857,8 +863,7 @@ handle_existing_install() {
   case "${INSTALL_TYPE}" in
     kickstart-*|legacy-*|binpkg-*|manual-static|unknown)
       if [ "${INSTALL_TYPE}" = "unknown" ]; then
-        warning "Found an existing netdata install at ${ndprefix}, but could not determine the install type."
-        warning "Usually this means you installed Netdata through your distribution’s regular package repositories or some other unsupported method."
+        warning "Found an existing netdata install at ${ndprefix}, but could not determine the install type. Usually this means you installed Netdata through your distribution’s regular package repositories or some other unsupported method."
       else
         progress "Found an existing netdata install at ${ndprefix}, with installation type '${INSTALL_TYPE}'."
       fi
@@ -948,7 +953,7 @@ handle_existing_install() {
         elif [ "${NETDATA_CLAIM_ONLY}" -eq 1 ]; then
           fatal "User asked to claim, but did not proide a claiming token." F0202
         else
-          fatal "Found an existing netdata install at ${ndprefix}, but the install type is '${INSTALL_TYPE}', which is not supported, refusing to proceed." F0103
+          fatal "Found an existing netdata install at ${ndprefix}, but the install type is '${INSTALL_TYPE}', which is not supported by this script, refusing to proceed." F0103
         fi
       fi
       ;;
@@ -992,7 +997,7 @@ EOF
 
 confirm_install_prefix() {
   if [ -n "${INSTALL_PREFIX}" ] && [ "${NETDATA_ONLY_BUILD}" -ne 1 ]; then
-    fatal "The \`--install-prefix\` and \`--install\` options are only supported together with the \`--build-only\` option." F0204
+    fatal "The --install-prefix and --install options are only supported together with the --build-only option." F0204
   fi
 
   if [ -n "${INSTALL_PREFIX}" ]; then
@@ -1074,7 +1079,7 @@ claim() {
   fi
 
   if [ ! -x "${NETDATA_CLAIM_PATH}" ]; then
-    fatal "Unable to find usable claiming script." F0106
+    fatal "Unable to find usable claiming script. Reinstalling Netdata may resolve this." F0106
   fi
 
   if ! is_netdata_running; then
@@ -1095,7 +1100,7 @@ claim() {
       warning "Unable to claim node due to issues creating the claiming directory or preparing the local claiming key. Make sure you have a working openssl command and that ${INSTALL_PREFIX}/var/lib/netdata/cloud.d exists, then try again."
       ;;
     3)
-      warning "Unable to claim node due to missing dependencies. Usually this means that the Netdata Agent was built without support for Netdata Cloud. If you built the agent from source, please install all needed dependencies for Cloud support. If you used the regular installation script and see this error, please file a bug."
+      warning "Unable to claim node due to missing dependencies. Usually this means that the Netdata Agent was built without support for Netdata Cloud. If you built the agent from source, please install all needed dependencies for Cloud support. If you used the regular installation script and see this error, please file a bug report at ${AGENT_BUG_REPORT_URL}."
       ;;
     4)
       warning "Failed to claim node due to inability to connect to ${NETDATA_CLAIM_URL}. Usually this either means that the specified claiming URL is wrong, or that you are having networking problems."
@@ -1233,7 +1238,7 @@ check_special_native_deps() {
 
         # shellcheck disable=SC2086
         if ! run ${ROOTCMD} env ${env} ${pm_cmd} install ${pkg_install_opts} epel-release; then
-          warning "Failed to install EPEL."
+          warning "Failed to install EPEL, even though it is required to install native packages on this system."
           return 1
         fi
       fi
@@ -1244,6 +1249,8 @@ check_special_native_deps() {
 }
 
 try_package_install() {
+  failed_refresh_msg="Failed to refresh repository metadata. ${BADNET_MSG} or by misconfiguration of one or more rpackage repositories in the system package manager configuration."
+
   if [ -z "${DISTRO}" ] || [ "${DISTRO}" = "unknown" ]; then
     warning "Unable to determine Linux distribution for native packages."
     return 2
@@ -1391,18 +1398,18 @@ try_package_install() {
   if ! pkg_installed "${repoconfig_name}"; then
     progress "Checking for availability of repository configuration package."
     if ! check_for_remote_file "${repoconfig_url}"; then
-      warning "No repository configuration package available for ${DISTRO} ${SYSVERSION}."
+      warning "No repository configuration package available for ${DISTRO} ${SYSVERSION}. Cannot install native packages on this system."
       return 2
     fi
 
     if ! download "${repoconfig_url}" "${tmpdir}/${repoconfig_file}"; then
-      fatal "Failed to download repository configuration package." F0209
+      fatal "Failed to download repository configuration package. ${BADNET_MSG}." F0209
     fi
 
     if [ -n "${needs_early_refresh}" ]; then
       # shellcheck disable=SC2086
       if ! run ${ROOTCMD} env ${env} ${pm_cmd} ${repo_subcmd} ${repo_update_opts}; then
-        warning "Failed to refresh repository metadata."
+        warning "${failed_refresh_msg}"
         return 2
       fi
     fi
@@ -1416,7 +1423,7 @@ try_package_install() {
     if [ -n "${repo_subcmd}" ]; then
       # shellcheck disable=SC2086
       if ! run ${ROOTCMD} env ${env} ${pm_cmd} ${repo_subcmd} ${repo_update_opts}; then
-        fatal "Failed to refresh repository metadata." F0205
+        fatal "${failed_refresh_msg}" F0205
       fi
     fi
   else
@@ -1533,16 +1540,16 @@ try_static_install() {
     netdata_agent="${NETDATA_STATIC_ARCHIVE_OLD_URL#"https://github.com/netdata/netdata/releases/download/v${INSTALL_VERSION}/"}"
     export NETDATA_STATIC_ARCHIVE_URL="${NETDATA_STATIC_ARCHIVE_OLD_URL}"
   else
-    warning "No static build available for ${SYSARCH} CPUs."
+    warning "There is no static build available for ${SYSARCH} CPUs. This usually means we simply do not currently provide static builds for ${SYSARCH} CPUs."
     return 2
   fi
 
   if ! download "${NETDATA_STATIC_ARCHIVE_URL}" "${tmpdir}/${netdata_agent}"; then
-    fatal "Unable to download static build archive for ${SYSARCH}." F0208
+    fatal "Unable to download static build archive for ${SYSARCH}. ${BADNET_MSG}." F0208
   fi
 
   if ! download "${NETDATA_STATIC_ARCHIVE_CHECKSUM_URL}" "${tmpdir}/sha256sum.txt"; then
-    fatal "Unable to fetch checksums to verify static build archive." F0206
+    fatal "Unable to fetch checksums to verify static build archive. ${BADNET_MSG}." F0206
   fi
 
   if [ "${DRY_RUN}" -eq 1 ]; then
@@ -1550,7 +1557,7 @@ try_static_install() {
   else
     if [ -z "${INSTALL_VERSION}" ]; then
       if ! grep "${netdata_agent}" "${tmpdir}/sha256sum.txt" | safe_sha256sum -c - > /dev/null 2>&1; then
-        fatal "Static binary checksum validation failed. Usually this is a result of an older copy of the file being cached somewhere upstream and can be resolved by retrying in an hour." F0207
+        fatal "Static binary checksum validation failed. ${BADCACHE_MSG}." F0207
       fi
     fi
   fi
@@ -1618,7 +1625,7 @@ install_local_build_dependencies() {
   fi
 
   if ! download "${PACKAGES_SCRIPT}" "${tmpdir}/install-required-packages.sh"; then
-    fatal "Failed to download dependency handling script for local build." F000D
+    fatal "Failed to download dependency handling script for local build. ${BADNET_MSG}." F000D
   fi
 
   if [ "${DRY_RUN}" -eq 1 ]; then
@@ -1680,7 +1687,7 @@ build_and_install() {
       if [ -n "${EXIT_REASON}" ]; then
         fatal "netdata-installer.sh failed to run: ${EXIT_REASON}" "${EXIT_CODE}"
       else
-        fatal "netdata-installer.sh failed to run correctly." I0000
+        fatal "netdata-installer.sh failed to run: Encountered an unhandled error in the installer code." I0000
       fi
       ;;
     2)
@@ -1706,14 +1713,14 @@ try_build_install() {
 
   if [ -n "${INSTALL_VERSION}" ]; then
     if ! download "${NETDATA_SOURCE_ARCHIVE_URL}" "${tmpdir}/netdata-v${INSTALL_VERSION}.tar.gz"; then
-      fatal "Failed to download source tarball for local build." F000B
+      fatal "Failed to download source tarball for local build. ${BADNET_MSG}." F000B
     fi
   elif ! download "${NETDATA_SOURCE_ARCHIVE_URL}" "${tmpdir}/netdata-latest.tar.gz"; then
-    fatal "Failed to download source tarball for local build." F000B
+    fatal "Failed to download source tarball for local build. ${BADNET_MSG}." F000B
   fi
 
   if ! download "${NETDATA_SOURCE_ARCHIVE_CHECKSUM_URL}" "${tmpdir}/sha256sum.txt"; then
-    fatal "Failed to download checksums for source tarball verification." F000C
+    fatal "Failed to download checksums for source tarball verification. ${BADNET_MSG}." F000C
   fi
 
   if [ "${DRY_RUN}" -eq 1 ]; then
@@ -1722,7 +1729,7 @@ try_build_install() {
     if [ -z "${INSTALL_VERSION}" ]; then
       # shellcheck disable=SC2086
       if ! grep netdata-latest.tar.gz "${tmpdir}/sha256sum.txt" | safe_sha256sum -c - > /dev/null 2>&1; then
-        fatal "Tarball checksum validation failed. Usually this is a result of an older copy of the file being cached somewhere upstream and can be resolved by retrying in an hour." F0005
+        fatal "Tarball checksum validation failed. ${BADCACHE_MSG}." F0005
       fi
     fi
   fi
@@ -1774,7 +1781,7 @@ prepare_offline_install_source() {
 
         progress "Fetching ${NETDATA_STATIC_ARCHIVE_URL}"
         if ! download "${NETDATA_STATIC_ARCHIVE_URL}" "netdata-${arch}-latest.gz.run"; then
-          warning "Failed to download static installer archive for ${arch}."
+          warning "Failed to download static installer archive for ${arch}. ${BADNET_MSG}."
         fi
       done
       legacy=0
@@ -1784,13 +1791,13 @@ prepare_offline_install_source() {
       legacy=1
 
       if ! download "${NETDATA_STATIC_ARCHIVE_OLD_URL}" "netdata-x86_64-latest.gz.run"; then
-        warning "Failed to download static installer archive for x86_64."
+        warning "Failed to download static installer archive for x86_64. ${BADNET_MSG}."
       fi
     fi
 
     progress "Fetching ${NETDATA_STATIC_ARCHIVE_CHECKSUM_URL}"
     if ! download "${NETDATA_STATIC_ARCHIVE_CHECKSUM_URL}" "sha256sums.txt"; then
-      fatal "Failed to download checksum file." F0506
+      fatal "Failed to download checksum file. ${BADNET_MSG}." F0506
     fi
   fi
 
@@ -1802,7 +1809,7 @@ prepare_offline_install_source() {
   if [ "${DRY_RUN}" -ne 1 ]; then
     progress "Verifying checksums."
     if ! grep -e "$(find . -name '*.gz.run')" sha256sums.txt | safe_sha256sum -c -; then
-      fatal "Checksums for offline install files are incorrect. Usually this is a result of an older copy of the file being cached somewhere upstream and can be resolved by retrying in an hour." F0507
+      fatal "Checksums for offline install files are incorrect. ${BADCACHE_MSG}." F0507
     fi
   else
     progress "Would verify SHA256 checksums of downloaded installation files."