docs: Restructure and deduplicate security docs #18594

bmorelli25 · 2020-05-15T19:29:44Z

What does this PR do?

This PR restructures the security documentation in a few different ways:

Secure content is now sorted in the order a user would complete each task.
The content in Configure authentication credentials, Configure {beatname} to use encrypted connections, and Secure communication with Elasticsearch has been consolidated and deduplicated into a single file: Secure communication with Elasticsearch. It has also been restructured to be more of a user guide.
User creation has moved to individual pages to allow room for APM Server to document the creation of additional user roles.

Before and after:

What doesn't this PR do?

This PR does not touch the Secure communication with Logstash or the Use Linux Secure Computing Mode (seccomp) files.

Related issues

elastic/apm-server#3596.

HTML preview

http://beats_18594.docs-preview.app.elstc.co/diff

Redirects

The following pages have been removed and will need redirects:

/beats-tls.html
/securing-beats.html
/beats-basic-auth.html

bmorelli25 · 2020-05-15T19:32:32Z

I have no idea which team label to apply to this. I guess APM, as that was the initial motivation for these changes, but these changes impact all Beats.

bmorelli25 · 2020-05-15T19:47:34Z

libbeat/docs/https.asciidoc

+ifndef::apm-server[]
+[role="xpack"]
+[float]
+[[securing-communication-kibana]]
+=== Secure communication with the Kibana endpoint
+
+If you've configured the <<setup-kibana-endpoint,{kib} endpoint>>,
+you can also specify credentials for authenticating with {kib} under `kibana.setup`.
+If no credentials are specified, Kibana will use the configured authentication method
+in the Elasticsearch output.
+
+For example, specify a unique username and password to connect to Kibana like this:
+
+--
+["source","yaml",subs="attributes,callouts"]
+----
+setup.kibana:
+  host: "mykibanahost:5601"
+  username: "{beat_default_index_prefix}_kib_setup" <1>
+  password: "{pwd}" <2>
+----
+<1> This user needs privileges required to set up dashboards. To create a user like this,
+see <<privileges-to-setup-beats>>.
+<2> This example shows a hard-coded password, but you should store sensitive
+values
+ifndef::serverless[]
+in the <<keystore,secrets keystore>>.
+endif::[]
+ifdef::serverless[]
+in environment variables.
+endif::[]
+endif::apm-server[]
+--


Should this content move to its own top-level heading/page? The TOC would then include:

Secure communication with Elasticsearch

Secure communication with Kibana

Secure communication with Logstash

Alternatively, we could group these under a new header, like this:

Secure communication with the Elastic Stack

Elasticsearch

Kibana

Logstash

I do like the idea of grouping the content under a new heading, "Secure communication with the Elastic Stack".

elasticmachine · 2020-05-15T19:51:08Z

💚 Build Succeeded

Expand to view the summary

Build stats

Build Cause: [Branch indexing]
Start Time: 2020-05-20T19:49:08.401+0000
Duration: 24 min 32 sec (1412247)

bmorelli25 · 2020-05-15T20:00:39Z

libbeat/docs/security/users.asciidoc


 [[privileges-to-setup-beats]]
-==== Grant privileges and roles needed for setup
+=== Grant privileges and roles needed for setup


If it's alright, I'll probably move each role into its own file in libbeat/docs/security/.

bmorelli25 · 2020-05-15T23:03:39Z

~~Please hold on reviewing this. I have some links to fix.~~

bmorelli25 · 2020-05-17T20:21:47Z

Ready for review again.

14:11:24 INFO:build_docs:Bad cross-document links:
14:11:24 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/elasticsearch/reference/master/beats.html:
14:11:24 INFO:build_docs:   - en/beats/auditbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/filebeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/heartbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/metricbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/packetbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/winlogbeat/master/securing-beats.html
14:11:24 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/elasticsearch/reference/master/ccs-clients-integrations.html:
14:11:24 INFO:build_docs:   - en/beats/auditbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/filebeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/heartbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/metricbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/packetbeat/master/securing-beats.html
14:11:24 INFO:build_docs:   - en/beats/winlogbeat/master/securing-beats.html
14:11:24 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/elasticsearch/reference/master/get-started-verify-users.html:
14:11:24 INFO:build_docs:   - en/beats/filebeat/master/securing-beats.html
14:11:24 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/elasticsearch/reference/master/ssl-tls.html:
14:11:24 INFO:build_docs:   - en/beats/filebeat/master/securing-beats.html

Broken links have been fixed in elastic/elasticsearch#56875.

bmorelli25 · 2020-05-19T16:16:53Z

@elasticmachine, run elasticsearch-ci/docs

EamonnTP

Looks good! As a newbie to Elastic, I found the content clear and concise to follow. As it's still early days for me, I feel @dedemorton would be in a better position to make a judgement call on the overall restructuring.

dedemorton

Thanks so much for taking this on! I like what you've done with the reorg. I had a couple of minor comments, but otherwise looks good! TBH it's been awhile since I've gone through the security setup myself. Let's make sure at least one developer from the beats team reviews this.

libbeat/docs/https.asciidoc

elasticmachine · 2020-05-27T18:42:33Z

💚 Build Succeeded

Expand to view the summary

Build stats

Build Cause: [Branch indexing]
Start Time: 2020-06-02T13:42:42.665+0000
Duration: 23 min 35 sec

…tic#20070)

…tic#20071)

docs: first draft

d4abc08

bmorelli25 added the docs label May 15, 2020

bmorelli25 requested a review from dedemorton May 15, 2020 19:29

bmorelli25 self-assigned this May 15, 2020

botelastic bot added the needs_team Indicates that the issue/PR needs a Team:* label label May 15, 2020

bmorelli25 added the Team:apm APM Server team issues/PRs label May 15, 2020

botelastic bot removed the needs_team Indicates that the issue/PR needs a Team:* label label May 15, 2020

bmorelli25 requested a review from EamonnTP May 15, 2020 19:33

bmorelli25 commented May 15, 2020

View reviewed changes

docs: fix build

f5b68c5

bmorelli25 commented May 15, 2020

View reviewed changes

bmorelli25 added 3 commits May 15, 2020 13:04

docs: update xpack attributes

c465fdf

docs: actually fix the build

54a93b1

docs: add no_dashboards to kib endpoint docs

24661b2

bmorelli25 mentioned this pull request May 15, 2020

docs: Update security documentation elastic/apm-server#3799

Merged

bmorelli25 mentioned this pull request May 17, 2020

[DOCS] update links to beats security docs elastic/elasticsearch#56875

Merged

EamonnTP approved these changes May 20, 2020

View reviewed changes

bmorelli25 mentioned this pull request May 26, 2020

[security] Review APM Server roles and their documentation elastic/apm-server#3596

Closed

dedemorton reviewed May 27, 2020

View reviewed changes

libbeat/docs/https.asciidoc Outdated Show resolved Hide resolved

libbeat/docs/https.asciidoc Outdated Show resolved Hide resolved

docs: update hosts

c12b5e7

docs: update includes for apm

2e1ae2f

bmorelli25 merged commit 9e38e66 into elastic:master Jun 4, 2020

bmorelli25 deleted the security-docs-structure branch June 4, 2020 15:11

bmorelli25 mentioned this pull request Jul 20, 2020

Cherry-pick to 7.9: docs: Restructure and deduplicate security docs (#18594) #20070

Merged

bmorelli25 added a commit to bmorelli25/beats that referenced this pull request Jul 20, 2020

docs: Restructure and deduplicate security docs (elastic#18594)

e714ac5

bmorelli25 mentioned this pull request Jul 20, 2020

Cherry-pick to 7.8: docs: Restructure and deduplicate security docs (#18594) #20071

Merged

bmorelli25 added a commit to bmorelli25/beats that referenced this pull request Jul 20, 2020

docs: Restructure and deduplicate security docs (elastic#18594)

766fa50

bmorelli25 added a commit to bmorelli25/beats that referenced this pull request Jul 20, 2020

docs: Restructure and deduplicate security docs (elastic#18594)

ec89fd3

bmorelli25 mentioned this pull request Jul 20, 2020

Cherry-pick to 7.x: docs: Restructure and deduplicate security docs (#18594) #20072

Merged

bmorelli25 added a commit that referenced this pull request Jul 21, 2020

docs: Restructure and deduplicate security docs (#18594) (#20071)

6d37d09

bmorelli25 added a commit that referenced this pull request Jul 21, 2020

docs: Restructure and deduplicate security docs (#18594) (#20070)

5d7e9b1

bmorelli25 added a commit that referenced this pull request Jul 21, 2020

docs: Restructure and deduplicate security docs (#18594) (#20072)

4d0fcea

melchiormoulin pushed a commit to melchiormoulin/beats that referenced this pull request Oct 14, 2020

docs: Restructure and deduplicate security docs (elastic#18594)

df33aea

leweafan pushed a commit to leweafan/beats that referenced this pull request Apr 28, 2023

docs: Restructure and deduplicate security docs (elastic#18594) (elas…

0e8ce4e

…tic#20070)

leweafan pushed a commit to leweafan/beats that referenced this pull request Apr 28, 2023

docs: Restructure and deduplicate security docs (elastic#18594) (elas…

b0b8a91

…tic#20071)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Restructure and deduplicate security docs #18594

docs: Restructure and deduplicate security docs #18594

bmorelli25 commented May 15, 2020 •

edited

Loading

bmorelli25 commented May 15, 2020 •

edited

Loading

bmorelli25 May 15, 2020

EamonnTP May 20, 2020

elasticmachine commented May 15, 2020 •

edited

Loading

Build stats

bmorelli25 May 15, 2020

bmorelli25 commented May 15, 2020 •

edited

Loading

bmorelli25 commented May 17, 2020

bmorelli25 commented May 19, 2020

EamonnTP left a comment

dedemorton left a comment

elasticmachine commented May 27, 2020 •

edited

Loading

Build stats

docs: Restructure and deduplicate security docs #18594

docs: Restructure and deduplicate security docs #18594

Conversation

bmorelli25 commented May 15, 2020 • edited Loading

What does this PR do?

What doesn't this PR do?

Related issues

HTML preview

Redirects

bmorelli25 commented May 15, 2020 • edited Loading

bmorelli25 May 15, 2020

Choose a reason for hiding this comment

EamonnTP May 20, 2020

Choose a reason for hiding this comment

elasticmachine commented May 15, 2020 • edited Loading

💚 Build Succeeded

Build stats

bmorelli25 May 15, 2020

Choose a reason for hiding this comment

bmorelli25 commented May 15, 2020 • edited Loading

bmorelli25 commented May 17, 2020

bmorelli25 commented May 19, 2020

EamonnTP left a comment

Choose a reason for hiding this comment

dedemorton left a comment

Choose a reason for hiding this comment

elasticmachine commented May 27, 2020 • edited Loading

💚 Build Succeeded

Build stats

bmorelli25 commented May 15, 2020 •

edited

Loading

bmorelli25 commented May 15, 2020 •

edited

Loading

elasticmachine commented May 15, 2020 •

edited

Loading

bmorelli25 commented May 15, 2020 •

edited

Loading

elasticmachine commented May 27, 2020 •

edited

Loading