diff options
Diffstat (limited to 'packaging/installer/methods')
| -rw-r--r-- | packaging/installer/methods/cloud-providers.md | 126 | ||||
| -rw-r--r-- | packaging/installer/methods/freebsd.md | 107 | ||||
| -rw-r--r-- | packaging/installer/methods/freenas.md | 24 | ||||
| -rw-r--r-- | packaging/installer/methods/kickstart.md | 172 | ||||
| -rw-r--r-- | packaging/installer/methods/kubernetes.md | 197 | ||||
| -rw-r--r-- | packaging/installer/methods/macos.md | 111 | ||||
| -rw-r--r-- | packaging/installer/methods/manual.md | 240 | ||||
| -rw-r--r-- | packaging/installer/methods/offline.md | 66 | ||||
| -rw-r--r-- | packaging/installer/methods/pfsense.md | 83 | ||||
| -rw-r--r-- | packaging/installer/methods/source.md | 236 | ||||
| -rw-r--r-- | packaging/installer/methods/synology.md | 59 |
11 files changed, 1421 insertions, 0 deletions
diff --git a/packaging/installer/methods/cloud-providers.md b/packaging/installer/methods/cloud-providers.md new file mode 100644 index 0000000..bc5c9aa --- /dev/null +++ b/packaging/installer/methods/cloud-providers.md @@ -0,0 +1,126 @@ +<!-- +title: "Install Netdata on cloud providers" +description: "The Netdata Agent runs on all popular cloud providers, but often requires additional steps and configuration for full functionality." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/cloud-providers.md +--> + +# 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 the [`kickstart.sh` automatic installation script](kickstart.md). + +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: <name> +Type: Ingress +Targets: <name-tag> +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 ranges: 19999 +Protocol: TCP +Action: Allow +Priority: 310 +Name: Netdata +``` + +Click **Add** to apply your new inbound security rule. + + diff --git a/packaging/installer/methods/freebsd.md b/packaging/installer/methods/freebsd.md new file mode 100644 index 0000000..3523157 --- /dev/null +++ b/packaging/installer/methods/freebsd.md @@ -0,0 +1,107 @@ +<!-- +title: "Install Netdata on FreeBSD" +description: "Install Netdata on FreeBSD to monitor the health and performance of bare metal or VMs with thousands of real-time, per-second metrics." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freebsd.md +--> + +# 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 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. + + + +Starting with v1.30, Netdata collects anonymous usage information by default and sends it to a self hosted PostHog instance within the Netdata infrastructure. 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 <path>`| Install netdata in `<path>.` 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| +| `--disable-exporting-kinesis` | Disable AWS Kinesis exporting connector. Default: enable it when libaws_cpp_sdk_kinesis and libraries (it depends on are available)| +| `--enable-exporting-prometheus-remote-write` | Enable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available| +| `--disable-exporting-prometheus-remote-write` | Disable Prometheus remote write exporting connector. Default: enable it when libprotobuf and libsnappy are available| +| `--enable-exporting-mongodb` | Enable MongoDB exporting connector. Default: enable it when libmongoc is available| +| `--disable-exporting-mongodb` | Disable MongoDB exporting connector| +| `--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. (DISABLE_TELEMETRY=1)| + + diff --git a/packaging/installer/methods/freenas.md b/packaging/installer/methods/freenas.md new file mode 100644 index 0000000..a69f1e3 --- /dev/null +++ b/packaging/installer/methods/freenas.md @@ -0,0 +1,24 @@ +<!-- +title: "Install Netdata on FreeNAS" +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freenas.md +--> + +# 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 +``` + + diff --git a/packaging/installer/methods/kickstart.md b/packaging/installer/methods/kickstart.md new file mode 100644 index 0000000..2555e4a --- /dev/null +++ b/packaging/installer/methods/kickstart.md @@ -0,0 +1,172 @@ +<!-- +title: "Install Netdata with kickstart.sh" +description: "The kickstart.sh script installs Netdata from source, including all dependencies required to connect to Netdata Cloud, with a single command." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kickstart.md +--> +import { OneLineInstallWget, OneLineInstallCurl } from '@site/src/components/OneLineInstall/' + +# Install Netdata with kickstart.sh + +  + +This page covers detailed instructions on using and configuring the automatic one-line installation script named +`kickstart.sh`. + +The kickstart script works on all Linux distributions and macOS environments. By default, automatic nightly updates are enabled. If you are installing on macOS, make sure to check the [install documentation for macOS](macos.md) before continuing. + +> If you are unsure whether you want nightly or stable releases, read the [installation guide](/packaging/installer/README.md#nightly-vs-stable-releases). +> If you want to turn off [automatic updates](/packaging/installer/README.md#automatic-updates), use the `--no-updates` option. You can find more installation options below. + +To install Netdata, run the following as your normal user: + +<OneLineInstallWget/> + +Or, if you have cURL but not wget (such as on macOS): + +<OneLineInstallCurl/> + + +## 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. + +## Optional parameters to alter your installation + +The `kickstart.sh` script accepts a number of optional parameters to control how the installation process works: + +- `--non-interactive`: Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run. +- `--interactive`: Act as if running interactively, even if automatic detection indicates a run is non-interactive. +- `--dont-wait`: Synonym for `--non-interactive` +- `--dry-run`: Show what the installer would do, but don’t actually do any of it. +- `--dont-start-it`: Don’t auto-start the daemon after installing. This parameter is not guaranteed to work. +- `--release-channel`: Specify a particular release channel to install from. Currently supported release channels are: + - `nightly`: Installs a nightly build (this is currently the default). + - `stable`: Installs a stable release. + - `default`: Explicitly request whatever the current default is. +- `--nightly-channel`: Synonym for `--release-channel nightly`. +- `--stable-channel`: Synonym for `--release-channel stable`. +- `--auto-update`: Enable automatic updates (this is the default). +- `--no-updates`: Disable automatic updates. +- `--disable-telemetry`: Disable anonymous statistics. +- `--repositories-only`: Only install appropriate repository configuration packages (only for native install). +- `--native-only`: Only install if native binary packages are available. +- `--static-only`: Only install if a static build is available. +- `--build-only`: Only install using a local build. +- `--reinstall`: If an existing install is found, reinstall instead of trying to update it in place. +- `--reinstall-even-if-unsafe`: Even try to reinstall if we don't think we can do so safely (implies `--reinstall`). +- `--disable-cloud`: For local builds, don’t build any of the cloud code at all. For native packages and static builds, + use runtime configuration to disable cloud support. +- `--require-cloud`: Only install if Netdata Cloud can be enabled. Overrides `--disable-cloud`. +- `--install`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system), this option is deprecated and will be removed in a future version, please use `--install-prefix` instead. +- `--install-prefix`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system). +- `--install-version`: Specify the version of Netdata to install. +- `--old-install-prefix`: Specify the custom local build's installation prefix that should be removed. +- `--uninstall`: Uninstall an existing installation of Netdata. +- `--reinstall-clean`: Performs an uninstall of Netdata and clean installation. +- `--local-build-options`: Specify additional options to pass to the installer code when building locally. Only valid if `--build-only` is also specified. +- `--static-install-options`: Specify additional options to pass to the static installer code. Only valid if --static-only is also specified. +- `--prepare-offline-install-source`: Instead of insallling the agent, prepare a directory that can be used to install on another system without needing to download anything. See our [offline installation documentation](/packaging/installer/methods/offline.md) for more info. + +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): + +- `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 + 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. + +### Connect node to Netdata Cloud during installation + +The `kickstart.sh` script accepts additional parameters to automatically [connect](/claim/README.md) your node to Netdata Cloud immediately after installation. + +> Note: You either need to run the command with root privileges or run it with the user that is running the agent. More details: [Connect an agent without root privileges](/claim/README.md#connect-an-agent-without-root-privileges) section. + +To automatically claim nodes after installation: + +1. Sign in to [Netdata Cloud](https://app.netdata.cloud/sign-in?cloudRoute=/spaces) +2. Go to the [Spaces management area](https://learn.netdata.cloud/docs/cloud/spaces#manage-spaces) +3. Click on **Connect Nodes** +4. Find the `token` and `rooms` strings and specify your nodes: + +- `--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. +- `--claim-rooms`: Specify a comma-separated list of tokens for each War Room this node should appear in. +- `--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](/claim/README.md#connect-through-a-proxy) for details. +- `--claim-url`: Specify a URL to use when connecting to the cloud. Defaults to `https://api.netdata.cloud`. + +For example: + +```bash +wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 +``` + +### Native packages + +We publish official DEB/RPM packages 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. + +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. + +### Static builds + +We publish pre-built static builds 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. + + +## 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 +[ "<checksum-will-be-added-in-documentation-processing>" = "$(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. + + diff --git a/packaging/installer/methods/kubernetes.md b/packaging/installer/methods/kubernetes.md new file mode 100644 index 0000000..216703a --- /dev/null +++ b/packaging/installer/methods/kubernetes.md @@ -0,0 +1,197 @@ +<!-- +title: "Deploy Kubernetes monitoring with Netdata" +description: "Deploy Netdata to monitor a Kubernetes cluster to monitor the health, performance, resource utilization, and application metrics of a Kubernetes cluster in real time." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kubernetes.md +--> + +# Deploy Kubernetes monitoring with Netdata + +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 create a Kubernetes monitoring 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, responsible for collecting metrics from the node, Kubernetes control planes, +pods/containers, and [supported application-specific +metrics](https://github.com/netdata/helmchart#service-discovery-and-supported-services). + +To deploy Kubernetes monitoring with Netdata, 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. + +## 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 +``` + +Run `kubectl get services` and `kubectl get pods` to confirm that your cluster now runs a `netdata` service, one +parent pod, and multiple child pods. + +You've now installed Netdata on your Kubernetes cluster. Next, it's time to opt-in and enable the powerful Kubernetes +dashboards available in Netdata Cloud. + +## Connect your Kubernetes cluster to Netdata Cloud + +To start [Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualize/kubernetes/), you must first +[connect](/claim/README.md) your Kubernetes cluster to [Netdata Cloud](https://app.netdata.cloud). The connection process securely +connects your Kubernetes cluster to stream metrics data to Netdata Cloud, enabling Kubernetes-specific visualizations +like the health map and time-series composite charts. + +### New installations + +First, find the script to run an `helm install` command. You can get it by clicking on your Space's dropdown, then **Manage your Space**. +Click the **Nodes** tab and select the environment your node is running, in this case **kubernetes**, to reveal the script for your Space in Netdata Cloud. You need the `TOKEN` +and `ROOM` values. + +The script should be similar to: + +```bash +helm install netdata netdata/netdata --set parent.claiming.enabled="true" --set parent.claiming.token="TOKEN" --set parent.claiming.rooms="ROOM" --set child.claiming.enabled=true --set child.claiming.token="TOKEN" --set child.claiming.rooms="ROOM" +``` + +### Existing installations + +On an existing installation, you will need to override the configuration values by running the `helm upgrade` command and provide a file with the values to override. You can start with creating a file called `override.yml`. + +```bash +touch override.yml +``` + +Paste the following into your `override.yml` file, replacing instances of `ROOM` and `TOKEN` with those from the script from Netdata Cloud. These settings connect your `parent`/`child` nodes to Netdata Cloud and store more +metrics in the nodes' time-series databases. + +```yaml +parent: + claiming: + enabled: true + token: "TOKEN" + rooms: "ROOM" + +child: + claiming: + enabled: true + token: "TOKEN" + rooms: "ROOM" + configs: + netdata: + data: | + [global] + memory mode = ram + history = 3600 + [health] + enabled = no +``` + +> ❗ These override settings, along with the Helm chart's defaults, will retain an hour's worth of metrics (`history = +> 3600`, or `3600 seconds`) on each child node. Based on your metrics retention needs, and the resources available on +> your cluster, you may want to increase the `history` setting. + +Apply these new settings: + +```bash +helm upgrade -f override.yml netdata netdata/netdata +``` + +The cluster terminates the old pods and creates new ones with the proper persistence and connection configuration. You'll +see your nodes, containers, and pods appear in Netdata Cloud in a few seconds. + + + +If you don't need to configure your Netdata deployment, [skip down](#whats-next) to see how Kubernetes monitoring works +in Netdata, in addition to more guides and resources. + +## Configure your Netdata monitoring deployment + +Read up on the various configuration options in the [Helm chart +documentation](https://github.com/netdata/helmchart#configuration) if you need to tweak your Kubernetes monitoring. + +Your first option is to create an `override.yml` file, if you haven't created one already for +[connect](#connect-your-kubernetes-cluster-to-netdata-cloud), then apply the new configuration to your cluster with `helm +upgrade`. + +```bash +helm upgrade -f override.yml netdata netdata/netdata +``` + +If you want to change only a single setting, use the `--set` argument with `helm upgrade`. For example, to change the +size of the persistent metrics volume on the parent node: + +```bash +helm upgrade --set parent.database.volumesize=4Gi netdata netdata/netdata +``` + +### Configure service discovery + +Netdata's [service discovery](https://github.com/netdata/agent-service-discovery/#service-discovery), installed as part +of the Helm chart installation, finds what services are running in a cluster's containers and automatically collects +service-level metrics from them. + +Service discovery supports [popular applications](https://github.com/netdata/helmchart#applications) and [Prometheus +endpoints](https://github.com/netdata/helmchart#prometheus-endpoints). + +If your cluster runs services on non-default ports or uses non-default names, you may need to configure service +discovery to start collecting metrics from your services. You have to edit the default ConfigMap that is shipped with +the Helmchart and deploy that to your cluster. + +First, copy the default 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 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 upgrade --set-file sd.child.configmap.from.value=./child.yml netdata netdata/netdata +``` + +Now that you pushed an edited ConfigMap to your cluster, service discovery should find and set up metrics collection +from your non-default service. + +## 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 +``` + +To update Netdata's Helm chart to the latest version, run `helm repo update`, then deploy `upgrade` it`: + +```bash +helm repo update +helm upgrade netdata netdata/netdata +``` + +## What's next? + +[Start Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualize/kubernetes/) in Netdata Cloud, which +comes with meaningful visualizations out of the box. + +Read our guide, [_Kubernetes monitoring with Netdata: Overview and +visualizations_](/docs/guides/monitor/kubernetes-k8s-netdata.md), for a complete walkthrough of Netdata's Kubernetes +monitoring capabilities, including a health map of every container in your infrastructure, aggregated resource +utilization metrics, and application metrics. + +### Related reference documentation + +- [Netdata Cloud · Kubernetes monitoring](https://learn.netdata.cloud/docs/cloud/visualize/kubernetes/) +- [Netdata Helm chart](https://github.com/netdata/helmchart) +- [Netdata service discovery](https://github.com/netdata/agent-service-discovery/) + + diff --git a/packaging/installer/methods/macos.md b/packaging/installer/methods/macos.md new file mode 100644 index 0000000..a1b5f60 --- /dev/null +++ b/packaging/installer/methods/macos.md @@ -0,0 +1,111 @@ +<!-- +title: "Install Netdata on macOS" +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/macos.md +--> + +# 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). + +You can install Netdata in one of the three following ways: + +- **[Install Netdata with the our automatic one-line installation script (recommended)](#install-netdata-with-our-automatic-one-line-installation-script)**, +- [Install Netdata via Homebrew](#install-netdata-via-homebrew) +- [Install Netdata from source](#install-netdata-from-source) + +Each of these installation option requires [Homebrew](https://brew.sh/) for handling dependencies. + +> The Netdata Homebrew package is community-created and -maintained. +> Community-maintained packages _may_ receive support from Netdata, but are only a best-effort affair. Learn more about [Netdata's platform support policy](/packaging/PLATFORM_SUPPORT.md). + +## Install Netdata with our automatic one-line installation script + +**Local Netdata Agent installation** +To install Netdata using our automatic [kickstart](/packaging/installer/README.md#automatic-one-line-installation-script) open a new terminal and run: + +```bash +curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh +``` +The Netdata Agent is installed under `/usr/local/netdata`. Dependencies are handled via Homebrew. + +**Automatically connect to Netdata Cloud during installation** +<!-- Potential reuse: https://learn.netdata.cloud/docs/agent/claim#connect-an-agent-running-in-macos--> +<!--Potential reuse https://learn.netdata.cloud/docs/agent/packaging/installer/methods/kickstart#connect-node-to-netdata-cloud-during-installation The following information is copied from this link.--> + +The `kickstart.sh` script accepts additional parameters to automatically [connect](/claim/README.md) your node to Netdata +Cloud immediately after installation. Find the `token` and `rooms` strings by [signing in to Netdata +Cloud](https://app.netdata.cloud/sign-in?cloudRoute=/spaces), then clicking on **Connect Nodes** in the [Spaces management +area](https://learn.netdata.cloud/docs/cloud/spaces#manage-spaces). + +- `--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. +- `--claim-rooms`: Specify a comma-separated list of tokens for each War Room this node should appear in. +- `--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](/claim/README.md#connect-through-a-proxy) for details. +- `--claim-url`: Specify a URL to use when connecting to the cloud. Defaults to `https://api.netdata.cloud`. + +For example: +```bash +curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud +``` +The Netdata Agent is installed under `/usr/local/netdata` on your machine. Your machine will also show up as a node in your Netdata Cloud. + +If you experience issues while claiming your node, follow the steps in our [Troubleshooting](/claim/README.md#troubleshooting) documentation. +## Install Netdata via Homebrew + +To install Netdata and all its dependencies, run Homebrew using the following command: + +```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. + +1. Open your terminal of choice and install the Xcode development packages: + + ```bash + xcode-select --install + ``` + +2. Click **Install** on the Software Update popup window that appears. +3. Use the same terminal session to install some of Netdata's prerequisites using Homebrew. If you don't want to use [Netdata Cloud](https://learn.netdata.cloud/docs/cloud/), you can omit `cmake`. + + ```bash + brew install ossp-uuid autoconf automake pkg-config libuv lz4 json-c openssl libtool cmake + ``` + +4. Download Netdata from our GitHub repository: + + ```bash + git clone https://github.com/netdata/netdata.git --recursive + ``` + +5. `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/`. +> 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). + + + diff --git a/packaging/installer/methods/manual.md b/packaging/installer/methods/manual.md new file mode 100644 index 0000000..d320753 --- /dev/null +++ b/packaging/installer/methods/manual.md @@ -0,0 +1,240 @@ +<!-- +title: "Install Netdata on Linux from a Git checkout" +description: "Use the Netdata Agent source code from GitHub, plus helper scripts to set up your system, to install Netdata without packages or binaries." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/manual.md +--> + +# 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. + +- **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`, `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 libssl-dev libelf-dev libmnl-dev libprotobuf-dev protobuf-compiler gcc g++ make git autoconf autoconf-archive autogen automake pkg-config curl python cmake + +# Fedora +dnf install zlib-devel libuuid-devel libuv-devel lz4-devel openssl-devel elfutils-libelf-devel libmnl-devel protobuf-devel protobuf-compiler gcc gcc-c++ make git autoconf autoconf-archive autogen automake pkgconfig curl findutils python cmake + +# CentOS / Red Hat Enterprise Linux +yum install autoconf automake curl gcc gcc-c++ git libmnl-devel libuuid-devel openssl-devel libuv-devel lz4-devel elfutils-libelf-devel protobuf protobuf-devel protobuf-compiler make nc pkgconfig python zlib-devel cmake + +# openSUSE +zypper install zlib-devel libuuid-devel libuv-devel liblz4-devel libopenssl-devel libelf-devel libmnl-devel protobuf-devel gcc gcc-c++ 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**<br/>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**<br/>this package is required only if the system has python v2. python v3 has this functionality embedded| +| `python-mysqldb`<br/>or<br/>`python-pymysql`|used for monitoring **mysql** or **mariadb** databases<br/>`python-mysqldb` is a lot faster and thus preferred| +| `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| +| `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 | +| `protobuf`| Used for the new Cloud<->Agent binary protocol + +*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 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 --recursive +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`. + +## Optional parameters to alter your installation + +`netdata-installer.sh` accepts a few parameters to customize your installation: + +- `--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. + +### Connect node to Netdata Cloud during installation + +Unlike the [`kickstart.sh`](/packaging/installer/methods/kickstart.md), the `netdata-installer.sh` script does +not allow you to automatically [connect](/claim/README.md) your node to Netdata Cloud immediately after installation. + +See the [connect to cloud](/claim/README.md) doc for details on connecting a node with a manual installation of 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. + + diff --git a/packaging/installer/methods/offline.md b/packaging/installer/methods/offline.md new file mode 100644 index 0000000..5e92976 --- /dev/null +++ b/packaging/installer/methods/offline.md @@ -0,0 +1,66 @@ +<!-- +title: "Install Netdata on offline systems" +description: "Install the Netdata Agent on offline/air gapped systems to benefit from real-time, per-second monitoring without connecting to the internet." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/offline.md +--> + +# Install Netdata on offline systems + +Our kickstart install script provides support for installing the Netdata Agent on systems which do not have a +usable internet connection by prefetching all of the required files so that they can be copied to the target system. +Currently, we only support using static installs with this method. There are tentative plans to support building +locally on offline systems as well, but there is currently no estimate of when this functionality may be implemented. + +Users who wish to use native packages on offline systems may be able to do so using whatever tooling their +distribution already provides for offline package management (such as `apt-offline` on Debian or Ubuntu systems), +but this is not officially supported. + +## Preparing the offline installation source + +The first step to installing Netdata on an offline system is to prepare the offline installation source. This can +be as a regular user from any internet connected system that has the following tools available: + +- cURL or wget +- sha256sum or shasum +- A standard POSIX compliant shell + +To prepare the offline installation source, simply run: + +```bash +wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh --prepare-offline-install-source ./netdata-offline +``` + +or + +```bash +curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --prepare-offline-install-source ./netdata-offline +``` + +> The exact name used for the directory does not matter, you can specify any other name you want in place of `./netdata-offline`. + +This will create a directory called `netdata-offline` in the current directory and place all the files required for an offline install in it. + +If you want to use a specific release channel (nightly or stable), it _must_ be specified on this step using the +apporpriate option for the kickstart script. + +## Installing on the target system + +Once you have prepared the offline install source, you need to copy the offline install source directory to the +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 +customization of the installation, though it will default to not enabling automatic updates (as they are not +supported on offline installs). + +## 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. diff --git a/packaging/installer/methods/pfsense.md b/packaging/installer/methods/pfsense.md new file mode 100644 index 0000000..e055662 --- /dev/null +++ b/packaging/installer/methods/pfsense.md @@ -0,0 +1,83 @@ +<!-- +title: "Install Netdata on pfSense" +description: "Install Netdata on pfSense to monitor the health and performance of firewalls with thousands of real-time, per-second metrics." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/pfsense.md +--> + +# 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:12:amd64/latest/All/json-c-0.15_1.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-certifi-2021.10.8.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-asn1crypto-1.4.0.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-pycparser-2.20.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-cffi-1.14.6.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-six-1.16.0.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-cryptography-3.3.2.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-idna-2.10.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-openssl-20.0.1.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-pysocks-1.7.1.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-urllib3-1.26.7,1.txz +pkg add http://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/py38-yaml-5.4.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:12:amd64/latest/All/netdata-1.31.0_1.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://<pfsenseIP>: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`. + Alternatively more information can be found in +<https://doc.pfsense.org/index.php/Installing_FreeBSD_Packages>, 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 <https://redmine.pfsense.org/issues/6643> + +**Note:** In pfSense, the Netdata configuration files are located under `/usr/local/etc/netdata`. + + diff --git a/packaging/installer/methods/source.md b/packaging/installer/methods/source.md new file mode 100644 index 0000000..d8f4f0b --- /dev/null +++ b/packaging/installer/methods/source.md @@ -0,0 +1,236 @@ +<!-- +title: "Manually build Netdata from source" +description: "Package maintainers and power users may be interested in manually building Netdata from source without using any of our installation scripts." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/source.md +--> + +# 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). +- 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) + - protobuf (Google Protocol Buffers) and protoc compiler + +## 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 +#### 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` from 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. + + diff --git a/packaging/installer/methods/synology.md b/packaging/installer/methods/synology.md new file mode 100644 index 0000000..30ec303 --- /dev/null +++ b/packaging/installer/methods/synology.md @@ -0,0 +1,59 @@ +<!-- +title: "Install Netdata on Synology" +description: "The Netdata Agent can be installed on AMD64-compatible NAS systems using the 64-bit pre-compiled static binary." +custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/synology.md +--> + +# Install Netdata on Synology + +> 💡 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, before proceeding. +> +> You can help improve this document by +> [submitting a PR](https://github.com/netdata/netdata/edit/master/packaging/installer/methods/synology.md) +> with your recommended improvements or changes. Thank you! + + +The good news is that our [one-line installation script](kickstart.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. Create 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 +``` + +4. Restart Netdata + +```sh +/etc/rc.netdata restart +``` + +## 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`. + + |