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?api.version=1&hostname=hostname.example.com
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/sethostname?api.version=1&hostname=hostname.example.com
 Command Line
whmapi1 sethostname hostname=hostname.example.com

Notes:

  • 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. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
  "metadata": {
    "version": 1,
    "reason": "Hostname set to: hostname.example.com",
    "output": {
      "warnings": "The hostname was already set to hostname.example.com, syncing configuration only.",
      "messages": "Updating cPanel license...Done. Update succeeded.\n
Building global cache for cpanel...Done\n
Updating cPHulkd\nhulkdsetup: database schema is up to date."
    },
    "result": 1,
    "command": "sethostname"
  }
}
 Output (XML)
<result>
    <metadata>
        <version>1</version>
        <reason>Hostname set to: hostname.example.com</reason>
        <output>
            <warnings>
                The hostname was already set to hostname.example.com, syncing configuration only.
            </warnings>
            <messages>
                Updating cPanel license...Done. Update succeeded. 
Building global cache for cpanel...Done
Updating cPHulkd hulkdsetup: database schema is up to date.
            </messages>
        </output>
        <result>1</result>
        <command>sethostname</command>
    </metadata>
</result>

Note:

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

   

Parameters

ParameterTypeDescriptionPossible valuesExample
hostnamestring

Required

The server's new hostname.


 

A valid hostname.

Important

The server's hostname should never be identical to the domain name. For example, if the domain is example.com, you could use a hostname such as server1.example.com, but not example.com.  

hostname.example.com

Returns

Note:

The function outputs these returns in the metadata.


ReturnTypeDescriptionPossible valuesExample
outputhash

A hash of the function's output.

This hash includes the warnings and messages returns. 

warnings

string

Any of the function's warnings.

The function returns this value in the output hash.

A valid string.The hostname was already set to hostname.example.com, syncing configuration only.

messages

string

Any of the function's output messages.

The function returns this value in the output hash.

A valid string.

Updating cPanel license...Done. Update succeeded.

Building global cache for cpanel...Done

Updating cPHulkd hulkdsetup: database schema is up to date.