ZENworks 2017 Upgrade Cookbook

  • 7018169
  • 18-Oct-2016
  • 25-Nov-2020


Novell ZENworks Configuration Management 2017
Novell ZENworks Configuration Management 2017 Migration
Novell ZENworks Configuration Management 2017 System Update
Novell ZENworks Configuration Management 11.4 System Update


This document is assembled, focused to assist in migrating to ZCM v2017 and latest Update.
This example starts at ZCM ZONE version 11.4.x.https://youtu.be/mrJvSNgvSw4
common upgrade/update best practices with HTML links, documents and videos.

Note: Be sure to reference the documentation for your specific environment.


What's New in ZENworks 2017
What's New in ZENworks 2017 Update 1
What's New in ZENworks 2017 Update 2
What's New in ZENworks 2017 Update 3
What's New in ZENworks 2017 Update 4
What's New in ZENworks 2017 Update 4 FRU1a - TID 7023841

Locate downloads through the Micro Focus Trial download siteMicro Focus Customer Portal download site or patches through Patch Finder.
Do not extract .iso’s (
KB 7015386) – the .iso must be “mounted” to a public location.
Perform MD5 on all downloaded files for data integrity.
Make sure any Downloaded/Imported System Update content replication is 100% on all Primary Servers before starting.

ZENworks Control Center
Browser requirements change depending on the ZENworks version.
ZENworks 2017 ZCC changes (see the documentation for the full list):

  • Branding and color scheme
  • Mobile Management added to Navigation pane
  • Mobile Devices, Mobile Policies and iOS/Android Bundles
  • InTune App Management
  • Active Sync to ZCC > Configuration > ActiveSync (Tab)
  • Available System Updates Status displays Downloaded, Prepared, Authorized, Deploying
  • Assignment Optimization
  • Browser Agnostic
  • Database Migration Support for Oracle to MSSQL (U3)
  • Dashboards (U3)
  • ZENworks Reporting - Inventory Domain (U3)
  • FDE added support for Secure Boot (U3)

ZENworks 2017 Licensing
License key from ZCM 11 doesn't carry over.
Log in to the Micro Focus customer care portal for ZENworks 2017 license keys to activate the environment during upgrade.
Note: During the migration if not licensed for the ZENworks 2017 Suite, then all individual "Active" ZENworks Configuration Management component licenses will need to be entered.
You cannot continue with Evaluation options if your zone has a Product or Suite licensed in an Active state.  For more details and clarification see TID 7023323.
See documentation for what the suite consists of when Activating ZENworks Licenses and Product
License States.

2017 Known Issues

  • ZENworks 2017
  • ZENworks 2017 Update1
  • ZENworks 2017 Update2
    • Information and List of Fixes  TID 7023221
    • TID 7022612 - See TID for Impact Details.
      Update2 and Update2a are only differentiated by the update script (and so have different GUID's),
      the update end results for the files and database are the same.
      Note:  Aside from the issue described in this TID, ZENworks 2017 Update 2 and ZENworks 2017 Update 2a builds are functionally identical.
  • ZENworks 2017 Update3
    • Information and List of Fixes  TID 7023221
    • TID 7023380 - See TID for impact details.
      Update3 and Update3a are only differentiated by the update script (and so have different GUID's),
      the update end results or the files and database are the same.
      Note: Aside from the issue described in this TID, ZENworks 2017 Update 3 and ZENworks 2017 Update 3a builds are functionally identical.
  • ZENworks 2017 Update 4
  • ZENworks 2017 Update 4 FTF Roll Up 1a  (FRU1a)
    • ZCM 2017 Update 4 FRU1a is a Fixes only Update for ZCM 2017 Update 4
    • Use ZDC for ZENworks 2017 Update 4 
    • Do not remove ZCM 2017 Update 4 after installing ZCM 2017 Update 4 FRU1a (FRU1a is dependent on Update 4).

Planning and compatibility Guide


  • Important information about the Sybase database platform, if internal use the recommended tool to Move the Sybase Db to PostgreSQL Db or see other options in the ZCM 2017 Db Migration Guide or ZCM 2020 Db Migration Guide.
  • Plan End User communication and downtime.  During Primary Server upgrade to ZEnworks 2017, based on scale of environment, some end users may see disruption on functionalities like; installing apps, user login, content download, etc.
  • Always take a backup of ZENworks Server (or snapshot of Virtual Environment) including databases and other related files (Imaging, TFTP, etc.)
  • Refer to the documentation for the best practices for backing up the ZENworks system and its components (certificates, database, file system, imaging configuration files, etc)
  • Zones must be upgraded to ZCM v11.4.0 minimum before upgrading to ZENworks 2017.
  • Using the ZENworks 2017 installation media, the zone can directly be upgraded to ZENworks 2017 if the zone is currently ZENworks 11 SP4 (11.4.0) or later.
  • Windows Primary Servers must be at Windows 2012 Server OS minimum (Windows Server 2008 R2 is no longer supported in ZENworks 2017).
  • Micro Focus has tested upgrading Windows Server 2008 to 2012 prior to migrating ZENworks from v11.4.x to ZENworks 2017.
    Note: While there were not any ZCM related issues performing an in-place OS upgrade from 2008R2 to 2012, however it does pose a risk and Micro Focus cannot ensure the OS itself will upgrade cleanly.
  • Do not Upgrade to Windows Server 2016 OS prior to ZENworks 2017 migration, since Windows Server 2016 OS is not supported on ZCM v11.4.x.
  • SLES v12 requires libXtst6-32bit-1.2.2-3.60.x86_64.rpm installed prior to ZENworks install.  (This rpm can be found on the corresponding media for the installed OS version)
  • Known issues after in-place upgrade of the Linux OS with ZENworks installed.
  • Make sure there is disk space available to do the migration: 20Gb+ for Appliance, and 20Gb+ for physical/VM.
  • VM RAM should be dedicated and not dynamic.
  • Make sure Upgrade is "Success" on the Primary before moving to the next step.
  • Firewall settings and network TCP and UDP ports reviewed and Anti-Virus exclusions updated TID 7007545
  • ARSO changes in Windows 10 Fall Creators Update (Build 1709) reference TID 7022379 (fixed in 2017 Update 2).
  • If older Primary Servers do not meet ZCM 2017 Requirements (see Additional Information below) and consult the Disaster Recovery Documentation re: Replacing Primary Servers
  • Make sure Roles, Dedicated Server settings and Locations have proper server configurations.
  • When doing System Updates make sure SU Replication Status is 100% for all Pri's and Sats.
  • If using ZENworks Full Disk Encryption prior to ZCM 2017 U1, be sure to unencrypt the agent prior to upgrading the Agent to ZCM 2017 U1 or higher.  Once on ZCM 2017 U1 create a new Encryption policy for device reencryption. (See ZAA section below for more details and links)
  • LDAP Connection to User Source must be a username w/ReadOnly to the entire directory where users exist (AD) or replica (eDir)

ZENworks 2017 Appliance

ZENworks 2017 Appliance Deployment
ZENworks 2017 Appliance Configuration
ZENworks 2017 Appliance Management Console

  • Backup ZENworks 11 SP4 System Appliance, and any external content repository (attached volumes or disks), system files, certificates and databases.
  • Run zman zenserver-backup (zsb) command to save zone critical data.
  • If a restore is necessary, revert both the appliance and the database.
  • See a tour of the Appliance Administration Console in the video links below.

Migration from Appliance to Appliance
Be sure to follow the step by step process in the ZENworks 2017 Appliance Migration documentation.

  1. ZENworks 11 SP4 Appliance - After powering down the 11 SP4 Appliance, detach the virtual disk (VAStorage volume)
  2. Make a copy of the VAStorage volume placing the copy into the ZENworks 2017 VM file location
  3. ZENworks 2017 Appliance - Add the copied VAStorage volume as an additional hard disk onto the ZENworks 2017 Appliance (prior to powering on of the 2017 appliance).
  • Snapshot or backup ZENworks 2017 appliance prior to powering it on.
Migration from ZCM 2017 installed on Windows or Linux OS to ZCM 2017 Appliance
ZCM Database Requirements
Database Requirements ZENworks 2017
Database Maintenance and User Schema Rights
If internal database consider the Embedded Database Maintenance Section of the documentation. 
When needing to move the embedded database consider moving the Internal Sybase Database to another Primary Server
Internal PostgreSQL on ZCM 2017 U0 is experimental and ZDC/ZMAN DB will fail.
Internal PostgreSQL database commands TID 7024768

On a ZENworks 2017 Zone where the Sybase database migration is to occur, use the proper ZDC version and run zdc on each database separately using only the db parameters.
  • zdc verify -v zendatabase -b data/<Filename>.zdc
  • zdc verify -v auditdatabase -b data/<Filename>.zdc
If external database:
  • Check requirements necessary for db space, db version and OS versioning.
  • Have the external database server name/IP, dbname for ZENworks and Audit databases and username/pw of who can modify the database (Read/Write)
If using Oracle Database: Check Database Requirement details if planning on using Oracle RAC.
Caution: Oracle Partitioning may be used for ZCM during the upgrade process if this feature is on (even if Oracle Partitioning is not purchased).

If moving to a new database server (upgrading, replacing or moving to another vendor), and/or new database user/pw, check the Database Management Reference Guide for accurate communication settings.
(or TID 7023412)
  • dmmappings.properties
  • dmaccounts.properties
  • zenaudit_dmaccounts.properties
  • zdm.xml
  • zenaudit.xml
DB Migration tool can be downloaded from your Customer Care Portal under ZENworks Suite or ZENworks Configuration Management download:
  • Sybase to PostgeSQL (db-migration-tool-1,0,zip or higher)
  • MSSQL to PostgreSQL  (db-migration-tool-2.0.zip or higher)
  • Oracle to PostgreSQL (db-migration-tool-3.0 or higher)

ZENworks Diagnostic Center
Running ZDC is a best practice, be sure to select the proper ZDC version.
ZDC's are published for every version, Service Pack (and subrev) found on Micro Focus download site or patch finder site. (2017 Update4 FRU1 is the exception)
Locate use of this utility in the ZENworks Command Line Reference Guide.
ZDC should be run on EVERY primary server prior to start of the upgrade to verify system files, database connections (zenworks and audit) and content. 
ZDC for ZENworks 2017 on the .iso Common\tools\zdc or the Micro Focus download portal:
ZDC for v11.4.0ZDC for v11.4.1ZDC for v11.4.2ZDC for v11.4.3
ZDC for v2017 Update 4
ZDC for v2017 Update 4 FRU1 use the zdc on the ZCM 2020 .iso (

If there are ZDC failures like inconsistencies, mismatches or missing files, check the knowledge base (or support for analysis) before upgrading.
Note: Please provide details of the zone version and database type along with the ZDC reports to expedite the request.
Because Embedded PostgreSQL is experimental for ZCM 2017 early releases, ZCM 2017 U0 & ZCM 2017 U1 Only - will fail ZDC.

ZENworks Adaptive Agents (ZAA)
Managed device requirements for new ZAA installs.
Managed device prerequisites for ZAA updates (including Satellites).
Supported ZAA versions for agents/satellites to receive cumulative update.
Read the system requirements carefully for the OS to be upgraded.  (Common OS's like XP, Vista, SLES11 SP2 managed but not supported in ZCM v2017.)
Example: Managed devices with ZAA v11.2.x can be directly upgraded to ZAA v2017, after your system primaries and satellites are at ZCM v2017.
ZAA managed devices can only use the available features that the ZAA version installed supports. 
e.g., Managed devices using v11.2.1 will not be using ZAPP (introduced in ZCM v2017)
Full Disk Encryption is on the Managed device, consult the ZENworks 2017 Update 1 - Full Disk Encryption Update Reference for process of upgrading those agents.
    Old FDE Policy must be removed prior to upgrading to ZENworks 2017 Update 1, decrypting the drive.
    Then upgrade the ZAA and apply a New 2017 Update1 FDE Policy.
Prior to installing or updating the ZENworks Adaptive Agent (ZAA) v2017 ensure:
  • ZAA version 11.x or higher must be installed
  • Microsoft .NET 4.5 Framework version (or higher) is installed and running on the Windows managed device.
    With the ZENworks 2017 new branding, the system tray icon changes  and can be modified in ZCC (ZCC > Configuration > System Update Agent > Update Watcher Icons)
    NOTE: Managed devices with the XP OS, can be managed in 2017 Zone using the older ZAA, however ZENworks 2017 ZAA is not supported on XP OS.
    NOTE: Upgrade the unsupported OS to a supported OS prior to deploying the ZAA.

Start of Zone Migrations

Upgrade process from v11.4.x to ZENworks 2017

ZENworks 2017 Precheck - Example Zone currently at ZCM 11.4.x
  • Run ZENworks Diagnostic Center (ZDC) for current ZONE version to verify integrity of system files, database inconsistencies, mismatches or missing files
  • Verify System Requirements
  • Snapshot or Backup ZCM Server(s), databases, system files, certificates, PXE imaging menu files and TFTP directories
  • Run zman zenserver-backup (zsb) command to save zone critical data.
  • Turn off Anti-virus and Windows Updates services if applicable
  • Verify prerequisites completed (rpms for Appliance and SLES12)
  • Make sure there is disk space available to do the migration: 15Gb+ for Appliance, and 20Gb+ for physical/VM.
  • Make sure Upgrade is "Success" on the Primary before moving to the next step.
  • Start the Upgrade Process
Migrate to ZENworks 2017 Reminders
  • Have the ZENworks 2017 Entitlement License available from customer portal prior to start.
  • Compatibility Check at beginning of Installation wizard may warn if unsupported managed devices are in the ZONE
    (e.g. SLES 11 SP2, XP, Vista, however these can be managed in 2017 zone with their older ZAA.)
  • (Conditional) if migrating an appliance detach the content storage volume (VAStorage) from v11.4.x, add to ZENworks 2017 prior to 2017 VM startup
  • Start the Upgrade Process
Post Upgrade Tasks
  • Verify updated files and database integrity by running ZDC for v2017
  • Verify all services are running
  • Update to the latest ZENworks 2017 Update after all Primary and Satellite Servers are Successfully Upgraded to ZCM 2017.
  • (Conditional) Add additional external content disks
  • (Conditional) Appliance migration configure NTP settings (NTP is not migrated)
  • (Conditional) Imaging re-upload the Tuxera Drivers and MDT Tools
  • (Conditional) Appliance & Patch Management enabled see TID 7018582
  • (Conditional) Appliance & Embedded Audit Database - Port 2639 not open - TID 7022432

Always reference the documentation, knowledgebase and/or call ZENworks Technical Support if experiencing issues.

Documentation References
ZENworks 2017 Documentation
ZENworks 2017 Update 1 Information TID 7020155

Video References
How To Migrate to Micro Focus ZENworks 2017
HowTo Migrate an Appliance with Micro Focus ZENworks 2017
What's New in ZENworks 2017 Update 2 - Mobile Enhancement (Webinar)
Micro Focus ZENworks Youtube Channel
More Video References in the ZCM 2017 documentation (Anywhere you see the Video Symbol , and more at bottom of page)

Documentation References
ZENworks Configuration Management v2017 Documentation

Other Versions
ZCM 11 Upgrade Cookbook

Additional Information

ZENworks 2017 server upgrade scenarios:
  1. Add to the ZONE, a supported OS platform (or Appliance) as primary server(s) before upgrading, migrating details and decommissioning unsupported OS.
  2. Move the ZONE to other primaries with supported OS platform through disaster recovery process
  3. Create a new ZONE with supported OS platform and configure ZONE subscribe and sharing feature to move the content
  4. Migrate the unsupported OS platform to an Appliance then upgrade the Appliance
  5. Upgrade the OS platform to a supported platform (for both ZCM 11 and ZCM 2017) before upgrading
    (This method NOT Supported with upgrading Linux OS major releases prior to upgrade-Example: SLES 11 > SLES 12)

  6. Be sure to reference ZCM Upgrade System Requirements and Disaster Recovery Documentation
Each scenario has their own set of challenges, refer to the documentation that pertains to your environment.

Considerations for unsupported OS Primaries before decommissioning:
  • Move key zcm components/roles off unsupported primaries
  • Add v11.4 appliances to the zone and upgrade to v11.4.3
  • Allow time for replication to process
  • Manually move images and image menu files
  • Check CA certificate configuration, if internal certificates, then migrate the CA role using ZCC to an Appliance or other supported primary
  • If external certificates, create new certificates for the new servers
  • Check Database configuration for the MasterPrimary Role if on unsupported platform, move the role
  • If using the internal Sybase database - move it to another server or Appliance or migrate to an external database
  • Add the appliances to the closest server rules (configuration location) and remove unsupported primaries from list(s)
  • Once ZCM system is running as expected - turn off unsupported primaries for a time before decommissioning
  • Decommission unsupported primaries
    (Conditional-When decommissioning unsupported primaries check if they hold Primary Server configurations below)

Considerations for replacing Satellites before decommissioning

  • Verify Default Server Rules are in place and all devices refreshed
  • Verify new Satellites have proper Location Server Configurations (especially if Exclude is set!)
  • Verify new Satellites have proper User Source Configured
  • Make sure all Satellites in that location are replicated with content (bundles/policies/images/tftp)

Other Primary Server configurations considerations

  • If you are new to ZCM 2017 be aware that ZAPP is the new NAL. 
    If you launched the previously known NAL window or using NAL as a Shell, check out the ZAPP documentation and  TID 7022369
  • ZONE Sharing Subscription Server
  • Preboot Services - TFTP Replication Server
  • Centralized Message Logging - Preferred Maintenance Server
  • If moving managed devices to new zone see TID 7000620 for additional details.
  • Closest Server Default Rules and/or Location & Network Environment Settings
  • Assignment Optimization - Dedicated Server (2017)
  • Audit Management - Audit Purge Server
  • Patch Management - Subscription Service Server
  • Apple Push Notification - MDM Server (2017)
  • Telemetry - Collection server
  • Online Updates Registration fails 500 see TID 7018622
  • Running Online Updates gives a Update Message Problem for vabase - see TID 7023186
  • Cleaning up older ZCM System Updates, leave at least one prior version behind in case of dependencies.
    NOTE: ZCM 2017 U4 FRU1 is not a system update but a set of patches and is dependent on ZCM 2017 U4.