logstash-input-jms 3.0.6-java → 3.1.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e0b7da08d783aaa34842119cb780c5f52b00483b09c652d779da9c1f1ba24d0
-  data.tar.gz: 4c96668a804e020bb50c57fd6258cf4cfddb136fc0fde1ff81f8dbdc95dca74b
+  metadata.gz: 0c67e7b1c2a2cdef01628e322b3d7e7f2b0d569354c4284b667b30ed9ca874d5
+  data.tar.gz: 10f7a99686215d53cd59145a898c0b931763eca6ff20d5a4cd82ababde5b65ba
 SHA512:
-  metadata.gz: 9261b580965f2c5f0ba2ad29966ef9a47b2302652da035c6f917c81742c02954ac05cf49a0d164a6740f704e93448b6e388f5c9004fbfd6af1ad490eff2a6929
-  data.tar.gz: 0ddc3508282986ea0ffec41e4a49b07ba6f24a7ea7b2ee67b043370442190130ed92b3f47bf3f77f89bcecea0f14c9485b8377e9a33796eaafb8b9f702d107cf
+  metadata.gz: 9fb991ca333e90e0900d36ddac2c299e46805f911d8a3f357a3794bcbab74638d7e63496bb35bb18f4ea7940a266336ab88082193a8f554b87b552c3ea6df17a
+  data.tar.gz: 0e86a615ad62ddc0a9a59d228debdc62cbb2e31f0994146754fc015e9c6cafa828873b462fcd3eaf970902fa2760ec193f9fa92ee5279fdf3d5bb5f7f1d7844e

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 3.1.0
+ - Added many improvements to plugin [#35](https://github.com/logstash-plugins/logstash-input-jms/pull/35), including:  
+   - Added support for TLS
+   - Added support for durable subscriptions
+   - Added support to skip processing of specified headers and properties
+   - Added Integration tests
+   - Added support for specifying system and connection factory settings in configuration
+   - Improved error handling and reporting
+   - Deprecated confusing runner settings, and simplified code.
+   - Improved unit test coverage
+   - Improved documentation with sample configurations and a basic troubleshooting guide
+
 ## 3.0.6
   - Fixed formatting issues in documentation [#32](https://github.com/logstash-plugins/logstash-input-jms/pull/32) and [#33](https://github.com/logstash-plugins/logstash-input-jms/pull/33]
 

data/docs/index.asciidoc

@@ -23,24 +23,318 @@ include::{include_path}/plugin_header.asciidoc[]
 
 Read events from a Jms Broker. Supports both Jms Queues and Topics.
 
-For more information about Jms, see <http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html>.
+For more information about Jms, see <https://javaee.github.io/tutorial/jms-concepts.html>.
 For more information about the Ruby Gem used, see <http://github.com/reidmorrison/jruby-jms>.
-Here is a config example to pull from a queue:
 
+
+JMS configurations can be done either entirely in the Logstash configuration file, or in a mixture of the Logstash
+  configuration file, and a specified yaml file. Simple configurations that do not need to make calls to implementation
+  specific methods on the connection factory can be specified entirely in the Logstash configuration, whereas more complex
+  configurations, should also use the combination of yaml file and Logstash configuration.
+
+
+
+==== Sample Configuration using Logstash Configuration Only
+
+
+Configurations can be configured either entirely in Logstash configuration, or via a combination of Logstash configuration
+and yaml file, which can be useful for sharing similar configurations across multiple inputs and outputs.
+The JMS plugin can also be configured using JNDI if desired.
+
+===== Logstash Confuguration for Non-JNDI Connection
 [source,ruby]
-----
- jms {
-    include_header => false
-    include_properties => false
-    include_body => true
-    use_jms_timestamp => false
-    interval => 10
-    destination => "myqueue"
-    pub-sub => false
-    yaml_file => "~/jms.yml"
-    yaml_section => "mybroker"
+--------------------------------------------------
+ input
+ {
+    jms {
+        broker_url => 'failover:(tcp://host1:61616,tcp://host2:61616)?initialReconnectDelay=100' <1>
+        destination => 'myqueue' <2>
+        factory => 'org.apache.activemq.ActiveMQConnectionFactory' <3>
+        pub_sub => false <4>
+        use_jms_timestamp => false <5>
+        # JMS provider credentials if needed <6>
+        username => 'username'
+        password => 'secret'
+        # JMS provider keystore and truststore details <7>
+        keystore => '/Users/logstash-user/security/keystore.jks'
+        keystore_password => 'another_secret'
+        truststore => '/Users/logstash-user/security/truststore.jks'
+        truststore_password => 'yet_another_secret'
+        # Parts of the JMS message to be included <8>
+        include_header => false
+        include_properties => false
+        include_body => true
+        # Message selector
+        selector => "string_property = 'this' OR int_property < 3" <9>
+        # Connection factory specific settings
+        factory_settings => { <10>
+                              exclusive_consumer => true
+        }
+        # Jar Files to include
+        require_jars => ['/usr/share/jms/activemq-all-5.15.9.jar'] <11>
+    }
   }
-----
+--------------------------------------------------
+
+<1> Url of the broker to connect to. Please consult your JMS provider documentation for the exact syntax to use
+    here, including how to enable failover.
+<2> Name of the topic or queue that the plugin will listen to events from.
+<3> Full name (including package name) of Java connection factory used to create a connection with your JMS provider.
+<4> Determines whether the event source is a queue or a topic, set to `true` for topic, `false` for queue.
+<5> Determines whether the JMSTimestamp header is used to populate the `@timestamp` field.
+<6> Credentials to use when connecting to the JMS provider, if required.
+<7> Keystore and Truststore to use when connecting to the JMS provider, if required.
+<8> Parts of the JMS Message to include in the event - headers, properties and the message body can be included or
+    excluded from the event.
+
+<9> Message selector: Use this to filter messages to be processed. The whole selector query should be double-quoted,
+    string property values should be single quoted, and numeric property vaues should not be quoted.
+    See JMS provider documentation for exact syntax.
+<10> Additional settings that are set directly on the ConnectionFactory object can be added here.
+<11> List of jars required by the JMS provider. Paths should be the fully qualified location of all jar files required
+     by the JMS provider. This list may also include dependent jars as well as specific jars from the JMS provider.
+
+===== Logstash Configuration for JNDI Connection
+[source,ruby]
+--------------------------------------------------
+ input {
+    jms {
+        # Logstash Configuration Settings. <1>
+        include_header => false
+        include_properties => false
+        include_body => true
+        use_jms_timestamp => false
+        destination => "myqueue"
+        pub_sub => false
+        # JNDI Settings
+        jndi_name => /jms/cf/default <2>
+        jndi_context => { <3>
+         'java.naming.factory.initial' => com.solacesystems.jndi.SolJNDIInitialContextFactory
+         'java.naming.security.principal' => solace-cloud-client@user
+         'java.naming.provider.url' => tcp://address.messaging.solace.cloud:20608
+         'java.naming.security.credentials' => verysecret
+        }
+        # Jar files to be imported
+        require_jars=> ['/usr/share/jms/commons-lang-2.6.jar', <4>
+                        '/usr/share/jms/sol-jms-10.5.0.jar',
+                        '/usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar',
+                        '/usr/share/jms/commons-lang-2.6.jar]'
+    }
+ }
+--------------------------------------------------
+
+<1> Configuration settings. Note that there is no `broker_url` or `username` or `password` defined here - these are
+    defined in the `jndi_context` hash.
+<2> JNDI name for this connection.
+<3> JNDI context settings hash. Contains details of how to connect to JNDI server. See your JMS provider documentation for
+     implementation specific details.
+<4> List of jars required by the JMS provider. Paths should be the fully qualified location of all jar files required
+     by the JMS provider. This list may also include dependent jars as well as specific jars from the JMS provider.
+
+
+==== Sample Configuration using Logstash Configuration and Yaml File
+
+===== Non-JNDI Connection
+
+This section contains sample configurations for connecting to a JMS provider that is not using JNDI using a combination
+ of the Logstash configuration and the yaml file
+
+===== Logstash Configuration for Non-JNDI Connection (for configs including yaml)
+
+[source,ruby]
+--------------------------------------------------
+ input {
+    jms {
+        # Logstash Configuration File Settings <1>
+        include_header => false
+        include_properties => false
+        include_body => true
+        use_jms_timestamp => false
+        destination => "myqueue"
+        pub_sub => false
+        # JMS Provider credentials <2>
+        username => xxxx
+        password => xxxx
+        # Location of yaml file, and which section to use for configuration
+        yaml_file => "~/jms.yml"  <3>
+        yaml_section => "mybroker" <4>
+    }
+ }
+--------------------------------------------------
+
+
+<1> Configuration settings
+<2> Username and password for the connection.
+<3> Full path to a yaml file containing the definition for the ConnectionFactory.
+<4> Section name in the yaml file of the ConnectionFactory for this plugin definition
+
+
+===== Yaml File for Non-JNDI Connection
+
+[source,yaml]
+--------------------------------------------------
+mybroker: <1>
+  :broker_url: 'ssl://localhost:61617' <2>
+  :factory: org.apache.activemq.ActiveMQConnectionFactory <3>
+  :exclusive_consumer: true <4>
+  :require_jars: <5>
+    - /usr/share/jms/activemq-all-5.15.9.jar
+    - /usr/share/jms/log4j-1.2.17.jar
+--------------------------------------------------
+
+<1> Section name for this broker definition. This should be the value of `yaml_section` in the logstash configuration file.
+    Note that multiple sections can co-exist in the same yaml file.
+<2> Full url of the broker. See your JMS Provider documentation for details.
+<3> Full name (including package name) of Java connection factory used to create a connection with your JMS provider.
+<4> Implementation specific configuration parameters to be used with the connection factory specified.
+    in <3>. Each JMS Provider will have its own set of parameters that can be used here. These parameters are mapped to
+    `set` methods on the provided connection factory, and can be supplied in either 'snake' or 'camel' case. In <4> above,
+    the `exclusive_consumer` property will call the `setExclusiveConsumer` on the supplied connection factory. See your JMS provider
+   documentation for implementation specific details.
+<5> List of jars required by the JMS provider. Paths should be the fully qualified location of all jar files required
+    by the JMS provider. This list may also include dependent jars as well as specific jars from the JMS provider.
+
+
+===== JNDI Connection
+
+This section contains sample configurations for connecting to a JMS provider that is using JNDI using a combination
+ of the Logstash configuration and the yaml file
+
+===== Logstash Configuration for JNDI Connection (for configs including yaml)
+
+[source,ruby]
+--------------------------------------------------
+ input {
+    jms {
+        # Logstash specific configuration settings <1>
+        include_header => false
+        include_properties => false
+        include_body => true
+        use_jms_timestamp => false
+        destination => "myqueue"
+        pub_sub => false
+        # Location of yaml file, and which section to use for configuration
+        yaml_file => "~/jms.yml"  <2>
+        yaml_section => "mybroker" <3>
+    }
+ }
+--------------------------------------------------
+
+<1> Configuration settings
+<2> Full path to a yaml file containing the definition for the ConnectionFactory.
+<3> Section name in the yaml file of the ConnectionFactory for this plugin definition
+
+
+===== Yaml File for JNDI Connection
+
+[source,yaml]
+--------------------------------------------------
+
+solace: <1>
+  :jndi_name: /jms/cf/default <2>
+  :jndi_context: <3>
+    java.naming.factory.initial: com.solacesystems.jndi.SolJNDIInitialContextFactory
+    java.naming.security.principal: solace-cloud-client@user
+    java.naming.provider.url: tcp://address.messaging.solace.cloud:20608
+    java.naming.security.credentials: verysecret
+  :require_jars: <4>
+    - /usr/share/jms/commons-lang-2.6.jar
+    - /usr/share/jms/sol-jms-10.5.0.jar
+    - /usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar
+    - /usr/share/jms/commons-lang-2.6.jar
+--------------------------------------------------
+
+<1> Section name for this broker definition. This should be the value of `yaml_section` in the Logstash configuration file.
+<2> Name of JNDI entry at which the Factory can be found
+<3> JNDI context settings. Contains details of how to connect to JNDI server. See your JMS provider documentation for
+     implementation specific details.
+<4> List of jars required by the JMS provider. Paths should be the fully qualified location of all jar files required
+     by the JMS provider. This list may also include dependent jars as well as specific jars from the JMS provider.
+
+
+==== Jar files
+
+In order to communicate with a JMS broker, the plugin must load the jar files necessary for each client type.
+This can be set in the yaml file, or in the main configuration if a yaml file is not necessary. The `require_jars`
+  setting should include the full path for each jar file required for the client. Eg
+
+===== Logstash configuration
+
+[source,ruby]
+--------------------------------------------------
+
+ input {
+    jms {
+              :
+              [snip]
+         require_jars => ['/usr/share/jms/commons-lang-2.6.jar',
+                          '/usr/share/jms/sol-jms-10.5.0.jar',
+                          '/usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar',
+                          '/usr/share/jms/commons-lang-2.6.jar']
+    }
+ }
+--------------------------------------------------
+
+==== Troubleshooting
+
+This section includes some common issues that a user may have when integrating this plugin with their JMS provider.
+
+===== Missing Jar files
+
+The most common issue is missing jar files, which may be jar files provided by the JMS vendor, or jar files that the JMS
+ vendor requires to run. This issue can manifest in different ways, depending on where the missing jar file is discovered.
+
+Example log output:
+
+[source,txt]
+-----
+  Failed to load JMS Connection, likely because a JMS Provider is not on the Logstash classpath or correctly
+  specified by the plugin's `require_jars` directive
+  {:exception=>"cannot load Java class javax.jms.DeliveryMode"
+-----
+
+[source,txt]
+-----
+  JMS Consumer Died {:exception=>"Java::JavaxNaming::NoInitialContextException",
+                     :exception_message=>"Cannot instantiate class:"
+-----
+
+[source,txt]
+-----
+  warning: thread "[main]<jms" terminated with exception (report_on_exception is true):
+  java.lang.NoClassDefFoundError: org/apache/commons/lang/exception/NestableException
+-----
+
+[source,txt]
+-----
+  JMS Consumer Died {:exception=>"Java::JavaxJms::JMSException", :exception_message=>"io/netty/channel/epoll/Epoll",
+  :root_cause=>{:exception=>"Java::JavaLang::NoClassDefFoundError", :exception_message=>"io/netty/channel/epoll/Epoll"}
+-----
+
+If any of these issues occur, check the list of `require_jars` in either the Logstash configuration or yaml configuration
+  files.
+
+===== Setting System Properties
+
+Many JMS providers allow or expect System properties to be set to configure certain properties when using JMS, for
+example, the Apache qpid JMS client allows the connection factory lookup to be stored there, and the Solace JMS client
+allows many properties, such as number of connection retries to be set as System properties. Any system properties that
+are set should be set in the Logstash `jvm.options` file.
+
+===== Multiple JMS inputs/outputs in the same Logstash process
+
+The use of multiple JMS consumers and producers in the same Logstash process is unsupported if:
+
+  * System properties need to be different for any of the consumers/producers
+  * Different keystores or truststores are required for any of the consumers/producers
+
+===== Message Selectors unexpectedly filtering out all messages
+
+Incorrect message selector syntax can have two effects - either the syntax is incorrect and the selector parser from the
+JMS provider will throw an exception causing the plugin to fail OR the syntax will be accepted, but the messages will
+be silently dropped - this can happen with incorrect quoting of string properties in the selector definition. All
+selector definitions must be double quoted in the Logstash configuration file, and string property values must be
+single quoted, and numeric property values not quoted at all.
 
 
 [id="plugins-{type}s-{plugin}-options"]
@@ -53,6 +347,9 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 |Setting |Input type|Required
 | <<plugins-{type}s-{plugin}-broker_url>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-destination>> |<<string,string>>|Yes
+| <<plugins-{type}s-{plugin}-durable_subscriber>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-durable_subscriber_client_id>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-durable_subscriber_name>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-factory>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-include_body>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-include_header>> |<<boolean,boolean>>|No
@@ -60,14 +357,21 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-interval>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-jndi_context>> |<<hash,hash>>|No
 | <<plugins-{type}s-{plugin}-jndi_name>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|No
+| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|No
 | <<plugins-{type}s-{plugin}-oracle_aq_buffered_messages>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-password>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-pub_sub>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-require_jars>> |<<array,array>>|No
-| <<plugins-{type}s-{plugin}-runner>> |<<string,string>>, one of `["consumer", "async", "thread"]`|No
+| <<plugins-{type}s-{plugin}-runner>> |<<string,string>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-selector>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-skip_headers>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-skip_properties>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-system_properties>> |<<hash,hash>>|No
 | <<plugins-{type}s-{plugin}-threads>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-timeout>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-truststore>> |a valid filesystem path|No
+| <<plugins-{type}s-{plugin}-truststore_password>> |<<password,password>>|No
 | <<plugins-{type}s-{plugin}-use_jms_timestamp>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-username>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-yaml_file>> |<<string,string>>|No
@@ -80,15 +384,15 @@ input plugins.
 &nbsp;
 
 [id="plugins-{type}s-{plugin}-broker_url"]
-===== `broker_url` 
+===== `broker_url`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
 
-Url to use when connecting to the JMS provider.
+Url to use when connecting to the JMS provider. This is only relevant for non-JNDI configurations.
 
 [id="plugins-{type}s-{plugin}-destination"]
-===== `destination` 
+===== `destination`
 
   * This is a required setting.
   * Value type is <<string,string>>
@@ -96,16 +400,52 @@ Url to use when connecting to the JMS provider.
 
 Name of the destination queue or topic to use.
 
+[id="plugins-{type}s-{plugin}-durable_subscriber"]
+===== `durable_subscriber`
+
+  * Value type is <<boolean,boolean>>
+  * This is `false` by default
+  * Requires `pub_sub` to be true
+
+Setting this value to `true` will make subscriptions to topics "durable", which allowing messages that arrived on the
+specified topic while Logstash is not running to still be read. Without setting this value, any messages sent to a topic
+while Logstash is not actively listening will be lost. A durable subscriber specifies a unique identity consisting of the
+ topic (`destination`), the client id (`durable_subscriber_client_id`) and subscriber name
+ (`durable_subscriber_subscriber_name`). See your JMS Provider documentation for any further requirements/limitations
+ around these settings.
+
+* Note that a durable subscription can only have one active subscriber at a time.
+* Note that this setting is only permitted when `pub_sub` is set to true, and will generate a configuration error otherwise
+
+[id="plugins-{type}s-{plugin}-durable_subscriber_client_id"]
+===== `durable_subscriber_client_id`
+
+  * Value type is <<string,string>>
+  * If `durable_subscriber` is set, the default value for this setting is 'Logstash', otherwise this setting has no
+    effect
+
+This represents the value of the client ID for a durable subscribtion, and is only used if `durable_subscriber` is set to `true`.
+
+[id="plugins-{type}s-{plugin}-durable_subscriber_name"]
+===== `durable_subscriber_name`
+
+  * Value type is <<string,string>>
+  * If `durable_subscriber` is set, the default value for this setting will be the same value as the `destination`
+    setting, otherwise this setting has no effect.
+
+This represents the value of the subscriber name for a durable subscribtion, and is only used if `durable_subscriber`
+is set to `true`. Please consult your JMS Provider documentation for constraints and requirements for this setting.
+
 [id="plugins-{type}s-{plugin}-factory"]
-===== `factory` 
+===== `factory`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
 
-Name of JMS Provider Factory class.
+Full name (including package name) of Java connection factory used to create a connection with your JMS provider.
 
 [id="plugins-{type}s-{plugin}-include_body"]
-===== `include_body` 
+===== `include_body`
 
   * Value type is <<boolean,boolean>>
   * Default value is `true`
@@ -120,7 +460,7 @@ the key/value pairs will be added in the Hashmap of the event.
 StreamMessage and ObjectMessage are not supported.
 
 [id="plugins-{type}s-{plugin}-include_header"]
-===== `include_header` 
+===== `include_header`
 
   * Value type is <<boolean,boolean>>
   * Default value is `true`
@@ -136,7 +476,7 @@ You can tell the input plugin which parts should be included in the event produc
 Include JMS Message Header Field values in the event.
 
 [id="plugins-{type}s-{plugin}-include_properties"]
-===== `include_properties` 
+===== `include_properties`
 
   * Value type is <<boolean,boolean>>
   * Default value is `true`
@@ -144,7 +484,7 @@ Include JMS Message Header Field values in the event.
 Include JMS Message Properties Field values in the event.
 
 [id="plugins-{type}s-{plugin}-interval"]
-===== `interval` 
+===== `interval`
 
   * Value type is <<number,number>>
   * Default value is `10`
@@ -154,33 +494,52 @@ This is the time sleeping between asks to a consumed Queue.
 This parameter has non influence in the case of a subcribed Topic.
 
 [id="plugins-{type}s-{plugin}-jndi_context"]
-===== `jndi_context` 
+===== `jndi_context`
 
   * Value type is <<hash,hash>>
   * There is no default value for this setting.
 
-Mandatory if jndi lookup is being used.
-Contains details on how to connect to JNDI server.
+Only used if using JNDI lookup. Key value pairs to determine how to connect the JMS message brokers if JNDI
+is being used. Consult your JMS provider documentation for the correct values to use here.
+
 
 [id="plugins-{type}s-{plugin}-jndi_name"]
-===== `jndi_name` 
+===== `jndi_name`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
 
-Name of JNDI entry at which the Factory can be found.
+Only used if using JNDI lookup. Name of JNDI entry at which the Factory can be found.
+
+[id="plugins-{type}s-{plugin}-keystore"]
+===== `keystore`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+If you need to use a custom keystore (`.jks`) specify it here. This does not work with .pem keys
+
+[id="plugins-{type}s-{plugin}-keystore_password"]
+===== `keystore_password`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting.
+
+Specify the keystore password here.
+Note, most .jks files created with keytool require a password
 
 [id="plugins-{type}s-{plugin}-oracle_aq_buffered_messages"]
-===== `oracle_aq_buffered_messages` 
+===== `oracle_aq_buffered_messages`
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
 Receive Oracle AQ buffered messages.
 In this mode persistent Oracle AQ JMS messages will not be received.
+Only for use with Oracle AQ
 
 [id="plugins-{type}s-{plugin}-password"]
-===== `password` 
+===== `password`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
@@ -188,15 +547,15 @@ In this mode persistent Oracle AQ JMS messages will not be received.
 Password to use when connecting to the JMS provider.
 
 [id="plugins-{type}s-{plugin}-pub_sub"]
-===== `pub_sub` 
+===== `pub_sub`
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
-If pub-sub (topic) style should be used.
+If pub-sub (topic) style should be used.  Note that if `pub_sub` is set to true, `threads` must be set to 1.
 
 [id="plugins-{type}s-{plugin}-require_jars"]
-===== `require_jars` 
+===== `require_jars`
 
   * Value type is <<array,array>>
   * There is no default value for this setting.
@@ -208,45 +567,91 @@ to put all the JMS Provider specific jar files into the
 java CLASSPATH prior to starting Logstash.
 
 [id="plugins-{type}s-{plugin}-runner"]
-===== `runner` 
+===== `runner`
 
-  * Value can be any of: `consumer`, `async`, `thread`
-  * Default value is `"consumer"`
+  * DEPRECATED WARNING: This configuration item is deprecated and may not be available in future versions.
 
-Choose an implementation of the run block. Value can be `consumer`, `async` or `thread`.
 
 [id="plugins-{type}s-{plugin}-selector"]
-===== `selector` 
+===== `selector`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
 
-Set the selector to use to get messages off the queue or topic.
+JMS message selector. Use in conjunctions with message headers or properties to filter messages to be processed. Only
+messages that match the query specified here will be processed. Check with your JMS provider for the correct JMS message
+selector syntax.
+
+[id="plugins-{type}s-{plugin}-skip_headers"]
+===== `skip_headers`
+
+  * Value type is <<array,array>>
+  * There is no default value for this setting.
+
+If `include_headers` is set, a list of headers to skip processing on can be specified here.
+
+[id="plugins-{type}s-{plugin}-skip_properties"]
+===== `skip_properties`
+
+  * Value type is <<array,array>>
+  * There is no default value for this setting.
+
+If `include_properties` is set, a list of properties to skip processing on can be specified here.
+
+[id="plugins-{type}s-{plugin}-system_properties"]
+===== `system_properties`
+
+  * Value type is <<hash,hash>>
+  * There is no default value for this setting.
+
+Any System properties that the JMS provider requires can be set either in a Hash here, or in `jvm.options`
+
 
 [id="plugins-{type}s-{plugin}-threads"]
-===== `threads` 
+===== `threads`
 
   * Value type is <<number,number>>
   * Default value is `1`
 
+* Note that if pub_sub is set to true, this value *must* be 1. A configuration error will be thrown otherwise
+
 [id="plugins-{type}s-{plugin}-timeout"]
-===== `timeout` 
+===== `timeout`
 
   * Value type is <<number,number>>
   * Default value is `60`
 
 Initial connection timeout in seconds.
 
+[id="plugins-{type}s-{plugin}-truststore"]
+===== `truststore`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+If you need to use a custom truststore (`.jks`) specify it here. This does not work with .pem certs.
+
+[id="plugins-{type}s-{plugin}-truststore_password"]
+===== `truststore_password`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting.
+
+Specify the truststore password here.
+
+* Note, most .jks files created with keytool require a password.
+
+
 [id="plugins-{type}s-{plugin}-use_jms_timestamp"]
-===== `use_jms_timestamp` 
+===== `use_jms_timestamp`
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
-Convert the JMSTimestamp header field to the @timestamp value of the event.
+Convert the JMSTimestamp header field to the @timestamp value of the event
 
 [id="plugins-{type}s-{plugin}-username"]
-===== `username` 
+===== `username`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
@@ -254,7 +659,7 @@ Convert the JMSTimestamp header field to the @timestamp value of the event.
 Username to use for connecting to JMS provider.
 
 [id="plugins-{type}s-{plugin}-yaml_file"]
-===== `yaml_file` 
+===== `yaml_file`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
@@ -262,7 +667,7 @@ Username to use for connecting to JMS provider.
 Yaml config file
 
 [id="plugins-{type}s-{plugin}-yaml_section"]
-===== `yaml_section` 
+===== `yaml_section`
 
   * Value type is <<string,string>>
   * There is no default value for this setting.
@@ -275,4 +680,4 @@ For some known examples, see https://github.com/reidmorrison/jruby-jms/blob/mast
 [id="plugins-{type}s-{plugin}-common-options"]
 include::{include_path}/{type}.asciidoc[]
 
-:default_codec!:
+:default_codec!: