Red Hat Enterprise Virtualization REST API 0.9

REST API Installation Guide

Installing the REST API on Red Hat Enterprise Virtualization 2.2

Edition 0

Community Project

James Rankin

Red Hat Solutions

jrankin@redhat.com

David Jorm

Red Hat Engineering Content Services

djorm@redhat.com

Legal Notice

Copyright © 2011 Red Hat, Inc. This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).

Abstract

This document describes the procedure for installing the REST API on Red Hat Enterprise Virtualization 2.2.

Preface

1. Document Conventions

1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings

2. We Need Feedback!

1. Installing the REST API

1.1. Overview
1.2. Java and environment variables
1.3. Installing JBoss
1.4. Installing the REST API
1.5. Running JBoss
1.6. Starting JBoss on boot
1.7. Validating the installation using a web browser
1.8. Validating the installation using a REST client

A. Revision History

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:

Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session.

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.

Output sent to a terminal is set in mono-spaced roman and presented thus:

books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs

Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:

package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a ticket in Track: https://fedorahosted.org/rhevm-api/newticket/ or send a report by email to the project mailing list (rhevm-api@lists.fedorahosted.org ).

Chapter 1. Installing the REST API

1.1. Overview
1.2. Java and environment variables
1.3. Installing JBoss
1.4. Installing the REST API
1.5. Running JBoss
1.6. Starting JBoss on boot
1.7. Validating the installation using a web browser
1.8. Validating the installation using a REST client

1.1. Overview

This guide outlines how a Red Hat Enterprise Virtualization administrator may add the REST API developer preview onto an existing Red Hat Enterprise Virtualization 2.2 installation. Please ensure the Red Hat Enterprise Virtualization 2.2 environment is installed and operational before installing the REST API.

Note

The REST API will be bundled with the Red Hat Enterprise Virtualization Manager in version 2.3. The procedure in this guide applies only to Red Hat Enterprise Virtualization 2.2.

The REST API developer preview homepage is:

https://fedorahosted.org/rhevm-api/

The developer documentation for the API is available at:

http://markmc.fedorapeople.org/rhevm-api/en-US/html/index.html

The workflow for installing the REST API is as follows:

Figure 1.1. Installation workflow

1.2. Java and environment variables

The REST API runs on an embedded JBoss Application Server. To support this, the Oracle JDK must be installed onto the Red Hat Enterprise Virtualization Manager server. To install the JDK:

Download the current 64 bit JDK to the Red Hat Enterprise Virtualization Manager server. At the time of the writing, the current JDK is Java 6 Update 22. The JDK download is available at the Java SE landing page: http://www.oracle.com/technetwork/java/javase/downloads/index.html
Install the JDK onto the Red Hat Enterprise Virtualization Manager server.
After installation of the JDK, the %JAVA_HOME% environment variable must be set to the JDK path; the JBoss Application Server will not start unless this variable is correctly defined.
To set the %JAVA_HOME% variable on the Red Hat Enterprise Virtualization Manager server, click Start, then right-click Computer and choose Properties. Toward the upper left of the System Properties window, click the Advanced system settings link. Next, click the Environment Variables... box, as shown below.

In the Environment Variables window, click the New button, and set the JAVA_HOME variable to the path to your newly installed JDK. In the example below, the variable is set to the default path for the 64 bit JDK 6u22 install.

1.3. Installing JBoss

Once the JDK is installed, download version 5.1.0 of the JBoss Application Server from:

http://sourceforge.net/projects/jboss/files/JBoss/JBoss-5.1.0.GA/jboss-5.1.0.GA.zip/download

Install JBoss by unzipping it into a directory of your choice. In the example below, JBoss was placed in the C:\Program Files\ directory.

1.4. Installing the REST API

To install the REST API follow these steps:

Download the current milestone release of the REST API from the REST API homepage on fedorahosted.org:
https://fedorahosted.org/rhevm-api/wiki/milestones
Unzip the API zip file into C:\Program Files, or any other location. Once unzipped, navigate into the webapp folder of the REST API. Copy the rhevm-api-powershell.war file and then paste it into the \server\default\deploy directory inside the JBoss install, as shown below.
Next, create a certificate for https communication (which is also described in the README_HTTPS file). To do this, open a command prompt in Windows as an Administrator. Navigate to the Command Prompt icon in the Start menu, right-click it, and choose Run as Administrator. If the command prompt is not opened as an administrator, then you will not have write access into Program Files. With the command prompt open, navigate to your JBoss\server\default\conf directory, and run the following Java keytool command to generate a certificate:
"C:\Program Files\Java\jdk1.6.0_22\bin\keytool.exe" -genkey -alias rhevm -keyalg RSA -keystore rhevm-keystore -keypass redhat -storepass redhat
In this example, note that the path to keytool.exe is fully qualified and in quotes. If using a JDK other than 6U22, this path would be different, so using tab completion is advised. Also, note that the redhat values in this command are certificate passwords; please change these to any value you prefer. After running the keytool.exe command, answer the certificate creation questions when prompted. An example is below.
After creating the certificate, the next step is to modify the server.xml file in the JBoss install. Start WordPad as an Administrator and navigate to $JBOSS_HOME\server\default\deploy\jbossweb.sar\ and open server.xml. With the server.xml file open, find the following section:
```

```
First, ensure that the SSL/TLS Connector... stanza is no longer commented out; these lines are commented out by default. Next, modify the keystoreFile and keystorePass values to correspond to the filename and passwords chosen when creating the certificate. Since the example here uses rhevm-keystore as the keystore file and redhat as the password, the server.xml should be edited as shown below:
```

<Connector protocol="HTTP/1.1" SSLEnabled="true"
port="8443" address="${jboss.bind.address}"
scheme="https" secure="true" clientAuth="false"
keystoreFile="${jboss.server.home.dir}/conf/rhevm-keystore"
keystorePass="redhat" sslProtocol = "TLS" />
```
Notice again how the comment at the beginning of the stanza is now closed at the end of the first line. After making these changes, save the file in WordPad.

Next configure JBoss to listen in all interfaces and set a port offset to avoid conflicts with the ports used by RHEV. This can be accomplished by editing the file run.bat. Find the following section:

if "x%JAVA_OPTS%" == "x" (
  set "JAVA_OPTS=-Dprogram.name=%PROGNAME%"
) else (
  set "JAVA_OPTS=-Dprogram.name=%PROGNAME% %JAVA_OPTS%"
)

And edit this as shown below:

if "x%JAVA_OPTS%" == "x" (
  set "JAVA_OPTS=-Dprogram.name=%PROGNAME% -Djboss.bind.address=0.0.0.0 -Djboss.service.binding.set=ports-01"
) else (
  set "JAVA_OPTS=-Dprogram.name=%PROGNAME% -Djboss.bind.address=0.0.0.0 -Djboss.service.binding.set=ports-01 %JAVA_OPTS%"
)

Save the file and exit WordPad.

1.5. Running JBoss

Open a command prompt as an Administrator and navigate to the JBoss directory. Run the following command in the JBoss directory to start the JBoss Application Server:

.\bin\run.bat

Warning

When using the Powershell backend, JBoss should NOT be run as the RHEV Administrator user (typically rhevadmin)

Once JBoss starts, you'll see the output similar to the example below. Starting JBoss and the REST API may take a minute.

Before moving to the next step, it's recommended to test the API with the instructions provided in the section "Validating the installation using a web browser".

1.6. Starting JBoss on boot

Once the JBoss Application Server starts correctly on the command prompt, one way to automatically start this service on Windows Server's boot is by using JBossNative, which will configure JBoss to start as a Windows Service. To use this method run the following command:

cd $JBOSS_HOME\bin

.\service.bat install

Now click on the Start menu and choose Administrative Tools -> Services. A new service called JBoss Application Server 5.1 should be in the list. Right click over the service and select Properties. To finish the setup, change the Startup type from Manual to Automatic and click OK.

Note

When running in service mode the console output is redirected to the file run.log. You can inspect the file for any errors during service startup.

Please refer to the file bin\README-service.txt if need extra instructions or how to unistall the service.

1.7. Validating the installation using a web browser

REST API functionality can be easily verified using any web browser. Start Internet Explorer or Firefox and navigate to:

https://<rhevm-IP-address-or-FQDN>:8543/rhevm-api-powershell/

Note that connections to the API will be on port 8543. If the Windows Firewall is enabled, ensure that this port is open.

Since the SSL certificate is self-signed, accept the IE or Firefox security warning. To prevent this warning from occurring again, import the certificate.

Next, you will be prompted to provide Red Hat Enterprise Virtualization Administrator credentials. Note that the username syntax is required to be <username>@<domain-name>. In the example below, the username is rhevadmin and the domain is jrlab.local.

Once Red Hat Enterprise Virtualization Administrator credentials are provided, the API will output XML similar to the example below.

Also browse to the /rhevm-api-powershell/vms and other URLs to see more information on your Red Hat Enterprise Virtualization environment. Please consult the Red Hat Enterprise Virtualization REST API Guide for additional options and details.

1.8. Validating the installation using a REST client

Another easy way to test the REST API is with the java rest-client available on Google Code:

http://code.google.com/p/rest-client/

Download the jar file for the rest-client from the project homepage. On Windows, double click the jar file to run the client. On Linux, issue the command java -jar <jar-file-name>.
To configure the rest-client, provide a URL to the client, just as when testing the API via a web browser. Under the Auth tab, choose BASIC authentication and provide Red Hat Enterprise Virtualization Administrator credentials, as shown below:
Click on the SSL tab and provide the client with a copy of the rhevm-keystore file that was created during the earlier setup process. Also provide the trust store password; in this example, the trust store password was set to redhat.
Change the hostname verifier to allow all as shown below:
To run the GET query, click the green button to the right of the URL field. After processing the query, click on the Body tab under HTTP Response to view the XML response:

The rest-client may also be used to issue POST and PUT requests to the API. Please consult the Red Hat Enterprise Virtualization REST API Guide or the rhev-api mailing list for more details.

Revision History

Revision History

Revision 0

Wed Feb 23 2011

David Jorm

Initial creation