Elasticsearch on FreeBSD

Overview

This project is an unofficial port of Elasticsearch for FreeBSD systems. It was created to continue supporting Elasticsearch on FreeBSD after Elastic introduced NativeAccess in 8.16, making it difficult to run ES without additional source code modifications.

The following table lists the actively maintained releases on this repository. These versions are tested & supported on FreeBSD 14.3, and presumed to work on 13.5 and 15.x.

ES	Branch	Bugzilla
8.19	Link	Link
9.1	Link	Link
9.2	Link	Link

Installation

The recommended way to install Elasticsearch is by using the port makefile. Since this project's port is not included in the official FreeBSD package repositories or ports index, one can create a local repository and install from there. Currently, a new port makefile is posted on the FreeBSD Bugzilla entry page as new Elasticsearch versions are released.

Warning

If you are upgrading an existing Elasticsearch instance to version 9.x, you MUST upgrade to 8.19 first! Read the official documentation for additional info.

New installations

If you are upgrading from a previous version (e.g. 8.11.3) then skip to the upgrading section below. Replace the XXXXXX attachment ID in the fetch URL below with the latest version available on the relevant Bugzilla page.

mkdir /usr/local/ports
cd /usr/local/ports
fetch "https://bugs.freebsd.org/bugzilla/attachment.cgi?id=XXXXXX" -o /usr/local/ports/elasticsearch-8.19.7.tar.gz
tar xvf elasticsearch-8.19.7.tar.gz
cd textproc/elasticsearch8
make install clean
sysrc elasticsearch_enable="YES"
service elasticsearch start

Upgrading existing installations

This method can upgrade older versions of Elasticsearch, such as the outdated one found in the FreeBSD Ports index. It is highly recommended to read the official upgrade documentation before proceeding.

Warning

If you are upgrading an existing Elasticsearch instance to version 9.x, you MUST upgrade to 8.19 first! Read the official documentation for additional info.

Replace the XXXXXX attachment ID in the fetch URL below with the latest version available on the relevant Bugzilla page.

mkdir /usr/local/ports
cd /usr/local/ports
fetch "https://bugs.freebsd.org/bugzilla/attachment.cgi?id=XXXXXX" -o /usr/local/ports/elasticsearch-8.19.7.tar.gz
tar xvf elasticsearch-8.19.7.tar.gz
cd textproc/elasticsearch8
make reinstall clean

Update /usr/local/etc/elasticsearch/jvm.options by adding the following entries at the bottom of the file:

-Des.nativelibs.path=/usr/local/lib
-Dorg.elasticsearch.nativeaccess.enableVectorLibrary=false

Next, ensure Elasticsearch is configured to use OpenJDK 21 by modifying /etc/rc.conf:

elasticsearch_java_home="/usr/local/openjdk21"

Finally, start the service:

service elasticsearch start

Building

Building Elasticsearch is fairly straightforward. A FreeBSD-specific archive can be built on any operating system thanks to Java's cross-compilation capabilities. Building the vector library natively requires a FreeBSD host.

Prerequisites

Install the necessary JDKs and other build dependencies to compile and run Elasticsearch.

Note

As of 2025-11-10, OpenJDK 25 is only available on the FreeBSD latest pkg repo.

pkg install bash curl protobuf gcc13 java/openjdk17 java/openjdk19 java/openjdk20 java/openjdk21 java/openjdk22 java/openjdk23 java/openjdk25

Clone this repository by either checking out a release branch such as freebsd-8.19 or a specific tag, e.g. 8.19.7:

git clone --depth 1 --branch v8.19.7 https://github.com/portsbuild/elasticsearch elasticsearch-8.19.7
cd elasticsearch-8.19.7

Set the default JDK to 25 and begin the build:

export RUNTIME_JAVA_HOME=/usr/local/openjdk25
export JAVA_TOOLCHAIN_HOME=/usr/local/openjdk25
./gradlew distribution:archives:freebsd-tar:assemble -D"build.snapshot=false" -D"license.key=public.key" -Porg.gradle.java.installations.paths=/usr/local/openjdk17,/usr/local/openjdk19,/usr/local/openjdk20,/usr/local/openjdk21,/usr/local/openjdk22,/usr/local/openjdk23,/usr/local/openjdk25

A distribution archive will be created in the following folder:

distribution/archives/freebsd-tar/build/distributions/elasticsearch-8.19.7-freebsd-x86_64.tar.gz

Building the vector library

Compiling the vector library is simple. From the root of the repository:

export LOCAL_VEC_BINARY_OS=freebsd
./gradlew buildSharedLibraryAndCopy

Next, copy libvec.so to /usr/local/lib:

cp libs/native/libraries/build/platform/freebsd-x64/libvec.so /usr/local/lib/

Finally, set enableVectorLibrary to true in jvm.options and (re)start Elasticsearch:

-Dorg.elasticsearch.nativeaccess.enableVectorLibrary=true

service elasticsearch (re)start

Testing

A separate branch has been created to maintain FreeBSD tests. The decision to keep the tests separate was to avoid cluttering up the release branches. This also eases keeping track of changes between releases.

To run the full suite of tests, switch over to the freebsd-tests branch and type:

export RUNTIME_JAVA_HOME=/usr/local/openjdk25
export JAVA_TOOLCHAIN_HOME=/usr/local/openjdk25
./gradlew test -D"tests.haltonfailure=false" -D"build.snapshot=false" -D"license.key=public.key" -D"run.license_type=trial" -Porg.gradle.java.installations.paths=/usr/local/openjdk17,/usr/local/openjdk19,/usr/local/openjdk20,/usr/local/openjdk21,/usr/local/openjdk22,/usr/local/openjdk23,/usr/local/openjdk25

For the vector library benchmarks, a copy of libzstd.so and libvec.so (see build instructions) are required.

## From the repository root:
mkdir -p libs/native/libraries/build/platform/freebsd-x64
cp libs/vec/shared/amd64/libvec.so libs/native/libraries/build/platform/freebsd-x64/
cp /usr/local/lib/libzstd.so libs/native/libraries/build/platform/freebsd-x64/
export RUNTIME_JAVA_HOME=/usr/local/openjdk25
export JAVA_TOOLCHAIN_HOME=/usr/local/openjdk25
./gradlew -p benchmarks run --args 'Int7uScorerBenchmark' -Porg.gradle.java.installations.paths=/usr/local/openjdk17,/usr/local/openjdk19,/usr/local/openjdk20,/usr/local/openjdk21,/usr/local/openjdk22,/usr/local/openjdk23,/usr/local/openjdk25 -D"--enable-native-access=ALL-UNNAMED"

Kibana, Logstash & Beats

Administrators may be interested in the following related components when running the ELK stack:

• Kibana 8.19
• Beats 8.19
• Logstash 8.19

Support

For technical assistance or to report a bug, please create a GitHub Issue.

Misc.

The original Elasticsearch README is also available.