Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function changes the server's hostname.

Warning:

  • Do not select a hostname that begins with www or a number, or a hostname that ends with a hyphen (-).
  • You must use a fully-qualified domain name (FQDN) that contains two periods (for example, hostname.example.com).
  • Do not choose a hostname that a cPanel account on your server will use.
  • Do not choose a potential proxy subdomain as a hostname (for example, cpanel.example.com or whm.example.com).

Important:

If you update your hostname, the system blocks user access to the following interfaces and services:

  • Horde Webmail
  • Calendars and Contacts (CalDAV and CardDAV)

The system restores access to these interfaces and services after the hostname update finishes. For more information, read our Interface Lock Scripts documentation.

Note:

Whenever you change the server's hostname, you must use one of the following methods: 

These methods ensure that all of the necessary system and service changes occur.

 

 

 

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/sethostname?hostname=hostname.example.com
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/sethostname?hostname=hostname.example.com
 Command Line
whmapi0 sethostname hostname=hostname.example.com

Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 0 documentation or run the whmapi0 --help command. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
   "sethostname":[
      {
         "status":1,
         "statusmsg":"Hostname Changed to: host.example.com",
         "msgs":"Updating Apache configuration\nUpdating Internal cPanel 
          Information....\n.\nDone",
         "warns":[
            "\tWhostmgr::XMLUI::Hostname::sethostname('hostname', 'host.example.com') 
          called at whostmgr/bin/xml-api.pl line 133\n",
         ]
      }
   ]
}
 Output (XML)
<sethostname>
    <sethostname>
        <msgs>Updating Apache configuration
                    Updating Internal cPanel Information.....
                    Done</msgs>
        <status>1</status>
        <statusmsg>Hostname Changed to: host.example.com</statusmsg>
        <warns>main::runapp() called at whostmgr/bin/xml-api.pl line 583</warns>
    </sethostname>
</sethostname>

   

Parameters

ParameterTypeDescriptionPossible valuesExample
hostnamestring

Required

The server's new hostname.


 

A valid hostname.

Important

The server's hostname must never be identical to the domain name. For example, if the domain is example.com, use a hostname like server1.example.com, but do not use example.com.  

hostname.example.com

 

Returns

ReturnTypeDescriptionPossible valuesExample
sethostnamehash

An array of hashes of the function's status.

This hash includes the statusstatusmsgmsg, and warns returns. 

status

Boolean

Whether the function succeeded.

The function returns this value in the sethostname hash.

  • 1 — Success.
  • 0 — Failure.
1

statusmsg

string

A message of success or a reason for failure.

The function returns this value in the sethostname hash.

A valid string.
Hostname Changed to: host.example.com

msg

string

Information from the server about the function.

The function returns this value in the sethostname hash.

A valid string.
Updating Apache configuration
Updating Internal cPanel Information.....
Done

warns

string

Detailed information about any issues.

The function returns this value in the sethostname hash.

A valid string.
main::runapp() called at whostmgr/bin/xml-api.pl line 583