BarracudaDrive
Client command line and scripting tutorial
When you connect to the web-file manager using a browser, the web-file-manager dynamically creates an HTML user interface for the directory of the URL typed into the browser. The generated HTML user interface can subsequently be used for initiating upload, download, making new directories, etc. The commands sent from a dynamically created HTML interface to the server are sent using standard HTTP.
Support for the HTTP protocol is built into many programming environments such as Java and Python. One can link in a HTTP client library with legacy C/C++ code. It is easy to use a tool such as curl or write client computer programs to interact with the web-file manager.
The following shows you how to take advantage of the HTTP support built into the Python scripting language and how to use curl for uploading files to the server.
We have designed a number of Python scripts which are similar in functionality to the UNIX command line tools mkdir, cp, ls, cd, rm and pwd. The Python scripts are converted to Windows EXE files so it is not necessary to install the Python runtime environment. The below example shows the copy command in action. All command line tools start with b for BarracudaDrive. The bcp command line tool is similar in functionality to the UNIX cp command.
Copy data command line example:
This tutorial is divided into three sections: the command line scripts, the BarracudaDrive API, and using curl.
Command line scripts
Installing the scripts:
- Download the pre-compiled Windows executables or the python source code.
- Unzip the ZIP file and install into any directory.
- Add the path to where you unzipped the ZIP files to your PATH environment variable.
The Python scripts are similar in functionality to common UNIX commands for working with files. By using the Python scripts, you can simultaneously work with multiple remote servers, copy files to and from local storage or directly from a remote server to another remote server, and more.
Windows users should note that the scripts cannot use DOS style path separator, so for example c:\users will not work, but c:/users will work.
The scripts work in two modes: in a relative mode or in an absolute mode.
The absolute mode requires an URL of the form //user:password@ipaddress/path. For example, assuming that you are using the default password for the administrator, the following command lists the content of the root directory: bls //admin:admin@localhost/. You must specify the port number if the HTTPS server is not listening on the default port 443. For example, the command is bls //admin:admin@localhost:8443/ if the HTTPS server is listening on port 8443.
The relative mode is using the prefix r:, where r means remote. The BarracudaDrive relative path works similar to the way the relative path works on a regular file system. A limitation with the relative path is that you can work with only one server at a time, but one can mix a relative path and an absolute URL. Thus, one can copy by using a relative path from one server to an absolute path on another server. The relative path is automatically converted to an absolute URL by the scripts when you access the remote drive. The state information used by the relative path is stored in the file .bcudadrv in your home directory. Therefore,you should remove this file when completed. The command blogout removes the file. The file .bcudadrv is automatically created as soon as you start using a relative path. The commands will ask you for the hostname, user, and password before committing the command to the server.
The bcd command updates the .bcudadrv file when changing directory. You can directly specify an absolute URL with bcd or use a relative path. The bcd command will interactively ask you for hostname, user, and password if the .bcudadrv file is not yet created. You can also use the bcd command to change the URL from one server to another.
All scripts, except 'bpwd' (print current working directory), accept a "-h flag", where -h prints out information about how to use the command.
Examples
List the content of the //localhost/users/ directory:We assume that we have 5 servers with IP address 192.168.1.1 to 192.168.1.5 in the following example.
Copy all data on server 192.168.1.1 - 192.168.1.4 to 192.168.1.5
The BarracudaDrive API
The BarracudaDrive web-services API is used by the Python scripts, the Java File Manager, and the DHTML search application.
A client sends HTTP commands of type GET, POST and PUT to the server. The server performs the requested action, returns HTML for browser clients and plain text or JSON for non-browser clients. The user is informed via the HTML returned to the browser if the operation succeeded or not. A non-browser client is informed via the HTTP status code if the operation succeeded or failed.
The BarracudaDrive commands are divided into two sections:
- Data commands for uploading and downloading files.
- Control commands for listing directory content, creating/deleting directories and/or files.
Data commands
Downloading a file from the server to the client works just as it does for a regular web-server. The client sends a GET command to the server, and the server returns the file if found.
Uploading a file to the server is either made by using HTTP PUT or by using HTTP POST multipart/form-data as specified in RFC1867. A browser can only upload data by using multipart/form-data. The web file manager interface automatically creates an HTML form with the encoding type set to "multipart/form-data" when you press the upload button. A command line HTTP client or a script can use any HTTP method, but should use HTTP PUT since the BarracudaDrive is designed such that it assumes PUT uploads are from non-browser clients.
The server can automatically create the necessary directory structure when uploading a file. The URL-encoded data "mkdir=true" can be sent with a PUT request. The server will then attempt to recursively create the directory structure. A PUT command will otherwise fail if attempting to upload to a non existing directory.
Control commands
BarracudaDrive provides a web-service API for listing directory content, creating new directories, and removing resources. The web-service API is a combination of a REST API and a JSON API.
| Client | HTTP request type | URL-encoded request | HTTP response message | Explanation |
|---|---|---|---|---|
| Browser | GET | cmd=ls | text/html | List directory content. Response data is an HTML table. |
| Non-browser | GET | cmd=lj | text/plain JSON | List directory content. Response data is a JSON array. The array contains one object for each resource listed. The object contains the following keys: n,s,t: n=name,s=size, t=time. |
| Browser | GET | cmd=mkdir | text/html | Response data is an HTML form for creating a directory. |
| Browser | POST | cmd=mkdir&dir=name | text/html | Form data sent when user submits the "create directory" form. |
| Non-browser | POST | cmd=mkdirt&dir=name | text/plain | Typically sent from a non-browser client when creating a directory. |
| Browser | GET | cmd=rm | text/html | Response data is an HTML form for deleting a resource. |
| Browser | POST | cmd=rm&dir=name | text/html | Form data sent when user submits the "delete a resource" form. |
| Non-browser | POST | cmd=rmt&dir=name | text/plain | Typically sent from a non-browser client when deleting a resource. |
| Non-browser | DELETE | text/plain | Typically sent from a non-browser client when deleting a resource. |
The client response message to listing directory content requires a more complex composition than the other response messages. For example, the response could be XML, but we have chosen to use JSON. A scripting language such as Python or JavaScript can automatically convert the returned JSON string to an object. Unlike SOAP web-services, web-services based on REST and JSON are very compact and require little processing. For example, the following Python script prints out all resources in the root directory.
The response status code is 200 for a browser client, even if the request fails. The status code for a non-browser client is set to 200 if the operation succeeded or one of 400, 401, 403, 404, 405, 409, 423, 503, and 507 if the operation failed.
The BarracudaDrive resource in the Barracuda Embedded Web server is designed such that it does not differentiate between GET and POST. BarracudaDrive searches for the second argument, the dir=name argument. Therefore, you can create directories by typing in the URL and the URL encoded data in the browser's URL field. For example, you can click the following links in the order listed, if you have BarracudaDrive running on port 80 on your computer:
http://localhost/drive/?cmd=mkdirt&dir;=MkdirTsthttp://localhost/drive/MkdirTst/?cmd=mkdirt&dir;=subdir1
http://localhost/drive/MkdirTst/subdir1?cmd=mkdirt&dir;=subdir2
Using curl
In the following examples, we will use the BarracudaDrive web-file manager for viewing the files and use curl for uploading files. You may have curl already installed on your computer. If not, you will need to download and install curl. Windows users can install the full version of Cygwin and use curl provided by Cygwin.
Windows users can also download the following:
http://curl.haxx.se/latest.cgi?curl=win32-ssl-devel-mingw
http://curl.haxx.se/download/openssl-0.9.7e-win32-bin.zip
In the following examples, we will assume that the server and client run on the same computer. You must substitute 'localhost' with the IP address or domain name of the machine running BarracudaDrive if the client and server are not on the same machine. We also assume that BarracudaDrive is listening on HTTPS port 443.
All examples use the fictive file MyFile.txt. You should substitute the name with a file you can upload/download.
The URL sent from the HTTP client (curl) is mapped onto the physical drive on the server. As explained in the BarracudaDrive introduction, the root path element in the URL must be "drive", for example http://localhost/drive/users/ maps to the physical path c:\users\
Open a console window. Make sure you have curl properly installed by typing curl in the console window.
Try to upload MyFile.txt file to the root directory, i.e., to the c:\ directory. Please see the curl manual for information on the command line switches.
MyFile.txt should now be in the root directory. The following link should list the new file.
https://localhost/drive/?cmd=ls
You can also upload files to any subdirectory.
The command failed since the subdirectory does not exist. You can force BarracudaDrive to create the necessary directory structure by providing the following url encoded data on the command line: mkdir=true.
You can now verify the new upload: