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.
  2. (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.
  3. 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.

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-2.12.0-windows-x64.zip archive.
  2. 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.
  2. (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. See Security configuration for additional guidance to ensure that your nodes are configured according to your security requirements.

Option 1: Test your OpenSearch settings with security enabled

  1. Run the demo 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.

    2. Change to the top directory of your OpenSearch installation.

      1. cd \path\to\opensearch-2.12.0

      copy

    3. Run the batch script. For OpenSearch 2.12 or later, use the following command to specify a custom admin password:

      1. > set OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>

      copy

      1. .\opensearch-windows-install.bat

      copy

  2. 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:

      1.  curl.exe -X GET https://localhost:9200 -u "admin:<custom-admin-password>" --insecure

      copy

      You should get a response that looks like this:

      1.  {
      2.     "name" : "hostname-here",
      3.     "cluster_name" : "opensearch",
      4.     "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw",
      5.     "version" : {
      6.        "distribution" : "opensearch",
      7.        "number" : <version>,
      8.        "build_type" : <build-type>,
      9.        "build_hash" : <build-hash>,
      10.        "build_date" : <build-date>,
      11.        "build_snapshot" : false,
      12.        "lucene_version" : <lucene-version>,
      13.        "minimum_wire_compatibility_version" : "7.10.0",
      14.        "minimum_index_compatibility_version" : "7.0.0"
      15.     },
      16.     "tagline" : "The OpenSearch Project: https://opensearch.org/"
      17.  }

    • Query the plugins endpoint:

      1.  curl.exe -X GET https://localhost:9200/_cat/plugins?v -u "admin:<custom-admin-password>" --insecure

      copy

      The response should look like this:

      1.  hostname opensearch-alerting                  2.12.0
      2.  hostname opensearch-anomaly-detection         2.12.0
      3.  hostname opensearch-asynchronous-search       2.12.0
      4.  hostname opensearch-cross-cluster-replication 2.12.0
      5.  hostname opensearch-geospatial                2.12.0
      6.  hostname opensearch-index-management          2.12.0
      7.  hostname opensearch-job-scheduler             2.12.0
      8.  hostname opensearch-knn                       2.12.0
      9.  hostname opensearch-ml                        2.12.0
      10.  hostname opensearch-neural-search             2.12.0
      11.  hostname opensearch-notifications             2.12.0
      12.  hostname opensearch-notifications-core        2.12.0
      13.  hostname opensearch-observability             2.12.0
      14.  hostname opensearch-reports-scheduler         2.12.0
      15.  hostname opensearch-security                  2.12.0
      16.  hostname opensearch-security-analytics        2.12.0
      17.  hostname opensearch-sql                       2.12.0

Option 2: Test your OpenSearch settings with security disabled

  1. Open the opensearch-2.12.0\config folder.
  2. Open the opensearch.yml file with a text editor.

  3. Add the following line to disable the Security plugin:

    1. plugins.security.disabled: true

    copy

  4. Save the change and close the file.

  5. Navigate to the top directory of your OpenSearch installation and open the opensearch-2.12.0 folder.
  6. Run the default by double-clicking the opensearch-windows-install.bat file. This opens a command prompt with an OpenSearch instance running.

  7. 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:

      1.  curl.exe -X GET http://localhost:9200

      copy

      You should get a response that looks like this:

      1.  {
      2.     "name" : "hostname-here",
      3.     "cluster_name" : "opensearch",
      4.     "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw",
      5.     "version" : {
      6.        "distribution" : "opensearch",
      7.        "number" : "2.4.0",
      8.        "build_type" : "zip",
      9.        "build_hash" : "77ef9e304dd6ee95a600720a387a9735bbcf7bc9",
      10.        "build_date" : "2022-11-05T05:50:15.404072800Z",
      11.        "build_snapshot" : false,
      12.        "lucene_version" : "9.4.1",
      13.        "minimum_wire_compatibility_version" : "7.10.0",
      14.        "minimum_index_compatibility_version" : "7.0.0"
      15.     },
      16.     "tagline" : "The OpenSearch Project: https://opensearch.org/"
      17.  }

    • Query the plugins endpoint:

      1.  curl.exe -X GET http://localhost:9200/_cat/plugins?v

      copy

      The response should look like this:

      1.  hostname opensearch-alerting                  2.12.0
      2.  hostname opensearch-anomaly-detection         2.12.0
      3.  hostname opensearch-asynchronous-search       2.12.0
      4.  hostname opensearch-cross-cluster-replication 2.12.0
      5.  hostname opensearch-geospatial                2.12.0
      6.  hostname opensearch-index-management          2.12.0
      7.  hostname opensearch-job-scheduler             2.12.0
      8.  hostname opensearch-knn                       2.12.0
      9.  hostname opensearch-ml                        2.12.0
      10.  hostname opensearch-neural-search             2.12.0
      11.  hostname opensearch-notifications             2.12.0
      12.  hostname opensearch-notifications-core        2.12.0
      13.  hostname opensearch-observability             2.12.0
      14.  hostname opensearch-reports-scheduler         2.12.0
      15.  hostname opensearch-security                  2.12.0
      16.  hostname opensearch-security-analytics        2.12.0
      17.  hostname opensearch-sql                       2.12.0

To stop OpenSearch, press Ctrl+C in Command Prompt or Powershell, or simply close the Command Prompt or Powershell window.

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 for guidance before proceeding.

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.

  1. Open the opensearch-2.12.0\config folder.
  2. Open the opensearch.yml file with a text editor.

  3. Add the following lines:

    1. # Bind OpenSearch to the correct network interface. Use 0.0.0.0
    2. # to include all available interfaces or specify an IP address
    3. # assigned to a specific interface.
    4. network.host: 0.0.0.0
    6. # Unless you have already configured a cluster, you should set
    7. # discovery.type to single-node, or the bootstrap checks will
    8. # fail when you try to start the service.
    9. discovery.type: single-node
    11. # If you previously disabled the Security plugin in opensearch.yml,
    12. # be sure to re-enable it. Otherwise you can skip this setting.
    13. plugins.security.disabled: false

    copy

  4. Save your changes and close the file.

  5. Specify initial and maximum JVM heap sizes.

    1. Open the opensearch-2.12.0\config folder.
    2. Open the jvm.options file with a text editor.

    3. 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:

      1.  -Xms4g
      2.  -Xmx4g

      copy

    4. Save your changes and close the file.

  6. 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.
    2. Select Edit environment variables for your account or Edit the system environment variables.
    3. If the System Properties dialog opens, in the Advanced tab, select Environment Variables.
    4. Under User variables or System variables, select New.
    5. In Variable name, enter OPENSEARCH_JAVA_HOME.
    6. In Variable value, enter \path\to\opensearch-2.12.0\jdk.
    7. 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.