The Hash Reference List

Example of how to use the following list:

• Key (Value Type) — Details.
  • Example of the value.

Note: Some entries do not have all of the components listed in the example above. Formatting, however, will remain consistent.

• addopt_url (string) — URL to the script's functionality expanding module.
  • Example: http://www.example/com/addon-modules/additional-functionality
• admin_email (boolean) — Turns the email field on or off. If the field is enabled, it is available for config or mysql as [% email %]
  • 1 when enabled.
  • 0 when disabled.
• admin_user_pass_length (integer) — Minimum required length for [% username %] and [% password %]
  • Example: 10
• admin_user_pass_length_max (integer) — Maximum allowed length of [% username %] and [% password %]
  • Example: 16
• adminarea_name (string) — .htaccess protected area name.
  • Example: Foo Goods
• adminarea_path (string) — .htaccess protected path (protected with 'adminuser_pass' values), relative to the install directory.
  • Example: /user/admin/path
• adminuser_pass (boolean) — Turns on or off the username and password fields. If enabled, the fields are availble for config or mysql as [% username %] and [% password %] respectively.
  • 1 when enabled.
  • 0 when disabled.
• changelog_url (string) — URL to the script's changelog.
  • Example: http://www.example.com/change-log
• chgrp (boolean) — Will recursively change the group of all install files to the install user's group.
  • 1 when enabled.
  • 0 when disabled.
• chmod (Hash Reference) — Each key is a 4-digit mode and the value is an array ref of files to chmod to the key relative to tarball insides.
  • Example:

'chmod' => { 
      '0600' => ['foo.conf'],
 },

• chmod_order (Array Reference) — Add the keys in the chmod Hash Ref. These should be added in the order you want them applied.
• chmod_recursive (Boolean) — Will make the chmod action in chmod recursive.
  • 1 when enabled.
  • 0 when disabled.
• config_files (Array Reference) — List of files that need processed as config files (IE have the [% variables %] expanded)
  • Example:

'config_files' => [qw(foo.conf admin/foo.conf)], 

• cron (string) — Crontab entry (including newlines). This is processed for the config variables.
  • Example: 1 * * * * [% installdir %]/foo 2&>1\n1 * * * * /whatever
• crypt_salt (string) — Specific salt to use when crypting the password.
  • Example: xY
• description (string) — A sentence or two of text describing the script.
  • Example: "This is a widget for foo."
• documentation_url (string) — URL to script's documentation.
  • Example: http://docs.example.com
• lisc_disc (Array Reference) — The first item is the discount string and the second is a discount code to use when purchasing from the vendor.
  • Example:

lisc_disc => ['40% off','cPanel42'], 

• lisc_info (string) — Explanation of the vendor's license paradigm.
  • Example: "This product requires you buy a license from the vendor and enter the key after it's installed the first time you log into the admin area."
• lisc_url (string) — URL to purchase a license.
  • Example: http://www.example.com/buy_lisc.pl
• maintainer_url (string) — URL to maintainer contact.
  • Example: http://www.example.com/contact
• miscurls (Hash Reference) — A hashref of helpful URL links to list in cPanel for each installation. The keys are a short label with the values as a URL relative to the base install (no preceding slash).
  • Example:

{ 'Administration' => 'admin/', 
           'Users' => 'users/' }

• mysql (Array Reference) — Generally there's only one value for this array. It is a list of short ^\w+$ strings that are used to reference the database(s) used by the cPAddons.
  • Example:

'mysql' => ['foo'], 

• nomovecopy (boolean) — Turns copy and move functionality on or off.
  • 1 when enabled.
  • 0 when disabled.
• packager_name (string) — Packager's name.
  • Example: "My Addon Co."
• perl_module (Hash Reference) — Warns if any of the required Perl modules need installed. Each key is the namespace of the module and the value is either the required minimum version or an empty string (meaning any version).
  • Example:

'perl_module'     => { 
      'Mod::You::Need' => '1.2', 
      'Other::Mod'     => '',    
},

• require_suexec (boolean) — Only allow installation if SuEXEC is enabled.
  • 1 when enabled.
  • 0 when disabled.
• security (string) — Text description of security issues good or bad with the script.
  • Example: "Do not allow users to post HTML when posting."
• set_phpinfo_at_this_moment (boolean)* — Turns on the check to see whether PHP is running as the user or not.
  • 1 when enabled.
  • 0 when disabled.
• setphpsuexecvar (boolean) — Turns on the check to see whether PHPsuEXEC is enabled or not.
  • 1 when enabled.
  • 0 when disabled.
• specialfunctions (Hash Reference) — Add any additional functionality to managing the installs in cPAddons. sub checkinstallsforfleas {} should be put after the #### addon specific special functions ## in our example module.
  • Note: 'code' and 'name' are required for each special function's hashref key.
  • Example:

'specialfunctions' => { 
    'checkinstallsforfleas' => {
        'code' => \&checkinstallsforfleas,   
        'name' => 'Check Installs for fleas',
    },
},

• support_url (string) — URL to vendor's support.
  • Example: http://www.example.com/support
• table_prefix (string) — If specified, turns on table prefix input field, available via [% table_prefix %]. Also used as the initial value of that field.
  • foo
• vendor_license (non-specific) — The license key for your addon, if needed. See Licensing Your Addons.
• warn_php_is_running_as_user_at_this_moment_change (string) — If we are setting set_php_is_running_as_user_at_this_moment, then check if it changed and output the key's value as a warning. * "PHP's running user status has changed. You may want to make sure all your PHP scripts are working."
• warnphpsuexec_change (string) — What to say when PHPSuExec status has changed (if setphpsuexecvar was in use).
  • "PHPSuExec functionality has changed since this install was done. Use the fix suexec status below to resolve any PHPSuExec issues."
• website (string) — URL to vendor's website.
  • Example: http://www.example.com
• whm_addon (Array Reference) — List of WHM Addon Modules that are required for installation. If your addon requires a system component to be installed it must be installed as a WHM Addon Module.
  • ['tomcat']

Hash Keys Related to Versioning and Upgrades

The following keys are available for versioning and upgrades. These keys allow you to list the specific files associated with your cPAddon so that you can manage installations directly into a domain's document root. The keys create a manifest of files used to know what files to work with on various operations. For example, when uninstalling you'll need to know what to delete so as not to blindly remove all the user's files.

As this file list may become lengthy, it can be added to your cPAddon.pm as a link to an external file after the

my $meta_info = {...}

section by adding these 3 lines of code and then using the below instructions to create your file list:

if ( defined &Cpanel::cPAddons::proc_keys_named_after_version ) {
   Cpanel::cPAddons::proc_keys_named_after_version( $meta_info, __PACKAGE__ );
}

You can easily create a list of all files in your archive by using the script located at: http://bugzilla.cpanel.net/attachment.cgi?id=565. Simply save this script as cpaddons_filelist.pl to the same directory as your cPAddon archive and run perl cpaddons_filelist.pl $archive where $archive is the name of your cPAddon archive for the appropriate version of your cPAddon. For example:

perl cpaddons_filelist.pl svn/Vendor/Category/Addonname/1.0.2.tar.gz

If you see an error message that looks like this:

Can't find Archive/Tar.pm in @INC...

You'll need to install Archive::Tar through CPAN. Or, if this is a cPanel server, you can run:

• /scripts/perlinstaller Archive::Tar

Keys

• 1.0.42-beta (Hash Reference) — This (optional) key corresponds to the 'version' key's value. On upgrades, a new one will need to be created if necessary, and any old ones should be left in. The only required key is 'public_html_install_files' example.
  • Example:

'1.0.42-beta' => { 


    'public_html_install_files' => \@list_of_files,


    'public_html_install_dirs' => \@list_of_dirs,


},

• '1.0.42-beta' -> {public_html_install_files} (Array Reference) — This key designates what files are associated with the installer. If you add these, they will be removed when the addon is uninstalled.
  • Example: ['admin.html', 'README', 'other_file_name']
• '1.0.42-beta' -> { public_html_install_dirs } (Array Reference) — This way if a user has his or her own files in those directories, the directories will not be deleted even though the installed files will be gone (from *_files above, list directories in "cascading order" or rmdir() will be unable to do its thing.
  • Example: ['admin/foo', 'admin'],
• '1.0.42-beta' -> { public_html_install_unknown } (Array Reference — For directories that will have unknown contents (IE files uploaded to it) or that you otherwise don't want to specify every single file in above - these directories have been removed.
  • ['uploads'],
• '1.0.42-beta' -> { public_html_install_note } (string) — This note should warn users if you are using common names and directory names for your install. For example, if you use index.html and add that to public_html_install_files, any file named index.html will be removed from the install directory.
  • "The files will also be removed when uninstalled, so be careful with common named files or directories!"