Scripting Tutorial #1

Scripting Tutorial - 1

Scripting in BlackMoon FTP Server

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 folder too.

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 = pythonscript.

Events

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

void OnUploadEnd(      
    String Filename,
    Long bytesTransferred,
    Long transferRate,
    Date startTime,
    Date endTime,
    Long errCode
    Long crc32
)

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.

sub Client_<event>()
        ....
        do stuff
        ....
end sub

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

boolean OnDownloadStart(      
    String filePath
)

here your vbscript function will take the form

function Client_OnUploadStart( uploadfile ) 
        .....
        do stuff
        .....
        Client_OnUploadStart = true  
end function

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 hair out.

Helper Objects

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 for.

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 was doing.

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

void OnLogin
(
    String Username,
    String Password,
    Date loginDate
)

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"
end sub

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 different).

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 says

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" 
end sub

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 tutorials.

Download the tutorial files here