Document switching from a native package to a static build (#20075)
* Document switching from a native package to a static build Even though we document that static builds can be used on platforms that are not, or no longer, supported, we do not explain how to _switch_ from a native package to a static build. This PR addresses that. * Link to start-stop documentation. Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> * Add whitespace after code blocks * Remove systemd commands, except step 4 This is because without step 4, the service will not work properly after install. * Apply suggestions from code review * Apply suggestions from code review --------- Co-authored-by: Fotis Voutsas <fotis@netdata.cloud>
Ralph Meijer committed
Apr 9, 2025 at 10:38 UTC
c4682dab1475f1aca9c2daba19b14087ac373e33
1 file changed
+40
docs/netdata-agent/versions-and-platforms.md
+40
@@ -67,3 +67,43 @@ Static builds usually miss certain features that require operating-system suppor
67
- eBPF related features
68
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.
70
+
71
+### Migrating from Native Package to Static Build
72
+
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.
74
+
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:
76
+
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.
80
+
81
+ ```sh
82
+ wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --uninstall
83
+ ```
84
+
85
+4. For platforms using systemd, unmask the Netdata service:
86
+
87
+ ```sh
88
+ sudo systemctl unmask netdata
89
+ sudo systemctl daemon-reload
90
+ ```
91
+
92
+5. Install the static build:
93
+
94
+ ```sh
95
+ sh /tmp/netdata-kickstart.sh --static-only
96
+ ```
97
+
98
+6. Stop the Agent (again).
99
+7. Copy over the data from the previous install:
100
+
101
+ ```sh
102
+ cd /opt/netdata
103
+ sudo rsync -aRv --delete \
104
+ --exclude /etc/netdata/.install-type \
105
+ --exclude /etc/netdata/.environment \
106
+ /etc/netdata /var/lib/netdata /var/cache/netdata /var/log/netdata ./
107
+ ```
108
+
109
+8. Start the Agent.