The .mfdeploy file

The .mfdeploy file is used by the Visual COBOL deployment feature, which is used by application developers and administrators to deploy COBOL Web Services and EJBs to Enterprise Server instances.

The .mfdeploy file serves two purposes:

• A .mfdeploy file must exist in the parent directory of the directory where the COBOL Archive (.CAR) file is being processed. This is a security measure to prevent abusing the deployment mechanism to create or overwrite files outside an authorized deployment area.
• The contents of the .mfdeploy file are configuration information for mfdepinst, the Micro Focus Deployment Installer.

When deploying using a deployment client, such as an IDE, the imtkmake utility, or the web-deploy.html web form, some of the configuration settings in .mfdeploy may be overridden or supplemented by information sent by the client.

Classic .mfdeploy configuration

The traditional .mfdeploy file contents are a series of name=value pairs, similar to environment-variable settings. In fact, in mfdepinst versions prior to 1.8, these settings are simply added to the mfdepinst process environment, then queried as needed.

An example setting is MFES_SERVER=ESDEMO, which tells mfdepinst which Enterprise Server instance will own the new service being installed, if the deployment client did not provide that information.

Settings recognized by mfdepinst include:

MFDS

MFC_MFDS

Specifies the location of the Micro Focus Directory Server. The default is "localhost".

MFDS_USER

The username to use when binding to MFDS.

MFDS_PASSWORD

The password to use when binding to MFDS.

MFES_SERVER

The name of the Enterprise Server instance under which the new service will be installed.

MFUS_SERVER

An old name for the above setting, maintained for backward compatibility.

MFES_LISTENER

The name of the Enterprise Server listener that will host the new service.

MFUS_LISTENER

An old name for the above setting, maintained for backward compatibility.

UPDATE_MODE

If this is defined with the value add, the deployment installer will allow a deployment package to specify additional operations for an existing service. If it is defined with the value replace, a deployment package can replace an existing service and its associated package in its entirety. Otherwise, the service being deployed must not already exist.

Advanced .mfdeploy configuration

From COBOL Server 5.0 onwards, the .mfdeploy file also supports an advanced configuration syntax with additional features. The classic and advanced styles can be used in the same file, as long as classic entries appear first.

The advanced syntax uses the "ini" format, with name=value lines grouped in named sections. Section names are enclosed in square brackets. Blank lines are ignored, and comments can be included by prefixing them with a hash sign (#). For example:

# Location of MFDS and credentials for binding
# These will usually be overridden by the deployment request,
# but apply when mfdepinst is run manually.
[MFDS]
MFDS=localhost
User=admin
Password=Secret password for admin

With the new syntax, the available sections and their settings are:

[MFDS]
MFDS=hostname[:port]
User=username
Password=password

[ES]
Server=ES-name
Listener=listener-name
Default server=ES-name
Default listener=listener-name

[Operation]
Update_mode=add

[Environment]
name=value

[Passwords]
username=password

In the [ES] section, the Default server and Default listener values are used only if the deployment client did not specify a target server and listener. The Server and Listener values, if set, will override any server or listener requested by the deployment client.

In the [Operation] section, the Update_mode setting has the same effect as setting UPDATE_MODE using the classic syntax. Note the underscore in the name. The value add is case-sensitive, for historical reasons.

The [Environment] section can be used to set arbitrary environment variables for the mfdepinst process. It is not generally necessary to use this section.

The [Passwords] section can be used to make mfdepinst bind to MFDS using the credentials of the user making the deployment requests. To enable this behavior:

• The Enterprise Server instance must be configured for External Security.
• The deployment listener must be configured for restricted mode, with HTTP and/or certificate authentication enabled.
• The user's password must be included in the [Passwords] section. This is because with HTTP and certificate authentication, the user's password is not otherwise available to the mfdepinst process.

If these criteria are not satisfied, mfdepinst will look in the request for a username and password to use when binding to MFDS. If none is found, it will use the default username and password specified in the [MFDS] section; and if those are not set, it will use a hard-coded default.

MFDS=localhost
MFES_SERVER=ESDEMO
MFES_LISTENER=Web Services and J2EE

# New configuration syntax with mfdepinst 1.8. The old syntax is still
# supported for backward compatibility, but the new format provides more
# options.

# The optional [Environment] section sets values in the mfdepinst environment.
# Any name=value items before the first section header are also put in the
# environment.
# [Environment]
# Name=value

[MFDS]
MFDS=localhost
# User=username for MFDS, if not supplied with request
# Password=password for MFDS, if not supplied with request

[ES]
# Default server is used if no server is specified in the request, and
# mfdepinst is not running under MFCS. If mfdepinst is running under MFCS,
# it uses the MFCS server name.
#
# The MFCS server name can be overridden with:
#    Server=name
# or with the old syntax (MFES_SERVER set in the environment, or in this ES
# section).
Default server=ESDEMO
Default listener=Web Services and J2EE

# The [Passwords] section can be used to set the MFDS password based on the
# remote user ID supplied using HTTP Basic Authentication.
# [Passwords]
# Username=password