Skip to content

Commit 335e778

Browse files
committed
[DOCS] Adds tutorial for getting started with security
1 parent bd3d1fe commit 335e778

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
@@ -212,7 +212,7 @@ then {cloud}/ec-enable-kibana.html[Kibana can be enabled] with the flick of a sw
212212
We recommend that you install {kib} on the same server as {es},
213213
but it is not required. If you install the products on different servers, you'll
214214
need to change the URL (IP:PORT) of the {es} server in the {kib} configuration
215-
file, `config/kibana.yml`, before starting {kib}.
215+
file, `kibana.yml`, before starting {kib}.
216216

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

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

691692
[float]
693+
[[gs-start-logstash]]
692694
==== Start {ls}
693695

694696
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)