All Products
Search

This Product

    VPN Gateway:Configure custom DNS for SSL-VPN clients

    Document Center

    VPN Gateway:Configure custom DNS for SSL-VPN clients

    Last Updated:Jun 02, 2026
    Important

    This feature is currently available in the following regions: Philippines (Manila), Thailand (Bangkok), and Malaysia (Kuala Lumpur).

    Configure private DNS server addresses on the SSL-VPN server so clients can resolve private domain names within a VPC.

    How it works

    image

    SSL-VPN custom client DNS uses the OpenVPN DHCP Option mechanism. The workflow is as follows:

    1. Enable the SSL Server switch on the Custom Client DNS and enter up to two private DNS server IPs within the VPC.

    2. The SSL-VPN server pushes the DNS configuration to the client.

    3. After the client connects, it automatically receives the DNS server addresses from the server.

    4. The OS sets these as the preferred DNS for the active connection.

    5. DNS queries (e.g., git.internal or example.com) route through the VPN tunnel to the VPC DNS server for resolution.

    Limitations

    • Maximum two DNS server addresses (primary and secondary).

    • The system does not verify DNS server reachability. Ensure the specified IPs can serve DNS within the VPC.

    • Some clients require additional configuration. macOS (Tunnelblick) applies DNS automatically. Windows may need a network adapter metric change. Linux requires script-based configuration.

    • Not supported on iPhone, iPad, or Android.

    • Domain-name-format DNS addresses are not supported.

    • Dynamic DNS updates are not supported.

    • IPv6 DNS addresses are not supported.

    Procedure

    Prerequisites

    • You have connected the client to the VPC by following the instructions in the Quick start guide. If you are using macOS, use the Tunnelblick client.

    • A DNS server (Windows AD DNS, CoreDNS, BIND, etc.) is running in the VPC.

    • The security group of the DNS server allows inbound traffic on UDP port 53 from the Client CIDR Block.

    Step 1: Enable custom DNS

    Console

    1. In the Actions column of the SSL server, click Edit.

    2. Enable the Custom Client DNS switch and configure:

      • DNS Server Address 1: Enter the private IP address of a DNS server deployed in your VPC.

      • DNS Server Address 2: Optional. Enter the IP address of a secondary DNS server.

    API

    Call the ModifySslVpnServer API operation and use the DnsServers parameter to set the DNS server addresses.

    Step 2: Configure the client

    Choose the method for your OS. macOS (Tunnelblick) applies DNS automatically on connect. Linux requires .ovpn file modifications.

    Windows

    1. Right-click the OpenVPN client icon in the system tray and select Reconnect.

    2. Run nslookup example.com in Command Prompt. Replace example.com with your private domain name. A correct private IP in the response confirms the DNS configuration works.

    Important

    If DNS does not work:

    1. Check network adapter metrics:

      netsh interface ip show config

      A lower metric value indicates a higher network adapter priority.

    2. If the VPN adapter does not have the lowest metric, set it:

      netsh interface ip set interface "OpenVPN TAP-Windows" metric=10

      The network adapter created by the OpenVPN client for the VPN tunnel typically has a name that starts with 'OpenVPN TAP-Windows'. Replace 'OpenVPN TAP-Windows' with the actual VPN adapter name on your system.

    Mac

    1. In the Tunnelblick client, disconnect and then reconnect.

    2. Run dig example.com in Terminal. Replace example.com with your private domain name. A correct private IP in the response confirms the DNS configuration works.

    CentOS/AliOS

    1. Add the following lines to the end of config.ovpn in /etc/openvpn/conf:

      script-security 2
up /etc/openvpn/conf/client.up
down /etc/openvpn/conf/client.down
down-pre

    2. Copy client.up and client.down from the OpenVPN contrib directory to the config directory and make them executable:

      sudo cp /usr/share/doc/openvpn/contrib/pull-resolv-conf/client.up /etc/openvpn/conf/
sudo cp /usr/share/doc/openvpn/contrib/pull-resolv-conf/client.down /etc/openvpn/conf/
sudo chmod +x /etc/openvpn/conf/client.up
sudo chmod +x /etc/openvpn/conf/client.down

    3. In both client.up and client.down, change the following code to if false; then:

      image

    4. Restart the openvpn process:

      sudo killall openvpn
sudo openvpn --config /etc/openvpn/conf/config.ovpn --daemon

    5. Verify the DNS update:

      cat /etc/resolv.conf

    6. Run dig example.com. Replace example.com with your private domain name. A correct private IP confirms DNS works.

    Important

    To disable custom DNS:

    1. Disconnect from the SSL-VPN:

      sudo killall openvpn

    2. Edit config.ovpn in /etc/openvpn/conf. Comment out the four lines starting with script-security, up, down, and down-pre.

    3. Restart OpenVPN to reconnect:

      sudo openvpn --config /etc/openvpn/conf/config.ovpn --daemon

    Ubuntu

    1. Download the certificate again from the Alibaba Cloud console. In the SSL Client column for the target Actions, click Download Certificate.

    2. Back up the existing certificate in /etc/openvpn/conf by moving it to another directory.

    3. Place the new certificate in /etc/openvpn/conf.

    4. Edit the config.ovpn file and uncomment the last four lines:

      image

    5. Install resolvectl (systemd-resolved CLI):

      apt install systemd-resolved

    6. Set tun0 DNS as the global default (~. matches all domains):

      resolvectl domain tun0 "~."

    7. Restart the openvpn process:

      sudo killall openvpn
sudo openvpn --config /etc/openvpn/conf/config.ovpn --daemon

    8. Verify the DNS update:

      resolvectl status tun0

    9. Run dig example.com. Replace example.com with your private domain name. A correct private IP confirms DNS works.

    Important

    To disable custom DNS:

    1. Disconnect from the SSL-VPN:

      sudo killall openvpn

    2. Edit config.ovpn in /etc/openvpn/conf. Comment out the four lines starting with script-security, up, down, and down-pre.

    3. Restart OpenVPN to reconnect:

      sudo openvpn --config /etc/openvpn/conf/config.ovpn --daemon

    FAQ

    DNS settings do not take effect

    • Ensure the DNS server subnet is included in the Local CIDR Block configured for the SSL Server. If not, add it to the Local CIDR Block.

    • Ensure the DNS server allows requests from the Client CIDR Block (the IP pool allocated to SSL-VPN clients).

    • Ensure that the security group of the DNS server allows UDP port 53 traffic.

    • Check if other VPNs or network software are overriding the DNS settings.

    • For Windows clients, also check the following:

    • For CentOS/AliOS clients, also check the following:

      • Ensure script-security 2 and up/down script lines are in the .ovpn file.

      • Ensure client.up and client.down exist in /etc/openvpn/conf/.

      • Check /etc/resolv.conf for the configured DNS address.

    • For Ubuntu clients, also check the following:

      • Ensure the certificate was re-downloaded and the last four lines in the .ovpn file are uncommented.

      • Ensure the DNS update scripts (update-resolv-conf or update-systemd-resolved) exist on the system.

      • Run resolvectl status to verify the configured DNS address appears.

    Re-downloading the client certificate

    Certificate re-download is only required for Ubuntu clients.

    IPv6 address support

    No. Only DNS servers with IPv4 addresses are supported.

    Unreachable DNS servers

    The system does not verify DNS server reachability. If configured servers are unreachable, clients cannot resolve domain names after connecting. Ensure the DNS servers are operational and their subnets are included in the SSL-VPN routing configuration.

    Using a non-VPC DNS server

    Yes. For example, you can set the DNS server addresses on the SSL server to a DNS server in your on-premises data center.