When running Elastic Agents in a restricted or closed network, you need to take extra steps to make sure:
- Kibana is able to reach the Elastic Package Registry to download package metadata and content.
- Elastic Agents are able to download binaries during upgrades.
See the Elastic Security Solution documentation for air-gapped offline endpoints.
When upgrading all the components in an air-gapped environment, it is recommended that you upgrade in the following order:
- Upgrade the Elastic Package Registry.
- Upgrade the Elastic Stack including Kibana.
- Upgrade the Elastic artifact registry and ensure the latest Elastic Agent binaries are available.
- Upgrade the on-premise Fleet Server.
- In Fleet, issue an upgrade for all the Elastic Agents.
Use a proxy server to access the Elastic Package Registryedit
By default Kibana downloads package metadata and content from the public Elastic Package Registry at epr.elastic.co.
If you can route traffic to the public endpoint of the Elastic Package Registry through a network gateway, set the following property in Kibana to use a proxy server:
For more information, refer to Using a proxy server with Elastic Agent and Fleet.
Host your own Elastic Package Registryedit
The Elastic Package Registry packages include signatures used in
package verification. By default, Fleet uses the Elastic
public GPG key to verify package signatures. If you ever need to change this GPG
key, use the
xpack.fleet.packageVerification.gpgKeyPath setting in
kibana.yml. For more information, refer to
If routing traffic through a proxy server is not an option, you can host your own Elastic Package Registry.
The Elastic Package Registry can be deployed and hosted onsite using one of the available Docker images. These docker images include the Elastic Package Registry and a selection of packages.
There are different distributions available:
docker.elastic.co/package-registry/distribution:8.11.4- Selection of packages from the production repository released with Elastic Stack 8.11.4.
docker.elastic.co/package-registry/distribution:lite-8.11.4- Subset of the most commonly used packages from the production repository released with Elastic Stack 8.11.4. This image is a good candidate to start using Fleet in air-gapped environments.
docker.elastic.co/package-registry/distribution:production- Packages available in the production registry (https://epr.elastic.co).
docker.elastic.co/package-registry/distribution:lite- Subset of the most commonly used packages available in the production registry (https://epr.elastic.co).
To update the distribution image, re-pull the image and then restart the docker container.
Every distribution contains packages that can be used by different versions of the Elastic Stack. The Elastic Package Registry API exposes a Kibana version constraint that allows for filtering packages that are compatible with a particular version.
These steps use the standard Docker CLI, but you can create a Kubernetes manifest based on this information. These images can also be used with other container runtimes compatible with Docker images.
Pull the Docker image from the public Docker registry:
docker pull docker.elastic.co/package-registry/distribution:8.11.4
Save the Docker image locally:
docker save -o package-registry-8.11.4.tar docker.elastic.co/package-registry/distribution:8.11.4
Check the image size to ensure that you have enough disk space.
Transfer the image to the air-gapped environment and load it:
docker load -i package-registry-8.11.4.tar
Run the Elastic Package Registry:
docker run -it -p 8080:8080 docker.elastic.co/package-registry/distribution:8.11.4
(Optional) You can monitor the health of your Elastic Package Registry with requests to the root path:
docker run -it -p 8080:8080 \ --health-cmd "curl -f -L http://127.0.0.1:8080/health" \ docker.elastic.co/package-registry/distribution:8.11.4
Connect Kibana to your hosted Elastic Package Registryedit
xpack.fleet.registryUrl property in the Kibana config to set the URL of
your hosted package registry. For example:
TLS configuration of the Elastic Package Registryedit
You can configure the Elastic Package Registry to listen on a secure HTTPS port using TLS.
For example, given a key and a certificate pair available in
can start the Elastic Package Registry listening on the 443 port using the following command:
docker run -it -p 443:443 \ -v /etc/ssl/package-registry.key:/etc/ssl/package-registry.key:ro \ -v /etc/ssl/package-registry.crt:/etc/ssl/package-registry.crt:ro \ -e EPR_ADDRESS=0.0.0.0:443 \ -e EPR_TLS_KEY=/etc/ssl/package-registry.key \ -e EPR_TLS_CERT=/etc/ssl/package-registry.crt \ docker.elastic.co/package-registry/distribution:8.11.4
Using custom CA certificatesedit
If you are using self-signed certificates or certificates issued by a custom Certificate Authority (CA), you need to set the file path to your CA in the
variable in the Kibana startup files.
Host your own artifact registry for binary downloadsedit
Elastic Agents must be able to access the Elastic artifact registry to download
binaries during upgrades. By default Elastic Agents download artifacts from
To make binaries available in an air-gapped environment, you can host your own custom artifact registry, and then configure Elastic Agents to download binaries from it.
Create a custom artifact registry in a location accessible to your Elastic Agents:
Download the latest release artifacts from the public Elastic artifact registry at
https://artifacts.elastic.co/downloads/. For example, the following cURL commands download all the artifacts that may be needed to upgrade Elastic Agents running on Linux x86_64. You may replace
arm64for the ARM64 version. The exact list depends on which integrations you’re using.
curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/auditbeat/auditbeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/heartbeat/heartbeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/osquerybeat/osquerybeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/cloudbeat/cloudbeat-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/endpoint-dev/endpoint-security-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/fleet-server/fleet-server-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-host-agent-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-host-agent-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-host-agent-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-collector-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-collector-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-collector-8.11.4-linux-x86_64.tar.gz.asc curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-symbolizer-8.11.4-linux-x86_64.tar.gz curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-symbolizer-8.11.4-linux-x86_64.tar.gz.sha512 curl -O https://artifacts.elastic.co/downloads/prodfiler/pf-elastic-symbolizer-8.11.4-linux-x86_64.tar.gz.asc
On your HTTP file server, group the artifacts into directories and sub-directories that follow the same convention used by the Elastic artifact registry:
endpoint-dev, and so on.
Make sure you have a plan or automation in place to update your artifact registry when new versions of Elastic Agent are available.
Add the agent binary download location to Fleet settings:
- In Kibana, go to Fleet → Settings.
- Under Agent Binary Download, click Add agent binary source to add the location of your artifact registry. For more detail about these settings, refer to Agent binary download settings. If you want all Elastic Agents to download binaries from this location, set it as the default.
If your artifact registry is not the default, edit your agent policies to override the default:
- Go to Fleet → Agent policies and click the policy name to edit it.
- Click Settings.
Under Agent Binary Download, select your artifact registry.
When you trigger an upgrade for any Elastic Agents enrolled in the policy, the binaries are downloaded from your artifact registry instead of the public repository.
Not using Fleet? For standalone Elastic Agents, you can set the binary download
agent.download.sourceURI in the
elastic-agent.yml file, or run the
elastic-agent upgrade command
--source-uri flag specified.