HOWTO: Setting up BulletProof FTP Server to email when Events are triggered on the FTP Server.
BulletProof FTP Server supports the execution of external programs when "events" are triggered on the FTP Server. In the current v2.x source-code there are over 30 events that are available for you to perform actions when fired. Events range from filesystem changes (Uploaded/Deleted Files) and Server Activity (User Logins) to generic events triggered every 5 minutes.
- Table of Contents
- 1.0 Introduction
- 1.1 Overview
- 1.2 Requirements
- 1.3 Background
- 2.0 BPFTP Event Manager
- 2.1 Event Manager
- 2.2 Event List
- 2.3 Event Variables
- 2.4 Event Filemask (Advanced)
- 3.0 Example: EMail on FileUpload
BulletProof FTP Server pioneered the concept of "Events" with v2.x. These "Events" are triggered based on various actions, conditions and activity on the server. In the v2.x source-code there are over 30 events.
In this HOW-TO, you'll learn to configure BPFTP Server to send an email to the FTP Administrator whenever a file is uploaded to the server. But by using this template you'll find the flexibility to do almost anything!
To configure BulletProof FTP Server correctly you must have the following information and access:
- Administrative access to the computer running the software (Windows Administrative Privileges)
- BulletProof FTP Server (http://www.bpftpserver.com) installed and running on the intended computer
BulletProof FTP Server has an extensive Events Manager, which allows you to "hook" into a variety of system events. These events range from users connecting and transferring files to BPFTP Server restarts and the creation of user accounts. In order to provide the most flexibility in any computing environment, BPFTP Server has the ability to call any external program with arguments relating to the action.
Configuring the Events Manager is easy and can be setup in a matter of minutes.
To configure the Events Manager, pull-down the
Setup menu and choose
This dialog is the Event Manager for BPFTP Server and allows you to hook external programs into BPFTP Server and react to events occurring on the FTP Server.
Below is a list of all the different Server Events you can hook into, including a brief description on how/when they are fired.
|Event Name||Event Description|
|OnAccountDisabled ||When a user account has been disabled.|
|OnExceedUSERPASS ||When a user failed to authenticate, exceeding the limited USER/PASSWORD|
|OnQuotaExceeded ||When quota has reached maximum quota allowed.|
|OnSameIPConnect ||When a user con only log once on the FTP Server.|
|OnDirCreated ||When a Directory/Folder has been created by a user logged into the FTP Server|
|OnDirDeleted ||When a Directory/Folder has been deleted by a user logged into the FTP Server|
|OnFileBanned ||User a user attempts to upload a file which has been banned on the FTP Server|
|OnFileDeleted ||When a file has been deleted by a user logged into the FTP Server|
|OnFileDownloaded ||When a file has been successfully downloaded by a user logged into the FTP Server|
|OnFileRenamed ||When a file has been renamed by a user logged into the FTP Server|
|OnFileUploaded ||When a file has been successfully uploaded by a user logged into the FTP Server|
|OnFileUploadFailed ||When an upload has failed due to an abort, disconnection, etc.|
|OnEvery05mins ||A pseudo event fired by the FTP Server every 5 minutes (0:00, 0:05, 0:10, etc)|
|OnEveryDay ||A pseudo event fired by the FTP Server every day at midnight (12:01am)|
|OnEveryHour ||A pseudo event fired by the FTP Server every hours (0:00, 1:00, 2:00)|
|OnIPChanged ||An event fired when the computer running BPFTP Server's IP address has been changed or a new IP address has been found.|
|OnLogFileRotate ||When BPFTP Server rotates the log files|
|OnServerClosed ||When the has been closed to any new connections by the administrator of the FTP Server|
|OnServerStarted ||When the has been started|
|OnStatRefreshed ||When the stat-generator has updated the top-files on the FTP Server|
|OnTooManyUsers ||When the defined maximum number of concurrent users for the FTP Server has been reached|
|OnTooManyUsersForAccount ||When the defined maximum number of concurrent sessions for the user has been reached.|
|OnUserAndPass ||When the user has provided the login/password for their account (before OnUserLoggedIn)|
|OnUserDisconnect ||When a user leaves/disconnectes from the FTP Server|
|OnUserHammering ||When a user unsuccessfully tries to connect multiple times (Possible Brute-Force Attack)|
|OnUserIsBanned ||When a banned user tries to login to the FTP Server|
|OnUserLoggedIn ||When a user has successfully logged into the FTP Server with their user/password.|
|OnUserQuit ||When a user has executed the QUIT command to logoff the server|
|OnUserTimeOut ||When a user has been disconnected due to surpassing the Idle Connection Timeout.|
|OnWelcomeUser ||When the Message-of-the-Day (MOTD) has been sent to the user on Welcome.|
Whenever an event is fired, BPFTP Server has the ability to send details of the event to your external program. This is performed with variables, each variable is prefixed with a percent (%) sign to indicate that the following word is the variable name. You'll notice in this table, that there are several variations of the same data. Specifically the 8.3 DOS file-format, this is no longer needed in today's modern file-systems; but has been included for backward compatibility of old 16-bit external programs and software that can't handle embedded spaces in filenames.
For the example values, I've uploaded a picture of my broken throttle cable from my Moped to my installation of BPFTP Server. My user account has it's Home Directory setup as
E:\ftp\mmc\ and the uploaded filename is long; showing the 8.3 naming-convention.
||IP address of BPFTP Server, separated by commas.
||Name of the event which was fired.
||Current Date on the computer running BPFTP Server.
||Current Time on the computer running BPFTP Server.
||User account which caused the event to fire.
||Group in which the %CLIENTNAME belongs to.
||IP Address for the connected %CLIENTNAME.
||Login used by the %CLIENTNAME.
||Password used by %CLIENTLOGIN.
||The full file path of the uploaded file on the computer running BPFTP Server.
||Same as %FILE, but in 8.3 DOS-Format.
||Time-stamp portion of the
||Just the filename (archives.zip, archives.rar, etc)
||Same as %FILENAME, but in 8.3 DOS-Format.
||Just the extension of the file in UPPERCASE (.EXE, .RAR, .ZIP, etc.)
||Filename without the extension.
||Full path to the file on the computer running BPFTP Server with the trailing-backslash "\".
||Same as %FILEPATH, but in 8.3 DOS-Format.
||The size of the file in bytes (1024 bytes = 1 KB, 1024 KB = 1 MB, 1024MB = 1 GB.
||The name of the directory created on BPFTP Server. Only relevant for OnDirCreated.
||The name of the directory deleted on BPFTP Server. Only relevant for OnDirDeleted.
||The name of the directory where the new directory/file was created.
||Same as %DIRTARGET, but in 8.3 DOS-Format.
||Full path to the directory created on the computer running BPFTP Server.
||Same as %DIR, but in 8.3 DOS-Format.
The firing of an event can be restricted by the use of a filemask. Filemasks are an integral part of all computer filesystems and all you to select files based on naming patterns and conventions.
In the below example, the batch-file "application.bat" is only called if the file hooked to the fired event is an executable (*.EXE) or resides in the directory "c:\ftp\":
Example: '*.exe;c:\ftp\*.*|c:\path\application.bat %parameters'
Based on your email, you are wanting to perform an action in BPFTP Server when someone does something on BPFTP Server.
No problem! BulletProof FTP Server has an extensive Events Manager, which allows you to "hook" into a variety of system events.
As an example: We'll setup BPFTP Server to send an email, when a file has been uploaded to the server.
BPFTP Server doesn't have the ability to send email by itself, instead we've developed the software to call external programs written in-house, open-source or the BPFTP Server community.
For sending email, we'll use the open-source, free program called "BLAT". BLAT.EXE is a win32 console-mode program. This doesn't mean it's an old DOS program, just that it conforms to more open-standards and a philosophy of system development leveraged from very stable and flexible UNIX systems (like RedHat Linux, Debian, Unixware, etc).
Let's just jump into it!
Download and install BLAT.EXE from it's official website:
Be sure to save it in a location on your hard-drive (not a network drive) and in a place you can remember.
Since this is a third-party, outside of the normal Microsoft Windows suite of utilities; and it follows the more conventional GNU coding/stdin/stdout standards. I usually place these types of files in a "binary directory", such as:
In addition, I would recommend placing this "binary directory" in the search path for Windows:
1.Click the Start button at the in your task-bar.
2.Dbl-Click Control Panel.
3.Click on the link to the far left to Switch to Classic View.
5.Click on the tab labeled Advanced.
6.Click the button labeled Environment Variables.
7.In the bottom ListView labeled System Variables, click on the line containing the variable-name PATH.
8.Click the button labeled Edit and at the end of the line in the edit-box labeled Variable value add your BIN directory with a ";" (semi-colon) separating your new variable from the previous ones.
It's now time to decide on the format of the email you want to send, where it's being sent to and who it's going to appear from; then test your configuration before hooking the command-line into the BPFTP Server Event Manager.
BLAT.EXE has a good deal of flexibility in it's command-line arguments. If you don't know the command-line, your in luck, because your going to get a hang of it after this exercise.
To open a command-line, click the Start button in your task-bar, type "cmd" and hit . If this is old-hat to you, download 4NT from http://jpsoft.com and use a better one!
In the command-line
c:\bin\blat.exe -to email@example.com -subject "Example Subject" -body "Hey a file has been uploaded:[THIS IS THE FILE]" -server mail.myisp.com -f firstname.lastname@example.org
Be sure to substitute the c:\bin\blat.exe for the location where you download/installed the BLAT.EXE. In addition, make sure you go through the text and change the TO/FROM to their appropriate values. The -server argument mail.myisp.com should also be set to the DNS name for your ISP's SMTP server.
After you've successfully received your test message, it's time to plug that command-line into BPFTP Server for execution on your desired Event. In this example, we're using the OnFileUploaded event.
1.Start BPFTP Server or restore the window for BPFTP Server. If you are running it as a Windows Server, you'll need to stop the service and launch the GUI via the Start button.
2.Pull-down Setup and select Events Manager.
3.Scroll down through the list of Events and click on the one labeled OnFileUploaded
4.Check-ON the box labeled Execute and copy/paste your command-line into the edit box, but change the [THIS IS THE FILE] with just %FILE.
5.Pull down the drop-box just to the right of the edit box and choose a run-method, I would recommend using Start Normal until you are sure it's working; then change to Start Hidden.
6.Click OK and you're done!
BPFTP Server has now been configured to execute the BLAT.EXE command whenever a file is uploaded to the FTP Server. Go ahead and test it. Remember, if you're having troubles getting it to work. Take a big breath and debug it! Go back to Step 1, challenge your assumptions and make sure it works first from a command-line.