Matchd is a DNS server which can be configured via YAML files.
Like it's example RubyDNS, it uses a pattern matching rule model but does not require you to write any ruby.
This is work in progress and not yet released. I will break things all the time.
$ gem install matchd
Although it's probably possible to use as a public/private DNS, Matchd is intended to be used in a development environment where using "localhost" or "editing /etc/hosts" isn't feasible anymore. Such as:
The idea is to use a globally non-route-able top level domain like .test and configure your local system in a way, that it will use Matchd as a resolver for such domains.
You can use Matchd to hook into global top level domain such as .com if you wish, and Matchd will forward everything it can't match to an upstream resolver. But keep in mind that doing so can have unexpected or even catastrophic results when expediently matching a domain you actually need for work.
Please refer to the section "Using as a local Dev DNS" on how to make your system use Matchd as a resolver.
Print available commands and sub-commands:
$ matchd help
$ matchd help start # to display details for a specific command
$ matchd help config # ... or sub-command
$ matchd config help setup # prints details for a specific sub-commands command
Create the default configuration directory within your $HOME
$ matchd config setup
.matchd: This is also the home for log and pid files.matchd/config.yml: Base configurations of the server.matchd/registry.yml: The registry for all of your rulesPlease also see examples for more.
config.yml)dot_dir: Path to the daemons base directory. This is where log and pid files are written to.listen: Collection of interface where the server will listen on.
This setting supports multiple formats:
listen:
- ["udp", "127.0.0.1", 15353]
listen:
- protocol: udp
ip: 127.0.0.1
port: 15353
listen:
- "udp://127.0.0.1:15353"
resolver: Collection of upstream resolvers for "passthrough" requests. (If a query could net been matched, we'll forward that request to this server)
Supports the same formats as listen:
resolver:
- ["udp", "1.1.1.1", 53]
resolver:
- protocol: udp
ip: 1.1.1.1
port: 53
resolver:
- "udp://1.1.1.1:53"
resolver: system
registry.yml)This file uses a single key rules which lists all the rules. Each rule is a structure with three keys.
- rules:
- match: ... # String or Regexp
resource_class: ... # A IN::* resource record name
_action_: ... # How to answer this match
The first two options, match and resource_class describe which query to match. The third describes how to respond and should be one of: append_question, respond, passthrough or fail.
Rules will get evaluated top-to-bottom. Once a rule matches, it will get executed and processing stops. A match always considers the name and resource class of the query.
The query name can be matched against a specific string or regular expression. The query resource class can be matched against a single or a list of targets. When a list is used, any of the targets in the list will trigger.
When no rule matches, the query will be forwarded to the configured resolvers (see config.yml and it's resolver key).
To match against a specific name use the string notation.
# This will only match where the requested domain is exactly `mydomain.test`, sub-domains like `sub.mydomain.test` will not match.
match: mydomain.test
To match all sub-domains, use a regular expression.
# This will only match sub-domain queries like `sub.mydomain.test` or `bus.mydomain.test`, but not `mydomain.de`
match: /^\w+\.mydomain\.test$/
# This will only match sub-domain queries like `sub.mydomain.test` or `bus.mydomain.test`, and also `mydomain.de`
match: /(^\w+\.)?mydomain\.test$/
# This will also match any depth of sub-domain queries like `bus.sub.mydomain.test`:
match: /(^\w+\.)*mydomain\.test$/
Under the hood, Matchd uses ruby regular expressions.
For the YAML configuration format only the /.../ syntax is supported, optionally using the m, x and i modifiers.
When using regular expressions, it's recommended to use ^ and $ anchors to have better control over what you want to match. Also keep in mind, that you'll need to escape dots (. -> \.).
A single or a list of ARPA Internet specific resource record (RRs) names:
A, AAAA, ANY, CNAME, HINFO, LOC, MINFO, MX, NS, PTR, SOA, SRV, TXT, WKS
To give some most common samples:
# IPv4 record
resource_class: A
# IPv6 record
resource_class: AAAA
# I'm funny:
resource_class:
- TXT
- CNAME
To let a rule respond, include the respond key.
Supported response types are: A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT
You can configure multiple responses per rule. Each rule has it's own configuration keys (see below) but they all support a common set of options:
ttl: 86400 # The Time-To-Live of the record (default: 86400 seconds == 24h)
name: "other.sample.test." # The absolute DNS name (needs to end with a dot). Default is the question name.
section: answer # The answer section. One of "answer", "additional", "authority" (default: "answer")
To avoid clutter, there are some shortcuts when defining a rule:
resource_class when it's the same as the queries resource_classExample:
One single value response:
- match: sample.test
resource_class: A
respond: 10.0.0.1
# is the same as:
- match: sample.test
resource_class: A
respond:
- resource_class: A
ip: 10.0.0.1
Multiple single value responses:
- match: sample.test
resource_class: NS
respond:
- 'ns1.sample.test.'
- 'ns2.sample.test.'
# is the same as:
- match: sample.test
resource_class: NS
respond:
- resource_class: NS
host: 'ns1.sample.test.'
- resource_class: NS
host: 'ns2.sample.test.'
Aresource_class: A
ip: "127.0.0.1"
AAAAresource_class: AAAA
ip: "::1"
CNAMEresource_class: CNAME
alias: "sample.test"
MXresource_class: MX
preference: 10
host: "mail.sample.test"
NSresource_class: NS
host: "ns1.sample.test"
PTRresource_class: PTR
host: "host1.sample.test"
SOAresource_class: SOA
mname: "ns1.sample.test." # master zone name
rname: "admin.sample.test." # Responsible Name
serial: "1533038712" # Serial Number
refresh: 1200 # Refresh Time
retry: 900 # Retry Time
expire: 3600000 # Maximum TTL / Expiry Time
minimum_ttl: 172800 # Minimum TTL
SRVresource_class: SRV
target: jabber
priority: 10
weight: 0
port: 5269
# To make this meaningful, we need to provide a name:
name: "_xmpp-server._tcp.sample.test"
TXTresource_class: TXT
txt: "some-token=value"
Append the results of another query to the response.
append_question: A
# is the same as:
append_question:
- A
Append rules accept the same common options as Respond rules. The Response rules options will take precedence if configured.
append_question:
ttl: 86400 # The Time-To-Live of the record (default: 86400 seconds == 24h)
name: "other.sample.test." # The absolute DNS name (needs to end with a dot). Default is the question name.
section: answer # The answer section. One of "answer", "additional", "authority" (default: "answer")
resource_class:
- A
- AAAA
Example:
- match: dev.sample.test
resource_class: ANY
append_question:
ttl: 86400
resource_class:
- A
- CNAME
- MX
- NS
Query an upstream resolver and use its response.
Takes the same parameters as the server config's resolver:
# Mixing IPv4 and IPv6 in different formats:
passthrough:
- ["udp", "1.1.1.1", 53]
- protocol: udp
ip: 1.0.0.1
port: 53
- "tcp://[2606:4700:4700::1111]:53"
- system
# Shortcut, if you need only one:
passthrough: system # or any other version above
# Long format with added options
passthrough:
force: true
resolver:
- ["udp", "1.1.1.1", 53]
- protocol: udp
ip: 1.0.0.1
port: 53
- "tcp://[2606:4700:4700::1111]:53"
- system
Indicate an error processing the query.
To cite Async::DNS list of list of the most commonly used errors:
NoError: No error occurred.FormErr: The incoming data was not formatted correctly.ServFail: The operation caused a server failure (internal error, etc).NXDomain: Non-eXistant Domain (domain record does not exist).NotImp: The operation requested is not implemented.Refused: The operation was refused by the server.NotAuth: The server is not authoritive for the zone.Note that the above values are all case sensitive!
Example:
- match: not-there.sample.test
resource_class: A
fail: NXDomain
# a catchall rule:
- match: /^(\w+\.)?sample.test$/
resource_class: A
respond: "127.0.0.1"
When using Matchd as a local dns server for development purposes, it's recommended to:
.testCreate a file under /etc/resolver/ which is named like the top level domain you'd like to specify a different resolver (Matchd) for.
cat <<EOF | sudo tee /etc/resolver/test
nameserver 127.0.0.1
nameserver ::1
port 15353
EOF
While Matchd is intended to be used as a demonizing CLI tool, you can use it as a library.
TODO: Docs
After checking out the repo, run bin/setup to install dependencies. Then, run bin/rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bin/rake install. To release a new version, update the version number in version.rb, and then run bin/rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/fnordfish/matchd
This software is distributed under the Mozilla Public License Version 2.0
A copy of the license text can be found in this repository under License.txt or at http://mozilla.org/MPL/2.0/
This software is based on the ideas of:
FAQs
Unknown package
We found that matchd demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.