Set up wildcard subdomains

A wildcard DNS record, written as *, catches any subdomain that does not have its own record. One wildcard lets blog.example.com, shop.example.com, and any other name reach the same server, and your web server then decides which content to show based on the name requested.

Before you begin

• Your domain managed in the Lantern DNS editor, such as example.com.
• nginx installed and running. See Install and configure nginx if you have not done this yet.
• A sudo user, such as deploy, and SSH access to the server.

Step 1: Add the wildcard A record

In Lantern DNS, add a record with the name *, type A, value 203.0.113.10, and TTL 300. A wildcard only matches names that have no record of their own. If you already have a www record, it keeps working as before.

*.example.com.   300   IN   A   203.0.113.10

Step 2: Verify the wildcard in DNS

Query a few names that do not exist as separate records. Each should return your server's IP address.

dig +short blog.example.com A
dig +short some-random-name.example.com A

203.0.113.10
203.0.113.10

Note that a wildcard does not cover the bare domain, example.com. That name needs its own A record.

Step 3: Create a folder for each subdomain

This setup maps each subdomain to a folder named after its first label. For blog.example.com, the folder is /var/www/blog. Create a couple of example folders and a test page. The tee command writes the text to a file while letting sudo handle the permissions.

sudo mkdir -p /var/www/blog /var/www/shop
echo "<h1>Hello from the blog</h1>" | sudo tee /var/www/blog/index.html

Step 4: Write a wildcard server block

Create a new nginx site file with sudo nano /etc/nginx/sites-available/wildcard.conf. The regular expression after server_name captures the first label of the requested name into a variable called sub. The root line uses that variable to choose the folder.

server {
    listen 80;
    listen [::]:80;
    server_name ~^(?<sub>[a-z0-9-]+)\.example\.com$;

    root /var/www/$sub;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Enable the site by creating a symbolic link in sites-enabled, which nginx reads on startup:

sudo ln -s /etc/nginx/sites-available/wildcard.conf /etc/nginx/sites-enabled/

Step 5: Test and reload nginx

Check the configuration for errors, then reload nginx so the change takes effect.

sudo nginx -t
sudo systemctl reload nginx

nginx: configuration file /etc/nginx/nginx.conf test is successful

Step 6: Test one subdomain

Send a request with the Host header set, which lets you test before DNS has fully spread.

curl -H "Host: blog.example.com" http://203.0.113.10/

<h1>Hello from the blog</h1>

Step 7: Plan for HTTPS

New subdomains will show certificate warnings in browsers unless a certificate covers them. A wildcard certificate requires DNS validation, which needs API access to your DNS provider, so it is an advanced setup. The simpler route is one certificate per subdomain, as described in Enable HTTPS with free TLS certificates.

Troubleshooting

• A new subdomain shows the default nginx page. A more specific server block is matching first. Run grep -r server_name /etc/nginx/sites-enabled/ to see which names are claimed where.
• A 404 error. The matching folder is missing or has no index.html. Check with ls /var/www/blog.
• The bare domain does not resolve. Add an explicit A record for @ that points to the server, because the wildcard does not cover it.
• Permission denied in the error log. Open the log with sudo tail -n 20 /var/log/nginx/error.log. Make sure the folders and files are readable by the web server user.

Next steps

Once your subdomains work over plain HTTP, add HTTPS to each one. The steps are in Enable HTTPS with free TLS certificates. For more about DNS records, see Manage records in the Lantern DNS editor.