diff options
| -rw-r--r-- | aclk/README.md | 9 | ||||
| -rw-r--r-- | claim/README.md | 6 | ||||
| -rw-r--r-- | docs/get/README.md | 16 | ||||
| -rw-r--r-- | docs/guides/step-by-step/step-09.md | 7 | ||||
| -rw-r--r-- | exporting/prometheus/remote_write/README.md | 4 | ||||
| -rw-r--r-- | packaging/installer/README.md | 4 | ||||
| -rw-r--r-- | packaging/installer/REINSTALL.md | 68 | ||||
| -rw-r--r-- | packaging/installer/UNINSTALL.md | 6 | ||||
| -rw-r--r-- | packaging/installer/UPDATE.md | 108 | ||||
| -rw-r--r-- | packaging/installer/methods/packages.md | 52 |
10 files changed, 166 insertions, 114 deletions
diff --git a/aclk/README.md b/aclk/README.md index 5702ec7e41..14aeb4b657 100644 --- a/aclk/README.md +++ b/aclk/README.md @@ -111,11 +111,12 @@ Restart your Agent to disable the ACLK. ### Re-enable the ACLK If you first disable the ACLK and any Cloud functionality and then decide you would like to use Cloud, you must either -reinstall Netdata with Cloud enabled or change the runtime setting in your `cloud.conf` file. +[reinstall Netdata](/packaging/installer/REINSTALL.md) with Cloud enabled or change the runtime setting in your +`cloud.conf` file. -If you passed `--disable-cloud` to `netdata-installer.sh` during installation, you must reinstall your Agent. Use the -same method as before, but pass `--require-cloud` to the installer. When installation finishes you can [claim your -node](/claim/README.md#how-to-claim-a-node). +If you passed `--disable-cloud` to `netdata-installer.sh` during installation, you must +[reinstall](/packaging/installer/REINSTALL.md) your Agent. Use the same method as before, but pass `--require-cloud` to +the installer. When installation finishes you can [claim your node](/claim/README.md#how-to-claim-a-node). If you changed the runtime setting in your `var/lib/netdata/cloud.d/cloud.conf` file, edit the file again and change `enabled` to `yes`: diff --git a/claim/README.md b/claim/README.md index 65a912dfd0..17fe255815 100644 --- a/claim/README.md +++ b/claim/README.md @@ -1,10 +1,7 @@ <!-- ---- title: "Agent claiming" 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." -date: 2020-04-30 custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md ---- --> # Agent claiming @@ -202,7 +199,8 @@ option, you need to update your `$PATH` or run `netdata-claim.sh` using the full Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim.sh` to run the claiming script. If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution, -please remove that package and reinstall using our [recommended kickstart script](/docs/get#install-the-netdata-agent). +please remove that package and reinstall using our [recommended kickstart +script](/docs/get/README.md#install-the-netdata-agent). #### Claiming on older distributions (Ubuntu 14.04, Debian 8, CentOS 6) diff --git a/docs/get/README.md b/docs/get/README.md index bd2580dba3..55029cf4c2 100644 --- a/docs/get/README.md +++ b/docs/get/README.md @@ -125,6 +125,14 @@ Cloud. If the script returns an error, try our [troubleshooting tips](/claim/REA For more information on the claiming process, why we implemented it, and how it works, see the [claim](/claim/README.md) and [Agent-Cloud link](/aclk/README.md) reference docs. +## Troubleshooting + +If you experience issues with installing the Netdata Agent, see our +[installation](/packaging/installer/README.md#troubleshooting-and-known-issues) reference. Our +[reinstall](/packaging/installer/REINSTALL.md) doc can help clean up your installation and get you back to monitoring. + +For Netdata Cloud issues, see the [Netdata Cloud reference docs](https://learn.netdata.cloud/docs/cloud). + ## What's next? 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). If you're looking to monitor an entire infrastructure with Netdata, see the [infrastructure monitoring quickstart](/docs/quickstart/infrastructure.md). +### Related reference documentation + +- [Packaging & installer](/packaging/installer/README.md) +- [Reinstall Netdata](/packaging/installer/REINSTALL.md) +- [Update Netdata](/packaging/installer/UPDATE.md) +- [Agent-Cloud link](/aclk/README.md) +- [Agent claiming](/claim/README.md) + [](<>) diff --git a/docs/guides/step-by-step/step-09.md b/docs/guides/step-by-step/step-09.md index c80781bf0d..8397a96d12 100644 --- a/docs/guides/step-by-step/step-09.md +++ b/docs/guides/step-by-step/step-09.md @@ -116,9 +116,10 @@ use netdata db.createCollection("netdata_metrics") ``` -Next, Netdata needs to be reinstalled in order to detect that the required libraries to make this exporting connection -exist. Since you most likely installed Netdata using the one-line installer script, all you have to do is run that -script again. Don't worry—any configuration changes you made along the way will be retained! +Next, Netdata needs to be [reinstalled](/packaging/installer/REINSTALL.md) in order to detect that the required +libraries to make this exporting connection exist. Since you most likely installed Netdata using the one-line installer +script, all you have to do is run that script again. Don't worry—any configuration changes you made along the way will +be retained! ```bash bash <(curl -Ss https://my-netdata.io/kickstart.sh) diff --git a/exporting/prometheus/remote_write/README.md b/exporting/prometheus/remote_write/README.md index 0e67e3459d..fe901024bd 100644 --- a/exporting/prometheus/remote_write/README.md +++ b/exporting/prometheus/remote_write/README.md @@ -15,8 +15,8 @@ than 20 external storage providers for long-term archiving and further analysis. To use the Prometheus remote write API with [storage providers](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage), install [protobuf](https://developers.google.com/protocol-buffers/) and [snappy](https://github.com/google/snappy) libraries. -Next, re-install Netdata from the source, which detects that the required libraries and -utilities are now available. +Next, [reinstall Netdata](/packaging/installer/REINSTALL.md), which detects that the required libraries and utilities +are now available. ## Configuration diff --git a/packaging/installer/README.md b/packaging/installer/README.md index 393361a358..2884530684 100644 --- a/packaging/installer/README.md +++ b/packaging/installer/README.md @@ -168,7 +168,7 @@ the community helps fix any bugs that might have been introduced in previous rel installation - Retain more control over the Netdata version you use -## Installation notes and known issues +## Troubleshooting and known issues We are tracking a few issues related to installation and packaging. @@ -232,4 +232,4 @@ issue altogether. Or, you can manually remove one version of OpenSSL to remove t Our current build process has some issues when using certain configurations of the `clang` C compiler on Linux. See [the section on `nonrepresentable section on output` -errors](/packaging/installer/methods/manual.md#nonrepresentable-section-on-output-errors) for a workaround.
\ No newline at end of file +errors](/packaging/installer/methods/manual.md#nonrepresentable-section-on-output-errors) for a workaround. diff --git a/packaging/installer/REINSTALL.md b/packaging/installer/REINSTALL.md new file mode 100644 index 0000000000..122f1a8473 --- /dev/null +++ b/packaging/installer/REINSTALL.md @@ -0,0 +1,68 @@ +<!-- +title: "Reinstall the Netdata Agent" +description: "Troubleshooting installation issues or force an update of the Netdata Agent by reinstalling it using the same method you used during installation." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/REINSTALL.md +--> + +# Reinstall the Netdata Agent + +In certain situations, such as needing to enable a feature or troubleshoot an issue, you may need to reinstall the +Netdata Agent on your node. + +Before you try reinstalling Netdata, figure out which [installation method you +used](/packaging/installer/UPDATE.md#determine-which-installation-method-you-used) if you do not already know. This will +deterimine the reinstallation method. + +## One-line installer script (`kickstart.sh`) + +Run the one-line installer script with the `--reinstall` parameter to reinstall the Netdata Agent. This will preserve +any [user configuration](/docs/configure/nodes.md) in `netdata.conf` or other files. + +If you used any [optional +parameters](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) during initial +installation, you need to pass them to the script again during reinstallation. If you cannot remember which options you +used, read the contents of the `.environment` file and look for a `REINSTALL_OPTIONS` line. This line contains a list of +optional parameters. + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --reinstall +``` + +## `.deb` or `.rpm` packages + +If you installed Netdata with [`.deb` or `.rpm` packages](/packaging/installer/methods/packages.md), use your +distribution's package manager to reinstall Netdata. Any custom settings present in your Netdata configuration directory +(typically at `/etc/netdata`) persists during this process. + +```bash +apt-get install --reinstall netdata # Ubuntu/Debian +dnf reinstall netdata # Fedora/RHEL +yum reinstall netdata # CentOS +zypper in -f netdata # openSUSE +``` + +## Pre-built static binary for 64-bit systems (`kickstart-static64.sh`) + +Run the one-line installer script with the `--reinstall` parameter to reinstall the Netdata Agent. This will preserve +any [user configuration](/docs/configure/nodes.md) in `netdata.conf` or other files. + +If you used any [optional +parameters](/packaging/installer/methods/kickstart-64.md#optional-parameters-to-alter-your-installation) during +initial installation, you need to pass them to the script again during reinstallation. If you cannot remember which +options you used, read the contents of the `.environment` file and look for a `REINSTALL_OPTIONS` line. This line +contains a list of optional parameters. + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --reinstall +``` + +## Troubleshooting + +If you still experience problems with your Netdata Agent installation after following one of these processes, the next +best route is to [uninstall](/packaging/installer/UNINSTALL.md) and then try a fresh installation using the [one-line +installer](/packaging/installer/methods/kickstart.md). + +You can also post to our [community forums](https://community.netdata.cloud/c/support/13) or create a new [bug +report](https://github.com/netdata/netdata/issues/new?labels=bug%2C+needs+triage&template=bug_report.md). + +[](<>) diff --git a/packaging/installer/UNINSTALL.md b/packaging/installer/UNINSTALL.md index ab29cb8b89..f900fe5cb3 100644 --- a/packaging/installer/UNINSTALL.md +++ b/packaging/installer/UNINSTALL.md @@ -1,12 +1,14 @@ <!-- ---- title: "Uninstall Netdata" custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UNINSTALL.md ---- --> # Uninstall Netdata +> ⚠️ If you're having trouble updating Netdata, moving from one installation method to another, or generally having +> issues with your Netdata Agent installation, consider our [**reinstall Netdata** +> doc](/packaging/installer/REINSTALL.md) instead of removing the Netdata Agent entirely. + Our self-contained uninstaller is able to remove Netdata installations created with shell installer. It doesn't need any other Netdata repository files to be run. All it needs is an `.environment` file, which is created during installation (with shell installer) and put in `${NETDATA_USER_CONFIG_DIR}/.environment` (by default `/etc/netdata/.environment`). diff --git a/packaging/installer/UPDATE.md b/packaging/installer/UPDATE.md index 47ddc238a9..de0fa116e3 100644 --- a/packaging/installer/UPDATE.md +++ b/packaging/installer/UPDATE.md @@ -1,26 +1,37 @@ <!-- ---- -title: "Update Netdata" -description: "We actively develop Netdata to add new features and remove bugs. Here's how to stay up-to-date with the -latest nightly or major releases." -date: 2020-03-12 +title: "Update the Netdata Agen" +description: "If you opted out of automatic updates, you need to update your Netdata Agent to the latest nightly or stable version." custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md ---- --> -# Update Netdata +# Update the Netdata Agent -We actively develop Netdata to add new features and remove bugs, and encourage all users to ensure they're using the -most up-to-date version, whether that's nightly or major releases. +By default, the Netdata Agent automatically updates with the latest nightly version. If you opted out of automatic +updates, you need to update your Netdata Agent to the latest nightly or stable version. -Before you update Netdata using one of the methods below, check to see if your Netdata agent is already up-to-date by -opening the update modal in the dashboard. Click the **Update** button in the top navigation to open it. The modal tells -you whether your agent is up-to-date or not. +> 💡 Looking to reinstall the Netdata Agent to enable a feature, update an Agent that cannot update automatically, or +> troubleshoot an error during the installation process? See our [reinstallation doc](/packaging/installer/REINSTALL.md) +> for reinstallation steps. - +Before you update the Netdata Agent, check to see if your Netdata Agent is already up-to-date by clicking on the update +icon in the local Agent dashboard's top navigation. This modal informs you whether your Agent needs an update or not. -If your agent can be updated, use one of the methods below. **The method you chose for updating Netdata depends on how -you installed it.** Choose from the following list to see the appropriate update instructions for your system. + + +## Determine which installation method you used + +If you are not sure where your Netdata config directory is, see the [configuration doc](/docs/configure/nodes.md). In +most installations, this is `/etc/netdata`. + +Use `cd` to navigate to the Netdata config directory, then use `ls -a` to look for a file called `.environment`. + +- If the `.environment` file _does not_ exist, reinstall with your [package manager](#deb-or-rpm-packages). +- If the `.environtment` file _does_ exist, check its contents with `less .environment`. + - If `IS_NETDATA_STATIC_BINARY` is `"yes"`, update using the [pre-built static + binary](#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh). + - In all other cases, update using the [one-line installer script](#one-line-installer-script-kickstartsh). + +Next, use the appropriate method to update the Netdata Agent: - [One-line installer script (`kickstart.sh`)](#one-line-installer-script-kickstartsh) - [`.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 - [macOS](#macos) - [Manual installation from Git](#manual-installation-from-git) -#### How to determine which install method you used - -First, see [here](https://learn.netdata.cloud/docs/configure/nodes#the-netdata-config-directory) to figure out -where your user configuration files for Netdata are. - -Once you have figured this out, look for a file called `.environment` in this directory (you will need to use -`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 -package manager to install netdata and need to update it through that package manager. If the `environment` file -is present, check the contents of the file. If `IS_NETDATA_STATIC_BINARY` is `"yes"`, then you installed using -`kickstart-static64.sh`. Otherwise you installed using `kickstart.sh`. - ## One-line installer script (`kickstart.sh`) 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. bash <(curl -Ss https://my-netdata.io/kickstart.sh) ``` -In the event that this command fails, there may be an issue with the installed update script. In such cases, you -can instead use the following command to run an update as if it were a clean install (this will still preserve -any user configuration). - -```bash -bash <(curl -Ss https://my-netdata.io/kickstart.sh) --reinstall -``` - -If using this method, you will need to pass any options you passed during the original installation process. To -determine what options you passed, start by finding the `.environment` file for your install as described above in -[How to determine which install method you used](#how-to-determine-which-install-method-you-used). Once you have -found this file, look at the value of the `REINSTALL_OPTIONS` line. This is the list of additional options you -need to pass to the above command. +> ❗ If the above command fails, you can [reinstall +> Netdata](/packaging/installer/REINSTALL.md#one-line-installer-script-kickstartsh) to get the latest version. This also +> preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files. ## `.deb` or `.rpm` packages -If you installed Netdata with `.deb` or `.rpm` packages, use your distribution's package manager update Netdata. Any -custom settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists during this -process. +If you installed Netdata with [`.deb` or `.rpm` packages](/packaging/installer/methods/packages.md), use your +distribution's package manager to update Netdata. Any custom settings present in your Netdata configuration directory +(typically at `/etc/netdata`) persists during this process. -Your package manager grabs a new package from our hosted repository, updates Netdata, and restarts it. +Your package manager grabs a new package from our hosted repository, updates the Netdata Agent, and restarts it. ```bash apt-get install netdata # Ubuntu/Debian @@ -99,25 +89,15 @@ you disabled automatic updates) and preserve the existing install options you sp bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) ``` -In the event that this command fails, there may be an issue with the installed update script. In such cases, you -can instead use the following command to run an update as if it were a clean install (this will still preserve -any user configuration). - -```bash -bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --reinstall -``` - -If using this method, you will need to pass any options you passed during the original installation process. To -determine what options you passed, start by finding the `.environment` file for your install as described above in -[How to determine which install method you used](#how-to-determine-which-install-method-you-used). Once you have -found this file, look at the value of the `REINSTALL_OPTIONS` line. This is the list of additional options you -need to pass to the above command. +> ❗ If the above command fails, you can [reinstall +> Netdata](/packaging/installer/REINSTALL.md#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh) to get the +> latest version. This also preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files. ## Docker -Docker-based installations do not update automatically. To update an agent running in a Docker container, you must pull -the [latest image from Docker hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container, and -re-create it using the latest image. +Docker-based installations do not update automatically. To update an Netdata Agent running in a Docker container, you +must pull the [latest image from Docker Hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container, +and re-create it using the latest image. First, pull the latest version of the image. @@ -150,16 +130,16 @@ and updates Netdata via reinstallation. ## Manual installation from Git -If you installed Netdata manually from Git using `netdata-installer.sh`, you can run that installer again to update your -agent. First, run our automatic requirements installer, which works on many Linux distributions, to ensure your system -has the dependencies necessary for new features. +If you installed [Netdata manually from Git](/packaging/installer/methods/manual.md), you can run that installer again +to update your agent. First, run our automatic requirements installer, which works on many Linux distributions, to +ensure your system has the dependencies necessary for new features. ```bash bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh) ``` -Then, navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run -`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation. +Navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run +`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation. ```bash cd /path/to/netdata/git diff --git a/packaging/installer/methods/packages.md b/packaging/installer/methods/packages.md index e31dfe76db..ef08b830df 100644 --- a/packaging/installer/methods/packages.md +++ b/packaging/installer/methods/packages.md @@ -1,52 +1,38 @@ <!-- ---- title: "Install Netdata with .deb/.rpm packages" +desciption: "Install the Netdata Agent with Linux packages that support Ubuntu, Debian, Fedora, RHEL, CentOS, openSUSE, and more." custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/packages.md ---- --> # Install Netdata with .deb/.rpm packages  -We provide our own flavour of binary packages for the most common operating systems that comply with .RPM and .DEB -packaging formats. +Netdata provides our own flavour of binary packages for the most common operating systems that use with `.deb` and +`.rpm` packaging formats. -We have currently released packages following the .RPM format with version -[1.16.0](https://github.com/netdata/netdata/releases/tag/v1.16.0) and packages following the -.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). +We provide two separate repositories, one for our stable releases and one for our nightly releases. Visit the repository +pages and follow the quick set-up instructions to get started. -Netdata is committed to support installation of our solution to all operating systems. This is a constant battle for -Netdata, as we strive to automate and make things easier for our users. For the operating system support matrix, please -visit our [distributions](../../DISTRIBUTIONS.md) support page. +1. Stable releases: Our stable production releases are hosted in the + [netdata/netdata](https://packagecloud.io/netdata/netdata) repository on packagecloud +2. Nightly releases: Our latest releases are hosted in the + [netdata/netdata-edge](https://packagecloud.io/netdata/netdata-edge) repository on packagecloud -We provide two separate repositories, one for our stable releases and one for our nightly releases. +## Using caching proxies with packagecloud repositories -1. Stable releases: Our stable production releases are hosted in - [netdata/netdata](https://packagecloud.io/netdata/netdata) repository of package cloud -2. Nightly releases: Our latest releases are hosted in - [netdata/netdata-edge](https://packagecloud.io/netdata/netdata-edge) repository of package cloud - -Visit the repository pages and follow the quick set-up instructions to get started. - -## Using caching proxies with PackageCloud repositories - -PackageCloud only provides HTTPS access to repositories they host, which -means in turn that Netdata's package repositories are only accessible -via HTTPS. This is known to cause issues with some setups that use a -caching proxy for package downloads. +packagecloud only provides HTTPS access to repositories they host, which means in turn that Netdata's package +repositories are only accessible via HTTPS. This is known to cause issues with some setups that use a caching proxy for +package downloads. If you are using such a setup, there are a couple of ways you can work around this: -* Configure your proxy to automatically pass through HTTPS connections - without caching them. This is the simplest solution, but means that - downloads of Netdata pacakges will not be cached. -* Mirror the respository locally on your proxy system, and use that mirror - when installing on other systems. This requires more setup and more disk - space on the caching host, but it lets you cache the packages locally. -* Some specific caching proxies may have alternative configuration - options to deal with these issues. You can find such options in their - documentation. +- Configure your proxy to automatically pass through HTTPS connections without caching them. This is the simplest + solution, but means that downloads of Netdata pacakges will not be cached. +- Mirror the respository locally on your proxy system, and use that mirror when installing on other systems. This + requires more setup and more disk space on the caching host, but it lets you cache the packages locally. +- Some specific caching proxies may have alternative configuration options to deal with these issues. You can find + such options in their documentation. ## What's next? |