@cryptotaxi247 / netdata-1 / commits / f7fb97708

Installation-Static Build-Windows (#20122)

Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>

kanelatechnical committed Apr 16, 2025 at 14:54 UTC f7fb97708648fb3f76833c7d629210a4eeb73cc0
9 files changed +660 -469
packaging/installer/UPDATE.md
+1 -1
@@ -101,4 +101,4 @@ The following configuration options are currently supported:
101
102 - `NETDATA_UPDATER_JITTER`: Sets an upper limit in seconds on the random delay in the updater script when running as a scheduled task. This random delay helps avoid issues resulting from too many nodes trying to reconnect to the Cloud at the same time. The default value is 3600, which corresponds to one hour. Most users shouldn’t ever need to change this.
103 - `NETDATA_MAJOR_VERSION_UPDATES`: If set to a value other than 0, then new major versions will be installed without user confirmation. Must be set to a non-zero value for automated updates to install new major versions.
104 -- `NETDATA_NO_SYSTEMD_JOURNAL`: If set to a value other than 0, skip attempting to install the `netdata-plugin-systemd-journal` package on supported systems on update. The updater will install this optional package by default on supported systems if this option is not set. It only affects systems using native packages.
104 +- `NETDATA_NO_SYSTEMD_JOURNAL`: If set to a value other than 0, skip attempting to install the `netdata-plugin-systemd-journal` package on supported systems on update. The updater will install this optional package by default on supported systems if this option is not set. It only affects systems using native packages.
\ No newline at end of file
packaging/installer/methods/ansible.md
+61 -58
@@ -1,28 +1,49 @@
1 # Deploy Netdata with Ansible
2
3 -How do you quickly set up infrastructure monitoring? How can you efficiently deploy Netdata across multiple nodes? How do you make sure the deployment is **reliable, repeatable, and idempotent**? And how can you manage monitoring as **code**?
3 +Meet [Ansible](https://ansible.com), a popular tool for provisioning, configuration management, and infrastructure as code (IaC).
4
5 -Meet [Ansible](https://ansible.com), a popular tool for provisioning, configuration management, and infrastructure as code (IaC). It uses **playbooks** to streamline operations with simple syntax, running them securely over SSH—no agent required. That means less setup and more focus on your application and monitoring.
5 +This guide walks you through deploying the **Netdata Agent** across multiple nodes using an [Ansible playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), managing configurations, and connecting to **Netdata Cloud**—all in minutes.
6
7 -What does **idempotent** mean?
8 -From the [Ansible glossary](https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html)
7 +What does **idempotent** mean? From the [Ansible glossary](https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html):
8
10 -> An operation is **idempotent** if running it once produces the same result as running it multiple times, without unintended changes. With Ansible, you can deploy Netdata repeatedly without disrupting your infrastructure—ensuring monitoring as code.
9 +> With Ansible, you can deploy Netdata repeatedly without disrupting your infrastructure—ensuring monitoring as code.
10
11 This guide walks you through deploying the **Netdata Agent** across multiple nodes using an [Ansible playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), managing configurations, and connecting to **Netdata Cloud**—all in minutes.
12
13 +> With Ansible, you can deploy Netdata repeatedly without disrupting your infrastructure—ensuring monitoring as code.
14 +
15 +---
16 +
17 ## Prerequisites
18
16 -- A Netdata Cloud account. [Sign in and create one](https://app.netdata.cloud) if you don't have one already.
19 +- Netdata Cloud account. [Sign in and create one](https://app.netdata.cloud) if you don't have one already.
20 - An administration system with [Ansible](https://www.ansible.com/) installed.
18 -- One or more nodes that your administration system can access via [SSH public
19 - keys](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) (preferably password-less).
21 +- One or more nodes that your administration system can access via [SSH public keys](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) (preferably password-less).
22 +
23 +---
24 +
25 +## Deployment Architecture
26 +
27 +Below is a visual representation of the deployment architecture, illustrating the relationship between the host system, Docker, the Netdata container, and key mounts/privileges.
28
21 -## Download and configure the playbook
29 +```mermaid
30 +graph TD
31 + A[Host System] -->|SSH| B[Ansible]
32 + B -->|Deploys| C[Netdata Agent]
33 + C -->|Collects Metrics| D[Monitored Services]
34 + C -->|Sends Data| E[Netdata Cloud]
35 + subgraph " "
36 + direction TB
37 + D
38 + E
39 + end
40 +```
41 +
42 +---
43 +
44 +## Download and Configure the Playbook
45
23 -First, download the
24 -[playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), move it to the
25 -current directory, and remove the rest of the cloned repository, as it's not required for using the Ansible playbook.
46 +First, download the [playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), move it to the current directory, and remove the rest of the cloned repository, as it's not required for using the Ansible playbook.
47
48 ```bash
49 git clone https://github.com/netdata/community.git
@@ -30,95 +51,77 @@ mv community/configuration-management/ansible-quickstart .
51 rm -rf community
52 ```
53
33 -Or if you don't want to clone the entire repository, use the [gitzip browser extension](https://gitzip.org/) to get the netdata-agent-deployment directory as a zip file.
54 +Or if you don't want to clone the entire repository, use the [gitzip browser extension](https://gitzip.org/) to get the `netdata-agent-deployment` directory as a zip file.
55
35 -Next, `cd` into the Ansible directory.
56 +Next, navigate into the Ansible directory.
57
58 ```bash
59 cd ansible-quickstart
60 ```
61
41 -### Edit the `hosts` file
62 +---
63
43 -The `hosts` file contains a list of IP addresses or hostnames that Ansible will try to run the playbook against. The
44 -`hosts` file that comes with the repository contains two example IP addresses, which you should replace according to the
45 -IP address/hostname of your nodes.
64 +### Edit the `hosts` File
65 +
66 +The `hosts` file contains a list of IP addresses or hostnames that Ansible will target. Replace the example IP addresses with those of your nodes.
67
68 ```text
69 203.0.113.0 hostname=node-01
49 -203.0.113.1 hostname=node-02
70 +203.0.113.1 hostname=node-02
71 ```
72
52 -You can also set the `hostname` variable, which appears both on the local Agent dashboard and Netdata Cloud, or you can
53 -omit the `hostname=` string entirely to use the system's default hostname.
73 +You can also set the `hostname` variable, which appears both on the local Agent dashboard and Netdata Cloud, or omit the `hostname=` string entirely to use the system's default hostname.
74
55 -#### Set the login user (optional)
75 +#### Set the Login User (Optional)
76
57 -If you SSH into your nodes as a user other than `root`, you need to configure `hosts` according to those user names. Use
58 -the `ansible_user` variable to set the login user. For example:
77 +If you SSH into your nodes as a user other than `root`, configure `hosts` accordingly using the `ansible_user` variable. For example:
78
79 ```text
80 203.0.113.0 hostname=ansible-01 ansible_user=example
81 ```
82
64 -#### Set your SSH key (optional)
83 +#### Set Your SSH Key (Optional)
84
66 -If you use an SSH key other than `~/.ssh/id_rsa` for logging into your nodes, you can set that on a per-node basis in
67 -the `hosts` file with the `ansible_ssh_private_key_file` variable. For example, to log into a Lightsail instance using
68 -two different SSH keys supplied by AWS.
85 +If you use an SSH key other than `~/.ssh/id_rsa` for logging into your nodes, specify it per node in the `hosts` file with the `ansible_ssh_private_key_file` variable. For example:
86
87 ```text
88 203.0.113.0 hostname=ansible-01 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-west-2.pem
89 203.0.113.1 hostname=ansible-02 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-east-1.pem
90 ```
91
75 -### Edit the `vars/main.yml` file
92 +---
93
77 -In order to connect your node(s) to your Space in Netdata Cloud, and see all their metrics in real-time in composite
78 -charts or perform [Metric
79 -Correlations](/docs/metric-correlations.md), you need to set the `claim_token`
80 -and `claim_room` variables.
94 +### Edit the `vars/main.yml` File
95
82 -To find your `claim_token` and `claim_room`, go to Netdata Cloud, then click on your Space's name in the top navigation,
83 -then click on **Manage your Space**. Click on the **Nodes** tab in the panel that appears, which displays a script with
84 -`token` and `room` strings.
96 +To connect your node(s) to your Space in Netdata Cloud and see all their metrics in real-time, set the `claim_token` and `claim_rooms` variables.
97
86 -![Animated GIF of finding the claiming script and the token and room
87 -strings](https://user-images.githubusercontent.com/1153921/98740235-f4c3ac00-2367-11eb-8ffd-e9ab0f04c463.gif)
98 +To find your `claim_token` and `claim_rooms`, go to Netdata Cloud, click on your Space's name in the top navigation, then click on **Manage your Space**. Click on the **Nodes** tab in the panel that appears, which displays a script with `token` and `room` strings.
99
100 Copy those strings into the `claim_token` and `claim_rooms` variables.
101
102 ```yml
92 -claim_token: XXXXX
93 -claim_rooms: XXXXX
103 +claim_token: YOUR_CLAIM_TOKEN
104 +claim_rooms: YOUR_CLAIM_ROOMS
105 ```
106
96 -Change the `dbengine_multihost_disk_space` if you want to change the metrics retention policy by allocating more or less
97 -disk space for storing metrics. The default is 2048 Mib, or 2 GiB.
107 +Adjust the `dbengine_multihost_disk_space` variable to change the metrics retention policy by allocating more or less disk space for storing metrics. The default is 2048 MiB (2 GiB).
108 +
109 +Since this node connects to Netdata Cloud, we'll view its dashboards there instead of using its IP or hostname. The playbook disables the local dashboard by setting `web_mode` to `none`, adding a small security boost by preventing unwanted access.
110
99 -Since this node connects to Netdata Cloud, we’ll view its dashboards there instead of using its IP or hostname. The playbook disables the local dashboard by setting `web_mode` to `none`, adding a small security boost by preventing unwanted access.
111 +You can read more about this decision, or other ways to lock down the local dashboard, in our [node security documentation](https://learn.netdata.cloud/docs/netdata-agent/security/overview).
112
101 -You can read more about this decision, or other ways you might lock down the local dashboard, in our [node security
102 -doc](/docs/security-and-privacy-design/README.md).
113 +> Curious about why Netdata's dashboard is open by default? Read our [blog post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) on that zero-configuration design decision.
114
104 -> Curious about why Netdata's dashboard is open by default? Read our [blog
105 -> post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) on that zero-configuration design decision.
115 +---
116
107 -## Run the playbook
117 +## Run the Playbook
118
109 -Time to run the playbook from your administration system:
119 +Execute the playbook from your administration system:
120
121 ```bash
122 ansible-playbook -i hosts tasks/main.yml
123 ```
124
115 -Ansible first connects to your node(s) via SSH, then [collects
116 -facts](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html#ansible-facts) about the system.
117 -This playbook doesn’t use these facts yet, but you can expand it to set up systems based on your infrastructure.
118 -
119 -Next, Ansible makes changes to each node according to the `tasks` defined in the playbook, and
120 -[returns](https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#changed) whether each
121 -task results in a changed, failure, or was skipped entirely.
125 +Ansible connects to your node(s) via SSH, collects [facts](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html#ansible-facts) about the system, and then applies the defined tasks.
126
123 -The task to install Netdata will take a few minutes per node, so be patient! Once the playbook reaches the connect to Cloud
124 -task, your nodes start populating your Space in Netdata Cloud.
127 +The task to install Netdata may take a few minutes per node. Once the playbook reaches the "connect to Cloud" task, your nodes will start appearing in your Space in Netdata Cloud.
\ No newline at end of file
packaging/installer/methods/freebsd.md
+107 -104
@@ -1,134 +1,137 @@
1 # Install Netdata on FreeBSD
2
3 -> 💡 This document is maintained by Netdata's community, and may not be completely up-to-date. Please double-check the
4 -> details of the installation process, such as version numbers for downloadable packages, before proceeding.
5 ->
6 -> You can help improve this document by [submitting a
7 -> PR](https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freebsd.md) with your recommended
8 -> improvements or changes. Thank you!
3 +> 💡 This guide is community-maintained and might not always reflect the latest details (like package versions).
4 +> Double-check before proceeding!
5 +> Want to help? [Submit a PR!](https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freebsd.md)
6
10 -## Install dependencies
7 +---
8
12 -This step needs root privileges.
9 +## 1. Install dependencies
10
14 -```sh
11 +Run as `root`:
12 +
13 +```bash
14 pkg install bash e2fsprogs-libuuid git curl autoconf automake pkgconf pidof liblz4 libuv json-c cmake gmake
15 ```
16
18 -Please respond in the affirmative for any relevant prompts during the installation process.
17 +Approve any prompts that appear.
18
20 -## Install Netdata
19 +---
20
22 -The simplest method is to use the single line [kickstart script](/packaging/installer/methods/kickstart.md)
21 +## 2. Choose an Installation Method
22
24 -If you have a Netdata Cloud account, clicking on the **Connect Nodes** button will generate the kickstart command you should use. Use the command from the "Linux" tab, it should look something like this:
23 +### Option A: Kickstart Installer (Recommended)
24
26 -```sh
27 -wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token <CLAIM_TOKEN> --claim-url https://app.netdata.cloud
28 -```
25 +The simplest approach is to use our one-line [kickstart installer](/packaging/installer/methods/kickstart.md).
26
30 -Please respond in the affirmative for any relevant prompts during the installation process.
27 +- Prepare the installation command:
28 + - For Netdata Cloud users: Navigate to your Space, click **Add Nodes** → Copy the command from the "Linux" tab.
29 + - For standalone installation, use the example below.
30
32 -Once the installation is completed, you should be able to start monitoring the FreeBSD server using Netdata.
31 +- Run the installation command:
32 + ```bash
33 + wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token <YOUR_TOKEN> --claim-url https://app.netdata.cloud
34 + ```
35 + > Replace `<YOUR_TOKEN>` with your actual claim token.
36
34 -Netdata can also be installed via [FreeBSD ports](https://www.freshports.org/net-mgmt/netdata).
37 +- After installation, access your Netdata dashboard at:
38
36 -## Manual installation
39 + ```
40 + http://NODE:19999
41 + ```
42
38 -If you would prefer to manually install Netdata, the following steps can help you do this.
43 + (`NODE` = your FreeBSD machine's hostname or IP)
44
40 -Download Netdata:
45 +---
46
42 -```sh
43 -fetch https://github.com/netdata/netdata/releases/download/v1.36.1/netdata-v1.36.1.tar.gz
44 -```
47 +### Option B: FreeBSD Ports Installation
48
46 -> ⚠️ Verify the latest version by either navigating to [Netdata's latest
47 -> release](https://github.com/netdata/netdata/releases/latest) or using `curl`:
48 ->
49 -> ```bash
50 -> basename $(curl -Ls -o /dev/null -w %{url_effective} https://github.com/netdata/netdata/releases/latest)
51 -> ```
49 +Netdata is also available through the FreeBSD Ports collection:
50
53 -Unzip the downloaded file:
51 +https://www.freshports.org/net-mgmt/netdata/
52
55 -```sh
56 -gunzip netdata*.tar.gz && tar xf netdata*.tar && rm -rf netdata*.tar
57 -```
53 +---
54
59 -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**):
55 +### Option C: Manual Installation (For Advanced Users)
56
61 -```sh
62 -cd netdata-v* && ./netdata-installer.sh --install-prefix /opt
63 -```
57 +- Download the latest Netdata release:
58
65 -You also need to enable the `netdata` service in `/etc/rc.conf`:
59 + ```bash
60 + fetch https://github.com/netdata/netdata/releases/latest/download/netdata-latest.tar.gz
61 + ```
62
67 -```sh
68 -sysrc netdata_enable="YES"
69 -```
63 + Or download a specific version:
64 +
65 + ```bash
66 + fetch https://github.com/netdata/netdata/releases/download/v2.3.2/netdata-v2.3.2.tar.gz
67 + ```
68 +
69 +- Extract the downloaded archive:
70 +
71 + ```bash
72 + tar -xzf netdata*.tar.gz && rm netdata*.tar.gz
73 + ```
74 +
75 +- Install Netdata to `/opt/netdata`:
76 +
77 + ```bash
78 + cd netdata-v*
79 + ./netdata-installer.sh --install-prefix /opt
80 + ```
81 +
82 +- Configure Netdata to start automatically at boot:
83 +
84 + ```bash
85 + sysrc netdata_enable="YES"
86 + ```
87
71 -Finally, and very importantly, update Netdata using the script provided by the Netdata team (**need root permission**):
88 +- Start the Netdata service:
89
73 -```sh
74 -cd /opt/netdata/usr/libexec/netdata/ && ./netdata-updater.sh
90 + ```bash
91 + service netdata start
92 + ```
93 +
94 +---
95 +
96 +## 3. Updating Netdata Installation
97 +
98 +If you enabled auto-updates with `--auto-update`, no further action is needed.
99 +
100 +For manual updates:
101 +
102 +```bash
103 +cd /opt/netdata/usr/libexec/netdata/
104 +./netdata-updater.sh
105 ```
106
77 -You can now access the Netdata dashboard by navigating to `http://NODE:19999`, replacing `NODE` with the IP address or hostname of your system.
78 -
79 -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
80 -more about the information collected and how to opt-out, check the [anonymous statistics
81 -page](/docs/netdata-agent/configuration/anonymous-telemetry-events.md).
82 -
83 -## Updating the Agent on FreeBSD
84 -
85 -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.
86 -The `netdata-updater.sh` script will update your Agent.
87 -
88 -## Optional parameters to alter your installation
89 -
90 -The `kickstart.sh` script accepts a number of optional parameters to control how the installation process works:
91 -
92 -- `--non-interactive`: Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run.
93 -- `--interactive`: Act as if running interactively, even if automatic detection indicates a run is non-interactive.
94 -- `--dont-wait`: Synonym for `--non-interactive`
95 -- `--dry-run`: Show what the installer would do, but don’t actually do any of it.
96 -- `--dont-start-it`: Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
97 -- `--release-channel`: Specify a particular release channel to install from. Currently supported release channels are:
98 - - `nightly`: Installs a nightly build (this is currently the default).
99 - - `stable`: Installs a stable release.
100 - - `default`: Explicitly request whatever the current default is.
101 -- `--nightly-channel`: Synonym for `--release-channel nightly`.
102 -- `--stable-channel`: Synonym for `--release-channel stable`.
103 -- `--auto-update`: Enable automatic updates (this is the default).
104 -- `--no-updates`: Disable automatic updates.
105 -- `--disable-telemetry`: Disable anonymous statistics.
106 -- `--native-only`: Only install if native binary packages are available.
107 -- `--static-only`: Only install if a static build is available.
108 -- `--build-only`: Only install using a local build.
109 -- `--install-prefix`: Specify an installation prefix for local builds (by default, we use a sane prefix based on the type of system).
110 -- `--install-version`: Specify the version of Netdata to install.
111 -- `--old-install-prefix`: Specify the custom local build's installation prefix that should be removed.
112 -- `--local-build-options`: Specify additional options to pass to the installer code when building locally. Only valid if `--build-only` is also specified.
113 -- `--static-install-options`: Specify additional options to pass to the static installer code. Only valid if --static-only is also specified.
114 -
115 -The following options are mutually exclusive and specify special operations other than trying to install Netdata normally or update an existing install:
116 -
117 -- `--reinstall`: If there is an existing install, reinstall it instead of trying to update it. If there is not an existing install, install netdata normally.
118 -- `--reinstall-even-if-unsafe`: If there is an existing install, reinstall it instead of trying to update it, even if doing so is known to potentially break things (for example, if we cannot detect what type of installation it is). If there is not an existing install, install Netdata normally.
119 -- `--reinstall-clean`: If there is an existing install, uninstall it before trying to install Netdata. Fails if there is no existing install.
120 -- `--uninstall`: Uninstall an existing installation of Netdata. Fails if there is no existing install.
121 -- `--claim-only`: If there is an existing install, only try to connect it without attempting to update it. If there is no existing install, install and connect Netdata normally.
122 -- `--repositories-only`: Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
123 -- `--prepare-offline-install-source`: Instead of installing 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.
124 -
125 -Additionally, the following environment variables may be used to further customize how the script runs (most users
126 -should not need to use special values for any of these):
127 -
128 -- `TMPDIR`: Used to specify where to put temporary files. On most systems, the default we select automatically
129 - should be fine. The user running the script needs to both be able to write files to the temporary directory,
130 - and run files from that location.
131 -- `ROOTCMD`: Used to specify a command to use to run another command with root privileges if needed. By default
132 - we try to use sudo, doas, or pkexec (in that order of preference), but if you need special options for one of
133 - those to work, or have a different tool to do the same thing on your system, you can specify it here.
134 -- `DISABLE_TELEMETRY`: If set to a value other than 0, behave as if `--disable-telemetry` was specified.
107 +---
108 +
109 +## Optional Kickstart Parameters
110 +
111 +| Option | Description |
112 +|------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
113 +| `--non-interactive` | Skip prompts and assume yes. |
114 +| `--interactive` | Force interactive prompts. |
115 +| `--release-channel stable` | Install stable builds (instead of nightly). |
116 +| `--no-updates` | Disable auto-updates. |
117 +| `--disable-telemetry` | Disable anonymous statistics. |
118 +| `--native-only` | Install only if native packages are available. |
119 +| `--static-only` | Install only if static builds are available. |
120 +| `--install-prefix /opt` | Change installation directory. |
121 +| `--prepare-offline-install-source ./netdata-offline` | Prepare offline installation source. See [Offline Install Guide](/packaging/installer/methods/offline.md). |
122 +
123 +---
124 +
125 +## Environment Variables (Advanced Users)
126 +
127 +| Variable | Purpose |
128 +|-----------------------|--------------------------------------------------------------------|
129 +| `TMPDIR` | Directory for temporary files. |
130 +| `ROOTCMD` | Command used for privilege escalation (default: `sudo` or `doas`). |
131 +| `DISABLE_TELEMETRY=1` | Disables anonymous telemetry data. |
132 +
133 +---
134 +
135 +## Telemetry Notice
136 +
137 +Anonymous usage data is collected by default. You can learn more or opt-out [here](/docs/netdata-agent/configuration/anonymous-telemetry-events.md)
\ No newline at end of file
packaging/installer/methods/kickstart.md
+85 -136
@@ -5,181 +5,130 @@ import TabItem from '@theme/TabItem';
5
6 # Install Netdata with kickstart.sh
7
8 -![last hour badge](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_by_url_pattern&options=unaligned&dimensions=kickstart&group=sum&after=-3600&label=last+hour&units=kickstart%20downloads&precision=0) ![today badge](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_by_url_pattern&options=unaligned&dimensions=kickstart&group=sum&after=-86400&label=today&units=kickstart%20downloads&precision=0)
8 +`kickstart.sh` is the recommended way to install Netdata.
9
10 -**`kickstart.sh` is the recommended way of installing Netdata.**
10 +This installation script works on all major Linux distributions. It automatically detects the best way to install Netdata for your system.
11
12 -This script works on all Linux distributions, by detecting the optimal method of installing Netdata directly to the operating system.
12 +<details><summary>What does kickstart.sh actually do?</summary>
13
14 +1. Detects your OS and environment
15 +2. Checks for an existing Netdata installation
16 +3. Installs using:
17 + - Native packages (preferred)
18 + - Static build (fallback)
19 + - Build from source (last resort)
20 +4. Installs an auto-update cron job (unless disabled)
21 +5. Optionally connects your node to Netdata Cloud
22
15 -## Installation
23 +</details>
24
17 -> **Tip**
18 ->
19 -> If you are unsure whether you want nightly or stable releases, read the [related section](/docs/netdata-agent/versions-and-platforms.md) of our Documentation, detailing the pros and cons of each release type.
25 +---
26 +
27 +## Quick Overview
28 +
29 +| Task | Command / Location | Notes |
30 +|-----------------------|--------------------------------|-----------------------------------------|
31 +| Install Netdata | Run `kickstart.sh` | Choose nightly or stable release |
32 +| Connect to Cloud | Use claim token | Connect node to Netdata Cloud |
33 +| Customize install | Pass flags to control behavior | Directory, release, update control |
34 +| Export config for IaC | Copy config from Cloud UI | For automation & Infrastructure as Code |
35 +
36 +---
37
21 -To install Netdata, run the following as your normal user:
38 +## Run the One-Line Install Command
39 +
40 +To install and connect to Netdata Cloud in a single step from your terminal:
41
42 <Tabs>
43 <TabItem value="wget" label="wget">
44
26 - <OneLineInstallWget/>
45 +<OneLineInstallWget/>
46
47 </TabItem>
48 <TabItem value="curl" label="curl">
49
31 - <OneLineInstallCurl/>
50 +<OneLineInstallCurl/>
51
52 </TabItem>
53 </Tabs>
54
36 -> **Note**
37 ->
38 -> If you plan to also connect the node to Netdata Cloud, make sure to replace `YOUR_CLAIM_TOKEN` with the claim token of your space,
39 -> and `YOUR_ROOM_ID` with the ID of the Room you’re willing to connect the node to.
40 -
41 -## Optional parameters to alter your installation
42 -
43 -The `kickstart.sh` script accepts a number of optional parameters to control how the installation process works:
44 -
45 -### destination directory
46 -
47 -- `--install-prefix`
48 - Specify a custom installation directory for local builds. If not provided, a default directory will be used based on your system.
49 -- `--old-install-prefix`
50 - Specify the previous custom installation directory to be removed during the update process.
51 -
52 -### interactivity
53 -
54 -The script automatically detects if it is running interactively, on a user's terminal, or headless in a CI/CD environment. These are options related to overriding this behavior.
55 -
56 -- `--non-interactive` or `--dont-wait`
57 - Don’t prompt for anything and assume yes whenever possible, overriding any automatic detection of an interactive run. Use this option when installing Netdata Agent with a provisioning tool or in CI/CD.
58 -- `--interactive`
59 - Act as if running interactively, even if automatic detection indicates a run is non-interactive.
60 -
61 -### release channel
62 -
63 -By default, the script installs the nightly channel of Netdata, providing you with the most recent Netdata. For production systems where stability is more important than new features, we recommend using the stable channel.
64 -
65 -- `--release-channel`
66 - Specify a particular release channel to install from. Currently supported release channels are:
67 - - `nightly`: Installs a nightly build (this is currently the default).
68 - - `stable`: Installs a stable release.
69 - - `default`: Explicitly request whatever the current default is.
70 -- `--nightly-channel`
71 - Synonym for `--release-channel nightly`.
72 -- `--stable-channel`
73 - Synonym for `--release-channel stable`.
74 -- `--install-version`
75 - Specify the exact version of Netdata to install.
76 -
77 -### install type
78 -
79 -By default, the script will prefer native builds when they’re available, and then static builds. It will fallback to build from source when all others aren’t available.
80 -
81 -- `--native-only`
82 - Only install if native binary packages are available. It fails otherwise.
83 -- `--static-only`
84 - Only install if a static build is available. It fails otherwise.
85 - When installing a static build, the parameter `--static-install-options` can provide additional options to pass to the static installer code.
86 -- `--build-only`
87 - Only install using a local build. It fails otherwise.
88 - When it builds from source, the parameter `--local-build-options` can be used to give additional build options.
89 -
90 -### automatic updates
91 -
92 -By default, the script installs a cron job to automatically update Netdata to the latest version of the release channel used.
93 -
94 -- `--auto-update`
95 - Enable automatic updates (this is the default).
96 -- `--no-updates`
97 - Disable automatic updates (not recommended).
98 -
99 -### Netdata Cloud related options
100 -
101 -By default, the kickstart script will provide a Netdata Agent installation that can potentially communicate with Netdata Cloud if the Netdata Agent is further configured to do so.
102 -
103 -- `--claim-token`
104 - Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node after the installation. This will connect and connect the Netdata Agent to Netdata Cloud.
105 -- `--claim-url`
106 - Specify a URL to use when connecting to the Cloud. Defaults to `https://app.netdata.cloud`. Use this option to change the Netdata Cloud URL to point to your Netdata Cloud installation.
107 -- `--claim-rooms`
108 - Specify a comma-separated list of tokens for each Room this node should appear in.
109 -- `--claim-proxy`
110 - Specify a proxy to use when connecting to the Cloud in the form of `http://[user:pass@]host:ip` for an HTTP(S) proxy. See [connecting through a proxy](/src/claim/README.md#automatically-via-a-provisioning-system-or-the-command-line) for details.
111 -- `--claim-only`
112 - If there is an existing installation, only try to connect it without attempting to update it. If there is no existing installation, install and connect Netdata normally.
55 +> **Tip**
56 +> Pick **Stable** or **Nightly**: Check the [guide](/docs/netdata-agent/versions-and-platforms.md) for differences.
57
114 -### anonymous telemetry
58 +<details><summary>🔍 Where to find your claim token</summary>
59
116 -By default, the Agent is sending anonymous telemetry data to help us identify the most common operating systems and the configurations Netdata Agents run. We use this information to prioritize our efforts towards what is most commonly used by our community.
60 +1. Log in to [Netdata Cloud](https://app.netdata.cloud)
61 +2. Navigate to your Space
62 +3. Go to **Space Settings** → **Nodes**
63 +4. Click **Add Node** → Copy Claim Token
64
118 -- `--disable-telemetry`
119 - Disable anonymous statistics.
65 +<!-- Screenshot Placeholder -->
66 +<!-- ![Claim Token in Netdata Cloud UI](../img/kickstart/claim-token-ui.png) -->
67
121 -### reinstalling
68 +</details>
69
123 -- `--reinstall`
124 - If there is an existing installation, reinstall it instead of trying to update it. If there is not an existing installation, install netdata normally.
125 -- `--reinstall-even-if-unsafe`
126 - If there is an existing installation, reinstall it instead of trying to update it, even if doing so is known to potentially break things (for example, if we can’t detect what type of installation it is). If there is not an existing install, install Netdata normally.
127 -- `--reinstall-clean`
128 - If there is an existing installation, uninstall it before trying to install Netdata. Fails if there is no existing installation.
70 +---
71
130 -### uninstall
72 +## Optional Parameters for kickstart.sh
73
132 -- `--uninstall`
133 - Uninstall an existing installation of Netdata. Fails if there is no existing install.
74 +Use these flags to customize your installation.
75
135 -### other options
76 +| Category | Parameter | Purpose |
77 +|-------------------------|------------------------|-------------------------------------|
78 +| **Directory Options** | `--install-prefix` | Custom install directory |
79 +| | `--old-install-prefix` | Clean previous install directory |
80 +| **Interactivity** | `--non-interactive` | No prompts (good for scripts) |
81 +| | `--interactive` | Force interactive prompts |
82 +| **Release Channel** | `--release-channel` | `nightly` or `stable` |
83 +| | `--install-version` | Install specific version |
84 +| **Auto-Updates** | `--auto-update` | Enable updates |
85 +| | `--no-updates` | Disable updates |
86 +| **Netdata Cloud** | `--claim-token` | Provide claim token |
87 +| | `--claim-rooms` | Assign node to specific Cloud Rooms |
88 +| **Reinstall/Uninstall** | `--reinstall` | Reinstall existing Netdata |
89 +| | `--uninstall` | Uninstall Netdata completely |
90
137 -- `--dry-run`
138 - Simulates the installation process without making any changes to your system. This allows you to review the steps and potential impacts before proceeding with the actual installation.
139 -- `--dont-start-it`
140 - Don’t auto-start the daemon after installing. This parameter is not guaranteed to work.
141 -- `--distro-override`
142 - Override the distro detection logic and assume the system is using a specific Linux distribution and release. Takes a single argument consisting of the values of the `ID`, `VERSION_ID`, and `VERSION_CODENAME` fields from `/etc/os-release` for the desired distribution.
91 +---
92
144 -The following options are mutually exclusive and specify special operations other than trying to install Netdata normally or update an existing install:
93 +## Environment Variables
94
146 -- `--repositories-only`
147 - Only install repository configuration packages instead of doing a full install of Netdata. Automatically sets --native-only.
148 -- `--prepare-offline-install-source`
149 - Instead of installing 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.
95 +These environment variables provide additional customization options (most users won't need these):
96
151 -### environment variables
97 +| Variable | Purpose | Default Behavior |
98 +|---------------------|----------------------------------------------|---------------------------------------------|
99 +| `TMPDIR` | Specify directory for temporary files | System default temp directory |
100 +| `ROOTCMD` | Command to run with root privileges | Uses `sudo`, `doas`, or `pkexec` (in order) |
101 +| `DISABLE_TELEMETRY` | Disable telemetry when set to non-zero value | Telemetry enabled |
102
153 -Additionally, the following environment variables may be used to further customize how the script runs (most users
154 -shouldn’t need to use special values for any of these):
103 +> [!NOTE]
104 +> The user running the script needs write and execute permissions in the temporary directory specified by TMPDIR.
105
156 -- `TMPDIR`: Used to specify where to put temporary files. On most systems, the default we select automatically
157 - should be fine. The user running the script needs to both be able to write files to the temporary directory,
158 - and run files from that location.
159 -- `ROOTCMD`: Used to specify a command to use to run another command with root privileges if needed. By default,
160 - we try to use sudo, doas, or pkexec (in that order of preference). However, if you need special options for one of
161 - those to work, or have a different tool to do the same thing on your system, you can specify it here.
162 -- `DISABLE_TELEMETRY`: If set to a value other than 0, behave as if `--disable-telemetry` was specified.
106 +---
107
164 -## Verify script integrity
108 +## Verify Script Integrity
109
166 -To use `md5sum` to verify the integrity of the `kickstart.sh` script you will download using the one-line command above,
167 -run the following:
110 +Before running the installation script, you can verify its integrity using the following command:
111
112 ```bash
113 [ "@KICKSTART_CHECKSUM@" = "$(curl -Ss https://get.netdata.cloud/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID"
114 ```
115
173 -If the script is valid, this command will return `OK, VALID`.
116 +If the script is valid, this command will return `OK, VALID`. We recommend verifying script integrity before installation, especially in production environments.
117 +
118 +---
119 +
120 +## Notes & Best Practices
121 +
122 +- Stop the Agent with `sudo systemctl stop netdata` before reinstalling
123 +- Customize install location or behavior with flags
124 +- Always verify the downloaded script for security
125 +- Use the `--non-interactive` flag in CI/CD pipelines
126
175 -## What does `kickstart.sh` do?
127 +---
128
177 -The `kickstart.sh` script does the following after being downloaded and run using `sh`:
129 +## Related Docs
130
179 -- Determines what platform you’re running on.
180 -- Checks for an existing installation, and if found updates that instead of creating a new installation.
181 -- Attempts to install Netdata using our [official native binary packages](/packaging/installer/methods/packages.md).
182 -- If there are no official native binary packages for your system (or installing that way failed), tries to install using a [static build of Netdata](/packaging/makeself/README.md) if one is available.
183 -- If no static build is available, installs required dependencies and then attempts to install by building Netdata locally (by downloading the sources and building them directly).
184 -- 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).
185 -- Prints a message whether installation succeeded or failed for QA purposes.
131 +- [Connect to Netdata Cloud](/docs/netdata-cloud/connect-agent-to-cloud)
132 +- [Release Channels & Versions](/docs/netdata-agent/versions-and-platforms.md)
133 +- [Uninstall Guide](/docs/netdata-agent/installation/uninstall)
134 +- [Offline Installation Guide](/packaging/installer/methods/offline.md)
\ No newline at end of file
packaging/installer/methods/manual.md
+14 -14
@@ -4,11 +4,11 @@ To install the latest git version of Netdata, please follow these 2 steps:
4
5 1. [Prepare your system](#prepare-your-system)
6
7 - Install the required packages on your system.
7 + Install the required packages on your system.
8
9 2. [Install Netdata](#install-netdata)
10
11 - Download and install Netdata. You can also update it the same way.
11 + Download and install Netdata. You can also update it the same way.
12
13 ## Prepare your system
14
@@ -20,23 +20,23 @@ should be installed on your system to build and run Netdata. It supports a large
20 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:
21
22 - **Alpine** Linux and its derivatives
23 - - You have to install `bash` yourself, before using the installer.
23 + - You have to install `bash` yourself, before using the installer.
24
25 - **Gentoo** Linux and its derivatives
26
27 - **Debian** Linux and its derivatives (including **Ubuntu**, **Mint**)
28
29 - **Red Hat Enterprise Linux** and its derivatives (including **Fedora**, **CentOS**, **Amazon Machine Image**)
30 - - Please note that for RHEL/CentOS you need
31 - [EPEL](http://www.tecmint.com/how-to-enable-epel-repository-for-rhel-centos-6-5/).
32 - In addition, RHEL/CentOS version 6 also need
33 - [OKay](https://okay.com.mx) for package libuv version 1.
34 - - CentOS 8 / RHEL 8 requires a bit of extra work. See the dedicated section below.
30 + - Please note that for RHEL/CentOS you need
31 + [EPEL](http://www.tecmint.com/how-to-enable-epel-repository-for-rhel-centos-6-5/).
32 + In addition, RHEL/CentOS version 6 also need
33 + [OKay](https://okay.com.mx) for package libuv version 1.
34 + - CentOS 8 / RHEL 8 requires a bit of extra work. See the dedicated section below.
35
36 - **SUSE** Linux and its derivatives (including **openSUSE**)
37
38 - **SLE12** Must have your system registered with SUSE Customer Center or have the DVD. See
39 - [#1162](https://github.com/netdata/netdata/issues/1162)
39 + [#1162](https://github.com/netdata/netdata/issues/1162)
40
41 Install the packages for having a **basic Netdata installation** (system monitoring and many applications, without `mysql` / `mariadb`, `named`, hardware sensors and `SNMP`):
42
@@ -196,14 +196,14 @@ cd netdata
196 - `--stable-channel`: Automatically update only on the release of new major versions.
197 - `--nightly-channel`: Automatically update on every new nightly build.
198 - `--disable-telemetry`: Opt-out of [anonymous statistics](/docs/netdata-agent/configuration/anonymous-telemetry-events.md) we use to make
199 - Netdata better.
199 + Netdata better.
200 - `--no-updates`: Prevent automatic updates of any kind.
201 - `--reinstall`: If an existing install is detected, reinstall instead of trying to update it. Note that this
202 - cannot be used to change installation types.
202 + cannot be used to change installation types.
203 - `--local-files`: Used for [offline installations](/packaging/installer/methods/offline.md). Pass four file paths: the Netdata
204 - tarball, the checksum file, the go.d plugin tarball, and the go.d plugin config tarball, to force kickstart run the
205 - process using those files. This option conflicts with the `--stable-channel` option. If you set this _and_
206 - `--stable-channel`, Netdata will use the local files.
204 + tarball, the checksum file, the go.d plugin tarball, and the go.d plugin config tarball, to force kickstart run the
205 + process using those files. This option conflicts with the `--stable-channel` option. If you set this _and_
206 + `--stable-channel`, Netdata will use the local files.
207
208 ### Connect node to Netdata Cloud during installation
209
packaging/installer/methods/offline.md
+109 -18
@@ -1,38 +1,129 @@
1 -# Install Netdata on offline systems
1 +# Install Netdata on Offline Systems
2
3 +This guide explains how to install Netdata Agent on systems without internet access.
4
4 -Our kickstart script enables offline Netdata Agent installation by prefetching required files (static installs only for now). Future support for local builds is possible, but no ETA. For offline systems, users can try their distro’s package tools (e.g., `apt-offline`), though it's not officially supported.
5 +Netdata supports offline installation of the Agent using our `kickstart.sh` script.
6
6 -## Preparing the offline installation source
7 +This method:
8
8 -The first step in installing Netdata on an offline system is preparing the offline installation source. This can be done as a regular user on any internet-connected system with the following tools available:
9 +- Downloads all required files in advance.
10 +- Works with static builds only (for now).
11 +- Does *not* support automatic updates on offline systems.
12
10 -- cURL or wget
11 -- sha256sum or shasum
12 -- A standard POSIX compliant shell
13 +> [!NOTE]
14 +> Local package tools like `apt-offline` may work for DEB/RPM installs — but we don’t officially support them.
15
14 -To prepare the offline installation source, simply run:
16 +---
17 +
18 +## Step 1: Prepare the Offline Installation Package
19 +
20 +On your internet-connected machine, you'll need::
21 +
22 +| Requirement | Purpose |
23 +|-------------------------|----------------------------|
24 +| `curl` or `wget` | Download the script |
25 +| `sha256sum` or `shasum` | Verify script downloads |
26 +| POSIX-compliant shell | Required to run the script |
27 +
28 +Run the following command:
29 +
30 +- using `wget`
31 + ```bash
32 + wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
33 + sh /tmp/netdata-kickstart.sh --release-channel stable --prepare-offline-install-source ./netdata-offline
34 + ```
35 +- or using `curl`
36 + ```bash
37 + curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh
38 + sh /tmp/netdata-kickstart.sh --release-channel stable --prepare-offline-install-source ./netdata-offline
39 + ```
40 +
41 + > [!NOTE]
42 + > The folder name `netdata-offline` is just an example — use any name you want.
43 + >
44 + > To use the nightly channel instead, replace `stable` with `nightly`.
45 +
46 +**What's Included**:
47 +
48 +The script creates a directory with all necessary files:
49 +
50 +```
51 +── netdata-offline
52 + ├── channel # Release channel info
53 + ├── install.sh # Installation script
54 + ├── kickstart.sh # Original kickstart script
55 + ├── netdata-*.gz.run # Netdata static packages for different architectures
56 + └── sha256sums.txt # Verification hashes
57 +```
58 +
59 +---
60 +
61 +## Step 2: Transfer to Offline System
62 +
63 +Copy the entire `netdata-offline` directory to your offline system using your preferred method (USB drive, secure copy, etc.).
64 +
65 +> [!IMPORTANT]
66 +> Do not rename or modify any files in the package.
67 +> The installation script expects the exact directory structure and filenames.
68 +
69 +> [!TIP]
70 +> The folder name `netdata-offline` is just an example — use any name you want.
71 +
72 +---
73 +
74 +### Output
75 +
76 +This will create a directory like:
77 +
78 +```
79 +./netdata-offline/
80 +```
81 +
82 +It will contain everything required to install Netdata offline.
83 +
84 +---
85 +
86 +## Choose Release Channel (Optional)
87 +
88 +To prepare for a specific channel (`nightly` or `stable`), add:
89
90 ```bash
17 -wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --prepare-offline-install-source ./netdata-offline
91 +--release-channel nightly
92 ```
93
94 or
95
96 ```bash
23 -curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --prepare-offline-install-source ./netdata-offline
97 +--release-channel stable
98 +```
99 +
100 +Example:
101 +
102 +```bash
103 +sh /tmp/netdata-kickstart.sh --release-channel stable --prepare-offline-install-source ./netdata-offline
104 ```
105
26 -> The exact name used for the directory does not matter, you can specify any other name you want in place of `./netdata-offline`.
106 +---
107 +
108 +## Install Netdata on the Target (Offline) System
109 +
110 +1. Copy the entire `netdata-offline` directory to your offline system.
111
28 -This will create a directory called `netdata-offline` in the current directory and place all the files required for an offline install in it.
112 +> ⚠️ Warning
113 +> Don't rename or modify the files.
114
30 -If you want to use a specific release channel (nightly or stable), it _must_ be specified on this step using the
31 -appropriate option for the kickstart script.
115 +---
116 +
117 +2. On the offline system, run:
118 +
119 +```bash
120 +cd netdata-offline
121 +sudo ./install.sh
122 +```
123
33 -## Installing on the target system
124 +The `install.sh` script accepts the [same parameters](/packaging/installer/methods/kickstart.md#optional-parameters-for-kickstartsh) as `kickstart.sh`, allowing you to customize your installation.
125
35 -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.
126 +## Automatic Updates
127
37 -After copying the files, simply run the `install.sh` script located in the
38 -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).
\ No newline at end of file
128 +> [!NOTE]
129 +> Automatic updates are *disabled* by default for offline installations — since there’s no network connection.
\ No newline at end of file
packaging/installer/methods/packages.md
+110 -74
@@ -1,79 +1,92 @@
1 -# Install Netdata using native DEB/RPM packages
1 +# Install Netdata Using Native DEB/RPM Packages
2
3 -For most DEB- or RPM-based Linux distributions, Netdata provides pre-built native packages, following our [platform support policy](/docs/netdata-agent/versions-and-platforms.md).
3 +Netdata provides pre-built native packages for most DEB- and RPM-based Linux distributions, following our [platform support policy](/docs/netdata-agent/versions-and-platforms.md).
4
5 -Our [kickstart.sh installer](/packaging/installer/methods/kickstart.md) uses these by default on supported platforms. To force native DEB or RPM packages, add `--native-only` when running the script—it will fail if native packages aren’t available.
5 +Our [kickstart.sh installer](/packaging/installer/methods/kickstart.md) uses these packages by default on supported platforms.
6
7 -> **Note**
8 ->
9 -> Until late 2024 we continued to provide packages via Package Cloud, but we have since then switched to only providing packages via our repositories.
7 +Add `--native-only` when running `kickstart.sh` to force native packages. The script will fail if native packages aren’t available.
8
11 -## Manual setup of RPM packages
9 +> [!NOTE]
10 +> Until late 2024, Netdata packages were hosted on Package Cloud. All packages are now provided exclusively from our own repositories.
11
13 -Netdata’s official RPM repositories are hosted at <https://repository.netdata.cloud/repos/index.html>. We provide four groups of
14 -repositories at that top level:
12 +---
13
16 -- `stable`: Contains packages for stable releases of the Netdata Agent.
17 -- `edge`: Contains packages for nightly builds of the Netdata Agent.
18 -- `repoconfig`: Provides packages that set up configuration files for using the other repositories.
19 -- `devel`: Is used for one-off development builds of the Netdata Agent, and can simply be ignored by users.
14 +## Manual Setup of RPM Packages
15
21 -Within each top level group of repositories, there are directories for each supported group of distributions:
16 +Repositories: [https://repository.netdata.cloud/repos/index.html](https://repository.netdata.cloud/repos/index.html)
17
23 -- `amazonlinux`: Is for Amazon Linux and binary compatible distros.
24 -- `el`: Is for Red Hat Enterprise Linux and binary compatible distros that are not covered by other repos, such
25 - as CentOS, Alma Linux, and Rocky Linux.
26 -- `fedora`: Is for Fedora and binary compatible distros.
27 -- `ol`: Is for Oracle Linux and binary compatible distros.
28 -- `opensuse`: Is for openSUSE and binary compatible distros.
18 +Available groups:
19
30 -Each distribution has a directory for supported releases, with subdirectories for each CPU architecture containing the actual repository.
20 +| Repo | Purpose |
21 +|--------------|-------------------------------|
22 +| `stable` | Stable Netdata Agent releases |
23 +| `edge` | Nightly builds |
24 +| `repoconfig` | Configuration packages |
25 +| `devel` | Dev builds (ignore) |
26
32 -For example, the stable release for RHEL 9 on 64-bit x86 is at:
33 -<https://repository.netdata.cloud/repos/stable/el/9/x86_64/>
27 +Supported distributions:
28 +
29 +- `amazonlinux`
30 +- `el` (RHEL, CentOS, AlmaLinux, Rocky Linux)
31 +- `fedora`
32 +- `ol` (Oracle Linux)
33 +- `opensuse`
34 +
35 +Example repository for RHEL 9 x86_64:
36 +[https://repository.netdata.cloud/repos/stable/el/9/x86_64/](https://repository.netdata.cloud/repos/stable/el/9/x86_64/)
37 +
38 +GPG Key fingerprint:
39 +`6E155DC153906B73765A74A99DD4A74CECFA8F4F`
40
35 -Our RPM packages and repository metadata are signed with a GPG key (`Netdatabot`), fingerprint:
36 -`6E155DC153906B73765A74A99DD4A74CECFA8F4F`.
41 Public key:
38 -<https://repository.netdata.cloud/netdatabot.gpg.key>
42 +[https://repository.netdata.cloud/netdatabot.gpg.key](https://repository.netdata.cloud/netdatabot.gpg.key)
43 +
44 +### Steps
45 +
46 +1. Download config package:
47 + [https://repository.netdata.cloud/repos/repoconfig/index.html](https://repository.netdata.cloud/repos/repoconfig/index.html)
48
40 -For manual repository setup, download the appropriate config package from:
41 -<https://repository.netdata.cloud/repos/repoconfig/index.html>
42 -Install it with your package manager to ensure dependencies and smooth updates.
49 +2. Install it with your package manager:
50
44 -> **Note:**
45 -> On RHEL and other `el`-based systems, some Netdata dependencies are in the EPEL repository, which isn’t enabled by default.
46 -> Our config packages should handle this, but if not, install `epel-release` manually.
51 + ```bash
52 + # For RHEL/CentOS/Fedora
53 + sudo rpm -i netdata-repo-*.rpm
54 + sudo dnf install netdata
55 + ```
56
48 -## Manual setup of DEB packages
57 + > **Note**
58 + > On RHEL systems, EPEL repository is required.
59 + > Our config packages handle this automatically — if not, install epel-release manually.
60
50 -Netdata’s official DEB repositories are hosted at <https://repository.netdata.cloud/repos/index.html>.
51 -We provide four groups of repositories at that top level:
61 +---
62
53 -- `stable`: Contains packages for stable releases of the Netdata Agent.
54 -- `edge`: Contains packages for nightly builds of the Netdata Agent.
55 -- `repoconfig`: Provides packages that set up configuration files for using the other repositories.
56 -- `devel`: Is used for one-off development builds of the Netdata Agent, and can simply be ignored by users.
63 +## Manual Setup of DEB Packages
64
58 -Within each top level group of repositories, there are directories for each supported group of distributions:
65 +Repositories: [https://repository.netdata.cloud/repos/index.html](https://repository.netdata.cloud/repos/index.html)
66
60 -- `debian`: Is for Debian Linux and binary compatible distros.
61 -- `ubuntu`: Is for Ubuntu Linux and binary compatible distros.
67 +Available groups:
68
63 -Each directory contains subdirectories for supported releases, named by codename.
69 +| Repo | Purpose |
70 +|--------------|-------------------------------|
71 +| `stable` | Stable Netdata Agent releases |
72 +| `edge` | Nightly builds |
73 +| `repoconfig` | Configuration packages |
74 +| `devel` | Dev builds (ignore) |
75
65 -Our repositories use **flat repository** structure (per Debian standards) and are accessible via HTTP and HTTPS. They also support metadata retrieval **by-hash**, which improves reliability. Example:
66 -`http://repository.netdata.cloud/repos/edge/ubuntu/focal/by-hash/SHA256/91ccff6523a3c4483ebb539ff2b4adcd3b6b5d0c0c2c9573c5a6947a127819bc`
76 +Supported distributions:
77
68 -As a result of this structure, the required APT sources.list entry for stable packages for Debian 11 (Bullseye) is:
78 +- `debian`
79 +- `ubuntu`
80
70 -```text
81 +APT source for Debian 11 (Bullseye):
82 +
83 +```
84 deb by-hash=yes http://repository.netdata.cloud/repos/stable/debian/ bullseye/
85 ```
86
74 -And the equivalent required deb822 style entry for stable packages for Debian 11 (Bullseye) is:
87 +Deb822 format:
88
76 -```text
89 +```
90 Types: deb
91 URIs: http://repository.netdata.cloud/repos/stable/debian/
92 Suites: bullseye/
@@ -81,39 +94,62 @@ By-Hash: Yes
94 Enabled: Yes
95 ```
96
84 -Note the `/` at the end of the codename, this is required for the repository to be processed correctly.
97 +GPG Key fingerprint:
98 +`6E155DC153906B73765A74A99DD4A74CECFA8F4F`
99 +
100 +Public key:
101 +[https://repository.netdata.cloud/netdatabot.gpg.key](https://repository.netdata.cloud/netdatabot.gpg.key)
102 +
103 +### Steps
104 +
105 +1. Download config package:
106 + [https://repository.netdata.cloud/repos/repoconfig/index.html](https://repository.netdata.cloud/repos/repoconfig/index.html)
107 +
108 +2. Install it using your package manager:
109 +
110 + ```bash
111 + # For Debian/Ubuntu
112 + sudo apt install ./netdata-repo_*.deb
113 + sudo apt update
114 + sudo apt install netdata
115 + ```
116 +
117 +---
118 +
119 +## Local Mirrors of the Official Netdata Repositories
120 +
121 +You can mirror Netdata’s repositories:
122
86 -Our DEB packages and repository metadata are signed using a GPG key with a user name of ‘Netdatabot’. The
87 -current key fingerprint is `6E155DC153906B73765A74A99DD4A74CECFA8F4F`. The associated public key can be fetched from
88 -`https://repository.netdata.cloud/netdatabot.gpg.key`.
123 +### Recommended Methods:
124
90 -For manual repository setup, download the appropriate config package from:
91 -<https://repository.netdata.cloud/repos/repoconfig/index.html>
125 +| Method | Use case |
126 +|------------------|---------------------------------------|
127 +| Standard tools | e.g., Aptly (APT) or `reposync` (RPM) |
128 +| Simple mirroring | Use `wget --mirror` or similar tools |
129
93 -Install it using your package manager to ensure all dependencies are met and to allow a smooth transition if our infrastructure changes.
130 +Mirror root URL:
131 +[https://repository.netdata.cloud/repos/](https://repository.netdata.cloud/repos/)
132
95 -## Local mirrors of the official Netdata repositories
133 +---
134
97 -Local mirrors of our official repositories can be created in one of two ways:
135 +### Mirror Tips:
136
99 -1. Using the standard tooling for mirroring the type of repository you want a local mirror of, such as Aptly for
100 - APT repositories, or reposync for RPM repositories. For this approach, please consult the documentation for
101 - the specific tool you are using for info on how to mirror the repositories.
102 -2. Using a regular website mirroring tool, such as GNU wget’s `--mirror` option. For this approach, simply point
103 - your mirroring tool at `https://repository.netdata.cloud/repos/`, and everything should just work.
137 +- Config packages don’t support custom mirrors — configure mirrors manually.
138 +- Packages are built in stages by architecture.
139 +- Metadata updates up to six times/hour.
140 +- Full mirror can require up to **100 GB**.
141 +- Ideal sync window: **05:00–08:00 UTC**.
142 +- Fetch a GPG key from:
143 + [https://repository.netdata.cloud/netdatabot.gpg.key](https://repository.netdata.cloud/netdatabot.gpg.key)
144
105 -We don’t officially support mirroring our repositories, but here are some tips:
145 +---
146
107 -- Our repository config packages **don’t** work with custom mirrors (except caching proxies like `apt-cacher-ng`), so you’ll need to configure mirrors manually.
108 -- Packages are built and published in stages: 64-bit x86 first, then 32-bit x86, followed by other architectures in alphabetical order. Publishing takes a few hours.
109 -- Repository metadata updates up to six times an hour, but syncing more than once per hour isn’t necessary.
110 -- A full mirror requires up to **100 GB** of storage, so mirror only what you need.
111 -- For daily syncing, **05:00–08:00 UTC** is ideal, as nightly packages are usually published by then.
112 -- If using our GPG signatures, grab our public key:
113 - <https://repository.netdata.cloud/netdatabot.gpg.key>
147 +## Public Mirrors of the Official Netdata Repositories
148
115 -## Public mirrors of the official Netdata repositories
149 +> **There are no official public mirrors**.
150
117 -There are no official public mirrors of our repositories.
151 +If you wish to provide a public mirror of Netdata repositories:
152
119 -If you wish to provide a public mirror of our official repositories, you are free to do so, but we kindly ask that you make it clear to your users that your mirror is not an official mirror of our repositories.
\ No newline at end of file
153 +- You’re free to do so.
154 +- Please clearly state to your users that it is *not* an official mirror.
155 +- Follow best practices for repository mirroring and security.
packaging/makeself/README.md
+102 -32
@@ -1,65 +1,135 @@
1 -# Netdata static binary build
1 +# Netdata Static Binary Build
2
3 -We publish pre-built static builds of Netdata for Linux systems. Currently, these are published for 64-bit x86, ARMv7,
4 -AArch64, and POWER8+ hardware. These static builds are able to operate in a mostly self-contained manner and only
5 -require a POSIX compliant shell and a supported init system. These static builds install under `/opt/netdata`. If
6 -you are on a platform which we provide static builds for but do not provide native packages for, a static build
7 -will be used by default for installation.
3 +Netdata provides pre-built static binaries for Linux systems where native packages aren't available. The [installer](/packaging/installer/methods/kickstart.md) automatically uses these static builds when needed.
4
9 -If you want to enforce the usage of a static build and have the installer return a failure if one is not available,
10 -you can do so by adding `--static-only` to the options you pass to the installer.
5 +**Key Features**:
6
12 -## Requirements
7 +- Self-contained installation (no system dependencies required, no interference with system libraries)
8 +- Installed under `/opt/netdata`
9
14 -- Container runtime tool (Docker or Podman)
10 +## Supported Architectures
11
16 -## Building a static binary package
12 +| Architecture | Identifier | Notes |
13 +|--------------|------------|----------------------------------|
14 +| x86_64 | `x86_64` | 64-bit Intel/AMD processors |
15 +| ARMv7 | `armv7l` | Raspberry Pi 2/3, many SBCs |
16 +| AArch64 | `aarch64` | ARM 64-bit (Pi 4, newer devices) |
17 +| POWER8+ | `ppc64le` | IBM POWER architecture |
18
18 -Before you begin, make sure that your repo and the repo's submodules are clean from any previous builds and up to date.
19 -Otherwise, [perform a cleanup](/packaging/installer/methods/manual.md#perform-a-cleanup-in-your-netdata-repo)
19 +---
20
21 +## Build Process
22
22 -To build the static binary 64-bit distribution package, into the root folder on the netdata repo, run:
23 +### Requirements
24 +
25 +| Requirement | Purpose |
26 +|------------------|-------------------------------------------|
27 +| Docker or Podman | Container environment for isolated builds |
28 +| ~10GB disk space | For build artifacts and containers |
29 +
30 +### Preparation
31 +
32 +Before building, ensure your repository is clean from previous builds.
33 +
34 +→ [Perform a cleanup](/packaging/installer/methods/manual.md#perform-a-cleanup-in-your-netdata-repo)
35 +
36 +### Building the Static Binary
37 +
38 +Run the build script with your target [architecture identifier](#supported-architectures):
39
40 ```bash
41 +# For x86_64 (default)
42 ./packaging/makeself/build-static.sh x86_64
43 +
44 +# For ARM 64-bit (AArch64)
45 +./packaging/makeself/build-static.sh aarch64
46 +
47 +# For ARMv7
48 +./packaging/makeself/build-static.sh armv7l
49 +
50 +# For POWER8+
51 +./packaging/makeself/build-static.sh ppc64le
52 ```
53
28 -The program will:
54 +The script will automatically:
55 +
56 +- Launch an Alpine Linux container
57 +- Install necessary build dependencies
58 +- Compile required third-party tools (bash, curl, etc.)
59 +- Build Netdata with optimized settings
60 +- Package everything into a self-extracting installer
61 +
62 +When building for an architecture different from your host:
63
30 -1. setup a new docker container with Alpine Linux
31 -2. install the required alpine packages (the build environment, needed libraries, etc)
32 -3. download and compile third party apps that are packaged with Netdata (`bash`, `curl`, etc)
33 -4. compile Netdata
64 +- The build process uses QEMU for emulation
65 +- Build times will be significantly longer
66 +- More disk space may be required
67 +- Some features may have architecture-specific limitations
68
35 -Once finished, a file named `netdata-vX.X.X-gGITHASH-x86_64-DATE-TIME.run` will be created in the current directory. This is the Netdata binary package that can be run to install Netdata on any other computer.
69 +### Build Output
70
37 -You can build static binaries for other architectures such as `armv7l`, `aarch64`, and `ppc64le`.
71 +The process generates several installer files in the artifacts/ directory:
72
39 -## Building binaries with debug info
73 +```
74 +artifacts/
75 +├── netdata-latest.gz.run # Latest version
76 +├── netdata-v[VERSION]-[BUILD].gz.run # Specific version
77 +├── netdata-[ARCH]-latest.gz.run # Architecture-specific latest
78 +└── netdata-[ARCH]-v[VERSION]-[BUILD].gz.run # Architecture-specific version
79 +```
80 +
81 +Example output:
82 +
83 +```
84 +$ ls -l artifacts/
85 +drwxrwxr-x - user group cache
86 +.rwxrwxr-x 94M user group netdata-latest.gz.run
87 +.rwxrwxr-x 94M user group netdata-v2.3.0-193-nightly.gz.run
88 +.rwxrwxr-x 94M user group netdata-x86_64-latest.gz.run
89 +.rwxrwxr-x 94M user group netdata-x86_64-v2.3.0-193-nightly.gz.run
90 +```
91
41 -To build Netdata binaries with debugging / tracing information in them, use:
92 +## Advanced Build Options
93 +
94 +### Debug Builds
95 +
96 +For troubleshooting, you can create a debug-enabled build:
97
98 ```bash
44 -cd /path/to/netdata.git
99 ./packaging/makeself/build-static.sh x86_64 debug
100 ```
101
48 -These binaries are not optimized (they are a bit slower), they have certain features disables (like log flood protection), other features enables (like `debug flags`) and are not stripped (the binary files are bigger, since they now include source code tracing information).
102 +Debug build characteristics:
103 +
104 +- Larger file size
105 +- Runtime performance impact
106 +- Additional diagnostic information
107 +- Disabled optimizations
108 +- Enhanced tracing capabilities
109
50 -## Debugging Netdata binaries
110 +## Troubleshooting
111
52 -Once you have installed a binary package with debugging info, you will need to install `valgrind` and run this command to start Netdata:
112 +### Running with Valgrind
113 +
114 +To diagnose memory issues or crashes:
115
116 ```bash
117 PATH="/opt/netdata/bin:${PATH}" valgrind --undef-value-errors=no /opt/netdata/bin/srv/netdata -D
118 ```
119
58 -The above command, will run Netdata under `valgrind`. While Netdata runs under `valgrind` it will be 10x slower and use a lot more memory.
120 +**Important notes**:
121 +
122 +- Performance will be significantly reduced (~10x slower)
123 +- Stop Valgrind with Ctrl+C
124 +- The `--undef-value-errors=no` flag suppresses hundreds of false positives from the bundled libraries
125
60 -If Netdata crashes, `valgrind` will print a stack trace of the issue. Open a github issue to let us know.
126 +### Crash Reporting
127
62 -To stop Netdata while it runs under `valgrind`, press Control-C on the console.
128 +If Netdata crashes during development or testing:
129
64 -> If you omit the parameter `--undef-value-errors=no` to valgrind, you will get hundreds of errors about conditional jumps that depend on uninitialized values. This is normal. Valgrind has heuristics to prevent it from printing such errors for system libraries, but for the static Netdata binary, all the required libraries are built into Netdata. So, valgrind cannot apply its heuristics and prints them.
65 ->
130 +1. Capture the complete Valgrind output
131 +2. [Open a GitHub Issue](https://github.com/netdata/netdata/issues/new/choose)
132 +3. Include:
133 + - Build details (architecture, version)
134 + - Complete stack trace
135 + - Steps to reproduce the issue
packaging/windows/WINDOWS_INSTALLER.md
+71 -32
@@ -1,61 +1,100 @@
1 -# Windows Installer Guide
1 +# Install Netdata on Windows
2
3 -Netdata provides a straightforward Windows installer for easy setup. The installer offers two installation modes, each with specific features outlined below.
3 +Netdata provides a simple Windows installer for quick setup.
4
5 -**Important Note**: The Netdata Windows Agent is intended for users with paid Netdata subscriptions. If you're using a free account or no account at all, certain features of the Windows Agent will be restricted.
5 +> [!NOTE]
6 +> The Windows Agent is available for users with paid Netdata subscriptions.
7 +> Free users will have limited functionality.
8
7 -**Key Limitations for Free Users**:
9 +---
10
9 -- **Standalone Agents**: The user interface will be locked, and you will not have access to monitoring data.
10 -- **Child Agents**: If the Windows Agent streams data to a Linux-based parent Netdata instance, you will be unable to view the Windows Agent’s monitoring data in the parent dashboard.
11 +## Limitations for Free Users
12
12 -## Download the MSI Installer
13 +| Agent Type | Limitation |
14 +|------------------|---------------------------------------------------------------------------------------|
15 +| Standalone Agent | UI is locked — No local monitoring |
16 +| Child Agent | No monitoring data in parent dashboard when streaming to a Linux-based Netdata parent |
17
14 -You can download the Netdata Windows installer (MSI) from the official releases page. Choose between the following versions:
18 +---
19
16 -| Version | Description |
17 -|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
18 -| [Stable](https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi) | Recommended for most users; offers the most reliable and well-tested features. |
19 -| [Nightly](https://github.com/netdata/netdata-nightlies/releases/latest/download/netdata-x64.msi) | Contains the latest features but may have bugs or instability. Choose this if you need the newest features and can handle potential issues. |
20 +## Download the Windows Installer (MSI)
21 +
22 +Choose the version that suits your needs:
23 +
24 +| Version | Download Link | Recommended For |
25 +|---------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
26 +| Stable | [Download Stable](https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi) | Most users — stable, well-tested |
27 +| Nightly | [Download Nightly](https://github.com/netdata/netdata-nightlies/releases/latest/download/netdata-x64.msi) | Users who need the latest features and can handle potential bugs |
28 +
29 +---
30
31 ## Silent Installation (Command Line)
32
23 -Silent mode allows for automated deployments without user interaction.
33 +Use silent mode to deploy Netdata without user interaction (ideal for automation).
34 +
35 +> [!TIP]
36 +> Run the command prompt as Administrator.
37
25 -> **Note**: Run the installer as an administrator to avoid prompts.
38 +---
39
27 -By using silent mode, you implicitly agree to the terms of the [GPL-3](https://raw.githubusercontent.com/netdata/netdata/refs/heads/master/LICENSE) (Netdata Agent) and [NCUL1](https://app.netdata.cloud/LICENSE.txt) (Netdata Web Interface) licenses, and the agreements will not be displayed during installation.
40 +### Installation Command Options
41
29 -### Installation Options
42 +| Option | Description |
43 +|--------------|------------------------------------------------------------------------|
44 +| `/qn` | Enables silent mode (no user interaction) |
45 +| `/i` | Specifies the path to the MSI installer |
46 +| `TOKEN=` | Claim token from your Netdata Cloud Space |
47 +| `ROOMS=` | Comma-separated Room IDs for your node |
48 +| `PROXY=` | (Optional) Proxy address if required |
49 +| `INSECURE=1` | (Optional) Allow insecure connections (hostname verification disabled) |
50
31 -| Option | Description |
32 -|--------------|----------------------------------------------------------------------------------------|
33 -| `/qn` | Enables silent mode installation. |
34 -| `/i` | Specifies the path to the MSI installer file. |
35 -| `INSECURE=1` | Forces insecure connections, bypassing hostname verification. Use only when necessary. |
36 -| `TOKEN=` | Sets the Claim Token for your Netdata Cloud Space. |
37 -| `ROOMS=` | Comma-separated list of Room IDs where your node will appear. |
38 -| `PROXY=` | Specifies the proxy server address for networks requiring one. |
51 +---
52
40 -### Example Usage
53 +### Example Command
54
42 -To connect your Agent to your Cloud Space, use the following command:
55 +Install Netdata and connect to your Cloud Space:
56
57 ```bash
58 msiexec /qn /i netdata-x64.msi TOKEN="<YOUR_TOKEN>" ROOMS="<YOUR_ROOMS>"
59 ```
60
48 -Replace `<YOUR_TOKEN>` with your Netdata Cloud Space claim token and `<YOUR_ROOMS>` with your Room ID(s).
61 +Replace:
62
50 -You can also download and install Netdata in one step with the following command:
63 +- `<YOUR_TOKEN>` with your claim token
64 +- `<YOUR_ROOMS>` with your Room ID(s)
65 +
66 +---
67 +
68 +### Download & Install in One Command (PowerShell)
69
70 ```powershell
71 $ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi -OutFile "netdata-x64.msi"; msiexec /qn /i netdata-x64.msi TOKEN=<YOUR_TOKEN> ROOMS=<YOUR_ROOMS>
72 ```
73
56 -## Graphical User Interface (GUI) Installation
74 +---
75 +
76 +## Graphical Installation (GUI)
77 +
78 +1. Download the `.msi` installer.
79 +2. Double-click to run it.
80 +3. Grant Administrator privileges when prompted.
81 +4. Complete the setup wizard.
82 +
83 +---
84 +
85 +## Access Netdata Dashboard
86 +
87 +After installation, open your browser and go to:
88 +
89 +```
90 +http://localhost:19999
91 +```
92 +
93 +---
94 +
95 +## License Information
96
58 -1. **Double-click** the MSI installer to begin the installation process.
59 -2. **Grant Administrator Privileges**: You will be prompted to provide administrator permissions to install the Netdata service.
97 +By using silent installation, you agree to:
98
61 -After installation, you can access your Netdata dashboard by opening your browser and going to `localhost:19999`.
99 +- [GPL-3 License](https://raw.githubusercontent.com/netdata/netdata/refs/heads/master/LICENSE) — Netdata Agent
100 +- [NCUL1 License](https://app.netdata.cloud/LICENSE.txt) — Netdata Web Interface