The imquotacheck utility calculates the total mailbox size for each user in the message store. This utility can also compare mailbox size with a user’s assigned quota. As an option, you can email a notification to users who have exceeded a set percentage of their assigned quota. If you perform a user search with imquotacheck, the search is performed against the LDAP directory, not the local mboxlist database. Use the mboxutil -l command to list the message store user accounts.
Requirements: Must be run locally on the Messaging Server.
Dependencies: The delivery agent’s quota warning mechanism needs to be turned off in order for imquotacheck to work, because the imquotacheck and the delivery agent use the same element in the quota database to record last-warn time. To turn off the delivery agent’s quota warning, set store.quotanotification to off.
Location: msg_svr_base/sbin/
The following form of imquotacheck should be used when you want to notify users if they have exceeded a set percentage of their assigned quota.
imquotacheck [-e] [-d domain][-f] [-r rulefile] [-t message template] [-D] -n |
This following form of imquotacheck should be used when you want to report the usage to stdout.
imquotacheck [-e] [-d domain] [-r rulefile] [-t message template] [-i] [-v] [-h] [-u user] [-D] |
The options for this command are:
Option |
Description |
---|---|
-e |
Allows extended reporting. Per folder usage is included in the report. |
-d domain |
Looks for users only in the specified domain. The -i option is implied, so it does not need to be specified. |
-f |
Enforces domain quotas. If the domain is over quota and the maildomainstatus attribute is currently set to active, the value will be reset to overquota, which will prevent mail from being accepted by the message store. If the domain is not over quota and the maildomainstatus attribute is set to overquota, then the value will be changed to active, and mail will be accepted. |
-r rulefile |
Specifies the set of rules to be used when you want to calculate quota usage. If -r is not specified, a default rulefile can be used. To setup a default rulefile, copy the Sample Rulefile to msg_svr_base/config. See Rulefile Format. |
-t message template |
Notifies users when their mailbox quota is exceeded. The message template format is the following:
If -t is not specified, a default message file will be mailed. To setup a default message file, copy the Notification File to msg_svr_base/config. |
-n |
Sends notification messages based on the rules defined in the rulefile. If you do not define any rules when you use this option, you will receive an error. |
-i |
Ignores the rulefile and any active rule defined in it. The quota status of all the users in the message store will be printed to stdout. This option can only be used when you want to report usage. If -i is not specified, the active rule with the least threshold is used to print a list of all of the users and their quota status to stdout. |
-v |
Prints the username, quota, total mailbox size and percentage of mailbox used by all of the users. When you are using imquotacheck to report usage, it will default to this option if no other options are specified. |
-u user |
Obtains the quota status of the specified user id. Can be used with -e for extended reporting on the user. Cannot be used to specify multiple users. |
-D |
Debug mode; displays the execution steps to stdout. |
To send a notification to all users in accordance to the default rulefile:
imquotacheck -n |
To send a notification to all users in accordance to a specified rulefile, myrulefile, and to a specified mail template file, mytemplate.file:
imquotacheck -n -r myrulefile -t mytemplate.file |
To list the usage of all users whose quota exceeds the least threshold in the rulefile:
imquotacheck |
To list the usage of all users and (will ignore the rulefile):
imquotacheck -i |
To list per folder usages for users user1 (will ignore the rulefile):
imquotacheck -u user1 -e |
To only list the users in domain siroe.com:
imquotacheck -d siroe.com |
The rulefile format is organized into two sections: a general section and a rule name section. The general section contains attributes that are common across all rules. Attributes that are typically specified in the general section are the mailQuotaAttribute and the reportMethod. In the rule name section, you can write specific quota rules for notification intervals, trigger percentages, and so on. Attributes that are typically specified in the rule name section are notificationTriggerPercentage, enabled, notificationInterval, and messageFile. Note that the attributes and corresponding values are not case-sensitive. The following rulefile format is used:
[General] mailQuotaAttribute = [value] reportMethod = [value] [rulename1] attrname=[value] attrname=[value] [rulename2] attrname=[value] attrname=[value] [rulename3] attrname=[value] attrname=[value] |
This table shows the attributes, whether they are required, the default value, and the description.
General Attribute |
Required Attribute? |
Default Value |
Description |
---|---|---|---|
mailQuotaAttribute |
No |
Value in quotadb |
Specifies the name of the custom mailquota attribute. If not specified, the value in quotadb is used. |
reportMethod |
No |
Can customize the output of the quota report. The value of this attribute is specified as library-path:function, where library-path is the path of the shared library and function is the name of the report function. See reportMethod Signature to see the structure of the attribute. |
Rule Attribute |
Required Attribute? |
Default Value |
Description |
---|---|---|---|
notificationTriggerPercentage |
Yes |
Specifies the consumed quota percentage that will trigger notification. Value should be unique and an integer. |
|
messageFile |
No |
msg_svr_base/config/imq.msgfile |
Specifies the absolute path to the message file. |
notificationInterval |
Yes |
Indicates the number of hours before a new notification is generated. |
|
enabled |
No |
0 (FALSE) |
Indicates if the particular rule is active. Applicable values are 0 for FALSE and 1 for TRUE. |
notificationMethod |
No |
Can customize the overquota notification method to send to the user. The value of this attribute is specified as library-path:function, where library-path is the path of the shared library and function is the name of the report function. See notificationMethod Signature attribute. |
The following signature can be used for the reportMethod():
int symbol(QuotaInfo* info, char** message, int* freeflag) info is a pointer to the following structure: typedef struct QuotaInfo { const char* username; /* user name (uid or uid@domain) */ long quotakb; /* quota in kbytes */ long quotamsg; /* quota in number of messages */ ulong usagekb; /* total usage in kbytes */ ulong usagemsg; /* total usage in number of messages */ FolderUsage* folderlist; /* folder list (for -e) */ long num_folder; /* number of folders in the folderlist */ long trigger; /* not used */ const char* rule; /* not used */ } typedef struct FolderUsage { const char*foldername; ulong usagekb; /* folder usage in kbytes */ } |
The address, message, points to the output message. The report function is expected to fill the value of *message and allocate memory for message when necessary. The freeflag variable indicates if the caller is responsible for freeing allocated memory for *message.
The return values are 0 for success and 1 for failure.
The imquotacheck function will invoke the reportMethod to generate the report output. If the reportMethod returns 0 and *message is pointing to a valid memory address, message will be printed.
If the *freeflag is set to 1, the caller will free the memory address pointed to by message. If the -e option is specified, the quota usage for every folder will be stored in the folderlist, an array in FolderUsage; the num_folder variable is set to the number of folders in the folderlist.
The following signature can be used for the notificationMethod():
The notification function has the following prototype: int symbol(QuotaInfo* info, char** message, int* freeflag) info is a pointer to the following structure: typedef struct QuotaInfo { const char* username; /* user name (uid or uid@domain) */ long quotakb; /* quota in kbytes */ long quotamsg; /* quota in number of messages */ ulong usagekb; /* total usage in kbytes */ ulong usagemsg; /* total usage in number of messages */ FolderUsage* folderlist; /* folder list (for -e) */ long num_folder; /* number of folders in the folderlist */ long trigger; /* the exceeded notificationTriggerPercentage */ const char* rule; /* rulename that triggered notification */ } typedef struct FolderUsage { const char *foldername; ulong usagekb; /* folder usage in kbytes */ } |
The address, message, points to the notification message. The notification function is expected to fill in the value of this variable and allocate the memory for the message when necessary. The freeflag variable indicates if the caller is responsible for freeing the memory allocated for message.
The return values are 0 for success and 1 for failure.
If the notification function returns a 0, and *message is pointing to a valid address, the imquotacheck utility will deliver the message to the user. If the *freeflag is set to 1, the caller will free the memory address pointed to by message after the message is sent.
If the -e option is specified, the quota usage for every folder will be stored in the folderlist variable, an array of FolderUsage structure; the num_folder variable is set to the number of folders in the folderlist.
If the messageFile attribute is also specified, the attributed messageFile will be ignored.
# # Sample rulefile # [General] mailQuotaAttribute=mailquota reportMethod=/xx/yy/libzz.so:myReportMethod [for Solaris only ] /xx/yy/libzz.sl:myReportMethod [for HP-UX only] \xx\yy\libzz.dll:myReportMethod [for Windows NT only] [rule1] notificationTriggerPercentage=60 enabled=1 notificationInterval=3 notificationMethod=/xx/yy/libzz.so:myNotifyMethod_60 [rule2] notificationTriggerPercentage=80 enabled=1 notificationInterval=2 messageFile=/xx/yy/message.txt [rule3] notificationTriggerPercentage=90 enabled=1 notificationInterval=1 notificationMethod=/xx/yy/libzz.so:myNotifyMethod_90 # # End # |
Rule precedence is determined by increasing trigger percentages.
The highest applicable threshold is used to generate a notification. The time and the rule’s threshold are recorded.
If users move into a higher threshold since their last quota notification, a new notification will be delivered based on the current set of applicable rules. This notice can be immediately delivered to any user whose space usage is steadily increasing.
If usage drops, the notification interval of the current rule (lower threshold) will be used to check the time elapsed since the last notice.
The stored time and threshold for the user will be reset to zero if the user’s mailbox size falls below all of the defined thresholds.
The utility depends on the message file to have at minimum a Subject Header. There should be at least one blank line separating the Subject from the body. The other required headers are generated by the utility. The notification file format is the following:
Subject: [Warning] quota reached for %U% Hello %U%, Your quota: %C% Your current mailbox usage: %M% Your mailbox is now %Q% full. The folders consuming the most space are: %R%. Please clean up unwanted diskspace. Thanks, -Administrator |
Localized versions of imquotacheck notification incorrectly convert the % and the $ signs. To correct the encoding, replace every $ with \24 and replace every % with \25 in the message file.