Database related Q&A	Authenticated access to debugger
	Last updated: Mon, 30 Jan 2023

HOWTO: Install debugger module

• Debugger module for php is a php extension that should be installed on the same machine where you're running php
• You need a web server with PHP properly configured. Follow these instructions on how to install php. If you don't have a web server for the development purpose, you can use SRV web server that comes with NuSphere PhpED IDE
• PHP and PHP debugger (dbg) are already installed for local debugging with SRV web server
• Debugger modules for all supported platforms are available in the following directory:
  %PROGRAMFILES%\NuSphere\PhpED\debugger\server
• Debugger modules that support TLS-encrypted communication and authenticated access (safe debugging), are available with NuSphere PhpED PRO commerical version only
• All web servers (including Apache, NginX and IIS) capable of running PHP, are supported for debugging php. List of supported platforms is available
• If you want to debug in NuSphere PhpED IDE either locally or remotely, you can quickly setup php debuger using Project Settings Wizard. It will check php and debugger installation, help configuring them, test the results, and suggest what to do in case of problems.
• It's possible to install debugger module with Project Settings Wizard help or without it

• Start NuSphere PhpED IDE
• If you don't have projects, please create one and Wizard will start automatically
• Open Project -> Project Properties dialog and click [Wizard] button at the bottom
• Proceed with Project Settings Wizard. It will inspect your php and web server configuration. If debugger is not yet installed, it will suggest how to install debugger, then it will check the debugger functionality.
  NOTE: You will need dbg-wizard.php script on your server. Wizard can upload it for you if project has an associated publishing account.
  
  

PREPARE

• PHP should be installed and properly configured (see this page for instructions on how to install PHP)
• Create a simple script shown below and run it using your favorite browser
  
  <?php
    phpinfo();
  ?>
• Locate path to php.ini listed in phpinfo's topmost header. This file will be needed in steps 4, 7, and 8 below
• Make sure extension_dir shown in phpinfo page is not ./ otherwise please set extension_dir to have an absolute path. For example "c:\php5\ext" under Windows or "/usr/lib/php5/modules" under unix.

INSTALL

• Find php debugger module for the target server platform in %PROGRAMFILES%\NuSphere\PhpED\debugger\server directory, for example C:\Program Files (x86)\NuSphere\PhpED\debugger\server\Windows or C:\Program Files (x86)\NuSphere\PhpED\debugger\server\Linux for Windows and Linux respectively. Debugger modules for all platforms except Windows are packed into tar.gz archive. All archives have directories with supported CPU type as directory name and thread safety indicator _TS appended to its name (if appropriate) at the first level. Debugger module files indicate php version they are compatible with. For example, debugger 5.0.7 module for php 5.3, thread safe, for FreeBSD x86 32bit platform will be found in dbg-5.0.7-FreeBSD.tar.gz archive, x86_TS subdirectory and file name will be dbg-php-5.3.so.
  Please see "Debugging PHP on various platforms" for the table of all supported platforms and the corresponding debugger modules.
• Copy selected module into extension_dir directory on the server.
• Pick correct zend_extension_ts vs zend_extension line to load the module and add it to php.ini
  If the OS is Windows and Thread Safety is enabled and php version is 5.2 or below:
  zend_extension_ts="c:\path\to\dbg-php-5.2.dll"
  
  if the OS is Windows and Thread Safety is disabled or php version is 5.3 or above:
  zend_extension="c:\path\to\dbg-php-5.3.dll"
  if the OS is UNIX and Thread Safety is disabled or php version is 5.3 or above:
  zend_extension="/usr/lib/php5/modules/dbg-php-5.3.so"
  if the OS is UNIX and Thread Safety is enabled and php version is 5.2 or below:
  zend_extension_ts="/usr/lib/php5/modules/dbg-php-5.2.so"
Notes:
-This line should appear before any other zend_extension(s) unless you're using IonCube. In latter case, debugger should be placed below it.
-If you run 32bit php (under for example 32bit apache), you have to load 32bit debugger module even though the OS is 64bit.
-Starting with version 5.3, php does not support zend_extension_ts anymore. With this version, you always have to use only zend_extension.

CONFIGURE

• Add the following debugger settings to php.ini
  
  [debugger]
  debugger.enabled=on
  debugger.profiler_enabled=on
  debugger.hosts_allow=host1 host2 host3
  debugger.hosts_deny=ALL
  debugger.ports=7869, 10000/16
  
  
  where:
  -host1 host2 and host3 are host names or IP addresses of development machines allowed to start debug sessions. If you run debugger through SSH tunnel, you have to add only localhost.
  -7869, 10000/16 means port 7869 and all ports in range from 10000 to 10015 are allowed
  -debugger.hosts_deny=ALL means prohibit all except allowed
  

Extra settings to enable TLS encryption and authenticated access to debugger with client SSL certificates (available to PRO customers only):
[debugger]
debugger.ssl=1
debugger.client_auth = On
debugger.ssl_CA=/path/to/ca-certificate.pem

where:
- debugger.ssl=1 enforces TLS encryption
- debugger.client_auth=On allows only clients authenticated with SSL certificate to work with debugger
- /path/to/ca-certificate.pem is a CA certificate that signed client SSL certificate.

Short instructions on how to create SSL certificates:
- create a CA key and certificate

openssl req -x509 -config openssl-ca.cnf -newkey rsa:2048 -sha256 -nodes -out cacert.pem -outform PEM
where openssl-ca.cnf has CA_default section with x509_extensions key pointing to CA related configuration - create client certificate and signing request

openssl req -config openssl-client.cnf -newkey rsa:2048 -sha256 -nodes -out dbglistener.csr -outform PEM
- sign client certificate with CA certificate

openssl ca -verbose -config openssl-ca.cnf -policy signing_policy -extensions signing_req -out dbglistener.pem -infiles dbglistener.csr
- keep CA key in trusted and secure location
- copy CA certificate to the server and configure debugger module to load it
- copy client certificate and key to the client machine so IDE can access it
- configure SSL Certificate and SSL Certificate key entries in the IDE debugger settings to load client certificate and key respectively. By default IDE uses dbglistener.cert and dbglistener.key in %APPDATA%\NuSphere\PhpED\config\openssl\ directory
NOTE:
- when authentication with SSL certificates is enabled, debugger module checks signature and validity period. Other fields like CN are not verified
- one CA certificate can sign multiple client sertificates. In this case they all can be used by different clients and they all will be authenticated with single CA certificate on the server
- multiple CA certificates are supported. In this case they should be concatenated into single CA file

VERIFY

• Restart web server (you have to restart IIS Admin service if you're using IIS)
• Launch phpinfo and check the output. Make sure that the topmost header contains:
  Zend Engine v3.2.0, Copyright (c) 1998-2022 Zend Technologies with DBG v11.0.x, (C) 2000,2023, by Dmitri Dmitrienko
• If server stopped showing phpinfo page or debugger did not appear on this page, please check these installation troubleshooing
• Verify the results using Project Settings Wizard

Database related Q&A	Authenticated access to debugger
	Last updated: Mon, 30 Jan 2023