From 2e85f9325a797977eea9dfea0a925775ddd211d9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Feb 2021 12:49:00 +0100 Subject: Merging upstream version 1.29.0. Signed-off-by: Daniel Baumann --- packaging/installer/methods/alpine.md | 36 +++ packaging/installer/methods/cloud-providers.md | 130 +++++++++++ packaging/installer/methods/freebsd.md | 108 +++++++++ packaging/installer/methods/freenas.md | 24 ++ packaging/installer/methods/kickstart-64.md | 96 ++++++++ packaging/installer/methods/kickstart.md | 79 +++++++ packaging/installer/methods/kubernetes.md | 209 ++++++++++++++++++ packaging/installer/methods/macos.md | 90 ++++++++ packaging/installer/methods/manual.md | 229 +++++++++++++++++++ packaging/installer/methods/offline.md | 90 ++++++++ packaging/installer/methods/packages.md | 48 ++++ packaging/installer/methods/pfsense.md | 84 +++++++ packaging/installer/methods/source.md | 291 +++++++++++++++++++++++++ packaging/installer/methods/synology.md | 52 +++++ 14 files changed, 1566 insertions(+) create mode 100644 packaging/installer/methods/alpine.md create mode 100644 packaging/installer/methods/cloud-providers.md create mode 100644 packaging/installer/methods/freebsd.md create mode 100644 packaging/installer/methods/freenas.md create mode 100644 packaging/installer/methods/kickstart-64.md create mode 100644 packaging/installer/methods/kickstart.md create mode 100644 packaging/installer/methods/kubernetes.md create mode 100644 packaging/installer/methods/macos.md create mode 100644 packaging/installer/methods/manual.md create mode 100644 packaging/installer/methods/offline.md create mode 100644 packaging/installer/methods/packages.md create mode 100644 packaging/installer/methods/pfsense.md create mode 100644 packaging/installer/methods/source.md create mode 100644 packaging/installer/methods/synology.md (limited to 'packaging/installer/methods') diff --git a/packaging/installer/methods/alpine.md b/packaging/installer/methods/alpine.md new file mode 100644 index 000000000..fb448959a --- /dev/null +++ b/packaging/installer/methods/alpine.md @@ -0,0 +1,36 @@ + + +# Install Netdata on Alpine 3.x + +Execute these commands to install Netdata in Alpine Linux 3.x: + +```sh +# install required packages +apk add alpine-sdk bash curl libuv-dev zlib-dev util-linux-dev libmnl-dev gcc make git autoconf automake pkgconfig python logrotate + +# if you plan to run node.js Netdata plugins +apk add nodejs + +# download Netdata - the directory 'netdata' will be created +git clone https://github.com/netdata/netdata.git --depth=100 +cd netdata + +# build it, install it, start it +./netdata-installer.sh + +# make Netdata start at boot +echo -e "#!/usr/bin/env bash\n/usr/sbin/netdata" >/etc/local.d/netdata.start +chmod 755 /etc/local.d/netdata.start + +# make Netdata stop at shutdown +echo -e "#!/usr/bin/env bash\nkillall netdata" >/etc/local.d/netdata.stop +chmod 755 /etc/local.d/netdata.stop + +# enable the local service to start automatically +rc-update add local +``` + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Falpine&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/cloud-providers.md b/packaging/installer/methods/cloud-providers.md new file mode 100644 index 000000000..943a649b6 --- /dev/null +++ b/packaging/installer/methods/cloud-providers.md @@ -0,0 +1,130 @@ + + +# Install Netdata on cloud providers + +Netdata is fully compatible with popular cloud providers like Google Cloud Platform (GCP), Amazon Web Services (AWS), +Azure, and others. You can install Netdata on cloud instances to monitor the apps/services running there, or use +multiple instances in a [parent-child streaming](/streaming/README.md) configuration. + +In some cases, using Netdata on these cloud providers requires unique installation or configuration steps. This page +aims to document some of those steps for popular cloud providers. + +> This document is a work-in-progress! If you find new issues specific to a cloud provider, or would like to help +> clarify the correct workaround, please [create an +> issue](https://github.com/netdata/netdata/issues/new?labels=feature+request,+needs+triage&template=feature_request.md) +> with your process and instructions on using the provider's interface to complete the workaround. + +- [Recommended installation methods for cloud providers](#recommended-installation-methods-for-cloud-providers) +- [Post-installation configuration](#post-installation-configuration) + - [Add a firewall rule to access Netdata's dashboard](#add-a-firewall-rule-to-access-netdatas-dashboard) + +## Recommended installation methods for cloud providers + +The best installation method depends on the instance's operating system, distribution, and version. For Linux instances, +we recommend either the [`kickstart.sh` automatic installation script](kickstart.md) or [.deb/.rpm +packages](packages.md). + +To see the full list of approved methods for each operating system/version we support, see our [distribution +matrix](../../DISTRIBUTIONS.md). That table will guide you to the various supported methods for your cloud instance. + +If you have issues with Netdata after installation, look to the sections below to find the issue you're experiencing, +followed by the solution for your provider. + +## Post-installation configuration + +Some cloud providers require you take additional steps to properly configure your instance or its networking to access +all of Netdata's features. + +### Add a firewall rule to access Netdata's dashboard + +If you cannot access Netdata's dashboard on your cloud instance via `http://HOST:19999`, and instead get an error page +from your browser that says, "This site can't be reached" (Chrome) or "Unable to connect" (Firefox), you may need to +configure your cloud provider's firewall. + +Cloud providers often create network-level firewalls that run separately from the instance itself. Both AWS and Google +Cloud Platform calls them Virtual Private Cloud (VPC) networks. These firewalls can apply even if you've disabled +firewalls on the instance itself. Because you can modify these firewalls only via the cloud provider's web interface, +it's easy to overlook them when trying to configure and access Netdata's dashboard. + +You can often confirm a firewall issue by querying the dashboard while connected to the instance via SSH: `curl +http://localhost:19999/api/v1/info`. If you see JSON output, Netdata is running properly. If you try the same `curl` +command from a remote system, and it fails, it's likely that a firewall is blocking your requests. + +Another option is to put Netdata behind web server, which will proxy requests through standard HTTP/HTTPS ports +(80/443), which are likely already open on your instance. We have a number of guides available: + +- [Apache](/docs/Running-behind-apache.md) +- [Nginx](/docs/Running-behind-nginx.md) +- [Caddy](/docs/Running-behind-caddy.md) +- [HAProxy](/docs/Running-behind-haproxy.md) +- [lighttpd](/docs/Running-behind-lighttpd.md) + +The next few sections outline how to add firewall rules to GCP, AWS, and Azure instances. + +#### Google Cloud Platform (GCP) + +To add a firewall rule, go to the [Firewall rules page](https://console.cloud.google.com/networking/firewalls/list) and +click **Create firewall rule**. + +The following configuration has previously worked for Netdata running on GCP instances +([see #7786](https://github.com/netdata/netdata/issues/7786)): + +```conf +Name: +Type: Ingress +Targets: +Filters: 0.0.0.0/0 +Protocols/ports: 19999 +Action: allow +Priority: 1000 +``` + +Read GCP's [firewall documentation](https://cloud.google.com/vpc/docs/using-firewalls) for specific instructions on how +to create a new firewall rule. + +#### Amazon Web Services (AWS) / EC2 + +Sign in to the [AWS console](https://console.aws.amazon.com/) and navigate to the EC2 dashboard. Click on the **Security +Groups** link in the navigation, beneath the **Network & Security** heading. Find the Security Group your instance +belongs to, and either right-click on it or click the **Actions** button above to see a dropdown menu with **Edit +inbound rules**. + +Add a new rule with the following options: + +```conf +Type: Custom TCP +Protocol: TCP +Port Range: 19999 +Source: Anywhere +Description: Netdata +``` + +You can also choose **My IP** as the source if you prefer. + +Click **Save** to apply your new inbound firewall rule. + +#### Azure + +Sign in to the [Azure portal](https://portal.azure.com) and open the virtual machine running Netdata. Click on the +**Networking** link beneath the **Settings** header, then click on the **Add inbound security rule** button. + +Add a new rule with the following options: + +```conf +Source: Any +Source port ranges: 19999 +Destination: Any +Destination port randes: 19999 +Protocol: TCP +Action: Allow +Priority: 310 +Name: Netdata +``` + +Click **Add** to apply your new inbound security rule. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fcloud-providers&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/freebsd.md b/packaging/installer/methods/freebsd.md new file mode 100644 index 000000000..e2af41754 --- /dev/null +++ b/packaging/installer/methods/freebsd.md @@ -0,0 +1,108 @@ + + +# Install Netdata on FreeBSD + +> 💡 This document is maintained by Netdata's community, and may not be completely up-to-date. Please double-check the +> details of the installation process, such as version numbers for downloadable packages, before proceeding. +> +> You can help improve this document by [submitting a +> PR](https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freebsd.md) with your recommended +> improvements or changes. Thank you! + +## Install latest version + +This is how to install the latest Netdata version on FreeBSD: + +Install required packages (**need root permission**): + +```sh +pkg install bash e2fsprogs-libuuid git curl autoconf automake pkgconf pidof Judy liblz4 libuv json-c cmake gmake +``` + +Download Netdata: + +```sh +fetch https://github.com/netdata/netdata/releases/download/v1.26.0/netdata-v1.26.0.tar.gz +``` + +> ⚠️ Verify the latest version by either navigating to [Netdata's latest +> release](https://github.com/netdata/netdata/releases/latest) or using `curl`: +> +> ```bash +> basename $(curl -Ls -o /dev/null -w %{url_effective} https://github.com/netdata/netdata/releases/latest) +> ``` + +Unzip the downloaded file: + +```sh +gunzip netdata*.tar.gz && tar xf netdata*.tar && rm -rf netdata*.tar +``` + +Install Netdata in `/opt/netdata`. If you want to enable automatic updates, add `--auto-update` or `-u` to install `netdata-updater` in `cron` (**need root permission**): + +```sh +cd netdata-v* && ./netdata-installer.sh --install /opt && cp /opt/netdata/usr/sbin/netdata-claim.sh /usr/sbin/ +``` + +You also need to enable the `netdata` service in `/etc/rc.conf`: + +```sh +sysrc netdata_enable="YES" +``` + +Finally, and very importantly, update Netdata using the script provided by the Netdata team (**need root permission**): + +```sh +cd /opt/netdata/usr/libexec/netdata/ && ./netdata-updater.sh +``` + +You can now access the Netdata dashboard by navigating to `http://NODE:19999`, replacing `NODE` with the IP address or hostname of your system. + +![image](https://user-images.githubusercontent.com/2662304/48304090-fd384080-e51b-11e8-80ae-eecb03118dda.png) + +From Netdata v1.12 and above, anonymous usage information is collected by default and sent to Google Analytics. To read +more about the information collected and how to opt-out, check the [anonymous statistics +page](/docs/anonymous-statistics.md). + +## Updating the Agent on FreeBSD +If you have not passed the `--auto-update` or `-u` parameter for the installer to enable automatic updating, repeat the last step to update Netdata whenever a new version becomes available. +The `netdata-updater.sh` script will update your Agent. + +## Optional parameters to alter your installation +| parameters | Description | +|:-----:|-----------| +|`--install `| Install netdata in `.` Ex: `--install /opt` will put netdata in `/opt/netdata`| +| `--dont-start-it` | Do not (re)start netdata after installation| +| `--dont-wait` | Run installation in non-interactive mode| +| `--auto-update` or `-u` | Install netdata-updater in cron to update netdata automatically once per day| +| `--stable-channel` | Use packages from GitHub release pages instead of GCS (nightly updates). This results in less frequent updates| +| `--nightly-channel` | Use most recent nightly updates instead of GitHub releases. This results in more frequent updates| +| `--disable-go` | Disable installation of go.d.plugin| +| `--disable-ebpf` | Disable eBPF Kernel plugin (Default: enabled)| +| `--disable-cloud` | Disable all Netdata Cloud functionality| +| `--require-cloud` | Fail the install if it can't build Netdata Cloud support| +| `--enable-plugin-freeipmi` | Enable the FreeIPMI plugin. Default: enable it when libipmimonitoring is available| +| `--disable-plugin-freeipmi` | Enable the FreeIPMI plugin| +| `--disable-https` | Explicitly disable TLS support| +| `--disable-dbengine` | Explicitly disable DB engine support| +| `--enable-plugin-nfacct` | Enable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available| +| `--disable-plugin-nfacct` | Disable nfacct plugin. Default: enable it when libmnl and libnetfilter_acct are available| +| `--enable-plugin-xenstat` | Enable the xenstat plugin. Default: enable it when libxenstat and libyajl are available| +| `--disable-plugin-xenstat` | Disable the xenstat plugin| +| `--enable-backend-kinesis` | Enable AWS Kinesis backend. Default: enable it when libaws_cpp_sdk_kinesis and libraries (it depends on are available)| +| `--disable-backend-kinesis` | Disable AWS Kinesis backend. Default: enable it when libaws_cpp_sdk_kinesis and libraries (it depends on are available)| +| `--enable-backend-prometheus-remote-write` | Enable Prometheus remote write backend. Default: enable it when libprotobuf and libsnappy are available| +| `--disable-backend-prometheus-remote-write` | Disable Prometheus remote write backend. Default: enable it when libprotobuf and libsnappy are available| +| `--enable-backend-mongodb` | Enable MongoDB backend. Default: enable it when libmongoc is available| +| `--disable-backend-mongodb` | Disable MongoDB backend| +| `--enable-lto` | Enable Link-Time-Optimization. Default: enabled| +| `--disable-lto` | Disable Link-Time-Optimization. Default: enabled| +| `--disable-x86-sse` | Disable SSE instructions. By default SSE optimizations are enabled| +| `--zlib-is-really-here` or `--libs-are-really-here` | If you get errors about missing zlib or libuuid but you know it is available, you might have a broken pkg-config. Use this option to proceed without checking pkg-config| +|`--disable-telemetry` | Use this flag to opt-out from our anonymous telemetry program. (DO_NOT_TRACK=1)| + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Ffreebsd&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/freenas.md b/packaging/installer/methods/freenas.md new file mode 100644 index 000000000..a0dafdff8 --- /dev/null +++ b/packaging/installer/methods/freenas.md @@ -0,0 +1,24 @@ + + +# Install Netdata on FreeNAS + +On FreeNAS-Corral-RELEASE (>=10.0.3 and <11.3), Netdata is pre-installed. + +To use Netdata, the service will need to be enabled and started from the FreeNAS [CLI](https://github.com/freenas/cli). + +To enable the Netdata service: + +```sh +service netdata config set enable=true +``` + +To start the Netdata service: + +```sh +service netdata start +``` + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Ffreenas&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/kickstart-64.md b/packaging/installer/methods/kickstart-64.md new file mode 100644 index 000000000..120cc9e11 --- /dev/null +++ b/packaging/installer/methods/kickstart-64.md @@ -0,0 +1,96 @@ + + +# Install Netdata with kickstart-static64.sh + +![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart64&group=sum&after=-3600&label=last+hour&units=installations&value_color=orange&precision=0) ![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart64&group=sum&after=-86400&label=today&units=installations&precision=0) + +This page covers detailed instructions on using and configuring the installation script named `kickstart-static64.sh`. + +This method uses a pre-compiled static binary to install Netdata on any Intel/AMD 64bit Linux system and on any Linux +distribution, even those with a broken or unsupported package manager. + +To install Netdata from a static binary package, including all dependencies required to connect to Netdata Cloud, and +get _automatic nightly updates_, run the following as your normal user: + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) +``` + +> This script installs Netdata at `/opt/netdata`. + +> See our [installation guide](/packaging/installer/README.md) for details about [automatic +> updates](/packaging/installer/README.md#automatic-updates) or [nightly vs. stable +> releases](/packaging/installer/README.md#nightly-vs-stable-releases). + +## What does `kickstart-static64.sh` do? + +The `kickstart.sh` script does the following after being downloaded and run: + +- Checks to see if there is an existing installation, and if there is updates that in preference to reinstalling. +- Downloads the latest Netdata binary from the [binary-packages](https://github.com/netdata/binary-packages) + repository. You can also run any of these `.run` files with [makeself](https://github.com/megastep/makeself). +- Installs Netdata by running `./netdata-installer.sh` from the source tree, including any options you might have + added. +- Installs `netdata-updater.sh` to `cron.daily` to enable automatic updates, unless you added the `--no-updates` + option. +- Prints a message about whether the installation succeeded for failed for QA purposes. + +If your shell fails to handle the above one-liner, you can download and run the `kickstart-static64.sh` script manually. + +```sh +# download the script with curl +curl https://my-netdata.io/kickstart-static64.sh >/tmp/kickstart-static64.sh + +# or, download the script with wget +wget -O /tmp/kickstart-static64.sh https://my-netdata.io/kickstart-static64.sh + +# run the downloaded script (any sh is fine, no need for bash) +sh /tmp/kickstart-static64.sh +``` + +## Optional parameters to alter your installation + +The `kickstart-static64.sh` script passes all its parameters to `netdata-installer.sh`, which you can use to customize +your installation. Here are a few important parameters: + +- `--dont-wait`: Enable automated installs by not prompting for permission to install any required packages. +- `--dont-start-it`: Prevent the installer from starting Netdata automatically. +- `--stable-channel`: Automatically update only on the release of new major versions. +- `--nightly-channel`: Automatically update on every new nightly build. +- `--disable-telemetry`: Opt-out of [anonymous statistics](/docs/anonymous-statistics.md) we use to make + Netdata better. +- `--no-updates`: Prevent automatic updates of any kind. +- `--reinstall`: If an existing installation is detected, reinstall instead of attempting to update it. Note + that this cannot be used to switch between installation types. +- `--local-files`: Used for [offline installations](/packaging/installer/methods/offline.md). Pass four file paths: + the Netdata tarball, the checksum file, the go.d plugin tarball, and the go.d plugin config tarball, to force + kickstart run the process using those files. This option conflicts with the `--stable-channel` option. If you set + this _and_ `--stable-channel`, Netdata will use the local files. + +## Verify script integrity + +To use `md5sum` to verify the integrity of the `kickstart-static64.sh` script you will download using the one-line +command above, run the following: + +```bash +[ "047c86a7c8905955bee39b6980a28e30" = "$(curl -Ss https://my-netdata.io/kickstart-static64.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID" +``` + +If the script is valid, this command will return `OK, VALID`. + +## What's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fkickstart-64&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/kickstart.md b/packaging/installer/methods/kickstart.md new file mode 100644 index 000000000..f825f808e --- /dev/null +++ b/packaging/installer/methods/kickstart.md @@ -0,0 +1,79 @@ + + +# Install Netdata with kickstart.sh + +![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-3600&label=last+hour&units=installations&value_color=orange&precision=0) ![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-86400&label=today&units=installations&precision=0) + +This page covers detailed instructions on using and configuring the automatic one-line installation script named +`kickstart.sh`. + +This method is fully automatic on all Linux distributions. To install Netdata from source, including all dependencies +required to connect to Netdata Cloud, and get _automatic nightly updates_, run the following as your normal user: + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart.sh) +``` + +> See our [installation guide](../README.md) for details about [automatic updates](../README.md#automatic-updates) or +> [nightly vs. stable releases](../README.md#nightly-vs-stable-releases). + +## What does `kickstart.sh` do? + +The `kickstart.sh` script does the following after being downloaded and run using `bash`: + +- Detects the Linux distribution and **installs the required system packages** for building Netdata. Unless you added + the `--dont-wait` option, it will ask for your permission first. +- Checks for an existing installation, and if found updates that instead of creating a new install. +- Downloads the latest Netdata source tree to `/usr/src/netdata.git`. +- Installs Netdata by running `./netdata-installer.sh` from the source tree, using any [optional + parameters](#optional-parameters-to-alter-your-installation) you have specified. +- 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. + +## Optional parameters to alter your installation + +The `kickstart.sh` script passes all its parameters to `netdata-installer.sh`, which you can use to customize your +installation. Here are a few important parameters: + +- `--dont-wait`: Enable automated installs by not prompting for permission to install any required packages. +- `--dont-start-it`: Prevent the installer from starting Netdata automatically. +- `--stable-channel`: Automatically update only on the release of new major versions. +- `--nightly-channel`: Automatically update on every new nightly build. +- `--disable-telemetry`: Opt-out of [anonymous statistics](/docs/anonymous-statistics.md) we use to make + Netdata better. +- `--no-updates`: Prevent automatic updates of any kind. +- `--reinstall`: If an existing install is detected, reinstall instead of trying to update it. Note that this + cannot be used to change installation types. +- `--local-files`: Used for [offline installations](offline.md). Pass four file paths: the Netdata + tarball, the checksum file, the go.d plugin tarball, and the go.d plugin config tarball, to force kickstart run the + process using those files. This option conflicts with the `--stable-channel` option. If you set this _and_ + `--stable-channel`, Netdata will use the local files. + +## 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 +[ "8df7a45b2abb336c84507b7c107bcba3" = "$(curl -Ss https://my-netdata.io/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's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fkickstart&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/kubernetes.md b/packaging/installer/methods/kubernetes.md new file mode 100644 index 000000000..3e85928e9 --- /dev/null +++ b/packaging/installer/methods/kubernetes.md @@ -0,0 +1,209 @@ + + +# Install Netdata on a Kubernetes cluster + +This document details how to install Netdata on an existing Kubernetes (k8s) cluster. By following these directions, you +will use Netdata's [Helm chart](https://github.com/netdata/helmchart) to bootstrap a Netdata deployment on your cluster. +The Helm chart installs one parent pod for storing metrics and managing alarm notifications plus an additional child pod +for every node in the cluster. + +Each child pod will collect metrics from the node it runs on, in addition to [compatible +applications](https://github.com/netdata/helmchart#service-discovery-and-supported-services), plus any endpoints covered +by our [generic Prometheus collector](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/prometheus), +via [service discovery](https://github.com/netdata/agent-service-discovery/). Each child pod will also collect +[cgroups](/collectors/cgroups.plugin/README.md), +[Kubelet](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubelet), and +[kube-proxy](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/k8s_kubeproxy) metrics from its node. + +To install Netdata on a Kubernetes cluster, you need: + +- A working cluster running Kubernetes v1.9 or newer. +- The [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) command line tool, within [one minor version + difference](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin) of your cluster, on an + administrative system. +- The [Helm package manager](https://helm.sh/) v3.0.0 or newer on the same administrative system. + +The default configuration creates one `parent` pod, installed on one of your cluster's nodes, and a DaemonSet for +additional `child` pods. This DaemonSet ensures that every node in your k8s cluster also runs a `child` pod, including +the node that also runs `parent`. The `child` pods collect metrics and stream the information to the `parent` pod, which +uses two persistent volumes to store metrics and alarms. The `parent` pod also handles alarm notifications and enables +the Netdata dashboard using an ingress controller. + +## Install the Netdata Helm chart + +We recommend you install the Helm chart using our Helm repository. In the `helm install` command, replace `netdata` with +the release name of your choice. + +```bash +helm repo add netdata https://netdata.github.io/helmchart/ +helm install netdata netdata/netdata +``` + +> You can also install the Netdata Helm chart by cloning the +> [repository](https://artifacthub.io/packages/helm/netdata/netdata#install-by-cloning-the-repository) and manually +> running Helm against the included chart. + +### Post-installation + +Run `kubectl get services` and `kubectl get pods` to confirm that your cluster now runs a `netdata` service, one +`parent` pod, and three `child` pods. + +You've now installed Netdata on your Kubernetes cluster. See how to [access the Netdata +dashboard](#access-the-netdata-dashboard) to confirm it's working as expected, or see the next section to [configure the +Helm chart](#configure-the-netdata-helm-chart) to suit your cluster's particular setup. + +## Configure the Netdata Helm chart + +Read up on the various configuration options in the [Helm chart +documentation](https://github.com/netdata/helmchart#configuration) to see if you need to change any of the options based +on your cluster's setup. + +To change a setting, use the `--set` or `--values` arguments with `helm install`, for the initial deployment, or `helm upgrade` to upgrade an existing deployment. + +```bash +helm install --set a.b.c=xyz netdata netdata/netdata +helm upgrade --set a.b.c=xyz netdata netdata/netdata +``` + +For example, to change the size of the persistent metrics volume on the parent node: + +```bash +helm install --set parent.database.volumesize=4Gi netdata netdata/netdata +helm upgrade --set parent.database.volumesize=4Gi netdata netdata/netdata +``` + +### Configure service discovery + +As mentioned in the introduction, Netdata has a [service discovery +plugin](https://github.com/netdata/agent-service-discovery/#service-discovery) to identify compatible pods and collect +metrics from the service they run. The Netdata Helm chart installs this service discovery plugin into your k8s cluster. + +Service discovery scans your cluster for pods exposed on certain ports and with certain image names. By default, it +looks for its supported services on the ports they most commonly listen on, and using default image names. Service +discovery currently supports [popular +applications](https://github.com/netdata/helmchart#service-discovery-and-supported-services), plus any endpoints covered +by our [generic Prometheus collector](https://learn.netdata.cloud/docs/agent/collectors/go.d.plugin/modules/prometheus). + +If you haven't changed listening ports, image names, or other defaults, service discovery should find your pods, create +the proper configurations based on the service that pod runs, and begin monitoring them immediately after deployment. + +However, if you have changed some of these defaults, you need to copy a file from the Netdata Helm chart repository, +make your edits, and pass the changed file to `helm install`/`helm upgrade`. + +First, copy the file to your administrative system. + +```bash +curl https://raw.githubusercontent.com/netdata/helmchart/master/charts/netdata/sdconfig/child.yml -o child.yml +``` + +Edit the new `child.yml` file according to your needs. See the [Helm chart +configuration](https://github.com/netdata/helmchart#configuration) and the file itself for details. + +You can then run `helm install`/`helm upgrade` with the `--set-file` argument to use your configured `child.yml` file +instead of the default, changing the path if you copied it elsewhere. + +```bash +helm install --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata +helm upgrade --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata +``` + +Your configured service discovery is now pushed to your cluster. + +## Access the Netdata dashboard + +Accessing the Netdata dashboard itself depends on how you set up your k8s cluster and the Netdata Helm chart. If you +installed the Helm chart with the default `service.type=ClusterIP`, you will need to forward a port to the parent pod. + +```bash +kubectl port-forward netdata-parent-0 19999:19999 +``` + +You can now access the dashboard at `http://CLUSTER:19999`, replacing `CLUSTER` with the IP address or hostname of your +k8s cluster. + +If you set up the Netdata Helm chart with `service.type=LoadBalancer`, you can find the external IP for the load +balancer with `kubectl get services`, under the `EXTERNAL-IP` column. + +```bash +kubectl get services +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +cockroachdb ClusterIP None 26257/TCP,8080/TCP 46h +cockroachdb-public ClusterIP 10.245.148.233 26257/TCP,8080/TCP 46h +kubernetes ClusterIP 10.245.0.1 443/TCP 47h +netdata LoadBalancer 10.245.160.131 203.0.113.0 19999:32231/TCP 74m +``` + +In the above example, access the dashboard by navigating to `http://203.0.113.0:19999`. + +## Claim a Kubernetes cluster's parent pod + +You can [claim](/claim/README.md) a cluster's parent Netdata pod to see its real-time metrics alongside any other nodes +you monitor using [Netdata Cloud](https://app.netdata.cloud). + +> Netdata Cloud does not currently support claiming child nodes because the Helm chart does not allocate a persistent +> volume for them. + +Ensure persistence is enabled on the parent pod by running the following `helm upgrade` command. + +```bash +helm upgrade \ + --set parent.database.persistence=true \ + --set parent.alarms.persistence=true \ + netdata netdata/netdata +``` + +Next, find your claiming script in Netdata Cloud by clicking on your Space's dropdown, then **Manage your Space**. Click +the **Nodes** tab. Netdata Cloud shows a script similar to the following: + +```bash +sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud +``` + +You will need the values of `TOKEN` and `ROOM1,ROOM2` for the command, which sets `parent.claiming.enabled`, +`parent.claiming.token`, and `parent.claiming.rooms` to complete the parent pod claiming process. + +Run the following `helm upgrade` command after replacing `TOKEN` and `ROOM1,ROOM2` with the values found in the claiming +script from Netdata Cloud. The quotations are required. + +```bash +helm upgrade \ + --set parent.claiming.enabled=true \ + --set parent.claiming.token="TOKEN" \ + --set parent.claiming.rooms="ROOM1,ROOM2" \ + netdata netdata/netdata +``` + +The cluster terminates the old parent pod and creates a new one with the proper claiming configuration. You can see your +parent pod in Netdata Cloud after a few moments. You can now [build new +dashboards](https://learn.netdata.cloud/docs/cloud/visualize/dashboards) using the parent pod's metrics or run [Metric +Correlations](https://learn.netdata.cloud/docs/cloud/insights/metric-correlations) to troubleshoot anomalies. + +![A parent Netdata pod in Netdata +Cloud](https://user-images.githubusercontent.com/1153921/94497340-c1f49880-01ab-11eb-97b2-6044537565af.png) + +## Update/reinstall the Netdata Helm chart + +If you update the Helm chart's configuration, run `helm upgrade` to redeploy your Netdata service, replacing `netdata` +with the name of the release, if you changed it upon installation: + +```bash +helm upgrade netdata netdata/netdata +``` + +## What's next? + +Read the [monitoring a Kubernetes cluster guide](/docs/guides/monitor/kubernetes-k8s-netdata.md) for details on the +various metrics and charts created by the Helm chart and some best practices on real-time troubleshooting using Netdata. + +Check out our [infrastructure](/docs/quickstart/infrastructure.md) for details about additional k8s monitoring features, +and learn more about [configuring the Netdata Agent](/docs/configure/nodes.md) to better understand the settings you +might be interested in changing. + +To further configure Netdata for your cluster, see our [Helm chart repository](https://github.com/netdata/helmchart) and +the [service discovery repository](https://github.com/netdata/agent-service-discovery/). + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fkubernetes&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/macos.md b/packaging/installer/methods/macos.md new file mode 100644 index 000000000..05883a7fe --- /dev/null +++ b/packaging/installer/methods/macos.md @@ -0,0 +1,90 @@ + + +# Install Netdata on macOS + +Netdata works on macOS, albeit with some limitations. The number of charts displaying system metrics is limited, but you +can use any of Netdata's [external plugins](../../../collectors/plugins.d/README.md) to monitor any services you might +have installed on your macOS system. You could also use a macOS system as the parent node in a [streaming +configuration](/streaming/README.md). + +We recommend installing Netdata with the community-created and -maintained [**Homebrew +package**](#install-netdata-with-the-homebrew-package). + +- [Install Netdata via the Homebrew package](#install-netdata-with-the-homebrew-package) +- [Install Netdata from source](#install-netdata-from-source) + +## Install Netdata with the Homebrew package + +If you don't have [Homebrew](https://brew.sh/) installed already, begin with their installation script: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +``` + +Next, you can use Homebrew's package, which installs Netdata all its dependencies in a single step: + +```sh +brew install netdata +``` + +> Homebrew will place your Netdata configuration directory at `/usr/local/etc/netdata/`. Use the `edit-config` script +> and the files in this directory to configure Netdata. For reference, you can find stock configuration files at +> `/usr/local/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/`. + +Skip on ahead to the [What's next?](#whats-next) section to find links to helpful post-installation guides. + +## Install Netdata from source + +We don't recommend installing Netdata from source on macOS, as it can be difficult to configure and install dependencies +manually. + +First open your terminal of choice and install the Xcode development packages. + +```bash +xcode-select --install +``` + +Click **Install** on the Software Update popup window that appears. Then, use the same terminal session to use Homebrew +to install some of Netdata's prerequisites. You can omit `cmake` in case you do not want to use +[Netdata Cloud](https://learn.netdata.cloud/docs/cloud/). + +```bash +brew install ossp-uuid autoconf automake pkg-config libuv lz4 json-c openssl@1.1 libtool cmake +``` + +If you want to use the [database engine](/database/engine/README.md) to store your metrics, you need to download +and install the [Judy library](https://sourceforge.net/projects/judy/) before proceeding compiling Netdata. + +Next, download Netdata from our GitHub repository: + +```bash +git clone https://github.com/netdata/netdata.git +``` + +Finally, `cd` into the newly-created directory and then start the installer script: + +```bash +cd netdata/ +sudo ./netdata-installer.sh --install /usr/local +``` + +> Your Netdata configuration directory will be at `/usr/local/netdata/`, and your stock configuration directory will +> be at **`/usr/local/lib/netdata/conf.d/`.** +> +> The installer will also install a startup plist to start Netdata when your macOS system boots. + +## What's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fmacos&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/manual.md b/packaging/installer/methods/manual.md new file mode 100644 index 000000000..6ece95240 --- /dev/null +++ b/packaging/installer/methods/manual.md @@ -0,0 +1,229 @@ + + +# Install Netdata on Linux from a Git checkout + +To install the latest git version of Netdata, please follow these 2 steps: + +1. [Prepare your system](#prepare-your-system) + + Install the required packages on your system. + +2. [Install Netdata](#install-netdata) + + Download and install Netdata. You can also update it the same way. + +## Prepare your system + +Use our automatic requirements installer (_no need to be `root`_), which attempts to find the packages that +should be installed on your system to build and run Netdata. It supports a large variety of major Linux distributions +and other operating systems and is regularly tested. You can find this tool [here](https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh) or run it directly with `bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh)`. Otherwise read on for how to get requires packages manually: + +- **Alpine** Linux and its derivatives + - You have to install `bash` yourself, before using the installer. + +- **Arch** Linux and its derivatives + - You need arch/aur for package Judy. + +- **Gentoo** Linux and its derivatives + +- **Debian** Linux and its derivatives (including **Ubuntu**, **Mint**) + +- **Red Hat Enterprise Linux** and its derivatives (including **Fedora**, **CentOS**, **Amazon Machine Image**) + - Please note that for RHEL/CentOS you need + [EPEL](http://www.tecmint.com/how-to-enable-epel-repository-for-rhel-centos-6-5/). + In addition, RHEL/CentOS version 6 also need + [OKay](https://okay.com.mx/blog-news/rpm-repositories-for-centos-6-and-7.html) for package libuv version 1. + - CentOS 8 / RHEL 8 requires a bit of extra work. See the dedicated section below. + +- **SUSE** Linux and its derivatives (including **openSUSE**) + +- **SLE12** Must have your system registered with SUSE Customer Center or have the DVD. See + [#1162](https://github.com/netdata/netdata/issues/1162) + +Install the packages for having a **basic Netdata installation** (system monitoring and many applications, without `mysql` / `mariadb`, `postgres`, `named`, hardware sensors and `SNMP`): + +```sh +curl -Ss 'https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh' >/tmp/install-required-packages.sh && bash /tmp/install-required-packages.sh -i netdata +``` + +Install all the required packages for **monitoring everything Netdata can monitor**: + +```sh +curl -Ss 'https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh' >/tmp/install-required-packages.sh && bash /tmp/install-required-packages.sh -i netdata-all +``` + +If the above do not work for you, please [open a github +issue](https://github.com/netdata/netdata/issues/new?title=packages%20installer%20failed&labels=installation%20help&body=The%20experimental%20packages%20installer%20failed.%0A%0AThis%20is%20what%20it%20says:%0A%0A%60%60%60txt%0A%0Aplease%20paste%20your%20screen%20here%0A%0A%60%60%60) +with a copy of the message you get on screen. We are trying to make it work everywhere (this is also why the script +[reports back](https://github.com/netdata/netdata/issues/2054) success or failure for all its runs). + +--- + +This is how to do it by hand: + +```sh +# Debian / Ubuntu +apt-get install zlib1g-dev uuid-dev libuv1-dev liblz4-dev libjudy-dev libssl-dev libelf-dev libmnl-dev gcc make git autoconf autoconf-archive autogen automake pkg-config curl python cmake + +# Fedora +dnf install zlib-devel libuuid-devel libuv-devel lz4-devel Judy-devel openssl-devel elfutils-libelf-devel libmnl-devel gcc make git autoconf autoconf-archive autogen automake pkgconfig curl findutils python cmake + +# CentOS / Red Hat Enterprise Linux +yum install autoconf automake curl gcc git libmnl-devel libuuid-devel openssl-devel libuv-devel lz4-devel Judy-devel elfutils-libelf-devel make nc pkgconfig python zlib-devel cmake + +# openSUSE +zypper install zlib-devel libuuid-devel libuv-devel liblz4-devel judy-devel libopenssl-devel libelf-devel libmnl-devel gcc make git autoconf autoconf-archive autogen automake pkgconfig curl findutils python cmake +``` + +Once Netdata is compiled, to run it the following packages are required (already installed using the above commands): + +| package | description| +|:-----:|-----------| +| `libuuid` | part of `util-linux` for GUIDs management| +| `zlib` | gzip compression for the internal Netdata web server| +| `libuv` | Multi-platform support library with a focus on asynchronous I/O, version 1 or greater| + +*Netdata will fail to start without the above.* + +Netdata plugins and various aspects of Netdata can be enabled or benefit when these are installed (they are optional): + +| package |description| +|:-----:|-----------| +| `bash`|for shell plugins and **alarm notifications**| +| `curl`|for shell plugins and **alarm notifications**| +| `iproute` or `iproute2`|for monitoring **Linux traffic QoS**
use `iproute2` if `iproute` reports as not available or obsolete| +| `python`|for most of the external plugins| +| `python-yaml`|used for monitoring **beanstalkd**| +| `python-beanstalkc`|used for monitoring **beanstalkd**| +| `python-dnspython`|used for monitoring DNS query time| +| `python-ipaddress`|used for monitoring **DHCPd**
this package is required only if the system has python v2. python v3 has this functionality embedded| +| `python-mysqldb`
or
`python-pymysql`|used for monitoring **mysql** or **mariadb** databases
`python-mysqldb` is a lot faster and thus preferred| +| `python-psycopg2`|used for monitoring **postgresql** databases| +| `python-pymongo`|used for monitoring **mongodb** databases| +| `nodejs`|used for `node.js` plugins for monitoring **named** and **SNMP** devices| +| `lm-sensors`|for monitoring **hardware sensors**| +| `libelf`|for monitoring kernel-level metrics using eBPF| +| `libmnl`|for collecting netfilter metrics| +| `netcat`|for shell plugins to collect metrics from remote systems| + +*Netdata will greatly benefit if you have the above packages installed, but it will still work without them.* + +Netdata DB engine can be enabled when these are installed (they are optional): + +| package | description| +|:-----:|-----------| +| `liblz4` | Extremely fast compression algorithm, version r129 or greater| +| `Judy` | General purpose dynamic array| +| `openssl`| Cryptography and SSL/TLS toolkit| + +*Netdata will greatly benefit if you have the above packages installed, but it will still work without them.* + +Netdata Cloud support may require the following packages to be installed: + +| package | description +|:--------:| ----------------------- +| `cmake` | Needed at build time if you aren't using your distribution's version of libwebsockets or are building on a platform other than Linux +| `openssl` | Needed to secure communications with the Netdata Cloud + +*Netdata will greatly benefit if you have the above packages installed, but it will still work without them.* + +### CentOS / RHEL 6.x + +On CentOS / RHEL 6.x, many of the dependencies for Netdata are only +available with versions older than what we need, so special setup is +required if manually installing packages. + +CentOS 6.x: + +- Enable the EPEL repo +- Enable the additional repo from [okay.network](https://okay.network/blog-news/rpm-repositories-for-centos-6-and-7.html) + +And install the minimum required dependencies. + +### CentOS / RHEL 8.x + +For CentOS / RHEL 8.x a lot of development packages have moved out into their +own separate repositories. Some other dependencies are either missing completely +or have to be sourced by 3rd-parties. + +CentOS 8.x: + +- Enable the PowerTools repo +- Enable the EPEL repo +- Enable the Extra repo from [OKAY](https://okay.network/blog-news/rpm-repositories-for-centos-6-and-7.html) + +And install the minimum required dependencies: + +```sh +# Enable config-manager +yum install -y 'dnf-command(config-manager)' + +# Enable PowerTools +yum config-manager --set-enabled powertools + +# Enable EPEL +yum install -y epel-release + +# Install Repo for libuv-devl (NEW) +yum install -y http://repo.okay.com.mx/centos/8/x86_64/release/okay-release-1-3.el8.noarch.rpm + +# Install Devel Packages +yum install autoconf automake curl gcc git cmake libuuid-devel openssl-devel libuv-devel lz4-devel make nc pkgconfig python3 zlib-devel + +# Install Judy-Devel directly +yum install -y http://mirror.centos.org/centos/8/PowerTools/x86_64/os/Packages/Judy-devel-1.0.5-18.module_el8.1.0+217+4d875839.x86_64.rpm +``` + +--- + +### Install Netdata + +Do this to install and run Netdata: + +```sh +# download it - the directory 'netdata' will be created +git clone https://github.com/netdata/netdata.git --depth=100 +cd netdata + +# run script with root privileges to build, install, start Netdata +./netdata-installer.sh +``` + +- If you don't want to run it straight-away, add `--dont-start-it` option. + +- You can also append `--stable-channel` to fetch and install only the official releases from GitHub, instead of the nightly builds. + +- If you don't want to install it on the default directories, you can run the installer like this: `./netdata-installer.sh --install /opt`. This one will install Netdata in `/opt/netdata`. + +- If your server does not have access to the internet and you have manually put the installation directory on your server, you will need to pass the option `--disable-go` to the installer. The option will prevent the installer from attempting to download and install `go.d.plugin`. + +Once the installer completes, the file `/etc/netdata/netdata.conf` will be created (if you changed the installation directory, the configuration will appear in that directory too). + +You can edit this file to set options. One common option to tweak is `history`, which controls the size of the memory database Netdata will use. By default is `3600` seconds (an hour of data at the charts) which makes Netdata use about 10-15MB of RAM (depending on the number of charts detected on your system). Check **\[[Memory Requirements]]**. + +To apply the changes you made, you have to restart Netdata. + +### 'nonrepresentable section on output' errors + +Our current build process unfortunately has some issues when using certain configurations of the `clang` C compiler on Linux. + +If the installation fails with errors like `/bin/ld: externaldeps/libwebsockets/libwebsockets.a(context.c.o): relocation R_X86_64_32 against '.rodata.str1.1' can not be used when making a PIE object; recompile with -fPIC`, and you are trying to build with `clang` on Linux, you will need to build Netdata using GCC to get a fully functional install. + +In most cases, you can do this by running `CC=gcc ./netdata-installer.sh`. + +## What's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fmanual&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/offline.md b/packaging/installer/methods/offline.md new file mode 100644 index 000000000..c978dd613 --- /dev/null +++ b/packaging/installer/methods/offline.md @@ -0,0 +1,90 @@ + + +# Install Netdata on offline systems + +The Netdata Agent installs on offline or air gapped systems with a few additional steps. + +By default, the `kickstart.sh` and `kickstart-static64.sh` download Netdata assets, like the precompiled binary and a +few dependencies, using the system's internet connection, but the Agent installer can also use equivalent files already +present on the local filesystem. + +First, download the required files. If you're using `kickstart.sh`, you need the Netdata tarball, the checksums, the +go.d plugin binary, and the go.d plugin configuration. If you're using `kickstart-static64.sh`, you need only the +Netdata tarball and checksums. + +Download the files you need to a system of yours that's connected to the internet. Use the commands below, or visit the +[latest Netdata release page](https://github.com/netdata/netdata/releases/latest) and [latest go.d plugin release +page](https://github.com/netdata/go.d.plugin/releases) to download the required files manually. + +**If you're using `kickstart.sh`**, use the following commands: + +```bash +cd /tmp + +curl -s https://my-netdata.io/kickstart.sh > kickstart.sh + +# Netdata tarball +curl -s https://api.github.com/repos/netdata/netdata/releases/latest | grep "browser_download_url.*tar.gz" | cut -d '"' -f 4 | wget -qi - + +# Netdata checksums +curl -s https://api.github.com/repos/netdata/netdata/releases/latest | grep "browser_download_url.*txt" | cut -d '"' -f 4 | wget -qi - + +# Netdata dependency handling script +wget -q - https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh + +# go.d plugin +# For binaries for OS types and architectures not listed on [go.d releases](https://github.com/netdata/go.d.plugin/releases/latest), kindly open a github issue and we will do our best to serve your request +export OS=$(uname -s | tr '[:upper:]' '[:lower:]') ARCH=$(uname -m | sed -e 's/i386/386/g' -e 's/i686/386/g' -e 's/x86_64/amd64/g' -e 's/aarch64/arm64/g' -e 's/armv64/arm64/g' -e 's/armv6l/arm/g' -e 's/armv7l/arm/g' -e 's/armv5tel/arm/g') && curl -s https://api.github.com/repos/netdata/go.d.plugin/releases/latest | grep "browser_download_url.*${OS}-${ARCH}.tar.gz" | cut -d '"' -f 4 | wget -qi - + +# go.d configuration +curl -s https://api.github.com/repos/netdata/go.d.plugin/releases/latest | grep "browser_download_url.*config.tar.gz" | cut -d '"' -f 4 | wget -qi - +``` + +**If you're using `kickstart-static64.sh`**, use the following commands: + +```bash +cd /tmp + +curl -s https://my-netdata.io/kickstart-static64.sh > kickstart-static64.sh + +# Netdata static64 tarball +curl -s https://api.github.com/repos/netdata/netdata/releases/latest | grep "browser_download_url.*gz.run" | cut -d '"' -f 4 | wget -qi - + +# Netdata checksums +curl -s https://api.github.com/repos/netdata/netdata/releases/latest | grep "browser_download_url.*txt" | cut -d '"' -f 4 | wget -qi - +``` + +Move downloaded files to the `/tmp` directory on the offline system in whichever way your defined policy allows (if +any). + +Now you can run either the `kickstart.sh` or `kickstart-static64.sh` scripts using the `--local-files` option. This +option requires you to specify the location and names of the files you just downloaded. + +> When using `--local-files`, the `kickstart.sh` or `kickstart-static64.sh` scripts won't download any Netdata assets +> from the internet. But, you may still need a connection to install dependencies using your system's package manager. +> The scripts will warn you if your system doesn't have all the dependencies. + +```bash +# kickstart.sh +bash kickstart.sh --local-files /tmp/netdata-(version-number-here).tar.gz /tmp/sha256sums.txt /tmp/go.d.plugin-(version-number-here).(OS)-(architecture).tar.gz /tmp/config.tar.gz /tmp/install-required-packages.sh + +# kickstart-static64.sh +bash kickstart-static64.sh --local-files /tmp/netdata-(version-number-here).gz.run /tmp/sha256sums.txt +``` + +## What's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackages%2Finstaller%2Fmethods%2Foffline&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]() diff --git a/packaging/installer/methods/packages.md b/packaging/installer/methods/packages.md new file mode 100644 index 000000000..cf1e33591 --- /dev/null +++ b/packaging/installer/methods/packages.md @@ -0,0 +1,48 @@ + + +# Install Netdata with .deb/.rpm packages + +![](https://raw.githubusercontent.com/netdata/netdata/master/web/gui/images/packaging-beta-tag.svg?sanitize=true) + +Netdata provides our own flavour of binary packages for the most common operating systems that use with `.deb` and +`.rpm` packaging formats. + +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. + +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 + +## 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. + +If you are using such a setup, there are a couple of ways to 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 packages will not be cached. +- Mirror the repository 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. Find + such options in their documentation. + +## What's next? + +When you're finished with installation, check out our [single-node](/docs/quickstart/single-node.md) or +[infrastructure](/docs/quickstart/infrastructure.md) monitoring quickstart guides based on your use case. + +Or, skip straight to [configuring the Netdata Agent](/docs/configure/nodes.md). + +Read through Netdata's [documentation](https://learn.netdata.cloud/docs), which is structured based on actions and +solutions, to enable features like health monitoring, alarm notifications, long-term metrics storage, exporting to +external databases, and more. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackages%2Finstaller%2Fmethods%2Fpackages&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]() diff --git a/packaging/installer/methods/pfsense.md b/packaging/installer/methods/pfsense.md new file mode 100644 index 000000000..ee1a453db --- /dev/null +++ b/packaging/installer/methods/pfsense.md @@ -0,0 +1,84 @@ + + +# Install Netdata on pfSense + +> 💡 This document is maintained by Netdata's community, and may not be completely up-to-date. Please double-check the +> details of the installation process, such as version numbers for downloadable packages, before proceeding. +> +> You can help improve this document by [submitting a +> PR](https://github.com/netdata/netdata/edit/master/packaging/installer/methods/pfsense.md) with your recommended +> improvements or changes. Thank you! + +## Install prerequisites/dependencies + +To install Netdata on pfSense, first run the following command (within a shell or under the **Diagnostics/Command** +prompt within the pfSense web interface). + +```bash +pkg install -y pkgconf bash e2fsprogs-libuuid libuv nano +``` + +Then run the following commands to download various dependencies from the FreeBSD repository. + +```sh +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/Judy-1.0.5_2.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/json-c-0.15_1.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-certifi-2020.6.20.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-asn1crypto-1.3.0.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-pycparser-2.20.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-cffi-1.14.3.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-six-1.15.0.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-cryptography-2.6.1.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-idna-2.10.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-openssl-19.0.0.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-pysocks-1.7.1.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-urllib3-1.25.11,1.txz +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/py37-yaml-5.3.1.txz +``` + +> ⚠️ If any of the above commands return a `Not Found` error, you need to manually search for the latest package in the +> [FreeBSD repository](https://www.freebsd.org/ports/). Search for the package's name, such as `py37-cffi`, find the +> latest version number, and update the command accordingly. + +> ⚠️ On pfSense 2.4.5, Python version 3.7 may be installed by the system, in which case you should should not install +> Python from the FreeBSD repository as instructed above. + +> ⚠️ If you are using the `apcupsd` collector, you need to make sure that apcupsd is up before starting Netdata. +> Otherwise a infinitely running `cat` process triggered by the default activated apcupsd charts plugin will eat up CPU +> and RAM (`/tmp/.netdata-charts.d-*/run-*`). This also applies to `OPNsense`. + +## Install Netdata + +You can now install Netdata from the FreeBSD repository. + +```bash +pkg add http://pkg.freebsd.org/FreeBSD:11:amd64/latest/All/netdata-1.28.0.txz +``` + +> ⚠️ If the above command returns a `Not Found` error, you need to manually search for the latest version of Netdata in +> the [FreeBSD repository](https://www.freebsd.org/ports/). Search for `netdata`, find the latest version number, and +> update the command accordingly. + +You must edit `/usr/local/etc/netdata/netdata.conf` and change `bind to = 127.0.0.1` to `bind to = 0.0.0.0`. + +To start Netdata manually, run `service netdata onestart`. + +Visit the Netdata dashboard to confirm it's working: `http://:19999` + +To start Netdata automatically every boot, add `service netdata onestart` as a Shellcmd entry within the pfSense web +interface under **Services/Shellcmd**. You'll need to install the Shellcmd package beforehand under **System/Package +Manager/Available Packages**. The Shellcmd Type should be set to `Shellcmd`. +![](https://i.imgur.com/wcKiPe1.png) Alternatively more information can be found in +, for achieving the same via the command line and +scripts. + +If you experience an issue with `/usr/bin/install` being absent in pfSense 2.3 or earlier, update pfSense or use a +workaround from + +**Note:** In pfSense, the Netdata configuration files are located under `/usr/local/etc/netdata`. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fpfsense&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/source.md b/packaging/installer/methods/source.md new file mode 100644 index 000000000..e0827fc17 --- /dev/null +++ b/packaging/installer/methods/source.md @@ -0,0 +1,291 @@ + + +# Manually build Netdata from source + +These instructions are for advanced users and distribution package +maintainers. Unless this describes you, you almost certainly want +to follow [our guide for manually installing Netdata from a git +checkout](/packaging/installer/methods/manual.md) instead. + +## Required dependencies + +At a bare minimum, Netdata requires the following libraries and tools +to build and run successfully: + +- libuuid +- libuv version 1.0 or newer +- zlib +- GNU autoconf +- GNU automake +- GCC or Xcode (Clang is known to have issues in certain configurations, see [Using Clang](#using-clang)) +- A version of `make` compatible with GNU automake +- Git (we use git in the build system to generate version info, don't need a full install, just a working `git show` command) + +Additionally, the following build time features require additional dependencies: + +- TLS support for the web GUI: + - OpenSSL 1.0.2 or newer _or_ LibreSSL 3.0.0 or newer. +- dbengine metric storage: + - liblz4 r129 or newer + - OpenSSL 1.0 or newer (LibreSSL _amy_ work, but is largely untested). + - [libJudy](http://judy.sourceforge.net/) +- Netdata Cloud support: + - A working internet connection + - A recent version of CMake + - OpenSSL 1.0.2 or newer _or_ LibreSSL 3.0.0 or newer. + - JSON-C (may be provided by the user as shown below, or by the system) + +## Preparing the source tree + +Certain features in Netdata require custom versions of specific libraries, +which the the build system will link statically into Netdata. These +libraries and their header files must be copied into specific locations +in the source tree to be used. + +### Netdata cloud + +Netdata Cloud functionality requires custom builds of libmosquitto and +libwebsockets. + +#### libmosquitto + +Netdata maintains a custom fork of libmosquitto at +https://github.com/netdata/mosquitto with patches to allow for proper +integration with libwebsockets, which is needed for correct operation of +Netdata Cloud functionality. To prepare this library for the build system: + +1. Verify the tag that Netdata expects to be used by checking the contents + of `packaging/mosquitto.version` in your Netdata sources. +2. Obtain the sources for that version by either: + - Navigating to https://github.com/netdata/mosquitto/releases and + downloading and unpacking the source code archive for that release. + - Cloning the repository with `git` and checking out the required tag. +3. If building on a platform other than Linux, prepare the mosquitto + sources by running `cmake -D WITH_STATIC_LIBRARIES:boolean=YES .` in + the mosquitto source directory. +4. Build mosquitto by running `make -C lib` in the mosquitto source directory. +5. In the Netdata source directory, create a directory called `externaldeps/mosquitto`. +6. Copy `lib/mosquitto.h` from the mosquitto source directory to + `externaldeps/mosquitto/mosquitto.h` in the Netdata source tree. +7. Copy `lib/libmosquitto.a` from the mosquitto source directory to + `externaldeps/mosquitto/libmosquitto.a` in the Netdata source tree. If + building on a platform other than Linux, the file that needs to be + copied will instead be named `lib/libmosquitto_static.a`, but it + still needs to be copied to `externaldeps/mosquitto/libmosquitto.a`. + +#### libwebsockets + +Netdata uses the standard upstream version of libwebsockets located at +https://github.com/warmcat/libwebsockets, but requires a build with SOCKS5 +support, which is not enabled by most pre-built versions. Currently, +we do not support using a system copy of libwebsockets. To prepare this +library for the build system: + +1. Verify the tag that Netdata expects to be used by checking the contents + of `packaging/libwebsockets.version` in your Netdata sources. +2. Obtain the sources for that version by either: + - Navigating to https://github.com/warmcat/libwebsockets/releases and + downloading and unpacking the source code archive for that release. + - Cloning the repository with `git` and checking out the required tag. +3. Prepare the libwebsockets sources by running `cmake -D + LWS_WITH_SOCKS5:bool=ON .` in the libwebsockets source directory. +4. Build libwebsockets by running `make` in the libwebsockets source + directory. +5. In the Netdata source directory, create a directory called + `externaldeps/libwebsockets`. +6. Copy `lib/libwebsockets.a` from the libwebsockets source directory to + `externaldeps/libwebsockets/libwebsockets.a` in the Netdata source tree. +7. Copy the entire contents of `lib/include` from the libwebsockets source + directory to `externaldeps/libwebsockets/include` in the Netdata source tree. + +#### JSON-C + +Netdata requires the use of JSON-C for JSON parsing when using Netdata +Cloud. Netdata is able to use a system-provided copy of JSON-C, but +some systems may not provide it. If your system does not provide JSON-C, +you can do the following to prepare a copy for the build system: + +1. Verify the tag that Netdata expects to be used by checking the contents + of `packaging/jsonc.version` in your Netdata sources. +2. Obtain the sources for that version by either: + - Navigating to https://github.com/json-c/json-c and downloading + and unpacking the source code archive for that release. + - Cloning the repository with `git` and checking out the required tag. +3. Prepare the JSON-C sources by running `cmake -DBUILD_SHARED_LIBS=OFF .` + in the JSON-C source directory. +4. Build JSON-C by running `make` in the JSON-C source directory. +5. In the Netdata source directory, create a directory called + `externaldeps/jsonc`. +6. Copy `libjson-c.a` fro the JSON-C source directory to + `externaldeps/jsonc/libjson-c.a` in the Netdata source tree. +7. Copy all of the header files (`*.h`) from the JSON-C source directory + to `externaldeps/jsonc/json-c` in the Netdata source tree. + +## Building Netdata + +Once the source tree has been prepared, Netdata is ready to be configured +and built. Netdata currently uses GNU autotools as it's primary build +system. To build Netdata this way: + +1. Run `autoreconf -ivf` in the Netdata source tree. +2. Run `./configure` in the Netdata source tree. +3. Run `make` in the Netdata source tree. + +### Configure options + +Netdata provides a number of build time configure options. This section +lists some of the ones you are most likely to need: + +- `--prefix`: Specify the prefix under which Netdata will be installed. +- `--with-webdir`: Specify a path relative to the prefix in which to + install the web UI files. +- `--disable-cloud`: Disables all Netdata Cloud functionality for + this build. + +### Using Clang + +Netdata is primarily developed using GCC, but in most cases we also +build just fine using Clang. Under some build configurations of Clang +itself, you may see build failures with the linker reporting errors +about `nonrepresentable section on output`. We currently do not have a +conclusive fix for this issue (the obvious fix leads to other issues which +we haven't been able to fix yet), and unfortunately the only workaround +is to use a different build of Clang or to use GCC. + +### Linking errors relating to OpenSSL + +Netdata's build system currently does not reliably support building +on systems which have multiple ABI incompatible versions of OpenSSL +installed. In such situations, you may encounter linking errors due to +Netdata trying to build against headers for one version but link to a +different version. + +## Additional components + +A full featured install of Netdata requires some additional components +which must be built and installed separately from the main Netdata +agent. All of these should be handled _after_ installing Netdata itself. + +### React dashboard + +The above build steps include a deprecated web UI for Netdata that lacks +support for Netdata Cloud. To get a fully featured dashboard, you must +install our new React dashboard. + +#### Installing the pre-built React dashboard + +We provide pre-built archives of the React dashboard for each release +(these are also used during our normal install process). To use one +of these: + +1. Verify the release version that Netdata expects to be used by checking + the contents of `packaging/dashboard.version` in your Netdata sources. +2. Go to https://github.com/netdata/dashboard/releases and download the + `dashboard.tar.gz` file for the required release. +3. Unpack the downloaded archive to a temporary directory. +4. Copy the contents of the `build` directory from the extracted + archive to `/usr/share/netdata/web` or the equivalent location for + your build of Netdata. This _will_ overwrite some files in the target + location. + +#### Building the React dashboard locally + +Alternatively, you may wish to build the React dashboard locally. Doing +so requires a recent version of Node.JS with a working install of +NPM. Once you have the required tools, do the following: + +1. Verify the release version that Netdata expects to be used by checking + the contents of `packaging/dashboard.version` in your Netdata sources. +2. Obtain the sources for that version by either: + - Navigating to https://github.com/netdata/dashboard and downloading + and unpacking the source code archive for that release. + - Cloning the repository with `git` and checking out the required tag. +3. Run `npm install` in the dashboard source tree. +4. Run `npm run build` in the dashboard source tree. +5. Copy the contents of the `build` directory just like step 4 of + installing the pre-built React dashboard. + +### Go collectors + +A number of the collectors for Netdata are written in Go instead of C, +and are developed in a separate repository from the mian Netdata code. +An installation without these collectors is still usable, but will be +unable to collect metrics for a number of network services the system +may be providing. You can either install a pre-built copy of these +collectors, or build them locally. + +#### Installing the pre-built Go collectors + +We provide pre-built binaries of the Go collectors for all the platforms +we officially support. To use one of these: + +1. Verify the release version that Netdata expects to be used by checking + the contents of `packaging/go.d.version` in your Netdata sources. +2. Go to https://github.com/netdata/go.d.plugin/releases, select the + required release, and download the `go.d.plugin-*.tar.gz` file + for your system type and CPu architecture and the `config.tar.gz` + configuration file archive. +3. Extract the `go.d.plugin-*.tar.gz` archive into a temporary + location, and then copy the single file in the archive to + `/usr/libexec/netdata/plugins.d` or the equivalent location for your + build of Netdata and rename it to `go.d.plugin`. +4. Extract the `config.tar.gz` archive to a temporarylocation and then + copy the contents of the archive to `/etc/netdata` or the equivalent + location for your build of Netdata. + +#### Building the Go collectors locally + +Alternatively, you may wish to build the Go collectors locally +yourself. Doing so requires a working installation of Golang 1.13 or +newer. Once you have the required tools, do the following: + +1. Verify the release version that Netdata expects to be used by checking + the contents of `packaging/go.d.version` in your Netdata sources. +2. Obtain the sources for that version by either: + - Navigating to https://github.com/netdata/go.d.plugin and downloading + and unpacking the source code archive for that release. + - Cloning the repository with `git` and checking out the required tag. +3. Run `make` in the go.d.plugin source tree. +4. Copy `bin/godplugin` to `/usr/libexec/netdata/plugins.d` or th + equivalent location for your build of Netdata and rename it to + `go.d.plugin`. +5. Copy the contents of the `config` directory to `/etc/netdata` or the + equivalent location for your build of Netdata. + +### eBPF collector + +On Linux systems, Netdata has support for using the kernel's eBPF +interface to monitor performance-related VFS, network, and process events, +allowing for insights into process lifetimes and file access +patterns. Using this functionality requires additional code managed in +a separate repository from the core Netdata agent. You can either install +a pre-built copy of the required code, or build it locally. + +#### Installing the pre-built eBPF code + +We provide pre-built copies of the eBPF code for 64-bit x86 systems +using glibc or musl. To use one of these: + +1. Verify the release version that Netdata expects to be used by checking + the contents of `packaging/ebpf.version` in your Netdata sources. +2. Go to https://github.com/netdata/kernel-collector/releases, select the + required release, and download the `netdata-kernel-collector-*.tar.xz` + file for the libc variant your system uses (either rmusl or glibc). +3. Extract the contents of the archive to a temporary location, and then + copy all of the `.o` and `.so.*` files and the contents of the `library/` + directory to `/usr/libexec/netdata/plugins.d` or the equivalent location + for your build of Netdata. + +#### Building the eBPF code locally + +Alternatively, you may wish to build the eBPF code locally yourself. For +instructions, please consult [the README file for our kernel-collector +repository](https://github.com/netdata/kernel-collector/blob/master/README.md), +which outlines both the required dependencies, as well as multiple +options for building the code. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fsource&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) diff --git a/packaging/installer/methods/synology.md b/packaging/installer/methods/synology.md new file mode 100644 index 000000000..4a0ae3551 --- /dev/null +++ b/packaging/installer/methods/synology.md @@ -0,0 +1,52 @@ + + +# Install Netdata on Synology + +The documentation previously recommended installing the Debian Chroot package from the Synology community package +sources and then running Netdata from within the chroot. This does not work, as the chroot environment does not have +access to `/proc`, and therefore exposes very few metrics to Netdata. Additionally, [this +issue](https://github.com/SynoCommunity/spksrc/issues/2758), still open as of 2018/06/24, indicates that the Debian +Chroot package is not suitable for DSM versions greater than version 5 and may corrupt system libraries and render the +NAS unable to boot. + +The good news is that the [64-bit static installer](kickstart-64.md) works fine if your NAS is one that uses the amd64 architecture. It +will install the content into `/opt/netdata`, making future removal safe and simple. + +## Run as netdata user + +When Netdata is first installed, it will run as _root_. This may or may not be acceptable for you, and since other +installations run it as the `netdata` user, you might wish to do the same. This requires some extra work: + +1. Creat a group `netdata` via the Synology group interface. Give it no access to anything. +2. Create a user `netdata` via the Synology user interface. Give it no access to anything and a random password. Assign + the user to the `netdata` group. Netdata will chuid to this user when running. +3. Change ownership of the following directories, as defined in [Netdata + Security](/docs/netdata-security.md#security-design): + +```sh +chown -R root:netdata /opt/netdata/usr/share/netdata +chown -R netdata:netdata /opt/netdata/var/lib/netdata /opt/netdata/var/cache/netdata +chown -R netdata:root /opt/netdata/var/log/netdata +``` + +## Create startup script + +Additionally, as of 2018/06/24, the Netdata installer doesn't recognize DSM as an operating system, so no init script is +installed. You'll have to do this manually: + +1. Add [this file](https://gist.github.com/oskapt/055d474d7bfef32c49469c1b53e8225f) as `/etc/rc.netdata`. Make it + executable with `chmod 0755 /etc/rc.netdata`. +2. Add or edit `/etc/rc.local` and add a line calling `/etc/rc.netdata` to have it start on boot: + +```conf +# Netdata startup +[ -x /etc/rc.netdata ] && /etc/rc.netdata start +``` + +3. Make sure `/etc/rc.netdata` is executable: `chmod 0755 /etc/rc.netdata`. + +[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fpackaging%2Finstaller%2Fmethods%2Fsynology&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>) -- cgit v1.2.3