imquotacheck
The imquotacheck utility administers user quotas and domain quotas 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.
The imquotacheck utility lists users in the local mboxlist database. To list users in the LDAP directory, use the imquotacheck -a option.
Requirements: Must be run locally on the Messaging Server.
Location: msg-svr-base/sbin/
Syntax
To report quota and usage information to stdout:
imquotacheck [-u user | -d domain] [-a] |
To enforce a domain quota:
imquotacheck -f [-d domain] |
To notify users when they have exceeded a set percentage of their assigned quota (to deliver over-quota notification messages):
imquotacheck -n [-D] [-d domain] [-r rulefile] [-t message template] |
Options
The options for this command are:
|
Option |
Description |
|---|---|
|
-a |
Lists users in the LDAP directory. If the -a option is not used, imquotacheck lists users in the message store (the local mboxlist database). |
|
-d domain |
Searches for users only in the specified domain. When used with the -f option, the -d domain option enforces quotas for the specified domain. When used with the -n option, the -d domain option delivers over-quota notifications for users in the specified domain. |
|
-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. |
|
-h |
Displays help for this command. |
|
-n |
Sends notification messages based on the rules defined in the rulefile. If you do not define any rules with the -r option when you use the -n option, the default rulefile is used. If you have not set up a default rulefile and you do not define any rules when you use the -n option, you will receive an error. The delivery agent’s quota warning mechanism needs to be turned off in order for the imquotacheck -n command 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. |
|
-r rulefile |
Specifies the set of rules to be used when you want to calculate quota usage. This option is used with the -n option. If -r is not specified, a default rulefile can be used. To set up a default rulefile, copy the Sample Rulefile to msg-svr-base/config/imq.rulefile. See Rulefile Format. |
|
-t message template |
Notifies users when their mailbox quota is exceeded. This option is used with the -n option. 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. |
|
-u user |
Obtains the quota status of the specified user id. Cannot be used to specify multiple users. |
|
-D |
Debug mode; displays the execution steps to stdout. |
Examples
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 enforce the domain quota for the siroe.com domain:
imquotacheck -f -d siroe.com |
To list the usage of all users whose quota exceeds the least threshold in the rulefile:
imquotacheck |
To list per folder usages for user user1:
imquotacheck -u user1 |
To only list the users in domain siroe.com:
imquotacheck -d siroe.com |
Rulefile Format
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. |
reportMethod Signature
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.
notificationMethod Signature
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.
Note –
If the messageFile attribute is also specified, the attributed messageFile will be ignored.
Sample Rulefile
In the sample rulefile, the following files libzz.so, libzz.sl, and libzz.dll are library files. The /xx/yy are directory paths that should be replaced by the relative paths to where these library files are located on the server.
# # 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 # |
Threshold Notification Algorithm
-
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.
Notification File
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 |
Note –
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.
- © 2010, Oracle Corporation and/or its affiliates