이 장에서는 제니퍼 PHP 에이전트를 일반적으로 설치하는 방법을 설명한다.

PHP 에이전트 지원 환경

지원되는 OS

아래는 PHP 에이전트를 정상적으로 설치할 수 있는 OS 이다.

• RedHat 5 이상

• CentOS 5 이상

• Ubuntu 7 이상

지원되는 PHP 버전

Apache 모듈, PHP-fpm, CLI, CGI로 동작하는 PHP 5.2 ~ 5.6, PHP 7.0 ~ 7.4, PHP8.0 ~ 8.2 를 지원한다.

라이브러리 의존성

PHP에이전트는 libstdc++.so.6, libgcc_s.so.1(GCC_4.2.0)에 의존성이 있다. PHP 모듈(libphp5.so 또는 php5-fpm)이 libstdc++.so.6 미만 버전에 의존성이 있거나 GCC 4.2.0을 지원하지 않는 libgcc_s.so.1에 의존성이 있다면 PHP 에이전트가 실행되지 않는다.

libgcc_s.so.1의 호환 GCC 버전은 다음 명령의 결과를 통해 확인할 수 있다.

# strings /lib/libgcc_s.so.1 | grep GCC
GCC_3.0
GCC_3.3
GCC_3.3.1
GCC_3.4
GCC_3.4.2
GCC_4.0.0
GCC_4.2.0
//결과에 GCC_4.2.0이 있으므로 PHP 에이전트가 실행 가능하다. 
# strings /lib/libgcc_s.so.1 | grep GCC
GCC_3.0
GCC_3.3
GCC_3.3.1
GCC_3.4
GCC_3.4.2
//결과에 GCC_4.2.0이 없으므로 PHP 에이전트가 실행 불가능하다.

LAMPP(XAMPP) 환경일 경우

특정 LAMPP 버전은 libgcc_s.so.1 과 libstdc++을 포함하고 있는데, 이때 LAMPP내에 포함된 libgcc_s.so.1과 libstdc++의 버전이 라이브러리 의존성 요구사항에 미치지 못한다면 PHP 에이전트를 설치 할 수 없다.

다음 과정을 통해 LAMPP 버전에서 사용하는 libstdc++ 와 libgcc_so.so.1 버전을 확인할 수 있다.

# ls /opt/lampp/lib/libstdc++*
libstdc++.so.5  libstdc++.so.5.0.7 libstdc++.so.6
//위 경우 LAMPP에 libstdc++.so.5가 있으므로 PHP 에이전트를 실행할 수 없다. 
//만약 libstdc++* 파일이 없다면 OS가 제공하는 libstdc++를 사용하는 것이므로 PHP 에이전트를 실행할 수 있다.

# ls /opt/lampp/lib/libgcc_s.so.1
libgcc_s.so.1
//만약 libgcc_s.so.1 파일이 없다면 OS가 제공하는 libgcc_s.so.1을 사용하는 것이므로 PHP 에이전트를 실행할 수 있다.
# strings /opt/lampp/lib/libgcc_s.so.1 | grep GCC
GCC_3.0
GCC_3.3
GCC_3.3.1
GCC_3.4
GCC_3.4.2
//이 경우 libgcc_s.so.1 호환 버전에 GCC_4.2.0 이 없으므로 PHP 에이전트를 실행할 수 없다.

에이전트 디렉토리, 파일 설명

PHP Agent 패키지 압축 파일을 해제하면 agent.php 디렉토리가 생성된다. agent.php 디렉토리 내의 파일들에 대한 설명은 다음과 같다.

agent-installer 를 이용해 PHP 에이전트 설치 (5.4.1 이상)

PHP 에이전트 5.4.1 버전 부터 agent-installer 바이너리 파일이 패키지에 추가되었다. agent-installer는 현재 실행 중인 Apache, PHP-fpm 프로세스를 검사해 PHP 버전과 Thread Safe, php.ini 파일을 확인한 후 PHP 에이전트를 설치 하는 프로그램이다.

#./agent-installer --help

USAGE:
    agent-installer
    agent-installer [FLAGS]

FLAGS:
    -d, --delete     Uninstall PHP Agent 
    -h, --help       Prints help information
    -i, --inspect    Inspect running PHP Application(mod-apache or fpm)
    -V, --version    Prints version information

실행 중인 PHP Apache 프로세스, PHP-fpm 프로세스 검사

sudo ./agent-installer -i 를 실행해 실행 중인 PHP Apache 프로세스, PHP-fpm 프로세스를 검사한다. 검사 결과가 화면에 출력되며, 상세 검사 로그는 .inspect-info 파일에 기록된다.

#sudo ./agent-installer -i

Inspect running PHP Application(mod-apache or fpm)
  Inspect file : "/usr/lib/apache2/modules/libphp7.so"
  Found PHP Thread Safety : NTS
  Found php.ini : /usr/local/etc/php/php.ini
  Found PHP Version : 7.2.16


Found 1 PHP Application

* cmd: apache2, version: PHP 7.2.16, thread safety: NTS

PHP 에이전트 설치

sudo ./agent-installer 를 실행해 PHP Agent를 설치한다. PHP 프로세스 상세 검사 로그는 .inspect-info 파일에 기록되며, PHP 설치 정보는 .install-info 파일에 기록된다.

#sudo ./agent-installer 


Install Jennifer PHP Agent

  Inspect running PHP Application(mod-apache or fpm)

    Inspect file : "/usr/lib/apache2/modules/libphp7.so"
    Found PHP Thread Safety : NTS
    Found php.ini : /usr/local/etc/php/php.ini
    Found PHP Version : 7.2.16

  1. cmd: apache2, version: PHP 7.2.16, thread safety: NTS

Found 1 PHP Application. Select PHP Application [1,n] :1

  Find extension for php-7.2.16-NTS
  PHP extension path : /usr/local/jennifer/agent.php/bin/jennifer5-php-7.2.x-NTS.so

  Update /usr/local/etc/php/php.ini
    * [jennifer]
    * jenniferAgent.agent_file_root=/usr/local/jennifer/agent.php
    * extension=/usr/local/jennifer/agent.php/bin/jennifer5-php-7.2.x-NTS.so

Install complete, edit /usr/local/jennifer/agent.php/jennifer.conf and restart apache or fpm.

PHP 에이전트 설치

1. agent.php 디렉토리로 이동한 후 php cli 명령으로 install.php 를 실행한다. 이때 인자로 php 설정파일(php.ini) 의 절대 경로를 지정한다.

# php install.php /etc/php5/apache2/php.ini ( 우분투 리눅스 )
# php install.php /etc/php.ini ( 레드헷 , 센트오에스 리눅스 )

2. PHP 에이전트 디렉토리를 입력한다. 현재 디렉토리를 입력할 경우 './'를 입력해야 하며 그렇지 않은 경우 절대 경로를 입력하도록 한다.

Start Jennifer PHP Agent Installer

Enter Jennifer PHP Agent install path : /home/jennifer/agent.php

Jennifer install path : /home/jennifer/agent.php 

--------------------------------------------------------
Current Directory : /home/jennifer/agent.php
Jennifer Agent Install Path : /home/jennifer/agent.php
PHP Version : 5.3.10-1ubuntu3.10
Thread Safety : disable
Arch : x86_64
Jennifer PHP Agent extension file name : jennifer5-php-5.3.x-NTS.so
PHP Configuration file : /etc/php5/apache2/php.ini
--------------------------------------------------------

3. PHP 버전과 설치할 에이전트의 버전등의 정보를 확인 한 후 yes 를 입력한다.

Do you want to continue? (yes or no) : yes

Write php.ini for Jennifer PHP Agent

extension=/home/jennifer/agent.php/bin/jennifer5-php-5.3.x-NTS.so
jenniferAgent.agent_file_root=/home/jennifer/agent.php

Check a Jennifer Agent executable file : /home/jennifer/agent.php/bin/Jennifer5Agent -- exists
Check a Jennifer Agent shared library file : /home/jennifer/agent.php/bin/Jennifer5Common.so -- exists
Check a Jennifer Agent PHP extension file : /home/jennifer/agent.php/bin/jennifer5-php-5.3.x-NTS.so -- exists
Check a Jennifer Agenet configuration file : /home/jennifer/agent.php/jennifer.conf -- exists

Installation successfully complete.
1. Open your jennifer.conf in jennifer install path, and specify a server address, sid, host_id and inst_id.
2. Restart Apache Server

root@NominT:/home/jennifer/agent.php#

4. agent.php/jennifer.conf 에서 필수 설정을 한다.

5. apache 또는 php-fpm을 재시작 한다.

6. apache 재시작 후 log 디렉토리에 jennifer_YYYY-MM-DD.log 로 로그 파일이 생성되며, 에이전트가 데이터 서버와 접속이 완료되면 아래와 같은 메세지를 로그 파일에서 확인할 수 있다.

2014-03-28/10:17:00 INFO--PHP Agent 5256: Send Agent Info

---------------- [App Initialized] ----------------------
Jennifer Server Address = 192.168.0.120
Jennifer Server Port = 5000
sid = 1000
inst id = 10000
Agent pid = 5256
Apache pid = 5254
MachineName = Ubuntu 12.04.4 LTS
Is64BitProcess = 1
Processor Architecture = x86_64
---------------------------------------------------------

PHP 에이전트 수동 설치

install.php 스크립트가 정상 동작 하지 않을 경우 다음을 통해 설치를 수동으로 진행한다.

1. 압출 파일을 해제 했을때 생성되는 agent.php 디렉토리를 PHP 에이전트 설치 디렉토리로 복사 한 후 해당 디렉토리로 이동한다.(동일하다면 이 과정은 무시해도 좋다)

$cp agent.php /home/jennifer/
$cd /home/jennifer/agent.php

2. PHP 버전을 확인한다.

$php -v
PHP 5.4.5 (cli) (built: Apr  3 2015 16:08:35)
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2012 Zend Technologies

3. PHP의 Thread Safety를 확인한다.

$php -i | grep Thread
Thread Safety => disabled

4. PHP extension으로 지정할 파일이 존재하는지 확인한다. PHP extension 파일은 agent.php/bin 디렉토리 내에 있으며, jennifer5-php-{PHP_Major_Version}.{PHP_Minor_Version}.x-{NTS or ZTS}.so 규칙을 따른다. 만약 Thread Safety 가 disabled라면 NTS를 지정해야 하며, enabled라면 ZTS를 지정해야 한다.

$ls agent.php/bin/jennifer5-php-5.4.x-NTS.so
agent.php/bin/jennifer5-php-5.4.x-NTS.so

5. php.ini 파일에 PHP 에이전트 extension 파일의 절대 경로와 PHP 에이전트 설치 절대 경로를 추가한다.

extension=/home/jennifer/agent.php/bin/jennifer5-php-5.4.x-NTS.so
jenniferAgent.agent_file_root=/home/jennifer/agent.php

6. jennifer.conf 에서 필수 설정을 한다.

7. apache 또는 php-fpm을 재시작 한다.

jennifer.conf 파일 위치 지정

특정한 위치에 있는 jennifer.conf 파일을 사용하기 위해서는 php.ini에 jenniferAgent.agent_config_root 옵션으로 설정할 수 있다. 설정하지 않는 경우 기본 값으로는 jenniferAgent.agent_file_root 의 위치와 같다.

php.ini 파일에 jennifer.conf 가 있는 위치 지정

;jenniferAgent.agent_config_root 옵션으로 jennifer.conf 의 위치가 에이전트 설치 위치와 다른 경우 설정할 수 있다. 설정하지 않는 경우 jenniferAgent.agent_file_root 의 위치와 같다.
jenniferAgent.agent_config_root=/some/conf/root/path

PHP 에이전트 Master 프로세스를 별도로 실행하는 경우

CLI, CGI 환경처럼 마스터 프로세스를 별도로 실행하는 경우 Jennifer5Agent 실행시 -c 옵션으로 config 위치를 지정할 수 있다. 기본값은 agent 설치 위치이다.

/jennifer/agent.php/bin/./Jennifer5Agent -k start -c /some/conf/root/path

PHP 에이전트 제거

PHP 설정 파일(php.ini)의 jennifer 관련된 설정을 주석처리하거나 삭제한 후 apache 또는 php-fpm을 재시작 한다.

;extension=/home/jennifer/agent.php/jennifer5-php-5.3.x-NTS.so
;jenniferAgent.agent_file_root=/usr/local/jennifer5-debug/

Red Hat 계열 Linux에서 SELINUX 구동시 PHP 에이전트 구동 법

Red Hat 계열 Linux(Red Hat, CentOS) 에서 SELINUX가 동작 중이라면 아래 방법 중 하나를 사용해야 한다.

SELINUX를 permissive 방식으로 변경

다음 명령을 통해 SELINUX를 permissive 모드로 사용하면 PHP 에이전트가 정상적으로 실행된다.

# setenforce 0

SELINUX 컨텍스트를 변경

설치 패키지에 포함된 te 파일을 사용해 SELINUX 컨텍스트를 변경할 수 있다.

# yum install policycoreutils-python //policy utility를 설치한다. centos5의 경우 기본 설치되어 있다. 
# chmod +x selinux_enable.sh
# selinux_enable.sh centos_#.te //OS버전에 맞는 te파일을 실행한다. 예를 들어 centos 6 이나 Red Hat 6인 경우 selinux_enable.sh centos_6.te로 실행해야 한다.

문제 해결

설치 패키지에 포함된 te 파일로 SELINUX 컨텍스트를 변경한 경우에도 OS의 가변적인 환경 설정에 의해 PHP 에이전트가 구동되지 않을 수도 있다. 이 경우 다음 과정을 반복해 SELINUX 컨텍스트를 변경해야 한다.

# grep httpd_t /var/log/audit/audit.log | audit2allow -m jennifer_2 > jennifer_2.te
# ./selinux_enable.sh jennifer_2.te

설치 문제 해결

PHP 에이전트를 설치 한 후 Apache 또는 php-fpm을 재시작 했을때 PHP 에이전트 설치 디렉토리의 log 디렉토리에 로그 파일이 생성되야 한다. 만약 로그 파일이 생성되지 않았다면 PHP 엔진이 제니퍼 PHP 모듈을 정상 로드하지 못한 것으로, Apache 또는 php-fpm 로그를 확인해야 한다.

grep jennifer error.log //error.log는 Apache의 에러 로그 파일을 지칭한다.

PHP 5.2.x 버전의 경우

PHP 5.2.x 버전의 경우 php.ini의 extension 옵션에 절대 경로로 지정한 Jennifer5Agent Extension so 파일을 로드하지 못할 수 있다. 이 경우 다음과 같이 php.ini의 extension_dir에 심볼릭 링크 파일들을 생성하고, php.ini파일을 수정해야 한다.

php의 extension_dir 경로 확인

php -i | grep extension_dir

extension_dir 경로로 이동 후 심볼릭 파일 링크 생성

cd /usr/local/lib/php/extensions/no-debug-non-zts-20060613
ln -s /home/jennifer/agent.php/bin/jennifer5-php-5.2.x-NTS.so jennifer5-php-5.2.x-NTS.so
ln -s /home/jennifer/agent.php/bin/Jennifer5Agent Jennifer5Agent 
ln -s /home/jennifer/agent.php/bin/libJennifer5Common.so libJennifer5Common.so

php.ini 에 지정된 Jennifer Agent Extension 경로를 다음과 같이 수정

extension=jennifer5-php-5.2.x-NTS.so

No such file or directory

PHP Warning:  PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.5.x-ZTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.5.x-ZTS.so: cannot open shared object file: No such file or directory in Unknown on line 0

php.ini에 제니퍼 설치 경로가 잘못 지정된 경우 이 문제가 발생한다. php.ini의 extension과 jenniferAgent.agent_file_root 옵션 지정 값을 확인해야 한다.

undefined symbol

PHP Warning:  PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so: undefined symbol: output_globals in Unknown on line 0

PHP 버전, 또는 PHP Thread Safety 환경에 일치하지 않는 jennifer extension 모듈이 지정되었을때 이 로그를 확인할 수 있다. php.ini 의 extension=.../jennifer5-php-5...-NTS.so를 PHP 환경에 맞는 파일로 지정해야 한다. 예를 들어 Thread Safety 모드로 동작하는 PHP 5.5.8 버전 이라면 jennifer5-php-5.5.x-ZTS.so를 지정해야 한다.

Wrong ELF class

Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so: wrong ELF class: ELFCLASS64 in Unknown on line 0

32bit 머신에 64bit PHP 에이전트를 설치 했거나, 64bit 머신에 32bit PHP 에이전트를 설치 했을 때 위와 같은 로그(wrong ELF class)를 확인할 수 있다. 64bit 머신에 32bit로 빌드된 Apache, php-fpm을 사용할 경우에도 위와 같은 로그를 확인할 수 있는데, 이 경우는 64bit 머신이라도 32bit PHP 에이전트를 설치해야 한다.

version 'GCC_4.2.0' not found

Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /lib/libgcc_s.so.1: version `GCC_4.2.0' not found (required by /home/jennifer5/agent.php/bin/libJennifer5Common.so) in Unknown on line 0

Apache, php-fpm이 참조하는 libgcc_s.so.1 버전이 GCC_4.2.0을 지원하지 않는 경우에 이 로그를 확인할 수 있다. libgcc_s.so.1을 업데이트 해야 하며, 업데이트 불가시 PHP 에이전트를 구동할 수 없다.(라이브러리 의존성 참고)