{"id":19466027,"url":"https://github.com/mxmehl/inwx-dns-recordmaster","last_synced_at":"2026-04-03T00:01:46.330Z","repository":{"id":226963439,"uuid":"769697114","full_name":"mxmehl/inwx-dns-recordmaster","owner":"mxmehl","description":"Manage DNS nameserver records of INWX domains via YAML files and API requests. Lightweight, version-control ready","archived":false,"fork":false,"pushed_at":"2026-03-26T16:28:52.000Z","size":490,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-29T14:36:08.165Z","etag":null,"topics":["api","dns","domain-management","inwx","nameserver"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxmehl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-09T19:54:58.000Z","updated_at":"2026-03-23T05:21:01.000Z","dependencies_parsed_at":"2024-04-06T13:25:43.443Z","dependency_job_id":"09d19172-5e7f-4ce1-92e0-1a7e8bbbbf06","html_url":"https://github.com/mxmehl/inwx-dns-recordmaster","commit_stats":null,"previous_names":["mxmehl/inwx-dns-recordmaster"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mxmehl/inwx-dns-recordmaster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Finwx-dns-recordmaster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Finwx-dns-recordmaster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Finwx-dns-recordmaster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Finwx-dns-recordmaster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxmehl","download_url":"https://codeload.github.com/mxmehl/inwx-dns-recordmaster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxmehl%2Finwx-dns-recordmaster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31319742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T23:57:25.032Z","status":"ssl_error","status_checked_at":"2026-04-02T23:57:06.281Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","dns","domain-management","inwx","nameserver"],"created_at":"2024-11-10T18:25:04.676Z","updated_at":"2026-04-03T00:01:46.319Z","avatar_url":"https://github.com/mxmehl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2024 Max Mehl \u003chttps://mehl.mx\u003e\n\nSPDX-License-Identifier: GPL-3.0-only\n--\u003e\n\n# INWX DNS Recordmaster\n\n[![Test suites](https://github.com/mxmehl/inwx-dns-recordmaster/actions/workflows/test.yaml/badge.svg)](https://github.com/mxmehl/inwx-dns-recordmaster/actions/workflows/test.yaml)\n[![REUSE status](https://api.reuse.software/badge/github.com/mxmehl/inwx-dns-recordmaster)](https://api.reuse.software/info/github.com/mxmehl/inwx-dns-recordmaster)\n[![The latest version of INWX DNS recordmaster can be found on PyPI.](https://img.shields.io/pypi/v/inwx-dns-recordmaster.svg)](https://pypi.org/project/inwx-dns-recordmaster/)\n[![Information on what versions of Python INWX DNS Recordmaster supports can be found on PyPI.](https://img.shields.io/pypi/pyversions/inwx-dns-recordmaster.svg)](https://pypi.org/project/inwx-dns-recordmaster/)\n\nManage DNS nameserver records of INWX domains via YAML files and API requests. Lightweight, fast, version-control ready.\n\nNote: This is no official software project by INWX, it just kindly uses their public API.\n\n- [Overview](#overview)\n- [Install](#install)\n- [Configuration](#configuration)\n  - [App/API configuration](#appapi-configuration)\n  - [DNS records configuration](#dns-records-configuration)\n    - [Domain-specific override options](#domain-specific-override-options)\n  - [Examples](#examples)\n- [Run the program](#run-the-program)\n  - [Synchronisation mode](#synchronisation-mode)\n  - [Conversion mode](#conversion-mode)\n- [Contribute and Develop](#contribute-and-develop)\n- [Troubleshooting](#troubleshooting)\n  - [Debug and dry-run](#debug-and-dry-run)\n  - [I deleted all my productive records!](#i-deleted-all-my-productive-records)\n  - [Simulate API response](#simulate-api-response)\n  - [URL records](#url-records)\n- [License](#license)\n\n\n## Overview\n\nThis tool enables customers of [INWX](https://www.inwx.de) (formerly known as InterNetworX) to manage the DNS entries/records of their domains via files. This has multiple advantages:\n\n* Version-control of nameserver entries, therefore a good record of what has changed over time.\n* Very simple copy/paste of existing entries for new domains, e.g. when a new alias domain has been added.\n* Enables search/replace, e.g. of IP addresses.\n* Work can be done offline and quicker, and pushed once it's done. No waiting times for the sometimes slow web interface.\n\nConfiguration of the DNS records is done in YAML files with a quite simple structure. It is compared against the \"remote\" state, pulled via the INWX API. If necessary, minimal API requests will be issues to align the remote state with the local configuration.\n\n\n## Install\n\nThis Python program is available under the name `inwx-dns-recordmaster`. After installation, you can invoke it with the command `inwx-dnsrm`.\n\n### Install and run via pipx (Recommended)\n\n[pipx](https://pypa.github.io/pipx/) makes installing and running Python programs easier and avoid conflicts with other packages. Install it with\n\n```sh\npip3 install pipx\n```\n\nThe following one-liner both installs and runs this program from [PyPI](https://pypi.org/project/inwx-dns-recordmaster/):\n\n```sh\npipx run inwx-dns-recordmaster\n```\n\nIf you want to be able to use the program without prepending it with `pipx run` every time, install it globally like so:\n\n```sh\npipx install inwx-dns-recordmaster\n```\n\nThe tool's binary `inwx-dnsrm` will then be available in `~/.local/bin`, which must be added to your `$PATH`. On Windows, the required path for your environment may look like `%USERPROFILE%\\AppData\\Roaming\\Python\\Python310\\Scripts`, depending on the Python version you have installed.\n\nTo upgrade the program to the newest available version, run this command:\n\n```sh\npipx upgrade inwx-dns-recordmaster\n```\n\n### Other installation methods\n\nYou may also use pure `pip` or `uv` to install this package.\n\n\n## Configuration\n\nThere are two types of configuration:\n\n1. App configuration: INWX API login data\n1. DNS records configuration: the desired state for each configured domain\n\n\n### App/API configuration\n\nYou need to add your credentials for the API authentication. The file will be created automatically on first run if it doesn't exist. On Linux systems, it will be located in `~/.config/inwx-dns-recordmaster/config.toml`.\n\nIn any case, you will need to add your INWX username and password, be it of the main or a sub-account. If you use two-factor-authentication you may add the shared secret as well, although this may weaken your security. You may also want to ask the INWX support to limit the login to specific IP addresses.\n\n\n### DNS records configuration\n\nDNS records are configured in YAML files. If you have multiple domains, you can either put all definitions in one big file, or create multiple ones. The `--dns-config` flag of the program just needs to point to a directory in which at least one such file is present. Only files ending with `.yaml` or `.yml` are considered.\n\nYou can find an example DNS records configuration in the file [`records/example.com.yaml.sample`](records/example.com.yaml.sample). Here is a much shorter example:\n\n```yaml\nexample.com:\n  # Records configuring example.com\n  .:\n    - type: A\n      content: \"192.168.13.37\"\n    - type: MX\n      content: \"my.mailhost.tld\"\n      prio: 10  # priority of MX record, relevant with multiple MX\n  # *.example.com\n  \"*\":\n    - type: A\n      content: \"192.168.13.37\"\n  # cloud.example.com\n  cloud:\n    - type: CNAME\n      content: cloudprovider.tld\n      ttl: 86400  # long TTL\n```\n\nPlease note that the general idea of this program is that ALL records are managed locally. In the above example, it would delete the `NS` records of the domain which is a bad idea.\n\nHowever, there are default and extendable exceptions:\n\n* By default, records of the type `SOA` are not considered as they change upon each change and are handled well by INWX. You can add additional, comma-separated record types with the `--ignore-types` argument if you don't want to handle them. Example: `--ignore-types SOA,NS,TXT`\n* You can also blatantly ignore records that exist at INWX but not in your local configuration, using the `--preserve-remote` flag. This way, you only *update existing* and *add new* records, but don't *delete unconfigured* records at INWX.\n\nIf you already have a domain configured at INWX whose records you want to migrate to your local DNS records configuration, there is the convert command: `inwx-dnsrm convert --domain example.com`. This enables you to take the DNS config at INWX for a specific domain, put it in your local configuration, and start from this point onwards. You don't have to manually write long configuration files from scratch, unless you want to.\n\n\n#### Domain-specific override options\n\n`--preserve-remote` and `--ignore-types` are handy options for this program if you want to customise how to interact with remote records. However, if you have multiple domains configured locally, you may want to treat some of them differently than the others. One way might be to run the program multiple times with individual `-d` arguments, but that's obviously burdensome.\n\nThis is why you can also override these options in the YAML configuration files. Here is an example:\n\n```yaml\nexample.com:\n  # Override options to preserve remote records that are not configured locally.\n  # This is equivalent to `--preserve-remote` but is only applied to this domain\n  --options:\n    preserve_remote: true\n  # Records configuring only extra.example.com\n  extra:\n    - type: TXT\n      content: \"This is my custom TXT record, all others are ignored\"\n```\n\n### Examples\n\nOpenRail Association is a user of INWX DNS Recordmaster to manage some of its domains. You can take inspiration from their\n\n* [App/API configuration](https://github.com/OpenRailAssociation/openrail-dns/blob/main/config.toml)\n* [DNS records](https://github.com/OpenRailAssociation/openrail-dns/tree/main/records)\n* and [GitHub workflow](https://github.com/OpenRailAssociation/openrail-dns/blob/main/.github/workflows/sync-records.yaml)\n\n\n## Run the program\n\nYou can execute the program using the command `inwx-dnsrm`. `inwx-dnsrm --help` shows all available arguments and options.\n\nThe program has two main commands: `sync` and `convert`.\n\n\n### Synchronisation mode\n\n`sync` covers the main functionality, managing INWX domain records based on local configuration files whose format is explained above.\n\nSome examples:\n\n* `inwx-dnsrm sync -c records/`: read the DNS records from the `records/` directory, match them with the remote, and call the API to add, update, and delete entries for each locally configured domain.\n* `inwx-dnsrm sync -c records/ -d example.com`: like the above, but only check the domain `example.com` and ignore all other locally configured. If you have many domains, this may speed up operations.\n* `inwx-dnsrm sync -c records/ -p`: run normally, but do not delete nameserver entries at INWX which are not configured locally.\n* `inwx-dnsrm sync -c records/ --dry`: run the whole program but do not make any changes at INWX. Very helpful if you just configure a new domain.\n* `inwx-dnsrm sync --debug -c records/`: run the whole program and show all debug messages.\n\nRun `inwx-dnsrm sync -h` to see all options.\n\n### Conversion mode\n\n`convert` can convert existing nameserver entries at INWX to the local configuration file format which is explained above. This is neat if you want to \"on-board\" a domain you already have configured at INWX and don't want to write the configuration files from scratch.\n\nSome examples:\n\n* `inwx-dnsrm convert -d example.com`: get the remote records for the domain \"example.com\" and output its corresponding local YAML configuration which you can just copy.\n* `inwx-dnsrm convert -d example.com \u003e records/example.com.yaml`: like the above, but write the configuration to a file so you don't have to copy it.\n* `inwx-dnsrm -i SOA,NS convert -d example.com`: the same as above, but do not fetch SOA and NS records (SOA is the default).\n\nRun `inwx-dnsrm convert -h` to see all options.\n\n## Contribute and Develop\n\nContributions are welcome! The development is easiest with `uv`: `uv sync` and `uv run inwx-dnsrm` will get you started.\n\n\n## Troubleshooting\n\n\n### Debug and dry-run\n\nThe `--debug` flag will bring you a long way. If you want to create an issue with this project, please provide a debug log, it will be of great help!\n\nWhen running the `sync` command, this may also help:\n* `--dry` is recommended to play around with the program and avoid breaking your productive configuration.\n* `--interactive` will ask you before each change for a confirmation.\n\n\n### I deleted all my productive records!\n\nOh no, you forgot to make a `sync --dry` run or `convert` the remote records first? While there is no rollback functionality, the tool preserves the local and remote data before making any modification. For each run and domain, you will find an export of the internal data scheme in a cache folder. On Linux systems, this is in `~/.cache/inwx-dns-recordmaster`, the file names will be something like `example.com-1521462189.json` (the number being the current UNIX time). With this, you can reconstruct the remote state before running this tool, either manually in the INWX web interface or you put it in your local DNS records configuration.\n\n\n### Simulate API response\n\nIf you want to work locally or want to modify the INWX API response, you can simulate it. The `--api-response` flag takes a JSON file as argument that basically contains the reponse of the INWX API about the remote state of a domain's nameserver entries. This works in both the `sync` and `convert` commands.\n\nThis could look like the following:\n\n```json\n{\n  \"roId\": 123456,\n  \"domain\": \"example.com\",\n  \"type\": \"MASTER\",\n  \"cleanup\": {\n    \"status\": \"OK\",\n    \"tstamp\": 1513779810\n  },\n  \"count\": 4,\n  \"record\": [\n    {\n      \"id\": 1402323103,\n      \"name\": \"example.com\",\n      \"type\": \"A\",\n      \"content\": \"185.26.156.148\",\n      \"ttl\": 3600,\n      \"prio\": 0\n    },\n    {\n      \"id\": 1404343107,\n      \"name\": \"www.example.com\",\n      \"type\": \"A\",\n      \"content\": \"185.26.156.148\",\n      \"ttl\": 3600,\n      \"prio\": 0\n    },\n    {\n      \"id\": 209645684,\n      \"name\": \"example.com\",\n      \"type\": \"NS\",\n      \"content\": \"ns.inwx.de\",\n      \"ttl\": 86400,\n      \"prio\": 0\n    },\n    {\n      \"id\": 2094329683,\n      \"name\": \"example.com\",\n      \"type\": \"SOA\",\n      \"content\": \"ns.inwx.de hostmaster.inwx.de 2024030422 10800 3600 604800 3600\",\n      \"ttl\": 86400,\n      \"prio\": 0\n    }\n  ]\n}\n```\n\nIn order to get this output from an existing domain, you can run the program with the `--debug` flag and search for the line starting with `Response (nameserver.info):`.\n\n\n### URL Records\n\nINWX has [URL records](https://kb.inwx.com/en-us/3-nameserver/106-how-can-i-forward-a-domain-to-an-internet-address) that allow for redirections of a domain to another domain. These records are somewhat supported by this tool, but there are [several issues and bugs](https://github.com/mxmehl/inwx-dns-recordmaster/pull/23). It's recommended to add and edit these records in the web interface and not via this tool as the INWX API doesn't seem to be reliable, but you can still store these configurations locally.\n\n\n## License\n\nThe main license of this project is the GNU General Public License 3.0, no later version (`GPL-3.0-only`), Copyright Max Mehl.\n\nThere may be components under different, but compatible licenses and from different copyright holders. The project is [REUSE](https://reuse.software) compliant which makes these portions transparent. You will find all used licenses in the `LICENSES` directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxmehl%2Finwx-dns-recordmaster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxmehl%2Finwx-dns-recordmaster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxmehl%2Finwx-dns-recordmaster/lists"}