xref: /PHP-5.4/sapi/nsapi/nsapi-readme.txt (revision 3cfbbc06)
1Configuration of your Netscape/iPlanet/Sun Webserver for PHP5
2-----------------------------------------------------------------
3
4These instructions are targetted at Netscape Enterprise Web Server and
5SUN/Netscape Alliance iPlanet Web Server and the new Sun Java System Webserver.
6On other web servers your milage may vary.
7
8Firstly you may need to add some paths to the LD_LIBRARY_PATH
9environment for Netscape to find all the shared libs. This is best done
10in the start script for your Netscape server.  Windows users can
11probably skip this step. The start script is located in:
12
13    <path-to-netscape-server>/https-servername/start
14
15
16Netscape/iPlanet/Sun config files are located in:
17
18    <path-to-server>/https-servername/config
19
20
21Add the following line to mime.types (you can do that by the administration server):
22
23    type=magnus-internal/x-httpd-php	exts=php
24
25
26Place the following two lines after mime.types init in
27<path-to-server>/https-servername/config/obj.conf (for servers < 6) or
28for iPlanet/Sun Webserver 6.0 and above however at the end of the
29<path-to-server>/https-servername/config/magnus.conf file:
30
31    Init fn="load-modules" funcs="php5_init,php5_execute,php5_auth_trans" shlib="/path/to/phplibrary"
32    Init fn=php5_init errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"]
33
34The "shlib" will vary depending on your OS:
35
36	Unix: "<path-to-server>/bin/libphp5.so".
37	Windows: "c:/path/to/php5/php5nsapi.dll"
38
39
40In obj.conf (for virtual server classes [Sun 6.0+] in their vserver.obj.conf):
41
42    <Object name="default">
43    .
44    .
45    .
46    # NOTE this next line should happen after all 'ObjectType' and before
47    # all 'AddLog' lines
48    # You can modify some entries in php.ini request specific by adding it to the Service
49    # directive, e.g. doc_root="/path"
50    # For boolean ini-keys please use 0/1 as value, NOT "On","Off",... (this will not work
51    # correctly), e.g. zlib.output_compression=1 instead of zlib.output_compression="On"
52
53    Service fn="php5_execute" type="magnus-internal/x-httpd-php" [inikey=value ...]
54    .
55    .
56    .
57    </Object>
58
59This is only needed if you want to configure a directory that only consists of
60PHP scripts (same like a cgi-bin directory):
61
62    <Object name="x-httpd-php">
63    ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
64    Service fn="php5_execute" [inikey=value ...]
65    </Object>
66
67After that you can configure a directory in the Administration server and assign it
68the style "x-httpd-php". All files in it will get executed as PHP. This is nice to
69hide PHP usage by renaming files to .html
70
71Note: The stacksize that PHP uses depends on the configuration of the webserver. If you get
72crashes with very large PHP scripts, it is recommended to raise it with the Admin Server
73(in the section "MAGNUS EDITOR").
74
75
76Authentication configuration
77----------------------------
78
79PHP authentication cannot be used with any other authentication. ALL
80AUTHENTICATION IS PASSED TO YOUR PHP SCRIPT.  To configure PHP
81Authentication for the entire server, add the following line:
82
83    <Object name="default">
84    AuthTrans fn=php5_auth_trans
85    .
86    .
87    .
88    .
89    </Object>
90
91
92To use PHP Authentication on a single directory, add the following:
93
94    <Object ppath="d:\path\to\authenticated\dir\*">
95    AuthTrans fn=php5_auth_trans
96    </Object>
97
98
99Special use for error pages or self-made directory listings
100-----------------------------------------------------------
101
102You can use PHP to generate the error pages for "404 Not Found"
103or similar. Add the following line to the object in obj.conf for
104every error page you want to overwrite:
105
106    Error fn="php5_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
107
108where XXX ist the HTTP error code. Please delete any other Error
109directives which could interfere with yours.
110If you want to place a page for all errors that could exist, leave
111the "code" parameter out. Your script can get the HTTP status code
112with $_SERVER['ERROR_TYPE'].
113
114Another posibility is to generate self-made directory listings.
115Just generate a PHP script which displays a directory listing and
116replace the corresponding default Service line for
117type="magnus-internal/directory" in obj.conf with the following:
118
119    Service fn="php5_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
120
121For both error and directory listing pages the original URI and
122translated URI are in the variables $_SERVER['PATH_INFO'] and
123$_SERVER['PATH_TRANSLATED'].
124
125
126Note about nsapi_virtual() and subrequests
127------------------------------------------
128
129The NSAPI module now supports the nsapi_virtual() function (alias: virtual())
130to make subrequests on the webserver and insert the result in the webpage.
131The problem is, that this function uses some undocumented features from
132the NSAPI library.
133
134Under Unix this is not a problem, because the module automatically looks
135for the needed functions and uses them if available. If not, nsapi_virtual()
136is disabled.
137
138Under Windows limitations in the DLL handling need the use of a automatic
139detection of the most recent ns-httpdXX.dll file. This is tested for servers
140till version 6.1. If a newer version of the Sun server is used, the detection
141fails and nsapi_virtual() is disabled.
142
143If this is the case, try the following:
144Add the following parameter to php5_init in magnus.conf:
145
146    Init fn=php5_init ... server_lib="ns-httpdXX.dll"
147
148where XX is the correct DLL version number. To get it, look in the server-root
149for the correct DLL name. The DLL with the biggest filesize is the right one.
150
151But be warned: SUPPORT FOR nsapi_virtual() IS EXPERIMENTAL !!!
152
153
154$Id$
155