Skip to content
Merged
Show file tree
Hide file tree
Changes from 18 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions deploy-manage/deploy/_snippets/installation-order.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
If you're deploying the {{stack}} in a self-managed cluster, then install the {{stack}} products you want to use in the following order:

* {{es}}
* {{kib}}
* [{{es}}](/deploy-manage/deploy/self-managed/installing-elasticsearch.md)
* [{{kib}}](/deploy-manage/deploy/self-managed/install-kibana.md)
* [Logstash](logstash://reference/index.md)
* [{{agent}}](/reference/fleet/index.md) or [Beats](beats://reference/index.md)
* [APM](/solutions/observability/apps/application-performance-monitoring-apm.md)
* [Elasticsearch Hadoop](elasticsearch-hadoop://reference/index.md)

Installing in this order ensures that the components each product depends on are in place.
Installing in this order ensures that the components each product depends on are in place.

:::{tip}
If you're deploying a production environment and you plan to use [trusted CA-signed certificates](/deploy-manage/security/self-setup.md#manual-configuration) for {{es}}, then you should do so before you deploy {{fleet}} and {{agent}}. If new security certificates are configured, any {{agent}}s need to be reinstalled, so we recommend that you set up {{fleet}} and {{agent}} with the appropriate certificates in place.
:::
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
When you start {{es}} for the first time, it automatically performs the following security setup:

* Generates [TLS certificates](#stack-security-certificates) for the [transport and HTTP layers](/deploy-manage/security/secure-cluster-communications.md#communication-channels)
* Applies TLS configuration settings to `elasticsearch.yml`
* Creates an enrollment token to securely connect {{kib}} to {{es}}

You can then start {{kib}} and enter the enrollment token, which is valid for 30 minutes. This token automatically applies the security settings from your {{es}} cluster, authenticates to {{es}} with the built-in `kibana` service account, and writes the security configuration to `kibana.yml`.

::::{note}
There are [some cases](/deploy-manage/security/self-auto-setup.md#stack-skip-auto-configuration) where security can’t be configured automatically because the node startup process detects that the node is already part of a cluster, or that security is already configured or explicitly disabled.
::::
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ curl --cacert {{es-conf}}{{slash}}certs{{slash}}http_ca.crt {{escape}} <1>
-u elastic:$ELASTIC_PASSWORD https://localhost:9200 <2>
```
1. `--cacert`: Path to the generated `http_ca.crt` certificate for the HTTP layer.
2. Ensure that you use `https` in your call, or the request will fail.
2. Replace `$ELASTIC_PASSWORD` with the `elastic` superuser password. Ensure that you use `https` in your call, or the request will fail.



Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Perform the following steps on each node in the cluster:

1. Open `elasticsearch.yml` in a text editor.
2. Comment out or remove the `cluster.initial_master_nodes` setting.
3. Update the `discovery.seed_hosts` value so it contains the IP address and port of each of the master-eligible {{es}} nodes in the cluster.

If you don't perform these steps, then one or more nodes will fail the [discovery configuration bootstrap check](/deploy-manage/deploy/self-managed/bootstrap-checks.md#bootstrap-checks-discovery-configuration) when they are restarted.

For more information, refer to [](/deploy-manage/distributed-architecture/discovery-cluster-formation.md).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to `localhost`. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration.

Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically.

Only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need make your instance reachable.

For more information about the cluster formation process, refer to [](/deploy-manage/distributed-architecture/discovery-cluster-formation.md).
21 changes: 13 additions & 8 deletions deploy-manage/deploy/self-managed/_snippets/enroll-nodes.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,25 @@
When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to localhost. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration.
To enroll new nodes in your cluster, create an enrollment token with the [`elasticsearch-create-enrollment-token`](elasticsearch://reference/elasticsearch/command-line-tools/create-enrollment-token.md) tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster.

Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically.
1. Using a text editor, update the `cluster.name` in `elasticsearch.yml` to match the other nodes in your cluster.

:::{tip}
If this value isn't updated and you attempt to join an existing cluster, then the connection will fail with the following error:

Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set `transport.host` to a [supported value](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#network-interface-values) (such as uncommenting the suggested value of `0.0.0.0`), or an IP address that’s bound to an interface where other hosts can reach it. Refer to [transport settings](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#transport-settings) for more information.
```
handshake failed: remote cluster name [cluster-to-join] does not match local cluster name [current-cluster-name]
```

To enroll new nodes in your cluster, create an enrollment token with the `elasticsearch-create-enrollment-token` tool on any existing node in your cluster. You can then start a new node with the `--enrollment-token` parameter so that it joins an existing cluster.

1. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the [`elasticsearch-create-enrollment-token`](elasticsearch://reference/elasticsearch/command-line-tools/create-enrollment-token.md) tool to generate an enrollment token for your new nodes.
2. In a separate terminal from where {{es}} is running, navigate to the directory where you installed {{es}} and run the `elasticsearch-create-enrollment-token` tool to generate an enrollment token for your new nodes.

```sh subs=true
bin{{slash}}elasticsearch-create-enrollment-token -s node
```

Copy the enrollment token, which you’ll use to enroll new nodes with your {{es}} cluster.

2. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter.
An enrollment token has a lifespan of 30 minutes. You should create a new enrollment token for each new node that you add.

3. From the installation directory of your new node, start {{es}} and pass the enrollment token with the `--enrollment-token` parameter.

```sh subs=true
bin{{slash}}elasticsearch --enrollment-token <enrollment-token>
Expand All @@ -26,6 +31,6 @@ To enroll new nodes in your cluster, create an enrollment token with the `elasti
config{{slash}}certs
```

3. Repeat the previous step for any new nodes that you want to enroll.
You can repeat these steps for each additional {{es}} node that you would like to add to the cluster.

For more information about discovery and shard allocation, refer to [Discovery and cluster formation](/deploy-manage/distributed-architecture/discovery-cluster-formation.md) and [Cluster-level shard allocation and routing settings](elasticsearch://reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings.md).
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
1. Run the `status` command to get details about the {{{kib}}} service.
1. Run the `status` command to get details about the {{kib}} service.

```sh
sudo systemctl status kibana
Expand Down
33 changes: 33 additions & 0 deletions deploy-manage/deploy/self-managed/_snippets/first-node.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
Update the {{es}} configuration on this first node so that other hosts are able to connect to it by editing the settings in [`elasticsearch.yml`](/deploy-manage/deploy/self-managed/configure-elasticsearch.md):

1. Open `elasticsearch.yml` in a text editor.

2. In a multi-node {{es}} cluster, all of the {{es}} instances need to have the same name.

In the configuration file, uncomment the line `#cluster.name: my-application` and give the {{es}} instance any name that you’d like:

```yaml
cluster.name: elasticsearch-demo
```

3. By default, {{es}} runs on `localhost`. For {{es}} instances on other nodes to be able to join the cluster, you need to set up {{es}} to run on a routable, external IP address.

Uncomment the line `#network.host: 192.168.0.1` and replace the default address with `0.0.0.0`. The `0.0.0.0` setting enables {{es}} to listen for connections on all available network interfaces. In a production environment, you might want to [use a different value](elasticsearch:///reference/elasticsearch/configuration-reference/networking-settings.md#common-network-settings).

```yaml
network.host: 0.0.0.0
```

4. {{es}} needs to be enabled to listen for connections from other, external hosts.

Uncomment the line `#transport.host: 0.0.0.0`. The `0.0.0.0` setting enables {{es}} to listen for connections on all available network interfaces. In a production environment you might want to restrict this by setting this value to match the value set for `network.host`.

```yaml
transport.host: 0.0.0.0
```

::::{tip}
You can find details about the `network.host` and `transport.host` settings in the {{es}} [networking settings reference](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md).
::::

5. Save your changes and close the editor.
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
% RPM and Debian only

When you install {{es}}, the installation process configures a single-node cluster by default. If you want a node to join an existing cluster instead, generate an enrollment token on an existing node *before* you start the new node for the first time.

1. On any node in your existing cluster, generate a node enrollment token:
Expand All @@ -6,13 +8,37 @@ When you install {{es}}, the installation process configures a single-node clust
/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node
```

An enrollment token has a lifespan of 30 minutes. You should create a new enrollment token for each new node that you add.

2. Copy the enrollment token, which is output to your terminal.
3. On your new {{es}} node, pass the enrollment token as a parameter to the `elasticsearch-reconfigure-node` tool:
3. On your new {{es}} node, pass the enrollment token as a parameter to the [`elasticsearch-reconfigure-node`](elasticsearch://reference/elasticsearch/command-line-tools/reconfigure-node.md) tool:

```sh
/usr/share/elasticsearch/bin/elasticsearch-reconfigure-node --enrollment-token <enrollment-token>
```

{{es}} is now configured to join the existing cluster.
Answer the `Do you want to continue` prompt with `yes` (`y`). The new {{es}} node will be reconfigured.

4. In a terminal, run `ifconfig` and copy the value for the host inet IP address. You’ll need this value later.
5. Open the new Elasticsearch instance's `elasticsearch.yml` file in a text editor.

The `elasticsearch-reconfigure-node` tool has updated several settings. For example:

* The `transport.host: 0.0.0.0` setting is already uncommented.
* The `discovery_seed.hosts` setting has the IP address and port of the other {{es}} nodes added the cluster so far. As you add each new {{es}} node to the cluster, the `discovery_seed.hosts` setting will contain an array of the IP addresses and port numbers to connect to each {{es}} node that was previously added to the cluster.

6. In the configuration file, uncomment the line `#cluster.name: my-application` and set it to match the name you specified for the first {{es}} node:

```yml
cluster.name: elasticsearch-demo
```

7. As with the first {{es}} node, you’ll need to set up {{es}} to run on a routable, external IP address. Uncomment the line `#network.host: 92.168.0.1` and replace the default address with the value that you copied. For example:

```yml
network.host: 10.128.0.132
```

8. Save your changes and close the editor.

4. [Start your new node using `systemd`](#running-systemd).
You can repeat these steps for each additional {{es}} node that you would like to add to the cluster.
12 changes: 12 additions & 0 deletions deploy-manage/deploy/self-managed/_snippets/kibana-ip.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
The default host and port settings configure Kibana to run on localhost:5601. To change this behavior and allow remote users to connect, you need to set up {{kib}} to run on a routable, external IP address. You can do this by editing the settings in [`kibana.yml`](/deploy-manage/deploy/self-managed/configure-kibana.md):

1. Retrieve the external IP address of your host. You’ll need this value later.
2. Open `kibana.yml` in a text editor.

3. Uncomment the line `#server.host: localhost` and replace the default address with the value that you retrieved in step one. For example:

```yaml
server.host: 10.128.0.28
```
4. Save your changes and close the editor.
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
% RPM and Debian only

When {{es}} starts for the first time, the security auto-configuration process binds the HTTP layer to `0.0.0.0`, but only binds the transport layer to `localhost`. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration.

Before enrolling a new node, additional actions such as binding to an address other than `localhost` or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically.

Only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need make your instance reachable.

* If you're installing the first node in a multi-node cluster across multiple hosts, then you need to [configure the node so that other hosts are able to connect to it](#first-node).

* If you're installing additional nodes for a cluster, then you need to [generate an enrollment token and then reconfigure the new node to join an existing cluster](#existing-cluster).

If you're running a single-node cluster, then skip to the next step.

For more information about the cluster formation process, refer to [](/deploy-manage/distributed-architecture/discovery-cluster-formation.md).
11 changes: 11 additions & 0 deletions deploy-manage/deploy/self-managed/_snippets/ports.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
This table shows the ports that must be accessible in order to operate an {{es}} cluster. The {{es}} REST and {{kib}} interfaces must be open to external users in order for the cluster to be usable. The transport API must be accessible between {{es}} nodes in the cluster, and to any external clients using the transport API.

These settings can be overridden in the relevant configuration file.

| Port | Access type | Purpose | Setting |
| --- | --- | --- | --- |
| 9200-9300 | HTTP (REST) | REST API for Elasticsearch. This is the primary interface used for access to the cluster from external sources, including {{kib}} and {{ls}}. | Elasticsearch [`http.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#common-network-settings) |
| 9300-9400 | TCP | Transport API. Used for intra-cluster communications and client access via the transport API (Java client). | Elasticsearch [`transport.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#common-network-settings) |
| 5601 | HTTP | {{kib}} default access port. | Kibana [`server.port`](kibana://reference/configuration-reference/general-settings.md#server-port) |

Additional ports might be required for [optional {{stack}} components](/get-started/the-stack.md). Refer to the installation guide for the component that you want to install.
4 changes: 3 additions & 1 deletion deploy-manage/deploy/self-managed/_snippets/prereqs.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
Before you install {{es}}, do the following:

* Review the [supported operating systems](https://www.elastic.co/support/matrix). {{es}} is tested on the listed platforms, but it is possible that it will work on other platforms too.
* Review the [supported operating systems](https://www.elastic.co/support/matrix) and prepare virtual or physical hosts where you can install {{es}}.

{{es}} is tested on the listed platforms, but it is possible that it will work on other platforms too.
* Configure your operating system using the [](/deploy-manage/deploy/self-managed/important-system-configuration.md) guidelines.
2 changes: 0 additions & 2 deletions deploy-manage/deploy/self-managed/_snippets/pw-env-var.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
The password for the `elastic` user and the enrollment token for {{kib}} are output to your terminal.

We recommend storing the `elastic` password as an environment variable in your shell. For example:

```sh subs=true
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Because {{es}} runs with `systemd` and not in a terminal, the `elastic` superuser password is not output when {{es}} starts for the first time. Use the [`elasticsearch-reset-password`](elasticsearch://reference/elasticsearch/command-line-tools/reset-password.md) tool tool to set the password for the user:

```shell
bin/elasticsearch-reset-password -u elastic
```
2 changes: 1 addition & 1 deletion deploy-manage/deploy/self-managed/configure-kibana.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Environment variables can be injected into configuration using `${MY_ENV_VAR}` s

## Available settings

For a complete list of settings that you can apply to {{kib}}, refer to [{{kib}} configuration reference](kibana:///reference/configuration-reference.md).
For a complete list of settings that you can apply to {{kib}}, refer to [{{kib}} configuration reference](kibana://reference/configuration-reference.md).

## Additional topics

Expand Down
Loading
Loading