 Running the OpenSOAP Server


(0) To run the OpenSOAP Server a HTTP Server is required.
At this time, operation with apache httpd 1.3.22 has been verified.


(1) In accordance INSTALL.txt, build and install the OpenSOAP Server.
Pay particular attention to the directory where soapInterface.cgi is installed.
This is used to connect apache httpd and the OpenSOAP Server.
The default setting places it in /home/httpd/cgi-bin, and, if necessary, use
the --with-cgi-bin to specify the CGI executable directory.


(2) By default, a service uses standard I/O for connection, but this behaviour
can be changed to socket connection by making the appropriate modifications to
the SSML settings file. Also, refer to RegistService.txt for instructions on
registering the service with inetd (xinetd).

A warning will be issued indicating that it is an error to run the service
programs as root.


Furthermore, by using the SSML settings, connecting to a service by specifying
the endpoint used by HTTP is now supported.
Please refer to the SSML_Readme.txt file for details.


(3) Edit the server settings file(server.conf) to be found under /usr/local/opensoap/etc/.



* Log files for all server processes

  <log>
    <path>/usr/local/opensoap/var/log/</path>
  </log>



* Server internal SOAP Message temporary directory

  <spool>
    <soap_message>
      <path>/usr/local/opensoap/var/spool/</path>
    </soap_message>



* Server internal asynchronous message temporary directory

    <async_table>
      <path>/usr/local/opensoap/var/spool/</path>
    </async_table>
  </spool>



* Server Processes ID management directory

  <run>
    <pid>
      <path>/usr/local/opensoap/var/run/</path>
    </pid>



* Server Processes Socket management directory

    <socket>
      <path>/usr/local/opensoap/var/run/</path>
    </socket>
  </run>



* Server Internal Signature Authentication management directory

  <security>
    <keys>
      <path>/usr/local/opensoap/etc/</path>
    </keys>
  </security>



* Service management SSML file registration directory

  <ssml>
    <path>/usr/local/opensoap/etc/ssml/</path>
  </ssml>



* Use the following setting when specifying the return EndPoint for an
  asynchronous request message. The following setting is required in order
  to indicate to the message responder where to send the message, and must
  be set to this server's location.
  Also, in order to check message transfer loop, if the server has another name
  or IP address, these should be listed as shown below.


  In the following example the response will be sent to

    http://myhost.opensoap.jp/cgi-bin/soapInterface.cgi


  <backward>
    <url>http://myhost.opensoap.jp/cgi-bin/soapInterface.cgi</url>
    <url>http://192.168.0.123/cgi-bin/soapInterface.cgi</url>
    <url>http://soap-server.opensoap.jp/cgi-bin/soapInterface.cgi</url>
  </backward>



* When the appropriate service is not available in this server, use the following
  setting to specify the EndPoint server to which the message will be forwarded.
  The server EndPoint is set in the <url>.
  In the following example, the message will be forwarded to

    http://yourhost.opensoap.jp/cgi-bin/soapInterface.cgi


  <forwarder>
    <url>http://yourhost.opensoap.jp/cgi-bin/soapInterface.cgi</url>
  </forwarder>


* Regarding server control messages for asynchronous message ID, etc.,
  the following setting is used to specify whether the server's signature
  is attached or not. When adding a signature, set this to true.


  <add_signature>false</add_signature>


* Setting the maximum size for a received SOAP message.
  It is now possible to set a limit on the maximum size for a received SOAP
  message. The message size is defined in bytes, but it is also possible
  to use 500k, 1M etc.
  Use negative values (ie. -1) to set no maximum limit.
  A value of 0 means no SOAP message will be accepted.

  <limit>
    <soap_message_size>1M</soap_message_size>
  </limit>


* For asynchronous processing, for incomplete internally queued processes,
  it is possible to set a cancellation time for the spool data. This is
  defined as seconds. Values less than 0 are not allowed.
    (If this is not set, it defaults to 3600 seconds)

  <limit>
    <asynchronizedTTL>3600</asynchronizedTTL>
  </limit>

  ** It is possible to set this value in the SSML file for each service, and
     this value, if set in the SSML file, takes precedence over all others.

  ** Also, it is possible to specify this value in each individual SOAP
     message header. In this instance, if the value specified in the SOAP
     header is LESS than that of the SSML file, then it takes precedence.
     If there is no value specified in the SSML file, then the value in the 
     header is used if it is less than that specified in the server.conf file.

       Example usage:
       server.conf  |  10  10  10  10  10  10
       SSML         |   -  20   5  20  20   -
       SOAP-header  |   -   -   -  30  15  15
       --------------------------------------
       Value used   |  10  20   5  20  15  10


* For synchronous process, it is possible to set the processing time-out in
  seconds for each SOAP message. Values less than 0 are not allowed.
    (If this is not set, it defaults to 600 seconds)

  <limit>
    <synchronizedTTL>600</synchronizedTTL>
  </limit>

  ** Using this value in the SSML file or in the SOAP message header is the
     same as for the <asynchronizedTTL> usage described above.


* Setting a limit on the number of allowable transfers of a SOAP message.
  If this is set to 0, no transfer is allowed. Negative values are not allowed.
   (If this is not set, the internal system default of 4 is used)

  <limit>
    <ttl>
      <hoptimes>4</hoptimes>
    </ttl>
  </limit>

  ** As before, usage of this value in th SSML file and SOAP header is the same
     as for the <asynchronizedTTL> value described above.


(4) The service settings files, SSML files, are place under /usr/local/opensoap/etc/ssml/ .

Refer to the file SSML_Readme.txt, in the same directory, for a description of SSML usage.



(5) Verify that the apache httpd is running.

If not, start the httpd server.



(6) Initiating the server process.

This is performed through the path ${bindir}.(The default is /usr/local/opensoap/sbin)

(6-00) Execute the command ${bindir}/opensoap-server-ctl start

* 1: To stop the server use the command ${bindir}/opensoap-server-ctl stop

* 2: When additions are made to the SSML execute the command ${bindir}/opensoap-server-ctl reload .

=============

 Process List

=============

* 3: In the case of (6-00) above, execute the commands (6-01) to (6-11) below.


(6-01) srvConfAttrMgr 

          Server configuration attribute manager process


(6-02) ssmlAttrMgr 

          SSML attribute manager process


(6-03) idManager 

          Internal messaging manager process


(6-04) msgDrvCreator 

          Message processing distribution manager process


(6-05) queueManager 

          Message queue manager process


(6-06) queueManager 1 

          Transfer message queue manager process


(6-07) spoolManager 

          Asynchronous response message spool manager process


(6-08) ttlManager 

          Message TTL manager process


* 4: Use this OpenSOAP Server process list to manually terminate any remaining processes.


(7) Run the client program.


======================================

 OpenSOAP Server Debug/Bug Reporting


(1) All program logs can be found under /usr/local/opensoap/var/log/ .
Please check here when any errors are encountered.(Default server.conf)


(2) Use the CXXFLAGS=-DDEBUG configure option to generate detailed logs.


(3) If any program terminates abnormally, its name will not be displayed
on execution of the command opensoap-server-ctl stop. This indicates that
the program terminated prematurely. Please feel free to report any errors
or bugs that are encountered. 

