Upgrade Manual

    Upgrade instructions

    For upgrade instructions, refer to Upgrade XL Deploy.

    Specific upgrade notes

    This section describes specific considerations for migrating from or to a particular XL Deploy/Deployit version:

    Upgrading to XL Deploy 4.5.5

    Security configuration has been consolidated

    Spring Security configuration settings that were previously stored in the internal deployit-context.xml file have been moved to the <XLDEPLOY_HOME>/conf/deployit-security.xml file. This change consolidates the Spring Security configuration and makes it easier to integrate XL Deploy security with external user authentication.

    Important: When upgrading, do not copy the <XLDEPLOY_HOME>/conf/deployit-security.xml from your previous installation of XL Deploy. Use the deployit-security.xml file that is included with XL Deploy 4.5.5 and manually update it with any customizations that are specific to your environment (such as your LDAP credentials).

    Upgrading to XL Deploy 4.5.4

    Generic plugin behavior

    The MODIFY behaviour of the generic.CopiedArtifact has been improved. While the older versions did not allow modification when preserveExistingFiles was set to true, from this version up any files specified in the CI will be overwritten and all other files on the same path will be preserved.

    Upgrading to XL Deploy 4.5.3

    Automatic repository upgrade

    The first time this version of XL Deploy is started with a repository created with an older version of XL Deploy, the following upgraders will automatically upgrade the repository:

    • Deployit453FolderChecksums: This upgrader updates the checksum property of all udm.FolderArtifact type artifacts. Artifacts with a custom checksum value will be ignored, while others will have a new SHA-1 checksum calculated according to an algorithm which takes into account empty files and file paths.

    Changes to deployed object in rules

    The behavior of the deployed object in the planning and script contexts has changed. Previously, deployed pointed to the current or previous deployed, depending on the operation.

    In XL Deploy 4.5.3, in the case of a CREATE, MODIFY, or NOOP operation, deployed points to the "current" deployed that the delta variable refers to. In the case of DESTROY, deployed is not available.

    In the case of a MODIFY, DESTROY, or NOOP operation, the new previousDeployed object points to the "previous" deployed that the delta variable refers to. In the case of CREATE, previousDeployed is not available.

    For more information, refer to Getting started with XL Deploy rules and Objects and properties available to rules.

    Changes to FreeMarker variables for os-script step

    In FreeMarker templates used by the os-script step, ${deployed.file} now evaluates to the uploaded file. This means that you can use the following expressions:

    • ${deployed.file.path}: Complete path of the uploaded file. For example, /tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.
    • ${deployed.file.name}: Name of the uploaded file. For example, PetClinic-1.0.ear.
    • ${deployed.file}: toString of the uploaded file. For example, ssh:sftp://root@jboss-51:22/tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.
    • ${deployed.deployable.file.path}: Complete path of the uploaded deployable file (without placeholder replacement). For example, /tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.

    Note that if you have previously used ${deployed.file.name} in a template, you may need to change it to ${deployed.file.path}.

    For more information, refer to the Steps Reference.

    Items deprecated in XL Deploy 4.5.3

    Parameter script-path of jython step primitive Will be removed in XLD 5.5.0 in favor of script parameter

    Upgrading to XL Deploy 4.5.1

    Security upgrade

    • Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:
      • Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
      • Change .../spring-security-3.1.xsd to .../spring-security.xsd


    Property targetFileName of file.Folder This property is not functional and will be removed in XLD 5.0.0

    Upgrading to XL Deploy 4.5.0

    Increased PermGen space

    The Permanent Generation memory (PermGen) allocation for XL Deploy has been increased. The default value of PermGen was increased from 128 MB to 256 MB. The value is specified in bin/server.sh and bin/server.cmd.

    Exposing password properties in exported package

    Before XL Deploy 4.5.0, a package export showed all password properties of deployables in an unencrypted and unobfuscated form. This is no longer the case. Currently, the default is only to export password properties whose values looks like a placeholder (e.g. {{PASSWORD}}) and to remove the value for the passwords that are not using placeholders.

    To control whether password properties should be exported, you can use the following two properties:

    • udm.Version.exportAllPasswords: If set to true, all passwords will be exported. Its default value is false, that means no passwords are exported by default.
    • udm.Version.exportOnlyPasswordPlaceholders: If set to true, only passwords that looks like placeholders (i.e. starting and ending with double curly braces) will be exported, and the rest will be exported as empty string. Its default value is true.

    You can change the default values of these properties using conf/deployit-defaults.properties file.

    If passwords were removed from the exported DAR archive, you will not be able to import it again, as password properties are by default required properties. To fix this you can choose one of the following solutions:

    • Use placeholders instead of actual values for the passwords, as placeholders are by default kept as they are in the exported package. This is the recommended practice.
    • Set udm.Version.exportAllPasswords to true before doing the export. This way, all the passwords are exported to the package manifest.
    • Add the missing passwords by manually editing the manifest file from the exported DAR archive.

    Importing a package with undefined CI properties in manifest

    In the previous versions, the package importer ignored the undefined CI properties used in the manifest and continued importing the package without raising a warning or error. Because of that, when upgrading to a new version of a plugin with different / changed CI properties, there is no indication that an existing package may be invalid. The error was only discovered at deployment time.

    Starting with the current version of XL Deploy, this situation can be handled in two ways. The default behaviour is to print a warning in the logs when importing a package with undefined CI properties. The alternative behaviour is to throw an exception and fail the package import.

    You can change the default behaviour by setting the value of udm.Version.ignoreUndefinedPropertiesInManifest to true in conf/deployit-defaults.properties file.


    This is a list of things that are marked as deprecated and will be removed in the next major version of XL Deploy.


    Deprecated item 1
    Replacement for deprecated item 1
    Deprecated item 2
    Replacement for deprecated item 2


    Deprecated item 1 Replacement 1
    Deprecated item 2 Replacement 2
    etc. etc.
    General deprecations
    • Support for Internet Explorer 8 and Internet Explorer 9 will be removed in XL Deploy 5.0.0.
    • Support for the MANIFEST.MF format for XL Deploy manifests is deprecated. Please migrate to the deployit-manifest.xml format.
    • The following orchestrators are deprecated:
      default (no orchestrator)
      container-by-container-serial sequential-by-container
      composite-package sequential-by-composite-package
      group-based sequential-by-deployment-group
    Deprecations in REST services
    • The REST endpoint /security/check/{permission}/{ciID} will no longer support HEAD requests. Instead, use a GET request, which returns a Boolean value instead of an HTTP status.
    • Endpoint /task will be removed. Use the /task/v2 endpoint instead.
    • The related object types TaskState and TaskWithSteps will be removed and superseded by TaskWithBlock, BlockState, and StepBlockState.
    • From the /deployment endpoint:
      /deployment/preview /deployment/previewblock
      /deployment/preview/{stepNumber} /deployment/previewblock/{blockId}/{stepNr}
      /deployment/generate/all /deployment/prepare/deployeds (note that this has slightly different semantics)
    Deprecations in the CLI
    • The tasks object is deprecated. Use task2 instead.
    • The related object types TaskState and TaskWithSteps will be removed and superseded by TaskWithBlock, BlockState, and StepBlockState.
    • From the deployment object:
      deployment.taskPreview(Deployment deployment) deployment.taskPreviewBlock(Deployment deployment)
      deployment.stepPreview(Deployment deployment, Integer stepNumber) deployment.taskPreviewBlock(Deployment deployment, String blockId, Integer stepNumber)
      deployment.generateAllDeployments(Deployment deployment) deployment.prepareAutoDeployeds(Deployment deployment) (note that this has slightly different semantics)
      deployment.deploy(Deployment deployment) deployment.getDeployTask(Deployment deployment)
      deployment.undeploy(String deployedApplication) deployment.createUndeployTask(String deployedApplication)
      deployment.rollbackTask(String taskId) deployment.getRollbackTask(String taskId)
      deployment.createTask(Deployment deployment) deployment.getDeployTask(Deployment deployment).getId()
    • From the repository object:

      repository.getArchivedTasks() repository.getArchivedTasksList()
      repository.getArchivedTasks(String beginDate, String endDate) repository.getArchivedTasksList(String beginDate, String endDate)

    • From the deployit object, the following calls will be deprecated:

      deployit.retrieveTaskInfo(String taskId) task2.get(String taskId)
      deployit.listUnfinishedTasks() task2.getMyCurrentTasks()
      deployit.listAllUnfinishedTasks() task2.getAllCurrentTasks()
      deployit.discover(ConfigurationItem ci) deployit.createDiscoveryTask() together with deployit.retrieveDiscoveryResults()

    Deprecations in plugins
    • The following FreeMarker-related methods will be deprecated from CIs in the Generic plugin:

      Namespace com.xebialabs.deployit.plugin.generic.freemarker
      constructor CiAwareObjectWrapper(ArtifactUploader uploader)
      constructor CiAwareObjectWrapper(ArtifactUploader uploader, boolean maskPasswords)
      constructor CiTemplateModel(ConfigurationItem ci, CiAwareObjectWrapper wrapper)
      constructor CiTemplateModel(ConfigurationItem ci, CiAwareObjectWrapper wrapper, boolean maskPasswords)

    • From the Remoting plugin:

      Namespace `com.xebialabs.deployit.plugin.overthere
      class AutoFlushingExecutionContextOverthereProcessOutputHandler
      class DefaultExecutionOutputHandler
      class ExecutionContextOverthereProcessOutputHandler
      class DefaultExecutionOutputHandler (also)

    Deprecations relevant for extenders
    • If you have written Java Contributors, PrePlanProcessors, or PostPlanProcessors, these need to be static methods.
    • For control tasks, the generic delegate type is deprecated. Use shellScript instead.
    • All Java-backed control task delegates need to be static methods.
    • You can no longer use getSyntheticProperties(...), putSyntheticProperties(...), or setSyntheticProperties(...) on CIs. Use getProperty(), etc.
    • Every custom CI will be required to extend BaseConfigurationItem (or a subclass thereof).
    • If you are writing your own Steps, note that in the Generic plugin's BaseStep class:
      method evaluateTemplate(String templatePath, Map<String, Object> vars)
      method evaluateTemplate(String templatePath, Map<String, Object> vars, boolean maskPasswords
    • The namespace com.xebialabs.deployit.plugin.api.execution is deprecated:
    • The namespace com.xebialabs.deployit.plugin.api.deployment.execution is deprecated:
    • If you have implemented your own orchestrators, note that all constructors without the description argument are deprecated. Use the variants that include them as their first arguments. This holds for these classes:
      • CompositeOrchestration
      • InterleavedOrchestration
      • ParallelOrchestration
      • SerialOrchestration
      • ... and their factory methods in the Orchestrations class
    • If you have written your own importer, in the ImportedPackage class, note that:
      In class com.xebialabs.deployit.server.api.importer.Importer
      constructor ImportedPackage(PackageInfo packageInfo)
      constructor ImportedPackage(PackageInfo packageInfo, Application application, Version version)
      method getDeploymentPackage()
      method getVersion()
    • When creating new CIs, note that:
      com.xebialabs.deployit.plugin.api.reflect.Descriptor.newInstance(String id)
    • The following Java classes have been deprecated:
      • com.xebialabs.deployit.cli.api.legacy.FullTaskInfo
      • com.xebialabs.deployit.cli.api.legacy.FullTaskInfos
      • com.xebialabs.deployit.cli.api.legacy.StepInfo
      • com.xebialabs.deployit.cli.api.legacy.TaskInfo

    Upgrading to XL Deploy 4.0.2

    Security upgrade

    • Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:
      • Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
      • Change .../spring-security-3.1.xsd to .../spring-security.xsd

    Upgrading to XL Deploy 4.0.0

    New license necessary

    We made changes to the license system as a result a new license file is needed to run XL Deploy. You can download your license from https://dist.xebialabs.com/customer/licenses/. The license needs to be installed into the conf directory.

    Note: Ensure the license file is not changed in any way, that will corrupt the license. Some mail programs may corrupt the license file unless wrapped in a ZIP.

    Java 7

    XL Deploy requires Java 7 to run.

    Plugin compatibility

    The following old plugins are not compatible with XL Deploy 4.0.0:

    • glassfish-plugin 3.9.x
    • ec2-plugin 3.9.x
    • cloud-plugin 3.9.x
    • wls-plugin 3.9.x
    • jbossdm-plugin 3.9.x
    • wp-plugin 3.9.x
    • was-plugin-extensions 3.9.x

    Use of cp, tar, copy and xcopy

    XL Deploy 4.0.0 uses version 2.4.2 of the remoting framework Overthere that introduces a new feature to copy files on a remote machine in an efficient manner. Overthere 2.4.2 does this by using the following commands to copy file and directories (where {0} is replaced with the path of the source file or directory and {1} is replaced with the path of the target file or directory):

    • File copy on Unix and z/OS: cp -p {0} {1}
    • Directory copy on Unix and z/OS:
      • XL Deploy 4.0.0: tar cC {0} . | tar xmC {1} .
      • XL Deploy 4.0.1 and up: cd {1} ; tar -cf - -C {0} . | tar xpf -
    • File copy on Windows: copy {0} {1} /y
    • Directory copy on Windows: xcopy {0} {1} /i /y /s /e /h /q

    This functionality is used in three places in XL Deploy:

    • When a file or directory is staged, it will be uploaded to the staging directory at the start of the deployment and then, when a step uses it, it will be copied to the target directory or the temporary directory (depending on the plugin) using one the commands specified above.
    • The behavior of the File Plugin has been modified to more atomic:
      1. If staging is enabled, the file or directory will be uploaded to the staging directory at the beginning of the deployment and then copied from the staging directory to the target directory (using one the commands specified above) during the actual deployment.
      2. If staging is not enabled, the file or directory will be uploaded to the temporary directory and immediately copied from there to the target directory (using one the commands specified above) in a single step.
    • The behavior of the generic.CopiedArtifact type of the Generic Model Plugin has been modified in a similar manner. This means all plugins that extend this behavior, e.g. the Tomcat Plugin or the JBossAS plugin for 5.x and 6.x, are also affected by this.

    Prior to XL Deploy 4.0.0, the behavior of the File Plugin and of generic.CopiedArtifact was to copy the file or directory directly to the target path. From XL Deploy 4.0.1 and up, this behavior can be re-enabled by setting the hidden property copyDirectlyToTargetPath to true

    For example, to revert the File Plugin to its pre-4.0.0 behavior, add the following line to the conf/deployit-defaults.properties file and restart the XL Deploy server:



    The kind of the orchestrator property on the udm.DeployedApplication type has been changed from STRING to LIST_OF_STRING, because it is now possible to compose orchestrators. If you have CLI scripts that assign a single String value to this property this will still work, because it will be put into the list as the only element. If you have scripts that depend on reading the value, the script must be changed to expect a list of string when reading the property.

    UI functionality has been moved

    The pause button and the skip button in task execution screen were moved into a context menu on the steps.

    Deprecations in XL Deploy 4.0.0

    The following orchestrators have been deprecated and will be removed in an upcoming (major) release.

    • container-by-container-serial, replaced by the sequential-by-container orchestrator.
    • composite-package, replaced by the sequential-by-composite-package orchestrator.
    • group-based, replaced by the sequential-by-deployment-group orchestrator.

    Upgrading to Deployit 3.9.90

    Java 7

    From this version onwards Deployit will require Java 7 to run. All pre-existing plugins are compatible with this version of Java and it should not be needed to rebuild them.

    Upgrading to Deployit 3.9.5

    Security upgrade

    • Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:
      • Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
      • Change .../spring-security-3.1.xsd to .../spring-security.xsd

    Upgrading to Deployit 3.9.4

    Support for deployment package level properties

    Support for deployment package level properties has been added in Deployit 3.9.4 to make it possible to set values for deployment properties from the udm.DeploymentPackage.

    Support for native Windows WinRM

    Support for the native Windows WinRM implementation, i.e. the winrs command, has been implemented in Deployit 3.9.4 to make the setup of WinRM easier for users running the Deployit server on a Windows platform. The existing Java implementation that is internal to Deployit is still available for users running the Deployit server on Unix or Windows.

    Because of this, the WINRM connection type has been renamed to WINRM_INTERNAL and the new WINRM_NATIVE connection type can be used to select the native Windows WinRM implementation. The WINRM_HTTP and WINRM_HTTPS connection types that were duplicates of the WINRM connection type have been removed.

    Please update any scripts or procedure that create overthere.CifsHost CIs will have to be updated to reflect the new connection types:

    • Replace WINRM with WINRM_INTERNAL.
    • Replace WINRM_HTTP with WINRM_INTERNAL and winrmEnableHttps set to false.
    • Replace WINRM_HTTPS with WINRM_INTERNAL and winrmEnableHttps set to true.

    You do not have to upgrade the contents of your repository. The UpgradeToRemotingPlugin394 upgrader mentioned below will take care of that.

    Automatic repository upgrade

    The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

    • Deployit394Checksums: Deployit 3.9 introduced the checksum property which stores SHA-1 checksums of artifacts. The SHA-1 algorithm in some cases generated too short checksum strings. This upgrader will recalculate all incorrect checksums.
    • UpgradeToRemotingPlugin394: This upgrader converts the connection type properties of all overthere.CifsHost properties in the repository as follows:
      • Replaces WINRM with WINRM_INTERNAL.
      • Replaces WINRM_HTTP with WINRM_INTERNAL and sets winrmEnableHttps to false.
      • Replaces WINRM_HTTPS with WINRM_INTERNAL and sets winrmEnableHttps to true.
      • Replaces WINRS (only available in hotfix versions of Deployit) with WINRM_NATIVE.

    Upgrading to Deployit 3.9.3

    Automatic repository upgrade

    The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

    • Deployit393ReportsView: Deployit 3.9.3 introduces the new global report#view permission to control how is allowed to view the reports tab. This upgrader will grant all roles that have the login permission the report#view permission.

    Upgrading to Deployit 3.9.2


    An autoPrepareDeployeds method has been added to the deployment object in the CLI and the corresponding REST API that works as follows:

    • For an initial deployment without any deployeds, it is identical to a call to generateAllDeployeds.
    • For an initial deployment with at least one deployed, the behavior is as below.
    • For an update deployment, keep existing mappings but:
      • Add mappings for new deployables, if allowed by types and tags.
      • Add mappings for new containers, if allowed by types and tags.
      • Remove mappings for old deployables, without a warning.

    Upgrading to Deployit 3.9.0

    Upgrading plugins

    Plugins provided by XebiaLabs for Deployit version 3.8 will work in Deployit 3.9. There is no need to upgrade plugins when you are upgrading to Deployit 3.9.

    Custom plugins built in Java against the Deployit plugin API will need to take the following change into account:

    • class ReadOnlyRepository returned from the DeploymentPlanningContext.getRepository() call has been replaced by class Repository. The new Repository class provides an extension on the original ReadOnlyRepository class.

    Recompiling the plugin Java source code against the new plugin API should bring your plugin up-to-date.

    Checksum property

    In Deployit 3.9, a new system property called checksum has been introduced on configuration items of type udm.BaseDeployableArtifact. This property influences how Deployit will calculate upgrades of deployments (See: Packaging Manual). If you've previously defined a property called checksum on your configuration items, please rename it to avoid clashes with the newly introduced checksum property.

    Importing (old style manifests)

    On importing it is now possible to pass in a CI-Name for non-artifact configuration items. The behavior for both Artifacts and non-Artifacts is now the same, both will be stored under the CI-Name value if it is given, and fallback to the Manifest entry name Name.

    Upgrading to Deployit 3.8.4


    In versions of Deployit prior to 3.8.4, the envVars property on the generic.Container type of the generic-plugin (and therefore also on the sql.SqlClient type of the database-plugin and its subtypes) was resolved using FreeMarker. From Deployit 3.8.4 onwards this is no longer done as their values should refer to Unix or Windows environment variables which will be resolved by the shell.

    Upgrading to Deployit 3.8.3

    Automatic repository upgrade

    The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

    • Deployit383AclClear: The upgrader that runs when upgrading from a pre-3.7.0 version of Deployit to a version below Deployit 3.9.3 (Deployit37Security, see below) left behind incorrect rep:policy nodes in the repository (DEPLOYITPB-4141). This upgrader removes those nodes.

    Upgrading to Deployit 3.8.0

    Automatic repository upgrade

    The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

    • Deployit38ConfigurationRoot: This upgrader creates the new Configuration root that is supported by Deployit 3.8.0 and up.

    Release Dashboard

    The Release Dashboard feature has changed to make it easy to reuse a deployment pipeline for many applications. A new CI has been introduced, release.DeploymentPipeline which is stored under the new Configuration root node. Each application that should be used in the Release Dashboard can link to the required deployment pipeline.

    When starting Deployit 3.8 for the first time, any deployment pipelines configured in 3.7 will be converted to 3.8 deployment pipeline CIs.

    Placeholder scanning

    Placeholder scanning in archives (EAR, WAR, etc.) is now disabled by default. To enable it, edit deployit-defaults.properties and add the following line:


    Custom Java plugins

    If you have custom Java plugins written against the Deployit 3.7 API, you may need to make some changes to take advantage of the new features in Deployit 3.8.

    Deployit 3.8 has changed the API to manage deployments and tasks. Java plugins that use the UDM Plugin-API from Deployit 3.7 will continue to work using a legacy layer. However, if your Java plugin extends classes from the Generic plugin or Python plugin, you may need to update your Java code, since these plugins now use the new API. Here's a table of replacements (read 'c.x.d.p' as 'com.xebialabs.deployit.plugin')

    Deployit 3.7 Deployit 3.8
    c.x.d.p.api.deployment.execution.Step c.x.d.p.api.flow.Step
    c.x.d.p.api.deployment.execution.Step.Result c.x.d.p.api.flow.StepExitCode
    c.x.d.p.api.deployment.execution.DeploymentStep c.x.d.p.api.flow.Step
    c.x.d.p.api.deployment.execution.DeploymentExecutionContext c.x.d.p.api.flow.ExecutionContext
    c.x.d.p.api.inspection.InspectionExecutionContext c.x.d.p.api.flow.ExecutionContext
    c.x.d.p.api.inspection.InspectionPlanningContext c.x.d.p.api.inspection.InspectionContext
    c.x.d.p.overthere.ExecutionContextOverthereProcessOutputHandler c.x.d.p.overthere.DefaultProcessOutputHandler

    Upgrading to Deployit 3.7.0

    • Deployit 3.7 contains an updated security implementation. Data from a pre-3.7 repository will automatically be converted to the new security model. See the section below for a complete description of the security upgrade.
    • New versions of the following plugins are needed:
      • WAS
      • WLS
      • Tomcat
      • JBoss

    Security upgrade

    Permissions and repository

    Starting with Deployit 3.7, Deployit needs to know the admin user's password to access the repository. This must be entered in the deployit.conf file prior to starting the new Deployit server. Note that the password in the configuration file is encrypted by the Deployit server when it starts.

    The main change in the Deployit 3.7 security model is that local security permissions are stored only on root nodes and core.Directory CIs. During the upgrade, Deployit will convert pre-3.7-style permissions to the new permission system and automatically create directories to attach the relevant permissions to. The server log contains a description of the old security information that was found and how this was translated to the new permission system.

    Permissions in Deployit are now assigned to roles instead of directly to principals. Deployit itself contains the definitions of roles and the principals they map to. Deployit will create a role for every user it finds during the upgrade.

    It is also no longer possible to globally grant certain permissions. Permissions deploy#initial, deploy#upgrade, deploy#undeploy, import#initial, import#upgrade, task#skip_step, task#move_step can now only be granted on a directory CI. Deployit will convert these global permissions into directory permissions during the upgrade.

    Deployit 3.7 no longer allows deny permissions. Instead, permissions should be segregated using the new core.Directory grouping CIs. The deny permissions are not migrated by Deployit and an equivalent configuration must be created manually.

    Permission repo#edit no longer allows deleting of packages. From 3.7 onwards, new permission import#remove is required to be allowed to delete packages.

    In summary, these are the security changes in Deployit 3.7:

    Feature Pre-3.7 3.7 Conversion
    Admin password Deployit did not need the administrator password. Deployit needs the administrator password. The administrator password must be set manually in the deployit.conf file before starting Deployit 3.7.
    Local permissions defined per CI Local permissions can be defined on any CI, if the permission is applicable. Local permissions can only be defined on root nodes or core.Directory CIs. Deployit automatically migrates permissions from pre-3.7 repositories to 3.7, creating new directory CIs as needed.
    Permission assignment Permissions are assigned to users (when using the repository as user store) or LDAP principals (users or groups). Permissions are assigned to roles managed within Deployit. Deployit automatically migrates principals from pre-3.7 repositories to 3.7, creating new roles as needed.
    Permissions that are both global as well as local Several permissions (deploy#initial, deploy#upgrade, deploy#undeploy, import#initial, import#upgrade, task#skip_step, task#move_step) can be assigned both globally as well as locally. These permissions can only be assigned locally on root nodes or directory CIs. Deployit automatically migrates these permissions from pre-3.7 repositories to 3.7.
    deny permissions Permissions can explicitly be denied on any level. Denying permissions is no longer possible. Deployit does not migrate deny permissions. An equivalent security configuration must be created manually after the upgrade.
    Permission to delete packages repo#edit permission allowed deleting of packages. New permission import#remove is introduced to allow deleting of packages. Permission repo#edit is still required to edit CIs. Deployit automatically assigns import#remove to roles that had repo#edit permission in the pre-3.7 repository.


    Configuration of LDAP security has also changed. The configuration in 3.7 is specified in a file called deployit-security.xml. The 3.6-style LDAP configuration in the jackrabbit-jaas.config file can be migrated easily to the 3.7 format. The following table describes the mapping of the 3.6-style LDAP setup to the new 3.7 setup:

    3.6 example 3.7 XML element 3.7 XML properties 3.7 example
    userProvider="ldap://localhost:389/ou=system" security:ldap-server url and root properties <security:ldap-server id="ldapServer" url="ldap://localhost:389/" root="ou=system"/>
    userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))" security:ldap-authentication-provider user-search-filter user-search-filter="(&(uid={0})(objectClass=inetOrgPerson))"
    userSearchBase="dc=example,dc=com" security:ldap-authentication-provider user-search-base user-search-base="dc=example,dc=com"
    groupFilter="(memberUid={USERNAME})" security:ldap-authentication-provider group-search-filter group-search-filter="(memberUid={0})"
    groupSearchBase="ou=groups,dc=example,dc=com" security:ldap-authentication-provider group-search-base group-search-base="ou=groups,dc=example,dc=com"
    java.naming.security.principal="cn=admin,dc=example,dc=com" security:ldap-server manager-dn <security:ldap-server id="ldapServer" url="ldap://localhost:389/" manager-dn="cn=admin,dc=example,dc=com" manager-password="secret"/>
    java.naming.security.credentials="secret" security:ldap-server manager-password <security:ldap-server id="ldapServer" url="ldap://localhost:389/" manager-dn="cn=admin,dc=example,dc=com" manager-password="secret"/>
    useSSL security:ldap-server url Use the LDAPS protocol in the url, for example: <security:ldap-server id="ldapServer" url="ldaps://localhost:686/"/>
    principalProvider=com.xebialabs.deployit.security.LdapPrincipalProvider n/a n/a This element is no longer required.

    See the System Administration Manual for more details on the available LDAP configuration options.

    If you used Deployit 3.6 with LDAP, you will have modified the conf/jackrabbit-repository.xml file. For 3.7, the Security snippet must be:

    <Security appName="Jackrabbit">
            <SecurityManager class="org.apache.jackrabbit.core.DefaultSecurityManager" workspaceName="security" />
            <AccessManager class="org.apache.jackrabbit.core.security.DefaultAccessManager" />
            <LoginModule class="org.apache.jackrabbit.core.security.authentication.DefaultLoginModule">
                    <param name="anonymousId" value="anonymous" />
                    <param name="adminId" value="admin" />

    Additional upgrade steps

    After completing the upgrade procedure described in Upgrading the Server above, perform the following additional steps:

    1. Edit the deployit.conf file and enter the admin password to property admin.password.
    2. If you use LDAP, migrate the LDAP configuration to the deployit-security.xml configuration file.
    3. Create a backup of your repository.
    4. Start the Deployit server. When the server starts, Deployit will migrate the security information from the 3.6 repository to the 3.7 structure. In this process, Deployit will automatically create a role for each user in Deployit as well as special core.Directory CIs to assign permissions to.
    5. Log into Deployit as the admin user and inspect the changes to the repository.
    6. Open the Admin tab to create meaningful role assignments.
    7. Open the Repository tab to create meaningful directory names.

    Completing the migration

    After the Deployit automated upgrade completes, log in to the Deployit GUI with various credentials to ensure that the security setup was correctly migrated. It is now possible to see the security permissions on directory CIs in the Repository Browser.

    Upgrading to Deployit 3.6.0

    • Deployit 3.6 is a drop-in replacement for Deployit 3.5. No repository migration is needed.
    • New versions of the following plugins are needed:
      • WAS plugin
      • WLS plugin

    Upgrading from Deployit 3.0.x or earlier

    Deployit and the plugins were changed extensively in version 3.5. As a consequence, it is not possible to automatically migrate from a 3.0 or earlier version to version 3.5 or later. If you want to perform this type of upgrade, please contact the XebiaLabs support team.