mrcharles
2440188f1f
Consolidate the Technitium DNS CLI into tooling-cli/dns/ with a
containerized bash CLI (src/dns_cli.sh), Dockerfile (alpine +
curl/python3/bind-tools/bash), README, AGENTS.md, validate.sh, and
.env.example. Env vars aligned to the centralized ~/.creds/technitium.env
store (TECHNITIUM_URL, TECHNITIUM_DNS_TOKEN, TECHNITIUM_DNS_ZONE).
Image built and pushed to the registry as
git.knownelement.com/reachableceo/dns-cli:latest. Verified live:
zones, list, and search all return data.
💘 Generated with Crush
Assisted-by: Crush:glm-5.2
98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# AGENTS.md — DNS CLI tooling
|
|
|
|
This directory holds the `dns-cli` Docker container — a bash CLI over the
|
|
Technitium DNS Server REST API. Every Crush session that works on or with
|
|
this tool should read this file first.
|
|
|
|
## Connection & invocation
|
|
|
|
Invoke the real container with `docker run`. Credentials come from the
|
|
centralized credential store (see `tooling-cli/KNELCredsManager`):
|
|
|
|
```bash
|
|
docker run --rm --env-file ~/.creds/technitium.env \
|
|
git.knownelement.com/reachableceo/dns-cli:latest <command>
|
|
```
|
|
|
|
There is intentionally **no `bin/` wrapper** — invoke the real container, as
|
|
the project-wide rules require. For readability in an interactive session you
|
|
may define a throwaway shell alias (do not commit one):
|
|
|
|
```bash
|
|
alias dns='docker run --rm --env-file ~/.creds/technitium.env \
|
|
git.knownelement.com/reachableceo/dns-cli:latest'
|
|
```
|
|
|
|
The examples below write `dns <cmd>` for brevity; expand it to the full
|
|
`docker run` line (or set the alias) before running.
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Instance | `http://pfv-netinfra-01.knel.net:5380` |
|
|
| Default zone | `knel.net` |
|
|
| Credentials | `~/.creds/technitium.env` (`TECHNITIUM_URL`, `TECHNITIUM_DNS_TOKEN`, `TECHNITIUM_DNS_ZONE`) |
|
|
| CLI image | `git.knownelement.com/reachableceo/dns-cli:latest` |
|
|
| Source | `src/dns_cli.sh` in this directory |
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# List all zones:
|
|
dns zones
|
|
|
|
# List records in the default zone:
|
|
dns list
|
|
|
|
# Search for a record:
|
|
dns search ns1
|
|
|
|
# Resolve a name:
|
|
dns get pfv-netinfra-01
|
|
```
|
|
|
|
## Command reference
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `zones` | List all zones. |
|
|
| `list [zone]` | List records in a zone (default: `TECHNITIUM_DNS_ZONE`). |
|
|
| `get <name>` | Resolve a record via `dig` (A/AAAA). |
|
|
| `add <name> <ip> [ttl]` | Add an A record with auto-PTR (default TTL 3600). |
|
|
| `delete <name> <ip>` | Delete an A record. |
|
|
| `flush` | Flush the DNS cache. |
|
|
| `search <pattern>` | Search records by name pattern (case-insensitive). |
|
|
|
|
## Patterns
|
|
|
|
### Pattern: add a new DNS record
|
|
1. `dns search <hostname>` — check if the name already exists.
|
|
2. `dns add <hostname> <ip>` — creates the A record with auto-PTR.
|
|
3. `dns get <hostname>` — verify resolution.
|
|
4. `dns flush` — flush cache so the new record is immediately resolvable.
|
|
|
|
### Pattern: before you act
|
|
- Always `dns search <pattern>` or `dns list` before adding/deleting —
|
|
confirm current state so you don't create duplicates or delete the wrong
|
|
record.
|
|
- **Never delete a record** unless the user explicitly asks.
|
|
- PTR records are auto-created on `add` and auto-deleted on `delete`.
|
|
|
|
## Git workflow
|
|
|
|
### Atomic commits
|
|
Each commit is **one logical change**. Stage precisely (`git add <file>`,
|
|
not `git add -A`).
|
|
|
|
### Conventional commit messages
|
|
```
|
|
<type>(<optional scope>): <imperative subject>
|
|
|
|
<optional body — why, not what>
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `refactor`, `chore`, `style`.
|
|
|
|
- Subject line under 72 chars, lowercase, imperative mood.
|
|
- No period at end of subject.
|
|
- Body wrapped at 72 chars, explains **why** the change exists.
|