cPanel API 2 Functions - SSL::getcnname

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.


Description

This function lists SSL certificate information for a cPanel service.

Warning:

We strongly recommend that you use the following UAPI function instead of this function:

  • SSL::get_cn_name — This function retrieves the most secure domain for a service.

Examples


WHM API (JSON)

https://hostname.example.com:2087/cpsess###########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=SSL&cpanel_jsonapi_func=getcnname&domain="example.com"&service="imap"&add_mail_subdomain="0"
Note:

For more information, read our Calls from the WHM API documentation.


LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// Get certificate information for example.com's IMAP server.
$get_certificate_info = $cpanel->api2(
    'SSL', 'getcnname',
    array(
        'domain'               => 'example.com',
        'service'              => 'imap',
        'add_mail_subdomain'   => '0',
    )
);
Note:

For more information, read our Guide to the LiveAPI System.


LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# Get certificate information for example.com's IMAP server.
my $get_certificate_info = $cpliveapi->api2(
    'SSL', 'getcnname',
    {
        'domain'               => 'example.com',
        'service'              => 'imap',
        'add_mail_subdomain'   => '0',
    }
);
Note:

For more information, read our Guide to the LiveAPI System.


cPanel Tag System (deprecated)

Warnings:
  • In cPanel & WHM version 11.30 and later, cPanel tags are deprecated . We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI .
  • cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
  • For more information, read our Deprecated cPanel Tag Usage documentation.

Command Line

cpapi2 --user=username SSL getcnname domain=example.com service=imap add_mail_subdomain=0
Notes:
  • You must URI-encode values.
  • username represents your account-level username.
  • You must include the --user=username option.
  • For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command.
  • If you run CloudLinux™, you must use the full path of the cpapi2 command:
    /usr/local/cpanel/bin/cpapi2

Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "func": "getcnname",
    "data": [
      {
        "is_self_signed": 1,
        "ssldomain": "example.com",
        "is_wild_card": 0,
        "ssldomain_matches_cert": 1,
        "cert_match_method": "hostname",
        "cert_valid_not_after": "1436471749"
      }
    ],
    "event": {
      "result": 1
    },
    "module": "SSL"
  }
}
Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.


Parameters

Parameter Type Description Possible values Example
domain string

Required

The domain name.

An SSL-enabled domain on the cPanel account.

example.com
service string

Required

The service for which to retrieve information.

  • imap — Return IMAP server information.
  • pop3 — Return POP3 server information.
  • smtp — Return SMTP (Exim) server information.
  • dav — Return Web Disk information.
  • cpanel— Return cPanel & WHM information.

If you specify imap or pop3, the mail server must be configured, and cannot be disabled.

imap
add_mail_subdomain Boolean

Whether to append mail or www onto the domain value in order to find a match.

For example, if you specify the domain example.com and enable this option, the function searches for service information from mail.example.com, www.example.com, and example.com.

This parameter defaults to 0.

  • 1 — Append mail and www onto the domain value during search.
  • 0 — Match on the specified domain value only.
0

Returns

Return Type Description Possible values Example
is_self_signed Boolean Whether the certificate is a self-signed certificate.
  • 1 — Self-signed certificate.
  • 0 — Third-party certificate.
1
ssldomain string The domain for which the certificate was issued. A valid domain name. example.com
is_wild_card Boolean Whether the certificate is a wildcard certificate.
  • 1 — The certificate is a wildcard certificate.
  • 0 — The certificate is not a wildcard certificate.
0
ssldomain_matches_cert Boolean Whether the certificate information matches the domain.
  • 1 — The certificate and domain match.
  • 0 — The certificate and domain do not match.
1
cert_match_method string The type of match.
  • hostname — The certificate hostname and the domain hostname match.
  • exact — All certificate and domain details match.
  • exact-wildcard — All certificate and domain details match for a wildcard certificate.
  • www-wildcard — The certificate matches the domain value when the system appends www.
  • mail-wildcard — The certificate matches the domain value when the system appends mail.
  • localdomain_on_cert — The certificate matches another domain on the server.
  • localdomain_on_cert-www-wildcard — The certificate matches another domain on the server when the system appends www.
  • localdomain_on_cert-mail-wildcard — The certificate matches another domain on the server when the system appends mail.
hostname
cert_valid_not_after integer The certificate's expiration date. The certificate's expiration date, in Unix time. 1436471749
reason string

A reason for failure. This function only returns a reason value if there was an error.

A string that describes the error. This is an error message.
result Boolean

Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.
1