A Fujitsu Siemens Computers GmbH APACHE (BS2000/OSD) Version 2.2A October 2008 README FILE Copyright (C) Fujitsu Siemens Computers GmbH 2008 All rights reserved A README file for delivery unit APACHE V2.2A 1 General 2 1.1 Interactive installation 3 1.2 SSL support 3 1.3 Modified package structure 3 1.4 Modularized server 3 1.5 JAVA Servlet support 3 1.6 Updated Perl support 3 2 Overview 4 2.1 BS2000 package files 4 2.2 Dependencies of the packages 4 2.3 Additional software prerequisites 6 2.4 Changes in the POSIX installation procedure 6 3 Port assignments of the web server 7 4 Installation 8 4.1 APACHE web server ID 8 4.2 BS2000 job attributes 10 4.3 Apache directory structure 10 4.4 POSIX installation in interactive mode 11 4.5 POSIX installation in BATCH mode 12 4.6 POSIX deinstallation 13 5 Operations 13 5.1 Start / stop the web server 13 5.2 Configuration files of the Apache web server 14 5.3 SSL/TLS operation 14 6 SDF support for APACHE:httpd 17 7 Additional tools 20 8 EBCDIC character set support 21 8.1 What must be done with incorrectly converted files? 22 9 HowTo's 22 9.1 How to use disk cache 22 9.2 How to handle Apache authentication with an SQLite database 23 9.3 How to use the forward proxy 24 9.4 How to use a reverse proxy 26 10 PHP notes 26 10.1 PHP directory structure 26 10.2 The PHP configuration file php.ini 26 10.3 EBCDIC-/ASCII dependencies in PHP functions 27 10.4 Time zone specifications 28 11 Oracle notes 28 12 SESAM notes 30 13 SQLITE notes 31 14 Restrictions 31 15 Literature 31 15.1 Online documentation 31 15.2 Apache Essentials: Install, Configure, Maintain 32 15.3 mod_perl2 User's Guide Book 32 15.4 PHP Cookbook (Paperback) 32 15.5 POSIX (BS2000/OSD) - fundamentals for users and system administrator 32 - 1 - A 1 General ------- This readme describes the BS2000 specific differences and exten- sions, and supplements the available online documentation (de- scribing the Unix version) in the packages APACHE:httpd-d, APACHE:modperl-d, and APACHE:modphp-d, which otherwise serve as the reference documentation for the product. It contains informa- tion about installing, configuring and using the components APACHE:httpd V2.2A APACHE:modperl V2.2A APACHE:modphp V2.2A under the operating system BS2000/OSD. 1) APACHE:httpd(BS2000/OSD) V2.2A is based on the official release version of the web server Apache httpd 2.2.8 from the Apache software Foundation. 2) APACHE:modperl(BS2000/OSD) V2.2A is based on version 2.0.3 of the Apache/Perl module mod_perl 3), as well as the Perl runtime envi- ronment version 5.8.8 (see subcomponent PERL (BS2000/OSD) V5.8A). 4) APACHE:modphp(BS2000/OSD) V2.2A is based on version 5.2.5 of the PHP script language 5) The contents correspond to release date: October 2008. This readme file is supplied as file SYSRME.APACHE.022.E (Eng- lish) or SYSRME.APACHE.022.D (German). Any subsequent changes are added to this file (labelled with #) and distributed. Print the file with /PRINT-DOCUMENT FROM-FILE=SYSRME.APACHE.022.E,- / DOC-FORM=*TEXT(LINE-SPACING=*BY-EBCDIC-CONTROL) (English). ________________ 1) BS2000/OSD (R) is a registered name for Fujitsu Siemens Com- puters GmbH 2) This product contains software developed by the Apache Soft- ware Foundation for the Apache HTTP server project (http://httpd.apache.org/). 3) mod_perl (http://perl.apache.org/) is an Apache Software Foundation project (http://www.apache.org/) and is covered by the Apache Software License (an Open Source license) 4) Perl Perl5 is Copyright (C) 1993-2005, by Larry Wall and others. It is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License". 5) This product includes PHP software, freely available from ; PHP is distributed under the PHP License, version 3.01, an Apache-style license. PHP in- cludes the Zend Engine, freely available at . - 2 - A In contrast to the earlier CERN Server used, the Apache Server has greater throughput and a wider range of functions. Version V2.2A00, in contrast to V1.3A11, is a greatly enhanced delivery with numerous new features. In addition to an extended configuration option for EBCDIC documents, it has the following new features highlighted below: 1.1 Interactive installation The required configuration parameters are inquired during the installation so that the web server is ready to start immedi- ately after a successful installation has been completed. 1.2 SSL support The SSL module for APACHE, formerly an add-on product that was not free-of-charge, is now a standard part of the APACHE V2.2 web server package. 1.3 Modified package structure The earlier monolithic package has now been divided into a base package, a web server package, two module packages for mod_perl and mod_php as well as three optional online documentation packages for web server, mod_perl and mod_php. This means that only those components have to be installed which are needed for specific functions. 1.4 Modularized server APACHE V2.2A00 contains numerous new modules via which the ac- cess check can be controlled more flexibly. New caching and proxying modules enable load distribution across several back- end servers. 1.5 JAVA Servlet support The Servlet Engine Apache Tomcat is now used as de-facto stan- dard software for server-side Java execution. Using the new Apache module mod_ajp, the Apache-httpd can be used as front- end, as cache and as accelerator for TOMCAT in an Apache-httpd / TOMCAT combination. 1.6 Updated Perl support The updated module mod_perl 2.0.3 (and the delivery unit PERL V5.8 which is part of APACHE V2.2A00) means that Perl scripts can be executed within an Apache Handler and thus more effi- ciently than in a Perl-CGI. - 3 - A 2 Overview -------- The delivery unit APACHE consists of several package components whose modules can be combined. Depending on the required func- tionality the installation can be limited to the components actu- ally required. 2.1 BS2000 package files The packages are supplied in the form of SINLIBs (or SPULIBs for the SPARC platform, with SPARC binaries instead of /390 binaries) which can be installed using the /START-POSIX-INSTALLATION com- mand. APACHE V02.2A00 (APACHE base package: directories and shared libraries) /390: SINLIB.APACHE.022 SPARC: SPULIB.APACHE.022 APACHE:httpd V02.2A00 (APACHE secure web server) /390: SINLIB.APACHE.022.HTTPD SPARC: SPULIB.APACHE.022.HTTPD /390&SPARC: SYSSDF.APACHE.022 /390&SPARC: SYSSPR.APACHE.022 APACHE:httpd-d V02.2A00 (online documentation about APACHE web server) /390&SPARC: SINLIB.APACHE.022.HTTPD-DOC APACHE:modperl V02.2A00 (PERL APACHE module mod_perl) /390: SINLIB.APACHE.022.MODPERL SPARC: SPULIB.APACHE.022.MODPERL APACHE:modprl-d V02.2A00 (online documentation about the PERL APACHE module) /390&SPARC: SINLIB.APACHE.022.MODPERL-DOC APACHE:modphp V02.2A00 (PHP5 APACHE module libphp5) /390: SINLIB.APACHE.022.MODPHP SPARC: SPULIB.APACHE.022.MODPHP APACHE:modphp-d V02.2A00 (online documentation about the PHP5 APACHE module) /390&SPARC: SINLIB.APACHE.022.MODPHP-DOC The name "APACHE:modphp-d" stands for a package in the form of, for example, a SINLIB.APACHE.022.MODPHP-DOC which is installed via the POSIX-INSTALLER as product "APACHE" and package of prod- uct "MODPHP-D". 2.2 Dependencies of the packages As some of the packages are mutually interdependent, the result- ing package dependencies must be observed during the installation - 4 - A (and vice versa at deinstallation). APACHE (Base package) requires: POSIX-SH prerequisite for: PERL APACHE:httpd APACHE:modperl APACHE:modphp APACHE:httpd (Secure Web Server) requires: APACHE prerequisite for: APACHE:httpd-d APACHE:modperl APACHE:modprl-d APACHE:modphp APACHE:modphp-d APACHE:httpd-d (online docs for APACHE:httpd) requires: APACHE:httpd prerequisite for: -- APACHE:modperl (Perl scripting modules for APACHE:httpd) requires: APACHE PERL APACHE:httpd prerequisite for: APACHE:modprl-d APACHE:modphp APACHE:modphp-d APACHE:modprl-d (online docs for APACHE:modperl) requires: APACHE:httpd prerequisite for: -- APACHE:modphp (PHP scripting modules for APACHE:httpd) requires: APACHE:httpd prerequisite for: -- APACHE:modprl-d (online docs for APACHE:modphp) requires: APACHE:httpd prerequisite for: -- Only the "APACHE" base package and the package "APACHE:httpd" is required for the Apache web server. However, if you wish to in- stall the mod_perl module, the components APACHE, PERL and APACHE:httpd must be installed before you can install APA- CHE:modperl. In order to install all the supplied components, you should keep to the following sequence in order to make sure that the package dependencies are observed: - APACHE (Base package with common run-time) - PERL (Perl scripting language run-time) - APACHE:httpd (Secure Web Server) - APACHE:httpd-d (Online docs for APACHE:httpd) - APACHE:modperl (Scripting modules for APACHE:httpd) - APACHE:modprl-d (Online docs for APACHE:modperl) - APACHE:modphp (PHP scripting modules for APACHE:httpd) - APACHE:modprl-d (Online docs for APACHE:modphp) Observe the dependencies in reverse order when deinstalling: be- fore you can deinstall APACHE:httpd, the packages APACHE:httpd-d, APACHE:modperl, APACHE:modprl-d, APACHE:modphp and APACHE:modphp- - 5 - A d must be deinstalled. All packages are optional: however, if the function of a package is to be used and the package is to be installed, the prerequi- site packages must be installed first. 2.3 Additional software prerequisites * POSIX-BC 6.0/7.0 (version A39 or greater) * POSIX-SH 6.0/7.0 (installed with POSIX-INSTALLer) * BLSSERV as of V2.6 * openNet server as of V2.0 * The subsystem DIV must be started for the administration of "shared memory" in the POSIX. * The subsystem PRNGD for entropy creation must be started. * ORACLE 10g or greater is the prerequisite for the optional usage of the ORACLE interface. * SESAM-SQL V5.0 or greater is the prerequisite for the op- tional usage of the SESAM interface. 2.4 Changes in the POSIX installation procedure POSIX installation procedure Compared with earlier BS2000 installation packages, the following improvements on the installation procedure have been made: * The installation packages use the interaction with the user in order to make inquiries (to inquire configuration pa- rameters or yes/no confirmations) and to display progress messages during the installation. * If possible and if required, background processes (such as the Apache Web Server) are automatically started after a successful installation and stopped before deinstallation. * Each installation package checks during the installation as to whether the dependencies to the prerequisite packages have been met. Should dependencies not be met, the instal- lation is aborted with an error message. * Each installation package checks during installation as to whether there is enough space on the selected file system for the package to be installed. It aborts with a "not enough space" error message before the actual installation begins. * All configuration questions are asked at the beginning of the installation; the installation then runs as far as the end without inquiries (except for: %PLEASE ACKNOWLEDGE). * In BATCH installation mode, standard responses are used, and background processes, such as the Apache Web Server, are not automatically started. Example parameter files for installing and deinstalling all APACHE packages in BATCH mode are in the installation library of the base package. * If Apache Web Server add-on products (APACHE:modphp and APACHE:modperl) are installed, the installed module can be optionally added and activated, When deinstalling it is automatically deactivated and removed. * Deinstallations partially test whether the package to be deleted is a prerequisite for another package (e.g., the APACHE base package is a prerequisite for APACHE:httpd and PERL and if it is deleted, these packages no longer operate correctly). The deinstallation can be aborted on request without endangering the mutual consistency of the packages. - 6 - A Configuration files' upgrade handling The strategy to prevent losing configuration files modified by the user when upgrading to a new web server version is as fol- lows: * During the installation, configuration files are installed as original under another file name. With APACHE:httpd (Apache Web Server) these originals are in a subdirectory $IPATH/conf/original/... * After the installation, the originals are copied to their final position $IPATH/conf/... if there is no user-adapted configuration file already at that position. * At deinstallation, only the configuration files are removed which have not been modified in comparison to the original. All the changed copies remain at their position in $IPATH/conf/..., and are reused during reinstallation. * If you wish to delete the product completely or install anew without the old configuration files, you must manually delete (after Deinstallation of all of the components) the $IPATH directory structure (or delete specifically the files which you do not want to reuse). * A migration from an existing Apache 1.3 configuration to an Apache 2.2 configuration is not planned. The structure of the configuration files as well as the semantics of some configuration directives have changed considerably, and the interactive installation makes it fairly simple to success- fully start APACHE 2.2. 3 Port assignments of the web server ---------------------------------- The Apache web server assigns the following port numbers by de- fault: Port: Protocol: Explanation: 80/tcp http Hypertext Transfer Protocol 443/tcp https SSL/TLS secure http (These default values can of course be changed in the configura- tion). Depending on the security policy, you should first decide whether all the network connections to the web server should be generally permitted via the command /BCOPTION ADD-SERVER-PORTS=(80,443) (See also /SHOW-BCAM-SERVER-PORTS). Apache also makes connections to other computers on the following ports: Port: Protocol: Explanation: 53/udp|tcp dns Domain name Services 20+21/tcp ftp When using mod_proxy_ftp 80/tcp http When using mod_proxy_http 443/tcp https When using mod_proxy_connect 8009/tcp ajp13 Apache JServ Protocol 1.3 (when using a remote tomcat) - 7 - A As a functioning DNS name resolution for Apache is very impor- tant, a functioning DNS name server (known to BCAM or generally permitted via the command /BCOPTION ADD-REMOTE-SERVER-PORTS=(53)) should be named in the DNS resolver configuration file /etc/resolv.conf. 4 Installation ------------ 4.1 APACHE web server ID The Apache Web Server requires for its operation a separate user ID which should be configured before installing the package APACHE:httpd. It is used for security purposes, as the individual web server processes should have as few privileges as possible and be optimally separated from the other existing user IDs. This prevents the server machine from being open to attacks from the network when using CGI programs. Only the Apache manager process which controls load control (creation and termination of the server processes), has more rights under the SYSROOT-ID, but it never comes into contact with the requests coming from the net- work. The The default name of the web server ID is "APACHE" but you can specify any other name during the interactive installation. When installing in BATCH mode, if this ID does not exist at the time when installation begins, it is automatically created with suitable default values on the default pubset. This web server ID should have the following attributes: * The ADDRESS-SPACE-LIMIT for the ID (and also for SYSROOT) should be at least 96MB. (However, when using the SQL data- base interfaces to SESAM and ORACLE, see also the require- ments for the respective databases e.g. 512MB for ORACLE users) * The ACCOUNT of the web server ID or its default JOBCLASS should, if possible, permit the NO-CPU-LIMIT and START- IMMEDIATE privilege. * The required ACCOUNT of the web server ID must be set as POSIX default account: /MODIFY-USER-ATTRIBUTES - / USER-IDENTIFICATION=apache,- / ADDRESS-SPACE-LIMIT=96,- / ACCOUNT-ATTRIBUTES=- / *MODIFY(ACCOUNT=webserve,- / PRIVILEGE=(NO-CPU-LIMIT=*YES,- / START-IMMEDIATE=*YES- / ),- / POSIX=*YES) * The default JOBCLASS of the web server ID should permit as LIMIT at least as many tasks as the APACHE server may cre- ate for child and children's child (CGI) processes. * SYSROOT should also be allowed to use this JOBCLASS. If it is entered in /etc/default/APACHE22.httpd, the Apache moni- tor process (i.e. the SYSROOT web server task) starts with - 8 - A this JOBCLASS instead of the default job class. * The POSIX home directory must not be /home/gast (or the de- fault POSIX DIRECTORY; see /SHOW-POSIX-USER-DEFAULTS). As the ID is not designed as a standard log-in, you can se- lect, e.g. the $IPATH base directory /opt/apache22. * The numeric POSIX user ID must not be 0 or 100 (or the de- fault POSIX USER NUMBER; see /SHOW-POSIX-USER-DEFAULTS). It should have a numeric value which differs from all other POSIX user IDs if possible. * The numeric POSIX Group ID must not be 0 or 100 (or the de- fault POSIX GROUP NUMBER; see /SHOW-POSIX-USER-DEFAULTS). It should have a numeric value which, if possible, differs from all other POSIX Group IDs. It is recommended to put this value in the file /etc/group with a name, e.g. "httpd". * If ORACLE is installed, and access from the web server to the database should be possible (with mod_php5 or mod_perl), the ID must have the group called 'oracle' as its additional "POSIX supplementary group" (entry in /etc/group), see below. As it is not easy to determine a free POSIX user or group number using BS2000 commands, this can be done very easily (having in- stalled the base component APACHE) using the tool /opt/apache22/sbin/start-daemon. The tool option "-=80-" determines an unused POSIX user ID / group ID pair larger than or equal to 80 (where the user ID is the same as the group ID) which is not used by any other ID. Example for configuring the web server user ID: =========================================================== /EXECUTE-POSIX-CMD '/opt/apache22/sbin/start-daemon -=80-' 82 / REMARK "Please insert this POSIX user/group id " / REMARK "in the commands below:" /ADD-USER - / USER-IDENTIFICATION=apache,- / LOGON-PASS=X'A9AC6E22F0384E1D',- / ADDRESS-SPACE-LIMIT=96,- / ACCOUNT-ATTRIBUTES=*PAR(ACCOUNT=webserve,CPU-LIM=*MAX,- / PRIVILEGE=(NO-CPU-LIMIT=Y*,- / START-IMMEDIATE=*Y),- / POSIX=*YES),- / MAIL-ADDR='APACHE web server Daemon' /MOD-POSIX-USER-ATTR USER-ID=apache,- / USER-NUM=82,- / GROUP-NUM=82,- / COMMENT='APACHE web server Daemon',- / DIRECTORY='/opt/apache22',- / PROGRAM=*SHELL /EXECUTE-POSIX-CMD 'echo >>/etc/group httpd::82:' =========================================================== - 9 - A If the default pubset of the user id is different from the HOME pubset, the ADD-USER and MOD-POSIX-USER-ATTR commands must be is- sued a second time with ",PUBSET=XXXX" appended. 4.2 BS2000 job attributes In order to operate background processes (in Unix also known as "daemons") such as web servers, it is recommended to configure a dedicated job class which provides the required attributes (NO- TIME-LIMIT, START=IMMED, LIMIT=...). The job attributes can be modified further in the POSIX startup configuration file /etc/default/APACHE22.httpd: * The standard job name for the APACHE server tasks is JOB- NAME="APACHE22". This name can be changed here (to a valid BS2000 job name). * The preset JOB-CLASS is JOBCLASS="*STD", i.e. the default job class of the SYSROOT user. If a dedicated job class has been configured for background processes (and the SYSROOT and the APACHE IDs are allowed to use them), they can be specified here. * If the default value ACCOUNT="*STD" is retained, when starting the web server task the "DEFAULT-ACCOUNT-# FOR RE- MOTE-LOGIN" is used for SYSROOT. Alternatively, a special valid ACCOUNT can be specified which, for example, was con- figured for background processes and permits the START=IMMED attribute. * The START_APACHE_AT_POSIXSTART value decides whether the web server is to be automatically started or not at the next POSIX start. One of three values is allowed: o START_APACHE_AT_POSIXSTART="yes": starts APACHE with each POSIX start o START_APACHE_AT_POSIXSTART="no": No start, issues warning on console o START_APACHE_AT_POSIXSTART="never": No start, no message on console. This variable has the default value "no" in BATCH mode in- stallations, and "yes" in interactive installations. 4.3 Apache directory structure The main paths of the APACHE:httpd package: Path Function $IPATH/ Base directory of the Apache installation $IPATH/sbin/httpd Apache Web Server Executable /opt/bin/apache2ctl Wrapper script to start and stop the server $IPATH/conf/httpd.conf Main configuration file of the Apache web server $IPATH/conf/extra/httpd-*.conf Included configuration parts $IPATH/modules/ - 10 - A Directory with the loadable Apache modules $IPATH/lib/lib*.so Jointly used shared libraries $IPATH/conf/conf.d/*.load 3rd -party "LoadModule" parameter files $IPATH/conf/conf.d/*.conf 3rd party configuration files $IPATH/logs/ Directory of Apache log files (Symlink) -> /var/opt/APACHE22.httpd/logs/ $IPATH/htdocs/ Standard document root of the web server $IPATH/manual/ Directory tree for optional online documentation packages 4.4 POSIX installation in interactive mode The packages are installed to the POSIX file system in the se- quence of their above cross-dependencies with the POSIX in- staller, i.e. first of all the base package, then TOMCAT, PERL and/or APACHE:httpd, then the further add-on packages for APACHE:httpd. The calling user ID must have user ID 0 in POSIX in order to install directories and files (e.g. TSOS or SYSROOT). Example: ============================================================= BS2000 POSIX package installation IMON support ? : Y (y) mandatory for official package (n) private package (SINLIB...) name of product : APACHE package of product : HTTPD (optional for certain products) version of product : (format Vmm.n or mmn) correction state : (format also, optional) installation userid: (mandatory for no IMON support) The definition of an installation path is optional for this product. Please enter the full pathname of the wanted installation directory: /opt/apache22 install: DUE help: F1 terminate: F2 ============================================================= The installation's base directory (the default $IPATH being: "/opt/apache22") can be selected when installing the base package "APACHE". When installing the other APACHE packages (APACHE:httpd etc.) the same directory must be specified. However, retaining - 11 - A the standard value is recommended. At the beginning of an interactive installation (i.e. /START- POSIX-INSTALLATION without FILE= specification) of the packages APACHE:httpd and the module packages APACHE:modperl and APA- CHE:modphp, the POSIX-INSTALLER asks a number of configuration questions and then begins with the actual installation. (Until this point, you can abort the installation without any danger by entering 'q' or K2 without changing anything on your system.) Your answers are saved until the end of the installation and then used for configuration. The answers are, if possible, subjected to a simple validity check, and any obviously incorrect entries are prompted for correction. After installing the files in the POSIX file system and adapting the configuration files, the web server is started (optionally, see Prompt "AutoStartApache") in a SYSROOT /ENTER job. (Even if the installation was made under a TSOS-ID, the web server is started in a new task under SYSROOT in order to ensure secure op- erations under a non-TSOS-ID.) 4.5 POSIX installation in BATCH mode In order to simplify the installation, an installation in BATCH mode is partially supported. While in an interactive installation a configuration is made during the installation, this is not pos- sible in BATCH mode: the packages are installed with default con- figuration, but a subsequent configuration and server start must be done manually after the installation. To make BATCH installation easier, the base package contains a library element S//LIB.APACHE.022(PKGADD.APACHE.022,S) which can be used as parameter file for the POSIX-INSTALLER call. Copy it to a file, edit it and comment the components that you don't want to install by prefixing a '#'. You can then start the batch installation via a call such as: /START-POSIX-INSTALLATION INPUT-INTERFACE=- / *FILE(FILE-NAME=PKGADD.APACHE.022) As important information about problems can be displayed during the batch installation (low system limits, incorrect file permis- sions, non-configured IDs etc.), it is recommended to have the entire POSIX-INSTALLER output written to a file and then evaluate it. The standard answers to the questions during the installation can already be modified and pre-assigned before starting the batch installation in the following 'S' library elements: S//LIB.APACHE.022.HTTPD(response.APACHE-HTTPD.022,S): ServerName, Port, ServerAdmin etc. S//LIB.APACHE.022.MODPERL(response.APACHE-MODPERL.022,S): EnablePerlModule? RestartApache? S//LIB.APACHE.022.MODPHP(response.APACHE-MODPHP.022,S): EnablePHPModule? RestartApache? SINLIB.APACHE.022.MODPRL-D(response.APACHE-MODPERL-DOC.022,S): RestartApache? SINLIB.APACHE.022.MODPHP-D(response.APACHE-MODPHP-DOC.022,S): RestartApache? - 12 - A (Please note that the standard file permissions of the installa- tion libraries (SHARE=YES, ACCESS=READ) do not permit editing li- brary elements) Note: In POSIX version A39, the POSIX-INSTALLER has a File Descriptor Leak which in a Batch installation selecting all components leads to a dump or hangs. It is thus not recom- mended to BATCH-install all APACHE components jointly, but individually. 4.6 POSIX deinstallation The deinstallation must also be made under a user ID with POSIX User ID 0 (e.g. TSOS or SYSROOT) in order to stop the web server and remove directories and files. The interactive deinstallation is started by calling /START- POSIX-INSTALLATION, selecting "Delete Packages from POSIX" and marking the required product component; delete the packages in the reverse sequence of the installation. Analog to batch installation, the base package also has a library element S//LIB.APACHE.022(PKGRM.APACHE.022,S) as example parame- ter file for the batch deinstallation with the POSIX-INSTALLER. Note: If, for a product upgrade, the deinstallation and rein- stallation is automated via IMON, this occurs from the APACHE package viewpoint in batch mode, and that is why, with rein- stallation, the variable START_APACHE_AT_POSIXSTART="no" is set in the parameter file /etc/default/APACHE22.httpd. After the product upgrade, you must thus edit this file if neces- sary, set the value again to START_APACHE_AT_POSIXSTART="yes" and execute a web server start with # apache2ctl start or under BS2000: /START-APACHE 5 Operations ---------- 5.1 Start / stop the web server In normal Apache documentation, the use of the "apachectl" script is recommended to start, stop and restart the APACHE:httpd. This script can also be used with BS2000 Apache, but we recommend us- ing the /opt/bin/apache2ctl wrapper instead. The reasons are: * Start under SYSROOT-ID: Even if the caller is TSOS, the web server monitor process is started under SYSROOT. This ensures that no part of the web server ever has increased TSOS privileges. (The actual web server processes are run with even fewer privileges un- der the 'APACHE' ID). * Detach from current job attributes and from the terminal: the web server is started in a separate /ENTER job (its JOB-NAME and other attributes can be configured). It is - 13 - A thus detached from the terminal as well and can thus op- tionally already be started at the end of the installation. As the restart function of the "apachectl" script can also start the server (if none is running), the restarts should be executed via the /opt/bin/apache2ctl wrapper as well if the caller is not already logged in as SYSROOT: # apache2ctl graceful or under BS2000: /RESTART-APACHE *GRACEFUL 5.2 Configuration files of the Apache web server If you would like to adapt the configuration files of the web server, you should know which files are evaluated in which se- quence by Apache. The base directory of the installation (that you specified in the POSIX-INSTALLER) is known as $IPATH. The structure of the configuration files corresponds to the stan- dard Apache layout of the Apache Software Foundation, but is dif- ferent from that of many other Linux distributions. * The main configuration file is $IPATH/conf/httpd.conf * The list of the standard modules to be loaded is in $IPATH/conf/extra/httpd-modules.conf: you can bracket out unused Apache modules by placing an '#' in front of the af- fected line. * The delivery status has a number of rarely used modules bracketed in order to avoid causing unnecessary loads on the main memory and CPU. Should you require the appropriate functionality, simply remove the comment characters and re- start the web server. * Additional configuration files are read in (via explicit "Include" directives in the $IPATH/conf/httpd.conf) from the directory $IPATH/conf/extra/httpd-*.conf. * The load module directives of the optional add-on modules mod_php5 and mod_perl (and possible extensions of the user) are either bracketed or active in $IPATH/conf/conf.d/.load, depending on the specifica- tion during the installation. These configuration files are read in from the $IPATH/conf/httpd.conf having loaded the standard Apache modules with the directive "Include conf/conf.d/*.load". * The configuration directives of the optional add-on modules (and possible extensions of the user) are included by a di- rective "Include conf/conf.d/*.conf". After each change on the list of the modules to be loaded, you should call "apache2ctl graceful" in order to have the web server reread the modified configuration. 5.3 SSL/TLS operation The web server package installs a dummy certificate ("snakeoil certificate") which is valid until 2018. This certificate is only - 14 - A used to run a web server with SSL before an official certificate has been applied for from a Trust Center. Each attempt to access your server via SSL results of course in a browser warning on ac- count of the dummy certificate. (You should never permanently in- stall such a dummy certificate in your browser!) Under no circumstance should you operate a productive server with this certificate! The SSL configuration consists of the following files below the Apache configuration directory /opt/apache22/conf/: path | function -------------------------+--------------------------------------- extra/httpd-modules.conf | Determines whether SSL module is loaded extra/httpd-ssl.conf | Configures SSL module if loaded ssl.crt/server.crt | The SSL certificate for the web server ssl.key/server.key | Private key for SSL certificate ssl.csr/server.csr | SSL Certificate Signing Request ssl.crl/server.crl | (Optional) certificate revocation list In order to apply for a correct certificate, you can create a CSR (certificate signing request), using the data of your machine, in the so-called PEM format which you transfer to the Trust Center when applying for an SSL certificate. A simple script (mkcert.sh) is supplied which helps you to create a CSR and creates a tempo- rary snakeoil-signed dummy certificate. Replacing the "snakeoil" certificate Execute the following steps when you want to operate your server with an official SSL certificate (issued by a Certificate Author- ity (="CA") which your standard browsers trust): * Invoke the "mkcert.sh" utility in order to create a CSR (certificate signing request). The inquired values appear in the CSR and thus in your later official certificate. When the prompt "Common name (eg, FQDN)" appears, enter your correct DNS host name (this value is compared against the host name in the https:// request by the client when making the SSL connection): ======================================================== # cd /opt/apache22/support/ # ./mkcert.sh SSL Certificate Generation Utility (mkcert.sh) Copyright (c) 1998-2000 Ralf S. Engelschall, All Rights Re- served. ... STEP 2: Generating X.509 certificate signing request You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distin- guished name or a DN. There are quite a few fields but you can leave some blank. For some fields there will be a default value. If you enter '.', the field will be left blank. ----- 1. Country name (2 letter code) [XY]: DE 2. State or Province name (full name) [Snake Desert]: Bavaria 3. Locality name (eg, city) [Snake Town]: - 15 - A Munich 4. Organization name (eg, company) [Snake Oil,Ltd]: Intranet 5. Organization unit name (eg, section)[web server team]: 6. Common name (eg, FQDN) [www.snakeoil.dom]: hostname.dom.ain 7. E-Mail address (eg, name@FQDN) [www@snakeoil.dom]: WebMaster@hostname.dom.ain 8. Certificate Validity (days) [365]: 730 ----- ... Are you satisfied with the entered data, and do you want to install the generated private key and certificate as your new server key and certificate? [y/n;N]: y Certificate: /opt/apache22/conf/ssl.crt/server.crt Private Key: /opt/apache22/conf/ssl.key/server.key Signing Req: /opt/apache22/conf/ssl.csr/server.csr ======================================================== * You now have a certificate application /opt/apache22/conf/ssl.csr/server.csr as well as a private key /opt/apache22/conf/ssl.key/server.key and a temporary certificate /opt/apache22/conf/ssl.crt/server.crt (already issued on your machine, however from the non-trustworthy "Snakeoil-CA"). Stop the web server completely and start it again so that the new certificate is activated: ======================================================== # apache2ctl stop # apache2ctl start ======================================================== * Apply for an SSL certificate in PEM format by using the certificate application /opt/apache22/conf/ssl.csr/server.csr. * If you have received the certificate issued, simply replace the temporary certificate /opt/apache22/conf/ssl.crt/server.crt via a copy of your official PEM certificate and start the server anew so that the new certificate is activated: ======================================================== # apache2ctl stop # apache2ctl start ======================================================== * When replacing the certificate, do not use the "graceful" or "restart" functions, but stop the web server completely and start it anew as shown in the example above. Deactivate SSL We do not recommend deactivating the SSL interface as an en- crypted SSL communication increases security and prevents trans- ferred data from being tapped during transport and being misused. If you nevertheless want to configure a pure HTTP server without SSL, simply carry out the following steps: * Look in the configuration file "conf/extra/httpd- modules.conf" for the line: LoadModule ssl_module modules/mod_ssl.so - 16 - A and place a '#' character in front of the line. * Restart the web server with # apache2ctl graceful or under BS2000: /RESTART-APACHE MODE=*GRACEFUL the server is thus restarted without SSL support. 6 SDF support for APACHE:httpd ---------------------------- The delivery unit APACHE also contains a SDF syntax file which is used to execute the start, restart, stop and status inquiry com- mands directly from TSOS or SYSROOT from the BS2000-ID as SDF commands. The implementation is contained in the procedure li- brary SYSSPR.APACHE.022 and the SDF syntax file SYSSDF.APACHE.022. List of SDF commands: =========================================================== /START-APACHE Requires POSIX-UserId 0 Domain: NETWORK-MANAGEMENT The Apache web server is started as SYSROOT /ENTER job. If a web server is already running, an error is reported. =========================================================== - 17 - A /STOP-APACHE [MODE=*FORCED|*GRACEFUL] Requires POSIX-UserId 0 Optional argument: (Default: MODE=*FORCED) *FORCED A running web server is stopped forcefully (i.e. aborts all running transfers). If no web server is running, an error is reported. *GRACEFUL A running web server is stopped gracefully (i.e. all running transfers still continue within the configured Grace- fulShutdownTimeout time and only then is the Apache monitor process stopped). If no web server is running, an error is reported. =========================================================== /RESTART-APACHE [MODE=*FORCED|*GRACEFUL] Requires POSIX-UserId 0 Optional argument: (Default: MODE=*FORCED) *FORCED A running web server is restarted forcefully (i.e. aborts running transfers). If no web server is running, a /START-APACHE is executed. *GRACEFUL A running web server is restarted gracefully (i.e. al- ready running transfers still continue). If no web server is running, a /START-APACHE is executed. =========================================================== /SHOW-APACHE-STATUS [INFORMATION=*STD|*ALL] Requires no privilege. Optional argument: (Default=*STD) *STD The Apache status is displayed (overview of network and CPU consumption and currently running web server processes) *ALL The entire Apache status is displayed (additional details for the individual processes and information about the SSL session cache). The command /SHOW-APACHE-STATUS assumes that the Apache web server has been configured so that an access to the mod_status output is possible under http://localhost/server-info. =========================================================== /EXECUTE-APACHE-CMD PARAMETERS= Alias: /APACHE2CTL Requires POSIX-UserId 0 Argument: (No Default) 'c-string' The POSIX command apache2ctl is invoked with the contents of the character string as its argument. This en- ables special forms of the command such as /APACHE2CTL PAR='-f conf/httpd-VHOST2.conf' =========================================================== Prerequisite for using the /SHOW-APACHE-STATUS command is the configuration of the Apache module mod_status by: * removing the comment character in front of #Include conf/extra/httpd-info.conf in the configuration file $IPATH/conf/httpd.conf as well as * editing the configuration file $IPATH/conf/extra/httpd- info.conf (you can define the allowed host names, IP ad- - 18 - A dresses or domain names to access the web server status page). The command /SHOW-APACHE-STATUS accesses the web server under the name "localhost", i.e. the two lines which regulate access for mod_info and mod_status should be changed to: Allow from localhost 127.0.0.1 ::1 It is not recommended to permit access for all IP addresses without any restrictions. * If the web server is not listening on the standard port 80, the port number in the line STATUSURL="http://localhost:80/server-status" in the file $IPATH/sbin/apachectl must be modified to re- flect the actual port number. * If more details about the status of the web server are de- sired, you can add the "ExtendedStatus on" directive to the configuration file $IPATH/conf/extra/httpd-info.conf. With INF=*STD display, this shows additional network and CPU load details; with *ALL display, it also shows the re- quests' URLs. * After adapting the configuration, restart the web server with # apache2ctl graceful or under BS2000 with /RESTART-APACHE MODE=*GRACEFUL in order for the changes to become effective. Example: ============================================================== /SHOW-APACHE-STATUS INF=*STD Apache Server Status for localhost Server version: Apache/2.2.8 (BS2000) mod_ssl/2.2.8 OpenSSL/0.9.8g DAV/2 PHP/5.2.5 Server Built: Mar 25 2008 17:28:26 _________________________________________________________________ Current Time: Thursday, 04-Apr-2008 16:45:17 MST Restart Time: Thursday, 04-Apr-2008 07:42:52 MST Parent Server Generation: 1 Server uptime: 9 hours 2 minutes 25 seconds 6 requests currently being processed, 8 idle workers __WR_D__W_K__R.................................................. ................................................................ ................................................................ ................................................................ Scoreboard Key: "_" Waiting for Connection, "S" Starting up, "R" Reading Re- quest, "W" Sending Reply, "K" Keepalive (read), "D" DNS Lookup, "C" Closing connection, "L" Logging, "G" Gracefully finishing, "I" Idle cleanup of worker, "." Open slot with no current proc- ess - 19 - A ============================================================== 7 Additional tools ---------------- Some Open Source utilities are installed together with the APACHE base package which can help you when configuring and operating the web server. * /opt/apache22/support/iconv: (See http://www.gnu.org/software/libiconv/) The GNU iconv utility is used to convert text documents be- tween numerous different source and target character sets. It is mainly useful for converting between an ASCII-based character set (ISO_8859-*, UTF*) and an EBCDIC-based char- acter set (OSD_EBCDIC_DF*, but also national versions). The file is also linked as /opt/bin/giconv. The list of the supported character set names and aliases is displayed when calling "/opt/bin/giconv -l". * /opt/apache22/support/openssl: (See http://www.openssl.org/) This tool can be used to display SSL certificate details. It is also required by the "mkcert.sh" script to create SSL certificates. The file is also linked as /opt/bin/openssl. * /opt/apache22/support/sqlite3: (See http://www.sqlite.org/) This command line utility is used to create, edit and dis- play SQLite3 databases, e.g. to use SQLite3-based user au- thentication (see HowTo further on). The file is also linked as /opt/bin/sqlite3. * /opt/apache22/support/nc: (netcat) (See http://nmap-ncat.sf.net/) This tool is used internally used when the "apache2ctl status" function is used to display the web server status and no "lynx" utility was found in the search path ("lynx" is a text mode browser and can issue HTTP requests and con- vert the HTML response to normal text format, but it is not available as standard in OSD/POSIX). The following Open Source utility is installed together with the web server component APACHE:httpd: - 20 - A * /opt/apache22/sbin/cronolog: (See http://cronolog.org/) An improved logfile rotation utility used to automatically distribute the web server log file(s) to periodically changing output files, without the need for a web server restart. For example, an apache directive TransferLog "|/opt/apache22/sbin/cronolog logs/%Y/%m/%d/access_log" can distribute the output to an implicitly created daily directory hierarchy, e.g., on 31st December 2008: logs/2008/12/31/access_log and after midnight: logs/2009/01/01/access_log 8 EBCDIC character set support ---------------------------- The APACHE web server in BS2000 assumes by default that HTML documents are encoded in the OSD_EBCDIC_DF04_1 character set, and converts them internally to ISO_8859-1 for the browser. This con- figuration can be found in the configuration file /opt/apache22/conf/httpd.conf: ================================================== ... AddDefaultCharset ISO-8859-1 CharsetSourceEnc OSD_EBCDIC_DF04-1 CharsetDefault ISO-8859-1 CharsetOptions DebugLevel=0 ImplicitAdd ... ================================================== This default can be adapted in the configuration when documents in other codes exist, or if they are to be converted to other character sets (in particular UTF-8 or ISO_8859-15) for browsers. If, for example, all HTML documents in the directory /opt/apache22/htdocs/utfdocs/ are encoded in the character set OSD_EBCDIC_DF04_15 (this character set contains among others the Euro character), and should be supplied to the browser as UTF-8 documents, the following configuration extension can be used: ================================================== CharSetOptions ImplicitAdd DebugLevel=0 CharsetSourceEnc OSD_EBCDIC_DF04_15 CharsetDefault UTF-8 ================================================== Such a configuration can be created under a name such as /opt/apache22/conf/conf.d/utfdocs.conf and becomes effective by restarting the web server with "/opt/bin/apache2ctl graceful". - 21 - A By the way: the character set names in the directive AddDe- faultCharset, CharsetSourceEnc and CharsetDefault are evaluated by the underlying GNU libiconv library and utility. You can dis- play the list of accepted character set names by invoking the GNU iconv utility ("/opt/bin/giconv -l") supplied with APACHE. 8.1 What must be done with incorrectly converted files? However, if you have copied from an ASCII machine a set of UTF documents in text mode to the POSIX file system, then this is an invalid conversion: due to the "text mode", you implicitly ap- plied a conversion ISO_8859-1 => OSD_EBCDIC_DF04_1, but the mate- rial was not really encoded in the character code ISO_8859-1, but in UTF-8. This incorrect conversion should be better corrected via renewed binary copying of the UTF-8 files and assigning at- tributes as "CharsetSourceEnc UTF-8". Or you can use a little "white lie" and tell APACHE that the files exist in the character set OSD_EBCDIC_DF04_1 and are to be supplied as ISO_8859-1 to the browser. Then override for the browser the ISO_8859-1 character set indicator with an explicit type with UTF-8 character set: ================================================== CharSetOptions ImplicitAdd DebugLevel=0 CharsetSourceEnc OSD_EBCDIC_DF04_1 CharsetDefault ISO_8859-1 # "White lie": the files are really UTF-8: ForceType text/html;charset=UTF-8 ================================================== 9 HowTo's ------- 9.1 How to use disk cache The new disk_cache module in Apache2 can be used both as cache for the proxy module (sensible with forward and reverse proxy cases) as well as a generic access cache which, for example, saves dynamic resources in a disk cache thus reducing the web server load. The following example shows how the dynamic output of scripts from a specific directory (and if "cacheable") can be cached for a specific time on the server. If the same URL is re- quested again within the expiry time, it does not have to be cal- culated again, but can be fetched from the cache. As configura- tion you could save the following directives as /opt/apache22/conf/conf.d/mod_cache.conf: ================================================== # Example /opt/apache22/conf/conf.d/mod_cache.conf # NOTE: the directory /var/opt/APACHE22.httpd/cache must # be created and chown'ed to the APACHE user. # The cache is filled but never cleaned by APACHE! # Use the htcacheclean utility to clean it regularly. CacheEnable disk /php-scripts/ - 22 - A CacheRoot /var/opt/APACHE22.httpd/cache CacheDirLevels 3 CacheDirLength 3 CacheMaxFileSize 1000000 CacheDefaultExpire 600 CacheMaxExpire 7200 ExpiresDefault "now plus 2 hours" # The cache module should be used with care and can be # used to circumvent Allow and Deny directives. # You should not enable caching for any content to which # you wish to limit access by client host name, # address or environment variable. ================================================== In addition, you must activate the "LoadModule" directives for the two modules cache_module and disk_cache_module in the con- figuration file /opt/apache22/conf/extra/httpd-modules.conf by removing the comment character, and then restart the web server via "/opt/bin/apache2ctl graceful". In contrast to Apache V1.3 it is not the web server that handles the periodical clean up work in the cache directory but a dedi- cated htcacheclean utility (its call syntax is documented in the description http://yourhost/manual/programs/htcacheclean.html) which you must execute periodically if you wish to use the disk cache. 9.2 How to handle Apache authentication with an SQLite data- base In addition to the authentication from a text file (AuthUserFile Directive) and from a Berkeley-DB, Apache2 also offers user au- thentication against an SQL database. The advantage is the simple creation and maintenance of such an SQLite3-based (see www.sqlite.org) database, e.g. with PHP scripts. An example for configuring access protection based on user name and password is shown below. The SQL database used for authentication can be cre- ated and updated using PHP's pdo_sqlite interface. ================================================== #Use the SQLite driver DBDriver sqlite3 #Connection string: database name and login credentials DBDParams "/opt/apache22/conf/user.passwd.sqlite" #Authentication Section AuthName "Protected Area" AuthType Basic AuthBasicProvider dbd file AuthType Digest AuthDigestProvider dbd file Require valid-user #SQL query to verify a user # The AuthDBDUserPWQuery specifies an SQL query # to look up a password for a specified user. The - 23 - A # query must take a single string (typically an SQL # varchar) argument (username), and must return # a single value (encrypted password). # Note: no single quotes are used around %s! AuthDBDUserPWQuery \ "SELECT password FROM basic_authn WHERE username = %s" # The AuthDBDUserRealmQuery specifies an SQL query # to look up a password for a specified user and # realm. The query must take two string (typically # SQL varchar) arguments (username and realm) and # must return a single value (encrypted password). AuthDBDUserRealmQuery "SELECT password FROM digest_authn \ WHERE username = %s AND realm = %s" ================================================== As a result of the following SQL code, which can be executed us- ing the sqlite3 command line utility, two users can be entered as example: one for "Basic" authentication, the other for "Digest" authentication: ================================================== # Example code to fill the SQLite database: BEGIN TRANSACTION; CREATE TABLE basic_authn ( username varchar(32) NOT NULL, password varchar(32) NOT NULL, description varchar(64) ); INSERT INTO "basic_authn" VALUES('sqlite3','cHUkyKx8z6QP.', 'Basic Authentication user'); CREATE TABLE digest_authn ( username varchar(32) NOT NULL, password varchar(32) NOT NULL, realm varchar(32), description varchar(64) ); INSERT INTO "digest_authn" VALUES('sqlite3', '415388677d084d30e591291feed51e61', 'Protected Area', 'Digest Authentication user'); COMMIT; ================================================== The encrypted password for basic authentication can be created using the htpasswd utility. 9.3 How to use the forward proxy Like Apache 1.3, Apache2 offers proxy functionality. In Apache2 it is even more flexible in usage and configuration. Because of the danger resulting from "open proxies" in the Internet, the proxy functionality is however no longer contained in the stan- dard configuration: whoever wants to set up a proxy should not do this by mistake, but taking all the risks into consideration. The proxy module in Apache2 no longer automatically handles the cache functionality as it did in Apache 1.3, but the functional- ity is still available in the mod_disk_cache module and must be - 24 - A configured separately. In order to use the BS2000 Apache as proxy forwarder e.g. for Internet resources, you can create a configuration similar to the following, e.g. as /opt/apache22/conf/conf.d/mod_proxy.conf: ================================================== # Warning # Do not enable proxying with ProxyRequests until # you have secured your server. Open proxy servers # are dangerous both to your network and to # the Internet at large. ProxyRequests On ProxyVia Full Order deny,allow Deny from all Allow from .my.dom.ain AuthType Digest AuthName HTTPProxy AuthDigestProvider file AuthUserFile "/opt/apache22/user.passwd" Require valid-user # You can use the htdigest program to create # the password database: # htdigest -c "/opt/apache22/user.passwd" Proxy hugo # Use Company Firewall Proxy if not directly connected # to the internet: ProxyRemoteMatch .* http://proxy.my.dom.ain:3128 ProxyTimeout 300 AllowCONNECT 443 563 ProxyBlock .double-advertising.net ProxyDomain .my.dom.ain # Use the additional service of the mod_cache module # to set up a caching proxy. CacheEnable disk http:// # For garbage collection, start htcacheclean # periodically or as daemon CacheRoot /var/opt/APACHE22.httpd/proxy CacheDirLevels 3 CacheDirLength 3 CacheDefaultExpire 600 CacheMaxExpire 7200 ExpiresDefault "now plus 2 hours" ================================================== - 25 - A 9.4 How to use a reverse proxy You can use the Reverse proxy functionality, for example, to al- low access to intranet servers hidden behind the mainframe via the mainframe server's web address. # ======================================================= # Note # It is not necessary to enable proxying with "ProxyRequests on" # if you only want to use the ProxyPass directives! ProxyPass /phpdoc http://docserv.my.dom-ain/~docs/phpdoc ProxyPassReverse /phpdoc http://docserv.my.dom-ain/~docs/phpdoc # If the Host: header should be passed to the backend server: #ProxyPreserveHost On # ======================================================= 10 PHP notes ---------- 10.1 PHP directory structure The main paths of the APACHE:modphp package: path | function ------------------------------+--------------------------------- $IPATH/php/ | PHP base directory $IPATH/modules/libphp5.so | The Apache-PHP module /opt/apache22/php/etc/php.ini | Default-PHP config file | (compiled-in path) $IPATH/php/bin/php | "php" command line utility $IPATH/conf/conf.d/php5.load | "LoadModule" parameter file for | Apache PHP module $IPATH/conf/conf.d/php5.conf | Apache configuration for PHP $IPATH/php/lib/php/extensions/| no-debug-non-zts-20060613/*.so| Optional loadable PHP modules 10.2 The PHP configuration file php.ini The compiled-in default path for PHP configuration file is "/opt/apache22/php/etc/php.ini". In order to override this value, the php command line utility offers an option "-c " to specify an alternative configuration file and the PHP module per- mits the specification of a directive "PHPIniDir ". If you wish to use different configuration files for the PHP mod- ule and the php command line utility, remember that the command line utility looks for a php.ini in its execution directory first (i.e., $IPATH/php/bin/php.ini) and also offers an option "-c " for specifying an alternative configuration file; the PHP module does not. A number of optional function groups is available in the form of separately loadable extensions and can be activated or deacti- vated in the php.ini by adding or removing a semi-colon in the lines extension = (at the end of the file). In the delivery state, the SESAM and ORACLE database modules are deactivated (as they depend on the installation and configuration of the respective databases), all other PHP extensions are acti- vated. - 26 - A 10.3 EBCDIC-/ASCII dependencies in PHP functions Some of the PHP functions operate on EBCDIC strings, others on binary data, such as image files in GIF, PNG or JPEG format which are stored bit-identical in the same way as on an ASCII machine. The essential differences are summarized below: * the standard EBCDIC character set in the POSIX universe is always OSD_EBCDIC_DF04_1: if a file is transferred in text mode via FTP, TELNET or remote copy (rcp) between an ASCII machine and OSD/POSIX, an implicit conversion OSD_EBCDIC_DF04_1 <-> ISO_8859-1 is always applied. This should be considered when transferring files encoded in a different character (it is sometimes better to transfer the file in binary mode and perform an explicit conversion us- ing the GNU iconv utility afterwards, see below). * Multibyte support and support for Japanese character sets are not supported in OSD/POSIX's PHP version. * iconv() operations always operate on the specified charac- ter set. The iconv implementation normally available in POSIX is not used in APACHE as it only supports a few con- versions; instead APACHE and PHP use the GNU libiconv li- brary. It knows the following BS2000 character set names: o OSD_EBCDIC_DF03_IRV aka. EDF03 aka. EDF03IRV 7-bit ASCII equivalent EBCDIC standard character set o OSD_EBCDIC_DF04_1 aka. EDF04-1 aka. EDF04 "Latin1" equivalent EBCDIC; POSIX standard character set o OSD_EBCDIC_DF04_15 aka. EDF04-15 aka. EDF04F "Latin9" equivalent EBCDIC character set o EDF03-DE aka. EDF03DE National 7-bit ASCII equivalent German o EDF03-DA,-EN,-IT,-FR,-SV aka. EDF03DA,EN,IT,FR,SV National 7-bit ASCII equivalent Denmark, England, It- aly, France, Sweden o EBCDIC.DF.04-DRV aka. EDF04DRV "Latin1" equivalent alternative: German EDF03DE ex- tension for missing characters from ISO_8859-1 (but not POSIX standard character set!) * The first three of these character sets are also registered with the IANA (with the first named name). * In addition to the named character sets the GNU libiconv library knows the normal ISO character set names and most of the numerous additional standardized character sets. The list of the character set names can be displayed by calling the GNU iconv utility supplied with APACHE: "/opt/bin/giconv -l" displays the available character set names. (The same character set names are also used for the configuration of conversions in the Apache web server.) * If you want to convert in PHP an EBCDIC text file to UTF-8, the source character set must be specified as OSD_EBCDIC_DF04_1 or OSD_EBCDIC_DF04_15 (and not as ISO- 8859-1 or ISO-8859-15). * iconv_mime_decode_headers() and iconv_mime_decode() expect the input MIME headers in ASCII format, any character set name as EBCDIC string and returns an array with EBCDIC strings on success. * iconv_mime_encode($fieldname,$fieldval[,$prefs_array]) ex- pects the field name as EBCDIC-String, the field value in the character set as specified in the $prefs_array['input- charset'] (or as default ISO_8859-1), and returns a string - 27 - A in the character set specified in the $prefs_array['output- charset'] (or as default ISO_8859-1). * image*() operations always operate on binary data. * uuencode() or uudecode() and base64_encode() or base64_decode() convert ASCII binary data to EBCDIC uuen- code text and vice versa. * range() operations on strings are processed as in ASCII: the range ("a","z") results in the array of (only) lower case letters, not all characters with code values between X'81' and X'A9'. * scanf(): character areas in scanf(), about: scanf("%[a-z]", ...) behave like in ASCII (in this example only lower case letters). * trim():character areas in trim($var,"a..z") works like on ASCII machines (in this example only lower case letters). * stripcslashes(): octal and hex constants are regarded as (EBCDIC converted) ASCII literals and processed accordingly (stripcslashes('{\133\x40}') results in => "{[@}" and not "{$ }") 10.4 Time zone specifications The UNIX SystemV Rel 4 upon which OSD/POSIX is based uses time zone specifications different from the time zone database in PHP. For example, in OSD/POSIX the following environment variable must be set for the time zone in Germany (see /etc/TIMEZONE): TZ=MEZ-1MSZ-2,M3.5.0/02:00,M10.5.0/03.00 while in PHP it is: ini_set("date.timezone","Europe/Berlin"); (analog in php.ini). Depending on the date function used, it can be necessary to use both methods in order to set the correct time zone. 11 Oracle notes ------------- The PHP Interpreter and the PHP module (both from APACHE:modphp) support the Oracle interface from ORACLE 10g(BS2000). In order to use them, the following configuration changes must be made: * Assume $ORAUID to be the ID under which the ORACLE software was installed in BS2000 * This ID must be used to install ORACLE in POSIX (call the procedure $ORAUID.INSTALL.P.POSIX as user $ORAUID). The ORACLE_HOME directory is inquired during the installation. * - 28 - A The file $ORAUID.APAC.P.ORAENV must be configured for the APACHE web server ID. An ORAENV for Apache is manually cre- ated under the $ORAUID ID after the POSIX installation, by executing the following steps (the SID APAC is only an ex- ample): - /COPY DEMO.P.ORAENV, APAC.P.ORAENV - edit APAC.P.ORAENV in an editor - modify all character strings "DEMO" to read "APAC" - modify parameter "* CLN_BASE=37M" to "CLN_BASE=200M" - add the parameter TNS_ADMIN: TNS_ADMIN=&ORACLE_HOME./network/admin - if a SIGINT signal should not result in a program termi- nation (a termination is only sensible in the PHP command line utility), the parameter BREAK_HANDLING=OFF must also be set. - write back the changes - set the file attributes ACCESS=READ and USER-ACCESS=ALL- USERS. * The APACHE web server-ID must have the POSIX group 'oracle' as additional "POSIX supplementary group" (entry in the fourth column of the 'oracle'-line in /etc/group) in order to be able to access the ORACLE Shared Library. * In the directory /opt/apache22/lib a symbolic Link must be configured to the actual path of the libclntsh.so shared library under $ORACLE_HOME so that the PHP modules oci8 and pdo_oci find the ORACLE library: ============================================== # cd /opt/apache22/lib # rm -f libclntsh.so* # ln -s $ORACLE_HOME/lib/libclntsh.so.* . # ln -s libclntsh.so.* libclntsh.so ============================================== * The specifications from the ORAENV-file for the PHP OCI8 module to find the database must be added to the environ- ment file $IPATH/sbin/envvars for the Apache web server in the form of environment variables (commented example lines are already there): ORACLE_HOME='/home/orac1020/oracle/product/10g'; ORACLE_BS2_ORAENV='$ORAUID.APAC.P.ORAENV'; LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$ORACLE_HOME/lib"; export ORACLE_HOME ORACLE_BS2_ORAENV LD_LIBRARY_PATH (The value of ORACLE_HOME= is in the BS2000 file $ORAUID.DEMO.P.ORAENV; see the POSIX file $ORA- CLE_HOME/.profile.oracle which is created during the POSIX installation and which contains the environment variables for Oracle under POSIX). * The file $ORACLE_HOME/network/admin/tnsnames.ora must be created and made readable for the web server ID; the user must provide the address parameter for Oracle Net. (The Oracle connection in PHP should only talk via TCP/IP with once instance; the IPC protocol cannot be used under POSIX.) * - 29 - A In the PHP configuration file /opt/apache22/php/etc/php.ini the comment character must be removed from the lines which load the respective OCI interface to load the OCI functions on web server start: extension = oci8.so extension = pdo.so extension = pdo_oci.so Alternatively, the call dl('oci8.so'); or the two calls dl('pdo.so'); and dl('pdo_oci.so'); can be used in php scripts in order to load these functions only as required. * When using the Oracle interface on a SPARC system, the sub- system CRTEC must be stopped in order to avoid a conflict between the SPARC and the /390 runtimes. Two different PHP/Oracle interfaces exist in PHP: the direct OCI8 functions ("oci8") and the abstracted functions available on top of the PDO database abstraction layer ("pdo_oci"). For more in- formation about this topic, see the PHP documentation in the package: APACHE:modphp-d or under http://www.php.net/ref.oci8 or http://www.php.net/pdo-oci 12 SESAM notes ------------ The PHP Interpreter and the PHP module (both from APACHE:modphp) support the SESAM interface from SESAM V5.0(BS2000). In order to use it, the following configuration changes must be made: * The specifications for the PHP Sesam module to find the da- tabase and the database handler must be entered in the file $IPATH/php/etc/php.ini: [Sesam] sesam.msgfile = "$.SYSMES.SESAM-SQL.050" sesam.sesamlib = "$.SYSLNK.SESAM-SQL.050" sesam.configuration = "$SESAM.CONF.AW" sesam.national_charset = "OSD_EBCDIC_DF04_15" magic_quotes_sybase = True The option "magic_quotes_sybase = True" is used for the correct handling of single quotes when processing form data for SQL commands. * In the PHP configuration file /opt/apache22/php/etc/php.ini, the comment character must be removed from the line which loads the SESAM interface if the SESAM functions are to be loaded on web server start: extension = sesam.so Alternatively, the call dl('sesam.so'); can be used in php scripts in order to load these functions only as required. However, this is not recommended due to the SESAM initiali- zation overhead per call. * When using the SESAM interface on a SPARC system, the sub- - 30 - A system CRTEC must be ended in order to avoid a conflict be- tween the SPARC and the /390 runtimes. 13 SQLITE notes ------------- Both APACHE and PHP can use SQLITE3 databases. The web server can, for example, load authentication information from either a clear text file like in APACHE V1.3, or from Berkeley DB files, or from SQL files in SQLITE3 format. The PHP module supports both the SQLITE2 and the SQLITE3 inter- faces, but with a different php language interface. While the SQLITE2 functions can be addressed both in a database-specific manner: $db = sqlite_open('/path/to/sqlite2dbfile', 0666, $sqliteerror); as well as via the PDO database abstraction layer, the SQLITE3 functions can only be addressed via the modern PDO database ab- straction layer: $dbh = new PDO('sqlite:/path/to/sqlite3dbfile', $user, $pass); More about this topic is found in the PHP documentation in the package: APACHE:modphp-d or under http://www.php.net/ 14 Restrictions ------------- * At the end of the PHP module installation, the automatic activation and restart of the web server does not always succeed. If required, please issue the command (in BS2000): /RESTART-APACHE *GRACEFUL or (under POSIX): # apache2ctl graceful manually after completion of the APACHE:modphp installation in order to activate the module for good. * Problems can occur on a SPARC machine when loading Shared Libraries, possibly mentioning "incompatible" symbols. In most cases it is enough to temporarily unload the subsystem *1 CRTEC and start the web server (or the PERL utilities) *1 anew. Alternatively, the optional REP-corrections A0480174 and A0566079-001 can be used to fix the problem. *1 This restriction doesn't exist anymore for the usage of *1 the PHP connection to an Oracle database. 15 Literature ----------- 15.1 Online documentation The online-documentation is available in the form of independ- ently installable documentation packages. They can be installed or deinstalled as required. The documentation is activated by a web server restart which can be (optionally) executed automati- - 31 - A cally in the post-install phase of the respective package. After the installation, the documentation packages can be ad- dressed under the following URLs: Component: URL: APACHE:httpd-d (documentation of Apache web server directives): http://servername/manual/ APACHE:modperl-d (documentation of the mod_perl module): http://servername/manual/mod/mod_perl/ APACHE:httpd-d (documentation the PHP5 script language): http://servername/manual/mod/mod_php5/ Furthermore, see the documentation pages of the respective Open- Source web sites at: * http://httpd.apache.org/docs/2.2/, * http://www.php.net/ and * http://perl.apache.org/docs/ 15.2 Apache Essentials: Install, Configure, Maintain By Darren James Harkness (Author) Paperback: 167 pages Publisher: friends of ED; Corr. 2nd printing edition (May, 2004) Language: English ISBN-10: 1590593553 ISBN-13: 978-1590593554 15.3 mod_perl2 User's Guide Book by Stas Bekmand Jim Brandt. Published by OnyxNeon in August 2007. Price: $34.95 (50% of this book's proceeds go to The Perl Foun- dation.) Language: English Date: August 2007 ISBN-10: 0-9779201-1-9 ISBN-13: 978-0-9779201-1-2 Companion Web Site at http://modperl2book.org/ 15.4 PHP Cookbook (Paperback) By Adam Trachtenberg (Author), David Sklar (Author) Paperback: 810 pages Publisher: O'Reilly Media, Inc.; 2 edition (Aug., 2006) Language: English ISBN-10: 0596101015 ISBN-13: 978-0596101015 15.5 POSIX (BS2000/OSD) - fundamentals for users and system ad- ministrator User manual Target group - 32 - A BS2000 system administrator, POSIX administrator, BS2000 user, UNIX workstation user Contents - Introducing and working with POSIX - BS2000 software products in the POSIX environment - Install POSIX - Administer POSIX control and filesystems - Administer POSIX users - BS2000 commands for POSIX - 33 -