https://github.com/bmarwell/nameserviceagent

A simple name service hook -- modifies Java’s DNS resolution behaviour
https://github.com/bmarwell/nameserviceagent

agent dns dns-over-https dnsresolver java javaagent name-service round-robin

Last synced: 3 months ago
JSON representation

A simple name service hook -- modifies Java’s DNS resolution behaviour

• Host: GitHub
• URL: https://github.com/bmarwell/nameserviceagent
• Owner: bmarwell
• License: apache-2.0
• Created: 2020-09-18T12:34:28.000Z (about 5 years ago)
• Default Branch: main
• Last Pushed: 2020-09-23T21:04:19.000Z (about 5 years ago)
• Last Synced: 2024-12-09T11:53:54.318Z (11 months ago)
• Topics: agent, dns, dns-over-https, dnsresolver, java, javaagent, name-service, round-robin
• Language: Java
• Homepage:
• Size: 73.2 KB
• Stars: 4
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

          
= Name Resolver Replacement Agent for Java

image:https://www.travis-ci.com/bmhm/nameserviceagent.svg?branch=main["Build Status",link="https://www.travis-ci.com/bmhm/nameserviceagent"]

image:https://img.shields.io/badge/License-Apache%202.0-blue.svg["Apache License v2.0",link="https://opensource.org/licenses/Apache-2.0""]

image:https://codecov.io/gh/bmhm/nameserviceagent/branch/main/graph/badge.svg["Code Coverage",link="https://codecov.io/gh/bmhm/nameserviceagent"]

== Use case / what is this agent for?

If you want to modify DNS resolving, you are out of luck with java.

The SPI NameServiceDefinition was silently removed in Java 9+.

Even with this definition, it was impossible to just extend the default `NameService` implementation.

If you want to modify the behaviour of the existing `InetAddress::NameService` implementation, this agent will let you do this via ugly reflection and will break in later java versions as well.

Oracle has not provided a solution to this problem.

footnote:jdk8134577[See: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8134577[JDK-8134577 : Eliminate or standardize a replacement for sun.net.spi.nameservice.NameServiceDescriptor].]

footnote:jdk8201428[See: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8201428[JDK-8201428 : Provide a standard API for name resolution].]

footnote:jdk8192780[See: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8192780[JDK-8192780 : Consider restoring DNS SPI].]

== Requirements

* This agent requires Java 8+.

* About 20 kiB of disk and heap space.

== Usage

To use this agent, there are three steps to this:

1. Compilation or Download

2. Mount the agent with default configuration

3. Configure or extend the agent

=== Compilation or download

You can compile this agent using `./mvnw package`.

All you need is java11+ for compilation.

You can use the file `./agent/target/nameserviceagent-agent-1.0.0-SNAPSHOT.jar`.

Alternative:

Download the nameserviceagent-agent.jar from the releases.

=== Mounting the agent

You can mount the agent using `java -javaagent:nameserviceagent-agent.jar `.

=== Configuration

Currently these options are available:

|===

|key |type |default value |description

|`nameserviceagent.implementation`

|System Property (`-D`)

|`DefaultSequentialReachableNameService`

|Switch the implementation of the replaced/injected naming service.

|`nameserviceagent.reachable.timeoutMs`

|System Property (`-D`)

|`100` (ms)

|Timeout for the DefaultSequentialReachableNameService when a remote host is considered unavailable.

|===

==== Default configuration

:fn-hostfile: footnote:[By default, java will use your system’s DNS resolver. If you specify `-Djdk.net.hosts.file=hosts.txt`, DNS resolution will be replaced by this host file mechanism.]

The default configuration will use the default nameService (e.g. system dns or host file‎{fn-hostfile}).

However, while the default implementation will just use the 1st IP returned, this implementation will in fact check all the IP addresses.

=== Always resolve loopback

This DNS NameResolver implementation will always resolve to loopback (either `127.0.0.1` or `::1`).

This configuration can be activated like this:

[source,sh]

....

java

    -javaagent:${localRepositoryPath}/io/github/bmhm/nameserviceagent/nameserviceagent-agent/@project.version@/nameserviceagent-agent-@project.version@.jar

    -Dnameserviceagent.implementation=io.github.bmhm.nameserviceagent.agent.nameservice.AlwaysLocalhostLoopbackNameService

....

==== Other configurations

Feel free to create PRs for other Configs -- eg DNSoHTTPS, DNSfromDB, etc.

== Extension

If you want to write your own DNS Name Resolver, just extend `AbstractProxyNameService`

and make sure you also have the public constructor with the NameService interface.

Provide the full class name via the system property `nameserviceagent.implementation`.

== Production use

This agent is not intended for production code.

It will probably fail for more recent java releases which do not allow acces via reflection.