||Scripting Tutorial - 1
|Scripting in BlackMoon FTP
|Unlike other ftp servers, where external programs are
executed by the server, scripting in blackmoon is interpreted, ie the server
reads the source code and then executes the commands in the file. The advantage
here is there isn't a need to have environment variables or shared memory
systems for external programs to access data from the server. The code can just
refer to the ftp clients ip address for example and the script interpreter will
supply it. Another advantage is that scripts cannot crash the server. If a
script takes too long to execute, it is ignored and processing continues.
Access violations are gracefully handled by the server too and scripting errors
are displayed in the GUI to help with debugging.
|Configuring scripts - The
Infopacks and Scripts Folder
|Infopacks describes scripts. They are xml files containing
data like the script name, version, who wrote it, the website to find updates,
which configuration file to edit and help text on how to use them. If a script
source does not have an accompanying infopack file it will not appear in the
list of scripts in the ftp server configuration. Infopacks are stored in
the /infopacks folder . When you finish writing your script, you
can use the InfoPack Editor to create or modify the infopack for the script.
The scripts are stored in the /scripts folder . All scripts
(vbscript, jscript, perlscript and pythonscript) should be stored in this
folder. All configuration files needed by the scripts should be stored in this
|Types of scripts
|Because blackmoon uses Microsoft's ActiveScripting technology, any language
that supports ActiveScripting can be used for scripting. Currently you can use
vbscript, jscript, perlscript and pythonscript. PerlScript and PythonScript
need to be downloaded and installed from ActiveState
before it can be used. BlackMoon will recognize script languages by the
extensions of the script filename. .vbs = vbscript, .js =
jscript, .pl = perlscript and .pys =
|The main reason you would want to write a script would be to respond to events.
For example, a script that emails an administrator when a particular file is
uploaded will have to respond to the event that the server "fires" to the
script when an upload has been completed. The BlackMoon help file has a list of
all the events supported but to receive them in your script, they have to be
formatted in a special way for them to work. We will start off with vbscript
and how to respond to ftp server events in them. For example the help file will
list the upload completed event has
in vbscript, to write code that gets executed when this event is fired, your
event has to be formatted as
sub Client_OnUploadEnd( filePath, bytesTransferred, transferRate, startTime, endTime, errorCode, crc32 )
The reason for having the documentation in a different format is because each
scripting language has a different way of writing functions or subroutines to
handle events. The help file is in a generic form that also lets you know what
types of data to expect in the parameters.
When writing event handlers in vbscript, always prefix Client_
to the event name in the help file. In this case Client_OnUploadEnd.
DO NOT add the types to the variables, ie, instead of Long transferRate,
just transferRate. This is because vbscript uses generic
types. It is important to know which types you are getting and you can get this
information from the documentation.
The return type is also very important. For some events, the
server will check if the function returns true or false.
eg in the DeleteFile event, if the function returns true, the file is deleted
and if it returns false, the deletion is halted. When the documentation has the
return type as void, it means the server does not check the
return type. If it is boolean, then the server does check the
return for true or false. When writing script in vbscript a function that has a
return type of void should always be written as a subroutine.
In this case the return type in the help file is void.
So a subroutine can do the job without worrying about the event type. Lets take
a look in the help file for an event that returns a boolean
here your vbscript function will take the form
function Client_OnUploadStart( uploadfile )
Client_OnUploadStart = true
In the above snippet of code you saw
Client_OnUploadStart = true
This is how a value is returned from a function in vbscript. The name of the
function is set to true or false. If it is not set, it is assumed to be false
by the server.
These coding rules are very important. Doing it wrong or forgetting something
like not returning true or false for a function that requires it could be the
difference between spending a minute on a task and ten minutes pulling your
|Helper objects are objects that are internally available to scripts that get
executed in blackmoon. For example in vbscript if you wanted to convert a
string to text to lower case, all you do is call the LCase function
and it will be done for you by the langauage.
The same concept holds true for blackmoon. If your script wanted to kick off
the user, it would call the function Client.KickUser. The "Client."
prefix to the function name means that there is an object called Client
which has methods and properties provided by the ftp server about the client
for which the script is being executed for. This object contains a lot of
useful information including the IP address, Username, Password, how many files
or kilobytes have been uploaded and so on. The help file has documentation on
all the available methods and properties.
Along with the Client Object, there is the Server Object,
the ScriptTimer Object and the Socket Object.
Client Object - provides methods and properties for the client
the script is executing for. The script is executed for each client so the
script gets a client object that is unique to the client it is being executed
Server Object - provides general methods and properties. This
includes server stats and other utility properties and methods like
installation folder or calculating crc32's for files and so on.
ScriptTimer Object - provides timing functions. Since the
script is executed sequentially, the timer event won't preempt the script if it
is already busy doing something. In otherwords, if the script is stuck in a
loop or doing something, the timer won't go off until it is done doing what it
Socket Object - provides simple socket services to connect to
other computers or programs. useful for talking to eggdrop. Socket objects are
also unique to the client so when the client disconnects any connections opened
by the socket object will be closed too.
To call a method or property for any of these objects you just prefix the
method or property name with the objectname. For example Client.RemoteIP
to get the connected ftp client's ip address, Server.FilesDownloaded
to get the number of files downloaded for the ftp server session, ScriptTimer.AddTimer(5)
to setup a 5 second timer, Socket.Open("127.0.0.1",3333) to
connect to an eggdrop on port 3333 localhost etc. More detailed information on
these objects will be provided in later tutorials.
Now we get dirty by writing our first sample script
|Sample script in vbscript
|For our first script, we will concentrate on writing text from the script to
the ftp client, and to the GUI (both the server logs and the client logs view).
This is a great way to debug your scripts since you can't see the output until
it gets executed.
The Script - When the ftp client logs in, we will show the ftp
client a friendly welcome message "welcome to my ftp site".
We will also print out in the blackmoon GUI "user xxx with
client ip xxx has logged into the ftp server", where xxxx is data
from the Client Object. On Logout we will print out to the ftp client "bye
bye, please drop by later" and in the GUI logs "xxxx
logged out of the server ".
First, open notepad (or your favorite editor) and create a file called "script_tut1.vbs"
in the /scripts folder under the main blackmoon ftp server
folder. If you use notepad, make sure you create a file "script_tut1.vbs"
and not "script_tut1.vbs.txt ".
To display our welcome message we need to respond to the login event. In the
help file the documentation says
in our script we write a function
sub Client_OnLogin(username, password, logindate)
Client.ShowMessage "welcome to my ftp site"
Server.PrintStatusMessage "User " & Client.Username & " with client ip " & Client.RemoteIP & " has logged into the ftp server"
note: The current documetation lists this function as
returning boolean which is wrong. The help file will be updated soon.
Client.ShowMessage is a method in the Client Object that
prints out a message to the ftp client
Server.PrintStatusMessage will display in the main server
view, in green text "user anonymous with client ip
192.168.2.132 has logged into the server" (the exact text will be
As you can tell Server.PrintStatusMessage is a good way to
debug your scripts. You could easily put "Login Event was called" just to make
sure that your login event was really called.
The next task is saying goodbye to the ftp client and telling the GUI the
client has logged out. In the help file our documentation for the logout event
void OnLogout( Date logoutDate, String Reason )
in our script we write a subroutine (as the function returns void)
sub Client_OnLogout(logoutdate, reason)
Client.ShowMessage "bye, bye.. please drop by later"
Server.PrintStatusMessage Client.Username & " logged out of the server"
Save the coding changes made in the script files. Now we will create an
infopack to let the server know there is a new script available to run. We do
this by running the InfoPack Editor (start->program files->blackmoon ftp
server->infopack editor). Enter the values you see in the screenshot below
and save it in the /infopacks folder (for example c:\program
files\blackmoon ftp server\infopacks) use "script_tut1
" as the file name.
When you open the GUI, go to server properties, scripting page and select and
add "Scripting Tutorial 1" to the list of active scripts. Log in to the server
with your ftp client and you will see an output similar to the screenshot below
This ends the scripting tutorial lesson one, look forward to writing scripts in
other languages, how to write better scripts, script config files etc in later
Download the tutorial files here