Script Provisioning

Script provisioning is a simple, yet revolutionary provisioning module - it allows you to execute your custom scripts in any scripting/programming language when certain actions related to product using this module occur. I.e.: Run certain script with certain arguments when related account is created. This way you can integrate any system that does not offer an remote API but other management tools that are accessible from cli.

Warning

This is potentially dangerous module - it can execute any script from scripts directory you pass to it, so its important to run your HostBill php/php-fpm processes under a isolated system user (not root). Its also advised to use/enable HostBill queue module

System requirements & security precautions

Precautions below are for enterprise version installed using auto-install script. If your HostBill is installed on different user/paths - refer also to section Non-enterprise install

• Make sure that /home/hostbill/scripts directory exists, and belongs to user hostbill
• This module relies on php proc_open and exec functions, that are by default disabled in php.ini's disable_functions directive, to use it:
  
  • Use HostBill Queue module that runs tasks in background/trough cron, and with that can make use of different php settings, or
  • (not advised) remove proc_open and exec functions from php.ini disable_functions directive
• Its not advised to use this module on shared environment.

Scripts requirements

• Scripts should be placed in /home/hostbill/scripts 
• Script should be made executable for hostbill user (chmod u+x)
• If possible, use shebang in your custom scripts 
• On success your script should return 0 exit code.
• On failure return any other exit code
• Any script output is logged in related account log on error/success 
• Before executing any script, module changes working directory (cwd) to main HostBill scripts directory

Configuring module/product

• As with any HostBill module, activate Script_Provisioning module in Settings→Modules section of adminarea. 
• You will be redirected to Settings→Apps section to create connection, this module requires just adding name for its connection details
• When configuring product in Settings→Products  & Services, select newly activated module & app. 
• Proceed to "Settings" Tab, to configure your scripts:
  
  
  • Check which events should execute a script (ie. terminate/create etc.)
  • From dropdown list select which script to execute (you should create scripts first)
  • Provide arguments that script should be executed with, here you can use variables available in Available Variables tab
     
  • Note about arguments: 
    All arguments will be escaped before execution for additional security. 
• Under Custom client-triggered actions you can define which script to execute when client will trigger custom action from Client Functions::Client UI
  Same rules/limitations/variables as in Settings tab apply
  
• Under Available Variables you can check what variables can be used in your script arguments  (up-to-date list is available in product configuration)
  

Client functions

Next to standard client functions that HostBill offers, module comes with "Client UI" function (name can be changed) of which you can enable multiple instances.

Once function is enabled, in its "Settings" tab you can define:

• names of Allowed actions customer is allowed to trigger
• HTML template rendered in client portal. In this code you can use variables.
  Once customer clicks on link with {$actlink}youraction URL, and youraction is within Allowed actions module will call script defined in Custom client-triggered actions tab (see above).
  Action customer clicks will be available as {$actname} variable in your custom script arguments

Template defined above, results in following in client portal:

Non-Enterise install

By default scripts should be located in /home/hostbill/scripts directory, to use custom dir on other installations, edit includes/config.php file and add lines:

$config = array();
$config['ScriptsDirectory'] = "/path/to/your/scripts/dir";

Make sure that this directory is not accessible from web (outside of public_html or similar folders)