Child pages
  • UAPI Functions - KnownHosts::verify
Skip to end of metadata
Go to start of metadata

Description

This function checks whether a host's public key exists in the /home/user/.ssh/known_hosts file.

Examples  


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/KnownHosts/verify?host_name=host.example.com


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Verify the host
$verify = $cpanel->uapi(
    'KnownHosts', 'verify',
     array(
        'host_name'    => 'host.example.com';
     )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Verify the host
my $verify = $cpliveapi->uapi(
    'KnownHosts', 'verify',    {
        'host_name'    => 'host.example.com',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 cPanel Template Toolkit
<!-- Verify the host. -->
[% data = execute( 
   'KnownHosts', 'verify', {
        'host_name'    => 'host.example.com',
   } 
); %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username KnownHosts verify host_name=host.example.com


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{  
   "errors":null,
   "data":{
      "status": 0,
      "failure_type": new,
      "errors": [
          "The “host.example.com” host does not exist in the known_hosts file."
      ],
      "host": [
          {
            "host": "host.example.com",
            "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
            "line": "host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvu\P4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
            "meta": {
                "algorithm": "ssh-rsa",
                "body":  "AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9\bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
                "md5": "b6030e39979ed0e724cea3773e014209",
                "md5-printable": "MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09",
                "sha256": "44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc44",
                "sha256-printable": "SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ"
            }
          }
      ]
   },
   "status":1,
   "metadata":{  
   },
   "messages":null
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
host_namestring

Required

The host to query.

A valid hostname.

host.example.com

portinteger

The SSH port to use, if the system uses a non-standard SSH port.

If you do not supply a value, the function uses the standard SSH port (22).

A valid port number.1234

 

Returns

ReturnTypeDescriptionPossible valuesExample
statusBoolean

Whether the host already exists in the /home/user/.ssh/known_hosts file, where user represents the cPanel account's username.

  • 1 — The host already exists.
  • 0 — The host does not already exist, or the system must re-register the hostname.
0

failure_type

string

The reason why the system will register the hostname.

  • new — The host does not already exist.
  • changed — The host's information has changed.
new

errors

array

An array of errors that the system generated.

A valid array of strings.
 Click to view...
The “example.com” host does not exist in the known_hosts file.

host

array of hashes

An array of hashes of information for the host.

Each hash includes the host, key, and line returns and the meta hash.

host

string

The hostname.

The function returns this value in the host hash.

A valid hostname.host.example.com

key

string

The host's key.

The function returns this value in the host hash.

A valid algorithm and key.
 Click to view...

ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==

line

string

The host's entry in the /home/user/.ssh/known_hosts file, where user represents the cPanel account's username.

The function returns this value in the host hash.

A valid entry that includes the hostname, the key's algorithm, and the public key.
 Click to view...

host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==

meta

hash

A hash of metadata about the host's public key.

The function returns this hash in the host hash.

This hash includes the algorithm, body, md5, md5-printable, sha256, and sha256-printable returns.

algorithm

string

The key's algorithm.

The function returns this value in the meta hash.

A valid key algorithm.ssh-rsa

body

string

The host's public key.

The function returns this value in the meta hash.

A valid public key.
 Click to view...

AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==

md5

string

The key's MD5 fingerprint.

The function returns this value in the meta hash.

A valid MD5 value.b6030e39979ed0e724cea3773e014209

md5-printable

string

A human-readable version of the key's MD5 fingerprint.

The function returns this value in the meta hash.

A valid formatted MD5 value.
 Click to view...
MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09


sha256

string

The key's SHA-256 fingerprint.

The function returns this value in the meta hash.

A valid SHA-256 value.
 Click to view...
44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc44

sha256-printable

string

A human-readable version of the key's SHA-256 fingerprint.

The function returns this value in the meta hash.

A valid formatted SHA-256 value.
 Click to view...
SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ