Debian

Installing OpenSearch using the Advanced Packaging Tool (APT) package manager simplifies the process considerably compared to the Tarball 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.
  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 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.

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. The Debian package can be downloaded for both x64 and arm64 architectures.

  2. From the CLI, install the package using dpkg:

    For new installations of OpenSearch 2.12 and later, you must define a custom admin password in order to set up a demo security configuration. Use one of the following commands to define a custom admin password:

    1. # x64
    2. sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> dpkg -i opensearch-2.13.0-linux-x64.deb
    4. # arm64
    5. sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> dpkg -i opensearch-2.13.0-linux-arm64.deb

    Use the following command for OpenSearch versions 2.11 and earlier:

    1. # x64
    2. sudo dpkg -i opensearch-2.13.0-linux-x64.deb
    4. # arm64
    5. sudo dpkg -i opensearch-2.13.0-linux-arm64.deb

  3. After the installation succeeds, enable OpenSearch as a service.

    1.  sudo systemctl enable opensearch

    copy

  4. Start the OpenSearch service.

    1.  sudo systemctl start opensearch

    copy

  5. Verify that OpenSearch launched correctly.

    1.  sudo systemctl status opensearch

    copy

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.

    1. curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/2.13.0/opensearch-2.13.0-linux-x64.deb

    copy

  2. Download the corresponding signature file.

    1. curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/2.13.0/opensearch-2.13.0-linux-x64.deb.sig

    copy

  3. Download and import the GPG key.

    1. curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | gpg --import -

    copy

  4. Verify the signature.

    1. gpg --verify opensearch-2.13.0-linux-x64.deb.sig opensearch-2.13.0-linux-x64.deb

    copy

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. Install the necessary packages.

    1. sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2

    copy

  2. Import the public GPG key. This key is used to verify that the APT repository is signed.

    1.  curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/opensearch-keyring

    copy

  3. Create an APT repository for OpenSearch:

    1. echo "deb [signed-by=/usr/share/keyrings/opensearch-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-2.x.list

    copy

  4. Verify that the repository was created successfully.

    1.  sudo apt-get update

    copy

  5. With the repository information added, list all available versions of OpenSearch:

    1. sudo apt list -a opensearch

    copy

  6. Choose the version of OpenSearch you want to install:

    • Unless otherwise indicated, the latest available version of OpenSearch is installed.
    1. # For new installations of OpenSearch 2.12 and later, you must define a custom admin password in order to set up a demo security configuration.
    2. # Use one of the following commands to define a custom admin password:
    3. sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> apt-get install opensearch
    5. # Use the following command for OpenSearch versions 2.11 and earlier:
    6. sudo apt-get install opensearch

    copy

    • To install a specific version of OpenSearch:
    1. # Specify the version manually using opensearch=<version>
    3. # For new installations of OpenSearch 2.12 and later, you must define a custom admin password in order to set up a demo security configuration.
    4. # Use one of the following commands to define a custom admin password:
    5. sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> apt-get install opensearch=2.13.0
    7. # Use the following command for OpenSearch versions 2.11 and earlier:
    8. sudo apt-get install opensearch=2.13.0

  7. During installation, the installer will present you with the GPG key fingerprint. Verify that the information matches the following:

    1. Fingerprint: c5b7 4989 65ef d1c2 924b a9d5 39d3 1987 9310 d3fc

    copy

  8. Once complete, enable OpenSearch.

    1.  sudo systemctl enable opensearch

    copy

  9. Start OpenSearch.

    1.  sudo systemctl start opensearch

    copy

  10. Verify that OpenSearch launched correctly.

    1. sudo systemctl status opensearch

    copy

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.

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.

  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:

      1.  curl -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",
      3.     "cluster_name":"opensearch",
      4.     "cluster_uuid":"QqgpHCbnSRKcPAizqjvoOw",
      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 -X GET https://localhost:9200/_cat/plugins?v -u 'admin:<custom-admin-password>' --insecure

      copy

    The response should look like this:

    1.  name          component                            version
    2.  hostname      opensearch-alerting                  2.13.0
    3.  hostname      opensearch-anomaly-detection         2.13.0
    4.  hostname      opensearch-asynchronous-search       2.13.0
    5.  hostname      opensearch-cross-cluster-replication 2.13.0
    6.  hostname      opensearch-geospatial                2.13.0
    7.  hostname      opensearch-index-management          2.13.0
    8.  hostname      opensearch-job-scheduler             2.13.0
    9.  hostname      opensearch-knn                       2.13.0
    10.  hostname      opensearch-ml                        2.13.0
    11.  hostname      opensearch-neural-search             2.13.0
    12.  hostname      opensearch-notifications             2.13.0
    13.  hostname      opensearch-notifications-core        2.13.0
    14.  hostname      opensearch-observability             2.13.0
    15.  hostname      opensearch-performance-analyzer      2.13.0
    16.  hostname      opensearch-reports-scheduler         2.13.0
    17.  hostname      opensearch-security                  2.13.0
    18.  hostname      opensearch-security-analytics        2.13.0
    19.  hostname      opensearch-sql                       2.13.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 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 mitigate any issues caused by a bad configuration.

  1. Open opensearch.yml.

    1. sudo vi /etc/opensearch/opensearch.yml

    copy

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

  3. Save your changes and close the file.

  4. Specify initial and maximum JVM heap sizes.

    1. Open jvm.options.

      1.   vi /etc/opensearch/jvm.options

      copy

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

    3. 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 and Generate Certificates, which are included in the Security plugin 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.

    1. cd /etc/opensearch

    copy

  2. Delete the demo certificates.

    1. sudo rm -f *pem

    copy

  3. Generate a root certificate. This is what you will use to sign your other certificates.

    1. # Create a private key for the root certificate
    2. sudo openssl genrsa -out root-ca-key.pem 2048
    4. # Use the private key to create a self-signed root certificate. Be sure to
    5. # replace the arguments passed to -subj so they reflect your specific host.
    6. 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

  4. Next, create the admin certificate. This certificate is used to gain elevated rights for performing administrative tasks relating to the Security plugin.

    1. # Create a private key for the admin certificate.
    2. sudo openssl genrsa -out admin-key-temp.pem 2048
    4. # Convert the private key to PKCS#8.
    5. sudo openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem
    7. # Create the certficiate signing request (CSR). A common name (CN) of "A" is acceptable because this certificate is
    8. # used for authenticating elevated access and is not tied to a host.
    9. sudo openssl req -new -key admin-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=A" -out admin.csr
    11. # Sign the admin certificate with the root certificate and private key you created earlier.
    12. sudo openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730

  5. Create a certificate for the node being configured.

    1. # Create a private key for the node certificate.
    2. sudo openssl genrsa -out node1-key-temp.pem 2048
    4. # Convert the private key to PKCS#8.
    5. sudo openssl pkcs8 -inform PEM -outform PEM -in node1-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out node1-key.pem
    7. # Create the CSR and replace the arguments passed to -subj so they reflect your specific host.
    8. # The CN should match a DNS A record for the host-do not use the hostname.
    9. 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
    11. # Create an extension file that defines a SAN DNS name for the host. This
    12. # should match the DNS A record of the host.
    13. sudo sh -c 'echo subjectAltName=DNS:node1.dns.a-record > node1.ext'
    15. # Sign the node certificate with the root certificate and private key that you created earlier.
    16. 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

  6. Remove temporary files that are no longer required.

    1. sudo rm -f *temp.pem *csr *ext

    copy

  7. Make sure the remaining certificates are owned by the opensearch user.

    1. sudo chown opensearch:opensearch admin-key.pem admin.pem node1-key.pem node1.pem root-ca-key.pem root-ca.pem root-ca.srl

    copy

  8. Add these certificates to opensearch.yml as described in Generate Certificates. Advanced users might also choose to append the settings using a script:

    1. #! /bin/bash
    3. # Before running this script, make sure to replace the CN in the 
    4. # node's distinguished name with a real DNS A record.
    6. echo "plugins.security.ssl.transport.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    7. echo "plugins.security.ssl.transport.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    8. echo "plugins.security.ssl.transport.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    9. echo "plugins.security.ssl.http.enabled: true" | sudo tee -a /etc/opensearch/opensearch.yml
    10. echo "plugins.security.ssl.http.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    11. echo "plugins.security.ssl.http.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    12. echo "plugins.security.ssl.http.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml
    13. echo "plugins.security.allow_default_init_securityindex: true" | sudo tee -a /etc/opensearch/opensearch.yml
    14. echo "plugins.security.authcz.admin_dn:" | sudo tee -a /etc/opensearch/opensearch.yml
    15. echo "  - 'CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml
    16. echo "plugins.security.nodes_dn:" | sudo tee -a /etc/opensearch/opensearch.yml
    17. echo "  - 'CN=node1.dns.a-record,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml
    18. echo "plugins.security.audit.type: internal_opensearch" | sudo tee -a /etc/opensearch/opensearch.yml
    19. echo "plugins.security.enable_snapshot_restore_privilege: true" | sudo tee -a /etc/opensearch/opensearch.yml
    20. echo "plugins.security.check_snapshot_restore_write_privileges: true" | sudo tee -a /etc/opensearch/opensearch.yml
    21. echo "plugins.security.restapi.roles_enabled: [\"all_access\", \"security_rest_api_access\"]" | sudo tee -a /etc/opensearch/opensearch.yml

    copy

  9. (Optional) Add trust for the self-signed root certificate.

    1. # Copy the root certificate to the correct directory
    2. sudo cp /etc/opensearch/root-ca.pem /etc/pki/ca-trust/source/anchors/
    4. # Add trust
    5. 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 for more information about configuring users. The following steps explain how to add a new internal user and how to replace the admin default password using a script.

  1. Navigate to the Security plugins tools directory.

    1. cd /usr/share/opensearch/plugins/opensearch-security/tools

    copy

  2. Run hash.sh to generate a new password.

    • This script will fail if a path to the JDK has not been defined.

      1.  # Example output if a JDK isn't found...
      2.  $ ./hash.sh
      3.  **************************************************************************
      4.  ** This tool will be deprecated in the next major release of OpenSearch **
      5.  ** https://github.com/opensearch-project/security/issues/1755           **
      6.  **************************************************************************
      7.  which: no java in (/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/home/user/.local/bin:/home/user/bin)
      8.  WARNING: nor OPENSEARCH_JAVA_HOME nor JAVA_HOME is set, will use 
      9.  ./hash.sh: line 35: java: command not found

      copy

    • Declare an environment variable when you invoke the script in order to avoid issues:

      1.  OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./hash.sh

      copy

    • Enter the desired password at the prompt and make a note of the output hash.

  3. Open internal_users.yml.

    1. sudo vi /etc/opensearch/opensearch-security/internal_users.yml

    copy

  4. Add a new internal user and replace the hash inside internal_users.yml with the output provided by hash.sh in step 2. The file should look similar to the following example:

    1. ---
    2. # This is the internal user database
    3. # The hash value is a bcrypt hash and can be generated with plugin/tools/hash.sh
    5. _meta:
    6.    type: "internalusers"
    7.    config_version: 2
    9. # Define your internal users here
    11. admin:
    12.    hash: "$2y$1EXAMPLEQqwS8TUcoEXAMPLEeZ3lEHvkEXAMPLERqjyh1icEXAMPLE."
    13.    reserved: true
    14.    backend_roles:
    15.    - "admin"
    16.    description: "Admin user"
    18. user1:
    19.    hash: "$2y$12$zoHpvTCRjjQr6h0PEaabueCaGam3/LDvT6rZZGDGMusD7oehQjw/O"
    20.    reserved: false
    21.    backend_roles: []
    22.    description: "New internal user"
    24. # Other users 
    25. ...

    copy

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.

    1. sudo systemctl restart opensearch

    copy

  2. Open a separate terminal session with the host and navigate to the directory containing securityadmin.sh.

    1. # Change to the correct directory
    2. cd /usr/share/opensearch/plugins/opensearch-security/tools

  3. Invoke the script. See Apply changes using securityadmin.sh for definitions of the arguments you must pass.

    1. # You can omit the environment variable if you declared this in your $PATH.
    2. 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

    copy

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.

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

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 Project downloads page.

Navigate to the directory containing the distribution and run the following command:

  1. sudo dpkg -i opensearch-2.13.0-linux-x64.deb

copy

APT-GET

To upgrade to the latest version of OpenSearch using apt-get:

  1. sudo apt-get upgrade opensearch

copy

You can also upgrade to a specific OpenSearch version:

  1. sudo apt-get upgrade opensearch=<version>

copy

Automatically restart the service after a package upgrade (2.13.0+)

To automatically restart OpenSearch after a package upgrade, enable the opensearch.service through systemd:

  1. sudo systemctl enable opensearch.service

copy