From 854986abcbe1b8680a429b73e9238f3371e1e6fc Mon Sep 17 00:00:00 2001 From: Michael Kaufmann Date: Mon, 8 Oct 2018 09:35:15 +0200 Subject: [PATCH] add some more function-doc; add setting to enable/disable api in system-settings; added last three api-command classes (empty so far) Signed-off-by: Michael Kaufmann --- actions/admin/settings/120.system.php | 8 + lib/classes/api/commands/class.Cronjobs.php | 36 ++++ .../api/commands/class.CustomerBackups.php | 78 +++++++-- .../api/commands/class.HostingPlans.php | 36 ++++ .../api/commands/class.PhpSettings.php | 159 ++++++++++++++---- lib/classes/api/commands/class.Traffic.php | 36 ++++ lng/english.lng.php | 2 + lng/german.lng.php | 2 + tests/bootstrap.php | 3 +- 9 files changed, 312 insertions(+), 48 deletions(-) create mode 100644 lib/classes/api/commands/class.Cronjobs.php create mode 100644 lib/classes/api/commands/class.HostingPlans.php create mode 100644 lib/classes/api/commands/class.Traffic.php diff --git a/actions/admin/settings/120.system.php b/actions/admin/settings/120.system.php index 644ee5f4..7d643c2e 100644 --- a/actions/admin/settings/120.system.php +++ b/actions/admin/settings/120.system.php @@ -79,6 +79,14 @@ return array( 'save_method' => 'storeSettingHostname', 'plausibility_check_method' => 'checkHostname', ), + 'api_enabled' => array( + 'label' => $lng['serversettings']['enable_api'], + 'settinggroup' => 'api', + 'varname' => 'enabled', + 'type' => 'bool', + 'default' => false, + 'save_method' => 'storeSettingField', + ), 'system_validatedomain' => array( 'label' => $lng['serversettings']['validate_domain'], 'settinggroup' => 'system', diff --git a/lib/classes/api/commands/class.Cronjobs.php b/lib/classes/api/commands/class.Cronjobs.php new file mode 100644 index 00000000..ef858206 --- /dev/null +++ b/lib/classes/api/commands/class.Cronjobs.php @@ -0,0 +1,36 @@ + (2010-) + * @license GPLv2 http://files.froxlor.org/misc/COPYING.txt + * @package API + * @since 0.10.0 + * + */ +class Cronjobs extends ApiCommand implements ResourceEntity +{ + public function add() + {} + + public function get() + {} + + public function update() + {} + + public function listing() + {} + + public function delete() + {} + + +} diff --git a/lib/classes/api/commands/class.CustomerBackups.php b/lib/classes/api/commands/class.CustomerBackups.php index e1722128..cdd02365 100644 --- a/lib/classes/api/commands/class.CustomerBackups.php +++ b/lib/classes/api/commands/class.CustomerBackups.php @@ -18,6 +18,11 @@ class CustomerBackups extends ApiCommand implements ResourceEntity { + /** + * check whether backup is enabled systemwide and if accessable for customer (hide_options) + * + * @throws Exception + */ private function validateAccess() { if (Settings::Get('system.backupenabled') != 1) { @@ -31,38 +36,55 @@ class CustomerBackups extends ApiCommand implements ResourceEntity } } + /** + * add a new customer backup job + * + * @param string $path + * path to store the backup to + * @param bool $backup_dbs + * optional whether to backup databases, default is 0 (false) + * @param bool $backup_mail + * optional whether to backup mail-data, default is 0 (false) + * @param bool $backup_web + * optional whether to backup web-data, default is 0 (false) + * @param int $customerid + * required when called as admin, not needed when called as customer + * + * @access admin, customer + * @return array + */ public function add() { $this->validateAccess(); - + // required parameter $path = $this->getParam('path'); - + // parameter $backup_dbs = $this->getParam('backup_dbs', true, 0); $backup_mail = $this->getParam('backup_mail', true, 0); $backup_web = $this->getParam('backup_web', true, 0); - + // get customer data $customer = $this->getCustomerData(); - + // validation $path = makeCorrectDir(validate($path, 'path', '', '', array(), true)); $userpath = $path; $path = makeCorrectDir($customer['documentroot'] . '/' . $path); - + if ($backup_dbs != '1') { $backup_dbs = '0'; } - + if ($backup_mail != '1') { $backup_mail = '0'; } - + if ($backup_web != '1') { $backup_web = '0'; } - + $task_data = array( 'customerid' => $customer['customerid'], 'uid' => $customer['guid'], @@ -75,27 +97,47 @@ class CustomerBackups extends ApiCommand implements ResourceEntity ); // schedule backup job inserttask('20', $task_data); - + $this->logger()->logAction($this->isAdmin() ? ADM_ACTION : USR_ACTION, LOG_NOTICE, "[API] added customer-backup job for '" . $customer['loginname'] . "'. Target directory: " . $userpath); return $this->response(200, "successfull", $task_data); } + /** + * You cannot get a planned backup. + * Try CustomerBackups.listing() + */ public function get() { throw new Exception('You cannot get a planned backup. Try CustomerBackups.listing()', 303); } + /** + * You cannot update a planned backup. + * You need to delete it and re-add it. + */ public function update() { throw new Exception('You cannot update a planned backup. You need to delete it and re-add it.', 303); } + /** + * list all planned backup-jobs, if called from an admin, list all planned backup-jobs of all customers you are allowed to view, or specify id or loginname for one specific customer + * + * @param int $customerid + * optional, admin-only, select backup-jobs of a specific customer by id + * @param string $loginname + * optional, admin-only, select backup-jobs of a specific customer by loginname + * + * @access admin, customer + * @throws Exception + * @return array count|list + */ public function listing() { $this->validateAccess(); - + $customer_ids = $this->getAllowedCustomerIds('extras.backup'); - + // check whether there is a backup-job for this customer $sel_stmt = Database::prepare("SELECT * FROM `" . TABLE_PANEL_TASKS . "` WHERE `type` = '20'"); Database::pexecute($sel_stmt); @@ -113,6 +155,20 @@ class CustomerBackups extends ApiCommand implements ResourceEntity )); } + /** + * delete a planned backup-jobs by id, if called from an admin you need to specify the customerid/loginname + * + * @param int $backup_job_entry + * id of backup job + * @param int $customerid + * optional, required when called as admin (if $loginname is not specified) + * @param string $loginname + * optional, required when called as admin (if $customerid is not specified) + * + * @access admin, customer + * @throws Exception + * @return bool + */ public function delete() { // get planned backups diff --git a/lib/classes/api/commands/class.HostingPlans.php b/lib/classes/api/commands/class.HostingPlans.php new file mode 100644 index 00000000..428292f7 --- /dev/null +++ b/lib/classes/api/commands/class.HostingPlans.php @@ -0,0 +1,36 @@ + (2010-) + * @license GPLv2 http://files.froxlor.org/misc/COPYING.txt + * @package API + * @since 0.10.0 + * + */ +class HostingPlans extends ApiCommand implements ResourceEntity +{ + public function add() + {} + + public function get() + {} + + public function update() + {} + + public function listing() + {} + + public function delete() + {} + + +} diff --git a/lib/classes/api/commands/class.PhpSettings.php b/lib/classes/api/commands/class.PhpSettings.php index 52614506..2f7b6438 100644 --- a/lib/classes/api/commands/class.PhpSettings.php +++ b/lib/classes/api/commands/class.PhpSettings.php @@ -29,29 +29,29 @@ class PhpSettings extends ApiCommand implements ResourceEntity { if ($this->isAdmin()) { $this->logger()->logAction(ADM_ACTION, LOG_NOTICE, "[API] list php-configs"); - + $result = Database::query(" SELECT c.*, fd.description as fpmdesc FROM `" . TABLE_PANEL_PHPCONFIGS . "` c LEFT JOIN `" . TABLE_PANEL_FPMDAEMONS . "` fd ON fd.id = c.fpmsettingid ORDER BY c.description ASC "); - + $phpconfigs = array(); while ($row = $result->fetch(PDO::FETCH_ASSOC)) { $query_params = array( 'id' => $row['id'] ); - + $query = "SELECT * FROM `" . TABLE_PANEL_DOMAINS . "` WHERE `phpsettingid` = :id AND `parentdomainid` = '0'"; - + if ((int) $this->getUserDetail('domains_see_all') == 0) { $query .= " AND `adminid` = :adminid"; $query_params['adminid'] = $this->getUserDetail('adminid'); } - + if ((int) Settings::Get('panel.phpconfigs_hidestdsubdomain') == 1) { $ssdids_res = Database::query(" SELECT DISTINCT `standardsubdomain` FROM `" . TABLE_PANEL_CUSTOMERS . "` @@ -64,35 +64,35 @@ class PhpSettings extends ApiCommand implements ResourceEntity $query .= " AND `id` NOT IN (" . implode(', ', $ssdids) . ")"; } } - + $domains = array(); $domainresult_stmt = Database::prepare($query); Database::pexecute($domainresult_stmt, $query_params, true, true); - + if (Database::num_rows() > 0) { while ($row2 = $domainresult_stmt->fetch(PDO::FETCH_ASSOC)) { $domains[] = $row2['domain']; } } - + // check whether we use that config as froxor-vhost config if (Settings::Get('system.mod_fcgid_defaultini_ownvhost') == $row['id'] || Settings::Get('phpfpm.vhost_defaultini') == $row['id']) { $domains[] = Settings::Get('system.hostname'); } - + if (empty($domains)) { $domains[] = $this->lng['admin']['phpsettings']['notused']; } - + // check whether this is our default config if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini') == $row['id']) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.defaultini') == $row['id'])) { $row['is_default'] = true; } - + $row['domains'] = $domains; $phpconfigs[] = $row; } - + return $this->response(200, "successfull", array( 'count' => count($phpconfigs), 'list' => $phpconfigs @@ -103,9 +103,10 @@ class PhpSettings extends ApiCommand implements ResourceEntity /** * return a php-setting entry by id - * - * @param int $id php-settings-id - * + * + * @param int $id + * php-settings-id + * * @access admin * @throws Exception * @return array @@ -114,7 +115,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity { if ($this->isAdmin()) { $id = $this->getParam('id'); - + $result_stmt = Database::prepare(" SELECT * FROM `" . TABLE_PANEL_PHPCONFIGS . "` WHERE `id` = :id "); @@ -132,6 +133,49 @@ class PhpSettings extends ApiCommand implements ResourceEntity /** * add new php-settings entry * + * @param string $description + * description of the php-config + * @param string $phpsettings + * the actual ini-settings + * @param string $binary + * optional the binary to php-cgi if FCGID is used + * @param string $file_extensions + * optional allowed php-file-extensions if FCGID is used, default is 'php' + * @param int $mod_fcgid_starter + * optional number of fcgid-starters if FCGID is used, default is -1 + * @param int $mod_fcgid_maxrequests + * optional number of fcgid-maxrequests if FCGID is used, default is -1 + * @param string $mod_fcgid_umask + * optional umask if FCGID is used, default is '022' + * @param int $fpmconfig + * optional id of the fpm-daemon-config if FPM is used + * @param bool $phpfpm_enable_slowlog + * optional whether to write a slowlog or not if FPM is used, default is 0 (false) + * @param string $phpfpm_reqtermtimeout + * optional request terminate timeout if FPM is used, default is '60s' + * @param string $phpfpm_reqslowtimeout + * optional request slowlog timeout if FPM is used, default is '5s' + * @param bool $phpfpm_pass_authorizationheader + * optional whether to pass authorization header to webserver if FPM is used, default is 0 (false) + * @param bool $override_fpmconfig + * optional whether to override fpm-daemon-config value for the following settings if FPM is used, default is 0 (false) + * @param string $pm + * optional process-manager to use if FPM is used (allowed values are 'static', 'dynamic' and 'ondemand'), default is fpm-daemon-value + * @param int $max_children + * optional number of max children if FPM is used, default is the fpm-daemon-value + * @param int $start_server + * optional number of servers to start if FPM is used, default is fpm-daemon-value + * @param int $min_spare_servers + * optional number of minimum spare servers if FPM is used, default is fpm-daemon-value + * @param int $max_spare_servers + * optional number of maximum spare servers if FPM is used, default is fpm-daemon-value + * @param int $max_requests + * optional number of maximum requests if FPM is used, default is fpm-daemon-value + * @param int $idle_timeout + * optional number of seconds for idle-timeout if FPM is used, default is fpm-daemon-value + * @param string $limit_extensions + * optional limitation of php-file-extensions if FPM is used, default is fpm-daemon-value + * * @access admin * @throws Exception * @return array @@ -139,18 +183,18 @@ class PhpSettings extends ApiCommand implements ResourceEntity public function add() { if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) { - + // required parameter $description = $this->getParam('description'); $phpsettings = $this->getParam('phpsettings'); - + if (Settings::Get('system.mod_fcgid') == 1) { $binary = $this->getParam('binary'); $fpm_config_id = 1; } elseif (Settings::Get('phpfpm.enabled') == 1) { $fpm_config_id = intval($this->getParam('fpmconfig')); } - + // parameters $file_extensions = $this->getParam('file_extensions', true, 'php'); $mod_fcgid_starter = $this->getParam('mod_fcgid_starter', true, - 1); @@ -160,7 +204,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity $fpm_reqtermtimeout = $this->getParam('phpfpm_reqtermtimeout', true, "60s"); $fpm_reqslowtimeout = $this->getParam('phpfpm_reqslowtimeout', true, "5s"); $fpm_pass_authorizationheader = $this->getParam('phpfpm_pass_authorizationheader', true, 0); - + $override_fpmconfig = $this->getParam('override_fpmconfig', true, 0); $def_fpmconfig = $this->apiCall('FpmDaemons.get', array( 'id' => $fpm_config_id @@ -218,11 +262,11 @@ class PhpSettings extends ApiCommand implements ResourceEntity $mod_fcgid_maxrequests = 0; $mod_fcgid_umask = "022"; } - + if (strlen($description) == 0 || strlen($description) > 50) { standard_error('descriptioninvalid', '', true); } - + $ins_stmt = Database::prepare(" INSERT INTO `" . TABLE_PANEL_PHPCONFIGS . "` SET `description` = :desc, @@ -272,7 +316,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity ); Database::pexecute($ins_stmt, $ins_data, true, true); $ins_data['id'] = Database::lastInsertId(); - + inserttask('1'); $this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting with description '" . $description . "' has been created by '" . $this->getUserDetail('loginname') . "'"); @@ -288,22 +332,64 @@ class PhpSettings extends ApiCommand implements ResourceEntity * update a php-setting entry by given id * * @param int $id + * @param string $description + * description of the php-config + * @param string $phpsettings + * the actual ini-settings + * @param string $binary + * optional the binary to php-cgi if FCGID is used + * @param string $file_extensions + * optional allowed php-file-extensions if FCGID is used, default is 'php' + * @param int $mod_fcgid_starter + * optional number of fcgid-starters if FCGID is used, default is -1 + * @param int $mod_fcgid_maxrequests + * optional number of fcgid-maxrequests if FCGID is used, default is -1 + * @param string $mod_fcgid_umask + * optional umask if FCGID is used, default is '022' + * @param int $fpmconfig + * optional id of the fpm-daemon-config if FPM is used + * @param bool $phpfpm_enable_slowlog + * optional whether to write a slowlog or not if FPM is used, default is 0 (false) + * @param string $phpfpm_reqtermtimeout + * optional request terminate timeout if FPM is used, default is '60s' + * @param string $phpfpm_reqslowtimeout + * optional request slowlog timeout if FPM is used, default is '5s' + * @param bool $phpfpm_pass_authorizationheader + * optional whether to pass authorization header to webserver if FPM is used, default is 0 (false) + * @param bool $override_fpmconfig + * optional whether to override fpm-daemon-config value for the following settings if FPM is used, default is 0 (false) + * @param string $pm + * optional process-manager to use if FPM is used (allowed values are 'static', 'dynamic' and 'ondemand'), default is fpm-daemon-value + * @param int $max_children + * optional number of max children if FPM is used, default is the fpm-daemon-value + * @param int $start_server + * optional number of servers to start if FPM is used, default is fpm-daemon-value + * @param int $min_spare_servers + * optional number of minimum spare servers if FPM is used, default is fpm-daemon-value + * @param int $max_spare_servers + * optional number of maximum spare servers if FPM is used, default is fpm-daemon-value + * @param int $max_requests + * optional number of maximum requests if FPM is used, default is fpm-daemon-value + * @param int $idle_timeout + * optional number of seconds for idle-timeout if FPM is used, default is fpm-daemon-value + * @param string $limit_extensions + * optional limitation of php-file-extensions if FPM is used, default is fpm-daemon-value * * @access admin - * @throws Exception:: + * @throws Exception * @return array */ public function update() { if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) { - + // required parameter $id = $this->getParam('id'); $result = $this->apiCall('PhpSettings.get', array( 'id' => $id )); - + // parameters $description = $this->getParam('description', true, $result['description']); $phpsettings = $this->getParam('phpsettings', true, $result['phpsettings']); @@ -371,11 +457,11 @@ class PhpSettings extends ApiCommand implements ResourceEntity $mod_fcgid_maxrequests = 0; $mod_fcgid_umask = "022"; } - + if (strlen($description) == 0 || strlen($description) > 50) { standard_error('descriptioninvalid', '', true); } - + $upd_stmt = Database::prepare(" UPDATE `" . TABLE_PANEL_PHPCONFIGS . "` SET `description` = :desc, @@ -426,7 +512,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity 'id' => $id ); Database::pexecute($upd_stmt, $upd_data, true, true); - + inserttask('1'); $this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting with description '" . $description . "' has been updated by '" . $this->getUserDetail('loginname') . "'"); @@ -441,8 +527,9 @@ class PhpSettings extends ApiCommand implements ResourceEntity /** * delete a php-setting entry by id * - * @param int $id php-settings-id - * + * @param int $id + * php-settings-id + * * @access admin * @throws Exception * @return array @@ -455,15 +542,15 @@ class PhpSettings extends ApiCommand implements ResourceEntity $result = $this->apiCall('PhpSettings.get', array( 'id' => $id )); - + if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini_ownvhost') == $id) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.vhost_defaultini') == $id)) { standard_error('cannotdeletehostnamephpconfig', '', true); } - + if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini') == $id) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.defaultini') == $id)) { standard_error('cannotdeletedefaultphpconfig', '', true); } - + // set php-config to default for all domains using the // config that is to be deleted $upd_stmt = Database::prepare(" @@ -473,14 +560,14 @@ class PhpSettings extends ApiCommand implements ResourceEntity Database::pexecute($upd_stmt, array( 'id' => $id ), true, true); - + $del_stmt = Database::prepare(" DELETE FROM `" . TABLE_PANEL_PHPCONFIGS . "` WHERE `id` = :id "); Database::pexecute($del_stmt, array( 'id' => $id ), true, true); - + inserttask('1'); $this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting '" . $result['description'] . "' has been deleted by '" . $this->getUserDetail('loginname') . "'"); return $this->response(200, "successfull", $result); diff --git a/lib/classes/api/commands/class.Traffic.php b/lib/classes/api/commands/class.Traffic.php new file mode 100644 index 00000000..b298bc01 --- /dev/null +++ b/lib/classes/api/commands/class.Traffic.php @@ -0,0 +1,36 @@ + (2010-) + * @license GPLv2 http://files.froxlor.org/misc/COPYING.txt + * @package API + * @since 0.10.0 + * + */ +class Traffic extends ApiCommand implements ResourceEntity +{ + public function add() + {} + + public function get() + {} + + public function update() + {} + + public function listing() + {} + + public function delete() + {} + + +} diff --git a/lng/english.lng.php b/lng/english.lng.php index 16699484..77be7df5 100644 --- a/lng/english.lng.php +++ b/lng/english.lng.php @@ -2143,3 +2143,5 @@ $lng['apikeys']['allowed_from'] = 'Allowed from'; $lng['apikeys']['allowed_from_help'] = 'Comma separated list of ip addresses. Default empty.'; $lng['apikeys']['valid_until'] = 'Valid until'; $lng['apikeys']['valid_until_help'] = 'Date until valid, format YYYY-MM-DD'; +$lng['serversettings']['enable_api']['title'] = 'Enable external API usage'; +$lng['serversettings']['enable_api']['description'] = 'In order to use the froxlor API you need to activate this option. For more detailed information see https://api.froxlor.org/'; diff --git a/lng/german.lng.php b/lng/german.lng.php index 45322e59..c7668615 100644 --- a/lng/german.lng.php +++ b/lng/german.lng.php @@ -1791,3 +1791,5 @@ $lng['apikeys']['allowed_from'] = 'Erlaube Zugriff von'; $lng['apikeys']['allowed_from_help'] = 'Komma getrennte Liste von IPs. Standard ist leer.'; $lng['apikeys']['valid_until'] = 'Gültig bis'; $lng['apikeys']['valid_until_help'] = 'Datum Gültigkeitsende, Format JJJJ-MM-TT'; +$lng['serversettings']['enable_api']['title'] = 'Aktiviere externe API Nutzung'; +$lng['serversettings']['enable_api']['description'] = 'Um die froxlor API nutzen zu können, muss diese Option aktiviert sein. Für detaillierte Informationen siehe https://api.froxlor.org/'; diff --git a/tests/bootstrap.php b/tests/bootstrap.php index b5dbbab7..eb7fa9d3 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -13,7 +13,8 @@ $userdata_content = "