-
Notifications
You must be signed in to change notification settings - Fork 46
Tools ‐ z push admin
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.
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.
There are several actions for z-push-admin.
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.
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).
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.
Attention
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.
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.
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: email Re-synchronizes all email folders. calendar Re-synchronizes all calendar folders. contact Re-synchronizes all contact folders. task Re-synchronizes all task folders. note Re-synchronizes all note folders. hierarchy Causes 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. gab Re-synchronizes the Global Address Book of a Kopano Outlook Extension.
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.
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.
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.
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).
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.
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.
It's possible to use the command to perform special (e.g. periodical tasks).
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!
Script for adding shared folders contributed by coffee_is_life: https://forum.kopano.io/topic/1169/script-for-adding-shared-folders/