mirror of
https://github.com/netdata/netdata.git
synced 2025-04-02 20:48:06 +00:00
Installation section simplification (#18911)
Co-authored-by: ilyam8 <ilya@netdata.cloud>
This commit is contained in:
Fotis Voutsas
GitHub
parent
3e09256884
commit
a4201c88dc
15 changed files with 91 additions and 363 deletions
docs/developer-and-contributor-corner
packaging/installer
src
claim
collectors
perf.plugin
python.d.plugin/go_expvar
statsd.plugin
daemon/config
health/notifications
|
|
@ -37,8 +37,8 @@ configuring CockroachDB. Netdata only needs to regularly query the database's `_
|
|||
display them on the dashboard.
|
||||
|
||||
If your CockroachDB instance is accessible through `http://localhost:8080/` or `http://127.0.0.1:8080`, your setup is
|
||||
complete. Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate
|
||||
method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, and refresh your browser. You should see CockroachDB
|
||||
complete. Restart Netdata with `sudo systemctl restart netdata`, or the appropriate
|
||||
method for your system, and refresh your browser. You should see CockroachDB
|
||||
metrics in your Netdata dashboard!
|
||||
|
||||
<figure>
|
||||
|
|
|
|||
|
|
@ -180,7 +180,7 @@ sql: mariad* postmaster* oracle_* ora_* sqlservr
|
|||
```
|
||||
|
||||
Restart Netdata with `sudo systemctl restart netdata`, or
|
||||
the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, to start collecting utilization metrics
|
||||
the appropriate method for your system, to start collecting utilization metrics
|
||||
from your application. Time to [visualize your process metrics](#visualize-process-metrics).
|
||||
|
||||
### Custom applications
|
||||
|
|
@ -207,7 +207,7 @@ custom-app: custom-app
|
|||
```
|
||||
|
||||
Restart Netdata with `sudo systemctl restart netdata`, or
|
||||
the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, to start collecting utilization metrics
|
||||
the appropriate method for your system, to start collecting utilization metrics
|
||||
from your application.
|
||||
|
||||
## Visualize process metrics
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ LLVM_CONFIG=llvm-config-9 pip3 install --user llvmlite numpy==1.20.1 netdata-pan
|
|||
|
||||
## Enable the anomalies collector
|
||||
|
||||
Now you're ready to enable the collector and [restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation).
|
||||
Now you're ready to enable the collector and restart Netdata.
|
||||
|
||||
```bash
|
||||
sudo ./edit-config python.d.conf
|
||||
|
|
|
|||
|
|
@ -6,150 +6,15 @@ Netdata is very flexible and can be used to monitor all kinds of infrastructure.
|
|||
|
||||
The easiest way to install Netdata on your system is via Netdata Cloud, to do so:
|
||||
|
||||
1. Sign up to <https://app.netdata.cloud/>.
|
||||
2. You will be presented with an empty space, and a prompt to "Connect Nodes" with the install command for each platform.
|
||||
3. Select the platform you want to install Netdata to, copy and paste the script into your node's terminal, and run it.
|
||||
1. Sign in to <https://app.netdata.cloud/>.
|
||||
2. Select a [Space](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md#netdata-cloud-spaces), and click the "Connect Nodes" prompt, which will show the install command for your platform of choice.
|
||||
3. Copy and paste the script into your node's terminal, and run it.
|
||||
|
||||
Once Netdata is installed, you can see the node live in your Netdata Space and charts in the [Metrics tab](/docs/dashboards-and-charts/metrics-tab-and-single-node-tabs.md).
|
||||
|
||||
Take a look at our [Dashboards and Charts](/docs/dashboards-and-charts/README.md) section to read more about Netdata's features.
|
||||
## Anonymous statistics
|
||||
|
||||
## Post-install
|
||||
|
||||
### Configuration
|
||||
|
||||
If you are looking to configure your Netdata Agent installation, refer to the [respective section in our Documentation](/docs/netdata-agent/configuration/README.md).
|
||||
|
||||
### Data collection
|
||||
|
||||
If Netdata didn't autodetect all the hardware, containers, services, or applications running on your node, you should learn more about [how data collectors work](/src/collectors/README.md). If there's a [supported integration](/src/collectors/COLLECTORS.md) for metrics you need, refer to its respective page and read about its requirements to configure your endpoint to publish metrics in the correct format and endpoint.
|
||||
|
||||
### Alerts & notifications
|
||||
|
||||
Netdata comes with hundreds of pre-configured alerts, designed by our monitoring gurus in parallel with our open-source community, but you may want to [edit alerts](/src/health/REFERENCE.md) or [enable notifications](/docs/alerts-and-notifications/notifications/README.md) to customize your Netdata experience.
|
||||
|
||||
### Make your deployment production ready
|
||||
|
||||
Go through our [deployment guides](/docs/deployment-guides/README.md), for suggested configuration changes for production deployments.
|
||||
|
||||
## Advanced installation options and troubleshooting
|
||||
|
||||
### Automatic updates
|
||||
|
||||
By default, Netdata's installation scripts enable automatic updates for both nightly and stable release channels.
|
||||
|
||||
If you preferred to update your Netdata Agent manually, you can disable automatic updates by using the `--no-updates`
|
||||
option when you install or update Netdata using the [automatic one-line installation script](/packaging/installer/methods/kickstart.md).
|
||||
|
||||
```bash
|
||||
wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --no-updates
|
||||
```
|
||||
|
||||
With automatic updates disabled, you can choose exactly when and how you [update Netdata](/packaging/installer/UPDATE.md).
|
||||
|
||||
### Nightly vs. Stable Releases
|
||||
|
||||
**Nightly**: We create nightly builds every 24 hours. They contain fully-tested code that fixes bugs or security flaws,
|
||||
or introduces new features to Netdata. Every nightly release is a candidate for then becoming a stable release—when
|
||||
we're ready, we simply change the release tags on GitHub. That means nightly releases are stable and proven to function
|
||||
correctly in the vast majority of Netdata use cases. That's why nightly is the _best choice for most Netdata users_.
|
||||
|
||||
**Stable**: We create stable releases whenever we believe the code has reached a major milestone. Most often, stable
|
||||
releases correlate with the introduction of new, significant features. Stable releases might be a better choice for
|
||||
those who run Netdata in _mission-critical production systems_, as updates will come more infrequently, and only after
|
||||
the community helps fix any bugs that might have been introduced in previous releases.
|
||||
|
||||
**Pros of using nightly releases:**
|
||||
|
||||
- Get the latest features and bug fixes as soon as they're available
|
||||
- Receive security-related fixes immediately
|
||||
- Use stable, fully-tested code that's always improving
|
||||
- Leverage the same Netdata experience our community is using
|
||||
|
||||
**Pros of using stable releases:**
|
||||
|
||||
- Protect yourself from the rare instance when major bugs slip through our testing and negatively affect a Netdata installation
|
||||
- Retain more control over the Netdata version you use
|
||||
|
||||
### Anonymous statistics
|
||||
|
||||
Starting with v1.30, Netdata collects anonymous usage information by default and sends it to a self-hosted PostHog instance within the Netdata infrastructure. Read about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/netdata-agent/configuration/anonymous-telemetry-events.md) page.
|
||||
Netdata collects anonymous usage information by default and sends it to a self-hosted PostHog instance within the Netdata infrastructure. Read about the information collected on our [anonymous statistics](/docs/netdata-agent/configuration/anonymous-telemetry-events.md) documentation page.
|
||||
|
||||
The usage statistics are _vital_ for us, as we use them to discover bugs and prioritize new features. We thank you for
|
||||
_actively_ contributing to Netdata's future.
|
||||
|
||||
### Troubleshooting and known issues
|
||||
|
||||
We are tracking a few issues related to installation and packaging.
|
||||
|
||||
#### Installs on hosts without IPv4 connectivity
|
||||
|
||||
Our regular installation process requires access to a number of GitHub services that do not have IPv6 connectivity. As
|
||||
such, using the kickstart install script on such hosts generally does not work, and will typically fail with an
|
||||
error from cURL or wget about connection timeouts. You can check if your system is affected by this by attempting
|
||||
to connect to (or ping) `https://api.github.com/`. Failing to connect indicates that you are affected by this issue.
|
||||
|
||||
There are three potential workarounds for this:
|
||||
|
||||
1. You can configure your system with a proper IPv6 transition mechanism, such as NAT64. GitHub’s anachronisms
|
||||
affect many projects other than just Netdata, and there are unfortunately a number of other services out there
|
||||
that do not provide IPv6 connectivity, so taking this route is likely to save you time in the future as well.
|
||||
2. If you are using a system that we publish native packages for (see our [platform support
|
||||
policy](/docs/netdata-agent/versions-and-platforms.md) for more details),
|
||||
you can manually set up our native package repositories as outlined in our [native package install
|
||||
documentation](/packaging/installer/methods/packages.md). Our official
|
||||
package repositories do provide service over IPv6, so they work without issue on hosts without IPv4 connectivity.
|
||||
3. If neither of the above options work for you, you can still install using our [offline installation
|
||||
instructions](/packaging/installer/methods/offline.md), though
|
||||
do note that the offline install source must be prepared from a system with IPv4 connectivity.
|
||||
|
||||
#### Older distributions (Ubuntu 14.04, Debian 8, CentOS 6) and OpenSSL
|
||||
|
||||
If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS
|
||||
6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old
|
||||
versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation), which
|
||||
helps securely encrypt SSL connections.
|
||||
|
||||
If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit
|
||||
with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to
|
||||
man-in-the-middle attacks.
|
||||
|
||||
#### CentOS 6 and CentOS 8
|
||||
|
||||
To install the Agent on certain CentOS and RHEL systems, you must enable non-default repositories, such as EPEL or
|
||||
PowerTools, to gather hard dependencies. See the [CentOS 6](/packaging/installer/methods/manual.md#centos--rhel-6x) and
|
||||
[CentOS 8](/packaging/installer/methods/manual.md#centos--rhel-8x) sections for more information.
|
||||
|
||||
#### Access to file is not permitted
|
||||
|
||||
If you see an error similar to `Access to file is not permitted: /usr/share/netdata/web/index.html` when you try to
|
||||
visit the Agent dashboard at `http://NODE:19999`, you need to update Netdata's permissions to match those of your
|
||||
system.
|
||||
|
||||
Run `ls -la /usr/share/netdata/web/index.html` to find the file's permissions. You may need to change this path based on
|
||||
the error you're seeing in your browser. In the below example, the file is owned by the user `root` and the group
|
||||
`root`.
|
||||
|
||||
```bash
|
||||
ls -la /usr/share/netdata/web/index.html
|
||||
-rw-r--r--. 1 root root 89377 May 5 06:30 /usr/share/netdata/web/index.html
|
||||
```
|
||||
|
||||
These files need to have the same user and group used to install your netdata. Suppose you installed netdata with user
|
||||
`netdata` and group `netdata`, in this scenario you will need to run the following command to fix the error:
|
||||
|
||||
```bash
|
||||
# chown -R netdata:netdata /usr/share/netdata/web
|
||||
```
|
||||
|
||||
#### Multiple versions of OpenSSL
|
||||
|
||||
We've received reports from the community about issues with running the `kickstart.sh` script on systems that have both
|
||||
a distribution-installed version of OpenSSL and a manually-installed local version. The Agent's installer cannot handle
|
||||
both.
|
||||
|
||||
#### Clang compiler on Linux
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -106,8 +106,3 @@ The following configuration options are currently supported:
|
|||
- `NETDATA_UPDATER_JITTER`: Sets an upper limit in seconds on the random delay in the updater script when running as a scheduled task. This random delay helps avoid issues resulting from too many nodes trying to reconnect to the Cloud at the same time. The default value is 3600, which corresponds to one hour. Most users shouldn’t ever need to change this.
|
||||
- `NETDATA_MAJOR_VERSION_UPDATES`: If set to a value other than 0, then new major versions will be installed without user confirmation. Must be set to a non-zero value for automated updates to install new major versions.
|
||||
- `NETDATA_NO_SYSTEMD_JOURNAL`: If set to a value other than 0, skip attempting to install the `netdata-plugin-systemd-journal` package on supported systems on update. The updater will install this optional package by default on supported systems if this option is not set. It only affects systems using native packages.
|
||||
|
||||
### Updates on hosts without IPv4 connectivity
|
||||
|
||||
The update process outlined above suffers from the same issues that installing on hosts without IPv4 connectivity does, and requires similar workarounds.
|
||||
For more details, check [the explanation in our install documentation](/packaging/installer/README.md#installs-on-hosts-without-ipv4-connectivity).
|
||||
|
|
|
|||
|
|
@ -5,17 +5,29 @@ import TabItem from '@theme/TabItem';
|
|||
|
||||
# Install Netdata with kickstart.sh
|
||||
|
||||
 
|
||||
 
|
||||
|
||||
`kickstart.sh` is the recommended way of installing Netdata.
|
||||
**`kickstart.sh` is the recommended way of installing Netdata.**
|
||||
|
||||
This script works on all Linux distributions and macOS environments, by detecting the optimal method of installing Netdata directly to the operating system.
|
||||
|
||||
## What does `kickstart.sh` do?
|
||||
|
||||
The `kickstart.sh` script does the following after being downloaded and run using `sh`:
|
||||
|
||||
- Determines what platform you’re running on.
|
||||
- Checks for an existing installation, and if found updates that instead of creating a new installation.
|
||||
- Attempts to install Netdata using our [official native binary packages](/packaging/installer/methods/packages.md).
|
||||
- If there are no official native binary packages for your system (or installing that way failed), tries to install using a [static build of Netdata](/packaging/makeself/README.md) if one is available.
|
||||
- If no static build is available, installs required dependencies and then attempts to install by building Netdata locally (by downloading the sources and building them directly).
|
||||
- Installs `netdata-updater.sh` to `cron.daily`, so your Netdata installation will be updated with new nightly versions, unless you override that with an [optional parameter](#optional-parameters-to-alter-your-installation).
|
||||
- Prints a message whether installation succeeded or failed for QA purposes.
|
||||
|
||||
## Installation
|
||||
|
||||
> :bulb: Tip
|
||||
> **Tip**
|
||||
>
|
||||
> If you are unsure whether you want nightly or stable releases, read the [related section](/packaging/installer/README.md#nightly-vs-stable-releases) of our Documentation, detailing the pros and cons of each release type.
|
||||
> If you are unsure whether you want nightly or stable releases, read the [related section](/docs/netdata-agent/versions-and-platforms.md) of our Documentation, detailing the pros and cons of each release type.
|
||||
|
||||
To install Netdata, run the following as your normal user:
|
||||
|
||||
|
|
@ -32,146 +44,10 @@ To install Netdata, run the following as your normal user:
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> :bookmark_tabs: Note
|
||||
> **Note**
|
||||
>
|
||||
> If you plan to also connect the node to Netdata Cloud, make sure to replace `YOUR_CLAIM_TOKEN` with the claim token of your space,
|
||||
> and `YOUR_ROOM_ID` with the ID of the Room you are willing to connect the node to.
|
||||
|
||||
## Verify script integrity
|
||||
|
||||
To use `md5sum` to verify the integrity of the `kickstart.sh` script you will download using the one-line command above,
|
||||
run the following:
|
||||
|
||||
```bash
|
||||
[ "@KICKSTART_CHECKSUM@" = "$(curl -Ss https://get.netdata.cloud/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
|
||||
```
|
||||
|
||||
If the script is valid, this command will return `OK, VALID`.
|
||||
|
||||
## What does `kickstart.sh` do?
|
||||
|
||||
The `kickstart.sh` script does the following after being downloaded and run using `sh`:
|
||||
|
||||
- Determines what platform you are running on.
|
||||
- Checks for an existing installation, and if found updates that instead of creating a new install.
|
||||
- Attempts to install Netdata using our [official native binary packages](#native-packages).
|
||||
- If there are no official native binary packages for your system (or installing that way failed), tries to install
|
||||
using a [static build of Netdata](#static-builds) if one is available.
|
||||
- If no static build is available, installs required dependencies and then attempts to install by
|
||||
[building Netdata locally](#local-builds) (by downloading the sources and building them directly).
|
||||
- Installs `netdata-updater.sh` to `cron.daily`, so your Netdata installation will be updated with new nightly
|
||||
versions, unless you override that with an [optional parameter](#optional-parameters-to-alter-your-installation).
|
||||
- Prints a message whether installation succeeded or failed for QA purposes.
|
||||
|
||||
## Start stop or restart the Netdata Agent
|
||||
|
||||
You will most often need to _restart_ the Agent to load new or edited configuration files.
|
||||
|
||||
> **Note**
|
||||
> Stopping or restarting the Netdata Agent will cause gaps in stored metrics until the `netdata` process initiates collectors and the database engine.
|
||||
>
|
||||
> You do not need to restart the Netdata Agent between changes to health configuration files, see the relevant section on [reloading health configuration](/src/health/REFERENCE.md#reload-health-configuration).
|
||||
|
||||
### Using `systemctl` or `service`
|
||||
|
||||
This is the recommended way to start, stop, or restart the Netdata daemon.
|
||||
|
||||
- To **start** Netdata, run `sudo systemctl start netdata`.
|
||||
- To **stop** Netdata, run `sudo systemctl stop netdata`.
|
||||
- To **restart** Netdata, run `sudo systemctl restart netdata`.
|
||||
|
||||
If the above commands fail, or you know that you're using a non-systemd system, try using the `service` command:
|
||||
|
||||
- Starting: `sudo service netdata start`.
|
||||
- Stopping: `sudo service netdata stop`.
|
||||
- Restarting: `sudo service netdata restart`.
|
||||
|
||||
### Using the `netdata` command
|
||||
|
||||
Use the `netdata` command, typically located at `/usr/sbin/netdata`, to start the Netdata daemon:
|
||||
|
||||
```bash
|
||||
sudo netdata
|
||||
```
|
||||
|
||||
If you start the daemon this way, close it with `sudo killall netdata`.
|
||||
|
||||
### Shutdown using `netdatacli`
|
||||
|
||||
The Netdata Agent also comes with a [CLI tool](/src/cli/README.md) capable of performing shutdowns. Start the Agent back up using your preferred method listed above.
|
||||
|
||||
```bash
|
||||
sudo netdatacli shutdown-agent
|
||||
```
|
||||
|
||||
## Starting Netdata at boot
|
||||
|
||||
In the `system` directory you can find scripts and configurations for the
|
||||
various distros.
|
||||
|
||||
### systemd
|
||||
|
||||
The installer already installs `netdata.service` if it detects a systemd system.
|
||||
|
||||
To install `netdata.service` by hand, run:
|
||||
|
||||
```sh
|
||||
# stop Netdata
|
||||
killall netdata
|
||||
|
||||
# copy netdata.service to systemd
|
||||
cp system/netdata.service /etc/systemd/system/
|
||||
|
||||
# let systemd know there is a new service
|
||||
systemctl daemon-reload
|
||||
|
||||
# enable Netdata at boot
|
||||
systemctl enable netdata
|
||||
|
||||
# start Netdata
|
||||
systemctl start netdata
|
||||
```
|
||||
|
||||
### init.d
|
||||
|
||||
In the system directory you can find `netdata-lsb`. Copy it to the proper place according to your distribution's documentation. For Ubuntu, this can be done via running the following commands as root.
|
||||
|
||||
```sh
|
||||
# copy the Netdata startup file to /etc/init.d
|
||||
cp system/netdata-lsb /etc/init.d/netdata
|
||||
|
||||
# make sure it is executable
|
||||
chmod +x /etc/init.d/netdata
|
||||
|
||||
# enable it
|
||||
update-rc.d netdata defaults
|
||||
```
|
||||
|
||||
### openrc / Gentoo Linux
|
||||
|
||||
In the `system` directory you can find `netdata-openrc`. Copy it to the proper
|
||||
place according to your distribution documentation.
|
||||
|
||||
### CentOS / Red Hat Enterprise Linux
|
||||
|
||||
For older versions of RHEL/CentOS that don't have systemd, an init script is included in the system directory. This can be installed by running the following commands as root.
|
||||
|
||||
```sh
|
||||
# copy the Netdata startup file to /etc/init.d
|
||||
cp system/netdata-init-d /etc/init.d/netdata
|
||||
|
||||
# make sure it is executable
|
||||
chmod +x /etc/init.d/netdata
|
||||
|
||||
# enable it
|
||||
chkconfig --add netdata
|
||||
```
|
||||
|
||||
_There have been some recent work on the init script, see the following PR <https://github.com/netdata/netdata/pull/403>_
|
||||
|
||||
### Other operating systems
|
||||
|
||||
You can start Netdata by running it from `/etc/rc.local` or your system's equivalent.
|
||||
> and `YOUR_ROOM_ID` with the ID of the Room you’re willing to connect the node to.
|
||||
|
||||
## Optional parameters to alter your installation
|
||||
|
||||
|
|
@ -180,9 +56,9 @@ The `kickstart.sh` script accepts a number of optional parameters to control how
|
|||
### destination directory
|
||||
|
||||
- `--install-prefix`
|
||||
Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
|
||||
Specify a custom installation directory for local builds. If not provided, a default directory will be used based on your system.
|
||||
- `--old-install-prefix`
|
||||
Specify the custom local build's installation prefix that should be removed.
|
||||
Specify the previous custom installation directory to be removed during the update process.
|
||||
|
||||
### interactivity
|
||||
|
||||
|
|
@ -211,7 +87,7 @@ By default, the script installs the nightly channel of Netdata, providing you wi
|
|||
|
||||
### install type
|
||||
|
||||
By default the script will prefer native builds when they are available, and then static builds. It will fallback to build from source when all others are not available.
|
||||
By default, the script will prefer native builds when they’re available, and then static builds. It will fallback to build from source when all others aren’t available.
|
||||
|
||||
- `--native-only`
|
||||
Only install if native binary packages are available. It fails otherwise.
|
||||
|
|
@ -224,7 +100,7 @@ By default the script will prefer native builds when they are available, and the
|
|||
|
||||
### automatic updates
|
||||
|
||||
By default the script installs a cron job to automatically update Netdata to the latest version of the release channel used.
|
||||
By default, the script installs a cron job to automatically update Netdata to the latest version of the release channel used.
|
||||
|
||||
- `--auto-update`
|
||||
Enable automatic updates (this is the default).
|
||||
|
|
@ -233,10 +109,10 @@ By default the script installs a cron job to automatically update Netdata to the
|
|||
|
||||
### Netdata Cloud related options
|
||||
|
||||
By default, the kickstart script will provide a Netdata agent installation that can potentially communicate with Netdata Cloud, if of course the Netdata agent is further configured to do so.
|
||||
By default, the kickstart script will provide a Netdata agent installation that can potentially communicate with Netdata Cloud if the Netdata agent is further configured to do so.
|
||||
|
||||
- `--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. This will enable, connect and claim the Netdata agent, to Netdata Cloud.
|
||||
Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node after the installation. This will connect and claim the Netdata Agent to Netdata Cloud.
|
||||
- `--claim-url`
|
||||
Specify a URL to use when connecting to the cloud. Defaults to `https://app.netdata.cloud`. Use this option to change the Netdata Cloud URL to point to your Netdata Cloud installation.
|
||||
- `--claim-rooms`
|
||||
|
|
@ -244,7 +120,7 @@ By default, the kickstart script will provide a Netdata agent installation that
|
|||
- `--claim-proxy`
|
||||
Specify a proxy to use when connecting to the cloud in the form of `http://[user:pass@]host:ip` for an HTTP(S) proxy. See [connecting through a proxy](/src/claim/README.md#automatically-via-a-provisioning-system-or-the-command-line) for details.
|
||||
- `--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.
|
||||
If there is an existing installation, only try to claim it without attempting to update it. If there is no existing installation, install and claim Netdata normally.
|
||||
|
||||
### anonymous telemetry
|
||||
|
||||
|
|
@ -256,11 +132,11 @@ By default, the agent is sending anonymous telemetry data to help us take identi
|
|||
### reinstalling
|
||||
|
||||
- `--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.
|
||||
If there is an existing installation, reinstall it instead of trying to update it. If there is not an existing installation, 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 type of installation it is). If there is not an existing install, install Netdata normally.
|
||||
If there is an existing installation, reinstall it instead of trying to update it, even if doing so is known to potentially break things (for example, if we can’t detect what type 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.
|
||||
If there is an existing installation, uninstall it before trying to install Netdata. Fails if there is no existing installation.
|
||||
|
||||
### uninstall
|
||||
|
||||
|
|
@ -270,7 +146,7 @@ By default, the agent is sending anonymous telemetry data to help us take identi
|
|||
### other options
|
||||
|
||||
- `--dry-run`
|
||||
Show what the installer would do, but don’t actually do any of it.
|
||||
Simulates the installation process without making any changes to your system. This allows you to review the steps and potential impacts before proceeding with the actual installation.
|
||||
- `--dont-start-it`
|
||||
Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
|
||||
- `--distro-override`
|
||||
|
|
@ -286,43 +162,23 @@ The following options are mutually exclusive and specify special operations othe
|
|||
### environment variables
|
||||
|
||||
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):
|
||||
shouldn’t 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
|
||||
- `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). However, 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.
|
||||
|
||||
## Native packages
|
||||
## Verify script integrity
|
||||
|
||||
We publish [official DEB/RPM packages](/packaging/installer/methods/packages.md) for a number of common Linux distributions as part of our releases and nightly
|
||||
builds. These packages are available for 64-bit x86 systems. Depending on the distribution and release they may
|
||||
also be available for 32-bit x86, ARMv7, and AArch64 systems. If a native package is available, it will be used as the
|
||||
default installation method. This allows you to handle Netdata updates as part of your usual system update procedure.
|
||||
To use `md5sum` to verify the integrity of the `kickstart.sh` script you will download using the one-line command above,
|
||||
run the following:
|
||||
|
||||
If you want to enforce the usage of native packages and have the installer return a failure if they are not available,
|
||||
you can do so by adding `--native-only` to the options you pass to the installer.
|
||||
```bash
|
||||
[ "@KICKSTART_CHECKSUM@" = "$(curl -Ss https://get.netdata.cloud/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
|
||||
```
|
||||
|
||||
## Static builds
|
||||
|
||||
We publish pre-built [static builds](/packaging/makeself/README.md) of Netdata for Linux systems. Currently, these are published for 64-bit x86, ARMv7,
|
||||
AArch64, and POWER8+ hardware. These static builds are able to operate in a mostly self-contained manner and only
|
||||
require a POSIX compliant shell and a supported init system. These static builds install under `/opt/netdata`. If
|
||||
you are on a platform which we provide static builds for but do not provide native packages for, a static build
|
||||
will be used by default for installation.
|
||||
|
||||
If you want to enforce the usage of a static build and have the installer return a failure if one is not available,
|
||||
you can do so by adding `--static-only` to the options you pass to the installer.
|
||||
|
||||
## Local builds
|
||||
|
||||
For systems which do not have available native packages or static builds, we support building Netdata locally on
|
||||
the system it will be installed on. When using this approach, the installer will attempt to install any required
|
||||
dependencies for building Netdata, though this may not always work correctly.
|
||||
|
||||
If you want to enforce the usage of a local build (perhaps because you require a custom installation prefix,
|
||||
which is not supported with native packages or static builds), you can do so by adding `--build-only` to the
|
||||
options you pass to the installer.
|
||||
If the script is valid, this command will return `OK, VALID`.
|
||||
|
|
|
|||
13
packaging/installer/methods/no_ipv4.md
Normal file
13
packaging/installer/methods/no_ipv4.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
# Installing on hosts without IPv4 connectivity
|
||||
|
||||
Our regular installation process requires access to a number of GitHub services that do not have IPv6 connectivity.
|
||||
|
||||
As such, using the kickstart install script on such hosts generally does not work, and will typically fail with an error from cURL or wget about connection timeouts.
|
||||
|
||||
You can check if your system is affected by this by attempting to connect to (or ping) `https://api.github.com/`. Failing to connect indicates that this issue affects you.
|
||||
|
||||
There are three potential workarounds for this:
|
||||
|
||||
1. You can configure your system with a proper IPv6 transition mechanism, such as NAT64. GitHub’s anachronisms affect many projects other than just Netdata. There are, unfortunately, a number of other services out there that do not provide IPv6 connectivity, so taking this route is likely to save you time in the future as well.
|
||||
2. If you are using a system that we publish native packages for (see our [platform support policy](/docs/netdata-agent/versions-and-platforms.md) for more details), you can manually set up our native package repositories as outlined in our [native package install documentation](/packaging/installer/methods/packages.md). Our official package repositories do provide service over IPv6, so they work without issue on hosts without IPv4 connectivity.
|
||||
3. If neither of the above options work for you, you can still install using our [offline installation instructions](/packaging/installer/methods/offline.md), though do note that the offline install source must be prepared from a system with IPv4 connectivity.
|
||||
|
|
@ -43,7 +43,6 @@ Once you have prepared the offline install source, you need to copy the offline
|
|||
target system. This can be done in any manner you like, as long as filenames are not changed.
|
||||
|
||||
After copying the files, simply run the `install.sh` script located in the
|
||||
offline install source directory. It accepts all the [same options as the kickstart
|
||||
script](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) for further
|
||||
offline install source directory. It accepts all the [same options as the kickstart script](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) for further
|
||||
customization of the installation, though it will default to not enabling automatic updates (as they are not
|
||||
supported on offline installs).
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Netdata Agents can be connected to Netdata Cloud by creating the file `/etc/netd
|
|||
insecure = Either yes or no (optional)
|
||||
```
|
||||
|
||||
- `proxy` can get anything libcurl accepts as proxy, or the keywords `none` and `env`. `none` or just empty disables proxy configuration, while `env` instructs libcurl to use the environment for determining proxy configuration (usually the environment variable `https_proxy`).
|
||||
- `proxy` can get anything libcurl accepts as a proxy, or the `none` and `env` keywords. `none` (or just an empty value) disables proxy configuration, while `env` tells libcurl to use the environment to determine the proxy configuration (usually the `https_proxy` environment variable).
|
||||
- `insecure` is a boolean (either `yes`, or `no`) and when set to `yes` it instructs libcurl to disable host verification.
|
||||
|
||||
example:
|
||||
|
|
@ -73,8 +73,7 @@ example:
|
|||
If the agent is already running, you can either run `netdatacli reload-claiming-state` or restart the agent.
|
||||
Otherwise, the agent will be claimed when it starts.
|
||||
|
||||
If claiming fails for whatever reason, daemon.log will log the reason (search for `CLAIM`),
|
||||
and also `http://ip:19999/api/v2/info` would also state the reason at the `cloud` section of the response.
|
||||
If the claiming process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v2/info`.
|
||||
|
||||
#### Automatically, via environment variables
|
||||
|
||||
|
|
@ -88,8 +87,7 @@ Netdata will use the following environment variables:
|
|||
|
||||
The `NETDATA_CLAIM_TOKEN` alone is enough for triggering the claiming process.
|
||||
|
||||
If claiming fails for whatever reason, daemon.log will log the reason (search for `CLAIM`),
|
||||
and also `http://ip:19999/api/v2/info` would also state the reason at the `cloud` section of the response.
|
||||
If the claiming process fails, the reason will be logged in daemon.log (search for "CLAIM") and the `cloud` section of `http://ip:19999/api/v2/info`.
|
||||
|
||||
## Reconnect
|
||||
|
||||
|
|
@ -111,7 +109,7 @@ still be able to see this node in your Rooms in an **unreachable** state.
|
|||
|
||||
### Docker based installations
|
||||
|
||||
To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps:
|
||||
To remove a node from your Space in Netdata Cloud and connect it to another Space, follow these steps:
|
||||
|
||||
1. Enter the running container you wish to remove from your Space
|
||||
|
||||
|
|
@ -154,19 +152,22 @@ To remove a node from you Space in Netdata Cloud, and connect it to another Spac
|
|||
```
|
||||
|
||||
4. Finally, go to your new Space, copy the installation command with the new claim token and run it.
|
||||
If you are using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token.
|
||||
If you’re using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token.
|
||||
The node should now appear online in that Space.
|
||||
|
||||
## Regenerate Claiming Token
|
||||
|
||||
If in case of some security reason, or other, you need to revoke your previous claiming token and generate a new one you
|
||||
can achieve that from the Netdata Cloud UI.
|
||||
There may be situations where you need to revoke your previous Netdata Cloud claiming token and generate a new one for security reasons. Here's how to do it:
|
||||
|
||||
On any screen where you see the connect the node to Netdata Cloud command you'll see above it, next to
|
||||
the [updates channel](/docs/netdata-agent/versions-and-platforms.md), a
|
||||
button to **Regenerate token**. This action will invalidate your previous token and generate a fresh new one.
|
||||
**Requirements**:
|
||||
|
||||
Only the administrators of a Space in Netdata Cloud can trigger this action.
|
||||
- Only administrators of Space in Netdata Cloud can regenerate tokens.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Navigate to any screen within the Netdata Cloud UI where you see the "Connect the node to Netdata Cloud" command.
|
||||
2. Look above this command, near the [Updates channel](/docs/netdata-agent/versions-and-platforms.md). You should see a button that says "Regenerate token."
|
||||
3. Click the "Regenerate token" button. This action will invalidate your previous token and generate a new one.
|
||||
|
||||
## Troubleshoot
|
||||
|
||||
|
|
@ -202,33 +203,32 @@ installed Netdata using an unsupported package.
|
|||
|
||||
> **Note**
|
||||
>
|
||||
> If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution,
|
||||
> If you’re 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](/packaging/installer/methods/kickstart.md).
|
||||
|
||||
### kickstart: Failed to write new machine GUID
|
||||
|
||||
If you run the kickstart script but don't have privileges required for the actions done on the connecting to Netdata
|
||||
Cloud process you will get the following error:
|
||||
You might encounter this error if you run the Netdata kickstart script without sufficient permissions:
|
||||
|
||||
```bash
|
||||
Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id.
|
||||
```
|
||||
|
||||
For a successful execution you will need to run the script with root privileges or run it with the user that is running
|
||||
the Agent.
|
||||
To resolve this issue, you have two options:
|
||||
|
||||
### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)
|
||||
1. Run the script with root privileges.
|
||||
2. Run the script with the user that runs the Netdata Agent.
|
||||
|
||||
### Connecting to Cloud on older distributions (Ubuntu 14.04, Debian 8, CentOS 6)
|
||||
|
||||
If you're running an older Linux distribution or one that has reached EOL, such as Ubuntu 14.04 LTS, Debian 8, or CentOS
|
||||
6, your Agent may not be able to securely connect to Netdata Cloud due to an outdated version of OpenSSL. These old
|
||||
versions of OpenSSL cannot perform [hostname validation](https://wiki.openssl.org/index.php/Hostname_validation),
|
||||
which helps securely encrypt SSL connections.
|
||||
|
||||
We recommend you reinstall Netdata with
|
||||
a [static build](/packaging/installer/methods/kickstart.md#static-builds),
|
||||
which uses an up-to-date version of OpenSSL with hostname validation enabled.
|
||||
We recommend you reinstall Netdata with a [static build](/packaging/installer/methods/kickstart.md#install-type), which uses an up-to-date version of OpenSSL with hostname validation enabled.
|
||||
|
||||
If you choose to continue using the outdated version of OpenSSL, your node will still connect to Netdata Cloud, albeit
|
||||
with hostname verification disabled. Without verification, your Netdata Cloud connection could be vulnerable to
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ modules:
|
|||
sudo ./edit-config netdata.conf
|
||||
```
|
||||
|
||||
Change the value of the `perf` setting to `yes` in the `[plugins]` section. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system.
|
||||
Change the value of the `perf` setting to `yes` in the `[plugins]` section. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system.
|
||||
configuration:
|
||||
file:
|
||||
name: "netdata.conf"
|
||||
|
|
|
|||
|
|
@ -91,7 +91,7 @@ cd /etc/netdata # Replace this path with your Netdata config directory, if dif
|
|||
sudo ./edit-config python.d.conf
|
||||
```
|
||||
|
||||
Change the value of the `go_expvar` setting to `yes`. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system.
|
||||
Change the value of the `go_expvar` setting to `yes`. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system.
|
||||
|
||||
|
||||
#### Sample `expvar` usage in a Go application
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ modules:
|
|||
sudo ./edit-config python.d.conf
|
||||
```
|
||||
|
||||
Change the value of the `go_expvar` setting to `yes`. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system.
|
||||
Change the value of the `go_expvar` setting to `yes`. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system.
|
||||
- title: "Sample `expvar` usage in a Go application"
|
||||
description: |
|
||||
The `expvar` package exposes metrics over HTTP and is very easy to use.
|
||||
|
|
|
|||
|
|
@ -964,7 +964,7 @@ Note that Netdata will report the rate for metrics and counters, even if k6 or a
|
|||
sends an _absolute_ number. For example, k6 sends absolute HTTP requests with `http_reqs`,
|
||||
but Netdata visualizes that in `requests/second`.
|
||||
|
||||
To enable this StatsD configuration, [restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation).
|
||||
To enable this StatsD configuration, [restart Netdata](/docs/netdata-agent/start-stop-restart.md).
|
||||
|
||||
### Final touches
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ comment on settings it does not currently use.
|
|||
|
||||
## Applying changes
|
||||
|
||||
After `netdata.conf` has been modified, Netdata needs to be [restarted](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for
|
||||
After `netdata.conf` has been modified, Netdata needs to be [restarted](/docs/netdata-agent/start-stop-restart.md) for
|
||||
changes to apply:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The default script is `alarm-notify.sh`.
|
|||
> - To edit configuration files in a safe way, we provide the [`edit config` script](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)located in your [Netdata config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory) (typically is `/etc/netdata`) that creates the proper file and opens it in an editor automatically.
|
||||
> Note that to run the script you need to be inside your Netdata config directory.
|
||||
>
|
||||
> - Please also note that after most configuration changes you will need to [restart the Agent](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for the changes to take effect.
|
||||
> - Please also note that after most configuration changes you will need to [restart the Agent](/docs/netdata-agent/start-stop-restart.md) for the changes to take effect.
|
||||
>
|
||||
> It is recommended to use this way for configuring Netdata.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue