:plugin: zeromq
:type: input
:default_codec: json

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}s-{plugin}"]

=== Zeromq input plugin

include::{include_path}/plugin_header.asciidoc[]

==== Description

Read events over a 0MQ SUB socket.

You need to have the 0mq 2.1.x library installed to be able to use
this input plugin.

The default settings will create a subscriber binding to `tcp://127.0.0.1:2120`
waiting for connecting publishers.


[id="plugins-{type}s-{plugin}-options"]
==== Zeromq Input Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-address>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-mode>> |<<string,string>>, one of `["server", "client"]`|No
| <<plugins-{type}s-{plugin}-sender>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-sockopt>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-topic>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-topic_field>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-topology>> |<<string,string>>, one of `["pushpull", "pubsub", "pair"]`|Yes
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
input plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-address"]
===== `address` 

  * Value type is <<array,array>>
  * Default value is `["tcp://*:2120"]`

0mq socket address to connect or bind
Please note that `inproc://` will not work with logstash
as each we use a context per thread.
By default, inputs bind/listen
and outputs connect

[id="plugins-{type}s-{plugin}-mode"]
===== `mode` 

  * Value can be any of: `server`, `client`
  * Default value is `"server"`

mode
server mode binds/listens
client mode connects

[id="plugins-{type}s-{plugin}-sender"]
===== `sender` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

sender
overrides the sender to
set the source of the event
default is `zmq+topology://type/`

[id="plugins-{type}s-{plugin}-sockopt"]
===== `sockopt` 

  * Value type is <<hash,hash>>
  * Default value is `{"ZMQ::RCVTIMEO"=>"1000"}`

0mq socket options
This exposes `zmq_setsockopt`
for advanced tuning
see http://api.zeromq.org/2-1:zmq-setsockopt for details

This is where you would set values like:

 * `ZMQ::HWM` - high water mark
 * `ZMQ::IDENTITY` - named queues
 * `ZMQ::SWAP_SIZE` - space for disk overflow

Example:
[source,ruby]
    sockopt => {
       "ZMQ::HWM" => 50
       "ZMQ::IDENTITY"  => "my_named_queue"
    }

defaults to: `sockopt => { "ZMQ::RCVTIMEO" => "1000" }`, which has the effect of "interrupting"
the recv operation at least once every second to allow for properly shutdown handling.

[id="plugins-{type}s-{plugin}-topic"]
===== `topic` 

  * Value type is <<array,array>>
  * There is no default value for this setting.

0mq topic
This is used for the `pubsub` topology only
On inputs, this allows you to filter messages by topic
On outputs, this allows you to tag a message for routing
NOTE: ZeroMQ does subscriber side filtering.
NOTE: All topics have an implicit wildcard at the end
You can specify multiple topics here

[id="plugins-{type}s-{plugin}-topic_field"]
===== `topic_field` 

  * Value type is <<string,string>>
  * Default value is `"topic"`

Event topic field
This is used for the `pubsub` topology only
When a message is received on a topic, the topic name on which
the message was received will saved in this field.

[id="plugins-{type}s-{plugin}-topology"]
===== `topology` 

  * This is a required setting.
  * Value can be any of: `pushpull`, `pubsub`, `pair`
  * There is no default value for this setting.

0mq topology
The default logstash topologies work as follows:

* pushpull - inputs are pull, outputs are push
* pubsub - inputs are subscribers, outputs are publishers
* pair - inputs are clients, inputs are servers

If the predefined topology flows don't work for you,
you can change the `mode` setting



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!: