The installation of the SPLAY controller includes a web server that responds to JSON-RPC calls over HTTP. This allows users to send commands to the controller remotely, from any computer that has network connectivity with the SPLAY controller. This command server is used by the SPLAY command-line interface, and can be used for implementing new interfaces. Instructions for installing the command-line interface (typically on a different machine where the remaining of the SPLAY toolbox is not installed) can be found here.

If you want to go deeper on the understanding of the JSON-RPC API that are behind the commands, or you are interested in developing you own client, the detailed explanation of the API is here.

Once you have installed the client, you can test the commands with the sample run provided in this tutorial. A command with the -h or --help flag outputs a detailed explanation of all the options that you have at your disposition when using the given command.

Remember that, in order to test the commands, you must have the controller running along with some registered splayds.

A. Change admin's password

After a fresh install of the controller, the only user on the system is admin, with password admin. This user is, of course, the Administrator, the only one who has the possibility to create and remove users, and can also see or kill any job created on SPLAY.

So, the first step you should do is to change this password:

./splay-change-passwd.lua -u admin -p admin -n newpasswd -i your.splay.controller

where newpasswd is the password you want to have as Administrator. If you are not comfortable with the idea of typing the password on the command line, you can call the command without these options, and the program will ask you explicitly for the password, without showing it on the screen:

./splay-change-passwd.lua -i your.splay.controller
Administrator's username:
admin
Current password:
[type]
New password:
[type]

The option "-i" instructs the program to convert your.splay.controller into the URL form http://your.splay.controller:2222/json-rpc, using port 2222 and json-rpc as page, which are the default values. If you changed this parameters on the file rpc_server/rpc-server.rb on the controller side, you can type the complete URL when the option -i is not present.

If the procedure was successful, the program should output:

USERNAME       = your_username
RPC SERVER URL = http://your.splay.controller:2222/json-rpc

Sending command to http://your.splay.controller:2222/json-rpc...

Response from http://your.splay.controller:2222/json-rpc:
Password changed

There is also the possibility of fixing parameters like username, password and server URL by filling them on the file splay_cli_config.lua, in the following format:

config={
	rpc_server_url="http://127.0.0.1:2222/json-rpc",
	username="admin",
	password="admin",
	}

B. Creating/Removing users

The Administrator is the only one able to create and remove users. These users will be able to check how many splayds are on the system, submit jobs, and kill or get data (general info / logs) about jobs that were submitted by them.

To create a new user simply type:

./splay-new-user.lua -i -U admin -u newusername your.splay.controller

The program will ask you for the passwords of the Administrator and the new user. If the addition was successful, the program will display "User added" and the ID of the new user:

User added.
User ID = 2

To remove a user type:

./splay-remove-user.lua -i -U admin -u username your.splay.controller

The program will ask you for the password of the Administrator. If the removal was successful, the program will display "User removed".

C. Starting a session

Once you added new regular users, these users (also the Administrator) can start a session. To ease the creation of scripts that involve the SPLAY commands, all the other commands are session-oriented. That means, you start a session, the SPLAY controller will give you a unique session ID, valid for 24 hours, and this session will identify you without need of retyping your username or password.

To start a new session, type:

./splay-start-session.lua -i -u username -p password your.splay.controller

Or as usual, you can let the program ask you the username and password interactively.

If the session was successfully started, the program will display:

SESSION_ID = d9170e2f75a3596ecb3d247a606f4d579164c38f
EXPIRES_AT = 2000-01-01 00:00:00

This Session ID will be stored in a file associated with the SPLAY controller name. That means that you can keep one session per SPLAY controller per machine. If you start a session with a different user, the new session ID will overwrite the current one.

D. Checking the available splayds

To check the splayds and their status, type:

bash$ ./splay-list-splayds.lua -i your.splay.controller
SESSION_ID = d9170e2f75a3596ecb3d247a606f4d579164c38f
RPC SERVER URL   = http://your.splay.controller:2222/json-rpc

Sending command to http://your.splay.controller:2222/json-rpc...

Response from http://your.splay.controller:2222/json-rpc:
Splayd List =
        splayd_id=1, ip=10.0.0.1, status=AVAILABLE
                key=splayd1
        splayd_id=2, ip=10.0.0.2, status=RESET
                key=splay_number2
        splayd_id=3, ip=10.0.0.3, status=AVAILABLE
                key=pl.server.ws
bash$

If there are enough splayds with status "AVAILABLE" to execute your code, you can try to submit jobs.

E. Submitting, checking and killing jobs

Now you can submit a job. The SPLAY commands come with a file sample.lua, that you can use to test SPLAY for the first time. To submit sample.lua to be executed by 4 nodes, type:

bash$ ./splay-submit-job.lua -i -n 4 sample.lua your.splay.controller
DESCRIPTION      =
CODE_FILE        = sample.lua
NB_SPLAYDS       = 4
OPTIONS          =
SESSION_ID       = d9170e2f75a3596ecb3d247a606f4d579164c38f
RPC SERVER URL   = http://your.splay.controller:2222/json-rpc

Sending command to http://your.splay.controller:2222/json-rpc...

Response from http://your.splay.controller:2222/json-rpc:
Job Submitted:
JOB_ID           = 1
REF              = 0b096d2193f66de88ce842d2303cb12f
bash$

By adding the option "-d", the program will ask you a short description of the job to be submitted.

To check details about a job, type:

bash$ ./splay-get-job-details.lua 1 -i your.splay.controller
JOB_ID     = 1
SESSION_ID = d9170e2f75a3596ecb3d247a606f4d579164c38f
RPC SERVER URL   = http://your.splay.controller:2222/json-rpc

Sending command to http://your.splay.controller:2222/json-rpc...

Response from http://your.splay.controller:2222/json-rpc:

Description =
Ref         = 0b096d2193f66de88ce842d2303cb12f
Status      = ENDED
Host list =
        splayd_id=1, ip=10.0.0.2, port=27654
        splayd_id=2, ip=10.0.0.4, port=31959
        splayd_id=3, ip=10.0.0.7, port=30694
        splayd_id=4, ip=10.0.0.15, port=28877
bash$

To get the logs, type:

./splay-get-log.lua -i 1 your.splay.controller

If the log is retrieved, the program will display "Log from JOB 1 successfully retrieved", and the log will be stored in the file log_1.txt.

You can also kill a job, by typing:

./splay-kill-job.lua 1 -i your.splay.controller

If the KILL command was successfully sent (a KILL command can be sent also to jobs that have already ended), the program will display "KILL command successfully sent". We hope that this tutorial has helped you to understand the use of the SPLAY commands. Now, it's time for you to create new jobs and have fun! Thanks for your interest in SPLAY.