From 898dcfc82ed3cdcd91b8094b7333e9d3af4ff1e4 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS Date: Mon, 23 Jan 2023 13:52:57 -0600 Subject: [PATCH] Add install and configure section Signed-off-by: Naarcha-AWS --- _clients/k8s-operator.md | 2 +- _config.yml | 6 + _dashboards/install/index.md | 12 - _install-and-configure/configuration.md | 100 ++++ .../install-dashboards/debian.md | 129 +++++ .../install-dashboards}/docker.md | 2 + .../install-dashboards}/helm.md | 2 + .../install-dashboards/index.md | 39 ++ .../install-dashboards}/plugins.md | 2 + .../install-dashboards}/rpm.md | 2 + .../install-dashboards}/tar.md | 2 + .../install-dashboards}/tls.md | 2 + .../install-dashboards/windows.md | 54 ++ .../install-opensearch}/ansible.md | 2 + .../install-opensearch/debian.md | 465 ++++++++++++++++++ .../install-opensearch}/docker.md | 19 +- .../install-opensearch}/helm.md | 6 +- .../install-opensearch/index.md | 88 ++++ .../install-opensearch}/rpm.md | 9 +- .../install-opensearch}/tar.md | 14 +- .../install-opensearch/windows.md | 249 ++++++++++ .../plugins.md | 40 +- _opensearch/install/compatibility.md | 28 -- _opensearch/install/important-settings.md | 57 --- _opensearch/install/index.md | 15 - _opensearch/query-dsl/full-text.md | 4 +- _opensearch/supported-field-types/range.md | 2 +- index.md | 2 - 28 files changed, 1196 insertions(+), 158 deletions(-) delete mode 100644 _dashboards/install/index.md create mode 100755 _install-and-configure/configuration.md create mode 100644 _install-and-configure/install-dashboards/debian.md rename {_dashboards/install => _install-and-configure/install-dashboards}/docker.md (96%) rename {_dashboards/install => _install-and-configure/install-dashboards}/helm.md (99%) create mode 100644 _install-and-configure/install-dashboards/index.md rename {_dashboards/install => _install-and-configure/install-dashboards}/plugins.md (99%) rename {_dashboards/install => _install-and-configure/install-dashboards}/rpm.md (98%) rename {_dashboards/install => _install-and-configure/install-dashboards}/tar.md (94%) rename {_dashboards/install => _install-and-configure/install-dashboards}/tls.md (98%) create mode 100644 _install-and-configure/install-dashboards/windows.md rename {_opensearch/install => _install-and-configure/install-opensearch}/ansible.md (98%) create mode 100644 _install-and-configure/install-opensearch/debian.md rename {_opensearch/install => _install-and-configure/install-opensearch}/docker.md (96%) rename {_opensearch/install => _install-and-configure/install-opensearch}/helm.md (98%) create mode 100644 _install-and-configure/install-opensearch/index.md rename {_opensearch/install => _install-and-configure/install-opensearch}/rpm.md (98%) rename {_opensearch/install => _install-and-configure/install-opensearch}/tar.md (97%) create mode 100644 _install-and-configure/install-opensearch/windows.md rename {_opensearch/install => _install-and-configure}/plugins.md (91%) delete mode 100644 _opensearch/install/compatibility.md delete mode 100644 _opensearch/install/important-settings.md delete mode 100644 _opensearch/install/index.md diff --git a/_clients/k8s-operator.md b/_clients/k8s-operator.md index 51b99f8103..9a0cfd4005 100644 --- a/_clients/k8s-operator.md +++ b/_clients/k8s-operator.md @@ -11,7 +11,7 @@ The OpenSearch Kubernetes Operator is an open-source kubernetes operator that he There are two ways to get started with the operator: -- [Use a Helm chart](#use-a-helm-chartuse-a-helm). +- [Use a Helm chart](#use-a-helm-chart). - [Use a local installation](#use-a-local-installation). ### Use a Helm chart diff --git a/_config.yml b/_config.yml index 1bdb16c9df..fe70718a6a 100644 --- a/_config.yml +++ b/_config.yml @@ -28,6 +28,9 @@ color_scheme: opensearch # Define Jekyll collections collections: # Define a collection named "tests", its documents reside in the "_tests" directory + install-and-configure: + permalink: /:collection/:path/ + output: true upgrade-to: permalink: /:collection/:path/ output: true @@ -80,6 +83,9 @@ collections: just_the_docs: # Define the collections used in the theme collections: + install-and-configure: + name: Install and configure + nav_fold: true upgrade-to: name: Upgrade to OpenSearch # nav_exclude: true diff --git a/_dashboards/install/index.md b/_dashboards/install/index.md deleted file mode 100644 index 244ae18643..0000000000 --- a/_dashboards/install/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: default -title: Install OpenSearch Dashboards -nav_order: 2 -has_children: true -redirect_from: - - /dashboards/install/ ---- - -# Install and configure OpenSearch Dashboards - -OpenSearch Dashboards has three installation options at this time: Docker images, tarballs, and Helm charts. diff --git a/_install-and-configure/configuration.md b/_install-and-configure/configuration.md new file mode 100755 index 0000000000..3293d9038e --- /dev/null +++ b/_install-and-configure/configuration.md @@ -0,0 +1,100 @@ +--- +layout: default +title: Configuring OpenSearch +nav_order: 10 +--- + +# Configuring OpenSearch + +Most OpenSearch configuration can take place in the cluster settings API. Certain operations require you to modify `opensearch.yml` and restart the cluster. + +Whenever possible, use the cluster settings API instead; `opensearch.yml` is local to each node, whereas the API applies the setting to all nodes in the cluster. Certain settings, however, require `opensearch.yml`. In general, these settings relate to networking, cluster formation, and the local file system. To learn more, see [Cluster formation]({{site.url}}{{site.baseurl}}/opensearch/cluster/). + +## Specify settings as environment variables + +You can specify environment variables as arguments using `-E` when launching OpenSearch: + +```bash +./opensearch -Ecluster.name=opensearch-cluster -Enode.name=opensearch-node1 -Ehttp.host=0.0.0.0 -Ediscovery.type=single-node +``` + +## Update cluster settings using the API + +The first step in changing a setting is to view the current settings: + +``` +GET _cluster/settings?include_defaults=true +``` + +For a more concise summary of non-default settings: + +``` +GET _cluster/settings +``` + +Three categories of setting exist in the cluster settings API: persistent, transient, and default. Persistent settings, well, persist after a cluster restart. After a restart, OpenSearch clears transient settings. + +If you specify the same setting in multiple places, OpenSearch uses the following precedence: + +1. Transient settings +2. Persistent settings +3. Settings from `opensearch.yml` +4. Default settings + +To change a setting, just specify the new one as either persistent or transient. This example shows the flat settings form: + +```json +PUT _cluster/settings +{ + "persistent" : { + "action.auto_create_index" : false + } +} +``` + +You can also use the expanded form, which lets you copy and paste from the GET response and change existing values: + +```json +PUT _cluster/settings +{ + "persistent": { + "action": { + "auto_create_index": false + } + } +} +``` + +For more information about the Cluster Settings API, see [Cluster settings]({{site.url}}{{site.baseurl}}/api-reference/cluster-settings/). + + +--- + +## Configuration file + +You can find `opensearch.yml` in `/usr/share/opensearch/config/opensearch.yml` (Docker) or `/etc/opensearch/opensearch.yml` (most Linux distributions) on each node. + +You can edit the `OPENSEARCH_PATH_CONF=/etc/opensearch` to change the config directory location. This variable is sourced from `/etc/default/opensearch`(Debian package) and `/etc/sysconfig/opensearch`(RPM package). + +If you set your customized `OPENSEARCH_PATH_CONF` variable, be aware that other default environment variables will not be loaded. + +You don't mark settings in `opensearch.yml` as persistent or transient, and settings use the flat form: + +```yml +cluster.name: my-application +action.auto_create_index: true +compatibility.override_main_response_version: true +``` + +The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/). + +### (Optional) CORS header configuration +If you are working on a client application running against an OpenSearch cluster on a different domain, you can configure headers in `opensearch.yml` to allow for developing a local application on the same machine. Use [Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) so your application can make calls to the OpenSearch API running locally. Add the following lines in your `custom-opensearch.yml` file (note that the "-" must be the first character in each line). +```yml +- http.host:0.0.0.0 +- http.port:9200 +- http.cors.allow-origin:"http://localhost" +- http.cors.enabled:true +- http.cors.allow-headers:X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization +- http.cors.allow-credentials:true +``` \ No newline at end of file diff --git a/_install-and-configure/install-dashboards/debian.md b/_install-and-configure/install-dashboards/debian.md new file mode 100644 index 0000000000..8570f1e8d8 --- /dev/null +++ b/_install-and-configure/install-dashboards/debian.md @@ -0,0 +1,129 @@ +--- +layout: default +title: Debian +parent: Install OpenSearch Dashboards +nav_order: 33 +--- + +# Installing OpenSearch Dashboards (Debian) + +Installing OpenSearch Dashboards using the Advanced Packaging Tool (APT) package manager simplifies the process considerably compared to the [Tarball]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/tar/) method. For example, the package manager handles several technical considerations, such as the installation path, location of configuration files, and creation of a service managed by `systemd`. + +Before installing OpenSearch Dashboards you must configure an OpenSearch cluster. Refer to the OpenSearch [Debian]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/debian/) installation guide for steps. +{: .important} + +This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. Some example commands reference the `vi` text editor, but you may use any text editor available. +{:.note} + +## Installing OpenSearch Dashboards from a package + +1. Download the Debian package for the desired version directly from the [OpenSearch downloads page](https://opensearch.org/downloads.html){:target='\_blank'}. The Debian package can be downloaded for both **x64** and **arm64** architectures. +1. From the CLI, install using `dpkg`. + ```bash + # x64 + sudo dpkg -i opensearch-dashboards-{{site.opensearch_version}}-linux-x64.deb + # arm64 + sudo dpkg -i opensearch-dashboards-{{site.opensearch_version}}-linux-arm64.deb + ``` +1. After the installation completes, reload the systemd manager configuration. + ```bash + sudo systemctl daemon-reload + ``` +1. Enable OpenSearch as a service. + ```bash + sudo systemctl enable opensearch-dashboards + ``` +1. Start the OpenSearch service. + ```bash + sudo systemctl start opensearch-dashboards + ``` +1. Verify that OpenSearch launched correctly. + ```bash + sudo systemctl status opensearch-dashboards + ``` + +### Fingerprint verification + +The Debian package is not signed. If you would like to verify the fingerprint, the OpenSearch Project provides a `.sig` file as well as the `.deb` package for use with GNU Privacy Guard (GPG). + +1. Download the desired Debian package. + ```bash + curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/{{site.opensearch_version}}/opensearch-dashboards-{{site.opensearch_version}}-linux-x64.deb + ``` +1. Download the corresponding signature file. + ```bash + curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/{{site.opensearch_version}}/opensearch-dashboards-{{site.opensearch_version}}-linux-x64.deb.sig + ``` +1. Download and import the GPG key. + ```bash + curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | gpg --import - + ``` +1. Verify the signature. + ```bash + gpg --verify opensearch-dashboards-{{site.opensearch_version}}-linux-x64.deb.sig opensearch-dashboards-{{site.opensearch_version}}-linux-x64.deb + ``` + +## Installing OpenSearch Dashboards from an APT repository + +APT, the primary package management tool for Debian–based operating systems, allows you to download and install the Debian package from the APT repository. + +1. Import the public GPG key. This key is used to verify that the APT repository is signed. + ```bash + curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | sudo apt-key add - + ``` +1. Create an APT repository for OpenSearch. + ```bash + echo "deb https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/2.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/opensearch-dashboards-2.x.list + ``` +1. Verify that the repository was created successfully. + ```bash + sudo apt-get update + ``` +1. With the repository information added, list all available versions of OpenSearch: + ```bash + sudo apt list -a opensearch-dashboards + ``` +1. Choose the version of OpenSearch you want to install: + - Unless otherwise indicated, the latest available version of OpenSearch is installed. + ```bash + sudo apt-get install opensearch-dashboards + ``` + - To install a specific version of OpenSearch Dashboards, pass a version number after the package name. + ```bash + # Specify the version manually using opensearch= + sudo apt-get install opensearch-dashboards={{site.opensearch_version}} + ``` +1. Once complete, enable OpenSearch. + ```bash + sudo systemctl enable opensearch-dashboards + ``` +1. Start OpenSearch. + ```bash + sudo systemctl start opensearch-dashboards + ``` +1. Verify that OpenSearch launched correctly. + ```bash + sudo systemctl status opensearch-dashboards + ``` + +## Exploring OpenSearch Dashboards + +By default, OpenSearch Dashboards, like OpenSearch, binds to `localhost` when you initially install it. As a result, OpenSearch Dashboards is not reachable from a remote host unless the configuration is updated. + +1. Open `opensearch_dashboards.yml`. + ```bash + sudo vi /etc/opensearch-dashboards/opensearch_dashboards.yml + ``` +1. Specify a network interface that OpenSearch Dashboards should bind to. + ```bash + # Use 0.0.0.0 to bind to any available interface. + server.host: 0.0.0.0 + ``` +1. Save and quit. +1. Restart OpenSearch Dashboards to apply the configuration change. + ```bash + sudo systemctl restart opensearch-dashboards + ``` +1. From a web browser, navigate to OpenSearch Dashboards. The default port is 5601. +1. Log in with the default username `admin` and the default password `admin`. +1. Visit [Getting started with OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/index/) to learn more. \ No newline at end of file diff --git a/_dashboards/install/docker.md b/_install-and-configure/install-dashboards/docker.md similarity index 96% rename from _dashboards/install/docker.md rename to _install-and-configure/install-dashboards/docker.md index 560a9cf0f7..9b9637bdc1 100644 --- a/_dashboards/install/docker.md +++ b/_install-and-configure/install-dashboards/docker.md @@ -3,6 +3,8 @@ layout: default title: Docker parent: Install OpenSearch Dashboards nav_order: 1 +redirect_from: + - /dashboards/install/docker/ --- # Run OpenSearch Dashboards using Docker diff --git a/_dashboards/install/helm.md b/_install-and-configure/install-dashboards/helm.md similarity index 99% rename from _dashboards/install/helm.md rename to _install-and-configure/install-dashboards/helm.md index 4d2e0c83f9..488e86802f 100644 --- a/_dashboards/install/helm.md +++ b/_install-and-configure/install-dashboards/helm.md @@ -3,6 +3,8 @@ layout: default title: Helm parent: Install OpenSearch Dashboards nav_order: 35 +redirect_from: + - /dashboards/install/helm/ --- # Run OpenSearch Dashboards using Helm diff --git a/_install-and-configure/install-dashboards/index.md b/_install-and-configure/install-dashboards/index.md new file mode 100644 index 0000000000..c9cb4469a5 --- /dev/null +++ b/_install-and-configure/install-dashboards/index.md @@ -0,0 +1,39 @@ +--- +layout: default +title: Installing OpenSearch Dashboards +nav_order: 3 +has_children: true +redirect_from: + - /dashboards/install/ + - /dashboards/compatibility/ +--- + +# Installing OpenSearch Dashboards + +This section details how to install and configure OpenSearch Dashboards. + +## Installation options + +OpenSearch Dashboards has the following installation options: + +- [Docker]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/docker/) +- [Tarball]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/tar/) +- [RPM]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/rpm/) +- [Debian]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/debian/) +- [Helm]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/helm/) +- [Windows]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/windows/) + +## Browser compatibility + +OpenSearch Dashboards supports the following web browsers: + +- Chrome +- Firefox +- Safari +- Edge (Chromium) + +Other Chromium-based browsers might work, as well. Internet Explorer and Microsoft Edge Legacy are **not** supported. + +## Configuration + +To learn how to configure TLS for OpenSearch Dashboards, see [Configure TLS]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/tls/). diff --git a/_dashboards/install/plugins.md b/_install-and-configure/install-dashboards/plugins.md similarity index 99% rename from _dashboards/install/plugins.md rename to _install-and-configure/install-dashboards/plugins.md index a2fb81af9a..c1352d9c62 100644 --- a/_dashboards/install/plugins.md +++ b/_install-and-configure/install-dashboards/plugins.md @@ -3,6 +3,8 @@ layout: default title: OpenSearch Dashboards plugins parent: Install OpenSearch Dashboards nav_order: 50 +redirect_from: + - /dashboards/install/plugins --- # Standalone plugin install diff --git a/_dashboards/install/rpm.md b/_install-and-configure/install-dashboards/rpm.md similarity index 98% rename from _dashboards/install/rpm.md rename to _install-and-configure/install-dashboards/rpm.md index 7ec571b62f..6d4c8b4c92 100644 --- a/_dashboards/install/rpm.md +++ b/_install-and-configure/install-dashboards/rpm.md @@ -3,6 +3,8 @@ layout: default title: RPM parent: Install OpenSearch Dashboards nav_order: 31 +redirect_from: + - /dashboards/install/rpm/ --- {% comment %} diff --git a/_dashboards/install/tar.md b/_install-and-configure/install-dashboards/tar.md similarity index 94% rename from _dashboards/install/tar.md rename to _install-and-configure/install-dashboards/tar.md index 026f23f7e3..606aea1b73 100644 --- a/_dashboards/install/tar.md +++ b/_install-and-configure/install-dashboards/tar.md @@ -3,6 +3,8 @@ layout: default title: Tarball parent: Install OpenSearch Dashboards nav_order: 30 +redirect_from: + - /dashboards/install/tar/ --- # Run OpenSearch Dashboards using the tarball diff --git a/_dashboards/install/tls.md b/_install-and-configure/install-dashboards/tls.md similarity index 98% rename from _dashboards/install/tls.md rename to _install-and-configure/install-dashboards/tls.md index 22f123bce0..785f4f1c04 100644 --- a/_dashboards/install/tls.md +++ b/_install-and-configure/install-dashboards/tls.md @@ -3,6 +3,8 @@ layout: default title: Configure TLS parent: Install OpenSearch Dashboards nav_order: 40 +redirect_from: + - /dashboards/install/tls/ --- # Configure TLS for OpenSearch Dashboards diff --git a/_install-and-configure/install-dashboards/windows.md b/_install-and-configure/install-dashboards/windows.md new file mode 100644 index 0000000000..bea0109e7a --- /dev/null +++ b/_install-and-configure/install-dashboards/windows.md @@ -0,0 +1,54 @@ +--- +layout: default +title: Windows +parent: Install OpenSearch Dashboards +nav_order: 37 +redirect_from: + - /dashboards/install/windows/ +--- + +# Run OpenSearch Dashboards on Windows + +Perform the following steps to install OpenSearch Dashboards on Windows. + +Make sure you have a zip utility installed. +{: .note } + +1. Download the [`opensearch-dashboards-{{site.opensearch_version}}-windows-x64.zip`](https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/{{site.opensearch_version}}/opensearch-dashboards-{{site.opensearch_version}}-windows-x64.zip){:target='\_blank'} archive. + +1. To extract the archive contents, right-click to select **Extract All**. + + **Note**: Some versions of the Windows operating system limit the file path length. If you encounter a path-length-related error when unzipping the archive, perform the following steps to enable long path support: + + 1. Open Powershell by entering `powershell` in the search box next to **Start** on the taskbar. + 1. Run the following command in Powershell: + ```bat + Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled -Type DWORD -Value 1 -Force + ``` + 1. Restart your computer. + +1. Run OpenSearch Dashboards. + + There are two ways of running OpenSearch Dashboards: + + 1. Run the batch script using the Windows UI: + + 1. Navigate to the top directory of your OpenSearch Dashboards installation and open the `opensearch-dashboards-{{site.opensearch_version}}` folder. + 1. If desired, modify `opensearch_dashboards.yml` located in the `config` folder, to change the default OpenSearch Dashboards settings. + 1. Open the `bin` folder and run the batch script by double-clicking the `opensearch-dashboards.bat` file. This opens a command prompt with an OpenSearch Dashboards instance running. + + 1. Run the batch script from Command Prompt or Powershell: + + 1. Open Command Prompt by entering `cmd`, or Powershell by entering `powershell`, in the search box next to **Start** on the taskbar. + 1. Change to the top directory of your OpenSearch Dashboards installation. + ```bat + cd \path\to\opensearch-dashboards-{{site.opensearch_version}} + ``` + 1. If desired, modify `config\opensearch_dashboards.yml`. + 1. Run the batch script to start OpenSearch Dashboards. + ```bat + .\bin\opensearch-dashboards.bat + ``` + +To stop OpenSearch Dashboards, press `Ctrl+C` in Command Prompt or Powershell, or simply close the Command Prompt or Powershell window. +{: .tip} \ No newline at end of file diff --git a/_opensearch/install/ansible.md b/_install-and-configure/install-opensearch/ansible.md similarity index 98% rename from _opensearch/install/ansible.md rename to _install-and-configure/install-opensearch/ansible.md index 47a91a8d56..7806e4e461 100644 --- a/_opensearch/install/ansible.md +++ b/_install-and-configure/install-opensearch/ansible.md @@ -3,6 +3,8 @@ layout: default title: Ansible playbook parent: Install OpenSearch nav_order: 60 +redirect_from: + - /opensearch/install/ansible/ --- # Ansible playbook diff --git a/_install-and-configure/install-opensearch/debian.md b/_install-and-configure/install-opensearch/debian.md new file mode 100644 index 0000000000..d0172bbe6d --- /dev/null +++ b/_install-and-configure/install-opensearch/debian.md @@ -0,0 +1,465 @@ +--- +layout: default +title: Debian +parent: Install OpenSearch +nav_order: 55 +--- + +{% comment %} +The following liquid syntax declares a variable, major_version_mask, which is transformed into "N.x" where "N" is the major version number. This is required for proper versioning references to the Yum repo. +{% endcomment %} +{% assign version_parts = site.opensearch_major_minor_version | split: "." %} +{% assign major_version_mask = version_parts[0] | append: ".x" %} + +# Debian + +Installing OpenSearch using the Advanced Packaging Tool (APT) package manager simplifies the process considerably compared to the [Tarball]({{site.url}}{{site.baseurl}}/opensearch/install/tar/) method. Several technical considerations, such as the installation path, location of configuration files, and creation of a service managed by `systemd`, as examples, are handled automatically by the package manager. + +Generally speaking, installing OpenSearch from the Debian distribution can be broken down into a few steps: + +1. **Download and install OpenSearch.** + - Install manually from a Debian package or from an APT repository. +1. **(Optional) Test OpenSearch.** + - Confirm that OpenSearch is able to run before you apply any custom configuration. + - This can be done without any security (no password, no certificates) or with a demo security configuration that can be applied by a packaged script. +1. **Configure OpenSearch for your environment.** + - Apply basic settings to OpenSearch and start using it in your environment. + +The Debian distribution provides everything you need to run OpenSearch inside Debian-based Linux Distributions, such as Ubuntu. + +This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. Some example commands reference the `vi` text editor, but you may use any text editor available. +{:.note} + +## Step 1: Download and install OpenSearch + +### Install OpenSearch from a package + +1. Download the Debian package for the desired version directly from the [OpenSearch downloads page](https://opensearch.org/downloads.html){:target='\_blank'}. The Debian package can be downloaded for both **x64** and **arm64** architectures. +1. From the CLI, install using `dpkg`. + ```bash + # x64 + sudo dpkg -i opensearch-{{site.opensearch_version}}-linux-x64.deb + # arm64 + sudo dpkg -i opensearch-{{site.opensearch_version}}-linux-arm64.deb + ``` +1. After the installation succeeds, enable OpenSearch as a service. + ```bash + sudo systemctl enable opensearch + ``` +1. Start the OpenSearch service. + ```bash + sudo systemctl start opensearch + ``` +1. Verify that OpenSearch launched correctly. + ```bash + sudo systemctl status opensearch + ``` + +### Fingerprint verification + +The Debian package is not signed. If you would like to verify the fingerprint, the OpenSearch Project provides a `.sig` file as well as the `.deb` package for use with GNU Privacy Guard (GPG). + +1. Download the desired Debian package. + ```bash + curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/{{site.opensearch_version}}/opensearch-{{site.opensearch_version}}-linux-x64.deb + ``` +1. Download the corresponding signature file. + ```bash + curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/{{site.opensearch_version}}/opensearch-{{site.opensearch_version}}-linux-x64.deb.sig + ``` +1. Download and import the GPG key. + ```bash + curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | gpg --import - + ``` +1. Verify the signature. + ```bash + gpg --verify opensearch-{{site.opensearch_version}}-linux-x64.deb.sig opensearch-{{site.opensearch_version}}-linux-x64.deb + ``` + +### Install OpenSearch from an APT repository + +APT, the primary package management tool for Debian–based operating systems, allows you to download and install the Debian package from the APT repository. + +1. Import the public GPG key. This key is used to verify that the APT repository is signed. + ```bash + curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | sudo apt-key add - + ``` +1. Create an APT repository for OpenSearch: + ```bash + echo "deb https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/opensearch-2.x.list + ``` +1. Verify that the repository was created successfully. + ```bash + sudo apt-get update + ``` +1. With the repository information added, list all available versions of OpenSearch: + ```bash + sudo apt list -a opensearch + ``` +1. Choose the version of OpenSearch you want to install: + - Unless otherwise indicated, the latest available version of OpenSearch is installed. + ```bash + sudo apt-get install opensearch + ``` + - To install a specific version of OpenSearch: + ```bash + # Specify the version manually using opensearch= + sudo apt-get install opensearch={{site.opensearch_version}} + ``` +1. During installation, the installer will present you with the GPG key fingerprint. Verify that the information matches the following: + ```bash + Fingerprint: c5b7 4989 65ef d1c2 924b a9d5 39d3 1987 9310 d3fc + ``` +1. Once complete, enable OpenSearch. + ```bash + sudo systemctl enable opensearch + ``` +1. Start OpenSearch. + ```bash + sudo systemctl start opensearch + ``` +1. Verify that OpenSearch launched correctly. + ```bash + sudo systemctl status opensearch + ``` + +## Step 2: (Optional) Test OpenSearch + +Before proceeding with any configuration, you should test your installation of OpenSearch. Otherwise, it can be difficult to determine whether future problems are due to installation issues or custom settings you applied after installation. + +When OpenSearch is installed using the Debian package, some demo security settings are automatically applied. This includes self-signed TLS certificates and several users and roles. If you would like to configure these yourself, see [Set up OpenSearch in your environment](#step-3-set-up-opensearch-in-your-environment). + +An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. +{: .warning} + +1. Send requests to the server to verify that OpenSearch is running. Note the use of the `--insecure` flag, which is required because the TLS certificates are self-signed. + - Send a request to port 9200: + ```bash + curl -X GET https://localhost:9200 -u 'admin:admin' --insecure + ``` + You should get a response that looks like this: + ```bash + { + "name":"hostname", + "cluster_name":"opensearch", + "cluster_uuid":"QqgpHCbnSRKcPAizqjvoOw", + "version":{ + "distribution":"opensearch", + "number":"2.5.0", + "build_type":"deb", + "build_hash":"b8a8b6c4d7fc7a7e32eb2cb68ecad8057a4636ad", + "build_date":"2023-01-18T23:48:43.426713304Z", + "build_snapshot":false, + "lucene_version":"9.4.2", + "minimum_wire_compatibility_version":"7.10.0", + "minimum_index_compatibility_version":"7.0.0" + }, + "tagline":"The OpenSearch Project: https://opensearch.org/" + } + ``` + - Query the plugins endpoint: + ```bash + curl -X GET https://localhost:9200/_cat/plugins?v -u 'admin:admin' --insecure + ``` + + The response should look like this: + ```bash + name component version + hostname opensearch-alerting 2.5.0.0 + hostname opensearch-anomaly-detection 2.5.0.0 + hostname opensearch-asynchronous-search 2.5.0.0 + hostname opensearch-cross-cluster-replication 2.5.0.0 + hostname opensearch-geospatial 2.5.0.0 + hostname opensearch-index-management 2.5.0.0 + hostname opensearch-job-scheduler 2.5.0.0 + hostname opensearch-knn 2.5.0.0 + hostname opensearch-ml 2.5.0.0 + hostname opensearch-neural-search 2.5.0.0 + hostname opensearch-notifications 2.5.0.0 + hostname opensearch-notifications-core 2.5.0.0 + hostname opensearch-observability 2.5.0.0 + hostname opensearch-performance-analyzer 2.5.0.0 + hostname opensearch-reports-scheduler 2.5.0.0 + hostname opensearch-security 2.5.0.0 + hostname opensearch-security-analytics 2.5.0.0 + hostname opensearch-sql 2.5.0.0 + ``` + +## Step 3: Set up OpenSearch in your environment + +Users who do not have prior experience with OpenSearch may want a list of recommended settings in order to get started with the service. By default, OpenSearch is not bound to a network interface and cannot be reached by external hosts. Additionally, security settings are populated by default user names and passwords. The following recommendations will enable a user to bind OpenSearch to a network interface, create and sign TLS certificates, and configure basic authentication. + +The following recommended settings will allow you to: + +- Bind OpenSearch to an IP or network interface on the host. +- Set initial and maximum JVM heap sizes. +- Define an environment variable that points to the bundled JDK. +- Configure your own TLS certificates—no third-party certificate authority (CA) is required. +- Create an admin user with a custom password. + +If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) for guidance before proceeding. +{:.note} + +Before modifying any configuration files, it's always a good idea to save a backup copy before making changes. The backup file can be used to mitigate any issues caused by a bad configuration. +{:.tip} + +1. Open `opensearch.yml`. + ```bash + sudo vi /etc/opensearch/opensearch.yml + ``` +1. Add the following lines: + ```bash + # Bind OpenSearch to the correct network interface. Use 0.0.0.0 + # to include all available interfaces or specify an IP address + # assigned to a specific interface. + network.host: 0.0.0.0 + + # Unless you have already configured a cluster, you should set + # discovery.type to single-node, or the bootstrap checks will + # fail when you try to start the service. + discovery.type: single-node + + # If you previously disabled the security plugin in opensearch.yml, + # be sure to re-enable it. Otherwise you can skip this setting. + plugins.security.disabled: false + ``` +1. Save your changes and close the file. +1. Specify initial and maximum JVM heap sizes. + 1. Open `jvm.options`. + ```bash + vi /etc/opensearch/jvm.options + ``` + 1. Modify the values for initial and maximum heap sizes. As a starting point, you should set these values to half of the available system memory. For dedicated hosts this value can be increased based on your workflow requirements. + - As an example, if the host machine has 8 GB of memory, then you might want to set the initial and maximum heap sizes to 4 GB: + ```bash + -Xms4g + -Xmx4g + ``` + 1. Save your changes and close the file. + +### Configure TLS + +TLS certificates provide additional security for your cluster by allowing clients to confirm the identity of hosts and encrypt traffic between the client and host. For more information, refer to [Configure TLS Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/) and [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/), which are included in the [Security Plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) documentation. For work performed in a development environment, self-signed certificates are usually adequate. This section will guide you through the basic steps required to generate your own TLS certificates and apply them to your OpenSearch host. + +1. Navigate to the directory where the certificates will be stored. + ```bash + cd /etc/opensearch + ``` +1. Delete the demo certificates. + ```bash + sudo rm -f *pem + ``` +1. Generate a root certificate. This is what you will use to sign your other certificates. + ```bash + # Create a private key for the root certificate + sudo openssl genrsa -out root-ca-key.pem 2048 + + # Use the private key to create a self-signed root certificate. Be sure to + # replace the arguments passed to -subj so they reflect your specific host. + sudo openssl req -new -x509 -sha256 -key root-ca-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=ROOT" -out root-ca.pem -days 730 + ``` +1. Next, create the admin certificate. This certificate is used to gain elevated rights for performing administrative tasks relating to the security plugin. + ```bash + # Create a private key for the admin certificate. + sudo openssl genrsa -out admin-key-temp.pem 2048 + + # Convert the private key to PKCS#8. + sudo openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem + + # Create the certficiate signing request (CSR). A common name (CN) of "A" is acceptable because this certificate is + # used for authenticating elevated access and is not tied to a host. + sudo openssl req -new -key admin-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=A" -out admin.csr + + # Sign the admin certificate with the root certificate and private key you created earlier. + sudo openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730 + ``` +1. Create a certificate for the node being configured. + ```bash + # Create a private key for the node certificate. + sudo openssl genrsa -out node1-key-temp.pem 2048 + + # Convert the private key to PKCS#8. + sudo openssl pkcs8 -inform PEM -outform PEM -in node1-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out node1-key.pem + + # Create the CSR and replace the arguments passed to -subj so they reflect your specific host. + # The CN should match a DNS A record for the host-do not use the hostname. + sudo openssl req -new -key node1-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=node1.dns.a-record" -out node1.csr + + # Create an extension file that defines a SAN DNS name for the host. This + # should match the DNS A record of the host. + sudo sh -c 'echo subjectAltName=DNS:node1.dns.a-record > node1.ext' + + # Sign the node certificate with the root certificate and private key that you created earlier. + sudo openssl x509 -req -in node1.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out node1.pem -days 730 -extfile node1.ext + ``` +1. Remove temporary files that are no longer required. + ```bash + sudo rm -f *temp.pem *csr *ext + ``` +1. Make sure the remaining certificates are owned by the opensearch user. + ```bash + sudo chown opensearch:opensearch admin-key.pem admin.pem node1-key.pem node1.pem root-ca-key.pem root-ca.pem root-ca.srl + ``` +1. Add these certificates to `opensearch.yml` as described in [Generate Certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml). Advanced users might also choose to append the settings using a script: + ```bash + #! /bin/bash + + # Before running this script, make sure to replace the CN in the + # node's distinguished name with a real DNS A record. + + echo "plugins.security.ssl.transport.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.transport.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.transport.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.http.enabled: true" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.http.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.http.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.ssl.http.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.allow_default_init_securityindex: true" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.authcz.admin_dn:" | sudo tee -a /etc/opensearch/opensearch.yml + echo " - 'CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.nodes_dn:" | sudo tee -a /etc/opensearch/opensearch.yml + echo " - 'CN=node1.dns.a-record,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.audit.type: internal_opensearch" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.enable_snapshot_restore_privilege: true" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.check_snapshot_restore_write_privileges: true" | sudo tee -a /etc/opensearch/opensearch.yml + echo "plugins.security.restapi.roles_enabled: [\"all_access\", \"security_rest_api_access\"]" | sudo tee -a /etc/opensearch/opensearch.yml + ``` +1. (Optional) Add trust for the self-signed root certificate. + ```bash + # Copy the root certificate to the correct directory + sudo cp /etc/opensearch/root-ca.pem /etc/pki/ca-trust/source/anchors/ + + # Add trust + sudo update-ca-trust + ``` + +### Configure a user + +Users are defined and authenticated by OpenSearch in a variety of ways. One method that does not require additional backend infrastructure is to manually configure users in `internal_users.yml`. See [YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/) for more information about configuring users. The following steps explain how to remove all demo users except for the `admin` user and how to replace the `admin` default password using a script. + +1. Navigate to the security plugins tools directory. + ```bash + cd /usr/share/opensearch/plugins/opensearch-security/tools + ``` +1. Run `hash.sh` to generate a new password. + - This script will fail if a path to the JDK has not been defined. + ```bash + # Example output if a JDK isn't found... + $ ./hash.sh + ************************************************************************** + ** This tool will be deprecated in the next major release of OpenSearch ** + ** https://github.com/opensearch-project/security/issues/1755 ** + ************************************************************************** + which: no java in (/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/home/user/.local/bin:/home/user/bin) + WARNING: nor OPENSEARCH_JAVA_HOME nor JAVA_HOME is set, will use + ./hash.sh: line 35: java: command not found + ``` + - Declare an environment variable when you invoke the script in order to avoid issues: + ```bash + OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./hash.sh + ``` + - Enter the desired password at the prompt and make a note of the output hash. +1. Open `internal_users.yml`. + ```bash + sudo vi /etc/opensearch/opensearch-security/internal_users.yml + ``` +1. Remove all demo users except for `admin` and replace the hash with the output provided by `hash.sh` in a previous step. The file should look similar to the following example: + ```bash + --- + # This is the internal user database + # The hash value is a bcrypt hash and can be generated with plugin/tools/hash.sh + + _meta: + type: "internalusers" + config_version: 2 + + # Define your internal users here + + admin: + hash: "$2y$1EXAMPLEQqwS8TUcoEXAMPLEeZ3lEHvkEXAMPLERqjyh1icEXAMPLE." + reserved: true + backend_roles: + - "admin" + description: "Admin user" + ``` + +### Apply changes + +Now that TLS certificates are installed and demo users were removed or assigned new passwords, the last step is to apply the configuration changes. This last configuration step requires invoking `securityadmin.sh` while OpenSearch is running on the host. + +1. OpenSearch must be running for `securityadmin.sh` to apply changes. If you made changes to `opensearch.yml`, restart OpenSearch. + ```bash + sudo systemctl restart opensearch + ``` +1. Open a separate terminal session with the host and navigate to the directory containing `securityadmin.sh`. + ```bash + # Change to the correct directory + cd /usr/share/opensearch/plugins/opensearch-security/tools + ``` +1. Invoke the script. See [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) for definitions of the arguments you must pass. + ```bash + # You can omit the environment variable if you declared this in your $PATH. + OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./securityadmin.sh -cd /etc/opensearch/opensearch-security/ -cacert /etc/opensearch/root-ca.pem -cert /etc/opensearch/admin.pem -key /etc/opensearch/admin-key.pem -icl -nhnv + ``` + +### Verify that the service is running + +OpenSearch is now running on your host with custom TLS certificates and a secure user for basic authentication. You can verify external connectivity by sending an API request to your OpenSearch node from another host. + +During the previous test you directed requests to `localhost`. Now that TLS certificates have been applied and the new certificates reference your host's actual DNS record, requests to `localhost` will fail the CN check and the certificate will be considered invalid. Instead, requests should be sent to the address you specified while generating the certificate. + +You should add trust for the root certificate to your client before sending requests. If you do not add trust, then you must use the `-k` option so that cURL ignores CN and root certificate validation. +{:.tip} + +```bash +$ curl https://your.host.address:9200 -u admin:yournewpassword -k +{ + "name":"hostname", + "cluster_name":"opensearch", + "cluster_uuid":"QqgpHCbnSRKcPAizqjvoOw", + "version":{ + "distribution":"opensearch", + "number":"2.5.0", + "build_type":"deb", + "build_hash":"b8a8b6c4d7fc7a7e32eb2cb68ecad8057a4636ad", + "build_date":"2023-01-18T23:48:43.426713304Z", + "build_snapshot":false, + "lucene_version":"9.4.2", + "minimum_wire_compatibility_version":"7.10.0", + "minimum_index_compatibility_version":"7.0.0" + }, + "tagline":"The OpenSearch Project: https://opensearch.org/" +} +``` + +## Upgrade to a newer version + +OpenSearch instances installed using `dpkg` or `apt-get` can be easily upgraded to a newer version. + +### Manual upgrade with DPKG + +Download the Debian package for the desired upgrade version directly from the [OpenSearch downloads page](https://opensearch.org/downloads.html){:target='\_blank'}. + +Navigate to the directory containing the distribution and run the following command: +```bash +sudo dpkg -i opensearch-2.5.0-linux-x64.deb +``` + +### APT-GET + +To upgrade to the latest version of OpenSearch using `apt-get`: +```bash +sudo apt-get upgrade opensearch +``` + +You can also upgrade to a specific OpenSearch version: +```bash +sudo apt-get upgrade opensearch= +``` + +## Related links + +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) +- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) +- [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file diff --git a/_opensearch/install/docker.md b/_install-and-configure/install-opensearch/docker.md similarity index 96% rename from _opensearch/install/docker.md rename to _install-and-configure/install-opensearch/docker.md index 96668a66cf..b7f1e1bf4d 100644 --- a/_opensearch/install/docker.md +++ b/_install-and-configure/install-opensearch/docker.md @@ -2,14 +2,16 @@ layout: default title: Docker parent: Install OpenSearch -nav_order: 3 +nav_order: 5 +redirect_from: + - /opensearch/install/docker/ --- -# Why use OpenSearch with Docker? +# Docker [Docker](https://www.docker.com/) greatly simplifies the process of configuring and managing your OpenSearch clusters. You can pull official images from [Docker Hub](https://hub.docker.com/u/opensearchproject) or [Amazon Elastic Container Registry (Amazon ECR)](https://gallery.ecr.aws/opensearchproject/) and quickly deploy a cluster using [Docker Compose](https://github.com/docker/compose) and any of the sample Docker Compose files included in this guide. Experienced OpenSearch users can further customize their deployment by creating a custom Docker Compose file. -Docker containers are portable and will run on any compatible host that supports Docker (such as Linux, MacOS, or Windows). The portability of a Docker container offers flexibility over other installations methods, like [RPM]({{site.url}}{{site.baseurl}}/opensearch/install/rpm/) or a manual [Tarball]({{site.url}}{{site.baseurl}}/opensearch/install/tar/) installation, which both require additional configuration after downloading and unpacking. +Docker containers are portable and will run on any compatible host that supports Docker (such as Linux, MacOS, or Windows). The portability of a Docker container offers flexibility over other installations methods, like [RPM]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/rpm/) or a manual [Tarball]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/tar/) installation, which both require additional configuration after downloading and unpacking. This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} @@ -28,7 +30,8 @@ If you need to install Docker Compose manually and your host supports Python, yo ## Important host settings -Before launching OpenSearch you should review some [important system settings]({{site.url}}{{site.baseurl}}/opensearch/install/important-settings/){:target='\_blank'} that can impact the performance of your services. +Before launching OpenSearch you should review some [important system settings]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/index/#important-settings){:target='\_blank'} that can impact the performance of your services. + 1. Disable memory paging and swapping performance on the host to improve performance. ```bash sudo swapoff -a @@ -71,9 +74,6 @@ To download a specific version of OpenSearch or OpenSearch Dashboards other than Before continuing, you should verify that Docker is working correctly by deploying OpenSearch in a single container. -<<<<<<< HEAD -OpenSearch images use `amazonlinux:2` as the base image. If you run Docker locally, set Docker to use at least 4 GB of RAM in **Preferences** > **Resources**. -======= 1. Run the following command: ```bash # This command maps ports 9200 and 9600, sets the discovery type to "single-node" and requests the newest image of OpenSearch @@ -116,7 +116,6 @@ OpenSearch images use `amazonlinux:2` as the base image. If you run Docker local Remember that `docker container ls` does not list stopped containers. If you would like to review stopped containers, use `docker container ls -a`. You can remove unneeded containers manually with `docker container rm [...]` (pass all container IDs you wish to stop, separated by spaces), or if you want to remove all stopped containers, you can use the shorter command `docker prune`. {: .tip} ->>>>>>> da65102 (Putting all the Docker install material on a single page (#1452)) ## Deploy an OpenSearch cluster using Docker Compose @@ -458,7 +457,7 @@ COPY --chown=opensearch:opensearch my-root-cas.pem /usr/share/opensearch/config/ ## Related links -- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [Performance analyzer]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/) -- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/index/) +- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) - [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file diff --git a/_opensearch/install/helm.md b/_install-and-configure/install-opensearch/helm.md similarity index 98% rename from _opensearch/install/helm.md rename to _install-and-configure/install-opensearch/helm.md index e66bf3a8bf..b15c00628e 100644 --- a/_opensearch/install/helm.md +++ b/_install-and-configure/install-opensearch/helm.md @@ -3,9 +3,11 @@ layout: default title: Helm parent: Install OpenSearch nav_order: 6 +redirect_from: + - /opensearch/install/helm/ --- -# Run OpenSearch using Helm +# Helm Helm is a package manager that allows you to easily install and manage OpenSearch in a Kubernetes cluster. You can define your OpenSearch configurations in a YAML file and use Helm to deploy your applications in a version-controlled and reproducible way. @@ -156,4 +158,4 @@ To delete or uninstall a deployment, run the following command: helm delete opensearch-1-1629223146 ``` -For steps to install OpenSearch Dashboards, see [Helm to install OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/helm/). +For steps to install OpenSearch Dashboards, see [Helm to install OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/helm/). \ No newline at end of file diff --git a/_install-and-configure/install-opensearch/index.md b/_install-and-configure/install-opensearch/index.md new file mode 100644 index 0000000000..07f06f334e --- /dev/null +++ b/_install-and-configure/install-opensearch/index.md @@ -0,0 +1,88 @@ +--- +layout: default +title: Installing OpenSearch +nav_order: 2 +has_children: true +redirect_from: + - /opensearch/install/ + - /opensearch/install/compatibility/ + - /opensearch/install/important-settings/ + - /install-and-configure/index/ +--- + +# Installing OpenSearch + +This section details how to install OpenSearch on your host, including which operating systems are [compatible with OpenSearch](#operating-system-compatibility), which [ports to open](#network-requirements), and which [important settings](#important-settings) to configure on your host. + +## Operating system compatibility + +We recommend installing OpenSearch on Red Hat Enterprise Linux (RHEL) or Debian-based Linux distributions that use [systemd](https://en.wikipedia.org/wiki/Systemd), such as CentOS, Amazon Linux 2, or Ubuntu Long-Term Support (LTS). OpenSearch should work on most Linux distributions, but we only test a handful. We recommend RHEL 7 or 8, CentOS 7 or 8, Amazon Linux 2, or Ubuntu 16.04, 18.04, or 20.04 for any version of OpenSearch. OpenSearch also supports Windows Server 2019. + +Avoid using a network file system for node storage in a production workflow. Using a network file system for node storage can cause performance issues in your cluster due to factors such as network conditions (like latency or limited throughput) or read/write speeds. You should use solid-state drives (SSDs) installed on the host for node storage where possible. +{: .note} + +## Java compatibility + +The OpenSearch distribution for Linux ships with a compatible [Adoptium JDK](https://adoptium.net/) version of Java in the `jdk` directory. To find the JDK version, run `./jdk/bin/java -version`. For example, the OpenSearch 1.0.0 tarball ships with Java 15.0.1+9 (non-LTS), OpenSearch 1.3.0 ships with Java 11.0.14.1+1 (LTS), and OpenSearch 2.0.0 ships with Java 17.0.2+8 (LTS). OpenSearch is tested with all compatible Java versions. + +OpenSearch Version | Compatible Java Versions | Bundled Java Version +:---------- | :-------- | :----------- +1.0 - 1.2.x | 11, 15 | 15.0.1+9 +1.3.x | 8, 11, 14 | 11.0.14.1+1 +2.0.0 | 11, 17 | 17.0.2+8 + +To use a different Java installation, set the `OPENSEARCH_JAVA_HOME` or `JAVA_HOME` environment variable to the Java install location. For example: +```bash +export OPENSEARCH_JAVA_HOME=/path/to/opensearch-{{site.opensearch_version}}/jdk +``` + +## Network requirements + +The following ports need to be open for OpenSearch components. + +Port number | OpenSearch component +:--- | :--- +443 | OpenSearch Dashboards in AWS OpenSearch Service with encryption in transit (TLS) +5601 | OpenSearch Dashboards +9200 | OpenSearch REST API +9250 | Cross-cluster search +9300 | Node communication and transport +9600 | Performance Analyzer + +## Important settings + +For production workloads, make sure the [Linux setting](https://www.kernel.org/doc/Documentation/sysctl/vm.txt) `vm.max_map_count` is set to at least 262144. Even if you use the Docker image, set this value on the *host machine*. To check the current value, run this command: + +```bash +cat /proc/sys/vm/max_map_count +``` + +To increase the value, add the following line to `/etc/sysctl.conf`: + +``` +vm.max_map_count=262144 +``` + +Then run `sudo sysctl -p` to reload. + +The [sample docker-compose.yml]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#sample-docker-composeyml) file also contains several key settings: + +- `bootstrap.memory_lock=true` + + Disables swapping (along with `memlock`). Swapping can dramatically decrease performance and stability, so you should ensure it is disabled on production clusters. + +- `OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m` + + Sets the size of the Java heap (we recommend half of system RAM). + +- `nofile 65536` + + Sets a limit of 65536 open files for the OpenSearch user. + +- `port 9600` + + Allows you to access Performance Analyzer on port 9600. + +Do not declare the same JVM options in multiple locations because it can result in unexpected behavior or a failure of the OpenSearch service to start. If you declare JVM options using an environment variable, such as `OPENSEARCH_JAVA_OPTS=-Xms3g -Xmx3g`, then you should comment out any references to that JVM option in `config/jvm.options`. Conversely, if you define JVM options in `config/jvm.options`, then you should not define those JVM options using environment variables. +{: .note} + diff --git a/_opensearch/install/rpm.md b/_install-and-configure/install-opensearch/rpm.md similarity index 98% rename from _opensearch/install/rpm.md rename to _install-and-configure/install-opensearch/rpm.md index 70c5d96abc..0ba2ce3ddc 100644 --- a/_opensearch/install/rpm.md +++ b/_install-and-configure/install-opensearch/rpm.md @@ -113,7 +113,7 @@ YUM, the primary package management tool for Red Hat–based operating systems, Before proceeding with any configuration, you should test your installation of OpenSearch. Otherwise, it can be difficult to determine whether future problems are due to installation issues or custom settings you applied after installation. -When OpenSearch is installed using the RPM package, some demo security settings are automatically applied. This includes self-signed TLS certificates and several users and roles. If you would like to configure these yourself, see [Set up OpenSearch in your environment](#setup-opensearch-in-your-environment). +When OpenSearch is installed using the RPM package, some demo security settings are automatically applied. This includes self-signed TLS certificates and several users and roles. If you would like to configure these yourself, see [Set up OpenSearch in your environment](#step-3-set-up-opensearch-in-your-environment). An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. {: .warning} @@ -180,7 +180,7 @@ The following recommended settings will allow you to: - Configure your own TLS certificates—no third-party certificate authority (CA) is required. - Create an admin user with a custom password. -If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) for guidance before proceeding. +If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) for guidance before proceeding. {:.note} Before modifying any configuration files, it's always a good idea to save a backup copy before making changes. The backup file can be used to mitigate any issues caused by a bad configuration. @@ -443,8 +443,7 @@ sudo yum update ## Related links -- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) -- [Configure Performance Analyzer for Tarball Installation]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/#configure-performance-analyzer-for-tarball-installation) -- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/index/) +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) +- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) - [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file diff --git a/_opensearch/install/tar.md b/_install-and-configure/install-opensearch/tar.md similarity index 97% rename from _opensearch/install/tar.md rename to _install-and-configure/install-opensearch/tar.md index 483840790e..64ee26c593 100644 --- a/_opensearch/install/tar.md +++ b/_install-and-configure/install-opensearch/tar.md @@ -2,7 +2,9 @@ layout: default title: Tarball parent: Install OpenSearch -nav_order: 50 +nav_order: 10 +redirect_from: + - /opensearch/install/tar/ --- # Tarball @@ -75,7 +77,7 @@ Before proceeding you should test your installation of OpenSearch. Otherwise, it 1. **(Security enabled)** Apply a generic configuration using the demo security script included in the tar archive. 1. **(Security disabled)** Manually disable the security plugin and test the instance before applying your own custom security settings. -The demo security script will apply a generic configuration to your instance of OpenSearch. This configuration defines some environment variables and also applies self-signed TLS certificates. If you would like to configure these yourself, see [Set up OpenSearch in your environment](#setup-opensearch-in-your-environment). +The demo security script will apply a generic configuration to your instance of OpenSearch. This configuration defines some environment variables and also applies self-signed TLS certificates. If you would like to configure these yourself, see [Step 4: Set up OpenSearch in your environment](#step-4-set-up-opensearch-in-your-environment). If you only want to verify that the service is properly configured and you intend to configure security settings yourself, then you may want to disable the security plugin and launch the service without encryption or authentication. @@ -216,7 +218,7 @@ The following recommended settings will allow you to: - Configure your own TLS certificates - no third-party certificate authority (CA) is required. - Create an admin user with a custom password. -If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) for guidance before proceeding. +If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) for guidance before proceeding. {:.note} Before modifying any configuration files, it's always a good idea to save a backup copy before making changes. The backup file can be used to revert any issues caused by a bad configuration. @@ -457,7 +459,7 @@ $ curl https://your.host.address:9200 -u admin:yournewpassword -k This section will guide you through creating a service for OpenSearch and registering it with `systemd`. After the service has been defined, you can enable, start, and stop the OpenSearch service using `systemctl` commands. The commands in this section reflect an environment where OpenSearch has been installed to `/opt/opensearch` and should be changed depending on your installation path. -The following configuration is only suitable for testing in a non-production environment. We do not recommend using the following configuration in a production environment. You should install OpenSearch with the [RPM]({{site.url}}{{site.baseurl}}/opensearch/install/rpm/) distribution if you want to run OpenSearch as a systemd-managed service on your host. The tarball installation does not define a specific installation path, users, roles, or permissions. Failure to properly secure your host environment can result in unexpected behavior. +The following configuration is only suitable for testing in a non-production environment. We do not recommend using the following configuration in a production environment. You should install OpenSearch with the [RPM]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/rpm) distribution if you want to run OpenSearch as a systemd-managed service on your host. The tarball installation does not define a specific installation path, users, roles, or permissions. Failure to properly secure your host environment can result in unexpected behavior. {: .warning} 1. Create a user for the OpenSearch service. @@ -535,8 +537,8 @@ The following configuration is only suitable for testing in a non-production env ## Related links -- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/) +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [Configure Performance Analyzer for Tarball Installation]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/#install-performance-analyzer) -- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/index/) +- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) - [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) - [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file diff --git a/_install-and-configure/install-opensearch/windows.md b/_install-and-configure/install-opensearch/windows.md new file mode 100644 index 0000000000..e92b5b941b --- /dev/null +++ b/_install-and-configure/install-opensearch/windows.md @@ -0,0 +1,249 @@ +--- +layout: default +title: Windows +parent: Install OpenSearch +nav_order: 65 +--- + +# Windows + +The following sections describe installing OpenSearch on Windows from a zip archive. + +Generally speaking, the installation of OpenSearch from a zip archive can be broken down into a few steps: + +1. **Download and unpack OpenSearch.** +1. **(Optional) Test OpenSearch.** + - Confirm that OpenSearch is able to run before you apply any custom configuration. + - This can be done without any security (no password, no certificates) or with a demo security configuration that can be applied by a packaged script. +1. **Configure OpenSearch for your environment.** + - Apply basic settings to OpenSearch and start using it in your environment. + +The Windows OpenSearch archive is a self-contained directory with everything needed to run OpenSearch, including an integrated Java Development Kit (JDK). If you have your own Java installation and set the environment variable `JAVA_HOME`, OpenSearch will use that installation if the `OPENSEARCH_JAVA_HOME` environment variable is not set. To learn how to set the `OPENSEARCH_JAVA_HOME` environment variable, see [Step 3: Set up OpenSearch in your environment](#step-3-set-up-opensearch-in-your-environment). + +## Prerequisites + +Make sure you have a zip utility installed. + +## Step 1: Download and unpack OpenSearch + +Perform the following steps to install OpenSearch on Windows. + +1. Download the [`opensearch-{{site.opensearch_version}}-windows-x64.zip`](https://artifacts.opensearch.org/releases/bundle/opensearch/{{site.opensearch_version}}/opensearch-{{site.opensearch_version}}-windows-x64.zip){:target='\_blank'} archive. +1. To extract the archive contents, right-click to select **Extract All**. + +## Step 2: (Optional) Test OpenSearch + +Before proceeding with any configuration, you should test your installation of OpenSearch. Otherwise, it can be difficult to determine whether future problems are due to installation issues or custom settings you applied after installation. There are two quick methods for testing OpenSearch at this stage: + +1. **(Security enabled)** Apply a generic configuration using the batch script included in the Windows archive. +1. **(Security disabled)** Manually disable the security plugin and test the instance before applying your own custom security settings. + +The batch script will apply a generic configuration to your instance of OpenSearch. This configuration defines some environment variables and also applies self-signed TLS certificates. Alternatively, you can choose to configure these yourself. + +If you only want to verify that the service is properly configured and you intend to configure security settings yourself, then you may want to disable the security plugin and launch the service without encryption or authentication. + +An OpenSearch node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and [update the list of internal users and passwords]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml). See [Security configuration]({{site.url}}{{site.baseurl}}/security-plugin/configuration/index/) for additional guidance to ensure that your nodes are configured according to your security requirements. +{: .warning} + +### Option 1: Test your OpenSearch settings with security enabled + +1. Run the demo batch script. + + There are two ways of running the batch script: + + 1. Run the batch script using the Windows UI: + + 1. Navigate to the top directory of your OpenSearch installation and open the `opensearch-{{site.opensearch_version}}` folder. + 1. Run the batch script by double-clicking the `opensearch-windows-install.bat` file. This opens a command prompt with an OpenSearch instance running. + + 1. Run the batch script from Command prompt or Powershell: + + 1. Open Command Prompt by entering `cmd`, or Powershell by entering `powershell`, in the search box next to **Start** on the taskbar. + 1. Change to the top directory of your OpenSearch installation. + ```bat + cd \path\to\opensearch-{{site.opensearch_version}} + ``` + 1. Run the batch script. + ```bat + .\opensearch-windows-install.bat + ``` + +1. Open a new command prompt and send requests to the server to verify that OpenSearch is running. Note the use of the `--insecure` flag, which is required because the TLS certificates are self-signed. + - Send a request to port 9200: + ```bat + curl.exe -X GET https://localhost:9200 -u 'admin:admin' --insecure + ``` + You should get a response that looks like this: + ```bat + { + "name" : "hostname-here", + "cluster_name" : "opensearch", + "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw", + "version" : { + "distribution" : "opensearch", + "number" : "2.4.0", + "build_type" : "zip", + "build_hash" : "77ef9e304dd6ee95a600720a387a9735bbcf7bc9", + "build_date" : "2022-11-05T05:50:15.404072800Z", + "build_snapshot" : false, + "lucene_version" : "9.4.1", + "minimum_wire_compatibility_version" : "7.10.0", + "minimum_index_compatibility_version" : "7.0.0" + }, + "tagline" : "The OpenSearch Project: https://opensearch.org/" + } + ``` + - Query the plugins endpoint: + ```bat + curl.exe -X GET https://localhost:9200/_cat/plugins?v -u 'admin:admin' --insecure + ``` + + The response should look like this: + ```bat + hostname opensearch-alerting 2.4.0.0 + hostname opensearch-anomaly-detection 2.4.0.0 + hostname opensearch-asynchronous-search 2.4.0.0 + hostname opensearch-cross-cluster-replication 2.4.0.0 + hostname opensearch-geospatial 2.4.0.0 + hostname opensearch-index-management 2.4.0.0 + hostname opensearch-job-scheduler 2.4.0.0 + hostname opensearch-knn 2.4.0.0 + hostname opensearch-ml 2.4.0.0 + hostname opensearch-neural-search 2.4.0.0 + hostname opensearch-notifications 2.4.0.0 + hostname opensearch-notifications-core 2.4.0.0 + hostname opensearch-observability 2.4.0.0 + hostname opensearch-reports-scheduler 2.4.0.0 + hostname opensearch-security 2.4.0.0 + hostname opensearch-security-analytics 2.4.0.0 + hostname opensearch-sql 2.4.0.0 + ``` + +### Option 2: Test your OpenSearch settings with security disabled + +1. Open the `opensearch-{{site.opensearch_version}}\config` folder. +1. Open the `opensearch.yml` file with a text editor. +1. Add the following line to disable the security plugin: + ```yaml + plugins.security.disabled: true + ``` +1. Save the change and close the file. +1. Navigate to the top directory of your OpenSearch installation and open the `opensearch-{{site.opensearch_version}}` folder. +1. Run the default by double-clicking the `opensearch-windows-install.bat` file. This opens a command prompt with an OpenSearch instance running. +1. Open a new command prompt and send requests to the server to verify that OpenSearch is running. Because the security plugin has been disabled, you will be sending commands using `HTTP` rather than `HTTPS`. + - Send a request to port 9200: + ```bat + curl.exe -X GET http://localhost:9200 + ``` + You should get a response that looks like this: + ```bat + { + "name" : "hostname-here", + "cluster_name" : "opensearch", + "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw", + "version" : { + "distribution" : "opensearch", + "number" : "2.4.0", + "build_type" : "zip", + "build_hash" : "77ef9e304dd6ee95a600720a387a9735bbcf7bc9", + "build_date" : "2022-11-05T05:50:15.404072800Z", + "build_snapshot" : false, + "lucene_version" : "9.4.1", + "minimum_wire_compatibility_version" : "7.10.0", + "minimum_index_compatibility_version" : "7.0.0" + }, + "tagline" : "The OpenSearch Project: https://opensearch.org/" + } + ``` + - Query the plugins endpoint: + ```bat + curl.exe -X GET http://localhost:9200/_cat/plugins?v + ``` + + The response should look like this: + ```bat + hostname opensearch-alerting 2.4.0.0 + hostname opensearch-anomaly-detection 2.4.0.0 + hostname opensearch-asynchronous-search 2.4.0.0 + hostname opensearch-cross-cluster-replication 2.4.0.0 + hostname opensearch-geospatial 2.4.0.0 + hostname opensearch-index-management 2.4.0.0 + hostname opensearch-job-scheduler 2.4.0.0 + hostname opensearch-knn 2.4.0.0 + hostname opensearch-ml 2.4.0.0 + hostname opensearch-neural-search 2.4.0.0 + hostname opensearch-notifications 2.4.0.0 + hostname opensearch-notifications-core 2.4.0.0 + hostname opensearch-observability 2.4.0.0 + hostname opensearch-reports-scheduler 2.4.0.0 + hostname opensearch-security 2.4.0.0 + hostname opensearch-security-analytics 2.4.0.0 + hostname opensearch-sql 2.4.0.0 + ``` + +To stop OpenSearch, press `Ctrl+C` in Command Prompt or Powershell, or simply close the Command Prompt or Powershell window. +{: .tip} + +## Step 3: Set up OpenSearch in your environment + +Users who do not have prior experience with OpenSearch may want a list of recommended settings in order to get started with the service. By default, OpenSearch is not bound to a network interface and cannot be reached by external hosts. Additionally, security settings are either undefined (greenfield install) or populated by default usernames and passwords if you ran the security demo script by invoking `opensearch-windows-install.bat`. The following recommendations will enable a user to bind OpenSearch to a network interface. + +The following recommended settings will allow you to: + +- Bind OpenSearch to an IP or network interface on the host. +- Set initial and maximum JVM heap sizes. +- Define an environment variable that points to the bundled JDK. + +If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to [Security configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) for guidance before proceeding. +{:.note} + +Before modifying any configuration files, it's always a good idea to save a backup copy before making changes. The backup file can be used to revert any issues caused by a bad configuration. +{:.tip} + +1. Open the `opensearch-{{site.opensearch_version}}\config` folder. +1. Open the `opensearch.yml` file with a text editor. +1. Add the following lines: + ```bash + # Bind OpenSearch to the correct network interface. Use 0.0.0.0 + # to include all available interfaces or specify an IP address + # assigned to a specific interface. + network.host: 0.0.0.0 + + # Unless you have already configured a cluster, you should set + # discovery.type to single-node, or the bootstrap checks will + # fail when you try to start the service. + discovery.type: single-node + + # If you previously disabled the security plugin in opensearch.yml, + # be sure to re-enable it. Otherwise you can skip this setting. + plugins.security.disabled: false + ``` +1. Save your changes and close the file. +1. Specify initial and maximum JVM heap sizes. + 1. Open the `opensearch-{{site.opensearch_version}}\config` folder. + 1. Open the `jvm.options` file with a text editor. + 1. Modify the values for initial and maximum heap sizes. As a starting point, you should set these values to half of the available system memory. For dedicated hosts this value can be increased based on your workflow requirements.
+ As an example, if the host machine has 8 GB of memory, then you might want to set the initial and maximum heap sizes to 4 GB: + ```bash + -Xms4g + -Xmx4g + ``` + 1. Save your changes and close the file. +1. Specify the location of the included JDK. + 1. In the search box next to **Start** on the taskbar, enter `edit environment variables for your account` or `edit the system environment variables`. To edit the system environment variables, you need admin rights. User environment variables take precedence over system environment variables. + 1. Select **Edit environment variables for your account** or **Edit the system environment variables**. + 1. If the **System Properties** dialog opens, in the **Advanced** tab, select **Environment Variables**. + 1. Under **User variables** or **System variables**, select **New**. + 1. In **Variable name**, enter `OPENSEARCH_JAVA_HOME`. + 1. In **Variable value**, enter `\path\to\opensearch-{{site.opensearch_version}}\jdk`. + 1. Select **OK** to close all dialogs. + +## Plugin compatibility + +The Performance Analyzer plugin is not available on Windows. All other OpenSearch plugins, including the k-NN plugin, are available. For a complete list of plugins, see [Available plugins]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/#available-plugins). + +## Related links + +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) +- [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) \ No newline at end of file diff --git a/_opensearch/install/plugins.md b/_install-and-configure/plugins.md similarity index 91% rename from _opensearch/install/plugins.md rename to _install-and-configure/plugins.md index 5e581fca4c..2c715ac99f 100644 --- a/_opensearch/install/plugins.md +++ b/_install-and-configure/plugins.md @@ -1,25 +1,27 @@ --- layout: default -title: OpenSearch plugin installation -parent: Install OpenSearch +title: Installing plugins nav_order: 90 +redirect_from: + - /opensearch/install/plugins/ + - /install-and-configure/install-opensearch/plugins/ --- -# OpenSearch plugin installation +# Installing plugins -You can install individual plugins for OpenSearch based on your needs. For information about available plugins, see [Available plugins]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#available-plugins). +You can install individual plugins for OpenSearch based on your needs. For information about available plugins, see [Available plugins](#available-plugins). ## Managing plugins OpenSearch uses a command line tool called `opensearch-plugin` for managing plugins. This tool allows you to: -- [List]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#list) installed plugins. -- [Install]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#install) plugins. -- [Remove]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#remove) an installed plugin. +- [List](#list) installed plugins. +- [Install](#install) plugins. +- [Remove](#remove) an installed plugin. Print help text by passing `-h` or `--help`. Depending on your host configuration, you might also need to run the command with `sudo` privileges. -If you are running OpenSearch in a Docker container, plugins must be installed, removed, and configured by modifying the Docker image. For information, see [Working with plugins]({{site.url}}{{site.baseurl}}/opensearch/install/docker#working-with-plugins) +If you are running OpenSearch in a Docker container, plugins must be installed, removed, and configured by modifying the Docker image. For information, see [Working with plugins]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker#working-with-plugins) {: .note} ## List @@ -85,7 +87,7 @@ There are three ways to install plugins using the `opensearch-plugin`: ### Install a plugin by name: -For a list of plugins that can be installed by name, see [Additional plugins]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#additional-plugins) +For a list of plugins that can be installed by name, see [Additional plugins]({{site.url}}{{site.baseurl}}/opensearch/install/plugins#additional-plugins). #### Usage: ```bash @@ -97,7 +99,7 @@ bin/opensearch-plugin install $ sudo ./opensearch-plugin install analysis-icu -> Installing analysis-icu -> Downloading analysis-icu from opensearch -[=================================================] 100%   +[=================================================] 100% -> Installed analysis-icu with folder name analysis-icu ``` @@ -116,7 +118,7 @@ bin/opensearch-plugin install $ sudo ./opensearch-plugin install https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip -> Installing https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip -> Downloading https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip -[=================================================] 100%   +[=================================================] 100% @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: plugin requires additional permissions @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -140,7 +142,7 @@ Continue with installation? [y/N]y $ sudo ./opensearch-plugin install file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip -> Installing file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip -> Downloading file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip -[=================================================] 100%   +[=================================================] 100% @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: plugin requires additional permissions @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -175,7 +177,7 @@ bin/opensearch-plugin install :: $ sudo ./opensearch-plugin install org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0 -> Installing org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0 -> Downloading org.opensearch.plugin:opensearch-anomaly-detection:2.2.0.0 from maven central -[=================================================] 100%   +[=================================================] 100% @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: plugin requires additional permissions @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -251,12 +253,14 @@ The following plugins are bundled with all OpenSearch distributions except for m | ML Commons | [opensearch-ml](https://github.com/opensearch-project/ml-commons) | 1.3.0 | | Neural Search | [neural-search](https://github.com/opensearch-project/neural-search) | 2.4.0 | | Observability | [opensearch-observability](https://github.com/opensearch-project/observability) | 1.2.0 | -| Performance Analyzer | [opensearch-performance-analyzer](https://github.com/opensearch-project/performance-analyzer) | 1.0.0 | +| Performance Analyzer2 | [opensearch-performance-analyzer](https://github.com/opensearch-project/performance-analyzer) | 1.0.0 | | Security | [opensearch-security](https://github.com/opensearch-project/security) | 1.0.0 | -| Security Analytics | [security-analytics](https://github.com/opensearch-project/security-analytics) | 2.4.0 | +| Security Analytics | [opensearch-security-analytics](https://github.com/opensearch-project/security-analytics) | 2.4.0 | | SQL | [opensearch-sql](https://github.com/opensearch-project/sql) | 1.0.0 | -_1Dashboard Notebooks was merged in to the Observability plugin with the release of OpenSearch 1.2.0._ +_1Dashboard Notebooks was merged in to the Observability plugin with the release of OpenSearch 1.2.0._
+_2Performance Analyzer is not available on Windows._ + ### Additional plugins @@ -288,6 +292,7 @@ Members of the OpenSearch community have built countless plugins for the service ## Related links - [About Observability]({{site.url}}{{site.baseurl}}/observability-plugin/index/) +- [About security analytics]({{site.url}}{{site.baseurl}}/security-analytics/index/) - [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) - [Alerting]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/index/) - [Anomaly detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/index/) @@ -296,7 +301,8 @@ Members of the OpenSearch community have built countless plugins for the service - [Index State Management]({{site.url}}{{site.baseurl}}/im-plugin/ism/index/) - [k-NN]({{site.url}}{{site.baseurl}}/search-plugins/knn/index/) - [ML Commons Plugin]({{site.url}}{{site.baseurl}}/ml-commons-plugin/index/) +- [Neural Search]({{site.url}}{{site.baseurl}}/neural-search-plugin/index/) - [Notifications]({{site.url}}{{site.baseurl}}/notifications-plugin/index/) - [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/index/) - [Performance Analyzer]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/) -- [SQL]({{site.url}}{{site.baseurl}}/search-plugins/sql/index/) \ No newline at end of file +- [SQL]({{site.url}}{{site.baseurl}}/search-plugins/sql/index/) diff --git a/_opensearch/install/compatibility.md b/_opensearch/install/compatibility.md deleted file mode 100644 index 9e897967a1..0000000000 --- a/_opensearch/install/compatibility.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: default -title: Compatibility -parent: Install OpenSearch -nav_order: 2 ---- - -# Operating system compatibility - -We recommend installing OpenSearch on Red Hat Enterprise Linux (RHEL) or Debian-based Linux distributions that use [systemd](https://en.wikipedia.org/wiki/Systemd), such as CentOS, Amazon Linux 2, and Ubuntu Long-Term Support (LTS). OpenSearch should work on most Linux distributions, but we only test a handful. We recommend RHEL 7 or 8, CentOS 7 or 8, Amazon Linux 2, Ubuntu 16.04, 18.04, or 20.04 for any version of OpenSearch. - -Avoid using a network file system for node storage in a production workflow. Using a network file system for node storage can cause performance issues in your cluster due to factors such as network conditions (like latency or limited throughput) or read/write speeds. You should use solid-state drives (SSDs) installed on the host for node storage where possible. -{: .note} - -# Java compatibility - -The OpenSearch distribution for Linux ships with a compatible [Adoptium JDK](https://adoptium.net/) version of Java in the `jdk` directory. To find the JDK version, run `./jdk/bin/java -version`. For example, the OpenSearch 1.0.0 tarball ships with Java 15.0.1+9 (non-LTS), OpenSearch 1.3.0 ships with Java 11.0.14.1+1 (LTS), and OpenSearch 2.0.0 ships with Java 17.0.2+8 (LTS). OpenSearch is tested with all compatible Java versions. - -OpenSearch Version | Compatible Java Versions | Bundled Java Version -:---------- | :-------- | :----------- -1.0 - 1.2.x | 11, 15 | 15.0.1+9 -1.3.x | 8, 11, 14 | 11.0.14.1+1 -2.0.0 | 11, 17 | 17.0.2+8 - -To use a different Java installation, set the `OPENSEARCH_JAVA_HOME` or `JAVA_HOME` environment variable to the Java install location. For example: -```bash -export OPENSEARCH_JAVA_HOME=/path/to/opensearch-{{site.opensearch_version}}/jdk -``` \ No newline at end of file diff --git a/_opensearch/install/important-settings.md b/_opensearch/install/important-settings.md deleted file mode 100644 index 854b019333..0000000000 --- a/_opensearch/install/important-settings.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Important settings -parent: Install OpenSearch -nav_order: 70 ---- - -# Important settings - -For production workloads, make sure the [Linux setting](https://www.kernel.org/doc/Documentation/sysctl/vm.txt) `vm.max_map_count` is set to at least 262144. Even if you use the Docker image, set this value on the *host machine*. To check the current value, run this command: - -```bash -cat /proc/sys/vm/max_map_count -``` - -To increase the value, add the following line to `/etc/sysctl.conf`: - -``` -vm.max_map_count=262144 -``` - -Then run `sudo sysctl -p` to reload. - -The [sample docker-compose.yml]({{site.url}}{{site.baseurl}}/opensearch/install/docker#sample-docker-composeyml) file also contains several key settings: - -- `bootstrap.memory_lock=true` - - Disables swapping (along with `memlock`). Swapping can dramatically decrease performance and stability, so you should ensure it is disabled on production clusters. - -- `OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m` - - Sets the size of the Java heap (we recommend half of system RAM). - -- `nofile 65536` - - Sets a limit of 65536 open files for the OpenSearch user. - -- `port 9600` - - Allows you to access Performance Analyzer on port 9600. - -Do not declare the same JVM options in multiple locations because it can result in unexpected behavior or a failure of the OpenSearch service to start. If you declare JVM options using an environment variable, such as `OPENSEARCH_JAVA_OPTS=-Xms3g -Xmx3g`, then you should comment out any references to that JVM option in `config/jvm.options`. Conversely, if you define JVM options in `config/jvm.options`, then you should not define those JVM options using environment variables. -{: .note} - -### Network requirements - - The following ports need to be open for OpenSearch components. - -Port number | OpenSearch component -:--- | :--- -443 | OpenSearch Dashboards in AWS OpenSearch Service with encryption in transit (TLS) -5601 | OpenSearch Dashboards -9200 | OpenSearch REST API -9250 | Cross-cluster search -9300 | Node communication and transport -9600 | Performance Analyzer - diff --git a/_opensearch/install/index.md b/_opensearch/install/index.md deleted file mode 100644 index f9749d9869..0000000000 --- a/_opensearch/install/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Install OpenSearch -nav_order: 2 -redirect_from: - - /opensearch/install/ -has_children: true ---- - -# Install and configure OpenSearch - -OpenSearch has two installation options at this time: Docker images and tarballs. - -OpenSearch does not support direct version downgrades. If your environment must be downgraded, we recommend [using snapshots to create a restore point](https://opensearch.org/docs/latest/opensearch/snapshot-restore/), then restoring the snapshot to a cluster built with the target version. -{: .note } \ No newline at end of file diff --git a/_opensearch/query-dsl/full-text.md b/_opensearch/query-dsl/full-text.md index 186b931583..4718841f32 100644 --- a/_opensearch/query-dsl/full-text.md +++ b/_opensearch/query-dsl/full-text.md @@ -457,10 +457,10 @@ Option | Valid values | Description `fields` | String array | The list of fields to search (e.g. `"fields": ["title^4", "description"]`). If unspecified, defaults to the `index.query.default_field` setting, which defaults to `["*"]`. `flags` | String | A `|`-delimited string of [flags](#simple-query-string) to enable (e.g., `AND|OR|NOT`). The default is `ALL`. You can explicitly set the value for `default_field`. For example, to return all titles, set it to `"default_field": "title"`. `lenient` | Boolean | Setting `lenient` to true lets you ignore data type mismatches between the query and the document field. For example, a query string of "8.2" could match a field of type `float`. The default is false. -`low_freq_operator` | `and, or` | The operator for low-frequency terms. The default is `or`. See [Common terms](#common-terms) queries and `operator` in this table. +`low_freq_operator` | `and, or` | The operator for low-frequency terms. The default is `or`. `max_determinized_states` | Positive integer | The maximum number of "[states](https://lucene.apache.org/core/8_9_0/core/org/apache/lucene/util/automaton/Operations.html#DEFAULT_MAX_DETERMINIZED_STATES)" (a measure of complexity) that Lucene can create for query strings that contain regular expressions (e.g. `"query": "/wind.+?/"`). Larger numbers allow for queries that use more memory. The default is 10,000. `max_expansions` | Positive integer | `max_expansions` specifies the maximum number of terms to which the query can expand. The default is 50. -`minimum_should_match` | Positive or negative integer, positive or negative percentage, combination | If the query string contains multiple search terms and you used the `or` operator, the number of terms that need to match for the document to be considered a match. For example, if `minimum_should_match` is 2, "wind often rising" does not match "The Wind Rises." If `minimum_should_match` is 1, it matches. This option also has `low_freq` and `high_freq` properties for [Common terms](#common-terms) queries. +`minimum_should_match` | Positive or negative integer, positive or negative percentage, combination | If the query string contains multiple search terms and you used the `or` operator, the number of terms that need to match for the document to be considered a match. For example, if `minimum_should_match` is 2, "wind often rising" does not match "The Wind Rises." If `minimum_should_match` is 1, it matches. This option also has `low_freq` and `high_freq` properties for Common terms queries. `operator` | `or, and` | If the query string contains multiple search terms, whether all terms need to match (`and`) or only one term needs to match (`or`) for a document to be considered a match. `phrase_slop` | `0` (default) or a positive integer | See `slop`. `prefix_length` | `0` (default) or a positive integer | The number of leading characters that are not considered in fuzziness. diff --git a/_opensearch/supported-field-types/range.md b/_opensearch/supported-field-types/range.md index 1ae9e1a81d..c9cfabf91d 100644 --- a/_opensearch/supported-field-types/range.md +++ b/_opensearch/supported-field-types/range.md @@ -56,7 +56,7 @@ PUT testindex/_doc/1 } ``` -You can use a [term query](#term-query) or a [range query](#range-query) to search for values within range fields. +You can use a [term query](#term-query) or a [range query](#range-query-optional-parameters) to search for values within range fields. ### Term query diff --git a/index.md b/index.md index 0092ad8ff9..bba2f17120 100644 --- a/index.md +++ b/index.md @@ -11,8 +11,6 @@ permalink: / This site contains the technical documentation for [OpenSearch](https://opensearch.org/), the Apache 2.0-licensed search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. -[Get started](#docker-quickstart){: .btn .btn-blue } - ## Getting started