Rakesh's web blog: Web Server 7 stuff

The PHP Add-on 1.0 has Mysql support built into it. To test whether mysql works with Sun Java System Web Server or not, write the following simple script (in testMysql.php) and test it out. I have used 5.0.41 (The Web Server PHP Add-on works with all 5.x versions of mysql) version of mysql with user name as 'root', password as 'adminadmin', and database as 'rakesh'.

Note: please refer to my last post on setting up PHP with Sun Java System Web Server. I assume that you have already created a fastcgi handler with URI  pattern as '/php/*' and role as 'responder'.


If there was no error in the connection to the database, you should observe just the following, when your request to the web server is something like this: http://localhost:1894/php/testMysql.php.

• Connected Successfully!!

  
  

Lets deliberately introduce some error into the script by providing a wrong password ($password = wrongpassword) in the script. Again send a request to the web server as http://localhost:1894/php/testMysql.php. You should get the following error messages.

• Warning: mysql_connect() [function.mysql-connect]: Access denied for user 'root'@'localhost' (using password: YES) in C:\rak\ws71\iplanet\ias\server\work\B1\WINNT4.0_DBG.OBJ\https-test\ docs\php\testMysql.php on line 6 Error connecting to mysql

  
  

This article explains how to install and use PHP with Sun Java System Web Server 7.0 (Web Server from now onwards. Click to download ).
Assuming that you have already installed web server, all you need to do is:

• Download the SJSWS 7.0 PHP Add-On 1.0 (Click to download).
• Unzip the contents on to a local drive, say C:\php. After extracting the files, you should find the php executable (php-cgi.exe) under C:\php\phppack-5_2_0-windows-i586\php (lets call it <php_dir> from now onwards).
  
• Use either CLI (Command Line Interface) or GUI (Graphical User Interface) to configure PHP.
  

While there are different ways of  installing the PHP engine (Click to find out other ways of installing PHP engine on web server), this article discusses installing the PHP engine as a FASTCGI server. Before proceeding any further, there is some basic terminology that you should make yourself comfortable with (Click here for more info on FASTCGI plugin for web server).

There are four different types of FASTCGI applications, namely: Authorizer, Responder, Filter and Error (Click here for more info). A 'fastcgi-handler' refers to the handle to one of these four roles.


1. Using GUI:

• From the Common Tasks page, click on 'Edit Virtual Server > Content Handling > FASTCGI'.
• Click New to create a new URI with FASTCGI handler mapping.

• 
  

• By default, this mapping applies to the entire virtual server(lets say 'test' in this case). If you choose this option, web server looks for the files (to be served) in the default document root, which is <install_dir>/https-test/docs (<doc_root> from here onwards).
• Lets create a new URI called '/php/*' so that requests from http://localhost:1894/php/*.php will be served from '<doc_root>/php/'.
• Role is 'Responder' by default. From the drop down menu, choose the role as per your requirement. Lets select 'Responder' for now, which is used widely.
  
• Mime type is optional. Lets leave it for now.
  
• Out of Bind Path and Application Path, one of them must be provided. Providing both of them is also fine.
• Bind Path is a Unix Domain Socket or a Named Pipe or of the form host:port. Lets leave it for now.
• Application Path is the FASTCGI Server application path that processes the request. Applicatioin Path is most widely used compared to Bind Path. In our example, it is the path to the php executable: <php_dir>/php-cgi.exe.
• The next two attributes: Arguments and Environment Variables are applicable only when Applicatioin Path is specified and are also optional. Lets leave them for now.
• Click on OK to save changes. A FASTCGI enabled URI will be created successfully, but thats not all of it, you need to deploy the changes. Click on Deployment Pending link, followed by a click on Deploy button to deploy the configuration to all nodes. If you are creating a handler for the first time, you will be prompted to restart the instances. Choose 'Now' and click OK to restart the instance(s).
• Lets test whether php works fine or not.
  
• Make sure that you create directory named 'php' under <doc_root>. Create a test.php file with the contents as <? phpinfo() ?>, save and exit.
• Send a request (http://localhost:1894/php/test.php) to the web server from your browser. If PHP is configured properly, you should observe the following on your browser window (Note: only part of the image is copied here).

• 
  

2. Using CLI:

• There are 5 commands associated with a fastcgi-handler, namely create-fastcgi-handler, delete-fastcgi-handler, get-fastcgi-handler-prop, set-fastcgi-handler-prop, and list-fastcgi-handlers. The names are descriptive enough not to cause any confusion.
• Assuming that you are already connected to wadm, invoke create-fastcgi-handler command on the cli prompt to get the usage.
  

• wadm>create-fastcgi-handler usage: create-fastcgi-handler [--echo] [--no-prompt] [--verbose] [--mime-type=type] [--uri-pattern=pattern] [--role=authorizer|responder|filter|error] [--app-path=path] [--app-args=arg1,arg2...] [--bind-path=path] [--min-procs=count] [--max -procs=count] [--chroot=directory] [--server-user=user-id] [--group=group-id] [--nice=value] [--listen-queue-size=size] [--app-env='name=value','name=value'...] [--reuse-connection] [--connection-timeout=time-in-seconds] [--response-timeout =time-in-seconds] [--restart-interval=minutes] [--request-retry=retry-count] [--error-url=url] [--error-reason=string] --config=name --vs=name CLI014 config is a required option.

  
  
• Lets create a fastcgi handler with the role as 'Filter', by invoking the command as follows (Note: You need to escape '\' on Windows platform):

• wadm> create-fastcgi-handler --config=test --vs=test --uri-pattern=/php/* --role=filter --app-path=C:\\php\\phppack-5_2_0-windows-i586\\php\\php-cgi.exe CLI201 Command 'create-fastcgi-handler' ran successfully

  
  
• Deploy the config by invoking the following command.
  

• wadm> deploy-config test CLI201 Command 'deploy-config' ran successfully

  
  
• If you are creating the handler for the first time, you need to restart the instance as follows

• wadm> restart-instance --config=test localhost CLI202 Successfully restarted the server instance.

• Lets test a simple filter application to make sure that PHP works fine. Copy the files: <install_dir>/samples/fastcgi/pageCounter.php and <install_dir>/samples/fastcgi/counter.txt to <doc_root>/php. Send a request (http://localhost:1894/php/pageCounter.php) to the web server from your browser. If there are no issues during the configuration of PHP, you should observe the following (Note: the count increases as per the number of requests).
• Page Counter: 1

Thats it! A simple way of configuring php to work with web server. In summary, you need the application path and the php files in right locations to get things working. In my future posts, I will discuss more about the optional attributes that I have left out. Feel free to shoot any questions.

Are you using 6.0 or 6.1 version of Web Server? Do you wanna try the new and cool features of Sun Java System Web Server 7 with the settings of your 6.0 or 6.1 version?, then use the migration option provided in Sun Java System Web Server 7 (Download).

What will  be migrated from 6.0/6.1 to 7.0?

• Configurations-For every instance of 6.0/6.1, a new configuration will be created in webserver 7.0 (Please refer to migration logs <default location is admin-server/logs/MIGRATION*.log>  for more information on the files that will be/will not be migrated).
• Search -  Search collections can be migrated physically.
  
• Web-apps-  Web-app entries in server.xml will be migrated. If the web-apps directory resides under config-root of the migrating instance, it will be copied to the config-root of the new configuration.
  

How to migrate?

You can use either GUI or CLI to migrate.

Using GUI: Click on Migrate Configuration link from the Common Tasks page to open a wizard, which will guide you through the migration process.

Using CLI: Connect to wadm as shown below. (Note : wadm is located under the bin directory of your web server 7.0 installation root)

INSTALL_ROOT/bin/wadm --user=admin --port=8989 Please enter admin-user-password> Sun Java System Web Server 7.0-Technology-Preview-1 B05/15/2006 wadm>

wadm>migrate-server Usage: migrate-server [--echo] [--no-prompt] [--verbose] [--search-collection-copy-path=directory] [--log-dir=directory] ( [--all] | [--config=newconfigname] [--instance=instancename] ) --server-root=path CLI014 server-root is a required option.

Migrate all instances of a given 6.x installation using a single command.

wadm> migrate-server --log-dir=/logDir  --all=true --server-root=/Sun/WebServer6.1

Migrate specific intances of a given 6.x installation using a single command.

wadm> migrate-server --log-dir=/logDir  --config=rakesh --instance=https-rakesh --server-root=/Sun/WebServer6.1                                                                   OR wadm> migrate-server --log-dir=/logDir  --instance=https-rakesh --server-root=/Sun/WebServer6.1

--config is the new configuration name and --instance is the 6.x instance that you want to migrate. If you do not specify the --config option, a new config will be created from the instance name with 'https-' stripped from it (rakesh in this case).

---

About search migration

(1) If the search collection path is outside the 6.x instance, then migrated collection path will point to the same directory.

(2) (a)  If the search collection path is within the 6.x instance, and the user enters a valid value for search-collection-copy-path option, then the migrated collection path will be
    <search-collection-copy-path>/<instance name>/<vs id>/<collection name>
and migration will copy the collection to that directory.
(2) (b) If the search collection path is within the 6.x instance, and the user enters a wrong value for search-collection-copy-path option, then no collection will be created and a log message will be recorded.

(3) If the search collection path is within the 6.x instance, and the user does not enter any value for search-collection-copy-path option, then the migrated collection path will be
    ../collections/<vs id>/<collection name>
and log message will be recorded(asking the user to add the documents manually). Admin will create the "../collections/<vs id>/<collection name>" directory.

About Migration Logs

You can specify the directory in which you want the migration logs to be present.Otherwise, the default directory will be used which is,

        'INSTALL_ROOT/admin-server/logs'.

Post migration tasks

Migration of instances would simply create new configurations on webserver 7.0. User has to manually create instances for these configurations by using Create Instance command.

Eg: Migration of an instance, say "https-rakesh" from 6.0/6.1 would create a new configuration "rakesh" on 7.0. When the user creates an instance for "rakesh", it would be https-rakesh on web server 7.

Once you are done with Migrating your 6.x instance(s) please refer to the migration logs for some manual changes that you need to do.

Attention Windows operating system users!, you have to take care of certain things while migrating from 6.x to 7.0. Please, refer to the "Resolving Service ID conflicts during migration  on Windows Platform" section, to avoid service id conflicts as shown below.

wadm> create-instance --config=rakesh shogan Node "shogan": ADMIN3210: Could not create the instance because the Windows service 'https-rakesh' already exists.

---

Resolving Service ID conflicts during  migration on Windows Platform

Let us start from migrating a 6.x instance, say "https-rakesh". Migration using GUI would default the new configuration name to "rakesh", ie. it strips off 'https-'.On Windows platform, creation of instance for any config ("rakesh") will try to register a service-id ("https-rakesh") with Windows  Services. But, the service id "https-rakesh" is already taken by the existing  6.x instance, which is "https-rakesh" (plese, don't get confused by "https-rakesh" being used at two places, first one refers to service-id and the second one refers to instance). Hence, there would be a service-id conflict and creation of instance would fail for the migrated config.

There are two ways to handle this scenario. The first one can be used while migrating, whereas the second one can be used after migration.

1). Change the config name at the time of migration. Ensure you pick a name for which the service ID will be available.

    CLI: use the –config option of the migrate-server
    command.

    GUI: rename the default config name in the migrate
    server wizard.

2).If you've forgotten to change the config name or used --all option of while migrating, then creation of instances would fail. As a workaround copy  the configuration using the copy-config feature of web sever 7.0 to copy this configuration(rakesh) to a different and unique configuration(say rakesh-6x) and make sure that the service-id https-rakesh-6x is not taken already.

    CLI:

wadm> copy-config --config=rakesh rakesh6x CLI201 Command 'copy-config' ran successfully

    GUI: Go to Configurations page, click on 'copy' of
    Configurations table, enter a new config name and
    complete the copying  of configuration.

Feel free to shoot any questions on migration or related topics.