Add custom- and long-TXT-records

Introduction

This guide will give some insight in how to create custom resource records and maximum-length-exceeding TXT-records. Furthermore it integrates first troubleshooting steps.

A custom record allows a user to create any kind of resource record, even standard records which are not implemented, as well as unassigned and private usage records.

TXT records with a length of more than 255 bytes need to be split up. This guide helps you implementing these records with STACKIT DNS.

Prerequisites

• You have a STACKIT DNS zone: Manage DNS Zones

Custom records

Execution

STACKIT Portal

1. Navigate to Networking > DNS.

2. Click at the DNS zone you want to create an record in.

3. Choose the menu point Resource Records.

4. Click on Create Resource Record.

5. On the Creation pane on the Type select select CUSTOM.

   Select the CUSTOM resource record type:

   

   After selecting a new field appears. This is, because with the CUSTOM resource record type you have to specify the Type ID by yourself:

   

6. Enter a Type ID and the content of your custom record. You need to enter an officially assigned ID from the IANA standard. You find them in this list: IANA Domain Name System (DNS) Parameters.

   In this article we demonstrate this with the CDR record type, that has assigned the ID 59. Enter the actual data of the record to the Record data field.

   

   Keep in mind: The type of the requested record is CUSTOM and the ID has to be specified separately. So for the CDS type you need to enter 59 as type ID. The content has to match the standards in the RFC.

STACKIT API

Creating Custom Records works the almost same as creating any other record. The authorization and the API endpoints are identical: https://dns.api.stackit.cloud/v1/projects/{projectId}/zones/{zoneId}/rrsets.

You define the type, the type ID and the record data with the payload of your request. Consult the table to learn about the parameters:

Expand

Parameter	Meaning	Example
name	The name of the record.	my-cdr-record.my-example-project.runs.onstackit.cloud
records	An array of the records you want to create	[{"content": "1 1 1 10"}],
type	The type of your record. For custom records use TYPE followed by an officially assigned two digit type code. Consult IANA Domain Name System (DNS) Parameters for a list of types.	TYPE59

Your request body needs to contain these keys:

{
    "name": "[name]",
    "records": [records],
    "type": "[type]"
}

According to the examples in the table above, you can get an idea with this example request:

{
    "name": "customrecord.customzone.runs.onstackit.cloud",
    "records": [
        {
        "content": "1 1 1 10"
        }
    ],
    "type": "TYPE59"
}

FAQ and troubleshooting

If you have questions or encounter problems, consult the FAQ section of custom records.

Long-TXT-records

There are use cases in which you want to create resource records that are longer than 255 characters. A common use case is the creation of TXT records for DKIM. This section helps you achieving this task without manually splitting the resource record data. In the following code block you can see a shortened answer section of a query to a DKIM-record as a real world example:

# dig TXT tutorial._domainkey.at.stackit.rocks.
;; Truncated, retrying in TCP mode.

; <<>> DiG 9.18.33-S1 <<>> TXT tutorial._domainkey.at.stackit.rocks.
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 34220
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: f1613ddd35f5453001000000693abe1217faa35fd17f2c13 (good)
;; QUESTION SECTION:
;tutorial._domainkey.at.stackit.rocks. IN TXT

;; ANSWER SECTION:
tutorial._domainkey.at.stackit.rocks. 3600 IN TXT "v=DKIM1;t=s;p=MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAxBCl6zpXB7V6OEhsZofPdsT7MtYGIXkMwwA27CuZefU7mqxFqbUE4k6Gf1OHzC7LjpqyWtodFEnVSI7VkMk+2VLc0Vm4NHU4QpoxfVcHJGFFJWmsFbmxpOr/kMmTnE5s3+zuNNlEwl3OyLoicUH+2vYkyuekJtOIeaKoLX5Is4sIV1c1c2dAQo2tbs3HthR7iO7O/" "nByD2ltaM2p/DsIknxki8pxF5D+0PlCxuuUqW9wzWCtzJHkHou1D3s3FlllX98AFKTWBAtoraUQEnkT2RZUr/Te2b5ow6SEJVP1u8KePXpmT1COhy+rxcdJMyjunssza9Nfj/JJkhRXOkOBhH7X7tK7QlLvLaAFKkuNzv5eJBlsYzDl7Mnmq3e8FCXPkHScl5f0Al5ufb57v3FgscCNrcILPemx904TU3zRHvIWOMtuLlGgi5LAnUERG//Ysnh9" "U7Ky0GheWpR/S5p3oHNbHBoH1yZeyATtk5YTymw36fqw7yQq6mAjqMaERfxaXT7pUVnvitHfUGxnOam1wVFOk7aUiPeI3QkP4qOiZN/UFkuiwwbetBCg1r6ZUyWnyuqZLluGjLh7jzFWGOifKnnMH3T+FZo5XsLqu2YsTM96MUO/8TzOPCjVbWOzbZf0R6IlApBLW4vjnUBzCvEyNCgk8h/IaEBZLv/7uT165Q8CAwEAAQ=="

As always you have several possibilities to manage your STACKIT DNS records.

STACKIT Portal

The STACKIT Portal automatically splits payloads with a length of more than 255 bytes in its creation wizard. To create a DNS record with a length of more than 255 characters, follow these steps:

Open the Create resource record pane

1. Navigate to Networking > DNS.
2. Click at the DNS zone you want to create an record in.
3. Choose the menu point Resource Records.
4. Click on Create Resource Record.

Enter the details of your new resource record:

1. Add the Resource Record Name you want to create.

2. Choose the Time to Live for this record.

3. Choose the Type of the record. See Available record types for a list of possible records.

4. Add the Record data.

5. Add an optional Description for the record.

6. If the Record data exceeds 255 characters, a new icon appears (highlighted with the red square)

   

   When you click on the highlighted icon, a pane opens. There the system shows you, how it automatically splits your data into chunks, when you click on Create:

   

7. Click on Create. After successful creation the new record is visible in your Resource Records Overview.

STACKIT API

The STACKIT API creates the record as you provide it according to the limits of the RFC. This is the reason why you need to split the desired payload into chunks of 255 characters before calling the API. You can use the following script to split your desired payload into chunks of 255 characters in length:

#!/bin/bash

# Function to split a string into chunks of maximum length 255
split_string() {
local input_string="$1"
local max_length=255
local string_length=${#input_string}
local start=0
local end

echo -n "\""
while [ "$start" -lt "$string_length" ]; do
    end=$((start + max_length))
    if [ "$end" -gt "$string_length" ]; then
    end="$string_length"
    echo -n " "
    fi

    # Extract the substring
    local substring="${input_string:$start:$max_length}"

    # Print the substring (or do something else with it)
    echo -n "\\\"$substring\\\""

    # Move the starting position for the next chunk
    start="$end"
done
echo "\""
}

split_string "$1"

A resource record can hold more than one character string. For creating records longer than 255 characters, you only create one record but with multiple strings as payload. Thus you only make one API call to create one resource record.

After splitting the desired payload, call the API with the multiple chunks concatenated by spaces. Refer to the API reference on how to create resource records.