cPanel::SyncUtil - Perl extension for creating utilities that work with cpanelsync aware directories
use cPanel::SyncUtil;
These utility functions can be used to in scripts that create and work with cpanelsync environments.
See scripts/cpanelsync_build for a working example that can be used to build cPanel's cPAddon Vendor cpanelsync directory for your website.
None by default, all functions are exportable if you wish:
use cPanel::SyncUtil qw(_raw_dir); use cPanel::SyncUtil qw(:all);
Builds the .cpanelsync database for the given directory. Arguments are a directory (required) and a boolean to turn on verbose output.
The second argument can also be a hashref with the following keys:
The value is a boolean to turn on verbose output.
The value can be a coderef that takes the path you are interested in and returns a stringified mode value.
It defaults to cPanel::SycnUtil::get_mode_string() which does not preserve setuid for security.
If you have binaries that need to be setuid you can use \&cPanel::SycnUtil::get_mode_string_preserve_setuid or roll your own instead (e.g. to only preserve setuid on specific ones and warn about files that are setuid that need review).
Creates the compressed files for the given directory. Arguments are a directory (required) and a boolean to turn on verbose output.
If no .cpanelsync database is located then build_cpanelsync will be called prior to compressing and files.
Takes as its first argument a user that matches ^\w+$ (and optionally a group as its second argument, also matching ^\w+$) and recursively chown's the current working directory to the given user (and group if given).
Currently the return value is from a system() call to chown.
Returns an array (array ref in scalar context) of files in a given cpanelsync file. If none is passed it uses the one in the current directory.
Creates the .bz2 version of the given file. A second boolean argument can be passed for verbosity. Returns true if it worked false otherwise.
Takes a path and returns a string suitable the .cpanelsync format and oct().
For security, it does not retain setuid and is the default "mode determining" function. Alternate "mode determining" funcionality can be had as documented in functions where it is applicable.
This will retain setuid unless the given file is a symlink.
Returns an array (array ref in scalar context ) of all files recursively in the given directory.
@articles = @files;
The list is sorted by directories, files, then symlinks and those are each sorted case-insensitively
You can add file names to ignore as keys in %cPanel::SyncUtil::ignore_name which has by default '.svn' and '.git'.
The name can be the file name only or the path (that will start w/ the path given to _read_dir_recursively()).
Like _chown_pwd_recursively but takes a third argument of the path to process.
It can take 2 args : 'user, dir' or 3 args: 'user, group, dir'
Returns true if the given argument is a directory that it is safe to be cpanelsync'ified.
See the simple, scripts/cpanelsync_build_dir script for example useage while recursing directories.
This function makes the .tar and .bz2 version of the file system.
Its arguments are the following:
_raw_dir($base, $archive, $verbose, @files);
$base and $archive are the only required arguments.
$archive is a directory in $base.
It will chdir in $base and the process the directory $archive
If $verbose is true, output will be verbose.
$verbose can also be a hashref with the following keys:
If @files is specified each item in it is also processed.
Each item in @files must be a file (-f) in $base/$archive.
If it returns false the error is in $!
_raw_dir($base, $archive, $verbose, @files) or Carp::croak "_raw_dir($base, $archive, $verbose, @files) failed: $!";
Its very important to check the return value because if its failed its possible you will not be in the directory you think and then subsequent file operations will either fail or not work like you expect. Plus if its returned false then there is either a file system problem or the input to the function is not valid. In other words, if it fails you need to resolve the problem before continuing so croaking()ing is a good idea generally.
_sync_touchlock_pwd is then run on $base/$archive so that its now a cpanelsync directory
Shortcut to get a hash (in array context) or hash ref (in scalar context) of the script using this module's command line options.
Takes the same exact input as Getopt::Std getopts()
Creates the .cpanelsync file (and its .bz2 version) and .cpanelsync.lock for the current working directory
The argument can be a boolean to turn on verbose output or a hashref with the following keys:
Shortcut to File::Slurp's read_dir
Shortcut to File::Slurp's write_file
Locks the given directories.
_lock(qw(foo bar baz));
Unlocks the given directories.
_unlock(qw(foo bar baz));
Since a cpanelsycn directory is meant for downloading files you need to have the webserver handle files in the given path differently than it normally does.
For example typically you may have .cgi set up to so that it is executed and it's output retuned to the user. If it in a cpanelsync directory then you want users to download the source code of the .cgi file.
Here is an example of one way to configure this behavior in Apache 2.0 and Apache 2.2:
<Directory /path/to/cpanelsync/dir> # ForceType and Header are not strictly necessary but # may help ensure browsers can figure out what you want ForceType application/octet-stream Header set Content-Disposition attachment DefaultType application/octet-stream SetHandler default </Directory>
Note: You could also set the "filename" for the "attachment" by using rewrite rules to set an environment variable and use that variable in the "Header set" above. That is typically not necessary and beyond the scope of this document.
cPanel, http://www.cpanel.net
replace system() calls with perl versions.
anything mentioned in the source
Daniel Muey, http://drmuey.com/cpan_contact.pl
Copyright (C) 2006 cPanel, Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.
To install cPanel::SyncUtil, copy and paste the appropriate command in to your terminal.
cpanm
cpanm cPanel::SyncUtil
CPAN shell
perl -MCPAN -e shell install cPanel::SyncUtil
For more information on module installation, please visit the detailed CPAN module installation guide.