Skip to content

Commit d32eefd

Browse files
jrodewigjrodewig
committed
Reorganize
1 parent 5035b08 commit d32eefd

1 file changed

Lines changed: 79 additions & 36 deletions

File tree

‎docs/reference/setup/install/docker.asciidoc‎

Lines changed: 79 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -395,49 +395,48 @@ uid:gid `1000:0`**. Bind mounted host directories and files must be accessible b
395395
and the data and log directories must be writable by this user.
396396

397397
[[docker-keystore-bind-mount]]
398-
===== Mounting an {es} keystore
398+
===== Create an encrypted {es} keystore
399399

400-
By default, {es} will auto-generate a keystore file for secure settings. This
401-
file is obfuscated but not encrypted. If you want to encrypt your
402-
<<secure-settings,secure settings>> with a password, you must use the
403-
`elasticsearch-keystore` utility to create a password-protected keystore and
404-
bind-mount it to the container as
405-
`/usr/share/elasticsearch/config/elasticsearch.keystore`. In order to provide
406-
the Docker container with the password at startup, set the Docker environment
407-
value `KEYSTORE_PASSWORD` to the value of your password. For example, a `docker run`
408-
command might have the following options:
400+
By default, {es} will auto-generate a keystore file for <<secure-settings,secure
401+
settings>>. This file is obfuscated but not encrypted.
409402

410-
[source, sh]
411-
--------------------------------------------
412-
-v full_path_to/config:/usr/share/elasticsearch/config
413-
-E KEYSTORE_PASSWORD=mypassword
414-
--------------------------------------------
415-
416-
If the keystore is mounted incorrectly, it will induce example Docker errors from attempting to
403+
To encrypt your secure settings with a password and have them persist outside
404+
the container, use a `docker run` command to manually create the keystore
405+
instead. The command must:
417406

418-
- add keystore to running container without full reference
407+
* Bind-mount the `config` directory. The command will create an
408+
`elasticsearch.keystore` file in this directory. To avoid errors, do
409+
not directly bind-mount the `elasticsearch.keystore` file's path.
410+
* Use the `elasticsearch-keystore` tool with the `create` option.
411+
* Provide a keystore password using the `KEYSTORE_PASSWORD` or
412+
`KEYSTORE_PASSWORD_FILE` environment variables. Alternatively, you can use
413+
`elasticsearch-keystore` tool's `-p` option to use a password prompt.
419414

420-
[source,sh]
421-
--------------------------------------------
422-
Exception in thread "main" java.nio.file.FileSystemException: /usr/share/elasticsearch/config/elasticsearch.keystore.tmp -> /usr/share/elasticsearch/config/elasticsearch.keystore: Device or resource busy
423-
--------------------------------------------
424-
425-
- mount direct file rather than parent directory
426-
427-
[source,sh]
428-
--------------------------------------------
429-
Exception in thread "main" org.elasticsearch.bootstrap.BootstrapException: java.io.IOException: Is a directory: SimpleFSIndexInput(path="/usr/share/elasticsearch/config/elasticsearch.keystore")
430-
Likely root cause: java.io.IOException: Is a directory
431-
--------------------------------------------
415+
ifeval::["{release-state}"!="unreleased"]
416+
For example:
432417

433-
Versus a working example keystore mounting with update example would be
418+
[source,sh,subs="attributes"]
419+
----
420+
docker run -it --rm \
421+
-v full_path_to/config:/usr/share/elasticsearch/config \
422+
docker.elastic.co/elasticsearch/elasticsearch:{version} \
423+
bin/elasticsearch-keystore create \
424+
-E KEYSTORE_PASSWORD=mypassword
425+
----
434426

427+
You can also use a `docker run` command to add or update secure settings in the
428+
keystore. You'll receive a prompt to enter setting values.
435429

436-
[source,sh]
437-
--------------------------------------------
438-
docker run -it --rm -v /Users/me/elasticsearch/config:/usr/share/elasticsearch/config docker.elastic.co/elasticsearch/elasticsearch:7.14.0 bin/elasticsearch-keystore create
439-
docker run -it --rm -v /Users/me/elasticsearch/config:/usr/share/elasticsearch/config docker.elastic.co/elasticsearch/elasticsearch:7.14.0 bin/elasticsearch-keystore add test_keystore_setting
440-
--------------------------------------------
430+
[source,sh,subs="attributes"]
431+
----
432+
docker run -it --rm \
433+
-v full_path_to/config:/usr/share/elasticsearch/config \
434+
docker.elastic.co/elasticsearch/elasticsearch:{version} \
435+
bin/elasticsearch-keystore \
436+
add my.secure.setting \
437+
my.other.secure.setting \
438+
----
439+
endif::[]
441440

442441
[[_c_customized_image]]
443442
===== Using custom Docker images
@@ -486,4 +485,48 @@ You should use `centos:8` as a base in order to avoid incompatibilities.
486485
Use http://man7.org/linux/man-pages/man1/ldd.1.html[`ldd`] to list the
487486
shared libraries required by a utility.
488487

488+
[[troubleshoot-docker-errors]]
489+
==== Troubleshoot Docker errors for {es}
490+
491+
Here’s how to resolve common errors when running {es} with Docker.
492+
493+
===== elasticsearch.keystore is a directory
494+
495+
[source,txt]
496+
----
497+
Exception in thread "main" org.elasticsearch.bootstrap.BootstrapException: java.io.IOException: Is a directory: SimpleFSIndexInput(path="/usr/share/elasticsearch/config/elasticsearch.keystore") Likely root cause: java.io.IOException: Is a directory
498+
----
499+
500+
A <<docker-keystore-bind-mount,keystore-related>> `docker run` command attempted
501+
to directly bind-mount an `elasticsearch.keystore` file that doesn't exist. If
502+
you use the `-v` or `--volume` flag to mount a file that doesn't exist, Docker
503+
instead creates a directory with the same name.
504+
505+
To resolve this error:
506+
507+
. Delete the `elasticsearch.keystore` directory in the `config` directory.
508+
. Update the `-v` or `--volume` flag to point to the `config` directory path
509+
rather than the keystore file's path. For an example, see
510+
<<<<docker-keystore-bind-mount>>.
511+
. Retry the command.
512+
513+
===== elasticsearch.keystore: Device or resource busy
514+
515+
[source,txt]
516+
----
517+
Exception in thread "main" java.nio.file.FileSystemException: /usr/share/elasticsearch/config/elasticsearch.keystore.tmp -> /usr/share/elasticsearch/config/elasticsearch.keystore: Device or resource busy
518+
----
519+
520+
A <<docker-keystore-bind-mount,keystore-related>> `docker run` command attempted
521+
to directly bind-mount the `elasticsearch.keystore` file. To update the
522+
keystore, the container requires access to other files in the `config`
523+
directory, such as `keystore.tmp`.
524+
525+
To resolve this error:
526+
527+
. Update the `-v` or `--volume` flag to point to the `config` directory
528+
path rather than the keystore file's path. For an example, see
529+
<<<<docker-keystore-bind-mount>>.
530+
. Retry the command.
531+
489532
include::next-steps.asciidoc[]

0 commit comments

Comments
 (0)