{"id":63169,"date":"2009-12-01T09:41:22","date_gmt":"2009-12-01T14:41:22","guid":{"rendered":"http:\/\/blogs.wp.stage.cpanel.net\/2009\/12\/how_to_trace_the_cpanel_api\/"},"modified":"2009-12-01T09:41:22","modified_gmt":"2009-12-01T14:41:22","slug":"how_to_trace_the_cpanel_api","status":"publish","type":"post","link":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/","title":{"rendered":"How to trace the cPanel API"},"content":{"rendered":"

At this point, cPanel\u2019s APIs are not 100% documented. \u00a0We are working on it and hope to have complete API docs up in a few months. \u00a0I\u2019ve written a CustomEventHandler<\/a>\u00a0that will print every API call made into cpanel\u2019s error_log (\/usr\/local\/cpanel\/logs\/error_log<\/em>).<\/p>\n

Installation<\/strong>
\nTo use the API Tracer, you will need to download it, then place the Dumper.pm<\/em> file at \/usr\/local\/cpanel\/perl\/Dumpe<\/em>r<\/em> and the CustomEventHandler.pm<\/em> file at \/usr\/local\/cpanel\/Cpanel<\/em>.<\/p>\n

Once this has been put into the proper location, cPanel will automatically start logging API calls to the error_log. \u00a0To view each call, you simply need to run tail -f \/usr\/local\/cpanel\/logs\/error_log<\/em> and login to a cPanel interface to start seeing data.<\/p>\n

Filtering<\/strong>
\n90% of the information displayed by the API Tracer is probably not what you are looking for. \u00a0If you look at the code for this CustomEventHandler, you will see that the following pieces of information are passed to it:
\nmy ( $apiv, $type, $module, $event, $cfgref, $dataref ) = @_;<\/code><\/p>\n

Out of these, for the purpose of filtering, the only ones that we care about are the following variables:
\n$apiv - API Version<\/em>
\n$module - The module of the function being called<\/em>
\n$event - The name of the function being called<\/em>
\n<\/code><\/p>\n

When a custom event handler runs, it is executed both before and after the call has been completed. \u00a0This is indicated by the $type variable which will pass \u201cpre\u201d before the event has been executed and \u201cpost\u201d after the event has been executed. \u00a0The most important thing to note here is that in the event of a \u201cpre\u201d call, if CustomEventHandler returns a false value, it will stop execution of the event, so in this scenario it is very important to always return 1. \u00a0For example, if you are trying to filter an email event, you will see something like the following right after the first line of the event() function:
\nreturn 1 if $module ne \u2018email\u2019;<\/em><\/p>\n

It is also important to note that modules and function names are passed in lowercase form to the CustomEventHandler.<\/p>\n

If you want to filter for a very specific call, you would do something like the following
\nreturn 1 if module ne \u2018email\u2019 && $event ne \u2018addpop\u2019;<\/em><\/p>\n

Understanding the Data passed to the tracer<\/strong>
\nNow that you understand how the tracer operates and how to make it report useful information, we need to talk about how to understand the data that it gives.<\/p>\n

As you will see, the Tracer will print formatted text to the error log that looks something like this:
\n--------------------
\nmysql:adduserdb
\n$apiv = 1
\n$type = pre
\n-----
\n$cfgref<\/p>\n

$VAR1 = {
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param0' => 'cptest_dbname',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param1' => 'cptest_username',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param2' => 'ALTER CREATEROUTINE TEMPORARY CREATE DELETE DROP SELECT INSERT UPDATE REFERENCES INDEX LOCK '
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0};<\/p>\n

mysql:adduserdb
\n--------------------
\nmysql:adduserdb
\n$apiv = 1
\n$type = post
\n-----
\n$cfgref<\/p>\n

$VAR1 = {
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param0' => 'cptest_dbname',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param1' => 'cptest_username',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param2' => 'ALTER CREATEROUTINE TEMPORARY CREATE DELETE DROP SELECT INSERT UPDATE REFERENCES INDEX LOCK '
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0};<\/p>\n

-----
\noutput
\n<\/code><\/p>\n

The first line indicates the module and the version, the second line describes which API version it\u2019s using (either API1 (link) or API2 (link) ). \u00a0After this, it displays two variables, $cfgref and $dataref. \u00a0These two variables indicate the input ($cfgref) and output ($dataref) from the function in a Data::Dumper format.<\/p>\n

Understanding $cfgref<\/strong>As API1 and API2 <\/a>use different methods of input, they naturally have different methods of displaying within this module. \u00a0When using API1 you will see something like the following:$VAR1 = {
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param0' => 'cptest_dbname',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param1' => 'cptest_',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'param2' => 'ALTER CREATEROUTINE TEMPORARY CREATE DELETE DROP SELECT INSERT UPDATE REFERENCES INDEX LOCK '
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0};
\n<\/code><\/p>\n

These indicate the order of parameters to API1, starting with param0 to paramn<\/em>. \u00a0This data can be correlated to what input was given to the cPanel interface to determine the call.<\/p>\n

With API2, since it uses named parameters, rather than ordered parameters you will see something like the following:
\n$cfgref
\n$VAR1 = {
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'quota' => 250,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'password' => 'somepasswprd',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'domain' => 'somedomain.com',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0'email' => 'someuser'
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0};
\n<\/code><\/p>\n

With these, the parameter name maps directly to the parameter name for API2. \u00a0This is fairly easy to understand, however there are a few things that need to be noted. \u00a0Firstly, use of generic parameters that will probably not aid you. \u00a0There are a few of these mostly prefixed with \u201capi2_\u201d, are used for things like sorting, pagination, searching, etc. \u00a0The other main parameter to pay attention to is \u201ccache_fix\u201d which is used for browser caching and should always be ignored.<\/p>\n

Understanding the output from $dataref<\/strong>
\nOne thing that you will only see in \u201cpost\u201d calls, is the $dataref being populated. \u00a0This contains the output from the Tracer. API1 output is usually straight forward, as they return strings rather than data structures. Take for example, Email::addpop, it will return the name of the email address:
\nemail+domain.com<\/em><\/p>\n

This will be populated with an error message in the case of an error.<\/p>\n

API2, as it\u2019s far more robust than API1, returns actual data structures. \u00a0These can be complex to work with. \u00a0Please refer to the API2 documentation (link) on how to work with this data. \u00a0When it is returned it will look like the following:
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0{
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'diskquota' => 250,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'humandiskquota' => '250 MB',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'user' => 'asdge33',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'_diskused' => 0,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'humandiskused' => 'None',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'_diskquota' => 262144000,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'txtdiskquota' => 250,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'diskusedpercent' => 0,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'diskusedpercent20' => 0,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'login' => 'asdge33@cptest.com',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'domain' => 'cptest.com',
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'diskused' => 0,
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0'email' => 'asdge33@cptest.com'
\n\u00a0\u00a0 \u00a0 \u00a0 \u00a0 \u00a0},
\n<\/code><\/p>\n

This would be displayed in XML format via the XML-API by:
\n\u2212
\n<data>
\n<_diskquota>262144000<\/_diskquota>
\n<_diskused>0<\/_diskused>
\n<diskquota>250<\/diskquota>
\n<diskused>0<\/diskused>
\n<diskusedpercent>0<\/diskusedpercent>
\n<diskusedpercent20>0<\/diskusedpercent20>
\n<domain>cptest.com<\/domain>
\n<email>asdge33@cptest.com<\/email>
\n<humandiskquota>250 MB<\/humandiskquota>
\n<humandiskused>None<\/humandiskused>
\n<login>asdge33@cptest.com<\/login>
\n<txtdiskquota>250<\/txtdiskquota>
\n<user>asdge33<\/user>
\n<\/data>
\n<\/code><\/p>\n

There are some shortcomings that need to be noted:<\/p>\n

    \n
  1. This version of Tracer requires that \/dev\/shm to be writable, the path for the temp file can be edited within the script however \/dev\/shm is the fastest place.<\/li>\n
  2. This means that usernames and passwords for anything created\/modified through the cPanel interface will be written to the error_log. \u00a0You need to clear the error_log after enabling this, and be careful that it\u2019s not left running on a production server due to the inherent security risks.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"

    At this point, cPanel\u2019s APIs are not 100% documented. \u00a0We are working on it and hope to have complete API docs up in a few months. \u00a0I\u2019ve written a CustomEventHandler\u00a0that will print every API call made into cpanel\u2019s error_log (\/usr\/local\/cpanel\/logs\/error_log). Installation To use the API Tracer, you will need to download it, then place the […]<\/p>\n","protected":false},"author":77,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"footnotes":""},"categories":[49],"tags":[],"class_list":["post-63169","post","type-post","status-publish","format-standard","hentry","category-products"],"acf":[],"yoast_head":"\nHow to trace the cPanel API | cPanel<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"How to trace the cPanel API | cPanel\" \/>\n<meta property=\"og:description\" content=\"At this point, cPanel\u2019s APIs are not 100% documented. \u00a0We are working on it and hope to have complete API docs up in a few months. \u00a0I\u2019ve written a CustomEventHandler\u00a0that will print every API call made into cpanel\u2019s error_log (\/usr\/local\/cpanel\/logs\/error_log). Installation To use the API Tracer, you will need to download it, then place the […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/\" \/>\n<meta property=\"og:site_name\" content=\"cPanel\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/cpanel\/\" \/>\n<meta property=\"article:published_time\" content=\"2009-12-01T14:41:22+00:00\" \/>\n<meta name=\"author\" content=\"cPanel Community\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@cPanel\" \/>\n<meta name=\"twitter:site\" content=\"@cPanel\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"cPanel Community\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"6 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/\",\"url\":\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/\",\"name\":\"How to trace the cPanel API | cPanel\",\"isPartOf\":{\"@id\":\"https:\/\/devel.www.cpanel.net\/#website\"},\"datePublished\":\"2009-12-01T14:41:22+00:00\",\"dateModified\":\"2009-12-01T14:41:22+00:00\",\"author\":{\"@id\":\"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/8cf97408aad4fb70cf55d11a1d4f57f8\"},\"breadcrumb\":{\"@id\":\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/devel.www.cpanel.net\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"How to trace the cPanel API\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/devel.www.cpanel.net\/#website\",\"url\":\"https:\/\/devel.www.cpanel.net\/\",\"name\":\"cPanel\",\"description\":\"Hosting Platform of Choices\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/devel.www.cpanel.net\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/8cf97408aad4fb70cf55d11a1d4f57f8\",\"name\":\"cPanel Community\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/e1949945083b5526bb95711bd3d616b3?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/e1949945083b5526bb95711bd3d616b3?s=96&d=mm&r=g\",\"caption\":\"cPanel Community\"},\"description\":\"The web hosting industry's most reliable management solution since 1997. With our first-class support and rich feature set, it's easy to see why our customers and partners make cPanel & WHM their hosting platform of choice. For more information, visit cPanel.net.\",\"sameAs\":[\"https:\/\/cpanel.net\"],\"url\":\"https:\/\/devel.www.cpanel.net\/blog\/author\/cpadmin\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"How to trace the cPanel API | cPanel","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/","og_locale":"en_US","og_type":"article","og_title":"How to trace the cPanel API | cPanel","og_description":"At this point, cPanel\u2019s APIs are not 100% documented. \u00a0We are working on it and hope to have complete API docs up in a few months. \u00a0I\u2019ve written a CustomEventHandler\u00a0that will print every API call made into cpanel\u2019s error_log (\/usr\/local\/cpanel\/logs\/error_log). Installation To use the API Tracer, you will need to download it, then place the […]","og_url":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/","og_site_name":"cPanel","article_publisher":"https:\/\/www.facebook.com\/cpanel\/","article_published_time":"2009-12-01T14:41:22+00:00","author":"cPanel Community","twitter_card":"summary_large_image","twitter_creator":"@cPanel","twitter_site":"@cPanel","twitter_misc":{"Written by":"cPanel Community","Est. reading time":"6 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/","url":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/","name":"How to trace the cPanel API | cPanel","isPartOf":{"@id":"https:\/\/devel.www.cpanel.net\/#website"},"datePublished":"2009-12-01T14:41:22+00:00","dateModified":"2009-12-01T14:41:22+00:00","author":{"@id":"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/8cf97408aad4fb70cf55d11a1d4f57f8"},"breadcrumb":{"@id":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/devel.www.cpanel.net\/blog\/products\/how_to_trace_the_cpanel_api\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/devel.www.cpanel.net\/"},{"@type":"ListItem","position":2,"name":"How to trace the cPanel API"}]},{"@type":"WebSite","@id":"https:\/\/devel.www.cpanel.net\/#website","url":"https:\/\/devel.www.cpanel.net\/","name":"cPanel","description":"Hosting Platform of Choices","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/devel.www.cpanel.net\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/8cf97408aad4fb70cf55d11a1d4f57f8","name":"cPanel Community","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/devel.www.cpanel.net\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/e1949945083b5526bb95711bd3d616b3?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/e1949945083b5526bb95711bd3d616b3?s=96&d=mm&r=g","caption":"cPanel Community"},"description":"The web hosting industry's most reliable management solution since 1997. With our first-class support and rich feature set, it's easy to see why our customers and partners make cPanel & WHM their hosting platform of choice. For more information, visit cPanel.net.","sameAs":["https:\/\/cpanel.net"],"url":"https:\/\/devel.www.cpanel.net\/blog\/author\/cpadmin\/"}]}},"_links":{"self":[{"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/posts\/63169"}],"collection":[{"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/users\/77"}],"replies":[{"embeddable":true,"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/comments?post=63169"}],"version-history":[{"count":0,"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/posts\/63169\/revisions"}],"wp:attachment":[{"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/media?parent=63169"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/categories?post=63169"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devel.www.cpanel.net\/wp-json\/wp\/v2\/tags?post=63169"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}