Serengeti Web Service and CLI code
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

serengeti-ws: Serengeti's Web Service and CLI

Serengeti is an open source project initiated by VMware to enable the rapid deployment of an Apache Hadoop cluster on a virtual platform.

This repository contains the code for the Serengeti Web Service and CLI.

Getting Started

To jump into using Serengeti, follow our ![Installation Guide] (

Serengeti Web Service

Serengeti Web Service provides a RESTful API for resources managment and hadoop cluster management running on vSphere. It works as a proxy to invoke the Serengeti provisioning engine and return fine-grained process execution status to the caller.

Web Application architecture

Web service architecture (doc/ws-architecture.png)


MethodURL TemplateRequestResponseDescription
GET/tasksvoidList of TaskReadList all tasks
GET/task/{taskId}taskIdTaskReadGet task by task id
POST/clustersClusterCreateRedirect to /task/{taskId}Create cluster
GET/clustersvoidList of ClusterReadList all clusters
GET/cluster/{clusterName}clusterNameClusterReadGet cluster by name
GET/cluster/{clusterName}/specclusterNameClusterCreateGet cluster specification by name
PUT/cluster/{clusterName}clusterName; state=start/stop/resumeRedirect to /task/{taskId}Operate a cluster: start; stop or resume a failed creation
PUT/cluster/{clusterName}/nodegroup/{groupName}clusterName; groupName; instanceNumRedirect to /task/{taskId}Resize cluster with a new instance number
DELETE/cluster/{clusterName}clusterNameRedirect to /task/{taskId}Delete a cluster by name
POST/resourcepoolsResourcePoolAddvoidAdd a resource pool
GET/resourcepoolsvoidList of ResourcePoolReadList all resource pools
GET/resourcepool/{rpName}rpNameResourcePoolReadGet resource pool by name
DELETE/resourcepool/{rpName}rpNamevoidDelete a resource pool by name
POST/datastoresDatastoreAddvoidAdd a datastore
GET/datastoresvoidList of DatastoreReadList all datastores
GET/datastore/{dsName}dsNameDatastoreReadGet datastore by name
DELETE/datastore/{dsName}dsNamevoidDelete a datastore by name
POST/networksNetworkAddvoidAdd a network
GET/networksdetails=true/falseList of NetworkReadList all networks
GET/network/{networkName}networkName; details=true/falseNetworkReadGet a network by name
DELETE/network/{networkName}networkNamevoidDelete a network by name
GET/distrosvoidList of DistroReadList all distros
GET/distro/{distroName}distroNameDistroReadGet a distro by name
Note: The url of all REST APIs is prefixed with https://hostname:8443/serengeti/api .


Spring security In-Memory Authentication is used for Serengeti Authentication and user management.

We don't provide html or JSPs for login, instead, the Spring default standard URL is used. User needs to set j_username and j_password and then POST login information to URL /serengeti/j_spring_security_check for authentication, e.g. send POST to https://localhost:8443/serengeti/j_spring_security_check?j_username=serengeti&j_password=password .

Navigate to URL /serengeti/j_spring_security_logout means logout, and the session will be removed from server side.

Session timeout

If the user session is idle more than 30 mintues, server will invalidate the session. The timeout can be set in /opt/serengeti/tomcat/webapps/serengeti/WEB-INF/web.xml in following format:

  <session-timeout>30</session-timeout>    <!-- 30 minutes -->

Add/Delete a User in Serengeti

Add or delete user at /opt/serengeti/tomcat/webapps/serengeti/WEB-INF/spring-security-context.xml file, user-service element. Following is a sample to add one user into user-service.

<authentication-manager alias="authenticationManager">
        <user name="serengeti" password="password" authorities="ROLE_ADMIN"/>
        <user name="joe" password="password" authorities="ROLE_ADMIN"/>

The authorities value should define user role in Serengeti, but in M2, it’s not used.

Modify User Password

Change password is in the same element at /opt/serengeti/tomcat/webapps/serengeti/WEB-INF/spring-security-context.xml file.

<authentication-manager alias="authenticationManager">
        <user name="serengeti" password="password" authorities="ROLE_ADMIN"/>
        <user name="joe" password="welcome1" authorities="ROLE_ADMIN"/>

Serengeti CLI

The CLI is built using the Spring Shell project. The CLI supports an interactive shell mode, a command line mode, and execution of script files. After compiling, you can find the jar file under cli/target directory.

  • Shell mode: java -jar serengeti-cli-0.1.jar. It supports tab key based command hint and completion. It supports history by up/down arrows.

  • Command line mode: java -jar serengeti-cli-0.1.jar "command1;command2..."

  • Execution of script file: in shell mode or command line mode, execute "script --file scriptFileName". The shell history file named cli.log will help to generate the script file.

More details can be found at cli/ Some sample cluster creation specification files can be found at cli/samples.

Build serengeti webservice and cli

You need to have maven installed. Please reference our ![Installation Guide] ( to install maven if you don't have it.

If your server is behind a proxy, add following config into maven-settings.xml and make sure the right proxy setting.


then cd $SERENGETI_HOME/src/serengeti-ws

  mvn package -s maven-settings.xml


You can download a complete Serengeti distribution on There are no published maven artifacts at this time, stay tuned.


You can find a link to the user guide here.

Issue Tracking

Serengei's JIRA issue tracker can be found here


Pull requests are welcome; see the contributor guidelines.

Staying in touch

Follow @VMWserengeti on Twitter. You can get help with technical issues, ask questions, and share your experiences with Serengeti on the mailing list serengeti-user. To discuss the development of Serengeti sign up on the serengeti-dev mailing list.