Page tree
Skip to end of metadata
Go to start of metadata

This page contains a few hints how best to upgrade to Z-Push 2.3.

We assume that you've installed Z-Push from the packages, so the commands like z-push-admin are correctly installed by the packages.

If you installed from source or from GIT all of this still applies, but you need to adjust the command names slightly and run them from your z-push directory.

Upgrade from Z-Push 2.0.x or Z-Push 2.1.x

We have actually not tested this upgrade path and had no feedback from users so far. In general, we recommend that you upgrade to Z-Push 2.2.x (latest) first and in a later step upgrade to Z-Push 2.3.

Upgrade from Z-Push 2.2.x

It's not relevant from which Z-Push 2.2.x version you upgrade. You could upgrade from e.g. 2.2.3 to 2.3 directly.

Please use the repositories as described on the Installation page.

Upgrade from Tar archive to packages

While it is theoretically possible to just install the new packages on top of the old tar based installation, we recommend to remove the old z-push directory and any manually added Apache configuration before installing the packages. States and logfiles can remain as they are and will be reused (as long as the default paths are used for them).

Fix states

The most important step is to execute "z-push-admin -a fixstates" once after you upgrade, so your states are compatible with Z-Push 2.3.

After installing Z-Push 2.3 from the repository and packages you can simply execute as root on your command line:

z-push-admin -a fixstates

This should only take a couple of seconds or one minute or two if you have many devices and states.

Re-synchronizing all devices

For better compatibility (especially related to Outlook 2013+) we introduced a new type of folder ids that are shorter than the ones used before.

To deploy these new ids to the devices a full re-synchronization is required. This means, that the data on the mobile will be deleted completely and all data will be synchronized from the server again. Depending on the volume of devices and the data stored on them, this can generate significant load on your systems.

It's not required to re-synchronize immediately. All devices synchronized with Z-Push 2.2.x will continue working normally with Z-Push 2.3. Only some very special features will not be available. These features are related to Outlook, so if you already have Outlook connected we recommend that you re-synchronize these profiles first.

The re-sync can be done:

  • at once by deleting all the state files.
    Deleting all states at once is not recommended on systems with more than a couple of devices connected (5 or 10). When dropping the state directory all connected devices will start to re-synchronize immediately. This will cause a very high load on your servers. 
    If you only have a few devices you could still do this. The load will be over in a short period of time.

  • by re-synchronize devices one-by-one or in batches of e.g. 5 or 10 devices. This is a manual process. 
    A device is re-synchronized by executing on the command line:
        z-push-admin -a resync -u <username> -d <deviceid>

Attention Blackberry 10 and Outlook users

Our tests have shown that a server side resync as described here is not enough for BB10 devices and Outlook 2013+ to work reliably. You need to remove and re-create the profile on these devices. 
BB seems to cache old folderids which causes sync inconsistencies.


  1. remove profile from BB/Outlook
  2. remove state on server
  3. create the profile again. 

Existing Blackberry/Outlook profiles will work normally with 2.3.0, but at some point they should be re-synchronized & re-created.

This is especially recommended for Outlook, as several improvements require the new schema.


Find devices with old profiles via z-push-admin

To see which devices still need to be re-synchronized, you can execute:

z-push-admin -a lastsync

This will return a list of devices and users, indicating which already have short folder ids (aka were fully synchronized with Z-Push 2.3) and which don't have them (older profiles).

Output of "z-push-admin -a lastsync"
All known devices and users and their last synchronization time

Device id                           Synchronized user              Last sync time      Short Ids
1stde4ac5c99480f89a96db4ac3ec15a    user1                          never               No
2nded42161ea44cd8603bde692120d6e    user2                          2015-05-21 21:20    No
3rd1c9277a934f188fb81a05045743df    user3                          2016-05-21 01:03    Yes

The first device was either never fully synchronized or a "resync" was already requested. The "resync" command resets the "Last sync time" of the device, so it shows "never" afterwards.

If it stays at "never" this indicates that the device did not connect itself to the server since the re-sync was requested.

For detailed instructions how to use z-push-admin to see e.g. details of a device, see Tools: z-push-admin.

Re-synchronize a device

To request the re-synchronization of a device (e.g. from user2), execute:

z-push-admin -a resync -u user2 -d 2nded42161ea44cd8603bde692120d6e

After requesting a resync you can monitor the progress of the synchronization by executing "z-push-admin -a list" as shown above.

This will give you an indicating how long such a re-sync takes and how much load it generates.


Re-synchronize a batch of devices

To get through the list of devices that need to be re-synchronized easier, you can also request a resync in batches, like with this command:

z-push-admin -a lastsync | grep -v never | fgrep " No" | head -n5 | awk -F' ' '{ system("z-push-admin -a resync -d " $1 " -u " $2) }'

It will get the list of devices, remove all devices with last sync time "never", look at the ones that have no short ids, limit the amount to 5 and then execute z-push-admin -a resync for them. To change the command to e.g. resync 10 devices at once, change the "-n" parameter of the head command.

For a large amount of devices you could e.g. execute that via a cron job, once every hour at night or over the weekend to distribute the load in a way your systems and users are not affected too much.

  • No labels