CNX Documentation

aliases.yml format

aliases.yml defines DNS names whose target is another hostname rather than a fixed IP address.

CNX resolves the target and publishes the resulting address records at the configured name.

Format

One alias per line:

www.example.com.: cdn.some-provider.net.
example.com.:     app.some-platform.io.

The value on the left is the name CNX publishes.

The value on the right is the hostname CNX resolves.

Both names must be fully qualified domain names and should end with a trailing dot.

For example:

api.example.com.: service.vendor.example.

means:

CNX resolves:

service.vendor.example. → A / AAAA

CNX publishes:

api.example.com. → A / AAAA

The configured target itself is not published as a CNAME.

Rules

  • CNX publishes the A and AAAA records obtained from the configured target.
  • CNX derives the published TTL from the target's own DNS TTL and updates it whenever the target is checked again.
  • CNX re-resolves the target periodically and updates the published addresses when the target changes.
  • Each DNS name is managed in exactly one place: aliases.yml or zone.conf, never both.
  • An alias cannot replace a delegation. If api.example.com. is itself a separately delegated zone, api.example.com. cannot also be managed as an alias in the parent zone.
  • Removing an entry from aliases.yml stops CNX managing that name. Its flattened records are removed on the next processing cycle.
  • If CNX cannot resolve the configured target successfully, it does not publish new address records for that alias. The failure is recorded in the zone activity log.

Target resolution

The target must ultimately resolve to usable A, AAAA, or both address records.

If the target resolution fails, returns no usable address records, or otherwise cannot be flattened, CNX records the failure and the alias is not published.

Check the zone activity report if an alias is not appearing as expected.

Example

www.example.com.: cdn.some-provider.net.
example.com.:     app.some-platform.io.

CNX may publish:

www.example.com.    A       192.0.2.20
www.example.com.    AAAA    2001:db8::20

example.com.        A       192.0.2.30
example.com.        AAAA    2001:db8::30

The exact addresses and TTLs follow the resolved targets and may change over time.

See Setting up aliases.yml for configuration instructions, and CNAME flattening for the underlying DNS behaviour.