You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • WHM API 1 Functions - fetch_ssl_vhosts
Skip to end of metadata
Go to start of metadata

Description

This function lists the server's virtual hosts and their installed SSL certificates.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/fetch_ssl_vhosts?api.version=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/fetch_ssl_vhosts?api.version=1
 Command Line
whmapi1 fetch_ssl_vhosts


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
	"data": {
		"vhosts": [{
				"ipv6": "2001:0db8:0:0:1:0:0:1",
				"ip": "192.168.0.20",
				"needs_sni": 0,
				"is_primary_on_ip": 1,
				"user": "example",
				"mail_sni_status": 1,
				"type": "sub",
				"servername": "hostname.example.com",
				"domains": [
					"subdomain.example.com",
					"www.subdomain.example.com"

				],
				"docroot": "/home/example/public_html/directory_name",
				"crt": {
					"subject_text": "commonName\nsubdomain.example.tld",
					"modulus": "e20368382962bab56584a911657f01139552644739c571340c088d7c0e26b22b40169d2e898613158b4dd247190a68e8b5f67d197dfdc98c1e772cf6e1c71076d1f19df12289b1ac2cb4e55e1793ce918c8c3c86aaf2b4885e4e70d99ba356ef68c4ade805beedfbea84691659ab7e57f2ccc7246137a3fa444508d1f0f3ca78de2e10e041670f59ffa2eb2342f9b53c4c896b668f62577bc69ce80baeaa26f2845bb7117ffeae1d084e9ff62bf18517e32644906079f2fe5bafaa928d54a38be3b191d66b86ae1a6d23f03aa3874c1153a86f121729d8ea2bdd3ea8eb91115aa2a09abdf42d6a1b40b65ddbb337869d2455fa4e8f98d71047f34af505d69c27",
					"id": "example_sisko_tld_e2036_69c27_1612567898_0634f280090e7a6c141396da7c75cbf2",
					"issuer.organizationName": null,
					"subject.commonName": {
						"commonName": "subdomain.example.com"

					},
					"issuer_text": "commonName\nsubdomain.example.com",
					"not_after": 1612567898,
					"not_before": 1581031898,
					"signature_algorithm": "sha256WithRSAEncryption",
					"issuer.commonName": "subdomain.example.com",
					"public_exponent": "010001",
					"modulus_length": "2048",
					"ecdsa_curve_name":null,
					"ecdsa_public":null,
					"encryption_algorithm": "rsaEncryption",
					"created": 1581031898,
					"is_self_signed": "1",
					"domains": [
						"subdomain.example.com",
						"www.subdomain."

					],
					"validation_type": "dv"

				},
				"iptype": "shared"

			}

		]

	},
	"metadata": {
		"version": 1,
		"result": 1,
		"reason": "OK",
		"command": "fetch_ssl_vhosts"

	}
}
 Output (XML)
<result>
    <data>
        <vhosts>
            <iptype>dedicated</iptype>
            <needs_sni>0</needs_sni>
            <ipv6>2001:0db8:0:0:1:0:0:1</ipv6>
            <ip>192.168.0.20</ip>
            <type>sub</type>
            <domains>example.com</domains>
            <mail_sni_status>1</mail_sni_status>
            <servername>example.com</servername>
            <docroot>/home/example/public_html</docroot>
            <user>example</user>
            <crt>
                <subject_text>commonName\nsubdomain.example.tld</subject_text>
                <owner>
                    <example/>
                </owner>
                <is_self_signed>1</is_self_signed>
                <validation_type>dv</validation_type>
                <signature_algorithm>sha256WithRSAEncryption</signature_algorithm>
                <issuer.organizationName>cPanel L.L.C.</issuer.organizationName>
                <modulus>
                    e353aa25cc8ad05d3225611e4410c0270c11b2d46f88705d3d179a23102ab24ee167c1a9070b9f554e83bade1b84256e11c5a0cb2ac96b96f28e802b11c721d73fbfe61dd9839974a6fce4e17915c0fbf885056f18656041cf70db460b22cab5fd2502491e4ab9f0d2cb727480e0ebd62e83870acda31bfa2d4625efd82234f9729f351ea02fb162609c1654c11b5dec468539a3bb83073a85f78bcf577cd8b718501145cccd89d7adb0bb18c872e7303a15e2c75a6ab315c7fa099e4351a4f0ff126c2693f71d9f21d9f798b94bb689277083fea8dcc01b6af268d0ad8b7a481f8a179d07639cdf3290c93723937a767c400a8ce4b1ca19f0a7117084d5bc13
                </modulus>
                <subject.commonName>example.com</subject.commonName>
                <not_before>1376497388</not_before>
                <modulus_length>2048</modulus_length>
                <ecdsa_curve_name>null</ecdsa_curve_name>
                <ecdsa_public>null</ecdsa_public>
				<public_exponent>010001</public_exponent>
              	<encryption_algorithm>rsaEncryption</encryption_algorithm>
                <not_after>1408033388</not_after>
                <created>1376498495</created>
                <domains>example.com</domains>
                <issuer.commonName>example.com</issuer.commonName>
                <id>
                    example1_com_e353a_5bc13_1408033388_9a1d40aff655f98fed7206e5af466065
                </id>
                <issuer_text>
                    commonName
 example.com countryName US emailAddress username@example.com 
organizationName cPanel L.L.C. stateOrProvinceName Texas localityName 
Houston
                </issuer_text>
				<validation_type>null</validation_type>
            </crt>
            <is_primary_on_ip>1</is_primary_on_ip>
        </vhosts>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>fetch_ssl_vhosts</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

This function does not accept parameters.

Returns

ReturnTypeDescriptionPossible valuesExample
vhostshashA hash of the virtual host information.

This hash includes the iptype, needs_sni, ip, servername, docroot, and is_primary_on_ip, ipv6, type, and mail_sni_status returns, the domain array the crt hash.


iptype

string

The type of IP address.

The function returns this value in the vhosts hash.

  • shared
  • dedicated
dedicated

needs_sni

Boolean

Whether the virtual host requires SNI to function properly for SSL certificates.

The function returns this value in the vhosts hash.

  • 1 — Requires SNI.
  • 0 — Does not require SNI.
0

ipv6

string

The virtual host's IPv6 address.

The function returns this value in the vhosts hash.

A valid IPv6 address
2001:0db8:0:0:1:0:0:1

ip

string

The virtual host's IP address.

The function returns this value in the vhosts hash.

A valid IP address.192.168.0.20

domains

array

The virtual host's domains.

The function returns this array in the vhosts hash.

A list of valid domain names.
example.com

servername

string

The virtual host's primary domain.

The function returns this value in the vhosts hash.

A valid domain name.
example.com

docroot

string

The primary domain's document root.

The function returns this value in the vhosts hash.

A valid absolute directory path.
/home/example/public_html

user

string

The virtual host's user.

The function returns this value in the vhosts hash.

A valid username.
example

type

string

The virtual host's domain type.

The function returns this value in the vhosts hash.

  • addon — Addon domain.
  • main — Main domain on account.
  • parked — Parked domain.
  • sub — Subomain.
sub 

mail_sni_status

Boolean

Whether SNI for mail is enabled.

The function returns this hash in the vhosts hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

crt

hash

A hash of the certificate information.

The function returns this hash in the vhosts hash.

This hash includes the is_self_signed, signature_algorithm, validation_type, issuer.organizationNamemodulus, subject.commonName, not_before, modulus_length, not_after, created, issuer.commonName, id, subject_text, public_exponent, encryption_algorithm, validation_type, issuer_textecdsa_curve_name, and ecdsa_public returns, the domains array, and the owner hash.

subject_text

string

The certificate's subject text.

The function returns this hash in the crt hash.

A valid string.commonName\nsubdomain.example.tld

owner

hash

A hash of the certificate's owner information.

The function returns this hash in the crt hash.

This hash includes a return with the owner's name.

is_self_signed

Boolean

Whether the certificate is self-signed.

The function returns this value in the crt hash.

  • 1 — Self-signed.
  • 0Not self-signed.
1

signature_algorithm

string

The signature algorithm of the certificate.

Note:

We introduced this return in cPanel & WHM version 56.

The function returns this value in the crt hash.

A valid OID hash algorithm name.
sha256WithRSAEncryption

validation_type

string

The certificate's validation type.

Note:

We introduced this return in cPanel & WHM version 56.

The function returns this value in the crt hash.

  • ev — Extended Validation.
  • ov — Organization Validation.
  • dv — Domain Validation.
  • undef — The system could not parse and determine the certificate's validation type.
dv

issuer.organizationName

string

The organization that issued the certificate.

The function returns this value in the crt hash.

A valid string.
cPanel L.L.C.

modulus

string

The certificate's key's modulus, in hexadecimal format.

The function returns this value in the crt hash.

  • A valid string.
  • null — The certificate's key is not an RSA key.

Note:

We added the null value in cPanel & WHM version 92.

 Click to view...

 e353aa25cc8ad05d3225611e4410c0270c11b2d46f88705d3d179a23102ab24ee167c1a9070b9f554e83bade1b84256e11c5a0cb2ac96b96f28e802b11c721d73fbfe61dd9839974a6fce4e17915c0fbf885056f18656041cf70db460b22cab5fd2502491e4ab9f0d2cb727480e0ebd62e83870acda31bfa2d4625efd82234f9729f351ea02fb162609c1654c11b5dec468539a3bb83073a85f78bcf577cd8b718501145cccd89d7adb0bb18c872e7303a15e2c75a6ab315c7fa099e4351a4f0ff126c2693f71d9f21d9f798b94bb689277083fea8dcc01b6af268d0ad8b7a481f8a179d07639cdf3290c93723937a767c400a8ce4b1ca19f0a7117084d5bc13

subject.commonName

hash

A hash that contains the certificate's Common Name.

The function returns this value in the crt hash.

A hash that contains the commonName return.
                

commonName

string

The certificate's Common Name.

The function returns this value in the subject.commonName hash.

A valid domain name.example.com

not_before

string

When the certificate became active.

The function returns this value in the crt hash.

A valid date in Unix time format.
1376497388

public_exponent

string

The certificate's exponent.

The function returns this value in the crt hash.

A valid string.010001

modulus_length

integer

The certificate's key's modulus length.

The function returns this value in the crt hash.

  • A positive integer.
  • null — The certificate's key is not an RSA key.

Note:

We added the null value in cPanel & WHM version 92.

2048

encryption_algorithm

string

The certificate's key's algorithm.

The function returns this hash in the crt hash.

  • rsaEncryption

  • id-ecPublicKey

    Note:

    We added the id-ecPublicKey return in cPanel & WHM version 92.

rsaEncryption

not_after

integer

When the certificate expires.

The function returns this value in the crt hash.

A valid date in Unix time format.
1376497388

created

integer

When the certificate was created.

The function returns this value in the crt hash.

A valid date in Unix time format.
1376498495

domains

array

The certificate's associated domains.

The function returns this array in the crt hash.

A valid domain name.
example.com

issuer.commonName

string

The certificate's issuer.

The function returns this value in the crt hash.

A valid string, usually a domain.
example.com

id

string

The certificate's ID.

The function returns this value in the crt hash.

A valid string.
 Click to view...

example1_com_e353a_5bc13_1408033388_9a1d40aff655f98fed7206e5af466065

issuer_text

string

The full text of issuer information.

The function returns this value in the crt hash.

A valid string.
 Click to view...

 commonName\nexample.com\ncountryName\nUS\nemailAddress\nusername@example.com\norganizationName\ncPanel Inc.\nstateOrProvinceName\nTexas\nlocalityName\nHouston

validation_type

string

The certificate's validation type.

The function returns this value in the crt hash.

  • dv — Domain validation.
  • ev — Extended validation.
  • ov — Organizational validation.
  • null — Self-signed certificate.
dv

ecdsa_curve_name

string

The ECDSA curve that the certificate's key uses.

Note:

We added this return in cPanel & WHM version 92.

The function returns this hash in the crt hash.

  • A valid string.
  • null — The certificate's key is not an ECDSA key.
prime256v1

ecdsa_public

string

The certificate's key's ECDSA compressed public point, in hexadecimal format.

Note:

We added this return in cPanel & WHM version 92.

The function returns this hash in the crt hash.

  • A valid string.
  • null — The certificate's key is not an ECDSA key.
02a2cb73408a5833ffbe6eedac9227b9985c54a94990cc4a13ea2a57f3bdecada1

is_primary_on_ip

Boolean

Whether the certificate's domain is the IP address's primary domain.

The function returns this value in the vhosts hash.

  • 1 — Primary domain.
  • 0Not the primary domain.
1