Child pages
  • cPanel API 2 Functions - SSL::getcnname
Skip to end of metadata
Go to start of metadata

 

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 best domain to use for SSL 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 run the --user=username command.
  • 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

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

The domain name.

An SSL-enabled domain on the cPanel account.

example.com
servicestring

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.

Note:

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

imap
add_mail_subdomainBoolean

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

ReturnTypeDescriptionPossible valuesExample
is_self_signedBooleanWhether the certificate is a self-signed certificate.
  • 1 — Self-signed certificate.
  • 0 — Third-party certificate.
1
ssldomainstringThe domain for which the certificate was issued.A valid domain name.example.com
is_wild_cardBooleanWhether the certificate is a wildcard certificate.
  • 1 — The certificate is a wildcard certificate.
  • 0 — The certificate is not a wildcard certificate.
0
ssldomain_matches_certBooleanWhether the certificate information matches the domain.
  • 1 — The certificate and domain match.
  • 0 — The certificate and domain do not match.
1
cert_match_methodstringThe 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_afterintegerThe certificate's expiration date.The certificate's expiration date, in Unix time.1436471749
reasonstring

A reason for failure.

Note:

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


A string that describes the error. This is an error message.
resultBoolean

Whether the function succeeded.

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