Skip to content

Troubleshoot the Sekoia.io Forwarder

Use this procedure when the Sekoia.io Forwarder is not receiving events, does not forward events, or fails to start. Check the local configuration and input traffic first, then verify the connection to the Sekoia regional endpoint.

Prerequisites

Before you start, make sure that:

  • You have access to the forwarder host with sudo privileges.
  • You can read docker-compose.yml and intakes.yaml.
  • You know the source IP address, destination port, and protocol used by the affected log source.

Check the forwarder version

Sekoia releases new forwarder images regularly. Check the image tag in docker-compose.yml and compare it with the available versions in the GitHub Container Registry.

Check that the forwarder receives events

  1. Enable debug logging for the affected intake in intakes.yaml:

    - name: Techno2
  protocol: tcp
  port: 20517
  intake_key: INTAKE_KEY_FOR_TECHNO_2
  debug: True

  2. Recreate the container:

    sudo docker compose down
sudo docker compose up -d

  3. Stream logs for the affected intake:

    sudo docker compose logs -f | grep "YOUR_INTAKE_KEY"

If no events appear, check the following:

  • intakes.yaml declares the protocol and port used by the source.
  • The same port is exposed in the ports section of docker-compose.yml. For example, a port range from 25020 to 25023 requires at least "25020-25023:25020-25023".
  • A firewall allows traffic from the log source to the forwarder.
  • The source sends events to the correct forwarder IP address and port.

To check whether traffic reaches the host, run:

sudo tcpdump -c 10 -nn src <remote_ip> -vv

Disable debug logging after testing.

Check for malformed Syslog messages

The Forwarder may receive an event but parse it incorrectly when the source sends an invalid or unexpected Syslog header. In this case, part of the message payload may be interpreted as the Syslog header, and the event may appear with a warning or error status.

  1. Temporarily enable debug logging for the affected intake in intakes.yaml:

    - name: Techno2
  protocol: tcp
  port: 20517
  intake_key: INTAKE_KEY_FOR_TECHNO_2
  debug: True

  2. Recreate the container and inspect the input and output logs:

    sudo docker compose down
sudo docker compose up -d
sudo docker compose logs -f

  3. Compare the message received in the [Input INTAKE_KEY] log with the message sent in the [Output INTAKE_KEY] log.

  4. In Sekoia.io, inspect the native Syslog fields of the event and compare them with the original message generated by the source.

  5. If the Syslog header is malformed, update the source configuration to generate a valid RFC 3164 or RFC 5424 message, then disable debug logging after testing.

Note

If the source sends JSON or another structured payload, make sure that the payload is not inserted into the Syslog header. The payload should remain in the message body.

Check connectivity to Sekoia

  1. Confirm that the intake key in intakes.yaml is correct.

  2. Test the outbound connection to the regional endpoint:

    sudo apt install telnet
telnet intake.sekoia.io 10514

  3. Confirm that a successful connection returns:

    Connected to intake.sekoia.io.
Escape character is '^]'.

  4. Remove Telnet after testing:

    sudo apt remove telnet

  5. Check the Sekoia status page.

Use the endpoint for your region

Replace intake.sekoia.io with the regional host configured by REGION when you test a non-FRA1 deployment.

Check container logs

View all logs:

sudo docker compose logs

Stream logs while reproducing the issue:

sudo docker compose logs -f

Check the container status:

sudo docker compose ps

If the container fails after you add a custom rsyslog file, see Route multiple technologies through one port for syntax and listener checks.

Result

You have identified whether the problem is caused by the source configuration, the forwarder's port mapping, a firewall, an intake key, or the outbound connection to Sekoia.