Configuration files for notifications in File Server Resource Manager

You must use a configuration file when creating notifications for quotas and file screens by using the command-line tools for File Server Resource Manager. This configuration file includes the necessary information to create the notification, such as the e-mail addresses and the message in an e-mail notification, or the commands to run for a command notification.

This topic describes the syntax that you must follow when creating a configuration file for quota or file screen notifications. For examples of configuration files for notifications, see Examples.

Important
To send e-mail notifications and storage reports over e-mail, you must first specify the Simple Mail Transfer Protocol (SMTP) server that File Server Resource Manager will use for forwarding e-mail messages. You can specify the SMTP server by using the Dirquota admin options, Filescrn admin options, or Storrept admin options command. You can also specify the SMTP server to use by using the File Server Resource Manager snap-in (in the main node, click Configure Options).

Important

To send e-mail notifications and storage reports over e-mail, you must first specify the Simple Mail Transfer Protocol (SMTP) server that File Server Resource Manager will use for forwarding e-mail messages. You can specify the SMTP server by using the Dirquota admin options, Filescrn admin options, or Storrept admin options command. You can also specify the SMTP server to use by using the File Server Resource Manager snap-in (in the main node, click Configure Options).

Note
The syntax described in this topic is displayed in the Command Prompt window when you run the Dirquota notification or Filescrn notification command on a computer on which File Server Resource Manager has been installed. Note that the configuration file can have any file name extension (for example, .txt or .cfg).

Parameter Syntax

This section describes the syntax for the parameters used in configurations files for quota and file screen notifications.

Important
For a notification file to be processed correctly, each parameter must be in a separate line, and it must follow the syntax described in this topic.

General properties

These parameters apply to properties that affect all types of notifications.

Parameter

Required

Description

Notification=<NotifyType>

Yes

Specifies the type of notification. Note that this parameter must be the first line of the configuration file. The NotifyType value must be one of the following:

m — an e-mail notification
e — an event log notification
c — a command or script execution
r — a report generation

RunLimitInterval=<Interval>

Specifies the number of minutes before another notification will be raised for the same issue. This reduces the number of notifications raised for repeatedly exceeding a quota or detecting an unauthorized file.

If you do not specify an interval, the default interval for the type of notification will be used.

Note
You can use the Dirquota admin options and Filescrn admin options commands to display and configure the default intervals.

E-mail notifications

These parameters apply to e-mail notifications.

Parameter

Required

Description

To=<EmailList>

Yes

Specifies the list of e-mail addresses for the recipients of the e-mail notification. Use a semicolon to separate multiple e-mail addresses. All e-mail addresses must be in the format account@domain.

Note
You can use the [Source Io Owner Email] variable instead of an e-mail address to send the notification to the user who exceeded the quota threshold (for quota notifications) or saved the unauthorized file (for file screen notifications). For more information, see Available variables later in this topic.

From=<Email>

Specifies the default e-mail address to use as the originating e-mail address. The e-mail address must be in the format account@domain.

If you do not specify an originating e-mail address, the default originating e-mail address will be used.

Note
You can use the Dirquota admin options and Filescrn admin options commands to display and configure the originating e-mail address.

ReplyTo=<Email>

Specifies the e-mail address where e-mail replies should be sent. The e-mail address must be in the format account@domain.

Cc=<EmailList>

Specifies the list of e-mail addresses to which a carbon copy of the e-mail message will be sent. Use a semicolon to separate multiple e-mail addresses. All e-mail addresses must be in the format account@domain.

Bcc=<EmailList>

Specifies the list of e-mail addresses to which a blind carbon copy of the e-mail message will be sent. Use a semicolon to separate multiple e-mail addresses. All e-mail addresses must be in the format account@domain.

Subject=<Text>

Specifies the text for the subject field of the e-mail message.

Message=<Text>

Yes

Specifies the text used in the body of the e-mail message. You can add variables within the text of the message. For a list of variables, see Available variables later in this topic.

To specify line breaks in the body of the message, use a backslash (\) at the end of a line, followed by a carriage return.

Event log notifications

These parameters apply to properties that affect event log notifications.

Parameter	Required	Description
EventType=<Type>	No	Specifies the type of event that will be logged. The Type value must be one of the following: Error Warning Information If you do not specify an event type, a Warning event will be logged.
Message=<Text>	Yes	Specifies the text used in the body of the event message. You can add variables within the text of the message. For a list of variables that you can use, see Available variables. To specify line breaks in the body of the message, use a backslash (\) at the end of a line, followed by a carriage return.

Parameter

Required

Description

EventType=<Type>

Specifies the type of event that will be logged. The Type value must be one of the following:

Error
Warning
Information

If you do not specify an event type, a Warning event will be logged.

Message=<Text>

Yes

Specifies the text used in the body of the event message. You can add variables within the text of the message. For a list of variables that you can use, see Available variables.

To specify line breaks in the body of the message, use a backslash (\) at the end of a line, followed by a carriage return.

Note
Event log notifications for quotas are logged in the Application log, with event ID 12325 and source SRMSVC. Event log notifications for file screens are logged in the Application log, with event ID 8215 and source SRMSVC.

Command notifications

These parameters apply to properties that affect command notifications.

Parameter

Required

Description

Command=<Path>

Yes

Specifies the local path where the command or script is stored. If the specified path is on the boot volume, it must be the path to the Windows folder or one of its subfolders. (for example, c:\windows\system32\cscript.exe). If the specified path is on a volume other than the boot volume, the path must be for a folder or volume that permits write access only to the System account, and to members of either the Administrators group or the Backup Operators group.

Arguments=<Arguments>

Specifies the arguments to be used when running the command or script.

Account=<Account>

Specifies the account that should be used when running the command or script. To maintain server security, use the most restrictive account possible. This will help safeguard the system if the process is compromised in any way.

The Account value must be one of the following:

LocalService — The same level of access as the Users group, to access network resources as a null session with no credentials.
NetworkService — The same level of access as the Users group, to access network resources by using the credentials of the computer account.
LocalSystem — Full access to the system. Do not use this account unless full access is required and you are certain that the process cannot be compromised.

If you do not specify an account, the command or script runs with the Network Service account.

WorkingDirectory=<Path>

Specifies the folder where the command or script will run.

Note
To run the command or script in the folder where the quota applies, use the [Quota Path] variable for Path. To run the command or script in the folder where the file screen applies, use the [File Screen Path] variable for Path.

If you do not specify a path, the command or script runs in the folder where it is located.

MonitorCommand=<Status>

Specifies whether the correct execution of the command or script should be monitored. The Status value must be one of the following:

Enable — Monitors the command or script.
Disable — Does not monitor the command or script.

If you do not specify a status, the command or script is not monitored.

KillTimeOut=<Timeout>

Specifies the number of minutes after which a monitored command or script will be terminated.

This parameter requires that the MonitorCommand=Enable parameter be included in the configuration file.

LogResult=<Status>

Specifies whether a result code returned by the command or script must be logged as an event.

The Status value must be one of the following:

Enable — Logs the resulting code.
Disable — Does not log the resulting code.

If you do not specify a status, by default the event will be logged in the Application log, with event ID 8226 and source SRMSVC. The event message will list the return code.

If you specify the Disable value, the resulting code is not logged.

This parameter requires that the MonitorCommand=Enable parameter be included in the configuration file.

Report notifications

These parameters apply to properties that affect report notifications.

Parameter

Required

Description

ReportType=<Type>

Yes

Specifies the list of reports to generate. Use a pipe character (|) to separate multiple report types, without leaving blank spaces. The Type value must be one or more of the following:

DuplicateFiles — Lists files that appear to be duplicates (files with the same size and last-modified time).
Export — Includes all the unfiltered data gathered during a file system scan. This data can be used to perform customized storage analysis.

FileScreenAudit — Lists file screening events that have occurred on the server for a specified number of days. Use this report to identify users or applications that violate screening policies.

Important
Before you generate a File Screening Audit report, you must enable the recording of file screening activity in the auditing database by using the Dirquota admin options command with the /screenaudit:enabled parameter. You can also enable file screening auditing by using the File Server Resource Manager snap-in (in the main node, click Configure Options).

FilesByFileGroup — Lists files that belong to specified file groups.
FilesByOwner — Lists files, grouped by the users who own them.
LargeFiles — Lists files of a specified size or larger.
LeastRecentlyAccessed — Lists files that have not been accessed for a specified number of days.
MostRecentlyAccessed — Lists files that have been accessed within a specified number of days.
QuotaUsage — Lists quotas for which the quota usage is higher than a specified percentage. Use this report to identify quotas with high usage levels so that appropriate action can be taken.
Note
The Quota Usage report includes quotas that were created for volumes and folders in File Server Resource Manager only.

MailTo=<EmailList>

Specifies the list of e-mail addresses to which the report will be sent. Use a semicolon to separate multiple e-mail addresses. All e-mail addresses must be in the format account@domain.

Note

You can use the [Source Io Owner Email] variable instead of an e-mail address to send the notification to the user who exceeded the quota threshold (for quota notifications) or saved the unauthorized file (for file screen notifications). Also, you can use the [Admin Email] variable to send the notification to the default e-mail addresses for the administrators. For more information, see Available variables later in this topic.

If you do not specify an e-mail address, the reports are saved on the local computer, at the default path for incident reports.

Note
You can use the Dirquota admin defaults command to display and configure the default paths for storing reports. Use the /incident parameter of that command to change the default path where incident reports will be saved.

Note
Except for the Duplicate Files report, all report types have configurable report parameters that determine the information included in each report. To configure report parameters, use the Dirquota admin defaults command.

Available variables

You can use variables to configure notifications. When the notification is generated, variables are replaced with their corresponding values. For example, if the [Server] variable is used in the body of an e-mail message, the recipients of the e-mail message will see the actual name of the server on which the notification occurred, instead of the variable.

The variables that are available for quota notifications are not always the same ones that are available for file screen notifications. The following tables list and describe all of the variables that are available for quota and file screen notifications.

Quota notification variables

You can use the following variables in notifications created for quotas.

Variable

Description

[Admin Email]

Inserts the default e-mail addresses for the administrators.

Note
You can use the Dirquota admin options command to display and configure the default e-mail addresses.

[Quota Free]

Inserts the amount of free space remaining under the quota, in bytes.

[Quota Free KB]

Inserts the amount of free space remaining under the quota, in kilobytes (KB).

[Quota Free MB]

Inserts the amount of free space remaining under the quota, in megabytes (MB).

[Quota Free Percent]

Inserts the amount of free space remaining under the quota, as a percentage.

[Quota Limit]

Inserts the quota limit in bytes.

[Quota Limit KB]

Inserts the quota limit in KB.

[Quota Limit MB]

Inserts the quota limit in MB.

[Quota Path]

Inserts the quota path.

[Quota Peak]

Inserts the quota peak usage in bytes.

[Quota Peak KB]

Inserts the quota peak usage in KB.

[Quota Peak MB]

Inserts the quota peak usage in MB.

[Quota Peak Percent]

Inserts the quota peak usage as a percentage.

[Quota Peak Time]

Inserts the time when the peak usage was recorded.

[Quota Remote Paths]

If the path for the quota is a shared folder or volume, inserts the path in Universal Naming Convention (UNC) format (\\Server\Share\).

[Quota System Path]

Inserts the quota path in canonical format (\\?\VolumeGUID\).

[Quota Threshold]

Inserts the quota threshold that caused the notification.

[Quota Used]

Inserts the quota usage in bytes.

[Quota Used KB]

Inserts the quota usage in KB.

[Quota Used MB]

Inserts the quota usage in MB.

[Quota Used Percent]

Inserts the quota usage as a percentage.

[Server]

Inserts the name of the server on which the notification occurred.

[Server Domain]

Inserts the name of the domain of the server on which the notification occurred.

[Source File Owner]

Inserts the user name of the owner of the file that caused the notification.

[Source File Owner Email]

Inserts the e-mail address of the owner of the file that caused the notification.

[Source File Path]

Inserts the path of the file that caused the notification.

[Source File Remote Paths]

If the path for the file that caused the notification is a shared folder or volume, inserts the path in UNC format (\\Server\Share\).

[Source Io Owner]

Inserts the user name of the user who exceeded the quota threshold (for quota notifications) or saved the unauthorized file (for file screen notifications).

[Source Io Owner Email]

Inserts the e-mail address of the user who exceeded the quota threshold.

[Source Process Id]

Inserts the ID of the process that caused the notification.

[Source Process Image]

Inserts the name of the executable file for the process that caused the notification.

File screen notification variables

You can use these variables in notifications created for file screens.

Variable

Description

[Admin Email]

Inserts the default e-mail addresses for the administrators.

Note
You can use the Filescrn admin options command to display and configure the default e-mail addresses.

[File Screen Path]

Inserts the path of the file screen.

[File Screen Remote Paths]

If the path for the file screen is a shared folder or volume, inserts the path in UNC format (\\Server\Share\).

[File Screen System Path]

Inserts the path of the file screen in canonical format (\\?\VolumeGUID\).

[Server]

Inserts the name of the server on which the notification occurred.

[Server Domain]

Inserts the name of the domain of the server on which the notification occurred.

[Source File Owner Email]

Inserts the e-mail address of the owner of the unauthorized file.

[Source File Owner]

Inserts the user name of the owner of the unauthorized file.

[Source File Path]

Inserts the path of the unauthorized file that caused the notification.

[Source File Remote Paths]

If the path for the unauthorized file is a shared folder or volume, inserts the path in UNC format (\\Server\Share\).

[Source Io Owner]

Inserts the user name of the user who saved the unauthorized file.

[Source Io Owner Email]

Inserts the e-mail address of the user who saved the unauthorized file.

[Source Process Id]

Inserts the ID of the process that caused the notification.

[Source Process Image]

Inserts the name of the executable file for the process that caused the notification.

[Violated File Group]

Inserts the name of the file group to which the file that caused the notification belongs.

Examples

E-mail notification example

The following is an example of a configuration file for an e-mail notification that will be sent to the user who exceeds a soft quota, with a copy sent to the administrative e-mail addresses.

Notification=m
To=[Source Io Owner Email]
From=storage.quota@contoso.com 
ReplyTo=[Admin Email] 
CC=[Admin Email] 
Subject=You have exceeded your storage quota
Message= Hi [Source Io Owner],\
Your storage quota on server: [Server] has been exceeded.\
The quota limit is [Quota Limit MB] MB, and you are using [Quota Used MB] MB ([Quota Used Percent]%).\
To avoid receiving more quota alerts, please delete or remove files from [Quota Path].\
Best Regards,\
--IT Department

Event log notification example

The following is an example of a configuration file for an event log notification that will log an event of type Error if a user attempts to save an unauthorized file. The specified interval will ensure that the event is logged only once every two hours; this prevents the same event from being logged repeatedly if the user attempts to save the file several times.

Notification=e
RunLimitInterval=120
EventType=Error
Message=The system detected that user [Source Io Owner] attempted to save [Source File Path] on server [Server]. The unauthorized file matches the [Violated File Group] file group.

Command notification example

The following is an example of a configuration file for a command notification that will be raised when a folder where log files are stored reaches a specified quota threshold. The notification runs a script that moves all log files to an archive location. The notification will also log an event in the Application log (with event ID 8226 and source SRMSVC) after the script has finished running.

Notification=c
Command=C:\Windows\System32\cscript.exe
WorkingDirectory=[Quota Path]
Arguments=E:\scripts\move_logs.vbs //b
MonitorCommand=Enable

Report notification example

The following is an example of a configuration file for a report notification that will send an e-mail with three types of reports when a volume reaches a specified quota threshold. The reports selected for this notification help identify files that can be removed from the volume to recover disk space. The specified interval limits the generation of reports to once every 24 hours.

Notification=r
RunLimitInterval=1440
ReportType=LargeFiles|DuplicateFiles|LeastRecentlyAccessed
MailTo=storage@contoso.com