INWX DNS Recordmaster

通过YAML文件和API请求管理INWX域名的DNS名称服务器记录。轻量级，快速，支持版本控制。

注意：这不是INWX的官方软件项目，它只是友好地使用了他们的公共API。

• 概述
• 安装
• 配置
  • 应用程序/API配置
  • DNS记录配置
    • 特定域名覆盖选项
• 运行程序
  • 同步模式
  • 转换模式
• 贡献和开发
• 故障排除
  • 调试和预运行
  • 我删除了我所有的生产记录！
  • 模拟API响应
  • URL记录
• 许可证

概述

此工具使INWX（以前称为InterNetworX）的客户能够通过文件管理其域名的DNS条目/记录。这具有多个优点

• 域名服务器条目版本控制，因此能够记录随时间变化的记录。
• 非常简单的复制/粘贴现有条目到新域名，例如添加新的别名域名时。
• 支持搜索/替换，例如IP地址。
• 工作可以在离线状态下进行，并且完成后可以快速推送。无需等待有时缓慢的Web界面。

通过YAML文件以相当简单的结构配置DNS记录。它将与通过INWX API拉取的“远程”状态进行比较。如果需要，将发出最少的API请求以使远程状态与本地配置一致。

安装

该工具依赖于以下应用程序

• Python 3

您可以通过以下命令安装最新版本：pip3 install inwx-dns-recordmaster

使用inwx-dnsrm执行该工具。使用--help标志可了解所需和可用的命令。

配置

有两种配置类型

1. 应用程序配置：INWX API登录数据
2. DNS记录配置：每个配置域的期望状态

应用程序/API配置

您需要添加API身份验证的凭据。如果不存在，则将在首次运行时自动创建该文件。在Linux系统上，它将位于~/.config/inwx-dns-recordmaster/config.toml。

在任何情况下，您都需要添加INWX用户名和密码，无论是主账户还是子账户。如果您使用双因素身份验证，也可以添加共享密钥，尽管这可能会削弱您的安全性。您还可以要求INWX支持将登录限制到特定的IP地址。

DNS记录配置

DNS记录配置在YAML文件中。如果您有多个域名，您可以将所有定义放入一个大型文件中，或者创建多个文件。程序中的--dns-config标志只需指向一个目录，该目录中至少有一个这样的文件。只有以.yaml或.yml结尾的文件才被考虑。

您可以在文件records/example.com.yaml.sample中找到DNS记录配置的示例。以下是更短的示例

example.com:
  # Records configuring example.com
  .:
    - type: A
      content: "192.168.13.37"
    - type: MX
      content: "my.mailhost.tld"
      prio: 10  # priority of MX record, relevant with multiple MX
  # *.example.com
  "*":
    - type: A
      content: "192.168.13.37"
  # cloud.example.com
  cloud:
    - type: CNAME
      content: cloudprovider.tld
      ttl: 86400  # long TTL

请注意，此程序的一般思想是管理所有记录都是在本地进行的。在上面的示例中，它会删除域的NS记录，这是一个坏主意。

然而，存在默认和可扩展的异常

• 默认情况下，不将SOA类型的记录考虑在内，因为它们每次更改都会变化，并且由INWX处理得很好。如果您不希望处理它们，可以使用--ignore-types参数添加其他记录类型。
• 您还可以使用--preserve-remote标志明确忽略存在于INWX但不在本地配置中的记录。这样，您只更新现有记录和添加新记录，但不删除INWX中未配置的记录。

如果您已经在INWX配置了域名，并且希望将记录迁移到本地DNS记录配置中，可以使用转换命令：inwx-dnsrm convert --domain example.com。这使您可以获取特定域的DNS配置，将其放入本地配置中，并从这一点开始。除非您想手动从头开始编写长的配置文件，否则您不必这样做。

特定域名覆盖选项

--preserve-remote和--ignore-types是该程序中非常方便的选项，如果您想自定义如何与远程记录交互。然而，如果您在本地配置了多个域名，您可能希望将其中一些与其他的不同对待。一种方法可能是使用多个-d参数多次运行程序，但这显然很麻烦。

这就是为什么您也可以在YAML配置文件中覆盖这些选项。以下是一个示例

example.com:
  # Override options to preserve remote records that are not configured locally.
  # This is equivalent to `--preserve-remote` but is only applied to this domain
  --options:
    preserve_remote: true
  # Records configuring only extra.example.com
  extra:
    - type: TXT
      content: "This is my custom TXT record, all others are ignored"

运行程序

您可以使用命令inwx-dnsrm执行程序。inwx-dnsrm --help显示所有可用的参数和选项。

该程序有两个主要命令：sync 和 convert。

同步模式

sync 覆盖了主要功能，根据上述格式的本地配置文件管理 INWX 域名记录。

一些示例

• inwx-dnsrm sync -c records/：从 records/ 目录读取 DNS 记录，与远程匹配，并调用 API 为每个本地配置的域名添加、更新和删除条目。
• inwx-dnsrm sync -c records/ -d example.com：类似于上述操作，但仅检查域名 example.com 并忽略所有其他本地配置的域名。如果您有多个域名，这可能会加快操作速度。
• inwx-dnsrm sync -c records/ -p：正常运行，但不删除本地未配置的 INWX 中的名称服务器条目。
• inwx-dnsrm sync -c records/ --dry：运行整个程序，但不在 INWX 上做出任何更改。如果您刚刚配置了一个新的域名，这将非常有用。
• inwx-dnsrm sync --debug -c records/：运行整个程序并显示所有调试消息。

运行 inwx-dnsrm sync -h 以查看所有选项。

转换模式

convert 可以将 INWX 上现有的名称服务器条目转换为上述解释的本地配置文件格式。如果您想在 INWX 上“上线”一个已经配置的域名，并且不想从头开始编写配置文件，这将非常方便。

一些示例

• inwx-dnsrm convert -d example.com：获取域名 "example.com" 的远程记录，并输出相应的本地 YAML 配置，您可以直接复制。
• inwx-dnsrm convert -d example.com > records/example.com.yaml：类似于上述操作，但将配置写入文件，您不需要复制。
• inwx-dnsrm -i SOA,NS convert -d example.com：与上述操作相同，但不获取 SOA 和 NS 记录（SOA 是默认值）。

运行 inwx-dnsrm convert -h 以查看所有选项。

贡献和开发

欢迎贡献！开发最简单的方式是使用 poetry：运行 poetry install 和 poetry run inwx-dnsrm 即可开始。

故障排除

调试和预运行

--debug 标志将帮助您走得很远。如果您想就本项目创建问题，请提供调试日志，这将非常有帮助！

在运行 sync 命令时，这也可能有所帮助

• 建议使用 --dry 进行实验，以避免破坏您的生产配置。
• --interactive 将在每次更改之前询问您进行确认。

我删除了我所有的生产记录！

哎呀，您忘记运行 sync --dry 或先 convert 远程记录？虽然没有回滚功能，但工具在做出任何更改之前会保留本地和远程数据。对于每次运行和域名，您将在缓存文件夹中找到一个内部数据方案的导出。在 Linux 系统中，这位于 ~/.cache/inwx-dns-recordmaster，文件名可能类似于 example.com-1521462189.json（数字是当前的 UNIX 时间）。有了这个，您可以在运行此工具之前手动在 INWX 网络界面中重建远程状态，或者将其放入您本地的 DNS 记录配置中。

模拟API响应

如果您想在本地工作或想修改 INWX API 响应，您可以进行模拟。--api-response 标志接受一个 JSON 文件作为参数，该文件基本上包含 INWX API 关于域名名称服务器条目远程状态的响应。这适用于 sync 和 convert 命令。

这可能看起来像以下这样

{
  "roId": 123456,
  "domain": "example.com",
  "type": "MASTER",
  "cleanup": {
    "status": "OK",
    "tstamp": 1513779810
  },
  "count": 4,
  "record": [
    {
      "id": 1402323103,
      "name": "example.com",
      "type": "A",
      "content": "185.26.156.148",
      "ttl": 3600,
      "prio": 0
    },
    {
      "id": 1404343107,
      "name": "www.example.com",
      "type": "A",
      "content": "185.26.156.148",
      "ttl": 3600,
      "prio": 0
    },
    {
      "id": 209645684,
      "name": "example.com",
      "type": "NS",
      "content": "ns.inwx.de",
      "ttl": 86400,
      "prio": 0
    },
    {
      "id": 2094329683,
      "name": "example.com",
      "type": "SOA",
      "content": "ns.inwx.de hostmaster.inwx.de 2024030422 10800 3600 604800 3600",
      "ttl": 86400,
      "prio": 0
    }
  ]
}

要从现有域名获取此输出，您可以运行程序并使用 --debug 标志，然后搜索以 Response (nameserver.info): 开头的行。

URL 记录

INWX支持URL记录，允许将域名重定向到另一个域名。这些记录在一定程度上由本工具支持，但存在一些问题和错误。建议在网页界面中添加和编辑这些记录，而不是通过本工具，因为INWX API似乎不可靠，但您仍然可以本地存储这些配置。

许可证

本项目的主体许可证是GNU通用公共许可证3.0版，无后续版本（GPL-3.0-only），版权所有Max Mehl。

可能存在不同，但兼容的许可证和不同版权所有者的组件。该项目符合REUSE规范，这使得这些部分变得透明。您将在LICENSES目录中找到所有使用的许可证。