Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Serengeti Web Service and CLI code

Fetching latest commit…

Cannot retrieve the latest commit at this time

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)


Method URL Template Request Response Description
GET /hello void void
GET /tasks void List of TaskRead List all tasks
GET /task/{taskId} taskId TaskRead Get task by task id
POST /clusters ClusterCreate Redirect to /task/{taskId} Create cluster
GET /clusters void List of ClusterRead List all clusters
GET /cluster/{clusterName} clusterName ClusterRead Get cluster by name
GET /cluster/{clusterName}/spec clusterName ClusterCreate Get cluster specification by name
PUT /cluster/{clusterName} clusterName; state=start/stop/resume Redirect to /task/{taskId} Operate a cluster: start; stop or resume a failed creation
PUT /cluster/{clusterName}/nodegroup/{groupName} clusterName; groupName; instanceNum Redirect to /task/{taskId} Resize cluster with a new instance number
DELETE /cluster/{clusterName} clusterName Redirect to /task/{taskId} Delete a cluster by name
POST /resourcepools ResourcePoolAdd void Add a resource pool
GET /resourcepools void List of ResourcePoolRead List all resource pools
GET /resourcepool/{rpName} rpName ResourcePoolRead Get resource pool by name
DELETE /resourcepool/{rpName} rpName void Delete a resource pool by name
POST /datastores DatastoreAdd void Add a datastore
GET /datastores void List of DatastoreRead List all datastores
GET /datastore/{dsName} dsName DatastoreRead Get datastore by name
DELETE /datastore/{dsName} dsName void Delete a datastore by name
POST /networks NetworkAdd void Add a network
GET /networks details=true/false List of NetworkRead List all networks
GET /network/{networkName} networkName; details=true/false NetworkRead Get a network by name
DELETE /network/{networkName} networkName void Delete a network by name
GET /distros void List of DistroRead List all distros
GET /distro/{distroName} distroName DistroRead Get 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/tomcat6/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/tomcat6/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/tomcat6/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.

Something went wrong with that request. Please try again.