Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

Set Hostname — sethostname

This function lets you change the server's hostname.

PICK Important: The server's hostname should absolutely not be identical to your domain name. For example, if your domain is example.com, you could use a hostname such as server1.example.com, but not example.com itself.

Calling Functions

Using the XML API

To use the XML API to perform the sethostname function from within your custom script:

  • Append the /xml-api/sethostname function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/xml-api/sethostname

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Using the JSON API

To use the JSON API to perform the sethostname function from within your custom script:

  • Append the /json-api/sethostname function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/json-api/sethostname

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Variables

Input

The sethostname function takes the following required variable as input:
  • hostname (string) — The new hostname for the server.

Output

Show Hide

  • sethostname — Root-level XML tag for the output of the sethostname function.
    • sethostname — Container for the results of the operation.
      • msgs (string) — Information from the server about the sethostname call.
      • status (boolean) — Status of the request.
        • 1 — success.
        • 0 — failure.
      • statusmsg (string) — Detailed information about the status of the request.
      • warns (string) — Detailed information about any problems encountered while setting the server's hostname.

Examples

XML API

Show Hide

Calling https://example.com:2087/xml-api/sethostname?hostname=host.example.com in WebHost Manager will result in output similar to the following:

<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>

JSON API

Show Hide

Calling the URL https://example.com:2087/json-api/sethostname?hostname=host.example.com in WebHost Manager will produce output similar to:

{
   "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",
         ]
      }
   ]
}

Topic revision: r6 - 29 Sep 2009 - 19:04:35 - MelanieSeibert