Setup email notification in the Xlight FTP Server

System administrator can setup email notification for some events happened in the Xlight FTP Server, such as a file is uploaded, hard disk space is low. System administrator will receive a notification email when an event happens.

In this example, we will show you how to setup email notification. Note: after 30-day evaluation period, this function is only supported by the Professional edition of Xlight FTP Server.

1. To use email notification, you have to enable this function in the virtual server as showed in the figure below.

2. Then you will need to setup a SMTP server for sending notification email. We will use Gmail as an example. Because for sending email through Gmail SMTP server, TLS protocol must be used for encrypting connection. We select the SSL/TLS connection option and use port 465 for Gmail. However for most corporate internal e-mail servers, standard SMTP port 25 is always supported and SSL/TLS port 465 may not be supported for sending email. It is not necessary or even possible to use SSL/TLS for corporate internal e-mail servers.

3. You must also select the email notification configuration file. This file is used to configure events triggering FTP server to send email.Email notification configuration file is a text file that has the settings about events you want to receive email notification. You can edit this file by using Notepad.

4. You will need to setup the SMTP User Authentication settings and Email Settings. To setup the SMTP User Authentication, you need to have a vaild account in the email server, as showed in the figure below.

Events supported for the email notification

There are 7 email notification events supported by Xlight FTP Server. The following table is the list of events supported by Xlight FTP Server.

Event name	Event Description
OnFileUpload	This event is triggered when user uploaded a file.
OnFileDownload	This event is triggered when user downloaded a file.
OnFileDelete	This event is triggered when user deleted a file.
OnDiskSpaceLow	This event is triggered when hard disk space is low.
OnLogin	This event is triggered when user successfully login.
OnLogout	This event is triggered when user logout.
OnWanIPChange	This event is triggered when WAN IP changes after server starts.

5. If you want to receive email notification, you have to put the event type in the email notification configuration file. You can also use parameters to further restrict the conditions that the email notification will be sent. The figure below is a sample email notification configuration file with 5 events.

After a user uploaded, downloaded, deteled a file or when disk space is periodically checked in the virtual server, all these actions will cause FTP Server to check email notification configuration file preloaded in the memory. FTP Server uses current action to check against event and conditions at every line of this configuration file. If a line can pass the check, an email will be sent. After finding a matched line, Xlight FTP Server will not check lines below it any more. The sequence of lines in the configuration file will have impacts on the email notification. You would better put lines with specific conditions in the top and lines with general conditions in the bottom.

Each line in the configuration file is checked from left to right. In the figure above, OnFileUpload is the event of first line. The parameter $file sets the file types. $file has two values *.exe and *.bat. If a file with extension *.exe or *.bat is uploaded by a user, it can meet both OnFileUpload event and file type conditions of first line. The user upload action will then be checked against the $dir parameter. $dir parameter restricts the upload directories to be in the virtual path /public or its sub-directories.

If all conditions in above are met, an email will be sent to notify that a file with extension *.exe or *.bat is uploaded in the virtual path /public or its sub-directories.

The parameter $email_file in the first line is not a condition. It is used to specify a file for customerizing email message. If you don't use $email_file parameter, Xlight FTP Server will generate a default email message. In the file specified in the $email_file, you can use your own TO, CC and BCC addresses for people to receive this email. It will replace the default TO address in the Email Settings.

Samples for email notificaion configuration.

Example 1. Reveive the email notification when free disk space of C is below 100 MB or free disk space of D is below 200 MB.

OnDiskSpaceLow $disk_space=C(100),D(200)

Example 2. Reveive the email notification when a file uploaded is larger than 2000 MB.

OnFileUpload $file_size>2000

Example 3. Reveive the email notification when user test uploaded a file with extension gif, jpg, or png .

OnFileUpload $file=*.gif,*.jpg,*.png; $user=test

Example 4. Reveive the email notification when someone uploaded a file with the name containing forbidden words, such as sex, porn.

OnFileUpload $file=*sex*,*porn*;

Example 5. Reveive the email notification when a user logout, who had uploaded at least one file.

OnLogout $up_files>0;

Example 6. Reveive the email notification when the user "tester" login.

OnLogin $user=tester;

Example 7. Reveive the email notification when all users login except the "anonymous" user.

OnLogin $user=*; $exclude_user=anonymous;

Below are supported parameters for the email notificaion configuration file.

Parameters supported for the email notification configuration file

Parameter name	Allow multiple values	UNIX shell-style wildcards	Value Description
$file	Yes	Yes	The name of file.
$dir	Yes	Yes	The directory where events happened in. The directory can be either FTP virtual path such as "/public" or DOS path such as "C:\test". Use wildcards to include sub-directories. For example, to include all sub-directories of "C:\test", you can write it as "C:\test\*".
$user	Yes	Yes	The name of user.
$group	Yes	Yes	The user group.
$exclude_file	Yes	Yes	The name of file excluded from triggering event.
$exclude_dir	Yes	Yes	The directory excluded from triggering event.
$exclude_user	Yes	Yes	The name of user excluded from triggering event.
$exclude_group	Yes	Yes	The user group excluded from triggering event.
$file_size	No	No	The file size in MB. For example if you want OnFileUpload event to be triggerred when uploaded file is above 1000M, you can write it as $file_size>=1000. This parameter doesn't support multiple values.
$down_files	No	No	The number of files user downloaded. For example if you want OnLogout event to be triggered when user at least downloaded 10 files, you can write it as $down_files>=10. This parameter doesn't support multiple values.
$up_files	No	No	The number of files user uploaded. For example if you want OnLogout event to be triggered when user at least uploaded 1 files, you can write it as $up_files>=1. This parameter doesn't support multiple values.
$disk_space	Yes	No	The condition for triggering disk space low warning. This entry starts with the hard drive letter and brackets with free disk space in MB. For example, if we want to receive a warning when free disk space in hard drive E is lower than 500M, we can write it as E(500). After setting this parameter, Xlight FTP Server will check disk space for configured drives every 30 minutes. So if your current disk space is above threshold, but for some reason you had received an unexpected low disk space warning email. Please check if you have any scheduled job (such as backup) that will temporarily reduce the disk space usage in the configured drive.
$email_file	No	No	Customerize email message to be sent when an event is triggered. You can put many TO, CC and BCC addresses in the content of this file. They will override the default TO address in the Email Settings. There are no limits on the number of TO, CC and BCC addresses in this file. But SMTP server may have limitation. Also the size of email message file is limited to 16K. Another useful tip is that this file is read by Xlight FTP Server just before sending email. It can be useful if you want to change the email content dynamically. For example, if you have a nightly code build job generating a log. After build finished, before uploading the log file to FTP Server, you can use a script to write to a customerized email file, which includes the build result and recepient email addresses. Upload this email file to FTP server before uploading the log file. So people in the morning will receive an email with the result of nightly build job and the location of log file.

Some parameters allow multiple values. Multiple values are seperated by comma ",". For parameter with multiple values, the relationship between values is OR. For example $user = a*, c* means user's login name must start with character a or b. If a line with multiple parameters, all conditions must be met to trigger the event for this line. For parameters not showed in the line, their condition are met automatically.

The content of email message file set in $email_file parameter

The figure below is the content of a sample email message file specified in the parameter $email_file. Strings start with character % are variables, which they will be replaced with actual values before an email message is sent.

Note: there must have no blank lines in the email header. The email header and email content are separated by one blank line. You can have as many blank lines as you want in the email content, as showed in the figure below.

6. Below are supported variables for the content of email message file. Please note the difference: Variables in the email message file start with character %, but parameters in the email notification configuration file start with character $.

Variables supported for the email message file

Variable name	Value Description
%filename	It will be replaced with the name of the file being uploaded, downloaded or deleted.
%down_filelist	The name list of last 100 files being downloaded. Filenames are separated by comma.
%up_filelist	The name list of last 100 files being uploaded. Filenames are separated by comma.
%file_size	It will be replaced with the size of the file (in bytes) being uploaded, downloaded or deleted.
%file_size_mb	It will be replaced with the size of the file (in MBytes) being uploaded, downloaded or deleted.
%downfiles	It will be replaced with the number of the files the user downloaded.
%upfiles	It will be replaced with the number of the files the user uploaded.
%totaldown	It will be replaced with the total amount the user downloaded.
%totalup	It will be replaced with the total amount the user uploaded.
%username	It will be replaced with the name of the user who upload, download or delete file.
%password	It will be replaced with the password of the user who upload, download or delete file.
%groupname	It will be replaced with the name of the user group who upload, download or delete file.
%virtual_path	It will be replaced with the name of the virtual path where the file is uploaded, downloaded or deleted.
%real_path	It will be replaced with the name of the DOS path where the file is uploaded, downloaded or deleted.
%client_ip	It will be replaced with the IP address of the user who upload, download or delete file.
%server_ip	It will be replaced with the IP address of the virtual server where the file is uploaded, downloaded or deleted.
%server_port	It will be replaced with the port of the virtual server where the file is uploaded, downloaded or deleted.
%weekday	It will be replaced with the weekday.
%date	It will be replaced with the date.
%time	It will be replaced with the time.
%rfc822_date	It will be replaced with the RFC 822 date format. It is used if you want to set the DATE header for the email message.
%diskfree<>	It will be replaced with the free disk space. For example, %diskfree<C> will show free disk space of C:\ drive. It can work only when the OnDiskSpaceLow event is triggered.
%wan_ip	It will be replaced with the WAN IP address. This variable must be used with OnWanIPChange event.