z-push-admin is a tool which allows you to get information about configured devices, users and details about each device.

If Z-Push is installed via the packages or the tools are linked during the installation, it can be called via z-push-admin as root from the command line.

If this was not done, call it from the z-push base directory using ./z-push-admin.php

Some of the described actions are available since Z-Push 2.3.0.

 

General instruction

When calling z-push-admin directly, it will print the possible actions:

root@www:~# z-push-admin
Usage:
	z-push-admin.php -a ACTION [options]

Parameters:
	-a list/lastsync/wipe/remove/resync/clearloop/fixstates/addshared/removeshared/listshares
	[-u] username
	[-d] deviceid
	[-t] type	the following types are available: 'email', 'calendar', 'contact', 'task', 'note', 'hierarchy' of 'gab' (for KOE) or a folder id.
	[--shared|-s]	show detailed information about shared folders of a user in list.
	[--days-old] n	show or remove profiles older than n days with lastsync or remove. n must be a positive integer.

Actions:
	list					 Lists all devices and synchronized users.
	list -u USER				 Lists all devices of user USER.
	list -d DEVICE				 Lists all users of device DEVICE.
	lastsync				 Lists all devices and synchronized users and the last synchronization time.
	wipe -u USER				 Remote wipes all devices of user USER.
	wipe -d DEVICE				 Remote wipes device DEVICE.
	wipe -u USER -d DEVICE			 Remote wipes device DEVICE of user USER.
	remove -u USER				 Removes all state data of all devices of user USER.
	remove -d DEVICE			 Removes all state data of all users synchronized on device DEVICE.
	remove -u USER -d DEVICE		 Removes all related state data of device DEVICE of user USER.
	resync -u USER -d DEVICE		 Resynchronizes all data of device DEVICE of user USER.
	resync -t TYPE 				 Resynchronizes all folders of type (possible values above) for all devices and users.
	resync -t TYPE -u USER 			 Resynchronizes all folders of type (possible values above) for the user USER.
	resync -t TYPE -u USER -d DEVICE	 Resynchronizes all folders of type (possible values above) for a specified device and user.
	resync -t FOLDERID -u USER		 Resynchronize the specified folder id only. The USER should be specified for better performance.
	resync -t hierarchy -u USER -d DEVICE	 Resynchronize the folder hierarchy data for an optional USER and optional DEVICE.
	clearloop				 Clears system wide loop detection data.
	clearloop -d DEVICE -u USER		 Clears all loop detection data of a device DEVICE and an optional user USER.
	fixstates				 Checks the states for integrity and fixes potential issues.

	addshared -u USER -d DEVICE -n FOLDERNAME -o STORE -t TYPE -f FOLDERID -g FLAGS
						 Adds a shared folder for a user.
						 USER is required. If no DEVICE is given, the shared folder will be added to all of the devices of the user.
						 FOLDERNAME the name of the shared folder. STORE - where this folder is located, e.g. "SYSTEM" (for public folder) or a username.
						 TYPE is the folder type of the shared folder (possible values above, except 'hierarchy' and 'gab').
						 FOLDERID is the id of shared folder.
						 FLAGS is optional (default: '0'). Make sure you separate -g and value with "=", e.g. -g=4.
						 Possible values for FLAGS: 0(none), 1 (Send-As from this folder), 4 (show calendar reminders for this folder), 5 (combination of Send-as and calendar reminders).
	removeshared -u USER -d DEVICE -f FOLDERID
						 Removes a shared folder for a user.
						 USER is required. If no DEVICE is given, the shared folder will be removed from all of the devices of the user.
						 FOLDERID is the id of shared folder.


	listshares -o STORE -f FOLDERID
 						 Lists opened shared folders and who opened them on which device.
						 STORE and FOLDERID are optional. If they're not provided then the script will display all open shares.
						 STORE - whose shared folders to list, e.g. "SYSTEM" (for public folders) or a username.
						 FOLDERID - list who opened the shared folder.
						 If both STORE and FOLDERID are provided the script will only list who opened the folder ignoring the STORE parameter.

The -a (action) must always be set. Each action can take several other parameters that are described on this page.

Actions

There are several actions for z-push-admin.

Action: list

This will list the known devices and users on the system.

root@www:~# z-push-admin -a list
 
All synchronized devices

Device id                           Synchronized users
-----------------------------------------------------
1d3de4ac5c99480f89a96db4ac3ec15a    user1
bb2ab63a8f                          user1
appl36028yabg2s                     user2,user3
7721c9277a934f188fb81a05045743df    user3
uqh79eqfsh2ch3usfmdvueu2vg          user4
3e7f1223340d4fd7a19e36c51f42fa67    user5

It shows a list of all device ids and users that have a profile on this device. The deviceid is a unique id which identifies the device. Further actions can be done for this particular device. This id is expected for the -d parameter.

Sometimes it's possible to determine the device type from its id, e.g. bb2ab63a8f is a Blackberry 10 device, while appl36028yabg2s is an iOS device.

If there are several usernames for one device id, this means that there are several ActiveSync profiles on the device, like in the case of the apple device, there are accounts for user2 and user3.

 

If -u or/and -d are passed to the list command, it will show the details of the determined user and/or device.

root@www:~# z-push-admin -a list -d 1d3de4ac5c99480f89a96db4ac3ec15a
Synchronized by user: user1
-----------------------------------------------------
DeviceId:               1d3de4ac5c99480f89a96db4ac3ec15a
Device type:            WindowsOutlook
UserAgent:              Outlook/16.0 (16.0.6868.6525; C2R; x86)
ActiveSync version:     14.0
First sync:             2016-05-27 02:27
Last sync:              2016-05-28 18:22
Total folders:          27
Short folder Ids:       Yes
Synchronized folders:   22
Synchronized data:      Emails(15) Contacts Calendars(2) Notes(2) Tasks GAB
Status:                 Not available
WipeRequest on:         not set
WipeRequest by:         not set
Wiped on:               not set
Policy name:            default
Kopano Outlook Extension:
        Version:        1.0.1
        Build:          f6131e053a171597275e21d19097f1ab4774af5a
        Build Date:     2016-05-18 21:03
Attention needed:       No errors known

If there are several users configured on the same device, you will see several blocks of the above. Same occurs if you request the list for a user (with -u) and the user uses several devices.

Action: lastsync

This is simular to the list command but will return additional information. The lastsync action will return a list of devices and users, indicating when they synchronized the last time, which already have short folder ids (aka were synchronized with Z-Push 2.3) and which don't have them (older profiles).

More information on shortids in the upgrade manual of 2.3.

root@www:~# 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
2nded42161ea44cd8603bde692120d6e    user4                          2015-05-25 11:03    Yes
3rd1c9277a934f188fb81a05045743df    user3                          2016-05-21 01:03    Yes

For the second device id is listed twice, as two users have a profile on the same device. The last sync time indicates when changes were sent to the device for the last time. If it is displayed as never the device did never complete the synchronization cycle or a resync was requested for this device but the device did not connect again to perfom this action (or was unable to perform).

Action: wipe

Executes a remote wipe on the device, equivalent to a factory reset. The remote wipe is just an ActiveSync policy. The wipe itself is executed by the ActiveSync software used on the device. Native apps perform a factory reset while 3rd party ActiveSync applications (like TouchDown or RoadSync) only drop the ActiveSync profile, not affecting other settings on the mobile.

ALL DATA WILL BE LOST, including unrelated pim data, like pictures, WiFi passwords, installed apps and the data of these apps. The device will potentially "become a brick" and needs to be fully setup and activated to work again.

If -u is set, all devices of this user will be wiped when they try to connect the next time.

 

If -d is set the specific device will be reset, independently which users are configured for it.

If a wiped device is to be used with Z-Push again, the device needs to be removed (action remove) from z-push, else it will wipe again.

The list action will show details of the execution of the remote wipe.

Action: remove

Removes all state information for a user or device. Removing the states and the device will be seen from Z-Push as a completely new device.

A remove must be performed if a remote wipe was requested (or executed) for a device. Without the remove the device will be wiped again on next connection attempt.

After the remove command the device will not be known to Z-Push anymore and not be listed in e.g. the list action. If the device connects again, the states are recreated and it appears again in the list.

Action: resync

The resync action takes a variaty of settings. It's recommended to always provider -d and -u to limit the effect (unless you know exactly what you are doing).

-d     resynchronizes the entire device, with all configured profiles on it

-u     re-synchronizes all devices of the user

-t     re-synchronizes a certain type of folder

The "type" can be:

TypeResult
emailRe-synchronizes all email folders.
calendarRe-synchronizes all calendar folders.
contactRe-synchronizes all contact folders.
taskRe-synchronizes all task folders.
noteRe-synchronizes all note folders.
hierarchyCauses the hierarchy to be synchronized again. This updates the list of folders sent to the device. This does normally not trigger a full resynchronization of the device, only if the folderlist changed totally.
gabRe-synchronizes the Global Address Book of a Kopano Outlook Extension.
<folderid>

Re-synchronizes a specific folder for a user on a device.

It accepts values like:

  • 5a37a3f4faa340e49f5c0dc09cf6cb04470900000000
  • U9a350

If no -d and -u flags are specified and e.g. the type -t task is set, Z-Push will re-synchronize all task folders of all users on all devices. This can lead to a big amount on load on your servers.

Action: clearloop

In certain cases Z-Push enters the loop-detection-mode. The amount of items sent to the device is lowered to ensure synchronization under difficult circumstances (e.g. unstable connections) or when data is corrupted and not being accepted by the device. Detailed information about the Loop Detection here.

To force Z-Push to exit the loop detection mechanism, the clearloop action can be used.

If the anormal situation that caused the start of the loop detection is encountered again, loop detection will start again, even after the clearloop action was just executed.

Action: fixstates

The fixstates action will loop through all states and check if cross linking between e.g. devices and users are up to date. It will also drop potentially "left overs" from previous devices and users that were removed.

In Z-Push 2.3 a new meta state for the hierarchy was introduced, which is not available on 2.2.x profiles. In the upgrade process and the call of fixstates this meta state is created.

In general the execution of fixstates should only take a couple of seconds or one minute or two depending on the amount of devices and states on the system.

Action: addshared

Adds a shared folder for a user. This action requires several parameters to be set:

-u username a user the shared folder will be added for. If no deviceid is specified, the shared folder will be added to all devices of the user. If it's necessary to add a shared folder for all users, add it in the z-push.conf.php file.

-n foldername the name for the shared folder. If the foldername contains spaces, it might be necessary to quote them: "Folder\ with\ spaces" (please note the backslashes before the space character).

-o store where the folder is located. For public folders use SYSTEM, otherwise the username.

-t type folder type. For possible values see Action: resync (except 'hierarchy' and 'gab').

-f folderid the id of the shared folder.

-d deviceid (optional) - the shared folder will be added for the specific device.

-g flags (optional) - possible values for FLAGS: 0 (none), 1 (Send-As from this folder), 4 (show calendar reminders for this folder), 5 (combination of Send-as and calendar reminders).

Action: removeshared

Removes a shared folder for a user. This action requires several parameters to be set:

-u username a user the shared folder will be removed for. If no deviceid is specified, the shared folder will be removed to all devices of the user.

-f folderid the id of the shared folder.

-d deviceid (optional) - the shared folder will be removed for the specific device.

Action: listshares (available since Z-Push 2.4.3)

Lists opened shared folder and who opened them on which device. The STORE and FOLDERID parameters are optional. Without parameters listshares will list the opened folders over all stores.

-o STORE whose shared folders to list, e.g. "SYSTEM" (for public folders) or a username.

-f FOLDERID list who opened the shared folder with the provided id.

If both STORE and FOLDERID are provided the script will only list who opened the folder ignoring the STORE parameter.

Scripting

It's possible to use the command to perform special (e.g. periodical tasks). 


Re-synchronize a batch of devices with long folderids

To be fully Z-Push 2.3 compatible all devices should be re-synchronized to use short folderids. More details in the Upgrade manual to 2.3.

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.

 

Many other cases are possible, e.g. periodically remove all devices that have not connected in the last 3 months. 

Please share and contribute your scripts and command lines!

Contributions

Script for adding shared folders contributed by coffee_is_life: https://forum.kopano.io/topic/1169/script-for-adding-shared-folders/