Skip to content

Commit

Permalink
[DOCS] Update archive install docs for security ON by default (#80375)
Browse files Browse the repository at this point in the history
* [DOCS] Update archive install docs for security ON by default

* Remove extra attribute references that aren't needed

* Incorporate security info into start page

* Update heading
  • Loading branch information
Adam Locke authored Nov 5, 2021
1 parent 36ebac3 commit b13df02
Show file tree
Hide file tree
Showing 9 changed files with 84 additions and 28 deletions.
6 changes: 3 additions & 3 deletions docs/reference/setup/install/check-running.asciidoc
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
==== Checking that Elasticsearch is running
==== Check that Elasticsearch is running

You can test that your {es} node is running by sending an HTTPS request to port
`9200` on `localhost`:

[source,shell]
["source","sh",subs="attributes"]
----
curl --cacert /etc/elasticsearch/tls_auto_config_<timestamp>/http_ca.crt \
curl --cacert {os-dir}/tls_auto_config_<timestamp>/http_ca.crt \
-u elastic https://localhost:9200 <1>
----
// NOTCONSOLE
Expand Down
3 changes: 3 additions & 0 deletions docs/reference/setup/install/deb.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,9 @@ endif::include-xpack[]
include::systemd.asciidoc[]

[[deb-check-running]]

:os-dir: /etc/elasticsearch

include::check-running.asciidoc[]

[[deb-configuring]]
Expand Down
3 changes: 3 additions & 0 deletions docs/reference/setup/install/rpm.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,9 @@ endif::include-xpack[]
include::systemd.asciidoc[]

[[rpm-check-running]]

:os-dir: /etc/elasticsearch

include::check-running.asciidoc[]

[[rpm-configuring]]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
===== Security certificates and keys

When you install {es}, the following certificates and keys are
generated in the `/etc/elasticsearch/tls_auto_config_<timestamp>` directory,
which are used to connect a {kib} instance to your secured {es} cluster and
to encrypt internode communication. The files are listed here for reference.
generated in the {es} configuration directory, which are used to connect a {kib}
instance to your secured {es} cluster and to encrypt internode communication.
The files are listed here for reference.

`http_ca.crt`::
The CA certificate that is used to sign the certificates for the HTTP layer of
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/setup/install/targz-daemon.asciidoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
==== Running as a daemon
==== Run as a daemon

To run Elasticsearch as a daemon, specify `-d` on the command line, and record
the process ID in a file using the `-p` option:
Expand Down
53 changes: 46 additions & 7 deletions docs/reference/setup/install/targz-start.asciidoc
Original file line number Diff line number Diff line change
@@ -1,26 +1,65 @@
==== Running Elasticsearch from the command line
==== Run {es} from the command line

Elasticsearch can be started from the command line as follows:
Run the following command to start {es} from the command line:

[source,sh]
--------------------------------------------
----
./bin/elasticsearch
--------------------------------------------
----

When starting {es} for the first time, security features are enabled and
configured by default. The following security configuration occurs
automatically:

* Authentication and authorization are enabled, and a password is generated for
the `elastic` built-in superuser.
* Certificates and keys for TLS are generated for the transport and HTTP layer,
and TLS is enabled and configured with these keys and certificates.
* An enrollment token is generated for {kib}, which is valid for 30 minutes.
The password for the `elastic` user and the enrollment token for {kib} are
output to your terminal. For example:

[source,sh]
----
The generated password for the elastic built-in superuser is:
H16Wd=K4dcmgZVA-GE2I
The enrollment token for Kibana instances, valid for the next 30 minutes:
eyJ2ZXIiOiI4LjAuMCIsImFkciI6WyIxOTIuMTY4Ljg2LjEyMjo5MjAwIl0sImZnciI6ImU5MmVhYWM0ZWMzMGExY2EzMDA0MzM4NDgyM2I3Y2YwNTFkMWQ3OTdkNGJlNTQxYzE3ZWY4NGFiMzBjMjlmNGUiLCJrZXkiOiJFM05YNFh3QkVYOVV2SUs0QlU2YTphVEhESktYRVFEbTctUjlFYlBneGlnIn0=
The hex-encoded SHA-256 fingerprint of the generated HTTPS CA DER-encoded certificate:
e92eaac4ec30a1ca30043384823b7cf051d1d797d4be541c17ef84ab30c29f4e
You can complete the following actions at any time:
Reset the password of the elastic built-in superuser with
'bin/elasticsearch-reset-password -u elastic'.
Generate an enrollment token for Kibana instances with
'bin/elasticsearch-create-enrollment-token -s kibana'.
Generate an enrollment token for Elasticsearch nodes with
'bin/elasticsearch-create-enrollment-token -s node'.
----

If you have password-protected the {es} keystore, you will be prompted
to enter the keystore's password. See <<secure-settings>> for more
details.

By default {es} prints its logs to the console (`stdout`) and to the `<cluster
name>.log` file within the <<path-settings,logs directory>>. {es} logs some
information while it is starting up, but once it has finished initializing it
information while it is starting, but after it has finished initializing it
will continue to run in the foreground and won't log anything further until
something happens that is worth recording. While {es} is running you can
interact with it through its HTTP interface which is on port 9200 by default.
interact with it through its HTTP interface which is on port `9200` by default.

To stop {es}, press `Ctrl-C`.

NOTE: All scripts packaged with Elasticsearch require a version of Bash
NOTE: All scripts packaged with {es} require a version of Bash
that supports arrays and assume that Bash is available at `/bin/bash`.
As such, Bash should be available at this path either directly or via a
symbolic link.

To enroll additional nodes in your cluster, create an enrollment token with the
`elasticsearch-create-enrollment-token` tool. You can then start a node with the `--enrollment-token` parameter so that it
{ref}/configuring-stack-security.html#stack-enroll-nodes[joins an existing cluster].
35 changes: 21 additions & 14 deletions docs/reference/setup/install/targz.asciidoc
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
[[targz]]
=== Install Elasticsearch from archive on Linux or MacOS
=== Install {es} from archive on Linux or MacOS

Elasticsearch is as a `.tar.gz` archive for Linux and MacOS.
{es} is available as a `.tar.gz` archive for Linux and MacOS.

include::license.asciidoc[]

The latest stable version of Elasticsearch can be found on the
link:/downloads/elasticsearch[Download Elasticsearch] page.
The latest stable version of {es} can be found on the
link:/downloads/elasticsearch[Download {es}] page.
Other versions can be found on the
link:/downloads/past-releases[Past Releases page].

NOTE: Elasticsearch includes a bundled version of https://openjdk.java.net[OpenJDK]
NOTE: {es} includes a bundled version of https://openjdk.java.net[OpenJDK]
from the JDK maintainers (GPLv2+CE). To use your own version of Java,
see the <<jvm-version, JVM version requirements>>

Expand All @@ -19,13 +19,13 @@ see the <<jvm-version, JVM version requirements>>

ifeval::["{release-state}"=="unreleased"]

Version {version} of Elasticsearch has not yet been released.
Version {version} of {es} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

The Linux archive for Elasticsearch v{version} can be downloaded and installed as follows:
The Linux archive for {es} v{version} can be downloaded and installed as follows:

["source","sh",subs="attributes"]
--------------------------------------------
Expand All @@ -46,13 +46,13 @@ endif::[]

ifeval::["{release-state}"=="unreleased"]

Version {version} of Elasticsearch has not yet been released.
Version {version} of {es} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

The MacOS archive for Elasticsearch v{version} can be downloaded and installed as follows:
The MacOS archive for {es} v{version} can be downloaded and installed as follows:

["source","sh",subs="attributes"]
--------------------------------------------
Expand Down Expand Up @@ -80,6 +80,8 @@ endif::include-xpack[]
[[targz-running]]
include::targz-start.asciidoc[]

:os-dir: $ES_HOME

include::check-running.asciidoc[]

Log printing to `stdout` can be disabled using the `-q` or `--quiet`
Expand All @@ -89,9 +91,9 @@ option on the command line.
include::targz-daemon.asciidoc[]

[[targz-configuring]]
==== Configuring Elasticsearch on the command line
==== Configure {es} on the command line

Elasticsearch loads its configuration from the `$ES_HOME/config/elasticsearch.yml`
{es} loads its configuration from the `$ES_HOME/config/elasticsearch.yml`
file by default. The format of this config file is explained in
<<settings>>.

Expand All @@ -115,7 +117,7 @@ directories are, by default, contained within `$ES_HOME` -- the directory
created when unpacking the archive.

This is very convenient because you don't have to create any directories to
start using Elasticsearch, and uninstalling Elasticsearch is as easy as
start using {es}, and uninstalling {es} is as easy as
removing the `$ES_HOME` directory. However, it is advisable to change the
default locations of the config directory, the data directory, and the logs
directory so that you do not delete important data later on.
Expand All @@ -125,7 +127,7 @@ directory so that you do not delete important data later on.
|=======================================================================
| Type | Description | Default Location | Setting
| home
| Elasticsearch home directory or `$ES_HOME`
| {es} home directory or `$ES_HOME`
d| Directory created by unpacking the archive
|

Expand All @@ -140,6 +142,11 @@ directory so that you do not delete important data later on.
| $ES_HOME/config
| <<config-files-location,ES_PATH_CONF>>

| conf
| Generated TLS keys and certificates for the transport and HTTP layer.
| $ES_HOME/config/tls_auto_config_<timestamp>
d|

| data
| The location of the data files of each index / shard allocated
on the node.
Expand All @@ -163,5 +170,5 @@ directory so that you do not delete important data later on.

|=======================================================================


include::security-files-reference.asciidoc[]
include::next-steps.asciidoc[]
2 changes: 2 additions & 0 deletions docs/reference/setup/install/windows.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,8 @@ TIP: Typically, any cluster-wide settings (like `cluster.name`) should be
added to the `elasticsearch.yml` config file, while any node-specific settings
such as `node.name` could be specified on the command line.

:os-dir: %ES_HOME%

include::check-running.asciidoc[]

[[msi-installer-windows-service]]
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/setup/install/zip-windows.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,8 @@ TIP: Typically, any cluster-wide settings (like `cluster.name`) should be
added to the `elasticsearch.yml` config file, while any node-specific settings
such as `node.name` could be specified on the command line.

:os-dir: %ES_HOME%

include::check-running.asciidoc[]

[[windows-service]]
Expand Down

0 comments on commit b13df02

Please sign in to comment.