Manage DNS nameserver records of INWX domains via YAML files and API requests. Lightweight, fast, version-control ready.
Note: This is no official software project by INWX, it just kindly uses their public API.
This tool enables customers of INWX (formerly known as InterNetworX) to manage the DNS entries/records of their domains via files. This has multiple advantages:
- Version-control of nameserver entries, therefore a good record of what has changed over time.
- Very simple copy/paste of existing entries for new domains, e.g. when a new alias domain has been added.
- Enables search/replace, e.g. of IP addresses.
- Work can be done offline and quicker, and pushed once it's done. No waiting times for the sometimes slow web interface.
Configuration 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.
This Python program is available under the name inwx-dns-recordmaster. After installation, you can invoke it with the command inwx-dnsrm.
pipx makes installing and running Python programs easier and avoid conflicts with other packages. Install it with
pip3 install pipxThe following one-liner both installs and runs this program from PyPI:
pipx run inwx-dns-recordmasterIf you want to be able to use the program without prepending it with pipx run every time, install it globally like so:
pipx install inwx-dns-recordmasterThe 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.
To upgrade the program to the newest available version, run this command:
pipx upgrade inwx-dns-recordmasterYou may also use pure pip or poetry to install this package.
There are two types of configuration:
- App configuration: INWX API login data
- DNS records configuration: the desired state for each configured domain
You 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.
In 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.
DNS 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.
You can find an example DNS records configuration in the file records/example.com.yaml.sample. Here is a much shorter example:
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 TTLPlease 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.
However, there are default and extendable exceptions:
- By default, records of the type
SOAare not considered as they change upon each change and are handled well by INWX. You can add additional record types with the--ignore-typesargument if you don't want to handle them. - You can also blatantly ignore records that exist at INWX but not in your local configuration, using the
--preserve-remoteflag. This way, you only update existing and add new records, but don't delete unconfigured records at INWX.
If 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.
--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.
This is why you can also override these options in the YAML configuration files. Here is an example:
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"OpenRail Association is a user of INWX DNS Recordmaster to manage some of its domains. You can take inspiration from their
You can execute the program using the command inwx-dnsrm. inwx-dnsrm --help shows all available arguments and options.
The program has two main commands: sync and convert.
sync covers the main functionality, managing INWX domain records based on local configuration files whose format is explained above.
Some examples:
inwx-dnsrm sync -c records/: read the DNS records from therecords/directory, match them with the remote, and call the API to add, update, and delete entries for each locally configured domain.inwx-dnsrm sync -c records/ -d example.com: like the above, but only check the domainexample.comand ignore all other locally configured. If you have many domains, this may speed up operations.inwx-dnsrm sync -c records/ -p: run normally, but do not delete nameserver entries at INWX which are not configured locally.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.inwx-dnsrm sync --debug -c records/: run the whole program and show all debug messages.
Run inwx-dnsrm sync -h to see all options.
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.
Some examples:
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.inwx-dnsrm convert -d example.com > records/example.com.yaml: like the above, but write the configuration to a file so you don't have to copy it.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).
Run inwx-dnsrm convert -h to see all options.
Contributions are welcome! The development is easiest with poetry: poetry install and poetry run inwx-dnsrm will get you started.
The --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!
When running the sync command, this may also help:
--dryis recommended to play around with the program and avoid breaking your productive configuration.--interactivewill ask you before each change for a confirmation.
Oh 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.
If 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.
This could look like the following:
{
"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
}
]
}In 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):.
INWX has URL records 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. 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.
The main license of this project is the GNU General Public License 3.0, no later version (GPL-3.0-only), Copyright Max Mehl.
There may be components under different, but compatible licenses and from different copyright holders. The project is REUSE compliant which makes these portions transparent. You will find all used licenses in the LICENSES directory.