docs: clarify static build transition process for EOL platforms (#20110)
* docs: clarify static build transition process for EOL platforms * improve steps
Ilya Mashchenko committed
Apr 10, 2025 at 11:25 UTC
000c71fc4e8ecd529d52eedad5c99ffb6788b316
1 file changed
+34
-17
docs/netdata-agent/versions-and-platforms.md
+34
-17
@@ -58,31 +58,40 @@ The following builds from source should usually work, although we don't regularl
58
59
## Static Builds and Unsupported Linux Versions
60
61
-The static builds of Netdata can be used on any Linux platform of the supported architectures. The only requirement these static builds have is a working Linux kernel, any version. Everything else required for Netdata to run is inside the package itself.
61
+Netdata's static builds can run on any Linux platform with supported architecture, requiring only a functioning Linux kernel of any version. These self-contained packages include everything Netdata needs to operate effectively.
62
63
-Static builds usually miss certain features that require operating-system support and can’t be provided generically. These features include:
63
+### Limitations of Static Builds
64
65
-- IPMI hardware sensors support
66
-- systemd-journal features
67
-- eBPF related features
65
+Static builds lack certain features that require specific operating system support, including:
66
69
-When platforms are removed from the [Binary Distribution Packages](/packaging/makeself/README.md) list, they default to install or update Netdata to a static build. This may mean that after platforms become EOL, Netdata on them may lose some of its features. We recommend upgrading the operating system before it becomes EOL, to continue using all the features of Netdata.
67
+- IPMI hardware sensors monitoring
68
+- systemd-journal functionality
69
+- eBPF-related capabilities
70
71
-### Migrating from Native Package to Static Build
71
+### Impact of Platform End-of-Life (EOL)
72
+
73
+**Important**: When a platform is removed from the [Binary Distribution Packages list](/packaging/makeself/README.md):
74
73
-Existing installs of native packages on a platform that is no longer supported, are not automatically updated. The upgrade process will show the Agent is already at the newest version, because we no longer publish new packages for that platform.
75
+- **No automatic transitions occur** - Existing native package installations will remain as-is.
76
+- Your local updater will report the Agent as up-to-date even when newer versions exist.
77
+- When a new Netdata version is published, you'll see "Nodes are below the recommended Agent version" warnings in the Netdata Cloud UI.
78
+- You will stop receiving new features, improvements, and security updates.
79
75
-If the operating system cannot be upgraded to a more recent version, the install can be switched to a static build. This is a manual process, may cause data loss, and is therefore **not supported**. However, following these steps should result in a functioning Agent with metrics data and connection to Netdata Cloud in tact:
80
+We strongly recommend upgrading your operating system before it reaches EOL to maintain full Netdata functionality and continued updates.
81
+
82
+### Migrating from Native Package to Static Build
83
77
-1. Stop the Agent, [as appropriate for your platform](/docs/netdata-agent/start-stop-restart.md).
78
-2. Backup the contents of these directories: `/etc/netdata`, `/var/cache/netdata`, `/var/lib/netdata`, `/var/log/netdata`.
79
-3. Uninstall the native package, answering "yes" to all questions.
84
+If upgrading your operating system isn't possible, you can manually switch to a static build. Please note that this process is **not officially supported** and may result in data loss. However, following these steps should preserve your metrics data and Netdata Cloud connection:
85
+
86
+1. Stop the Netdata Agent [using the appropriate method for your platform](/docs/netdata-agent/start-stop-restart.md).
87
+2. Back up your Netdata configuration and data: `/etc/netdata`, `/var/cache/netdata`, `/var/lib/netdata`, `/var/log/netdata`.
88
+3. Uninstall the native package (confirm all prompts with "yes").
89
90
```sh
91
wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --uninstall
92
```
93
85
-4. For platforms using systemd, unmask the Netdata service:
94
+4. For systemd-based platforms, unmask the Netdata service:
95
96
```sh
97
sudo systemctl unmask netdata
@@ -92,13 +101,21 @@ If the operating system cannot be upgraded to a more recent version, the install
101
5. Install the static build:
102
103
```sh
95
- sh /tmp/netdata-kickstart.sh --static-only
104
+ # For nightly builds
105
+ sh /tmp/netdata-kickstart.sh --static-only --dont-start-it
106
+
107
+ # For stable release builds
108
+ sh /tmp/netdata-kickstart.sh --static-only --dont-start-it --stable-channel
109
```
110
98
-6. Stop the Agent (again).
99
-7. Copy over the data from the previous install:
111
+6. Restore your data from the previous installation:
112
113
```sh
114
+ # Install rsync if needed (example for Debian/Ubuntu)
115
+ # sudo apt-get update && sudo apt-get install -y rsync
116
+ # For RHEL/CentOS/Fedora
117
+ # sudo yum install -y rsync
118
+
119
cd /opt/netdata
120
sudo rsync -aRv --delete \
121
--exclude /etc/netdata/.install-type \
@@ -106,4 +123,4 @@ If the operating system cannot be upgraded to a more recent version, the install
123
/etc/netdata /var/lib/netdata /var/cache/netdata /var/log/netdata ./
124
```
125
109
-8. Start the Agent.
126
+7. Start the Netdata Agent to complete the migration.