Saturday, March 12, 2011

Install JBoss 6 on CentOS

This post will cover installing JBoss 6.0 on CentOS 5.x.


If you are looking to install JBoss 7.1.1 CentOS 6, please see:

http://www.davidghedini.com/pg/entry/install_jboss_7_on_centos


We'll also set up JBoss to run as a service, as well as secure the JMX and Web Service consoles.

While there are similarities to JBoss 5.1 installation, the file locations have changed in some instances.

Here is an outline of the steps we will follow:

1. Download and Install the Java Development Kit (JDK)
2. Download and Install JBoss 6.0 Application Server
3. Create the user, jboss, who will own and run JBoss
4. Set the required JAVA_HOME and JBOSS_HOME paths
5. Create a start/stop/restart script for JBoss
6. Configure JBoss to run as a service
7. Access the JBoss Admin console
8. Change the JBoss Admin Password
9. Secure the JMX Console
10. Securing the Web Service Console
11. Set memory parameters for JBoss using JAVA_OPTS
12. Configure JBoss to run on port 80



Step 1: Download and Install the Java Development Kit (JDK)

You can download the JDK here: http://www.oracle.com/technetwork/java/javase/downloads/index.html

I'm using JDK 6, update 26, the latest as of this post. The JDK is specific to 32 and 64 bit versions.

My CentOS box is 64 bit, so I'll need: jdk-6u26-linux-x64.bin

If you are on 32 bit, you'll need: jdk-6u26-linux-i586.bin

Download the appropriate JDK and save it to a directory. I'm saving it to /root.

Move (mv) or copy (cp) the file to the /opt directory:

[root@sv2 ~]# mv jdk-6u26-linux-x64.bin /opt/jdk-6u26-linux-x64.bin

Create the directory /usr/java.

[root@sv2 ~]# mkdir /usr/java

Change to the /usr/java directory we created and install the JDK using 'sh /opt/jdk-6u26-linux-x64.bin'

[root@sv2 ~]# cd /usr/java
[root@sv2 java]# sh /opt/jdk-6u26-linux-x64.bin

We now have the JDK installed at /usr/java/jdk1.6.0_26. We'll use this for our JAVA_HOME a bit later in step



Step 2: Download and Install JBoss 6.0 Application Server

Download jboss-6.0.0.Final.zip at http://sourceforge.net/projects/jboss/files/JBoss/jboss-6.0.0.Final/ or use wget:

[root@sv2 ~]# wget http://sourceforge.net/projects/jboss/files/JBoss/JBoss-6.0.0.Final/jboss-as-distribution-6.0.0.Final.zip/download
.
.
.
100%[======================================>] 181,267,148  816K/s   in 3m 31s

2011-03-13 00:56:44 (839 KB/s) - `jboss-as-distribution-6.0.0.Final.zip' saved [181267148/181267148]


Move (mv) or copy (cp) the file to /usr/share/jboss-6.0.0.Final.zip.

[root@sv2 ~]# mv jboss-as-distribution-6.0.0.Final.zip /usr/share/jboss-as-distribution-6.0.0.Final.zip

Change to the /usr/share directory and unzip the file:

[root@sv2 ~]# cd /usr/share
[root@sv2 share]# unzip -q jboss-as-distribution-6.0.0.Final.zip

The unzip will create the following directory: /usr/share/jboss-6.0.0.Final

This directory will be our JBOSS_HOME, which we will use below in Step 4.


Step 3: Create the user, jboss, who will own and run JBoss


Since we will want to run JBoss as a non-root user with minimal privileges, we'll create a user, jboss, who will own the JBoss files and JBoss will run under his account.

To do this, we can need to the following.

Create a new group, jboss, and then create the user jboss and add the user to the jboss group.

[root@sv2 ~]# groupadd jboss
[root@sv2 ~]# useradd -s /bin/bash -g jboss jboss


Change ownership of the JBoss home directory, /usr/share/jboss-6.0.0.Final so all files are owned by the user jboss we created.

[root@sv2 ~]# chown -Rf jboss.jboss /usr/share/jboss-6.0.0.Final/

Step 4: Set the required JAVA_HOME and JBOSS_HOME paths

We no need to set the JAVA_HOME and JBOSS_HOME.

The JAVA_HOME is where we installed the JDK above, /usr/java/jdk1.6.0_26, and the JBOSS_HOME is where we installed JBoss above /usr/share/jboss-6.0.0.Final.

Add the following to the jboss users .bash_profile:

JAVA_HOME=/usr/java/jdk1.6.0_26
export JAVA_HOME
PATH=$JAVA_HOME/bin:$PATH
export PATH
JBOSS_HOME=/usr/share/jboss-6.0.0.Final
export JBOSS_HOME


To set the JAVA_HOME for users, we add this to the user ~/.bashrc or ~/.bash_profile of the user. We can also add it /etc/profile and then source it to give to all users.

JAVA_HOME=/usr/java/jdk1.6.0_26 
export JAVA_HOME 
PATH=$JAVA_HOME/bin:$PATH 
export PATH

Once you have added the above to ~/.bash_profile or ~/.bashrc, you should su to the user jboss and verify that the JAVA_HOME and JBOSS_HOME are set correctly.

[root@sv2 ~]#  su jboss
[jboss@sv2 ~]#  echo $JAVA_HOME
/usr/java/jdk1.6.0_26
[jboss@sv2 ~]#  echo $JBOSS_HOME
/usr/share/jboss-6.0.0.Final






Step 5: Create a start/stop/restart script for JBoss.

For our JBoss script we will simply copy the existing jboss_init_redhat.sh script located at at /usr/share/jboss-6.0.0.Final/bin, copy it to /etc/init.d and rename it to 'jboss':

So, as root:
[root@sv2 ~]# cd /usr/share/jboss-6.0.0.Final/bin 
[root@sv2 bin]# cp jboss_init_redhat.sh /etc/init.d/jboss

In the jboss script (shown completed below), make the following changes:

1. Add lines 3,4, and 5:

# description: JBoss Start Stop Restart
# processname: jboss
# chkconfig: 234 20 80

2. Line 22, Set the JBOSS_HOME to where we unpacked JBoss in step 2 above:
JBOSS_HOME=${JBOSS_HOME:-"/usr/share/jboss-6.0.0.Final"}

3. Line 28. Set the JAVA_HOME to where we installed the JDK in step 1 above:
JAVAPTH=${JAVAPTH:-"/usr/java/jdk1.6.0_26"}

4. Add line 34, which sets the JBOSS_HOST to 0.0.0.0, allowing JBoss to bind to any IP.
JBOSS_HOST="0.0.0.0"

#!/bin/sh
#
# description: JBoss Start Stop Restart
# processname: jboss6
# chkconfig: 234 20 80
#
# $Id: jboss_init_redhat.sh 81068 2008-11-14 15:14:35Z dimitris@jboss.org $
#
# JBoss Control Script
#
# To use this script run it as root - it will switch to the specified user
#
# Here is a little (and extremely primitive) startup/shutdown script
# for RedHat systems. It assumes that JBoss lives in /usr/local/jboss,
# it's run by user 'jboss' and JDK binaries are in /usr/local/jdk/bin.
# All this can be changed in the script itself. 
#
# Either modify this script for your requirements or just ensure that
# the following variables are set correctly before calling the script.

#define where jboss is - this is the directory containing directories log, bin, conf etc
JBOSS_HOME=${JBOSS_HOME:-"/usr/share/jboss-6.0.0.Final"}

#define the user under which jboss will run, or use 'RUNASIS' to run as the current user
JBOSS_USER=${JBOSS_USER:-"jboss"}

#make sure java is in your path
JAVAPTH=${JAVAPTH:-"/usr/java/jdk1.6.0_26"}

#configuration to use, usually one of 'minimal', 'default', 'all'
JBOSS_CONF=${JBOSS_CONF:-"default"}

#if JBOSS_HOST specified, use -b to bind jboss services to that address
JBOSS_HOST="0.0.0.0"
JBOSS_BIND_ADDR=${JBOSS_HOST:+"-b $JBOSS_HOST"}

#define the classpath for the shutdown class
JBOSSCP=${JBOSSCP:-"$JBOSS_HOME/bin/shutdown.jar:$JBOSS_HOME/client/jnet.jar"}

#define the script to use to start jboss
JBOSSSH=${JBOSSSH:-"$JBOSS_HOME/bin/run.sh -c $JBOSS_CONF $JBOSS_BIND_ADDR"}

if [ "$JBOSS_USER" = "RUNASIS" ]; then
  SUBIT=""
else
  SUBIT="su - $JBOSS_USER -c "
fi

if [ -n "$JBOSS_CONSOLE" -a ! -d "$JBOSS_CONSOLE" ]; then
  # ensure the file exists
  touch $JBOSS_CONSOLE
  if [ ! -z "$SUBIT" ]; then
    chown $JBOSS_USER $JBOSS_CONSOLE
  fi 
fi

if [ -n "$JBOSS_CONSOLE" -a ! -f "$JBOSS_CONSOLE" ]; then
  echo "WARNING: location for saving console log invalid: $JBOSS_CONSOLE"
  echo "WARNING: ignoring it and using /dev/null"
  JBOSS_CONSOLE="/dev/null"
fi

#define what will be done with the console log
JBOSS_CONSOLE=${JBOSS_CONSOLE:-"/dev/null"}

JBOSS_CMD_START="cd $JBOSS_HOME/bin; $JBOSSSH"
JBOSS_CMD_STOP=${JBOSS_CMD_STOP:-"java -classpath $JBOSSCP org.jboss.Shutdown --shutdown"}

if [ -z "`echo $PATH | grep $JAVAPTH`" ]; then
  export PATH=$PATH:$JAVAPTH
fi

if [ ! -d "$JBOSS_HOME" ]; then
  echo JBOSS_HOME does not exist as a valid directory : $JBOSS_HOME
  exit 1
fi

echo JBOSS_CMD_START = $JBOSS_CMD_START

case "$1" in
start)
    cd $JBOSS_HOME/bin
    if [ -z "$SUBIT" ]; then
        eval $JBOSS_CMD_START >${JBOSS_CONSOLE} 2>&1 &
    else
        $SUBIT "$JBOSS_CMD_START >${JBOSS_CONSOLE} 2>&1 &" 
    fi
    ;;
stop)
    if [ -z "$SUBIT" ]; then
        $JBOSS_CMD_STOP
    else
        $SUBIT "$JBOSS_CMD_STOP"
    fi 
    ;;
restart)
    $0 stop
    $0 start
    ;;
*)
    echo "usage: $0 (start|stop|restart|help)"
esac



Step 6: Run JBoss as a Service.

To run JBoss as a service and enable start up at boot, make the script we created above executable and add it to our chkconfig so it starts at boot.

[root@sv2 init.d]# chmod 755 jboss
[root@sv2 init.d]# chkconfig --add jboss
[root@sv2 init.d]# chkconfig --level 234 jboss on


We should now be able to Start, Stop, and Restart JBoss as a service.

Start JBoss:

Note: JBoss can take some time to start.

[root@sv2 init.d]# service jboss start
JBOSS_CMD_START = cd /usr/share/jboss-6.0.0.Final/bin; /usr/share/jboss-6.0.0.Final/bin/run.sh -c default -b 0.0.0.0

Stop JBoss:
[root@sv2 init.d]# service jboss stop
JBOSS_CMD_START = cd /usr/share/jboss-6.0.0.Final/bin; /usr/share/jboss-6.0.0.Final/bin/run.sh -c default -b 0.0.0.0
Shutdown message has been posted to the server.
Server shutdown may take a while - check logfiles for completion



Step 7: Access the JBoss Admin.

Make sure JBoss is started and you should now be able to access the Jboss Console at:

http://yourdomain.com:8080 or http://yourip:8080

The default user name and password for the JBoss Admin Console is admin/admin


Access the Admin Console by clicking on the Administration Console link.










Step 8: Change the JBoss Admin Password

To change the default Admin Console password, go to:

/usr/share/jboss-6.0.0.Final/server/default/conf/props

Open the jmx-console-users.properties file in text editor and change the password.

# A sample users.properties file for use with the UsersRolesLoginModule
admin=MyPassword


Step 9: Secure the JMX Console

To secure the JMX Console, go to:

/usr/share/jboss-6.0.0.Final/common/deploy/jmx-console.war/WEB-INF

First, edit the web.xml file. Towards the bottom, you will find the security-constraint as shown below:

<!-- A security constraint that restricts access to the HTML JMX console
   to users with the role JBossAdmin. Edit the roles to what you want and
   uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
   secured access to the HTML JMX console.
   <security-constraint>
     <web-resource-collection>
       <web-resource-name>HtmlAdaptor</web-resource-name>
       <description>An example security config that only allows users with the
         role JBossAdmin to access the HTML JMX console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>JBossAdmin</role-name>
     </auth-constraint>
   </security-constraint>
   -->

Un-comment the security-constraint section so it appears thus:


<security-constraint>
     <web-resource-collection>
       <web-resource-name>HtmlAdaptor</web-resource-name>
       <description>An example security config that only allows users with the
         role JBossAdmin to access the HTML JMX console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>JBossAdmin</role-name>
     </auth-constraint>
   </security-constraint>

Next, still in the WEB-INF directory, edit the jboss-web.xml file, which will look as below:

<!DOCTYPE jboss-web PUBLIC
   "-//JBoss//DTD Web Application 5.0//EN"
   "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
   
<jboss-web>
   <!-- Uncomment the security-domain to enable security. You will
      need to edit the htmladaptor login configuration to setup the
      login modules used to authentication users.
      <security-domain>java:/jaas/jmx-console</security-domain>
   -->
</jboss-web>

Uncomment the security-domain so it appears thus:

<!DOCTYPE jboss-web PUBLIC
   "-//JBoss//DTD Web Application 5.0//EN"
   "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
   
<jboss-web>
   
      <security-domain>java:/jaas/jmx-console</security-domain>
   
</jboss-web>

At this point, the password for the JMX Console will be the same as the password we set for the Admin Console in step 8 above.

Both the Admin Console and JMX Console are are using the jmx-console-roles.properties and jmx-console-users.properties files.



Step 10: Secure the Web Service Console

To secure the Web Service Console, go to:

/usr/share/jboss-6.0.0.Final/common/deploy/jbossws-console.war/WEB-INF

First, edit the web.xml file. Towards the bottom, you will find the security-constraint as shown below:

<!-- A security constraint that restricts access
   <security-constraint>
     <web-resource-collection>
       <web-resource-name>ContextServlet</web-resource-name>
       <description>An example security config that only allows users with the
         role 'friend' to access the JBossWS console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>friend</role-name>
     </auth-constraint>
   </security-constraint>
   -->

Un-comment the security-constraint section so it appears thus:


<security-constraint>
     <web-resource-collection>
       <web-resource-name>ContextServlet</web-resource-name>
       <description>An example security config that only allows users with the
         role 'friend' to access the JBossWS console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>friend</role-name>
     </auth-constraint>
   </security-constraint>

Next, still in the WEB-INF directory, edit the jboss-web.xml file, which will look as below:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE jboss-web
    PUBLIC "-//JBoss//DTD Web Application 2.3V2//EN"
    "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd">

<jboss-web>

  <!-- A security domain that restricts access
  <security-domain>java:/jaas/JBossWS</security-domain>
  -->
  
  <context-root>jbossws</context-root>

</jboss-web>

Uncomment the security-domain so it appears thus:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE jboss-web
    PUBLIC "-//JBoss//DTD Web Application 2.3V2//EN"
    "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd">

<jboss-web>

 
  <security-domain>java:/jaas/JBossWS</security-domain>
 
  
  <context-root>jbossws</context-root>

</jboss-web>


The default user name and password are kermit/thefrog

To change this, go to:

/usr/share/jboss-6.0.0.Final/server/default/conf/props

Open jbossws-roles.properties in a text editor it should appear as below.

# A sample roles.properties file for use with the UsersRolesLoginModule
kermit=friend
Change 'kermit' to a new user name. For example, we'll change it to 'mywsuser' as shown below:

# A sample roles.properties file for use with the UsersRolesLoginModule
mywsuser=friend


Open jbossws-users.properties in a text editor it should appear as below.

# A sample users.properties file for use with the UsersRolesLoginModule
kermit=thefrog

Change 'kermit' to our new user name 'mywsuser' and change the password. For example, we'll change the password to it to 'MyWsPassword' as shown below:

# A sample users.properties file for use with the UsersRolesLoginModule
mywsuser=MyWsPassword


Step 11: Set JAVA_OPTS Memory Parameters


To set the memory limits for JBoss,

Got to: /usr/share/jboss-6.0.0.Final/bin

Open the run.sh file in a text editor.

Find the section below:
# Setup JBoss specific properties
JAVA_OPTS="-Dprogram.name=$PROGNAME $JAVA_OPTS"

Directly below this, add the desired parameters.

# Setup JBoss specific properties
JAVA_OPTS="-Dprogram.name=$PROGNAME $JAVA_OPTS"
JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx256m"

I'm installing this on a small VPS so I'm using JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx256m". You should set this to whatever is appropriate to your server and application.

Step 12: Running JBoss on Port 80.

To run services below port 1024 as user other than root, you can use port forwarding.

You can do this by adding the following to your IP tables:

[root@sv2 ~]# iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
[root@sv2 ~]# iptables -t nat -A PREROUTING -p udp -m udp --dport 80 -j REDIRECT --to-ports 8080

Be sure to save and then restart your IP Tables for the above to take effect.

Happy JBoss'ing.

6 comments:

Anonymous said...

good work

Anonymous said...

Dear David,

awesome HOWTO,
I've learn allot ..

thx,

Anonymous said...

The best and most complete installation guide I have found!
One minor issue: to start/stop the service, I think it must be:
"service jboss start" (not jboss6).

If I do
service jboss status
I get:
JBOSS_CMD_START = cd /usr/share/jboss-6.0.0.Final/bin; /usr/share/jboss-6.0.0.Final/bin/run.sh -c default -b 0.0.0.0
usage: /etc/init.d/jboss (start|stop|restart|help)
and not the information if the service is running.

David Ghedini said...

Hi -

Glad you found it useful. Thank you for noticing the typo with 'jboss6'. I've corrected this above.

DavidW said...

Thanks - very useful.

international calls said...

This is a great article. Thank you. How can I setup multiple websites (running SSL) under one jboss instance? I have 12GB RAM server with one JBoss 6.1 instance. I want to know how can I deploy multiple web apps (.war files), each of them accessible via https://www.xyz.com , https://www.abc.com (without any context root).

Any suggestions/solutions are highly appreciated.