Skip to content

Commit 6a5fbdb

Browse files
authored
[DOCS] Adds tutorial for getting started with security
2 parents 29e3f5e + dd7d54b commit 6a5fbdb

15 files changed

+464
-42
lines changed

docs/en/stack/getting-started/get-started-stack.asciidoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ then {cloud}/ec-enable-kibana.html[Kibana can be enabled] with the flick of a sw
213213
We recommend that you install {kib} on the same server as {es},
214214
but it is not required. If you install the products on different servers, you'll
215215
need to change the URL (IP:PORT) of the {es} server in the {kib} configuration
216-
file, `config/kibana.yml`, before starting {kib}.
216+
file, `kibana.yml`, before starting {kib}.
217217

218218
To download and install {kib}, open a terminal window and use the commands that
219219
work with your system:
@@ -498,6 +498,7 @@ The `setup` command loads the {kib} dashboards. If the dashboards are already
498498
set up, omit this command. The `-e` flag is optional and sends output to
499499
standard error instead of syslog.
500500

501+
[[gs-start-metricbeat]]
501502
. Start {metricbeat}:
502503
+
503504
*deb and rpm:*
@@ -690,6 +691,7 @@ through {ls}, where you have full access to {ls} capabilities for collecting,
690691
enriching, and transforming data.
691692

692693
[float]
694+
[[gs-start-logstash]]
693695
==== Start {ls}
694696

695697
Use the command that works with your system. If you installed {ls} as a deb or
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
There are built-in users that you can use for specific administrative purposes:
2+
`elastic`, `kibana`, `logstash_system`, and `beats_system`.
3+
4+
Before you can use them, you must set their passwords:
5+
6+
. Restart {es}. For example, if you installed {es} with a `.tar.gz` package, run
7+
the following command from the {es} directory:
8+
+
9+
--
10+
["source","sh",subs="attributes,callouts"]
11+
----------------------------------------------------------------------
12+
./bin/elasticsearch
13+
----------------------------------------------------------------------
14+
15+
See {ref}/starting-elasticsearch.html[Starting {es}].
16+
--
17+
18+
. Set the built-in users' passwords. Run the following command from the {es}
19+
directory:
20+
+
21+
--
22+
["source","sh",subs="attributes,callouts"]
23+
----------------------------------------------------------------------
24+
./bin/elasticsearch-setup-passwords interactive
25+
----------------------------------------------------------------------
26+
--
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
When you use the trial license, {security} is disabled by default. To enable it:
2+
3+
. Stop {kib}. The method for starting and stopping {kib} varies depending on
4+
how you installed it. For example, if you installed {kib} from an archive
5+
distribution (`.tar.gz` or `.zip`), stop it by entering `Ctrl-C` on the command
6+
line. See {kibana-ref}/start-stop.html[Starting and stopping {kib}].
7+
8+
. Stop {es}. For example, if you installed {es} from an archive distribution,
9+
enter `Ctrl-C` on the command line. See
10+
{ref}/stopping-elasticsearch.html[Stopping {es}].
11+
12+
. Add the `xpack.security.enabled` setting to the
13+
`ES_PATH_CONF/elasticsearch.yml` file.
14+
+
15+
--
16+
TIP: The `ES_PATH_CONF` environment variable contains the path for the {es}
17+
configuration files. If you installed {es} using archive distributions (`zip` or
18+
`tar.gz`), it defaults to `ES_HOME/config`. If you used package distributions
19+
(Debian or RPM), it defaults to `/etc/elasticsearch`. For more information, see
20+
{ref}/settings.html[Configuring {es}].
21+
22+
For example, add the following setting:
23+
24+
[source,yaml]
25+
----
26+
xpack.security.enabled: true
27+
----
28+
29+
TIP: If you have a basic or trial license, the default value for this setting is
30+
`false`. If you have a gold or higher license, the default value is `true`.
31+
Therefore, it is a good idea to explicitly add this setting to avoid confusion
32+
about whether {security} is enabled.
33+
34+
--
35+
36+
When you enable {security}, basic authentication is enabled by default. To
37+
communicate with the cluster, you must specify a username and password.
38+
Unless you <<anonymous-access,enable anonymous access>>, all requests that don't
39+
include a user name and password are rejected.
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
When {security} is enabled, users must log in to {kib} with a valid user ID and
2+
password.
3+
4+
{kib} also performs some tasks under the covers that require use of the
5+
built-in `kibana` user.
6+
7+
. Configure {kib} to use the built-in `kibana` user and the password that you
8+
created:
9+
10+
** If you don't mind having passwords visible in your configuration file,
11+
uncomment and update the following settings in the `kibana.yml` file in your
12+
{kib} directory:
13+
+
14+
--
15+
TIP: If you installed {kib} using archive distributions (`zip` or
16+
`tar.gz`), the `kibana.yml` configuration file is in `KIBANA_HOME/config`. If
17+
you used package distributions (Debian or RPM), it's in `/etc/kibana`. For more
18+
information, see {kibana-ref}/settings.html[Configuring {kib}].
19+
20+
For example, add the following settings:
21+
22+
[source,yaml]
23+
----
24+
elasticsearch.username: "kibana"
25+
elasticsearch.password: "your_password"
26+
----
27+
28+
Specify the password that you set with the `elasticsearch-setup-passwords`
29+
command then save your changes to the file.
30+
--
31+
32+
** If you prefer not to put your user ID and password in the `kibana.yml` file,
33+
store them in a keystore instead. Run the following commands to create the {kib}
34+
keystore and add the secure settings:
35+
+
36+
--
37+
["source","sh",subs="attributes,callouts"]
38+
----------------------------------------------------------------------
39+
./bin/kibana-keystore create
40+
./bin/kibana-keystore add elasticsearch.username
41+
./bin/kibana-keystore add elasticsearch.password
42+
----------------------------------------------------------------------
43+
44+
When prompted, specify the `kibana` built-in user and its password for these
45+
setting values. The settings are automatically applied when you start {kib}.
46+
To learn more, see {kibana-ref}/secure-settings.html[Secure settings].
47+
--
48+
49+
. Restart {kib}. For example, if you installed
50+
{kib} with a `.tar.gz` package, run the following command from the {kib}
51+
directory:
52+
+
53+
--
54+
["source","sh",subs="attributes,callouts"]
55+
----------------------------------------------------------------------
56+
./bin/kibana
57+
----------------------------------------------------------------------
58+
59+
See {kibana-ref}/start-stop.html[Starting and stopping {kib}].
60+
--

0 commit comments

Comments
 (0)