Enable authentication for Edge Processor package downloads

Reinstall existing Edge Processor instances and enable authenticated package downloads in supported Splunk Enterprise 10.0, 10.2, and 10.4 maintenance releases.

This procedure applies to Splunk Enterprise deployments that run Edge Processors on customer-managed hosts. It does not apply to Splunk Cloud Platform deployments that download packages from the Splunk Cloud package distribution service.

Before you begin, create an inventory of every Edge Processor instance in the deployment and track each instance as you reinstall and verify it.

Make sure that you have the admin role in Splunk Enterprise and administrative access to each instance host.

Supported maintenance releases for Splunk Enterprise 10.0, 10.2, and 10.4 include optional authentication for Edge Processor package downloads. Enabling this setting provides additional security for packages downloaded from Splunk Enterprise to Edge Processor instances.

Package download authentication is inactive by default in these releases. There is no migration deadline, and enabling the setting is optional.

CAUTION: Before you enable package download authentication, reinstall every existing Edge Processor instance using the installation commands from a supported maintenance release that includes this feature. Otherwise, an instance might fail the next time it automatically restarts or downloads an update, interrupting data ingestion and potentially causing data loss.

For a new deployment, you can enable authentication before installing your first Edge Processor instances. For an existing deployment, upgrade Splunk Enterprise and reinstall every existing instance before enabling authentication.

Why a full reinstallation is required

Each instance includes an Edge Processor component that starts the instance and downloads required software packages. This component cannot update itself, and older versions cannot authenticate package download requests.

Fully uninstalling and reinstalling an instance using installation commands generated after the Splunk Enterprise upgrade replaces the component with a version that supports authentication. Restarting the instance or waiting for an automatic software update does not complete this preparation.

Before you begin

Plan a rolling reinstallation

An Edge Processor is a logical group that can have one or more instances. Each standalone instance runs on a separate host. If an Edge Processor has multiple instances, you can reinstall them in batches while the remaining instances continue to process data.

Before taking an instance offline:

  • Confirm that the remaining instances are Healthy and can process incoming data.
  • Confirm how upstream senders or load balancers can stop routing data to an offline instance and fail over to the remaining instances.
  • Determine the minimum number of instances required to handle peak traffic. This number is your capacity floor.

Calculate the maximum batch size as follows:

CODE 
maximum instances offline = total instances - capacity floor

For example, if an Edge Processor has 10 instances and requires 8 instances to handle peak traffic, reinstall no more than 2 instances at a time.

For a single-instance Edge Processor, add a second instance to the same Edge Processor and confirm that it is Healthy and receiving traffic before removing the original instance. If you cannot add temporary capacity, schedule an ingestion interruption and account for the buffering and delivery behavior of each upstream sender.

Review the failover and buffering behavior of each upstream sender. Splunk forwarders must have another available target and sufficient queue capacity. HEC and syslog senders require a resilient client configuration or load balancer. UDP does not guarantee delivery, so provide another collection path or minimize the interruption.

  1. Select a batch of existing instances from your inventory without exceeding the maximum number of instances that can be offline.
    For a single-instance deployment, first add an updated instance to the same Edge Processor or schedule an ingestion interruption, as described in the Plan a rolling reinstallation section above.
  2. Remove the instances from active traffic. Stop upstream senders or reconfigure them to send data to other instances. Verify that no data is being sent to the instances that you plan to reinstall.
  3. CAUTION: Taking an instance offline while it is still receiving data can discard data held in memory or persistent queues.
    Fully uninstall each selected instance using the uninstallation command provided in the Edge Processor service.
    1. On the Edge Processors page, open the Edge Processor that contains the instance.
    2. Select Manage instances, then select the Install/uninstall tab.
    3. Expand Step 1: Run commands to install/uninstall instances.
    4. Select Uninstall, and then select Copy to clipboard.
    5. On the instance host, open a command-line interface and run the copied command.
    If systemd manages the splunk-edge service, follow Manage and uninstall Edge Processors for version 10.0, version 10.2, or version 10.4 for the supported commands and verification steps.
  4. Confirm that uninstallation is complete before reinstalling.
    • Confirm that the instance no longer appears in the instances table.
    • Verify that the splunk-edge process or service is no longer running on the host.
    • Verify that no sender or load balancer is routing data to the instance.

    Do not delete the logical Edge Processor. The reinstalled instance must join the same Edge Processor so that it receives the same pipelines and shared configuration.

  5. Install the updated instance into the same logical Edge Processor.
    1. On the Edge Processors page, open the same Edge Processor.
    2. Select Manage instances, then select the Install/uninstall tab.
    3. Expand Step 1: Run commands to install/uninstall instances.
    4. Select Install, and then select Copy to clipboard.
    5. On the instance host, open a command-line interface and run the copied installation command.
    Always generate a new installation command after upgrading Splunk Enterprise. Do not reuse a command saved before the upgrade or from a previous installation attempt.
  6. Confirm that the instance returned to service.
    • Confirm that the instance appears in the instances table.
    • Confirm that its status is Healthy.
    • Confirm that load balancer health checks have returned it to active rotation, when applicable.
    • Confirm that data is flowing through the instance's pipelines as expected.

    Observe the instance for a stabilization period appropriate for your environment before starting the next batch.

  7. Mark the instance as complete in your inventory, then repeat the reinstallation process until every instance that existed before the Splunk Enterprise upgrade has been reinstalled and verified.
    Do not enable package download authentication until the checklist is complete.

The required preparation is complete when every existing Edge Processor instance is reinstalled and verified. Enabling authentication is optional.

Enable package download authentication

CAUTION: Enabling authentication while an affected instance remains can prevent that instance from downloading or restarting required software. Data ingestion through the instance can stop and might result in data loss.

After you reinstall and verify all existing instances, you can optionally enable package download authentication. Choose one of these methods.

  1. Enable authentication from the first-time setup page.

    1. In Splunk Web, open the Splunk Pipeline Builders app.

    2. Navigate directly to the app's setup page by appending /setup to the app URL. For example:

      CODE 
      https://<splunk-web-host>:<port>/<locale>/app/splunk_pipeline_builders/setup
    3. Under Authentication for Edge Processor package downloads, turn on Authentication required.
    4. Select Save.
    5. When prompted, restart Splunk Enterprise to apply the change.

  2. Enable authentication in restmap.conf.

    1. Create or update $SPLUNK_HOME/etc/apps/splunk_pipeline_builders/local/restmap.conf.

    2. Add the following stanza and setting:

      CODE 
      [script:edge-binary-server]
requireAuthentication = true
    3. Restart Splunk Enterprise to apply the change.

Verify package download authentication

After you complete the required reinstallation and any optional authentication change, confirm the following:

  • Your inventory shows that every instance that existed before the Splunk Enterprise upgrade was reinstalled and verified.
  • No affected instance is labeled Needs reinstallation.
  • Every Edge Processor instance is Healthy, and data continues to flow through all associated pipelines.
  • If you enabled authentication, confirm that Authentication required is enabled.
  • If you left authentication inactive, confirm that it remains inactive.

Troubleshoot package download authentication

If a reinstalled instance does not become Healthy, complete these checks:

  1. Confirm that the host can connect to the Splunk management port and that intervening proxies or firewalls allow the connection.
  2. Generate new installation commands from the Install/uninstall tab and try the installation again. Do not reuse commands from a previous attempt.
  3. Review the instance logs for Edge Processor component, package download, or authentication errors.
  4. Confirm that the instance was installed into the intended logical Edge Processor.
  5. Contact Splunk Support if the problem continues.

If you enabled authentication before updating every instance, set requireAuthentication to false in the app-local restmap.conf file, then restart Splunk Enterprise. This restores unauthenticated package downloads but does not update affected instances. Complete the reinstallation before enabling authentication again.