Ensure consistency of kickstart script options that change operational mode of the script. (#13896)

* Centralize installer action types.

This ensures consistency of behavior when users specify multiple action
types.

* Update messaging around install action options.

- Document them in their own area of the help text, including mentioning
  that they are mutually exclusive and properly documenting their full
  behavior.
- Issue a warning whenever an action option gets overridden later in the
  command line.

* Update documentation about kickstart options to be consistent with help text.

Also brings the FreeBSD documentation in-line with the regular kickstart
documentation.

* Make option names more consistent.

3 files changed, 103 insertions, 79 deletions

diff --git a/packaging/installer/kickstart.sh b/packaging/installer/kickstart.sh
index 48ea0f6091..38ad91172c 100755
--- a/packaging/installer/kickstart.sh
+++ b/packaging/installer/kickstart.sh
@@ -44,7 +44,6 @@ SELECTED_INSTALL_METHOD="none"
 INSTALL_TYPE="unknown"
 INSTALL_PREFIX=""
 NETDATA_AUTO_UPDATES="default"
-NETDATA_CLAIM_ONLY=0
 NETDATA_CLAIM_URL="https://api.netdata.cloud"
 NETDATA_COMMAND="default"
 NETDATA_DISABLE_CLOUD=0
@@ -105,7 +104,7 @@ main() {
       uninstall
       cleanup
 
-      ACTION=
+      ACTION=''
       INSTALL_PREFIX="${NEW_INSTALL_PREFIX}"
       # shellcheck disable=SC2086
       main
@@ -177,12 +176,9 @@ USAGE: kickstart.sh [options]
   --auto-update                    Enable automatic updates.
   --auto-update-type               Specify a particular scheduling type for auto-updates (valid types: systemd, interval, crontab)
   --disable-telemetry              Opt-out of anonymous statistics.
-  --repositories-only              Only install appropriate repository configuration packages (only for native install).
   --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.
-  --reinstall                      Explicitly reinstall instead of updating any existing install.
-  --reinstall-even-if-unsafe       Even try to reinstall if we don't think we can do so safely (implies --reinstall).
   --disable-cloud                  Disable support for Netdata Cloud (default: detect)
   --require-cloud                  Only install if Netdata Cloud can be enabled. Overrides --disable-cloud.
   --install-prefix <path>          Specify an installation prefix for local builds (default: autodetect based on system type).
@@ -190,13 +186,19 @@ USAGE: kickstart.sh [options]
   --install-version <version>      Specify the version of Netdata to install.
   --claim-token                    Use a specified token for claiming to Netdata Cloud.
   --claim-rooms                    When claiming, add the node to the specified rooms.
-  --claim-only                     If there is an existing install, only try to claim it, not update it.
   --claim-*                        Specify other options for the claiming script.
   --no-cleanup                     Don't do any cleanup steps. This is intended to help with debugging the installer.
-  --uninstall                      Uninstall an existing installation of Netdata.
-  --reinstall-clean                Clean reinstall Netdata.
   --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.
+
+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 no 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. If there is no 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 installing the agent, prepare a directory that can be used to install on another system without needing to download anything.
 
 Additionally, this script may use the following environment variables:
@@ -924,7 +926,7 @@ handle_existing_install() {
         progress "Found an existing netdata install at ${ndprefix}, with installation type '${INSTALL_TYPE}'."
       fi
 
-      if [ -n "${NETDATA_REINSTALL}" ] || [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
+      if [ "${ACTION}" = "reinstall" ] || [ "${ACTION}" = "unsafe-reinstall" ]; then
         progress "Found an existing netdata install at ${ndprefix}, but user requested reinstall, continuing."
 
         case "${INSTALL_TYPE}" in
@@ -932,7 +934,7 @@ handle_existing_install() {
           *-build) NETDATA_ONLY_BUILD=1 ;;
           *-static) NETDATA_ONLY_STATIC=1 ;;
           *)
-            if [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
+            if [ "${ACTION}" = "unsafe-reinstall" ]; then
               warning "Reinstalling over top of a ${INSTALL_TYPE} installation may be unsafe, but the user has requested we proceed."
             elif [ "${INTERACTIVE}" -eq 0 ]; then
               fatal "User requested reinstall, but we cannot safely reinstall over top of a ${INSTALL_TYPE} installation, exiting." F0104
@@ -975,7 +977,7 @@ handle_existing_install() {
 
       ret=0
 
-      if [ "${NETDATA_CLAIM_ONLY}" -eq 0 ]; then
+      if [ "${ACTION}" != "claim" ]; then
         if ! update; then
           warning "Failed to update existing Netdata install at ${ndprefix}."
         else
@@ -990,7 +992,7 @@ handle_existing_install() {
         INSTALL_PREFIX="${ndprefix}"
         claim
         ret=$?
-      elif [ "${NETDATA_CLAIM_ONLY}" -eq 1 ]; then
+      elif [ "${ACTION}" = "claim" ]; then
         fatal "User asked to claim, but did not proide a claiming token." F0202
       else
         progress "Not attempting to claim existing install at ${ndprefix} (no claiming token provided)."
@@ -1006,8 +1008,8 @@ handle_existing_install() {
       fatal "This is an OCI container, use the regular container lifecycle management commands for your container tools instead of this script for managing it." F0203
       ;;
     *)
-      if [ -n "${NETDATA_REINSTALL}" ] || [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
-        if [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
+      if [ "${ACTION}" = "reinstall" ] || [ "${ACTION}" = "unsafe-reinstall" ]; then
+        if [ "${ACTION}" = "unsafe-reinstall" ]; then
           warning "Reinstalling over top of a ${INSTALL_TYPE} installation may be unsafe, but the user has requested we proceed."
         elif [ "${INTERACTIVE}" -eq 0 ]; then
           fatal "User requested reinstall, but we cannot safely reinstall over top of a ${INSTALL_TYPE} installation, exiting." F0104
@@ -1028,7 +1030,7 @@ handle_existing_install() {
           cleanup
           trap - EXIT
           exit $ret
-        elif [ "${NETDATA_CLAIM_ONLY}" -eq 1 ]; then
+        elif [ "${ACTION}" = "claim" ]; 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 by this script, refusing to proceed." F0103
@@ -1550,8 +1552,8 @@ try_package_install() {
     progress "Repository configuration is already present, attempting to install netdata."
   fi
 
-  if [ "${REPO_ACTION}" = "repositories-only" ]; then
-    progress "Successfully installed repository configuration package."
+  if [ "${ACTION}" = "repositories-only" ]; then
+    progress "Successfully installed repository configuraion package."
     deferred_warnings
     cleanup
     trap - EXIT
@@ -2063,6 +2065,10 @@ install_on_freebsd() {
 validate_args() {
   check_claim_opts
 
+  if [ "${ACTION}" = "repositories-only" ] && [ "${NETDATA_ONLY_NATIVE}" -eq 1 ]; then
+    fatal "Repositories can only be installed for native installs." F050D
+  fi
+
   if [ -n "${NETDATA_OFFLINE_INSTALL_SOURCE}" ]; then
     if [ "${NETDATA_ONLY_NATIVE}" -eq 1 ] || [ "${NETDATA_ONLY_BUILD}" -eq 1 ]; then
       fatal "Offline installs are only supported for static builds currently." F0502
@@ -2120,6 +2126,17 @@ validate_args() {
   fi
 }
 
+set_action() {
+  new_action="${1}"
+
+  if [ -n "${ACTION}" ]; then
+    warning "Ignoring previously specified '${ACTION}' operation in favor of '${new_action}' specified later on the command line."
+  fi
+
+  ACTION="${new_action}"
+  NETDATA_COMMAND="${new_action}"
+}
+
 parse_args() {
   while [ -n "${1}" ]; do
     case "${1}" in
@@ -2147,6 +2164,11 @@ parse_args() {
         ;;
       "--stable-channel") RELEASE_CHANNEL="stable" ;;
       "--nightly-channel") RELEASE_CHANNEL="nightly" ;;
+      "--reinstall") set_action 'reinstall' ;;
+      "--reinstall-even-if-unsafe") set_action 'unsafe-reinstall' ;;
+      "--reinstall-clean") set_action 'reinstall-clean' ;;
+      "--uninstall") set_action 'uninstall' ;;
+      "--claim-only") set_action 'claim' ;;
       "--no-updates") NETDATA_AUTO_UPDATES=0 ;;
       "--auto-update") NETDATA_AUTO_UPDATES="1" ;;
       "--auto-update-method")
@@ -2161,18 +2183,6 @@ parse_args() {
             ;;
         esac
         ;;
-      "--reinstall")
-        NETDATA_REINSTALL=1
-        NETDATA_COMMAND="reinstall"
-        ;;
-      "--reinstall-even-if-unsafe")
-        NETDATA_UNSAFE_REINSTALL=1
-        NETDATA_COMMAND="unsafe-reinstall"
-        ;;
-      "--claim-only")
-        NETDATA_CLAIM_ONLY=1
-        NETDATA_COMMAND="claim-only"
-        ;;
       "--disable-cloud")
         NETDATA_DISABLE_CLOUD=1
         NETDATA_REQUIRE_CLOUD=0
@@ -2218,19 +2228,14 @@ parse_args() {
           fatal "A distribution name and release must be specified for the --distro-override option." F050F
         fi
         ;;
-      "--uninstall")
-        ACTION="uninstall"
-        NETDATA_COMMAND="uninstall"
-        ;;
-      "--reinstall-clean")
-        ACTION="reinstall-clean"
-        NETDATA_COMMAND="reinstall-clean"
+      "--native-only")
+        NETDATA_ONLY_NATIVE=1
+        NETDATA_ONLY_STATIC=0
+        NETDATA_ONLY_BUILD=0
+        SELECTED_INSTALL_METHOD="native"
         ;;
       "--repositories-only")
-        REPO_ACTION="repositories-only"
-        NETDATA_COMMAND="repositories"
-        ;;
-      "--native-only")
+        set_action 'repositories-only'
         NETDATA_ONLY_NATIVE=1
         NETDATA_ONLY_STATIC=0
         NETDATA_ONLY_BUILD=0
@@ -2285,8 +2290,7 @@ parse_args() {
         ;;
       "--prepare-offline-install-source")
         if [ -n "${2}" ]; then
-          ACTION="prepare-offline"
-          NETDATA_COMMAND="prepare-offline"
+          set_action 'prepare-offline'
           OFFLINE_TARGET="${2}"
           shift 1
         else
diff --git a/packaging/installer/methods/freebsd.md b/packaging/installer/methods/freebsd.md
index 24f5e5db17..beb6826a19 100644
--- a/packaging/installer/methods/freebsd.md
+++ b/packaging/installer/methods/freebsd.md
@@ -76,35 +76,52 @@ If you have not passed the `--auto-update` or `-u` parameter for the installer t
 The `netdata-updater.sh` script will update your Agent.
 
 ## Optional parameters to alter your installation
-| parameters | Description |
-|:-----:|-----------|
-|`--install-prefix <path>`| Install netdata in `<path>.` Ex: `--install-prefix /opt` will put netdata in `/opt/netdata`|
-| `--dont-start-it` | Do not (re)start netdata after installation|
-| `--dont-wait` | Run installation in non-interactive mode|
-| `--auto-update` or `-u` | Install netdata-updater in cron to update netdata automatically once per day|
-| `--stable-channel` | Use packages from GitHub release pages instead of GCS (nightly updates). This results in less frequent updates|
-| `--nightly-channel` | Use most recent nightly updates instead of GitHub releases. This results in more frequent updates|
-| `--disable-go` | Disable installation of go.d.plugin|
-| `--disable-ebpf` | Disable eBPF Kernel plugin (Default: enabled)|
-| `--disable-cloud` | Disable all Netdata Cloud functionality|
-| `--require-cloud` | Fail the install if it can't build Netdata Cloud support|
-| `--enable-plugin-freeipmi` | Enable the FreeIPMI plugin. Default: enable it when libipmimonitoring is available|
-| `--disable-plugin-freeipmi` | Enable the FreeIPMI plugin|
-| `--disable-https` | Explicitly disable TLS support|
-| `--disable-dbengine` | Explicitly disable DB engine support|
-| `--enable-plugin-nfacct` | Enable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available|
-| `--disable-plugin-nfacct` | Disable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available|
-| `--enable-plugin-xenstat` | Enable the xenstat plugin. Default: enable it when libxenstat and libyajl are available|
-| `--disable-plugin-xenstat` | Disable the xenstat plugin|
-| `--disable-exporting-kinesis` | Disable AWS Kinesis exporting connector. Default: enable it when libaws_cpp_sdk_kinesis and libraries (it depends on are available)|
-| `--enable-exporting-prometheus-remote-write` | Enable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available|
-| `--disable-exporting-prometheus-remote-write` | Disable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available|
-| `--enable-exporting-mongodb` | Enable MongoDB exporting connector. Default: enable it when libmongoc is available|
-| `--disable-exporting-mongodb` | Disable MongoDB exporting connector|
-| `--enable-lto` | Enable Link-Time-Optimization. Default: enabled|
-| `--disable-lto` | Disable Link-Time-Optimization. Default: enabled|
-| `--disable-x86-sse` | Disable SSE instructions. By default SSE optimizations are enabled|
-| `--zlib-is-really-here` or `--libs-are-really-here` | If you get errors about missing zlib or libuuid but you know it is available, you might have a broken pkg-config. Use this option to proceed without checking pkg-config|
-|`--disable-telemetry` | Use this flag to opt-out from our anonymous telemetry program. (DISABLE_TELEMETRY=1)|
-
 
+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:
+    - `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.
+
+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 tyep 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](/packaging/installer/methods/offline.md) for more info.
+
+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):
+
+- `TMPDIR`: Used to specify where to put temporary files. On most systems, the default we select automatically
+  should be fine. The user running the script needs to both be able to write files to the temporary directory,
+  and run files from that location.
+- `ROOTCMD`: Used to specify a command to use to run another command with root privileges if needed. By default
+  we try to use sudo, doas, or pkexec (in that order of preference), but if you need special options for one of
+  those to work, or have a different tool to do the same thing on your system, you can specify it here.
+- `DISABLE_TELEMETRY`: If set to a value other than 0, behave as if `--disable-telemetry` was specified.
diff --git a/packaging/installer/methods/kickstart.md b/packaging/installer/methods/kickstart.md
index 679c172f73..561641ca7d 100644
--- a/packaging/installer/methods/kickstart.md
+++ b/packaging/installer/methods/kickstart.md
@@ -82,23 +82,17 @@ The `kickstart.sh` script accepts a number of optional parameters to control how
 - `--auto-update`: Enable automatic updates (this is the default).
 - `--no-updates`: Disable automatic updates.
 - `--disable-telemetry`: Disable anonymous statistics.
-- `--repositories-only`: Only install appropriate repository configuration packages (only for native install).
 - `--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.
-- `--reinstall`: If an existing install is found, reinstall instead of trying to update it in place.
-- `--reinstall-even-if-unsafe`: Even try to reinstall if we don't think we can do so safely (implies `--reinstall`).
 - `--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.
-- `--uninstall`: Uninstall an existing installation of Netdata.
-- `--reinstall-clean`: Performs an uninstall of Netdata and clean installation.
 - `--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.
-- `--prepare-offline-install-source`: Instead of installing 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.
 - `--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.
@@ -107,6 +101,15 @@ The `kickstart.sh` script accepts a number of optional parameters to control how
 - `--claim-url`: Specify a URL to use when connecting to the cloud. Defaults to `https://api.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 tyep 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](/packaging/installer/methods/offline.md) for more info.
 
 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):