components/camel-dns/src/main/docs/dns-component.adoc

[[dns-component]]
= DNS Component

*Since Camel 2.7*

// HEADER START
*Only producer is supported*
// HEADER END

This is an additional component for Camel to run DNS queries, using
DNSJava. The component is a thin layer on top of
http://www.xbill.org/dnsjava/[DNSJava].
The component offers the following operations:

* ip, to resolve a domain by its ip
* lookup, to lookup information about the domain
* dig, to run DNS queries

[NOTE]
====
*Requires SUN JVM*

The DNSJava library requires running on the SUN JVM.
 If you use Apache ServiceMix or Apache Karaf, you'll need to adjust the
`etc/jre.properties` file, to add `sun.net.spi.nameservice` to the list
of Java platform packages exported. The server will need restarting
before this change takes effect.
====

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-dns</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
----

== URI format

The URI scheme for a DNS component is as follows

[source,java]
-------------------------
dns://operation[?options]
-------------------------

This component only supports producers.

== Options


// component options: START
The DNS component supports 3 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
|===
// component options: END



// endpoint options: START
The DNS endpoint is configured using URI syntax:

----
dns:dnsType
----

with the following path and query parameters:

=== Path Parameters (1 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *dnsType* | *Required* The type of the lookup. |  | DnsType
|===


=== Query Parameters (3 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
|===
// endpoint options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-dns-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 4 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.dns.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean
| *camel.component.dns.bridge-error-handler* | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | Boolean
| *camel.component.dns.enabled* | Enable dns component | true | Boolean
| *camel.component.dns.lazy-start-producer* | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | Boolean
|===
// spring-boot-auto-configure options: END



== Headers
[width="100%",cols="10%,10%,10%,70%",options="header",]
|===

|Header |Type |Operations |Description

|dns.domain |String |ip |The domain name. Mandatory.

|dns.name |String |lookup |The name to lookup. Mandatory.

|dns.type |   | lookup, dig |The type of the lookup. Should match the values of `org.xbill.dns.Type`.
Optional.

|dns.class |   | lookup, dig |The DNS class of the lookup. Should match the values of
`org.xbill.dns.DClass`. Optional.

|dns.query |String |dig |The query itself. Mandatory.

|dns.server |String |dig |The server in particular for the query. If none is given, the default
one specified by the OS will be used. Optional.
|===

== Examples

=== IP lookup

[source,xml]
----
        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:ip"/>
        </route>
----

This looks up a domain's IP. For example, www.example.com resolves to
192.0.32.10. +
 The IP address to lookup must be provided in the header with key
`"dns.domain"`.

=== DNS lookup

[source,xml]
----
        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:lookup"/>
        </route>
----

This returns a set of DNS records associated with a domain. +
 The name to lookup must be provided in the header with key
`"dns.name"`.

=== DNS Dig

Dig is a Unix command-line utility to run DNS queries.

[source,xml]
----
        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:dig"/>
        </route>
----

The query must be provided in the header with key `"dns.query"`.


== Dns Activation Policy

DnsActivationPolicy can be used to dynamically start and stop routes based on dns state.

If you have instances of the same component running in different regions you can configure a route in each region to activate only if dns is pointing to its region.

i.e. You may have an instance in NYC and an instance in SFO. You would configure a service CNAME service.example.com to point to nyc-service.example.com to bring NYC instance up and SFO instance down. When you change the CNAME service.example.com to point to sfo-service.example.com -- nyc instance would stop its routes and sfo will bring its routes up. This allows you to switch regions without restarting actual components.

[source,xml]
----
	<bean id="dnsActivationPolicy" class="org.apache.camel.component.dns.policy.DnsActivationPolicy">
		<property name="hostname" value="service.example.com" />
		<property name="resolvesTo" value="nyc-service.example.com" />
		<property name="ttl" value="60000" />
		<property name="stopRoutesOnException" value="false" />
	</bean>

	<route id="routeId" autoStartup="false" routePolicyRef="dnsActivationPolicy">
	</route>
----