Link Search Menu Expand Document Documentation Menu
Documentation

You're viewing version 3.8 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Installing OpenSearch Dashboards (Debian)

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

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.

Installing OpenSearch Dashboards 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 using dpkg.

    x64:

    sudo dpkg -i opensearch-dashboards-3.8.0-linux-x64.deb

    arm64:

    sudo dpkg -i opensearch-dashboards-3.8.0-linux-arm64.deb

    For new installations of OpenSearch Dashboards 3.7 and later, you can use the following environment variable to control the Security Dashboards plugin behavior:

    DISABLE_SECURITY_DASHBOARDS_PLUGIN=true

  3. After the installation completes, reload the systemd manager configuration: 
     sudo systemctl daemon-reload

  4. Enable OpenSearch Dashboards as a service: 
     sudo systemctl enable opensearch-dashboards

  5. Start the OpenSearch Dashboards service: 
     sudo systemctl start opensearch-dashboards

  6. Verify that OpenSearch Dashboards launched correctly: 
     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: 
    curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.8.0/opensearch-dashboards-3.8.0-linux-x64.deb

  2. Download the corresponding signature file: 
    curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.8.0/opensearch-dashboards-3.8.0-linux-x64.deb.sig

  3. Download and import the GPG key: 
    curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | gpg --import -

  4. Verify the signature: 
    gpg --verify opensearch-dashboards-3.8.0-linux-x64.deb.sig opensearch-dashboards-3.8.0-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. Install the necessary packages: 
    sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2

  2. Create the keyrings directory if it doesn’t already exist: 
    sudo mkdir -p /etc/apt/keyrings

  3. Import the public GPG key. This key is used to verify that the APT repository is signed. 
     curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | sudo gpg --dearmor --batch --yes -o /etc/apt/keyrings/opensearch-release-keyring

  4. Create an APT repository for OpenSearch Dashboards: 
    echo "deb [signed-by=/etc/apt/keyrings/opensearch-release-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-dashboards-3.x.list

  5. Verify that the repository was created successfully: 
     sudo apt-get update

  6. (Optional) As of May 22, 2024, the Origin and Label values of the APT repository were updated as part of this change. If you created the APT repository before this date, run the following command to accept the updated release information: 
     sudo apt-get update --allow-releaseinfo-change

  7. With the repository information added, list all available versions of OpenSearch Dashboards: 
    sudo apt list -a opensearch-dashboards

  8. Choose the version of OpenSearch Dashboards you want to install:
    • Unless otherwise indicated, the latest available version of OpenSearch Dashboards is installed: 
      sudo apt-get install opensearch-dashboards

    • To install a specific version of OpenSearch Dashboards, pass a version number after the package name: 
      sudo apt-get install opensearch-dashboards=3.8.0

  9. Once complete, enable OpenSearch Dashboards: 
     sudo systemctl enable opensearch-dashboards

  10. Start OpenSearch Dashboards: 
     sudo systemctl start opensearch-dashboards

  11. Verify that OpenSearch Dashboards launched correctly: 
     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: 
     sudo vi /etc/opensearch-dashboards/opensearch_dashboards.yml

  2. Specify a network interface that OpenSearch Dashboards should bind to. Use 0.0.0.0 to bind to any available interface: 
     server.host: 0.0.0.0

  3. Save and quit.
  4. Restart OpenSearch Dashboards to apply the configuration change: 
     sudo systemctl restart opensearch-dashboards

  5. From a web browser, navigate to OpenSearch Dashboards. The default port is 5601.
  6. Log in with the default username admin and the default password admin. (For OpenSearch 2.12 and later, the password should be the custom admin password)
  7. Visit Getting started with OpenSearch Dashboards to learn more.

Upgrade to a newer version

OpenSearch Dashboards instances installed using dpkg or apt-get can be upgraded to a newer version.

Upgrade your OpenSearch cluster before you upgrade OpenSearch Dashboards. OpenSearch Dashboards must run the same version as the cluster it connects to, and installed plugins must match that version. For more information, see Plugin compatibility.

Prepare the host for an upgrade

The opensearch-dashboards package declares no dependencies on other Debian packages. An upgrade that fails with unresolved dependencies therefore points to the APT configuration on the host rather than to OpenSearch Dashboards itself. Complete the following steps before you run an upgrade command.

  1. Install the packages that APT needs in order to read the OpenSearch Dashboards repository over HTTPS: 
    sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2

  2. Back up your configuration. The package registers the following files as configuration files, and dpkg prompts you to keep or replace each one that you edited:

    • /etc/opensearch-dashboards/opensearch_dashboards.yml
    • /etc/opensearch-dashboards/node.options
    • /etc/default/opensearch-dashboards
    • /etc/init.d/opensearch-dashboards

    To back up the main configuration file, run the following command:

    sudo cp /etc/opensearch-dashboards/opensearch_dashboards.yml /etc/opensearch-dashboards/opensearch_dashboards.yml.bak

    Run the upgrade from an interactive shell so that you can respond to these prompts. An unattended upgrade either stops at the prompt or applies the default answer configured in Dpkg::Options on the host.

  3. Refresh the package lists and confirm that a newer version is available: 
    sudo apt-get update && sudo apt list -a opensearch-dashboards

    If apt-get update reports that a public key is unavailable, or if the newest version listed is the version that you already have, see Upgrade across major versions.

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:

sudo dpkg -i opensearch-dashboards-3.8.0-linux-x64.deb

This method reads the package file directly and does not use an APT repository, so it also upgrades across major versions.

APT-GET

To upgrade to the newest available version of OpenSearch Dashboards, run the following command:

sudo apt-get install --only-upgrade opensearch-dashboards

You can also upgrade to a specific OpenSearch Dashboards version by providing the version number:

sudo apt-get install opensearch-dashboards=<version>

The apt-get upgrade subcommand acts on every installed package on the host and cannot install or remove packages, so an unrelated package that APT holds back stops the OpenSearch Dashboards upgrade. The --only-upgrade option limits the operation to the opensearch-dashboards package.

Upgrade across major versions

The repository definition that you create during installation is pinned to one major version, so APT reports no newer version when you try to move to a different major version. The repositories for different major versions are also signed with different GPG keys, so APT reports a missing public key when it reads the new repository using your existing keyring.

  1. Import the public GPG key for the new repository: 
    curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | sudo gpg --dearmor --batch --yes -o /etc/apt/keyrings/opensearch-release-keyring

    Repositories for OpenSearch Dashboards 2.x are signed with the key published at https://artifacts.opensearch.org/publickeys/opensearch.pgp. Leave the keyring for that key in place until you remove the 2.x repository definition. Otherwise, apt-get update fails while reading the 2.x repository.

  2. Add the repository for the new major version: 
    echo "deb [signed-by=/etc/apt/keyrings/opensearch-release-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-dashboards-3.x.list

  3. Remove the repository definition for your previous major version, replacing <previous-major-version> with a value such as 2.x: 
    sudo rm /etc/apt/sources.list.d/opensearch-dashboards-<previous-major-version>.list

  4. Refresh the package lists and confirm that the new version appears: 
    sudo apt-get update && sudo apt list -a opensearch-dashboards

  5. Install the new version: 
    sudo apt-get install opensearch-dashboards=<version>

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

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

sudo systemctl enable opensearch-dashboards.service

350 characters left

Have a question? .

Want to contribute? or .