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

 

Introduction

cPanel & WHM supports secure remote logins via the Cpanel::LogMeIn module.

Important:

  • API calls that use a method that includes a URL must use the correct port:
    • 2082 — Unsecure calls to cPanel's APIs.
    • 2083 — Secure calls to cPanel's APIs.
    • 2086 — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
    • 2087 — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
    • 2095 — Unsecure calls to cPanel's APIs via a Webmail session.
    • 2096 — Secure calls to cPanel's APIs via a Webmail session.
    Otherwise-correct calls will return Permission denied or Function not found errors if they use an incorrect port number. 
  • This document only includes cPanel & WHM authentication methods. For Manage2 authentication information, read our Guide to the Manage2 API documentation.

Secure remote logins

To allow users to log in to cPanel & WHM remotely, write a script that calls the Cpanel::LogMeIn module's get_loggedin_url() subroutine. This subroutine returns a URL for remote logins to cPanel, WHM, or Webmail.

  • In cPanel & WHM version 11.38.0 and earlier, the URL is a single-use URL.
  • cPanel & WHM version 11.38.1 introduced reusable remote login URLs. These URLs expire when the user logs out, or after a normal session timeout.

Parameters

When you call the get_loggedin_url() subroutine, you must pass in the following parameters:

ParameterTypeDescriptionPossible valuesExample
userstring

Required

The cPanel, WHM, or Webmail username.

A valid username.

In most scripts, retrieve this value from user input.

username
passstring

Required

The account's password.

A secure password.

In most scripts, retrieve this value from user input.

12345luggage
hostnamestring

Required

The cPanel, WHM, or Webmail account's main domain.

A valid domain on the server.example.com
servicestring

Required

The account's service type.

  • cpanel
  • whm
  • webmail
cpanel
goto_uristring

Required

The location to which the script will redirect the user. The get_loggedin_url() subroutine uses this value to create the URL.

A valid path, relative to the /usr/local/cpanel/base/ directory./frontend/paper_lantern/park/index.html

Returns

The get_loggedin_url() subroutine returns the following values:

ReturnTypeDescriptionPossible valuesExample
login_okbooleanWhether the function authenticated the user successfully.
  • 1 — Success.
  • 0 — Failure.
1
login_messagestringA status message from the subroutine.
  • Login OK
  • An error message.
Login OK
login_urlstringThe secure remote login URL.A valid URL that includes a valid session token and directs the user to the goto_uri path.https://example.com:2083/cpsess##########/frontend/paper_lantern/park/index.html

Example Perl script

 Click to view...

Note:

This script reuses the session URL. For cPanel & WHM version 11.38.0 and earlier, you must call the get_loggedin_url() subroutine each time that you generate a URL. 

#!/usr/bin/perl 
 
use lib '/usr/local/cpanel';
use Cpanel::LogMeIn ();
  
# The cPanel, WHM, or Webmail username entered at login.
my $user    = 'YYYYYY'; 
 
# The cPanel, WHM, or Webmail password entered at login. 
my $pass    = 'XXXXXX';
 
# The cPanel, WHM, or Webmail account's main domain.
my $host    = 'localhost';
 
# The service to log in to (cpanel, whm, or webmail).
my $service = 'cpanel';
 
# Call the get_loggedin_url subroutine.
my ( $login_ok, $login_message, $login_url, $security_token ) = Cpanel::LogMeIn::get_loggedin_url(
    'user'     => $user,
    'pass'     => $pass,
    'hostname' => $host,
    'service'  => $service,
    'goto_uri' => '/'
);
  
# Set up HTTP headers with the returned values.
if ($login_ok) {
    print "Location: $login_url\r\n\r\n";
}
else {
    print "Content-type: text/plain\r\n\r\n";
    print "LOGIN FAILED: $login_message\n";
}
  
# Call the get_loggedin_url subroutine for a different URL.
( $login_ok, $login_message, $login_url, $security_token ) = Cpanel::LogMeIn::get_loggedin_url(
    'active_token_for_reuse'    => $security_token,                                                                                                                                                   
    'user'     => $user,
    'pass'     => $pass,
    'hostname' => $host,
    'service'  => $service,
    'goto_uri' => '/frontend/paper_lantern/park/index.html'
);
  
# Set up HTTP headers with the returned values.
if ($login_ok) {
    print "Location: $login_url\r\n\r\n";
}
else {
    print "Content-type: text/plain\r\n\r\n";
    print "LOGIN FAILED: $login_message\n";
}