EasyApache 3

Build Process

Kenneth Power
What you will gain

Stages of build process

Customizing the process
Troubleshooting
Definitions

OptMod - “Option Module”

OptLib - “Option Library”
OptMod
It is what you select
OptLib
Software dependency provided by cPanel

c-client (IMAP)‫‏‬
/opt
The Build Process
Initialization
OptMod order constructed by dependencies
Tarballs downloaded and unpacked
Install via package manager
OptMods Processed
Three main stages

1) Dry Run Stage

2) Action Stage

3) Post Install Test Stage

Dry Run Stage
Failures in Dry Run cause the Opt Mod to be skipped

OptLib installation
Dependency checking
configure
make
Action Stage
Failure halts build

make install
apxs
needed configuration applied
Post Install Tests Stage
Failure halts the process

Static pages
CGI
Others as dictated by Options
Refresher

Initialization
For each OptMod:
– Dry Run Stage
– Action Stage
– Post Install Tests Stage
Customizing the Build
Several Ways to Customize

1) Environment variables
2) Configure flags
3) Hook scripts
4) Custom OptMod
Environment Variables
Environment Variables

CFLAGS=”-DFD_SETSIZE=16382”
CXXFLAGS=”-funroll-loops”
LDFLAGS=”-L/usr/local/lib/my_lib”

Persist?
Environment Variables
EasyApache 3 RAWENV support

Store contents in file

Location:
/var/cpanel/easy/apache/rawenv/ENV_NAME
Environment Variables
/var/cpanel/easy/apache/rawenv/CFLAGS

-O0 -g
Environment Variables
Problem: over writes existing

/var/cpanel/easy/apache/rawenv/PATH

Append: .append_ENV_NAME
Prepend: .prepend_ENV_NAME
Environment Variables

/var/cpanel/easy/apache/rawenv/.prepend_PATH

/usr/local/app/bin

Result:
/usr/local/app/bin:/usr/kerberos/sbin:/usr/kerberos/bin:/usr/
local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
Environment Variables
More Information:

http://www.cpanel.net/support/docs/ea/ea3/ea3custom_modvar.html
Configure Flags
Configure Flags

Apache 1.3.x - /var/cpanel/easy/apache/rawopts/Apache1

Apache 2.0.x - /var/cpanel/easy/apache/rawopts/Apache2
Apache 2.2.x - /var/cpanel/easy/apache/rawopts/Apache2_2

All PHP 4.x versions - /var/cpanel/easy/apache/rawopts/all_php4

All PHP 5.x versions - /var/cpanel/easy/apache/rawopts/all_php5
Specific PHP Version - /var/cpanel/easy/apache/rawopts/PHP-X.X.X
Configure Flags - Format
One entry per line:

--with-zlib-dir=/usr/local/zlib
--enable-foo

Auto-Corrects:
--with-zlib-dir=

Becomes:
--with-zlib-dir
Configure Flags
Values added (appended) to configure

Possibility for conflicts

Recommend:

disable EA3 Entry

Configure Flags
More Information:

http://www.cpanel.net/support/docs/ea/ea3/ea3custom_flags.html
Hook Scripts
Hook Scripts
/scripts/preeasyapache
/scripts/posteasyapache
/scripts/before_apache_make
/scripts/after_apache_make_install
/scripts/before_httpd_restart_tests
/scripts/after_restart_tests
Hook Scripts
Each receives following arguments (in order shown):

1) EasyApache version
2) EasyApache revision
3) Apache version built
4) Comma separated PHP version(s) being built
5) --hook-args you stipulate

Environment Variable: ea3_params_yaml

Hook Scripts
Custom arguments: --hook-args

Format:
--hook-args=value
--hook-args=”param=value”
Hook Scripts
/scripts/easyapache --hook-args=value1 --hook-args="param=value"

$VAR1 = [
'3.2.0',
'4243',
'',
'',
'value1',
'param=value'
];
Hook Scripts: preeasyapache
Before anything else in the Initialization stage

Unclean exit (e.g. non-zero exit value) causes build to

halt
Example:

exit 1
!! Executing custom hook '/scripts/preeasyapache' !!
!! Done executing '/scripts/preeasyapache' !!
!! '/scripts/preeasyapache 3.2.0 4243 value1
param=value' failed with exit code '256' !!
Hook Scripts: posteasyapache
Executed at end of successful build

Exit value not important

Hook Scripts
Other scripts executed at specific points in process

Exit value not important

Hook Scripts
More Information:

/scripts/easyapache --help=hooks
/scripts/easyapache --help=hooks-advanced
Custom OptMod
Custom OptMod
Documentation:

/scripts/easyapache --perldoc

WHM >> Software >> Apache Update >>

Help >> Cpanel::Easy Framework POD
Perl code this way comes!
Custom OptMod
An OptMod is:

1. A Perl Module
file_name.pm

2. Stored in
/var/cpanel/easy/apache/custom_opt_mods

3. A multi-level hash table

 Custom OptMod: the simple way
1: package Cpanel::Easy::ModPython;
2:
3: our $easyconfig = {
4: 'name' => 'Mod Python',
5: 'hastargz' => 1,
6: 'src_cd2' => 'mod_python-3.3.1/',
7: 'step' => {
8: '0' => {
9: 'name' => 'Adding mod_python',
10: 'command' => sub {
11: my( $self ) = @_;
12: return $self->run_system_cmd_stack([
13: [qw(./configure --with-apxs=/usr/local/apache/bin/apxs)],
14: ['make'],
15: ['make', 'install'],
16: ]);
17: },
18: },
19: },
20: };
21:
22: 1;
Custom OptMod: the simple way

1: package Cpanel::Easy::ModPython;

/var/cpanel/easy/apache/custom_opt_mods/
Cpanel/
Easy/
ModPython.pm
/var/cpanel/easy/apache/custom_opt_mods/Cpanel/Easy/ModPython.pm
Custom OptMod: the simple way
12-16: return $self->run_system_cmd_stack( ...

./configure, etc are executed inside ‘src_cd2’ IE: mod_python-3.3.1

run_system_cmd_stack
Easy to use to execute multiple commands in a way
that communicates with easyapache properly.

First argument is an array reference.

Each item is an array ref of a command suitable
for a standard perl system() call

Wraps the logic up for multiple

run_system_cmd_returnable() to use as one “step”
Custom OptMod: the simple way
To customize template:

1. Change package namespace

2. Change 'name' entries
3. Change 'src_cd2'
(or remove it and 'hastargz ' if there is no tarball)
4. Change run_system_cmd_stack entry
5. Save as new file
/var/cpanel/easy/apache/custom_opt_mods/Cpanel/Easy/ModuleName.pm
 Custom OptMod: the simple way
1: package Cpanel::Easy::_________;
2:
3: our $easyconfig = {
4: 'name' => '__________',
5: 'hastargz' => 1,
6: 'src_cd2' => '__________',
7: 'step' => {
8: '0' => {
9: 'name' => '__________',
10: 'command' => sub {
11: my( $self ) = @_;
12: return $self->run_system_cmd_stack([
13: [qw(./configure --with-apxs=/usr/local/apache/bin/apxs)],
14: ['make'],
15: ['make', 'install'],
16: ]);
17: },
18: },
19: },
20: };
21:
22: 1;
Custom OptMod: tarball
Resides in same location as the OptMod
Name:
OptMod.pm.tar.gz

/var/cpanel/easy/apache/custom_opt_mods/Cpanel/Easy/
ModPython.pm.tar.gz
Custom OptMod: tarball
Directory inside tarball it is what goes into ‘src_cd2’
Unpacked inside:
/home/cpeasyapache/src
6: 'src_cd2' => 'mod_python-3.3.1/',

/home/cpeasyapache/src/mod_python-3.3.1
That is where the script is when the steps are run.

If no tarball/src_cd2 its in the .../cpeasyapache/src

(which can be /usr/home or /var/cpanel at times)
Custom OptMod: the simple way
Necessary files:

/var/cpanel/easy/apache/custom_opt_mods/Cpanel/Easy/ModPython.pm
/var/cpanel/easy/apache/custom_opt_mods/Cpanel/Easy/ModPython.pm.tar.gz
Custom OptMod: the simple way
Pros:
little programming required

Cons:
Assumes works with all versions of Apache
(mod_python’s tarball has Apache1/ and Apache2/ directories
that the same commands need done in for the given apache
version)
Assumes it has all the system things it needs
No info about what this option does
Doesn’t verify its added to httpd.conf (and
datastore ?) by apxs
Custom OptMod

Some of the possibilities:

1. Divide into “non-destructive” and “system changes”
a. non-destructive (pre check, info gathering type
things) : ‘dryrun’ element
b. system changes: ‘steps’ element
2. Split each group into individual steps
3. Add Apache version logic (modify src_cd2 and steps
based on Apache version)
4. Much much more, see the documentation for details
 Custom OptMod
1: package Cpanel::Easy::ModPython;
2:
3: our $easyconfig = {
4: 'name' => 'Mod Python',
5: 'url' => 'http://www.modpython.org/',
6: 'note' => 'For Django and other Python related scripts',
7: 'hastargz' => 1,
8: 'ensurepkg' => ['python-devel'],
9: 'src_cd2' => 'mod_python-3.3.1/',
10: 'modself' => sub { ... append ‘Apache1’ or ‘Apache2’ to ‘src_cd2’ ... },
11: 'step' => {
12: '0' => {
13: 'name' => 'Configuring mod_python',
14: 'command' => sub {
15: my( $self ) = @_;
16: return $self->run_system_cmd_returnable([
17: qw(./configure --with-apxs=/usr/local/apache/bin/apxs)
18: ]);
19: },
20: },
 Custom OptMod
21: '1' => {
22: 'name' => 'Making mod_python',
23: 'command' => sub {
24: my( $self ) = @_;
25: return $self->run_system_cmd_returnable(['make']);
26: },
27: },
28: '2' => {
29: 'name' => 'Installing mod_python',
30: 'command' => sub {
31: my( $self ) = @_;
32: return $self->run_system_cmd_returnable(['make','install']);
33: },
35: },
35: '3' => {
36: 'name' => 'Adding mod_python to httpd.conf',
37: 'command' => sub {... $self->ensure_loadmodule_in_httpdconf...},
38: },
39: }, # end ‘step’
40: };
41:
42: 1;
Custom OptMod
Full source and tarball:

http://conference.cpanel.net/files/
Custom OptMod: success
Customizing the Build
1) Environment Variables
http://www.cpanel.net/support/docs/ea/ea3/ea3custom_modvar.html
2) Configure Flags
http://www.cpanel.net/support/docs/ea/ea3/ea3custom_flags.html
3) Hook Scripts
/scripts/easyapache --help=hooks
/scripts/easyapache --help=hooks-advanced
4) Custom OptMod
/scripts/easyapache --perldoc
Troubleshooting
Common Problems

VPS
Package Management
FreeBSD
VPS
Memory

Minimum requirement: 256 MB

Dedicated vs. Burst
Package Management
Failure can be fatal
http://www.cpanel.net/support/could_not_ensurepkgs.htm

Network
Dependencies
Database
Race conditions
Antiquated OS
FreeBSD

Packages and Ports

64 Bit
Troubleshooting: build logs
/usr/local/cpanel/logs/easy/apache

-rw------- 1 root root 1154 May 20 05:49 build.1211276985

-rw------- 1 root root 1149 May 20 05:49 build.1211276985.env
-rw------- 1 root root 1154 May 20 05:55 build.1211277317
-rw------- 1 root root 1149 May 20 05:55 build.1211277317.env
-rw------- 1 root root 778498 May 21 11:15 build.1211382007
-rw------- 1 root root 1149 May 21 11:00 build.1211382007.env
Troubleshooting: Custom builds

/scripts/easyapache --skip-rawopts
/scripts/easyapache --skip-rawenv
/scripts/easyapache --skip-hooks

Disable custom OptMod

Troubleshooting: cPanel OptMod
/var/cpanel/perl/easy/Cpanel

/scripts/easyapache --skip-cpanelsync
Questions?