How to configure a Logstash UDP input

Centralizing logs from network devices and appliances is often easiest over UDP, especially when the sender only supports datagram-based syslog or needs minimal connection overhead.

In Logstash, the udp input plugin binds a UDP socket to a local host and port and turns each received datagram into a single event. On common package installs, pipeline snippets under /etc/logstash/conf.d are combined into a single pipeline, so a UDP listener can be added as a standalone file.

Commands assume a Logstash package install on Linux using /etc/logstash for settings and a systemd-managed logstash service. UDP delivery is best-effort, so packets can be dropped, duplicated, or received out of order during congestion, and untrusted sources can inject spoofed events into an exposed listener.

1. Pick an unprivileged UDP port for the input listener.

   Ports below 1024 (for example syslog UDP 514) are privileged and can prevent Logstash from starting when the service runs as a non-root user.

   Restrict access to the UDP port with firewall rules or security groups to reduce unauthenticated log injection.

2. Confirm nothing is already listening on UDP port 5515.

   $ sudo ss -lnup | grep -F ':5515'

   No output indicates the port is free.

3. Create a pipeline configuration file at /etc/logstash/conf.d/27-udp-input.conf.

   input {
     udp {
       host => "0.0.0.0"
       port => 5515
       codec => json
     }
   }
   
   output {
     elasticsearch {
       hosts => ["http://elasticsearch.example.net:9200"]
       index => "udp-events-%{+YYYY.MM.dd}"
     }
   }

   Set codec to plain for raw text payloads, and set host to a specific local address to limit exposed interfaces.

4. Test the pipeline configuration for syntax errors.

   $ sudo /usr/share/logstash/bin/logstash --path.settings /etc/logstash --config.test_and_exit
   ##### snipped #####
   Configuration OK

   Related: How to test a Logstash pipeline configuration

5. Restart the Logstash service to apply the pipeline changes.

   $ sudo systemctl restart logstash

   Related: How to manage the Logstash service with systemctl in Linux

6. Verify Logstash is listening on UDP port 5515.

   $ sudo ss -lnup | grep -F ':5515'
   UNCONN 0      0            0.0.0.0:5515       0.0.0.0:*    users:(("java",pid=21792,fd=98))

7. Send a test JSON datagram to UDP port 5515.

   $ printf '{"message":"udp-smoke-test","source":"nc"}\n' | nc -u -w 1 127.0.0.1 5515

   Use the listener IP instead of 127.0.0.1 when testing from a remote sender.

8. Confirm the test event is indexed in Elasticsearch.

   $ curl -s 'http://elasticsearch.example.net:9200/udp-events-*/_search?q=message:udp-smoke-test&size=1&pretty'
   {
     "took" : 27,
     "timed_out" : false,
     "_shards" : {
       "total" : 1,
       "successful" : 1,
       "skipped" : 0,
       "failed" : 0
     },
     "hits" : {
       "total" : {
         "value" : 11,
         "relation" : "eq"
       },
       "max_score" : 18.778297,
       "hits" : [
         {
           "_index" : "udp-events-2026.01.07",
           "_id" : "t9VFmJsBMfcBipKWQNEj",
           "_score" : 18.778297,
           "_source" : {
             "event" : {
               "original" : "{\"message\":\"udp-smoke-test\",\"source\":\"nc\"}\n"
             },
             "source" : "nc",
             "@version" : "1",
             "host" : {
               "ip" : "127.0.0.1"
             },
             "@timestamp" : "2026-01-07T11:43:53.688278794Z",
             "message" : "udp-smoke-test",
             "ingest_source" : "beats"
           }
         }
       ]
     }
   }