| Name | dnscacher JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Cache domain to IP mappings |
| upload_time | 2025-02-12 06:39:12 |
| maintainer | None |
| docs_url | None |
| author | BartSte |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
dns
cache
ip
domain
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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](#features)
2. [Installation](#installation)
3. [Usage](#usage)
4. [Commands](#commands)
- [GET](#get)
- [ADD](#add)
- [UPDATE](#update)
- [REFRESH](#refresh)
5. [Options](#options)
6. [Output Formats](#output-formats)
7. [Logging](#logging)
8. [Error Handling](#error-handling)
9. [Examples](#examples)
10. [License](#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
```bash
pip install dnscacher
```
or
Clone the repository and install it locally:
```bash
pip install .
```
---
If you want to develop the code, you can install the development dependencies
by running:
```bash
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:
```bash
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](#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:
```bash
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
```bash
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
```bash
dnscacher --output ipset get
```
- Prints lines of the form `add dnscacher 93.184.216.34`.
### 3. Update Cache from a Local File
```bash
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
```bash
dnscacher --part 50 refresh
```
- Randomly picks 50% of the cached domains and re-resolves them, updating the
cache with potentially new IP addresses.
Raw data
{
"_id": null,
"home_page": null,
"name": "dnscacher",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "dns, cache, ip, domain",
"author": "BartSte",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1c/be/65a97d160462e045a25108c35a529dc984cf967ad98cf0a097ae0d919bfc/dnscacher-0.2.0.tar.gz",
"platform": null,
"description": "# DNSCacher\n\n**DNSCacher** is a command-line utility that helps you manage domain-to-IP\nmappings efficiently. It supports caching results in a local file, updating\nthose results on demand, removing stale entries, and refreshing entries in\nuser-defined parts of the cache. Additionally, it can produce various output\nformats (e.g., mappings, IP addresses, domain lists, and ipset commands) to\nstandard output.\n\n---\n\n## Table of Contents\n\n1. [Features](#features)\n2. [Installation](#installation)\n3. [Usage](#usage)\n4. [Commands](#commands)\n - [GET](#get)\n - [ADD](#add)\n - [UPDATE](#update)\n - [REFRESH](#refresh)\n5. [Options](#options)\n6. [Output Formats](#output-formats)\n7. [Logging](#logging)\n8. [Error Handling](#error-handling)\n9. [Examples](#examples)\n10. [License](#license)\n\n---\n\n## Features\n\n- **Domain-to-IP Caching** \n Store resolved IP addresses for a list of domains, preventing repeated DNS\n lookups.\n\n- **Incremental Updates** \n Only resolves domains that are not yet in your cache. Removes stale domains\n that no longer appear in your source list.\n\n- **Partial Refresh** \n Re-resolve only a random subset (percentage) of your cached domains to keep\n them fresh without resolving everything every time.\n\n- **Multiple Output Formats** \n Can output mappings, IP addresses, domain lists, or an ipset command.\n\n- **Parallelism** \n Specify a number of parallel jobs (`--jobs`) to resolve domains concurrently.\n\n---\n\n## Installation\n\n```bash\npip install dnscacher\n```\n\nor\n\nClone the repository and install it locally:\n\n```bash\npip install .\n```\n\n---\n\nIf you want to develop the code, you can install the development dependencies\nby running:\n\n```bash\npip install -e \".[dev]\"\n```\n\nThis will install the development dependencies together with the package in\neditable mode.\n\n## Usage\n\nRun the `dnscacher` command with one of the subcommands:\n\n```bash\ndnscacher [OPTIONS] {get|add|update|refresh} [SOURCE]\n```\n\n- The `SOURCE` is either a local file or a URL and is not needed for the `get`\n or `refresh` commands.\n\n### Basic Workflow\n\n1. **Add** a new source of domains or start from an existing one.\n2. **Update** to handle changes in a domain list.\n3. **Get** the stored cache data to your console.\n4. **Refresh** in parts to re-resolve subsets of the cache if needed.\n\n---\n\n## Commands\n\nBelow are the primary commands. Each command also accepts common options\ndescribed in [Options](#options).\n\n### GET\n\n**Command:** `dnscacher get`\n\n- **Description:** \n Retrieves the current domain-to-IP mappings from the cache and (optionally)\n prints them to stdout in the format(s) you choose.\n\n- **Key Points:**\n - Does **not** resolve or remove domains.\n - Use `--output` to choose what you want to see: e.g., `mappings`, `ips`,\n `domains`, or `ipset`.\n\n### ADD\n\n**Command:** `dnscacher add [SOURCE]`\n\n- **Description:** \n Resolves and **adds** any domains not already in the cache. \n If the `--debug` flag is set, the `SOURCE` is ignored, and `debug.txt` is used.\n\n- **Behavior:**\n - Reads from `SOURCE` (URL or file).\n - Only **new** domains (compared to the existing cache) are resolved.\n - The newly resolved IPs are appended to the cache.\n - Does **not** remove any domains already in the cache.\n\n### UPDATE\n\n**Command:** `dnscacher update [SOURCE]`\n\n- **Description:** \n Combines adding new domains and removing stale domains in one step.\n\n- **Behavior:**\n - Reads from `SOURCE` (URL or file).\n - Resolves any **new** domains, just like in **ADD**.\n - **Removes** any domains from your cache that are no longer in `SOURCE`.\n - Maintains the rest of the domains.\n\n### REFRESH\n\n**Command:** `dnscacher refresh`\n\n- **Description:** \n Re-resolves a random set (size is given by `--part`) of **already cached**\n domains.\n\n- **Behavior:**\n - Does **not** add or remove domains, only re-resolves ones that exist in the\n cache.\n - Useful if you want to verify that the IPs in your cache are still correct,\n without re-resolving **all** of them.\n\n---\n\n## Options\n\nTo get get information on the options run the `dnscacher --help` command.\n\n#### Source Argument\n\n- Some commands like **ADD** or **UPDATE** optionally take a `SOURCE` argument.\n- This `SOURCE` can be:\n - A local file path (e.g., `/path/to/file.txt`)\n - A URL (e.g., `https://example.com/domains.txt`)\n- If the `--debug` flag is set, the `SOURCE` provided is ignored, and the tool\n uses the local `debug.txt` file from the project.\n\n---\n\n## Output Formats\n\nUse `-o/--output` with one or more comma-separated values:\n\n- **`mappings`**: Prints the domain followed by all its IP addresses (e.g.,\n `example.com 93.184.216.34`).\n- **`ips`**: Prints only the IP addresses in the cache, one per line.\n- **`domains`**: Prints only the domains in the cache, one per line.\n- **`ipset`**: Prints `add <ipsetName> <ip>` lines. Useful for piping into\n `ipset` commands.\n\nIf you provide multiple outputs, separate them with commas:\n\n```bash\ndnscacher --output mappings,ipset get\n```\n\nThat will print the mappings block, then the ipset block.\n\n---\n\n## Examples\n\n### 1. Add a List of Domains from a URL\n\n```bash\ndnscacher add https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/porn-only/hosts\n```\n\n- Resolves all new domains found in that URL and appends them to the cache.\n\n### 2. Get the Current Mappings in `ipset` Format\n\n```bash\ndnscacher --output ipset get\n```\n\n- Prints lines of the form `add dnscacher 93.184.216.34`.\n\n### 3. Update Cache from a Local File\n\n```bash\ndnscacher update /path/to/domains.txt\n```\n\n- Adds any new domains from `domains.txt` and removes any that no longer appear\n in it.\n\n### 4. Refresh 50% of Cached Domains\n\n```bash\ndnscacher --part 50 refresh\n```\n\n- Randomly picks 50% of the cached domains and re-resolves them, updating the\n cache with potentially new IP addresses.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Cache domain to IP mappings",
"version": "0.2.0",
"project_urls": null,
"split_keywords": [
"dns",
" cache",
" ip",
" domain"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ac634e699d9f1c1b1ef7d1cc9a91a63a1c0a4d53b1492c0956b402902a7d6449",
"md5": "acb56906540ac4bc3b21946b6ae16b5d",
"sha256": "f4d95638ed2381df58c95420c1c50e12a6db874bebeda018f379351ba7e055fa"
},
"downloads": -1,
"filename": "dnscacher-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acb56906540ac4bc3b21946b6ae16b5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18296,
"upload_time": "2025-02-12T06:39:10",
"upload_time_iso_8601": "2025-02-12T06:39:10.609024Z",
"url": "https://files.pythonhosted.org/packages/ac/63/4e699d9f1c1b1ef7d1cc9a91a63a1c0a4d53b1492c0956b402902a7d6449/dnscacher-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1cbe65a97d160462e045a25108c35a529dc984cf967ad98cf0a097ae0d919bfc",
"md5": "ad07e858ba344be503cf799cbe1d33e6",
"sha256": "7da7955dcaaef4ba6188539afb0d5392331c75e8406f6f1ab48e06d1d1527aa8"
},
"downloads": -1,
"filename": "dnscacher-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ad07e858ba344be503cf799cbe1d33e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21456,
"upload_time": "2025-02-12T06:39:12",
"upload_time_iso_8601": "2025-02-12T06:39:12.618800Z",
"url": "https://files.pythonhosted.org/packages/1c/be/65a97d160462e045a25108c35a529dc984cf967ad98cf0a097ae0d919bfc/dnscacher-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 06:39:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dnscacher"
}
