Difference between revisions of "Koozali SME Server Debugging"

From SME Server
Jump to navigationJump to search
(11 intermediate revisions by the same user not shown)
Line 4: Line 4:
  
 
There are several ways to do this, both locally and remotely.
 
There are several ways to do this, both locally and remotely.
 +
 +
===Enable template debugging===
 +
 +
I happened to stumble over this in the templates.pm file
 +
 +
config set processtemplate Debug yes
 +
 +
This will add some debugging lines to /var/log/messages showing you the progress of the template expansion.
 +
 +
To disable either set the key to no or delete it.
 +
 +
===Builtin Db routines===
 +
 +
You can also use a couple of routines from db.pm
 +
 +
=item B<db_print>
 +
  db_print(\%config);
 +
  db_print(\%config, $key);
 +
Prints out keys and raw values in the %config database.  If $key is
 +
given it prints the $key and its raw value.  If no $key is given it
 +
prints out all the keys and their raw values.
 +
 +
=item B<db_show>
 +
  db_show(\%config);
 +
  db_show(\%config, $key);
 +
Prints out keys and their values in a human readable format.
 +
If $key is given it prints out the $key, type and properties of that
 +
$key.  Otherwise it prints out the key, type and properties for all
 +
keys.
 +
 +
=item B<db_print_type>
 +
  db_print_type(\%config);
 +
  db_print_type(\%config, $key);
 +
Prints out keys and their types in the %config database.
 +
If $key is given, it prints out just that $key and its type.
 +
Otherwise it prints out all the keys and their types.
 +
 +
=item B<db_print_prop>
 +
  db_print_prop(\%config, $key);
 +
  db_print_prop(\%config, $key, $property);
 +
Prints out the properties (or a single $property) of the given $key in
 +
the %config.
 +
  
 
===Locally using perl -d===
 
===Locally using perl -d===
Line 25: Line 68:
 
  q - quit
 
  q - quit
  
===Remotely using an IDE===
+
===Remote debugging using an IDE===
  
 
I have been using Komodo IDE courtesy of an Open Source Developers licence from [http://komodoide.com/ Activestate]
 
I have been using Komodo IDE courtesy of an Open Source Developers licence from [http://komodoide.com/ Activestate]
  
 
They produce an Open Source 'light' version of the full IDE called [http://komodoide.com/komodo-edit/ Komodo Edit] but it does not have the debug facilities.
 
They produce an Open Source 'light' version of the full IDE called [http://komodoide.com/komodo-edit/ Komodo Edit] but it does not have the debug facilities.
 
====Server setup====
 
 
====Single machine setup====
 
  
 
The simplest mode to use with Komodo IDE is to just use the IDE as a debugger to step through code. Code on the remote server can be edited if you have sufficient permissions.
 
The simplest mode to use with Komodo IDE is to just use the IDE as a debugger to step through code. Code on the remote server can be edited if you have sufficient permissions.
Line 40: Line 79:
  
 
This will enable us to work with one desktop and one server. See the section on debug proxy for multiple connections
 
This will enable us to work with one desktop and one server. See the section on debug proxy for multiple connections
 +
 +
====Server setup====
  
 
From your installed Komodo directory we need to copy a set of files to the server.
 
From your installed Komodo directory we need to copy a set of files to the server.
Line 54: Line 95:
 
  export PERLDB_OPTS=RemotePort=your.desktop.i.p:9020 async=1
 
  export PERLDB_OPTS=RemotePort=your.desktop.i.p:9020 async=1
  
Note: As with local debugging, the Break Now function is disabled by default and enabled with async - see the docs for more information
+
If required you can also add a user identifier:
 +
 
 +
export DBGP_IDEKEY=jdoe
 +
 
 +
Note: As with local debugging, the Break Now function is disabled by default. Setting async=1 breaks at the first line - see the docs for more information
 +
 
 +
====Single machine setup====
  
 
On your desktop we need to set up the Listener for Komodo.
 
On your desktop we need to set up the Listener for Komodo.
Line 60: Line 107:
 
  Edit/Preferences/Debugger/Connection
 
  Edit/Preferences/Debugger/Connection
 
  Set a specific port to 9020 (match the port above)
 
  Set a specific port to 9020 (match the port above)
 +
Set a user name as above
  
 
Now we need to start a program on the server. The debug code will then call Komodo.
 
Now we need to start a program on the server. The debug code will then call Komodo.
Line 117: Line 165:
 
Either reboot the server or use the following:
 
Either reboot the server or use the following:
  
  export PERL5LIB /usr/local/lib64/perl5:/usr/local/share/perl5:/usr/lib64/perl5/vendor_perl:/usr/share/perl5/vendor_perl
+
  export PERL5LIB=/usr/local/lib64/perl5:/usr/local/share/perl5:/usr/lib64/perl5/vendor_perl:/usr/share/perl5/vendor_perl
 
  export PERLDB_OPTS=
 
  export PERLDB_OPTS=
 +
export DBGP_IDEKEY=jdoe
  
 
==== Perl CGI Debugging====
 
==== Perl CGI Debugging====
Line 124: Line 173:
 
[[Debugging CGI programs on live production servers can seriously impair performance. You have been warned !!]]
 
[[Debugging CGI programs on live production servers can seriously impair performance. You have been warned !!]]
  
I have not tested this as yet. Please see here for further details:
+
Please see here for further details:
  
 
http://docs.komodoide.com/Manual/debugperl#debugging-perl-komodo-ide-only_configuring-perl-for-cgi-debugging
 
http://docs.komodoide.com/Manual/debugperl#debugging-perl-komodo-ide-only_configuring-perl-for-cgi-debugging
  
You would need a custom httpd.conf frgament with the following (I am not going to go into the full how to here)
+
You would need a custom httpd.conf fragment. I used 46PerlDebug with these options (configure to suit)
 +
 
 +
SetEnv PERL5LIB "/opt/dbgp/perllib:$PERL5LIB"
 +
SetEnv PERLDB_OPTS "RemotePort=192.168.x.x async=1"
 +
SetEnv DBGP_IDEKEY "user"
  
SetEnv PERL5LIB "/opt/dbgp/perllib"
+
You should now be able access your cgi-script and debug accordingly.
SetEnv PERLDB_OPTS "RemotePort=<hostname>:<port>"
 
SetEnv DBGP_IDEKEY "<ide_key>"
 
  
You should now be able access your cgi-script - e.g. server-manager and debug accordingly.
+
However, having tried it you cannot use this on server-manager panels because perl is setuid.
  
 +
It could be used in other scenarios, but not server-manager.
  
====Multiple machine debug proxy====
+
===Multiple machine debug proxy===
  
 
TBA
 
TBA
Line 144: Line 196:
 
http://docs.komodoide.com/Manual/debugger#debugging-programs-komodo-ide-only_remote-debugging_debugger-proxy
 
http://docs.komodoide.com/Manual/debugger#debugging-programs-komodo-ide-only_remote-debugging_debugger-proxy
  
 +
====PHP remote debugging====
 +
 +
You can debug on your local workstation but it is extremely useful to be able to debug direct on the server environment.
 +
You may have one PHP version installed on your desktop but be running a different one on the server, and you may have a different server setup.
 +
 +
First you need to install the xdebug packages eg:
 +
 +
yum install php74-php-pecl-xdebug
 +
yum install php80-php-pecl-xdebug
 +
 +
Next you need a small template fragment to enable remote debugging:
 +
 +
mkdir -p /etc/e-smith/templates-custom/etc/php.ini
 +
nano /etc/e-smith/templates-custom/etc/php.ini/90XdebugSettings
 +
 +
Add this:
 +
 +
[Debugger]
 +
; /etc/e-smith/templates-custom/etc/php.ini
 +
xdebug.remote_enable                  = true
 +
xdebug.remote_host                    = 127.0.0.1
 +
xdebug.remote_port                    = 9000
 +
xdebug.remote_handler                  = dbgp
 +
xdebug.remote_log                      = /var/log/xdebug.log
 +
xdebug.remote_mode                    = req
 +
xdebug.max_nesting_level              = 5000
 +
 +
Expand templates and restart services:
 +
 +
signal-event webapps-update
 +
 +
We should see Xdebug here
 +
 +
php74 -v
 +
PHP 7.4.28 (cli) (built: Feb 15 2022 13:23:10) ( NTS )
 +
Copyright (c) The PHP Group
 +
Zend Engine v3.4.0, Copyright (c) Zend Technologies
 +
    with Zend OPcache v7.4.28, Copyright (c), by Zend Technologies
 +
    with Xdebug v2.9.8, Copyright (c) 2002-2020, by Derick Rethans
 +
 +
====Komodo IDE====
 +
 +
We can obtain the debug proxy from the installation, and move it to the server and then execute from there:
 +
 +
python /root/dbgp/bin/pydbgpproxy -d 127.0.0.1:9000 -i 192.168.10.1:9003
 +
 +
Or alternatively grab the lastest xdebug client here:
 +
 +
mkdir /root/xdbg-proxy
 +
cd /root/xdbg-proxy
 +
curl https://xdebug.org/files/binaries/dbgpProxy -o dbgpProxy
 +
chmod 0700 dbgpProxy
 +
./dbgpProxy -s 127.0.0.1:9000 -i 192.168.10.1:9003
 +
 +
In Komodo Go to Preferences, Debugger, Connections
 +
 +
Komodo should listen on:
 +
System provide port
 +
 +
Check 'I am running a debugger proxy'
 +
Listener address: IP.of.your.server:9003
 +
Proxy key: individual key name for this desktop
 +
 +
Save and check that it connected to the debugger.
 +
 +
Now to debug a file:
 +
 +
https://your.server.ip/index.php?XDEBUG_SESSION_START=mydesktopkey
 +
 +
Or
 +
 +
https://your.server.ip/index.php?somevalue=3&XDEBUG_SESSION_START=mydesktopkey
 +
 +
====Visual Studio/VS Codium====
 +
 +
Sample launch.json
 +
 +
Note for newer versions of Xdebug the default port is now 9003
 +
Pay careful attention to the path mapping,. This has to be absolutely correct or it will not work.
 +
 +
{
 +
    // Use IntelliSense to learn about possible attributes.
 +
    // Hover to view descriptions of existing attributes.
 +
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 +
    "version": "0.2.0",
 +
    "configurations": [
 +
        {
 +
            "name"        : "vscphpdebug",
 +
            "type"        : "php",
 +
            "request"    : "launch",
 +
            "stopOnEntry" : false,
 +
            "proxy": {
 +
            "enable" : true,
 +
            "host" : "my.server.ip",
 +
            "key" : "mycodiumkey",
 +
            "port": 9003,
 +
            "allowMultipleSessions" : true
 +
            },
 +
            "pathMappings": {
 +
            "/home/e-smith/files/ibays/testbay/html/phptestcode": "${workspaceFolder}"
 +
            },
 +
        },
 +
    ]
 +
}
 +
 +
Now you can run start the PHP debugger in Codium so it connects the to the debug server, and then trigger it with a URL like this:
 +
 +
https://my.SME.Server/testbay/phptestcode/myTestPhpFile.php?XDEBUG_SESSION_START=mycodiumkey
 +
 +
===Editors and IDEs===
 +
 +
Some Open Source Editors/IDEs
 +
 +
These all allow remote debugging.
 +
 +
Komodo-IDE https://www.activestate.com/products/komodo-ide
 +
 +
Komodo Debug tools: https://code.activestate.com/komodo/remotedebugging/
 +
 +
Eclipse https://www.eclipse.org/
 +
 +
Netbeans https://netbeans.org/
 +
 +
Codium https://itsfoss.com/vscodium/ - Use PHP Debug - felixfbecker.php-debug
 +
<br>
 +
For Codium I can't see a remote Perl debugger as yet.
  
 
----
 
----
 
[[Category:Howto]]
 
[[Category:Howto]]
 
[[Category:Developer]]
 
[[Category:Developer]]
 +
[[Category:SME Server Development Framework]]
 +
[[Category:Development Tools]]

Revision as of 14:43, 22 March 2022

Server debugging

One issue that is often found to be problematic by new developers is debugging perl code on your SME server.

There are several ways to do this, both locally and remotely.

Enable template debugging

I happened to stumble over this in the templates.pm file

config set processtemplate Debug yes

This will add some debugging lines to /var/log/messages showing you the progress of the template expansion.

To disable either set the key to no or delete it.

Builtin Db routines

You can also use a couple of routines from db.pm

=item B<db_print>
 db_print(\%config);
 db_print(\%config, $key);
Prints out keys and raw values in the %config database.  If $key is
given it prints the $key and its raw value.  If no $key is given it
prints out all the keys and their raw values.
=item B<db_show>
 db_show(\%config);
 db_show(\%config, $key);
Prints out keys and their values in a human readable format.
If $key is given it prints out the $key, type and properties of that
$key.  Otherwise it prints out the key, type and properties for all
keys.
=item B<db_print_type>
 db_print_type(\%config);
 db_print_type(\%config, $key);
Prints out keys and their types in the %config database.
If $key is given, it prints out just that $key and its type.
Otherwise it prints out all the keys and their types.
=item B<db_print_prop>
 db_print_prop(\%config, $key);
 db_print_prop(\%config, $key, $property);
Prints out the properties (or a single $property) of the given $key in
the %config.


Locally using perl -d

There are a number of tutorials online.

To start you use:

perl -d myFile.pl

There are then a number of options you can use to control the debugger:

l 10 - list line 10
l get_pattern - find lines matching 'pattern'
b 22 - set breakpoint at line 22
s - step forward a line including all subroutines
n - step forward a line but jump through subroutines
c - continue to next break point
c 47 - continue to line 47
p $variable - print variable
q - quit

Remote debugging using an IDE

I have been using Komodo IDE courtesy of an Open Source Developers licence from Activestate

They produce an Open Source 'light' version of the full IDE called Komodo Edit but it does not have the debug facilities.

The simplest mode to use with Komodo IDE is to just use the IDE as a debugger to step through code. Code on the remote server can be edited if you have sufficient permissions.

http://docs.komodoide.com/Manual/debugperl

This will enable us to work with one desktop and one server. See the section on debug proxy for multiple connections

Server setup

From your installed Komodo directory we need to copy a set of files to the server.

I actually copied the entire dbgp directory as there are other files in there that are useful including the debug proxy.

scp -r ~/komdoeditDirectory/lib/support/dbgp root@some.server://opt/

We should now have /opt/dbgp on the server

We now need to set some paths on the server:

export PERL5LIB=/opt/dbgp/perllib:$PERL5LIB
export PERLDB_OPTS=RemotePort=your.desktop.i.p:9020 async=1

If required you can also add a user identifier:

export DBGP_IDEKEY=jdoe

Note: As with local debugging, the Break Now function is disabled by default. Setting async=1 breaks at the first line - see the docs for more information

Single machine setup

On your desktop we need to set up the Listener for Komodo.

Edit/Preferences/Debugger/Connection
Set a specific port to 9020 (match the port above)
Set a user name as above

Now we need to start a program on the server. The debug code will then call Komodo.

The following forms should work

perl -d myFile.pl

Add -d to the header of your file e.g.

#!/usr/bin/perl -w -d

Then do

perl myFile.pl

Add -d to /sbin/e-smith/signal-event

Then do

signal-event some-event

You should get a popup from Komodo stating that a remote application has requested a debugger session. When you click yes you will get a second box stating that a mapping could not be opened. If we are just going to use Komodo as a debugger then we can answer no and you are then in debug mode allowing you to step through the code and view variables.

Mapping for editing

Should you wish to actually edit code as well you will need to set up some form of file mapping between the URI that the debugger sends and your 'Server' setup in Komodo

Note that without some of the esmith libraries installed locally you will get some warnings about being unable to locate certain files but these can safely be ignored.

In Komodo preferences you need to setup a Server/Remote Account for the remote server. e.g.

Remote Account : Test_v9
Type: SCP
Port: 2222
Username: root
Pass: somepass (or alternatively use SSH keys)

You can then set up a mapping similar to this:

URI : file://v9-test/
Maps To : scp://Test_v9/

Or

URI : file://v9-test/etc/e-smith
Maps To : scp://Test_v9/etc/e-smith

You could be more specific about the directories should you require. Remember that you inherit the server permissions - you cannot save a file that is Read Only on the server !

Local file mapping

Although I have not tried this I believe that you can potentially map from the server to your local files. You can then edit locally, upload and re test.

Tidying up afterwards

Either reboot the server or use the following:

export PERL5LIB=/usr/local/lib64/perl5:/usr/local/share/perl5:/usr/lib64/perl5/vendor_perl:/usr/share/perl5/vendor_perl
export PERLDB_OPTS=
export DBGP_IDEKEY=jdoe

Perl CGI Debugging

Debugging CGI programs on live production servers can seriously impair performance. You have been warned !!

Please see here for further details:

http://docs.komodoide.com/Manual/debugperl#debugging-perl-komodo-ide-only_configuring-perl-for-cgi-debugging

You would need a custom httpd.conf fragment. I used 46PerlDebug with these options (configure to suit)

SetEnv PERL5LIB "/opt/dbgp/perllib:$PERL5LIB"
SetEnv PERLDB_OPTS "RemotePort=192.168.x.x async=1"
SetEnv DBGP_IDEKEY "user"

You should now be able access your cgi-script and debug accordingly.

However, having tried it you cannot use this on server-manager panels because perl is setuid.

It could be used in other scenarios, but not server-manager.

Multiple machine debug proxy

TBA

Notes are here: http://docs.komodoide.com/Manual/debugger#debugging-programs-komodo-ide-only_remote-debugging_debugger-proxy

PHP remote debugging

You can debug on your local workstation but it is extremely useful to be able to debug direct on the server environment. You may have one PHP version installed on your desktop but be running a different one on the server, and you may have a different server setup.

First you need to install the xdebug packages eg:

yum install php74-php-pecl-xdebug
yum install php80-php-pecl-xdebug

Next you need a small template fragment to enable remote debugging:

mkdir -p /etc/e-smith/templates-custom/etc/php.ini
nano /etc/e-smith/templates-custom/etc/php.ini/90XdebugSettings 

Add this:

[Debugger]
; /etc/e-smith/templates-custom/etc/php.ini
xdebug.remote_enable                   = true
xdebug.remote_host                     = 127.0.0.1
xdebug.remote_port                     = 9000
xdebug.remote_handler                  = dbgp
xdebug.remote_log                      = /var/log/xdebug.log
xdebug.remote_mode                     = req
xdebug.max_nesting_level               = 5000

Expand templates and restart services:

signal-event webapps-update

We should see Xdebug here

php74 -v
PHP 7.4.28 (cli) (built: Feb 15 2022 13:23:10) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
   with Zend OPcache v7.4.28, Copyright (c), by Zend Technologies
   with Xdebug v2.9.8, Copyright (c) 2002-2020, by Derick Rethans

Komodo IDE

We can obtain the debug proxy from the installation, and move it to the server and then execute from there:

python /root/dbgp/bin/pydbgpproxy -d 127.0.0.1:9000 -i 192.168.10.1:9003

Or alternatively grab the lastest xdebug client here:

mkdir /root/xdbg-proxy
cd /root/xdbg-proxy
curl https://xdebug.org/files/binaries/dbgpProxy -o dbgpProxy
chmod 0700 dbgpProxy
./dbgpProxy -s 127.0.0.1:9000 -i 192.168.10.1:9003

In Komodo Go to Preferences, Debugger, Connections

Komodo should listen on: System provide port

Check 'I am running a debugger proxy' Listener address: IP.of.your.server:9003 Proxy key: individual key name for this desktop

Save and check that it connected to the debugger.

Now to debug a file:

https://your.server.ip/index.php?XDEBUG_SESSION_START=mydesktopkey

Or

https://your.server.ip/index.php?somevalue=3&XDEBUG_SESSION_START=mydesktopkey

Visual Studio/VS Codium

Sample launch.json

Note for newer versions of Xdebug the default port is now 9003 Pay careful attention to the path mapping,. This has to be absolutely correct or it will not work.

{
   // Use IntelliSense to learn about possible attributes.
   // Hover to view descriptions of existing attributes.
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
       {
           "name"        : "vscphpdebug",
           "type"        : "php",
           "request"     : "launch",
            "stopOnEntry" : false,
           "proxy": {
           "enable" : true,
           "host" : "my.server.ip",
           "key" : "mycodiumkey",
           "port": 9003,
           "allowMultipleSessions" : true
           },
           "pathMappings": {
           "/home/e-smith/files/ibays/testbay/html/phptestcode": "${workspaceFolder}"
           },
       },
   ]
}

Now you can run start the PHP debugger in Codium so it connects the to the debug server, and then trigger it with a URL like this:

https://my.SME.Server/testbay/phptestcode/myTestPhpFile.php?XDEBUG_SESSION_START=mycodiumkey

Editors and IDEs

Some Open Source Editors/IDEs

These all allow remote debugging.

Komodo-IDE https://www.activestate.com/products/komodo-ide

Komodo Debug tools: https://code.activestate.com/komodo/remotedebugging/

Eclipse https://www.eclipse.org/

Netbeans https://netbeans.org/

Codium https://itsfoss.com/vscodium/ - Use PHP Debug - felixfbecker.php-debug
For Codium I can't see a remote Perl debugger as yet.