i-MSCP Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======Plugin Configuration======

=====Plugin Main Configuration Files=====

Each plugin can provide a configuration file, which is a simple PHP file that return an array. This file allow the administrator to configure the plugin for its own needs.

When you want modify the configuration of a specific plugin, you must edit the plugin configuration file and trigger a plugin update by clicking on the **Update Plugins** button which is available in the plugin management interface.

You must be aware that the plugin configuration files are not persistent, meaning that each time you update the plugin to a new version, your changes will be lost. Therefore, to remediate to this problem, you must in order:

  - Make a backup of the plugin configuration file
  - Update the plugin by uploading the new version through the plugin interface
  - Restore your plugin configuration file (you must check it by comparing it with the new plugin configuration file)
  - Trigger a plugin reconfiguration by clicking on the **Update Plugins** button.
=====Plugin Local Configuration Files=====

====Introduction====

Most plugins provide a standardized configuration file (see above) which is located at root of their directory. This file is not persistent, meaning that on each plugin update, you'll have to backup and restore it once the new plugin version will be uploaded.

Because such behavior is not really convenient, the plugin API provide a way to create plugin local configuration files, which are automatically merged with the main configuration files. Those files are persistent and never deleted automatically, even when i-MSCP get updated.

=====How It Works=====

When a local configuration file is found for a plugin, both, the default configuration file and the local configuration file are merged together.

Parameters defined in the local configuration files take precedence over those defined in default configuration files.

=====Creating Plugin Local Configuration File====

All plugin local configuration file must be stored in the **imscp/gui/data/persistent/plugins** directory.

Local configuration files *MUST* be named with plugin name followed by the php file extension. For instance, if the plugin for which you want create a local configuration file is named **JailKit**, the local configuration file *MUST* be named **JailKit.php**

=====Plugin Local Configuration File Sample====

Below a small sample of a plugin local configuration file wich can help you to understand how this works.

Here we want override the following plugin main configuration file:

  <?php
  return array(
    // Jailkit installation directory.
	  // This path is used as value of the --prefix option (JailKit configure script).
	  // IMPORTANT: You must never change this parameter while updating the plugin to a new version.
	  'install_path' => '/usr/local', // (Recommended value)
  
	  // Full path to the root jail directory which holds all jails. Be sure that the partition in which this directory is
	  // living has enough space to host the jails.
	  // IMPORTANT: You must never change this parameter while updating the plugin to a new version.
	  'root_jail_dir' => '/home/imscp-jails',
  
	  // See man shells
	  // Don't change this value if you do not know what you are doing
	  'shell' => '/bin/bash', // (Recommended value)
  
	  // See man jk_init
	  'jail_app_sections' => array(
		  'imscp-base', // Include Pre-selected sections, users and groups
		  'mysql-client'
	  ),
  
	  // See man jk_cp
	  // Any file which is not installed on your system will be ignored
	  'jail_additional_apps' => array(
		  '/bin/hostname',
		  '/usr/bin/basename',
		  '/usr/bin/dircolors',
		  '/usr/bin/dirname',
		  '/usr/bin/clear_console',
		  '/usr/bin/env',
		  '/usr/bin/id',
		  '/usr/bin/groups',
		  '/usr/bin/lesspipe',
		  '/usr/bin/tput',
		  '/usr/bin/which'
	  ),
  
	  // See man jk_socketd
	  'jail_socketd_base' => '512',
	  'jail_socketd_peak' => '2048',
	  'jail_socketd_interval' => '5.0'
  );
  
We create the following local configuration file:

**gui/data/persistent/plugins/JailKit.php file:**

  <?php
  return array(
    // Override default jail roor directory
	  'root_jail_dir' => '/var/www/imscp-jails',
  
	  // Append the git section to the jail_app_sections parameter
	  'jail_app_sections' => array(
		  'git'
	  )
  );

**Important**

Configuration items from main plugin configuration files are never removed automatically (this is by design). To remove an item, you must process as follow:

**gui/data/persistent/plugins/JailKit.php file:**

  <?php
  return array(
	  '__OVERRIDE__' => array(
		  // Override default jail roor directory
		  'root_jail_dir' => '/var/www/imscp-jails',
  
		  // Append the git section to the jail_app_sections parameter
		  'jail_app_sections' => array(
			 'git'
		  )
	  ),
	  '__REMOVE__' => array(
		  // Remove mysql-client section from the jail_app_section parameter
		  'jail_apps_sections => array(
			  'mysql-client'
		  ),
  
		  // Remove hostname command from the jail_additional_apps parameter
		  'jail_additional_apps' => array(
			  '/bin/hostname'
		  )
	  )
  );

Here, the special array key **%%__OVERRIDE__%%** defines an array which contain elements to add/override, and the second special array key **%%__REMOVE__%%**, an array which contain elements to remove.
i-MSCP Documentation

User Tools

Site Tools

Page Tools
