Differences

This shows you the differences between two versions of the page.

--- litespeed_wiki:other-ext-apps:apache-mod-perl-equivalent [2018/04/10 18:35]
Jackson Zhang [For LSWS native configuration]
+++ litespeed_wiki:other-ext-apps:apache-mod-perl-equivalent [2020/08/29 14:56]
Lisa Clarke Copyediting
@@ Line 1: / Line 1: @@
-===== How to run perl script on LSWS? =====
+====== How to Run a Perl Script on LSWS ======
-LiteSpeed comes with a persistent Perl CGI daemon which can run perl CGI script without modification, just like mod_perl in Apache.
+LiteSpeed Web Server comes with a persistent Perl CGI daemon which can run Perl CGI scripts without modification, just like mod_perl in Apache.
-==== For Control Panel Environment ====
+===== For a Control Panel Environment =====
-If you configure LSWS to run perl under control panel environment, such as cPanel, you need to configure it as a Fast CGI application, and then add a script handler for "pl" or whatever suffixes used for Perl scripts. The Perl CGI daemon is located at
+==== Set up a Perl FastCGI External App and Script Handler ====
+If you configure LSWS to run Perl under a control panel environment, such as cPanel, you need to configure it as a Fast CGI application, and then add a script handler for "pl" (or whatever suffix is used for Perl scripts). The Perl CGI daemon is located at ''/usr/local/lsws/fcgi-bin/lsperld.fpl''
-  /usr/local/lsws/fcgi-bin/lsperld.fpl
 {{ :litespeed_wiki:other-ext-apps:lsperld-ext-app.png?600 |}}
 {{ :litespeed_wiki:other-ext-apps:lsperld-ext-app-handler.png?600 |}}
+<code>
+    <extProcessor>
+      <type>fcgi</type>
+      <name>PerlFastCGI</name>
+      <address>uds://tmp/lshttpd/perl.sock</address>
+      <maxConns>35</maxConns>
+      <env>FCGI_PERL_MAX_REQ=1000</env>
+      <env>LSAPI_CHILDREN=35</env>
+      <initTimeout>60</initTimeout>
+      <retryTimeout>0</retryTimeout>
+      <persistConn>1</persistConn>
+      <pcKeepAliveTimeout>30</pcKeepAliveTimeout>
+      <respBuffer>0</respBuffer>
+      <autoStart>1</autoStart>
+      <path>/usr/local/lsws/fcgi-bin/lsperld.fpl</path>
+      <backlog>100</backlog>
+      <instances>1</instances>
+      <memSoftLimit>2074M</memSoftLimit>
+      <memHardLimit>2074M</memHardLimit>
+      <procSoftLimit>400</procSoftLimit>
+      <procHardLimit>500</procHardLimit>
+    </extProcessor>
+</code>
+<code>
+   <scriptHandler>
+      <suffix>pl</suffix>
+      <type>fcgi</type>
+      <handler>PerlFastCGI</handler>
+    </scriptHandler>
+</code>
-Restart LSWS, then done.
+Restart LiteSpeed Web Server.
-==== For LSWS native configuration ====
+==== Testing on cPanel ====
-For LSWS native cofiguration, you also need to procede the above step to setup Fast CGI application and then add a script handler for "pl".
+For a Perl or CGI script to run in a control panel environment, normally you should place the script in a designated directory such as ''/cgi-bin/'', otherwise it may not work.
-As "lsperld.fpl" utilizes the Fast CGI interface, it has normally been configured on control panel environment already.  However you may need to install Perl Fast CGI module FCGI.pm first in LSWS + bare OS situation since it may not be installed.
+You can create a simple test script hello.pl under /cgi-bin/
+<code>
+  #!/usr/bin/perl
+  use strict;
+  use warnings;
+  print "Content-type: text/html\n\n";
+  print("Hello World\n");
+</code>
-Perl Fast CGI module is available at CPAN(Comprehensive Perl Archive Network).
+You can also run perl from the command line to verify the error:
+<code>
+  perl -w hello.pl
+</code>
-On CentOS7, to add perl-CPAN package first.
+Visit ''https://yourdomain.com/cgi-bin/hello.pl'' from the browser to see if it works.
+If it works from the command line but doesn't work from the browser, most likely this is caused by an "x" permission issue. Perl or the CGI script will need to allow everyone "x" permission, like so:
+<code>
+  chmod 755 hello.pl
+</code>
+Perl script errors are beyond our support scope and you are encouraged to google for solutions. You can check [https://docs.cpanel.net/knowledge-base/general-systems-administration/troubleshooting-guide-for-perl-and-cgi-scripts/|cPanel's documentation] to troubelshoot similar CGI/Perl issues on cPanel.
+===== For LSWS Native Configuration =====
+==== Perl FastCGI for LSWS Native Configuration ====
+For LSWS native configuration, you also need to set up the Fast CGI application and add a script handler for "pl".
+As ''lsperld.fpl'' utilizes the Fast CGI interface, it is usually already configured for control panel environments. That may not be the case in a LSWS + bare OS situation. You may need to install the Perl Fast CGI module ''FCGI.pm''.
+The Perl Fast CGI module is available at CPAN(Comprehensive Perl Archive Network).
+On CentOS7, add the ''perl-CPAN'' package first:
   yum install epel-release
   yum install gcc
   yum install perl-CPAN
-The following command can be used to install FCGI.pm through CPAN:
+The following command can be used to install ''FCGI.pm'' through CPAN:
   perl -MCPAN -e 'install FCGI'
-On CentOS box, you can easily install perl-CGI and perl-FCGI packages through:
+On a CentOS box, you can install ''perl-CGI'' and ''perl-FCGI'' packages through:
   yum install perl-CGI
-Verify the installed location of FCGI.pm.
+Verify the installed location of ''FCGI.pm''.
   find / -name FCGI.pm
   /usr/lib64/perl5/vendor_perl/FCGI.pm
-In order to deal with increasing memory usage of a persistent process, the number of requests that a Perl daemon can process is controlled by an environment variable FCGI_PERL_MAX_REQ, the default is 500.
+In order to deal with the increasing memory usage of a persistent process, the number of requests that a Perl daemon can process is controlled by an environment variable ''FCGI_PERL_MAX_REQ''. The default value is ''500''.
-For example: FCGI_PERL_MAX_REQ=1000.
-Restart LSWS to make the change effective.
+For example: ''FCGI_PERL_MAX_REQ=1000''.
-==== Troubleshooting ====
-Without perl-CPAN package installed, the above installation may run into the following error:
+Restart LSWS to make the changes effective.
+==== Testing ====
+Place a test script called ''test.pl'' in the document root of one of your virtual hosts:
+  #!/usr/bin/perl
+  print "Content-type:text/html\n\n";
+  print <<EndOfHTML;
+  <html><head><title>Perl Environment Variables</title></head>
+  <body>
+  <h1>Perl Environment Variables</h1>
+  EndOfHTML
+  foreach $key (sort(keys %ENV)) {
+    print "$key = $ENV{$key}<br>\n";
+  }
+  print "</body></html>";
+You should see something similar to the following when visting ''nowiki>http://yourdomain.com/test.pl</nowiki>''
+<code>
+Perl Environment Variables
+DOCUMENT_ROOT = /usr/local/lsws/DEFAULT/html
+FCGI_PERL_MAX_REQ = 1000
+FCGI_ROLE = RESPONDER
+GATEWAY_INTERFACE = CGI-PerlEx/1.1
+HTTP_ACCEPT = text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
+HTTP_ACCEPT_ENCODING = gzip, deflate
+HTTP_ACCEPT_LANGUAGE = en-US,en;q=0.9
+HTTP_CONNECTION = keep-alive
+HTTP_COOKIE = SESS3d805002e809eafb1aa4295801ff28d0=AXgcoPkfgngK9KYuHS4wIn9eVLHEndfHAy7Ys9Gnj4M; COMBIN=2e9910cb4771588a621ae6371c01550bdbe3e6d498788981dca50a1ab6bef6d3; COMINF=bypass_varnish
+HTTP_HOST = 192.168.0.178:8088
+HTTP_UPGRADE_INSECURE_REQUESTS = 1
+HTTP_USER_AGENT = Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36
+LSAPI_CHILDREN = 35
+LSAPI_PADDING = leave_some_room_to_avoid_overwrite_important_env
+PATH = /bin:/usr/bin:/usr/local/bin
+QUERY_STRING =
+REMOTE_ADDR = 192.168.0.198
+REMOTE_PORT = 4322
+REQUEST_METHOD = GET
+REQUEST_URI = /test.pl
+SCRIPT_FILENAME = /usr/local/lsws/DEFAULT/html/test.pl
+SCRIPT_NAME = /test.pl
+SERVER_ADDR = 192.168.0.178
+SERVER_ADMIN =
+SERVER_NAME = 192.168.0.178
+SERVER_PORT = 8088
+SERVER_PROTOCOL = HTTP/1.1
+SERVER_SOFTWARE = LiteSpeed
+</code>
+===== Troubleshooting =====
+==== Installation Error on LSWS Native ====
+Without the ''perl-CPAN'' package installed, installation may run into the following error:
   Can't locate CPAN.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .).
   BEGIN failed--compilation aborted.
-Without installing FCGI.pm, you may run into the following error in stderr.log and 503 error on screen.
+Without installing ''FCGI.pm'', you may run into the following error in ''stderr.log'' and see a 503 error on screen.
    [STDERR] Can't locate FCGI.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at /usr/local/lsws/fcgi-bin/lsperld.fpl line 3
+==== lscgid: execve() No such file error ====
+A simple test perl script on a cPanel server runs into the following error and generates a 500 error code:
+  lscgid: execve():/home/user1/public_html/test.pl: No such file or directory
+{{ :litespeed_wiki:other-ext-apps:perl-lscgid-execve-nosuchfile-error.png?600 |}}
+But ''/home/user1/public_html/test.pl'' //does// exist. So why the ''No such file or directory'' error?
+Inspect the file in vi:
+  cd /home/user1/public_html/
+  vi test.pl
+There is a ''^M'' at the end of each line, which means the file is in DOS/Windows format, not Unix format:
+  #!/usr/bin/perl^M
+  print "Content-type:text/html\n\n";^M
+  print <<EndOfHTML;^M
+  <html><head><title>Perl Environment Variables</title></head>^M
+  <body>^M
+  <h1>Perl Environment Variables</h1>^M
+  EndOfHTML^M
+  foreach $key (sort(keys %ENV)) {^M
+    print "$key = $ENV{$key}<br>\n";^M
+  }^M
+  print "</body></html>";
+To test further, try:
+  [[ $(file test.pl) =~ CRLF ]] && echo dos
+It returns:
+  dos
+Because of the difference in DOS vs Unix format, LiteSpeed lscgid can not recognize the ''test.pl'' file. Hence the ''No such file or directory'' error.
+To fix the issue, you will need to convert from DOS format to Unix. There are many ways to do so, including the following ''awk'' command:
+  mv test.pl test.pl.dos
+  awk 'sub("$", "\r")' test.pl.dos > test.pl
+You can inspect ''test.pl'' again in vi to verify the file format. You should no longer see the trailing ''^M'' in each line.
+  #!/usr/bin/perl
+  print "Content-type:text/html\n\n";
+  print <<EndOfHTML;
+  <html><head><title>Perl Environment Variables</title></head>
+  <body>
+  <h1>Perl Environment Variables</h1>
+  EndOfHTML
+  foreach $key (sort(keys %ENV)) {
+  print "$key = $ENV{$key}<br>\n";
+  }
+After the conversion, you should find the perl script is working perfectly.