Deployment Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Deployment listeners allow a deployment client, such as the Visual COBOL 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:

The section named [virtual paths], containing a list of URL top-level directories and the paths they will be converted to.
A section named [allow], with rules for what can be retrieved from the virtual paths.
Optionally, a [security] section configuring security for deployment.

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 %ProgramFiles(x86)%\Micro Focus\Visual COBOL\bin and \bin64 (Windows) or $COBDIR/bin (UNIX).

On Windows platforms, the special token "<ES>" is translated into the installation directory. For example, if Enterprise Server is installed as part of Visual COBOL in the default installation directory, then "<ES>/deploy" becomes %ProgramFiles(x86)%\Micro Focus\Visual COBOL\deploy.

On UNIX platforms, the special token "<ES>" is translated into the directory named by the COBDIR environment variable, which should be the COBOL Server installation directory. For example, if $COBDIR is /opt/microfocus/VisualCOBOL, then "<ES>/deploy" becomes /opt/microfocus/VisualCOBOL/deploy, the default deployment directory.

Note: On UNIX platforms, the value of $COBDIR used by Enterprise Server is the one set for the Directory Server process, which normally runs as a system daemon.

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:

For Windows platforms:

[virtual paths]
 <default>=c:/web
 docs=c:/web/documents
 images=d:/media/images

With this configuration, the URL http://host:port/docs/a.html will return the file c:\web\documents\a.html, and the URL http://host:port/images/gif/b.gif will return the file d:\media\images\gif\b.gif.

For UNIX platforms:

[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.

The [security] section

Beginning with COBOL Server 5.0, deployment listeners have additional optional security features:

Deployment listeners may require user authentication for each request. This prevents anonymous access to deployment and ensures deployment is only performed by clients with valid credentials. (Credentials may be a username/password pair, validated against the Enterprise Server instance's security configuration, or a client certificate, depending on listener configuration.)
When user authentication is enabled, the Enterprise Server security system may also be configured to restrict access to particular users.
Also, with user authentication enabled, it is possible to configure the mfdepinst program to use the authenticated user when binding to the Micro Focus Directory Server (MFDS) to create the new service and package objects. This is useful for administrators who want more fine-grained control over updates to the Enterprise Server configuration information. For more information refer to the documentation for the .mfdeploy file.

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

Here:

The setting restricted=yes enables user authentication. It also enables access restriction if the server's security configuration supports resource access control (most commonly using LDAP-based security for Enterprise Server), and the resource class "Enterprise Server Web" is defined to the External Security Manager. (A different name can be configured for this class with the class setting.) See the topic Restricting access to service deployment for more information.
The setting authentication=MF, HTTP instructs the listener to support username/password user credentials from the client, passed in one of two ways: a proprietary mechanism used by older versions of Visual COBOL (for backward compatibility) and standard HTTP Basic Authentication.

A full description of the syntax for the [security] section can be found in the Web conversation type topic.

Certificate authentication for deployment

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:

The Enterprise Server instance must be configured to use External Security (ESF). This is true for all types of deployment listener authentication and access control.
The deployment listener must be configured to use SSL/TLS.
1. The SSL/TLS configuration for the listener must be set to request client certificates and verify them (require a certificate), or verify them when present (allow but do not require, making certificate authentication optional).
2. The SSL/TLS configuration must specify a collection of trusted Certification Authority signing certificates, sometimes called root certificates.
The listener's configuration must enable certificate authentication in the configuration text area. It must include the [Security] section with Authentication specifying the certificate and/or register tokens.
The deployment client must be configured, usually using the mf-client.dat file, to send a client certificate. This certificate must be signed by one of the Certification Authority signing certificates in the collection specified for the listener.
The client certificate must be known to the Enterprise Server instance and associated with a user. There are two ways to accomplish this:
1. The certificate can be registered with Enterprise Server using the cascertreg command-line utility.
2. If automatic registration is enabled, as described in the next section, the user can connect to the deployment listener with a web browser that has been configured to send the same client certificate. The browser will prompt for the Enterprise Server username and password to be associated with the certificate. If Enterprise Server successfully authenticates the username and password, it will register the certificate.
  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 client certificate registration for deployment listeners

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.