diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc
index b3dbcf2462e5..e009a753984e 100644
--- a/filebeat/docs/getting-started.asciidoc
+++ b/filebeat/docs/getting-started.asciidoc
@@ -242,6 +242,8 @@ specified. See
 {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
 in the _Beats Platform Reference_.
 
+include::{libbeat-dir}/docs/shared-brew-run.asciidoc[]
+
 *win:*
 
 [source,shell]
diff --git a/filebeat/docs/include/enable-modules-command.asciidoc b/filebeat/docs/include/enable-modules-command.asciidoc
index 243aef3d9216..4545e2e6e966 100644
--- a/filebeat/docs/include/enable-modules-command.asciidoc
+++ b/filebeat/docs/include/enable-modules-command.asciidoc
@@ -13,6 +13,13 @@
 ./{beatname_lc} modules enable {modulename}
 ----
 
+*brew:*
+
+["source","sh",subs="attributes"]
+----
+{beatname_lc} modules enable {modulename}
+----
+
 *linux:*
 
 ["source","sh",subs="attributes"]
diff --git a/filebeat/docs/include/list-modules-command.asciidoc b/filebeat/docs/include/list-modules-command.asciidoc
index ca4cf789e345..c79012325c75 100644
--- a/filebeat/docs/include/list-modules-command.asciidoc
+++ b/filebeat/docs/include/list-modules-command.asciidoc
@@ -13,6 +13,13 @@
 ./{beatname_lc} modules list
 ----
 
+*brew:*
+
+["source","sh",subs="attributes"]
+----
+{beatname_lc} modules list
+----
+
 *linux:*
 
 ["source","sh",subs="attributes"]
diff --git a/filebeat/docs/include/run-command.asciidoc b/filebeat/docs/include/run-command.asciidoc
index 9d24f60c1923..6a43b9bf8f3a 100644
--- a/filebeat/docs/include/run-command.asciidoc
+++ b/filebeat/docs/include/run-command.asciidoc
@@ -13,6 +13,13 @@ service {beatname_lc} start
 ./{beatname_lc} -e
 ----
 
+*brew:*
+
+["source","sh",subs="attributes"]
+----
+{beatname_lc} -e
+----
+
 *linux:*
 
 ["source","sh",subs="attributes"]
diff --git a/filebeat/docs/include/set-paths.asciidoc b/filebeat/docs/include/set-paths.asciidoc
index 07f9ffa0b490..6e28d978b453 100644
--- a/filebeat/docs/include/set-paths.asciidoc
+++ b/filebeat/docs/include/set-paths.asciidoc
@@ -28,6 +28,13 @@ must include the module and fileset name. For example:
 ./{beatname_lc} -e -M "nginx.access.var.paths=[/usr/local/var/log/nginx/access.log*]"
 ----
 
+*brew:*
+
+["source","sh",subs="attributes"]
+----
+{beatname_lc} -e -M "nginx.access.var.paths=[/usr/local/var/log/nginx/access.log*]"
+----
+
 *linux:*
 
 ["source","sh",subs="attributes"]
diff --git a/filebeat/docs/include/setup-command.asciidoc b/filebeat/docs/include/setup-command.asciidoc
index da0cc006ffd1..68fc66a03d69 100644
--- a/filebeat/docs/include/setup-command.asciidoc
+++ b/filebeat/docs/include/setup-command.asciidoc
@@ -20,6 +20,13 @@
 ./{beatname_lc} setup -e
 ----
 
+*brew:*
+
+["source","sh",subs="attributes"]
+----
+{beatname_lc} setup -e
+----
+
 *win:*
 
 ["source","sh",subs="attributes"]
diff --git a/heartbeat/docs/getting-started.asciidoc b/heartbeat/docs/getting-started.asciidoc
index 834bf4a7f418..0d3427cebc5f 100644
--- a/heartbeat/docs/getting-started.asciidoc
+++ b/heartbeat/docs/getting-started.asciidoc
@@ -248,6 +248,10 @@ configuration file, or run Heartbeat with `--strict.perms=false` specified. See
 {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
 in the _Beats Platform Reference_.
 
+:requires-sudo:
+include::{libbeat-dir}/docs/shared-brew-run.asciidoc[]
+:requires-sudo!:
+
 *win:*
 
 ["source","sh",subs="attributes"]
diff --git a/libbeat/docs/dashboards.asciidoc b/libbeat/docs/dashboards.asciidoc
index 015ac13a2d41..ea8b7d48d754 100644
--- a/libbeat/docs/dashboards.asciidoc
+++ b/libbeat/docs/dashboards.asciidoc
@@ -41,11 +41,9 @@ If you've configured the Logstash output, see
 <<load-dashboards-logstash>>.
 endif::only-elasticsearch[]
 
-ifeval::["{requires-sudo}"=="yes"]
-
+ifdef::requires-sudo[]
 include::../../libbeat/docs/shared-note-sudo.asciidoc[]
-
-endif::[]
+endif::requires-sudo[]
 
 ifdef::deb_os,rpm_os[]
 *deb and rpm:*
diff --git a/libbeat/docs/shared-brew-run.asciidoc b/libbeat/docs/shared-brew-run.asciidoc
index 20a07c22d66f..ff6d37bad73f 100644
--- a/libbeat/docs/shared-brew-run.asciidoc
+++ b/libbeat/docs/shared-brew-run.asciidoc
@@ -5,9 +5,10 @@ run:
 
 ["source","sh",subs="attributes"]
 -----
-brew services start elastic/tap/{beatname_lc}
+brew services start elastic/tap/{beatname_lc}-full
 -----
 
+ifndef::requires-sudo[]
 To run {beatname_uc} in the foreground instead of running it as a background
 service, run:
 
@@ -15,3 +16,38 @@ service, run:
 -----
 {beatname_lc} -e
 -----
+endif::[]
+
+ifdef::requires-sudo[]
+To run {beatname_uc} in the foreground instead of running it as a background
+service, run:
+
+ifndef::has_modules_command[]
+["source","sh",subs="attributes"]
+-----
+sudo chown root /usr/local/etc/{beatname_lc}/beatname_lc.yml <1>
+sudo {beatname_lc} -e
+-----
+<1> You'll be running {beatname_uc} as root, so you need to change ownership
+of the configuration file, or run {beatname_uc} with `--strict.perms=false`
+specified. See
+{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
+in the _Beats Platform Reference_.
+endif::has_modules_command[]
+
+ifdef::has_modules_command[]
+["source","sh",subs="attributes,callouts"]
+----------------------------------------------------------------------
+sudo chown root /usr/local/etc/{beatname_lc}/{beatname_lc}.yml <1>
+sudo chown root /usr/local/etc/{beatname_lc}/modules.d/system.yml <1>
+sudo {beatname_lc} -e
+----------------------------------------------------------------------
+<1> You'll be running {beatname_uc} as root, so you need to change ownership of the
+configuration file and any configurations enabled in the `modules.d` directory,
+or run {beatname_uc} with `--strict.perms=false` specified. See
+{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
+in the _Beats Platform Reference_.
+
+endif::has_modules_command[]
+
+endif::requires-sudo[]
diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/shared-template-load.asciidoc
index 4de4a1feaf77..b7fe1b7bddc6 100644
--- a/libbeat/docs/shared-template-load.asciidoc
+++ b/libbeat/docs/shared-template-load.asciidoc
@@ -137,11 +137,9 @@ ifdef::only-elasticsearch[]
 :disable_logstash:
 endif::only-elasticsearch[]
 
-ifeval::["{requires-sudo}"=="yes"]
-
+ifdef::requires-sudo[]
 include::./shared-note-sudo.asciidoc[]
-
-endif::[]
+endif::requires-sudo[]
 
 ifdef::deb_os,rpm_os[]
 *deb and rpm:*
diff --git a/libbeat/docs/step-test-config.asciidoc b/libbeat/docs/step-test-config.asciidoc
index 378c6b4d51e3..fb0378b1a167 100644
--- a/libbeat/docs/step-test-config.asciidoc
+++ b/libbeat/docs/step-test-config.asciidoc
@@ -1,15 +1,12 @@
-ifeval::["{requires-sudo}"!="yes"]
-
+ifndef::requires-sudo[]
 TIP: To test your configuration file, change to the directory where the
 {beatname_uc} binary is installed, and run {beatname_uc} in the foreground with
 the following options specified: +./{beatname_lc} test config -e+. Make sure your
 config files are in the path expected by {beatname_uc} (see <<directory-layout>>),
 or use the `-c` flag to specify the path to the config file.
-
 endif::[]
 
-ifeval::["{requires-sudo}"=="yes"]
-
+ifdef::requires-sudo[]
 TIP: To test your configuration file, change to the directory where the
 {beatname_uc} binary is installed, and run {beatname_uc} in the foreground with
 the following options specified: +sudo ./{beatname_lc} test config -e+. Make sure
@@ -19,5 +16,4 @@ file. Depending on your OS, you might run into file ownership issues when you
 run this test. See
 {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
 in the _Beats Platform Reference_ for more information.
-
 endif::[]
diff --git a/metricbeat/docs/gettingstarted.asciidoc b/metricbeat/docs/gettingstarted.asciidoc
index d6b0821f7d42..5f7c17cb1e28 100644
--- a/metricbeat/docs/gettingstarted.asciidoc
+++ b/metricbeat/docs/gettingstarted.asciidoc
@@ -272,6 +272,10 @@ or run {beatname_uc} with `--strict.perms=false` specified. See
 {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]
 in the _Beats Platform Reference_.
 
+:requires-sudo:
+include::{libbeat-dir}/docs/shared-brew-run.asciidoc[]
+:requires-sudo!:
+
 *win:*
 
 ["source","sh",subs="attributes"]
diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc
index 195c2de44be0..0b852196064c 100644
--- a/packetbeat/docs/gettingstarted.asciidoc
+++ b/packetbeat/docs/gettingstarted.asciidoc
@@ -239,7 +239,6 @@ include::{libbeat-dir}/docs/step-configure-kibana-endpoint.asciidoc[]
 
 include::{libbeat-dir}/docs/step-configure-credentials.asciidoc[]
 
-:requires-sudo: yes
 include::{libbeat-dir}/docs/step-test-config.asciidoc[]
 
 include::{libbeat-dir}/docs/step-look-at-config.asciidoc[]
@@ -247,13 +246,11 @@ include::{libbeat-dir}/docs/step-look-at-config.asciidoc[]
 [[packetbeat-template]]
 === Step 3: Load the index template in Elasticsearch
 
-:requires-sudo: yes
 include::{libbeat-dir}/docs/shared-template-load.asciidoc[]
 
 [[load-kibana-dashboards]]
 === Step 4: Set up the Kibana dashboards
 
-:requires-sudo: yes
 include::{libbeat-dir}/docs/dashboards.asciidoc[]
 
 [[packetbeat-starting]]
@@ -290,6 +287,8 @@ configuration file, or run Packetbeat with `--strict.perms=false` specified. See
 {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]in
 the _Beats Platform Reference_.
 
+include::{libbeat-dir}/docs/shared-brew-run.asciidoc[]
+
 *win:*
 
 [source,shell]
diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc
index 71176055309d..3b37e267dad4 100644
--- a/packetbeat/docs/index.asciidoc
+++ b/packetbeat/docs/index.asciidoc
@@ -14,6 +14,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 :discuss_forum: beats/{beatname_lc}
 :beat_default_index_prefix: {beatname_lc}
 :has_ml_jobs: yes
+:requires-sudo:
 :has_map:
 :deb_os:
 :rpm_os: