@cryptotaxi247 / netdata / commits / 9f88bee34

docs: task class: improve_docs — add claiming instructions for (#22568)

* docs: update docs/netdata-homebrew-claiming-deprecated-script * docs: Execution completed * docs: tighten Homebrew claim.conf permissions guidance Agent-Logs-Url: https://github.com/netdata/netdata/sessions/04137ccd-fe0d-4967-aa5d-0b1d0e265be2 Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * docs: clarify Homebrew claiming permissions and kickstart scope Agent-Logs-Url: https://github.com/netdata/netdata/sessions/a8b299ca-1c68-4be6-8335-d764627c731c Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: deduplicate Homebrew cloud-connection cross-reference Agent-Logs-Url: https://github.com/netdata/netdata/sessions/3ad3db6d-1709-47f3-9335-ce58129732cd Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * docs: clarify macOS claiming ownership scope and Homebrew paths Agent-Logs-Url: https://github.com/netdata/netdata/sessions/50b2aa1a-042c-491c-befb-9362c6482b03 Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Ancairon <70198089+Ancairon@users.noreply.github.com> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

nedi-app[bot] committed May 26, 2026 at 13:12 UTC 9f88bee3450a032d435ed4348a45b53231675596
2 files changed +54 -3
packaging/installer/methods/macos.md
+36
@@ -57,6 +57,8 @@ If you experience issues while connecting your node, follow the steps in our [Tr
57
58 ## Install Netdata via Homebrew
59
60 +To connect this Agent to Netdata Cloud, see [Connect a Homebrew-installed Agent to Netdata Cloud](#connect-a-homebrew-installed-agent-to-netdata-cloud) below.
61 +
62 ### For macOS Intel
63
64 To install Netdata and all its dependencies, run Homebrew using the following command:
@@ -81,6 +83,40 @@ Homebrew will place your Netdata configuration directory at `/opt/homebrew/etc/n
83
84 Use the `edit-config` script and the files in this directory to configure Netdata. For reference, you can find stock configuration files at `/opt/homebrew/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/`.
85
86 +### Connect a Homebrew-installed Agent to Netdata Cloud
87 +
88 +The easiest way to connect a Homebrew-installed Netdata Agent to Netdata Cloud is via the local dashboard UI, as described in [Method 1: Via UI](/src/claim/README.md#method-1-via-ui-recommended):
89 +
90 +1. Open the local dashboard in your browser at `http://localhost:19999` (or the Agent's IP address at port 19999).
91 +2. Sign in to your Netdata Cloud account.
92 +3. Click the **Connect** button and follow the on-screen instructions.
93 +
94 +For automated setups or headless machines where the UI is not accessible, you can use one of these alternatives:
95 +
96 +- **Kickstart script claiming flags** — this requires installing/reinstalling with kickstart (it installs under `/usr/local/netdata` by default, or your `--install-prefix` path) rather than adding flags to an existing Homebrew install. If you want to keep the Homebrew install, use the **Configuration file** method below. See the [kickstart claiming section](#automatically-connect-to-netdata-cloud-during-installation) above or the full [kickstart documentation](/packaging/installer/methods/kickstart.md).
97 +- **Configuration file** — create a `claim.conf` file in your Netdata configuration directory using the [configuration file method](/src/claim/README.md#method-2-via-configuration-file).
98 +
99 +**Configuration directory paths for `claim.conf`:**
100 +
101 +| Architecture | Path |
102 +|:--------------|:---------------------------------------|
103 +| Intel | `/usr/local/etc/netdata/claim.conf` |
104 +| Apple Silicon | `/opt/homebrew/etc/netdata/claim.conf` |
105 +
106 +:::note
107 +
108 +On macOS, Homebrew installs run under your user account and the `netdata` group does not exist. Use your own user and the `staff` group for file ownership when creating `claim.conf` manually. For full details on permissions and applying the configuration, see the [configuration file method](/src/claim/README.md#method-2-via-configuration-file).
109 +
110 +:::
111 +
112 +:::caution
113 +
114 +Do **not** run the `netdata-claim.sh` script manually. It is deprecated and will be unsupported in the near future. Instead, use one of the supported claiming methods described above: the Cloud UI, kickstart claiming flags during install/reinstall, or a `claim.conf` file.
115 +
116 +:::
117 +
118 +For the full list of claiming options and troubleshooting, see [Connect Agent to Cloud](/src/claim/README.md).
119 +
120 ## Install Netdata from source
121
122 We don't recommend installing Netdata from source on macOS, as it can be difficult to configure and install dependencies manually.
src/claim/README.md
+18 -3
@@ -46,13 +46,28 @@ Create `/INSTALL_PREFIX/etc/netdata/claim.conf`:
46
47 The `claim.conf` file contains sensitive claiming tokens and must be properly secured:
48
49 -- **Required permissions:** `0640` (owner read/write, group read, no world access)
50 -- **Required ownership:** `root:netdata` (owner root, group netdata)
49 +- **Required permissions (service installs):** `0640` (owner read/write, group read, no world access)
50 +- **Required ownership (service installs):** `root:netdata` (owner root, group netdata)
51
52 -The claiming script automatically sets these permissions when creating or updating `claim.conf`. If you create the file manually, ensure it follows these same security standards to prevent unauthorized access to your claiming tokens.
52 +The Netdata Cloud-generated claiming command automatically sets these permissions when creating or updating `claim.conf`. If you create the file manually, ensure it follows these same security standards to prevent unauthorized access to your claiming tokens.
53
54 :::
55
56 +:::note
57 +
58 +On macOS with Homebrew installs, the `netdata` group does not exist. Set ownership to your own user and the `staff` group instead:
59 +
60 +```bash
61 +chown $(whoami):staff /usr/local/etc/netdata/claim.conf # Intel
62 +chown $(whoami):staff /opt/homebrew/etc/netdata/claim.conf # Apple Silicon
63 +chmod 0600 /usr/local/etc/netdata/claim.conf # Intel
64 +chmod 0600 /opt/homebrew/etc/netdata/claim.conf # Apple Silicon
65 +```
66 +
67 +This prevents the `chown: netdata: illegal group name` error.
68 +Using `0600` is acceptable for Homebrew installs because the Netdata Agent runs under the same user that owns the file.
69 +
70 +:::
71
72 **Configuration Options:**
73