Add a Custom Domain Name (DNS Alias Mode)

Yeastar Central Management allows you to customize the domain name of P-Series Cloud PBX, so as to establish your own brand of Cloud PBXs. This topic describes how to add a custom domain name, and automatically manage certificate issuance and renewal via DNS alias mode without requiring your DNS provider's API credentials.

Introduction

Yeastar Central Management supports two methods for domain certificate management:

  • DNS API Mode: The system automatically interacts with your DNS provider's native API to complete certificate application and renewal. It dynamically adds and removes DNS TXT records required for ACME challenge, handling issuance and renewal without manual intervention. This method requires you to provide API credentials for your DNS provider. For more information, see Add a Custom Domain Name (DNS API Mode).

  • DNS Alias Mode: The system uses CNAME delegation to complete certificate application and renewal without requiring any API credentials. You manually add a one-time, static DNS CNAME record during initial setup to delegate SSL verification authority. After that, the system handles certificate renewal automatically. For more information, see the instructions in this topic.

Requirements and restrictions

Requirements
  • You have purchased sufficient custom domain quotas for the Custom Domain service.
    Note: If you have subscribed to the White Label service, one custom domain quota is provided by default.
  • You have added a DNS provider for DNS Alias mode in the system if you want the system to request or refresh domain certificates automatically.
Restriction

Once the domain is successfully deployed, it cannot be changed. You can only delete the domain and re-deploy it.

Background information

To add a custom domain name, you need to deploy two wildcard domain names on Yeastar Central Management, including a PBX wildcard domain name and a SBC Proxy Server domain name.
  • The PBX wildcard domain name, namely the custom domain name you are about to add, will be used as the suffix of a Cloud PBX URL. The domain name should be resolved to the IP address of the back-end SBC server.
  • The domain name of SBC Proxy Server, which is associated with the PBX wildcard domain name, will be used to compose the server address for specific PBX features, including Register Trunk, Port-Based Peer Trunk, DID-Based Peer Trunk, LDAP, SSH, AMI, and Database Grant.

Step 1. Obtain server information and CNAME targets

Obtain the cluster servers' IP addresses, automatically generated SBC Proxy domain names, and the corresponding CNAME targets for certificate validation.
  1. Log in to Yeastar Central Management, go to Cloud PBX > Custom Domain, then click Add.
  2. In the Region drop-down list, select the region where you want to add a custom domain name.

    The system automatically recognizes and displays the IP address of SBC Server and SBC Proxy Server that are deployed in the region.

  3. Obtain the cluster server's IP addresses, and the SBC Proxy Server domain name.

    1. In the PBX Wildcard Domain field, enter your SBC Server domain name.

      SBC Proxy Domain displays the SBC Proxy Server domain name accordingly.

    2. Note down the corresponding SBC Proxy Server domain name.
      Note: If you have deployed more than one SBC Proxy Server in the region, click Add and note down another IP address and domain name for the additional SBC Proxy Server.
    3. Note down both the IP addresses of the SBC Server and SBC Proxy Server.
  4. Obtain the CNAME targets.

    1. In the Operations column of SBC Domain Name section, click .
    2. In the pop-up window, select Apply for a certificate.
    3. In the DNS Provider drop-down list, select the DNS provider you added for DNS Alias Mode.
    4. Note down the generated Certificate CNAME Record Name and Certificate CNAME Record Target Domain.
    5. In the SBC Porxy Domain Name section, click and repeat step b - d to obtain the CNAME target for SBC Proxy Server.

Step 2. Configure DNS records on your DNS Provider

Add the required DNS records (A records and CNAME records) on your DNS provider's management console.

  1. Log in to your DNS provider's management console.
  2. Add the following DNS records your the domain name.
    • A records

      Set up domain forwarding to resolve the domain names to the corresponding server IP addresses.

      Domain Name Record Type IP Address
      PBX wildcard domain name *.docs.yeastar.com A SBC IP address 123.123.123.123.
      SBC Proxy domain name *.proxy1.docs.yeastar.com A SBC Proxy IP address 124.124.124.124
    • CNAME records

      Add CNAME records to point the validation domain names to the CNAME target domains generated by Yeastar Central Management.

      Domain Name Record Type Target Domain
      SBC Server's certificate CNAME record name

      _acme-challenge.docs.yeastar.com

      		 CNAME SBC Server's certificate CNAME record target domain

      docs.yeastar.com.cm.acme-alias.com
      SBC Proxy Server's Certificate CNAME Record Name

      _acme-challenge.proxy1.docs.yeastar.com

      		 CNAME SBC Proxy Server's certificate CNAME record target domain

      proxy1.docs.yeastar.com.cm.acme-alias.com

Step 3. (Optional) Prepare domain certificates

Purchase and download SSL certificates from Certified Authority (CA).

Note: If you want to apply for domain certificates directly on Yeastar Central Management without manually handling certificates, skip this step.
  1. Purchase wildcard SSL certificates for the domain names.

    In this example, purchase wildcard SSL certificates for the domain name *.docs.yeastar.com and *.proxy1.docs.yeastar.com.

  2. Download the wildcard SSL certificates and private keys.
    Note:
    • Yeastar P-Series Cloud PBX uses NGINX as web server, so the downloaded SSL certificates should be compatible with NGINX server.
    • RSA private key and EC private key are supported to secure the custom domain.

Step 4. Deploy domain certificates

Deploy certificates for the domain names via either of the following methods according to your needs.
Automatic certificate deployment
You can directly apply for certificate on Yeastar Central Management, the system will automatically request domain certificates from Let's Encrypt via your DNS provider.
  1. Log in to Yeastar Central Management, go to Cloud PBX > Custom Domain.
  2. Click Add.
  3. In the SBC Domain Name section, configure domain name and certificate for SBC Server.

    1. In the PBX Wildcard Domain field, enter your custom domain name.
    2. In the Operations column, click to configure domain certificate.
    3. In the pop-up window, select Apply for a certificate.
    4. In the DNS Provider drop-down list, select the DNS provider you added for DNS Alias mode.
    5. Click Confirm.
  4. In the SBC Proxy Domain Name section, configure domain name(s) and certificate(s) for SBC Proxy Server(s).

    1. In the SBC Proxy IP Address drop-down list, select the IP address of a SBC Proxy Server.

      A domain name corresponding to the IP address is automatically generated based on the SBC wildcard domain name set in the previous step.

    2. In the Operations column, click to configure domain certificate.
    3. In the pop-up window, select Apply for a certificate.
    4. In the DNS Provider drop-down list, select the DNS provider you added for DNS Alias mode.
    5. Click Confirm.
    6. Optional: Click Add to configure domain name and certificate for additional SBC Proxy Server.
  5. Click Save.
Manual certificate deployment
  1. Log in to Yeastar Central Management, go to Cloud PBX > Custom Domain.
  2. Click Add.
  3. In the SBC Domain Name section, do as follows:

    1. In the PBX Wildcard Domain field, enter your custom domain name.
    2. In the Operations column, click to configure domain certificate.
    3. In the pop-up window, select Upload certificate.
    4. Upload the certificate file and private key.
      • Certificate File: Click Browse to select the certificate file in the format of .cer, .crt, or .pem.
        Important: The certificate file must include a COMPLETE Certificate Chain, including the Root CA Certificate, the Intermediate Certificate, and the Server Domain Certificate.
      • Certificate Private Key: Click Browse to select the private key in the format of .key.
        Note: The supported content formats are as follows:
        • Start with -----BEGIN RSA PRIVATE KEY----- and end with -----END RSA PRIVATE KEY-----.
        • Start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----.
        • Start with -----BEGIN EC PRIVATE KEY----- and end with -----END EC PRIVATE KEY-----.
    5. If you want the system to automatically refresh the certificate, select the checkbox of Automatically refresh the certificate, then select your DNS provider (DNS Alias Mode) in the DNS Provider drop-down list.
      Note:
      • The system will automatically refresh the certificate 7 days before it expires using the provided DNS provider.
      • If auto-refresh is enabled but your certificate is not from Let's Encrypt, the system will automatically apply for a new one from Let's Encrypt instead.
    6. Click Confirm.
  4. In the SBC Proxy Domain Name section, do as follows:

    1. In the SBC Proxy IP Address drop-down list, select the IP address of SBC Proxy Server.
    2. In the Operations column, click .
    3. In the pop-up window, select Upload certificate.
    4. Upload the certificate file and private key.
      • Certificate File: Click Browse to select the certificate file in the format of .cer, .crt, or .pem.
        Important: The certificate file must include a COMPLETE Certificate Chain, including the Root CA Certificate, the Intermediate Certificate, and the Server Domain Certificate.
      • Certificate Private Key: Click Browse to select the private key in the format of .key.
        Note: The supported content formats are as follows:
        • Start with -----BEGIN RSA PRIVATE KEY----- and end with -----END RSA PRIVATE KEY-----.
        • Start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----.
        • Start with -----BEGIN EC PRIVATE KEY----- and end with -----END EC PRIVATE KEY-----.
    5. If you want the system to automatically refresh the certificate, select the checkbox of Automatically refresh the certificate, then select your DNS provider in the DNS Provider drop-down list.
      Note:
      • The system will automatically refresh the certificate 7 days before it expires using the provided DNS provider.
      • If auto-refresh is enabled but your certificate is not from Let's Encrypt, the system will automatically apply for a new one from Let's Encrypt instead.
    6. Optional: If you want to deploy domain names for more than one SBC Proxy Server, click Add to upload the certificate for another SBC Proxy Server domain name.
  5. Click Save.

Result

  • After the domain certificates are uploaded or successfully applied, the Certificate Status displays Deployed, indicating that the custom domain name is added successfully.

  • If the domain certificates is applied by Yeastar Central Management, or you have enabled auto renewal when uploading certificates, the system will automatically refresh the certificates 7 days before it expires.

What to do next

Now you can create Cloud PBXs with your custom domain in the region.

When creating a P-Series Cloud PBX in the region on Cloud PBX > PBX, you can see and select the custom domain name in the suffix of URL.

Note: For your resellers in the region, they can only see and use your custom domain name to create Cloud PBXs.