Installation Guide

Prerequisite

nGrinder is a combination of a web application(Controller) and a Java application(Agent).

• To install nGrinder controller, you need to first have Oracle JDK 1.6 and Tomcat 6.X or later.
  • We don't support OpenJDK yet.
  • We don't support IP6
• To install nGrinder agent, all you need is Oracle JDK 1.6
  • We don't support OpenJDK yet.
  • We don't support IP6

If you installed 32bit JVM on your 64bit OS. nGrinder won't work.

If you don’t know what a controller and agent are, please refer to Architecture.

If you like to install nGrinder in Windows XP, please refer link.

Please check your PATH environment variable if your java path is located at the head of PATH so that appropriate java can be run.

• http://www.youtube.com/watch?v=6q0X_pEWA6U (Youtube video for Windows XP)

Download

• You can download nGrinder at the following link.
  • http://sourceforge.net/projects/ngrinder/files 
• Please download the controller and the agent.

Install Controller

1. Please be sure that you configured PATH and JAVA_HOME in advance.
• There are a lot of questions which comes from wrong PATH configuration. You should put java path in the head of PATH env var.
• For example, in windows it should be set as C:\Program Files\Java\Your java Version\bin;BlarBlar...
2. Installing Controller can be done easily, simply by dropping nGrinder's controller war file in the ${TOMCAT_HOME}/webapps folder.
   • If you're not familiar with Tomcat, just download the nGrinder 3.1package bundled with Tomcat.
3. After dropping it into the folder, please add following option in tomcat's  ${TOMCAT_HOME}/catalina.sh(linux) or catalina.bat(windows) file. nGrinder controller has heavy library requirements so you need to have sufficient PermGem memory.
   

   JAVA_OPTS="-Xms600m -Xmx1024m -XX:MaxPermSize=200m"    # for catalina.sh

   set JAVA_OPTS=-Xms600m -Xmx1024m -XX:MaxPermSize=200m   # for catalina.bat

4. Please check if you configured the correct host name and ip mapping.
   
   

    $ hostname
   dev-ngrinder-abnormal.ncl
   $ ping dev-ngrinder-abnormal.ncl
   PING dev-ngrinder-abnormal.ncl.nhnsystem.com (10.101.55.46) 56(84) bytes of data
   # In above, the host name is dev-ngrinder-abnormal.ncl and is mapped to 10.101.55.44.
   # If you see the loopback address like (127.0.0.1), you should modify /etc/hosts 
   # to make it map into real ip.

   
   
5. Then run tomcat using startup.sh(linux) or, startup.bat(windows).
6. Now, access nGrinder using web browser. http://hostname:8080/ngrinder-controller  That’s it! You’re ready to use nGrinder.

• If you want to access ngrinder without any path other than hostname(e.g :http://yourdnsname/), you need to change the name of the war file to ROOT.war.
• If you want to access ngrinder with port 80, you should configure ${TOMCAT_HOME}/conf/server.xml

※ For more detailed nGrinder controller configuration options, please refer to Advanced Controller Configuration

 

Install Agent

• From the perspective of nGrinder, Agent is the java application that does the following:
  • When installed on the target server, it can act as a performance monitoring server.
  • When installed on the agent server, it can act as a stress injection server.
• To configure agents to work as you intend, you need to change some configuration files.

1. Please make sure that you have installed JDK in your agent machine and provide the JAVA_HOME env variable.
2. Installing Agents is really simple.  Just download the agent file and decompress it.
   • Windows:  ngrinder-core-{VersionNumber}-agent-package.zip
   • Linux:  ngrinder-core-{VersionNumber}-agent-package.tar.gz
3. You will find ngrinder-core-{VersionNumber}.jar and several folders.
4. Navigate to the decompressed folder and run the following command. Please note that you should run this in the folder where the nGrinder agent is installed.

5. run_agent.sh or run_agent.bat

6. The agent will then execute and create the .ngrinder_agent folder in your account home.
7. Then, go to the ${user.home}/.ngrinder_agent folder.
   • Window : C:Users{username}.ngrinder_agent or C:Users{username}.ngrinder_agent
   • Linux : /home/{username}/.ngrinder_agent
8. Change the following agent.conf file.
   

   start.mode=agent
   agent.console.ip=please specify your controller IP
   #monitor.listen.port=3243
   #monitor.collector.interval=1
   #monitor.controller.cache.size=128
   #monitor.collector.interval=1
   
   #start.mode=agent
   #agent.console.port=7001
   #If you set up the controller region. please provide the region you use here.
   #agent.region=

9. Then run the agent again.
   

   run_agent.bat (windows) or run_agent.sh & (linux)

10. Now the agent will try to connect to the server. 
11. When you shutdown the agent you can run the following commands.
    

    stop_agent.sh (windows) or stop_agent.bat (linux)

12. To enable agents, you should approve the connected agents. Please refer to the Administration Guide

• Sometimes, java fails to detect the current IP on some Linux distribution package. So the controller might not connect the agent.
  • Easiest way to fix this is to delete 127.0.0.1 localhost entry in your /etc/hosts and put real_ip and your_hostname pair 

 

nGrinder Port

• Agent : Any ==> Controller : 16001
• Agent : Any ==> Controller : 12000 ~ 12000+(the number of concurrent tests allowed)
  • This can be configured.
• Controller : Any ==> Monitor : 13243
• Controller ==> Public user : This is dependent on your tomcat configuration. By default, it is set as 8080.