Document the Agent reinstallation process (#10270)
* Set up the reinstall doc * Building out reinstall page, tweaks * Finish up reinstallation doc * Fix one link * Fix broken links
Joel Hans committed
Nov 20, 2020 at 13:36 UTC
7cf6e03f4e4e09e64077669ebe53857a24cca564
10 files changed
+166
-114
aclk/README.md
+5
-4
@@ -111,11 +111,12 @@ Restart your Agent to disable the ACLK.
111
### Re-enable the ACLK
112
113
If you first disable the ACLK and any Cloud functionality and then decide you would like to use Cloud, you must either
114
-reinstall Netdata with Cloud enabled or change the runtime setting in your `cloud.conf` file.
114
+[reinstall Netdata](/packaging/installer/REINSTALL.md) with Cloud enabled or change the runtime setting in your
115
+`cloud.conf` file.
116
116
-If you passed `--disable-cloud` to `netdata-installer.sh` during installation, you must reinstall your Agent. Use the
117
-same method as before, but pass `--require-cloud` to the installer. When installation finishes you can [claim your
118
-node](/claim/README.md#how-to-claim-a-node).
117
+If you passed `--disable-cloud` to `netdata-installer.sh` during installation, you must
118
+[reinstall](/packaging/installer/REINSTALL.md) your Agent. Use the same method as before, but pass `--require-cloud` to
119
+the installer. When installation finishes you can [claim your node](/claim/README.md#how-to-claim-a-node).
120
121
If you changed the runtime setting in your `var/lib/netdata/cloud.d/cloud.conf` file, edit the file again and change
122
`enabled` to `yes`:
claim/README.md
+2
-4
@@ -1,10 +1,7 @@
1
<!--
2
----
2
title: "Agent claiming"
3
description: "Agent claiming allows a Netdata Agent, running on a distributed node, to securely connect to Netdata Cloud. A Space's administrator creates a claiming token, which is used to add an Agent to their Space via the Agent-Cloud link."
5
-date: 2020-04-30
4
custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md
7
----
5
-->
6
7
# Agent claiming
@@ -202,7 +199,8 @@ option, you need to update your `$PATH` or run `netdata-claim.sh` using the full
199
Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script.
200
201
If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,
205
-please remove that package and reinstall using our [recommended kickstart script](/docs/get#install-the-netdata-agent).
202
+please remove that package and reinstall using our [recommended kickstart
203
+script](/docs/get/README.md#install-the-netdata-agent).
204
205
#### Claiming on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)
206
docs/get/README.md
+16
@@ -125,6 +125,14 @@ Cloud. If the script returns an error, try our [troubleshooting tips](/claim/REA
125
For more information on the claiming process, why we implemented it, and how it works, see the [claim](/claim/README.md)
126
and [Agent-Cloud link](/aclk/README.md) reference docs.
127
128
+## Troubleshooting
129
+
130
+If you experience issues with installing the Netdata Agent, see our
131
+[installation](/packaging/installer/README.md#troubleshooting-and-known-issues) reference. Our
132
+[reinstall](/packaging/installer/REINSTALL.md) doc can help clean up your installation and get you back to monitoring.
133
+
134
+For Netdata Cloud issues, see the [Netdata Cloud reference docs](https://learn.netdata.cloud/docs/cloud).
135
+
136
## What's next?
137
138
At this point, you have set up your free Netdata Cloud account, installed the Netdata Agent on your node(s), and claimed
@@ -137,4 +145,12 @@ quickstart](/docs/quickstart/single-node.md).
145
If you're looking to monitor an entire infrastructure with Netdata, see the [infrastructure monitoring
146
quickstart](/docs/quickstart/infrastructure.md).
147
148
+### Related reference documentation
149
+
150
+- [Packaging & installer](/packaging/installer/README.md)
151
+- [Reinstall Netdata](/packaging/installer/REINSTALL.md)
152
+- [Update Netdata](/packaging/installer/UPDATE.md)
153
+- [Agent-Cloud link](/aclk/README.md)
154
+- [Agent claiming](/claim/README.md)
155
+
156
[](<>)
docs/guides/step-by-step/step-09.md
+4
-3
@@ -116,9 +116,10 @@ use netdata
116
db.createCollection("netdata_metrics")
117
```
118
119
-Next, Netdata needs to be reinstalled in order to detect that the required libraries to make this exporting connection
120
-exist. Since you most likely installed Netdata using the one-line installer script, all you have to do is run that
121
-script again. Don't worry—any configuration changes you made along the way will be retained!
119
+Next, Netdata needs to be [reinstalled](/packaging/installer/REINSTALL.md) in order to detect that the required
120
+libraries to make this exporting connection exist. Since you most likely installed Netdata using the one-line installer
121
+script, all you have to do is run that script again. Don't worry—any configuration changes you made along the way will
122
+be retained!
123
124
```bash
125
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
exporting/prometheus/remote_write/README.md
+2
-2
@@ -15,8 +15,8 @@ than 20 external storage providers for long-term archiving and further analysis.
15
To use the Prometheus remote write API with [storage
16
providers](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage), install
17
[protobuf](https://developers.google.com/protocol-buffers/) and [snappy](https://github.com/google/snappy) libraries.
18
-Next, re-install Netdata from the source, which detects that the required libraries and
19
-utilities are now available.
18
+Next, [reinstall Netdata](/packaging/installer/REINSTALL.md), which detects that the required libraries and utilities
19
+are now available.
20
21
## Configuration
22
packaging/installer/README.md
+2
-2
@@ -168,7 +168,7 @@ the community helps fix any bugs that might have been introduced in previous rel
168
installation
169
- Retain more control over the Netdata version you use
170
171
-## Installation notes and known issues
171
+## Troubleshooting and known issues
172
173
We are tracking a few issues related to installation and packaging.
174
@@ -232,4 +232,4 @@ issue altogether. Or, you can manually remove one version of OpenSSL to remove t
232
233
Our current build process has some issues when using certain configurations of the `clang` C compiler on Linux. See [the
234
section on `nonrepresentable section on output`
235
-errors](/packaging/installer/methods/manual.md#nonrepresentable-section-on-output-errors) for a workaround.
\ No newline at end of file
235
+errors](/packaging/installer/methods/manual.md#nonrepresentable-section-on-output-errors) for a workaround.
packaging/installer/REINSTALL.md
new
+68
@@ -0,0 +1,68 @@
1
+<!--
2
+title: "Reinstall the Netdata Agent"
3
+description: "Troubleshooting installation issues or force an update of the Netdata Agent by reinstalling it using the same method you used during installation."
4
+custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/REINSTALL.md
5
+-->
6
+
7
+# Reinstall the Netdata Agent
8
+
9
+In certain situations, such as needing to enable a feature or troubleshoot an issue, you may need to reinstall the
10
+Netdata Agent on your node.
11
+
12
+Before you try reinstalling Netdata, figure out which [installation method you
13
+used](/packaging/installer/UPDATE.md#determine-which-installation-method-you-used) if you do not already know. This will
14
+deterimine the reinstallation method.
15
+
16
+## One-line installer script (`kickstart.sh`)
17
+
18
+Run the one-line installer script with the `--reinstall` parameter to reinstall the Netdata Agent. This will preserve
19
+any [user configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
20
+
21
+If you used any [optional
22
+parameters](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) during initial
23
+installation, you need to pass them to the script again during reinstallation. If you cannot remember which options you
24
+used, read the contents of the `.environment` file and look for a `REINSTALL_OPTIONS` line. This line contains a list of
25
+optional parameters.
26
+
27
+```bash
28
+bash <(curl -Ss https://my-netdata.io/kickstart.sh) --reinstall
29
+```
30
+
31
+## `.deb` or `.rpm` packages
32
+
33
+If you installed Netdata with [`.deb` or `.rpm` packages](/packaging/installer/methods/packages.md), use your
34
+distribution's package manager to reinstall Netdata. Any custom settings present in your Netdata configuration directory
35
+(typically at `/etc/netdata`) persists during this process.
36
+
37
+```bash
38
+apt-get install --reinstall netdata # Ubuntu/Debian
39
+dnf reinstall netdata # Fedora/RHEL
40
+yum reinstall netdata # CentOS
41
+zypper in -f netdata # openSUSE
42
+```
43
+
44
+## Pre-built static binary for 64-bit systems (`kickstart-static64.sh`)
45
+
46
+Run the one-line installer script with the `--reinstall` parameter to reinstall the Netdata Agent. This will preserve
47
+any [user configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
48
+
49
+If you used any [optional
50
+parameters](/packaging/installer/methods/kickstart-64.md#optional-parameters-to-alter-your-installation) during
51
+initial installation, you need to pass them to the script again during reinstallation. If you cannot remember which
52
+options you used, read the contents of the `.environment` file and look for a `REINSTALL_OPTIONS` line. This line
53
+contains a list of optional parameters.
54
+
55
+```bash
56
+bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --reinstall
57
+```
58
+
59
+## Troubleshooting
60
+
61
+If you still experience problems with your Netdata Agent installation after following one of these processes, the next
62
+best route is to [uninstall](/packaging/installer/UNINSTALL.md) and then try a fresh installation using the [one-line
63
+installer](/packaging/installer/methods/kickstart.md).
64
+
65
+You can also post to our [community forums](https://community.netdata.cloud/c/support/13) or create a new [bug
66
+report](https://github.com/netdata/netdata/issues/new?labels=bug%2C+needs+triage&template=bug_report.md).
67
+
68
+[](<>)
packaging/installer/UNINSTALL.md
+4
-2
@@ -1,12 +1,14 @@
1
<!--
2
----
2
title: "Uninstall Netdata"
3
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UNINSTALL.md
5
----
4
-->
5
6
# Uninstall Netdata
7
8
+> ⚠️ If you're having trouble updating Netdata, moving from one installation method to another, or generally having
9
+> issues with your Netdata Agent installation, consider our [**reinstall Netdata**
10
+> doc](/packaging/installer/REINSTALL.md) instead of removing the Netdata Agent entirely.
11
+
12
Our self-contained uninstaller is able to remove Netdata installations created with shell installer. It doesn't need any
13
other Netdata repository files to be run. All it needs is an `.environment` file, which is created during installation
14
(with shell installer) and put in `${NETDATA_USER_CONFIG_DIR}/.environment` (by default `/etc/netdata/.environment`).
packaging/installer/UPDATE.md
+44
-64
@@ -1,26 +1,37 @@
1
<!--
2
----
3
-title: "Update Netdata"
4
-description: "We actively develop Netdata to add new features and remove bugs. Here's how to stay up-to-date with the
5
-latest nightly or major releases."
6
-date: 2020-03-12
2
+title: "Update the Netdata Agen"
3
+description: "If you opted out of automatic updates, you need to update your Netdata Agent to the latest nightly or stable version."
4
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md
8
----
5
-->
6
11
-# Update Netdata
7
+# Update the Netdata Agent
8
13
-We actively develop Netdata to add new features and remove bugs, and encourage all users to ensure they're using the
14
-most up-to-date version, whether that's nightly or major releases.
9
+By default, the Netdata Agent automatically updates with the latest nightly version. If you opted out of automatic
10
+updates, you need to update your Netdata Agent to the latest nightly or stable version.
11
16
-Before you update Netdata using one of the methods below, check to see if your Netdata agent is already up-to-date by
17
-opening the update modal in the dashboard. Click the **Update** button in the top navigation to open it. The modal tells
18
-you whether your agent is up-to-date or not.
12
+> 💡 Looking to reinstall the Netdata Agent to enable a feature, update an Agent that cannot update automatically, or
13
+> troubleshoot an error during the installation process? See our [reinstallation doc](/packaging/installer/REINSTALL.md)
14
+> for reinstallation steps.
15
20
-
16
+Before you update the Netdata Agent, check to see if your Netdata Agent is already up-to-date by clicking on the update
17
+icon in the local Agent dashboard's top navigation. This modal informs you whether your Agent needs an update or not.
18
22
-If your agent can be updated, use one of the methods below. **The method you chose for updating Netdata depends on how
23
-you installed it.** Choose from the following list to see the appropriate update instructions for your system.
19
+
20
+
21
+## Determine which installation method you used
22
+
23
+If you are not sure where your Netdata config directory is, see the [configuration doc](/docs/configure/nodes.md). In
24
+most installations, this is `/etc/netdata`.
25
+
26
+Use `cd` to navigate to the Netdata config directory, then use `ls -a` to look for a file called `.environment`.
27
+
28
+- If the `.environment` file _does not_ exist, reinstall with your [package manager](#deb-or-rpm-packages).
29
+- If the `.environtment` file _does_ exist, check its contents with `less .environment`.
30
+ - If `IS_NETDATA_STATIC_BINARY` is `"yes"`, update using the [pre-built static
31
+ binary](#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh).
32
+ - In all other cases, update using the [one-line installer script](#one-line-installer-script-kickstartsh).
33
+
34
+Next, use the appropriate method to update the Netdata Agent:
35
36
- [One-line installer script (`kickstart.sh`)](#one-line-installer-script-kickstartsh)
37
- [`.deb` or `.rpm` packages](#deb-or-rpm-packages)
@@ -29,17 +40,6 @@ you installed it.** Choose from the following list to see the appropriate update
40
- [macOS](#macos)
41
- [Manual installation from Git](#manual-installation-from-git)
42
32
-#### How to determine which install method you used
33
-
34
-First, see [here](https://learn.netdata.cloud/docs/configure/nodes#the-netdata-config-directory) to figure out
35
-where your user configuration files for Netdata are.
36
-
37
-Once you have figured this out, look for a file called `.environment` in this directory (you will need to use
38
-`ls -a` to see it, as it will not be listed by default by a regular `ls` command). If it is not there, you used
39
-package manager to install netdata and need to update it through that package manager. If the `environment` file
40
-is present, check the contents of the file. If `IS_NETDATA_STATIC_BINARY` is `"yes"`, then you installed using
41
-`kickstart-static64.sh`. Otherwise you installed using `kickstart.sh`.
42
-
43
## One-line installer script (`kickstart.sh`)
44
45
If you installed Netdata using our one-line automatic installation script, run it again to update Netdata. Any custom
@@ -55,27 +55,17 @@ that prefix to this command to make sure it finds Netdata.
55
bash <(curl -Ss https://my-netdata.io/kickstart.sh)
56
```
57
58
-In the event that this command fails, there may be an issue with the installed update script. In such cases, you
59
-can instead use the following command to run an update as if it were a clean install (this will still preserve
60
-any user configuration).
61
-
62
-```bash
63
-bash <(curl -Ss https://my-netdata.io/kickstart.sh) --reinstall
64
-```
65
-
66
-If using this method, you will need to pass any options you passed during the original installation process. To
67
-determine what options you passed, start by finding the `.environment` file for your install as described above in
68
-[How to determine which install method you used](#how-to-determine-which-install-method-you-used). Once you have
69
-found this file, look at the value of the `REINSTALL_OPTIONS` line. This is the list of additional options you
70
-need to pass to the above command.
58
+> ❗ If the above command fails, you can [reinstall
59
+> Netdata](/packaging/installer/REINSTALL.md#one-line-installer-script-kickstartsh) to get the latest version. This also
60
+> preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
61
62
## `.deb` or `.rpm` packages
63
74
-If you installed Netdata with `.deb` or `.rpm` packages, use your distribution's package manager update Netdata. Any
75
-custom settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists during this
76
-process.
64
+If you installed Netdata with [`.deb` or `.rpm` packages](/packaging/installer/methods/packages.md), use your
65
+distribution's package manager to update Netdata. Any custom settings present in your Netdata configuration directory
66
+(typically at `/etc/netdata`) persists during this process.
67
78
-Your package manager grabs a new package from our hosted repository, updates Netdata, and restarts it.
68
+Your package manager grabs a new package from our hosted repository, updates the Netdata Agent, and restarts it.
69
70
```bash
71
apt-get install netdata # Ubuntu/Debian
@@ -99,25 +89,15 @@ you disabled automatic updates) and preserve the existing install options you sp
89
bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh)
90
```
91
102
-In the event that this command fails, there may be an issue with the installed update script. In such cases, you
103
-can instead use the following command to run an update as if it were a clean install (this will still preserve
104
-any user configuration).
105
-
106
-```bash
107
-bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --reinstall
108
-```
109
-
110
-If using this method, you will need to pass any options you passed during the original installation process. To
111
-determine what options you passed, start by finding the `.environment` file for your install as described above in
112
-[How to determine which install method you used](#how-to-determine-which-install-method-you-used). Once you have
113
-found this file, look at the value of the `REINSTALL_OPTIONS` line. This is the list of additional options you
114
-need to pass to the above command.
92
+> ❗ If the above command fails, you can [reinstall
93
+> Netdata](/packaging/installer/REINSTALL.md#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh) to get the
94
+> latest version. This also preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
95
96
## Docker
97
118
-Docker-based installations do not update automatically. To update an agent running in a Docker container, you must pull
119
-the [latest image from Docker hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container, and
120
-re-create it using the latest image.
98
+Docker-based installations do not update automatically. To update an Netdata Agent running in a Docker container, you
99
+must pull the [latest image from Docker Hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container,
100
+and re-create it using the latest image.
101
102
First, pull the latest version of the image.
103
@@ -150,16 +130,16 @@ and updates Netdata via reinstallation.
130
131
## Manual installation from Git
132
153
-If you installed Netdata manually from Git using `netdata-installer.sh`, you can run that installer again to update your
154
-agent. First, run our automatic requirements installer, which works on many Linux distributions, to ensure your system
155
-has the dependencies necessary for new features.
133
+If you installed [Netdata manually from Git](/packaging/installer/methods/manual.md), you can run that installer again
134
+to update your agent. First, run our automatic requirements installer, which works on many Linux distributions, to
135
+ensure your system has the dependencies necessary for new features.
136
137
```bash
138
bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh)
139
```
140
161
-Then, navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run
162
-`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation.
141
+Navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run
142
+`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation.
143
144
```bash
145
cd /path/to/netdata/git
packaging/installer/methods/packages.md
+19
-33
@@ -1,52 +1,38 @@
1
<!--
2
----
2
title: "Install Netdata with .deb/.rpm packages"
3
+desciption: "Install the Netdata Agent with Linux packages that support Ubuntu, Debian, Fedora, RHEL, CentOS, openSUSE, and more."
4
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/packages.md
5
----
5
-->
6
7
# Install Netdata with .deb/.rpm packages
8
9
10
12
-We provide our own flavour of binary packages for the most common operating systems that comply with .RPM and .DEB
13
-packaging formats.
11
+Netdata provides our own flavour of binary packages for the most common operating systems that use with `.deb` and
12
+`.rpm` packaging formats.
13
15
-We have currently released packages following the .RPM format with version
16
-[1.16.0](https://github.com/netdata/netdata/releases/tag/v1.16.0) and packages following the
17
-.DEB format with version [1.17.0](https://github.com/netdata/netdata/releases/tag/v1.17.0). Our current packaging infrastructure provider is [Package Cloud](https://packagecloud.io).
14
+We provide two separate repositories, one for our stable releases and one for our nightly releases. Visit the repository
15
+pages and follow the quick set-up instructions to get started.
16
19
-Netdata is committed to support installation of our solution to all operating systems. This is a constant battle for
20
-Netdata, as we strive to automate and make things easier for our users. For the operating system support matrix, please
21
-visit our [distributions](../../DISTRIBUTIONS.md) support page.
17
+1. Stable releases: Our stable production releases are hosted in the
18
+ [netdata/netdata](https://packagecloud.io/netdata/netdata) repository on packagecloud
19
+2. Nightly releases: Our latest releases are hosted in the
20
+ [netdata/netdata-edge](https://packagecloud.io/netdata/netdata-edge) repository on packagecloud
21
23
-We provide two separate repositories, one for our stable releases and one for our nightly releases.
22
+## Using caching proxies with packagecloud repositories
23
25
-1. Stable releases: Our stable production releases are hosted in
26
- [netdata/netdata](https://packagecloud.io/netdata/netdata) repository of package cloud
27
-2. Nightly releases: Our latest releases are hosted in
28
- [netdata/netdata-edge](https://packagecloud.io/netdata/netdata-edge) repository of package cloud
29
-
30
-Visit the repository pages and follow the quick set-up instructions to get started.
31
-
32
-## Using caching proxies with PackageCloud repositories
33
-
34
-PackageCloud only provides HTTPS access to repositories they host, which
35
-means in turn that Netdata's package repositories are only accessible
36
-via HTTPS. This is known to cause issues with some setups that use a
37
-caching proxy for package downloads.
24
+packagecloud only provides HTTPS access to repositories they host, which means in turn that Netdata's package
25
+repositories are only accessible via HTTPS. This is known to cause issues with some setups that use a caching proxy for
26
+package downloads.
27
28
If you are using such a setup, there are a couple of ways you can work around this:
29
41
-* Configure your proxy to automatically pass through HTTPS connections
42
- without caching them. This is the simplest solution, but means that
43
- downloads of Netdata pacakges will not be cached.
44
-* Mirror the respository locally on your proxy system, and use that mirror
45
- when installing on other systems. This requires more setup and more disk
46
- space on the caching host, but it lets you cache the packages locally.
47
-* Some specific caching proxies may have alternative configuration
48
- options to deal with these issues. You can find such options in their
49
- documentation.
30
+- Configure your proxy to automatically pass through HTTPS connections without caching them. This is the simplest
31
+ solution, but means that downloads of Netdata pacakges will not be cached.
32
+- Mirror the respository locally on your proxy system, and use that mirror when installing on other systems. This
33
+ requires more setup and more disk space on the caching host, but it lets you cache the packages locally.
34
+- Some specific caching proxies may have alternative configuration options to deal with these issues. You can find
35
+ such options in their documentation.
36
37
## What's next?
38