> ## Documentation Index
> Fetch the complete documentation index at: https://getyourfree.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Learn how to configure your subdomain with DNS records and additional settings.

To request a subdomain, you need to create a JSON configuration file that tells us how your subdomain should behave.

Each configuration file is added to the `domains/` directory in the repository and must follow specific naming conventions.

## Filename Requirements

Your configuration file must meet these criteria:

* Must be alphanumeric, in lowercase
* Dashes (-) may be used as separators
* Must be at least 1 character long
* Must have a `.json` file extension
* Must not contain the parent domain name

### Invalid Filename Examples

* `.json` (filename is less than 1 character)
* `A.json` (contains uppercase letters)
* `a..json` (contains consecutive dots)
* `.a.json` (starts with a dot)
* `a .json` (contains a space)
* `a$.json` (contains non-alphanumeric character)
* `a.json.json` (multiple .json extensions)

### Valid Filename Examples

* `a.json` (at least 1 character long)
* `example.json` (alphanumeric and lowercase)
* `blog.example.json` (includes dots for sub-subdomains)
* `my-blog.json` (uses dashes as separators)

> Note: To prevent monopolization, users are limited to one one-letter subdomain.

## Basic Structure

Here's what a minimal configuration looks like:

```json theme={null}
{
  "description": "My personal website",
  "repo": "https://github.com/username/repo",
  "owner": {
    "username": "your-github-username",
    "email": "yourname@example.com"
  },
  "records": {
    "CNAME": "username.github.io"
  },
  "proxied": false
}
```

## Required Fields

### owner

Information about the domain owner. This is required for communication if needed.

```json theme={null}
{
  "owner": {
    "username": "your-github-username",
    "email": "yourname@example.com"
  }
}
```

### records

Defines the DNS records for your subdomain. At least one record type is required.

## Optional Fields

### description

A brief description of your domain's purpose (optional but recommended).

### repo

Link to your website's repository or GitHub account (optional).

### proxied

Enable Cloudflare proxying for your domain (defaults to false).

```json theme={null}
{
  "proxied": true
}
```

## Supported DNS Records

### CNAME Record

Points your domain to another hostname.

```json theme={null}
{
  "records": {
    "CNAME": "username.github.io"
  }
}
```

### A Record

Maps your domain to IPv4 addresses.

```json theme={null}
{
  "records": {
    "A": [
      "192.0.2.1",
      "198.51.100.1"
    ]
  }
}
```

### AAAA Record

Maps your domain to IPv6 addresses.

```json theme={null}
{
  "records": {
    "AAAA": [
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
    ]
  }
}
```

### MX Record

Specifies mail servers for your domain.

```json theme={null}
{
  "records": {
    "MX": [
      {
        "target": "mx1.example.com",
        "priority": 10
      },
      {
        "target": "mx2.example.com",
        "priority": 20
      }
    ]
  }
}
```

### TXT Record

Stores text information, often used for verification.

```json theme={null}
{
  "records": {
    "TXT": ["v=spf1 include:_spf.example.com ~all"]
  }
}
```

### SRV Record

Defines service locations (e.g., VoIP, messaging, gaming servers).

```json theme={null}
{
  "records": {
    "SRV": [
      {
        "priority": 10,
        "weight": 5,
        "port": 8080,
        "target": "srv.example.com"
      }
    ]
  }
}
```

### CAA Record

Controls which Certificate Authorities can issue SSL certificates.

```json theme={null}
{
  "records": {
    "CAA": [
      {
        "flags": 0,
        "tag": "issue",
        "value": "letsencrypt.org"
      }
    ]
  }
}
```

## Important Notes

* Each domain requires its own configuration file
* JSON must be valid - use a JSON validator if needed
* Your subdomain request will be reviewed before approval
* You can update your configuration by submitting a new pull request
* Some record combinations may have restrictions (e.g., CNAME with other records)

Need help? Visit our [Get Started](/core/quickstart.mdx) guide or [open an issue](https://github.com/domainsproject/register/issues).