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.
Austin S. Hemmelgarn committed
Feb 28, 2023 at 12:52 UTC
6bd0c6e3c3b7df5b20d8ce5c220ed1a122c4ce6b
3 files changed
+103
-79
packaging/installer/kickstart.sh
+46
-42
@@ -44,7 +44,6 @@ SELECTED_INSTALL_METHOD="none"
44
INSTALL_TYPE="unknown"
45
INSTALL_PREFIX=""
46
NETDATA_AUTO_UPDATES="default"
47
-NETDATA_CLAIM_ONLY=0
47
NETDATA_CLAIM_URL="https://api.netdata.cloud"
48
NETDATA_COMMAND="default"
49
NETDATA_DISABLE_CLOUD=0
@@ -105,7 +104,7 @@ main() {
104
uninstall
105
cleanup
106
108
- ACTION=
107
+ ACTION=''
108
INSTALL_PREFIX="${NEW_INSTALL_PREFIX}"
109
# shellcheck disable=SC2086
110
main
@@ -177,12 +176,9 @@ USAGE: kickstart.sh [options]
176
--auto-update Enable automatic updates.
177
--auto-update-type Specify a particular scheduling type for auto-updates (valid types: systemd, interval, crontab)
178
--disable-telemetry Opt-out of anonymous statistics.
180
- --repositories-only Only install appropriate repository configuration packages (only for native install).
179
--native-only Only install if native binary packages are available.
180
--static-only Only install if a static build is available.
181
--build-only Only install using a local build.
184
- --reinstall Explicitly reinstall instead of updating any existing install.
185
- --reinstall-even-if-unsafe Even try to reinstall if we don't think we can do so safely (implies --reinstall).
182
--disable-cloud Disable support for Netdata Cloud (default: detect)
183
--require-cloud Only install if Netdata Cloud can be enabled. Overrides --disable-cloud.
184
--install-prefix <path> Specify an installation prefix for local builds (default: autodetect based on system type).
@@ -190,13 +186,19 @@ USAGE: kickstart.sh [options]
186
--install-version <version> Specify the version of Netdata to install.
187
--claim-token Use a specified token for claiming to Netdata Cloud.
188
--claim-rooms When claiming, add the node to the specified rooms.
193
- --claim-only If there is an existing install, only try to claim it, not update it.
189
--claim-* Specify other options for the claiming script.
190
--no-cleanup Don't do any cleanup steps. This is intended to help with debugging the installer.
196
- --uninstall Uninstall an existing installation of Netdata.
197
- --reinstall-clean Clean reinstall Netdata.
191
--local-build-options Specify additional options to pass to the installer code when building locally. Only valid if --build-only is also specified.
192
--static-install-options Specify additional options to pass to the static installer code. Only valid if --static-only is also specified.
193
+
194
+The following options are mutually exclusive and specifiy special operations other than trying to install Netdata normally or update an existing install:
195
+
196
+ --reinstall If there is an existing install, reinstall it instead of trying to update it. If there is no existing install, install netdata normally.
197
+ --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.
198
+ --reinstall-clean If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
199
+ --uninstall Uninstall an existing installation of Netdata. Fails if there is no existing install.
200
+ --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.
201
+ --repositories-only Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
202
--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.
203
204
Additionally, this script may use the following environment variables:
@@ -924,7 +926,7 @@ handle_existing_install() {
926
progress "Found an existing netdata install at ${ndprefix}, with installation type '${INSTALL_TYPE}'."
927
fi
928
927
- if [ -n "${NETDATA_REINSTALL}" ] || [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
929
+ if [ "${ACTION}" = "reinstall" ] || [ "${ACTION}" = "unsafe-reinstall" ]; then
930
progress "Found an existing netdata install at ${ndprefix}, but user requested reinstall, continuing."
931
932
case "${INSTALL_TYPE}" in
@@ -932,7 +934,7 @@ handle_existing_install() {
934
*-build) NETDATA_ONLY_BUILD=1 ;;
935
*-static) NETDATA_ONLY_STATIC=1 ;;
936
*)
935
- if [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
937
+ if [ "${ACTION}" = "unsafe-reinstall" ]; then
938
warning "Reinstalling over top of a ${INSTALL_TYPE} installation may be unsafe, but the user has requested we proceed."
939
elif [ "${INTERACTIVE}" -eq 0 ]; then
940
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() {
977
978
ret=0
979
978
- if [ "${NETDATA_CLAIM_ONLY}" -eq 0 ]; then
980
+ if [ "${ACTION}" != "claim" ]; then
981
if ! update; then
982
warning "Failed to update existing Netdata install at ${ndprefix}."
983
else
@@ -990,7 +992,7 @@ handle_existing_install() {
992
INSTALL_PREFIX="${ndprefix}"
993
claim
994
ret=$?
993
- elif [ "${NETDATA_CLAIM_ONLY}" -eq 1 ]; then
995
+ elif [ "${ACTION}" = "claim" ]; then
996
fatal "User asked to claim, but did not proide a claiming token." F0202
997
else
998
progress "Not attempting to claim existing install at ${ndprefix} (no claiming token provided)."
@@ -1006,8 +1008,8 @@ handle_existing_install() {
1008
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
1009
;;
1010
*)
1009
- if [ -n "${NETDATA_REINSTALL}" ] || [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
1010
- if [ -n "${NETDATA_UNSAFE_REINSTALL}" ]; then
1011
+ if [ "${ACTION}" = "reinstall" ] || [ "${ACTION}" = "unsafe-reinstall" ]; then
1012
+ if [ "${ACTION}" = "unsafe-reinstall" ]; then
1013
warning "Reinstalling over top of a ${INSTALL_TYPE} installation may be unsafe, but the user has requested we proceed."
1014
elif [ "${INTERACTIVE}" -eq 0 ]; then
1015
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() {
1030
cleanup
1031
trap - EXIT
1032
exit $ret
1031
- elif [ "${NETDATA_CLAIM_ONLY}" -eq 1 ]; then
1033
+ elif [ "${ACTION}" = "claim" ]; then
1034
fatal "User asked to claim, but did not proide a claiming token." F0202
1035
else
1036
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() {
1552
progress "Repository configuration is already present, attempting to install netdata."
1553
fi
1554
1553
- if [ "${REPO_ACTION}" = "repositories-only" ]; then
1554
- progress "Successfully installed repository configuration package."
1555
+ if [ "${ACTION}" = "repositories-only" ]; then
1556
+ progress "Successfully installed repository configuraion package."
1557
deferred_warnings
1558
cleanup
1559
trap - EXIT
@@ -2063,6 +2065,10 @@ install_on_freebsd() {
2065
validate_args() {
2066
check_claim_opts
2067
2068
+ if [ "${ACTION}" = "repositories-only" ] && [ "${NETDATA_ONLY_NATIVE}" -eq 1 ]; then
2069
+ fatal "Repositories can only be installed for native installs." F050D
2070
+ fi
2071
+
2072
if [ -n "${NETDATA_OFFLINE_INSTALL_SOURCE}" ]; then
2073
if [ "${NETDATA_ONLY_NATIVE}" -eq 1 ] || [ "${NETDATA_ONLY_BUILD}" -eq 1 ]; then
2074
fatal "Offline installs are only supported for static builds currently." F0502
@@ -2120,6 +2126,17 @@ validate_args() {
2126
fi
2127
}
2128
2129
+set_action() {
2130
+ new_action="${1}"
2131
+
2132
+ if [ -n "${ACTION}" ]; then
2133
+ warning "Ignoring previously specified '${ACTION}' operation in favor of '${new_action}' specified later on the command line."
2134
+ fi
2135
+
2136
+ ACTION="${new_action}"
2137
+ NETDATA_COMMAND="${new_action}"
2138
+}
2139
+
2140
parse_args() {
2141
while [ -n "${1}" ]; do
2142
case "${1}" in
@@ -2147,6 +2164,11 @@ parse_args() {
2164
;;
2165
"--stable-channel") RELEASE_CHANNEL="stable" ;;
2166
"--nightly-channel") RELEASE_CHANNEL="nightly" ;;
2167
+ "--reinstall") set_action 'reinstall' ;;
2168
+ "--reinstall-even-if-unsafe") set_action 'unsafe-reinstall' ;;
2169
+ "--reinstall-clean") set_action 'reinstall-clean' ;;
2170
+ "--uninstall") set_action 'uninstall' ;;
2171
+ "--claim-only") set_action 'claim' ;;
2172
"--no-updates") NETDATA_AUTO_UPDATES=0 ;;
2173
"--auto-update") NETDATA_AUTO_UPDATES="1" ;;
2174
"--auto-update-method")
@@ -2161,18 +2183,6 @@ parse_args() {
2183
;;
2184
esac
2185
;;
2164
- "--reinstall")
2165
- NETDATA_REINSTALL=1
2166
- NETDATA_COMMAND="reinstall"
2167
- ;;
2168
- "--reinstall-even-if-unsafe")
2169
- NETDATA_UNSAFE_REINSTALL=1
2170
- NETDATA_COMMAND="unsafe-reinstall"
2171
- ;;
2172
- "--claim-only")
2173
- NETDATA_CLAIM_ONLY=1
2174
- NETDATA_COMMAND="claim-only"
2175
- ;;
2186
"--disable-cloud")
2187
NETDATA_DISABLE_CLOUD=1
2188
NETDATA_REQUIRE_CLOUD=0
@@ -2218,19 +2228,14 @@ parse_args() {
2228
fatal "A distribution name and release must be specified for the --distro-override option." F050F
2229
fi
2230
;;
2221
- "--uninstall")
2222
- ACTION="uninstall"
2223
- NETDATA_COMMAND="uninstall"
2224
- ;;
2225
- "--reinstall-clean")
2226
- ACTION="reinstall-clean"
2227
- NETDATA_COMMAND="reinstall-clean"
2231
+ "--native-only")
2232
+ NETDATA_ONLY_NATIVE=1
2233
+ NETDATA_ONLY_STATIC=0
2234
+ NETDATA_ONLY_BUILD=0
2235
+ SELECTED_INSTALL_METHOD="native"
2236
;;
2237
"--repositories-only")
2230
- REPO_ACTION="repositories-only"
2231
- NETDATA_COMMAND="repositories"
2232
- ;;
2233
- "--native-only")
2238
+ set_action 'repositories-only'
2239
NETDATA_ONLY_NATIVE=1
2240
NETDATA_ONLY_STATIC=0
2241
NETDATA_ONLY_BUILD=0
@@ -2285,8 +2290,7 @@ parse_args() {
2290
;;
2291
"--prepare-offline-install-source")
2292
if [ -n "${2}" ]; then
2288
- ACTION="prepare-offline"
2289
- NETDATA_COMMAND="prepare-offline"
2293
+ set_action 'prepare-offline'
2294
OFFLINE_TARGET="${2}"
2295
shift 1
2296
else
packaging/installer/methods/freebsd.md
+48
-31
@@ -76,35 +76,52 @@ If you have not passed the `--auto-update` or `-u` parameter for the installer t
76
The `netdata-updater.sh` script will update your Agent.
77
78
## Optional parameters to alter your installation
79
-| parameters | Description |
80
-|:-----:|-----------|
81
-|`--install-prefix <path>`| Install netdata in `<path>.` Ex: `--install-prefix /opt` will put netdata in `/opt/netdata`|
82
-| `--dont-start-it` | Do not (re)start netdata after installation|
83
-| `--dont-wait` | Run installation in non-interactive mode|
84
-| `--auto-update` or `-u` | Install netdata-updater in cron to update netdata automatically once per day|
85
-| `--stable-channel` | Use packages from GitHub release pages instead of GCS (nightly updates). This results in less frequent updates|
86
-| `--nightly-channel` | Use most recent nightly updates instead of GitHub releases. This results in more frequent updates|
87
-| `--disable-go` | Disable installation of go.d.plugin|
88
-| `--disable-ebpf` | Disable eBPF Kernel plugin (Default: enabled)|
89
-| `--disable-cloud` | Disable all Netdata Cloud functionality|
90
-| `--require-cloud` | Fail the install if it can't build Netdata Cloud support|
91
-| `--enable-plugin-freeipmi` | Enable the FreeIPMI plugin. Default: enable it when libipmimonitoring is available|
92
-| `--disable-plugin-freeipmi` | Enable the FreeIPMI plugin|
93
-| `--disable-https` | Explicitly disable TLS support|
94
-| `--disable-dbengine` | Explicitly disable DB engine support|
95
-| `--enable-plugin-nfacct` | Enable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available|
96
-| `--disable-plugin-nfacct` | Disable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available|
97
-| `--enable-plugin-xenstat` | Enable the xenstat plugin. Default: enable it when libxenstat and libyajl are available|
98
-| `--disable-plugin-xenstat` | Disable the xenstat plugin|
99
-| `--disable-exporting-kinesis` | Disable AWS Kinesis exporting connector. Default: enable it when libaws_cpp_sdk_kinesis and libraries (it depends on are available)|
100
-| `--enable-exporting-prometheus-remote-write` | Enable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available|
101
-| `--disable-exporting-prometheus-remote-write` | Disable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available|
102
-| `--enable-exporting-mongodb` | Enable MongoDB exporting connector. Default: enable it when libmongoc is available|
103
-| `--disable-exporting-mongodb` | Disable MongoDB exporting connector|
104
-| `--enable-lto` | Enable Link-Time-Optimization. Default: enabled|
105
-| `--disable-lto` | Disable Link-Time-Optimization. Default: enabled|
106
-| `--disable-x86-sse` | Disable SSE instructions. By default SSE optimizations are enabled|
107
-| `--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|
108
-|`--disable-telemetry` | Use this flag to opt-out from our anonymous telemetry program. (DISABLE_TELEMETRY=1)|
109
-
79
80
+The `kickstart.sh` script accepts a number of optional parameters to control how the installation process works:
81
+
82
+- `--non-interactive`: Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run.
83
+- `--interactive`: Act as if running interactively, even if automatic detection indicates a run is non-interactive.
84
+- `--dont-wait`: Synonym for `--non-interactive`
85
+- `--dry-run`: Show what the installer would do, but don’t actually do any of it.
86
+- `--dont-start-it`: Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
87
+- `--release-channel`: Specify a particular release channel to install from. Currently supported release channels are:
88
+ - `nightly`: Installs a nightly build (this is currently the default).
89
+ - `stable`: Installs a stable release.
90
+ - `default`: Explicitly request whatever the current default is.
91
+- `--nightly-channel`: Synonym for `--release-channel nightly`.
92
+- `--stable-channel`: Synonym for `--release-channel stable`.
93
+- `--auto-update`: Enable automatic updates (this is the default).
94
+- `--no-updates`: Disable automatic updates.
95
+- `--disable-telemetry`: Disable anonymous statistics.
96
+- `--native-only`: Only install if native binary packages are available.
97
+- `--static-only`: Only install if a static build is available.
98
+- `--build-only`: Only install using a local build.
99
+- `--disable-cloud`: For local builds, don’t build any of the cloud code at all. For native packages and static builds,
100
+ use runtime configuration to disable cloud support.
101
+- `--require-cloud`: Only install if Netdata Cloud can be enabled. Overrides `--disable-cloud`.
102
+- `--install-prefix`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
103
+- `--install-version`: Specify the version of Netdata to install.
104
+- `--old-install-prefix`: Specify the custom local build's installation prefix that should be removed.
105
+- `--local-build-options`: Specify additional options to pass to the installer code when building locally. Only valid if `--build-only` is also specified.
106
+- `--static-install-options`: Specify additional options to pass to the static installer code. Only valid if --static-only is also specified.
107
+
108
+The following options are mutually exclusive and specifiy special operations other than trying to install Netdata normally or update an existing install:
109
+
110
+- `--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.
111
+- `--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.
112
+- `--reinstall-clean`: If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
113
+- `--uninstall`: Uninstall an existing installation of Netdata. Fails if there is no existing install.
114
+- `--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.
115
+- `--repositories-only`: Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
116
+- `--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.
117
+
118
+Additionally, the following environment variables may be used to further customize how the script runs (most users
119
+should not need to use special values for any of these):
120
+
121
+- `TMPDIR`: Used to specify where to put temporary files. On most systems, the default we select automatically
122
+ should be fine. The user running the script needs to both be able to write files to the temporary directory,
123
+ and run files from that location.
124
+- `ROOTCMD`: Used to specify a command to use to run another command with root privileges if needed. By default
125
+ we try to use sudo, doas, or pkexec (in that order of preference), but if you need special options for one of
126
+ those to work, or have a different tool to do the same thing on your system, you can specify it here.
127
+- `DISABLE_TELEMETRY`: If set to a value other than 0, behave as if `--disable-telemetry` was specified.
packaging/installer/methods/kickstart.md
+9
-6
@@ -82,23 +82,17 @@ The `kickstart.sh` script accepts a number of optional parameters to control how
82
- `--auto-update`: Enable automatic updates (this is the default).
83
- `--no-updates`: Disable automatic updates.
84
- `--disable-telemetry`: Disable anonymous statistics.
85
-- `--repositories-only`: Only install appropriate repository configuration packages (only for native install).
85
- `--native-only`: Only install if native binary packages are available.
86
- `--static-only`: Only install if a static build is available.
87
- `--build-only`: Only install using a local build.
89
-- `--reinstall`: If an existing install is found, reinstall instead of trying to update it in place.
90
-- `--reinstall-even-if-unsafe`: Even try to reinstall if we don't think we can do so safely (implies `--reinstall`).
88
- `--disable-cloud`: For local builds, don’t build any of the cloud code at all. For native packages and static builds,
89
use runtime configuration to disable cloud support.
90
- `--require-cloud`: Only install if Netdata Cloud can be enabled. Overrides `--disable-cloud`.
91
- `--install-prefix`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
92
- `--install-version`: Specify the version of Netdata to install.
93
- `--old-install-prefix`: Specify the custom local build's installation prefix that should be removed.
97
-- `--uninstall`: Uninstall an existing installation of Netdata.
98
-- `--reinstall-clean`: Performs an uninstall of Netdata and clean installation.
94
- `--local-build-options`: Specify additional options to pass to the installer code when building locally. Only valid if `--build-only` is also specified.
95
- `--static-install-options`: Specify additional options to pass to the static installer code. Only valid if --static-only is also specified.
101
-- `--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.
96
- `--claim-token`: Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node
97
after the install.
98
- `--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
101
- `--claim-url`: Specify a URL to use when connecting to the cloud. Defaults to `https://api.netdata.cloud`.
102
- `--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.
103
104
+The following options are mutually exclusive and specifiy special operations other than trying to install Netdata normally or update an existing install:
105
+
106
+- `--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.
107
+- `--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.
108
+- `--reinstall-clean`: If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
109
+- `--uninstall`: Uninstall an existing installation of Netdata. Fails if there is no existing install.
110
+- `--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.
111
+- `--repositories-only`: Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
112
+- `--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.
113
114
Additionally, the following environment variables may be used to further customize how the script runs (most users
115
should not need to use special values for any of these):