Deployment listeners allow a deployment client, such as the Enterprise Developer IDE or the imtkmake utility, deploy COBOL web services or EJBs to an Enterprise Server instance. The combination of a deployment listener, an associated deployment service, and the .mfdeploy file in the deployment directory control how deployment requests are handled.
Several aspects of deployment are determined by settings in the configuration information for a deployment listener, which consists of these sections:
For example, the Web listener used by ESDEMO's Deployer service looks like this:
[virtual paths] cgi=<ES>/bin uploads=<ES>/deploy <default>=/dev/null docs=<ES>/help [allow] cgi=mfdeploy.exe uploads=*.txt *.car *.wsdl
The "cgi" virtual path is used to specify the location of the mfdeploy.exe program that receives the COBOL archive file being deployed, and the "uploads" virtual path tells mfdeploy.exe where to create the directory for the uploaded COBOL archive file.
mfdeploy.exe is located in $COBDIR/bin.
Only the first directory in the URL specified by the client performing the deployment is checked against the list, and the entries in the list have to be just a single directory name.
The "<default>" directory is used if the first directory in the URL specified by the client doesn't match any of the entries in the list. The default directory must be one that does not exist, so that when the communications process translates the URL into a full path, the request will fail. This stops any attempt by a client to browse arbitrary directories on the machine. You don't need to specify a default directory, since the communications process uses a safe default anyway.
The "docs" virtual path can be used to retrieve product documentation, but is present largely for historical reasons.
Here is another example:
[virtual paths] <default>=/usr/web docs=/usr/web/documents images=/home/media/images
With this configuration, the URL http://host:port/docs/a.html will return the file /usr/web/documents/a.html, and the URL http://host:port/images/gif/b.gif will return the file /home/media/images/gif/b.gif.
The entries in the "[allow]" section restrict what files can be retrieved from a virtual path. Its entries are the names of virtual paths, and their values are filename patterns (delimited by spaces), one of which must match the requested file. The configuration created for a new deployment service will allow only mfdepinst.exe from the "cgi" virtual directory; and only text (*.txt), COBOL archive (*.car), and WSDL (*.wsdl) files from deployment directories under the "uploads" virtual directory.
Beginning with Enterprise Server 5.0, deployment listeners have additional optional security features:
These features are enabled in the optional [security] section of the deployment listener's configuration text area. For example:
[security] restricted=yes authentication=MF, HTTP
A full description of the syntax for the [security] section can be found in the Web conversation type topic.
A deployment listener can be configured to identify users using client certificates. When a deployment client connects to a deployment listener in this configuration, it sends a certificate (and proves it has the private key that corresponds to the certificate, as part of the TLS handshake). The listener can associate the certificate with an Enterprise Server user, and then check whether that user is authorized to deploy services.
Certificate authentication has the following requirements:
Automatic registration can also be performed with deployment clients that allow the user to specify a username and password. If the deployment client is configured to use a client certificate, and also configured with a username and password, it will attempt to automatically register the certificate if the server does not recognize it. Once the certificate is registered, the username and password can be removed from the client's configuration.
Automatic certificate registration is a mechanism to help administrators move to using certificate authentication for deployment. It relieves administrators of the need to manually register each client certificate.
To enable automatic registration, include the register token in the list of authentication methods configured for the listener (the Authentication setting in the optional Security section of the listener's text configuration area).
When automatic registration is enabled, if the listener receives a client certificate that is not already registered, it will check the request for a username and password sent using the standard HTTP Basic Authentication header. If they are not present, the listener will send back an HTTP response requesting them.
Once the listener has a username and password, it will ask the Enterprise Server instance's security stack to validate the credentials. If that succeeds, it will register the client certificate with the username, and proceed to check whether the user is authorized to perform the requested action.