dnscacher 0.3.0

Cache domain to IP mappings

DNSCacher

DNSCacher is a command-line utility that helps you manage domain-to-IP mappings efficiently. It supports caching results in a local file, updating those results on demand, removing stale entries, and refreshing entries in user-defined parts of the cache. Additionally, it can produce various output formats (e.g., mappings, IP addresses, domain lists, and ipset commands) to standard output.

---

Table of Contents

1. Features
2. Installation
3. Usage
4. Commands
   • GET
   • ADD
   • UPDATE
   • REFRESH
5. Options
6. Output Formats
7. Logging
8. Error Handling
9. Examples
10. License

---

Features

• Domain-to-IP Caching
  Store resolved IP addresses for a list of domains, preventing repeated DNS lookups.

• Incremental Updates
  Only resolves domains that are not yet in your cache. Removes stale domains that no longer appear in your source list.

• Partial Refresh
  Re-resolve only a random subset (percentage) of your cached domains to keep them fresh without resolving everything every time.

• Multiple Output Formats
  Can output mappings, IP addresses, domain lists, or an ipset command.

• Parallelism
  Specify a number of parallel jobs (--jobs) to resolve domains concurrently.

---

Installation

pip install dnscacher

or

Clone the repository and install it locally:

pip install .

---

If you want to develop the code, you can install the development dependencies by running:

pip install -e ".[dev]"

This will install the development dependencies together with the package in editable mode.

Usage

Run the dnscacher command with one of the subcommands:

dnscacher [OPTIONS] {get|add|update|refresh} [SOURCE]

• The SOURCE is either a local file or a URL and is not needed for the get or refresh commands.

Basic Workflow

1. Add a new source of domains or start from an existing one.
2. Update to handle changes in a domain list.
3. Get the stored cache data to your console.
4. Refresh in parts to re-resolve subsets of the cache if needed.

---

Commands

Below are the primary commands. Each command also accepts common options described in Options.

GET

Command: dnscacher get

• Description:
  Retrieves the current domain-to-IP mappings from the cache and (optionally) prints them to stdout in the format(s) you choose.

• Key Points:

  • Does not resolve or remove domains.
  • Use --output to choose what you want to see: e.g., mappings, ips, domains, or ipset.

ADD

Command: dnscacher add [SOURCE]

• Description:
  Resolves and adds any domains not already in the cache.
  If the --debug flag is set, the SOURCE is ignored, and debug.txt is used.

• Behavior:

  • Reads from SOURCE (URL or file).
  • Only new domains (compared to the existing cache) are resolved.
  • The newly resolved IPs are appended to the cache.
  • Does not remove any domains already in the cache.

UPDATE

Command: dnscacher update [SOURCE]

• Description:
  Combines adding new domains and removing stale domains in one step.

• Behavior:

  • Reads from SOURCE (URL or file).
  • Resolves any new domains, just like in ADD.
  • Removes any domains from your cache that are no longer in SOURCE.
  • Maintains the rest of the domains.

REFRESH

Command: dnscacher refresh

• Description:
  Re-resolves a random set (size is given by --part) of already cached domains.

• Behavior:

  • Does not add or remove domains, only re-resolves ones that exist in the cache.
  • Useful if you want to verify that the IPs in your cache are still correct, without re-resolving all of them.

---

Options

To get get information on the options run the dnscacher --help command.

Source Argument

• Some commands like ADD or UPDATE optionally take a SOURCE argument.
• This SOURCE can be:
  • A local file path (e.g., /path/to/file.txt)
  • A URL (e.g., https://example.com/domains.txt)
• If the --debug flag is set, the SOURCE provided is ignored, and the tool uses the local debug.txt file from the project.

---

Output Formats

Use -o/--output with one or more comma-separated values:

• mappings: Prints the domain followed by all its IP addresses (e.g., example.com 93.184.216.34).
• ips: Prints only the IP addresses in the cache, one per line.
• domains: Prints only the domains in the cache, one per line.
• ipset: Prints add <ipsetName> <ip> lines. Useful for piping into ipset commands.

If you provide multiple outputs, separate them with commas:

dnscacher --output mappings,ipset get

That will print the mappings block, then the ipset block.

---

Examples

1. Add a List of Domains from a URL

dnscacher add https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/porn-only/hosts

• Resolves all new domains found in that URL and appends them to the cache.

2. Get the Current Mappings in ipset Format

dnscacher --output ipset get

• Prints lines of the form add dnscacher 93.184.216.34.

3. Update Cache from a Local File

dnscacher update /path/to/domains.txt

• Adds any new domains from domains.txt and removes any that no longer appear in it.

4. Refresh 50% of Cached Domains

dnscacher --part 50 refresh

• Randomly picks 50% of the cached domains and re-resolves them, updating the cache with potentially new IP addresses.