Open Source RDBMS - Seamless, Scalable, Stable and Free

한국어 | Login |Register

Installation Guide

This contains the installation guide for nGrinder 3.3 or later. If you want to see the previous version's installation guide, Please visit Installation Guide - version 3.2
This guide shows how to install nGrinder 3.3 or later.


  • nGrinder is a combination of a web application(Controller) and Java applications(Agent, Monitor). If you don’t know what a controller and agent are, please refer to Architecture.
    To install nGrinder controller and agent, you need Oracle JDK 1.6~ or OpenJDK 1.7~.
  • Please check your PATH environment variable if your java path is located at the head of PATH so that appropriate java can be run.
  • nGrinder uses many ports to communicate with agent and agent. If some ports are blocked by your firewall, you should ask the network admin to open the following ports in the firewall. These ports can be configured by the configuration.
    • Agent : Any ==> Controller : 16001 
    • Agent : Any ==> Controller : 12000 ~ 12000+(the number of concurrent tests allowed)
    • Controller : Any ==> Monitor : 13243
    • Controller ==> Public user : This is dependent on your tomcat configuration. By default, it is set as 8080.


You can download nGridner controller from the following link.

Install Controller

nGrinder is distributed as a self executable web archive file(WAR) file just like Jenkins, you can put this archive file into your familar web application server (like Tomcat) or run the package in the command line.
Be careful, Never locate the war file in the space containing folder like "C:\Program Files\Tomcat\webapps\".

Run as a self executable

  1. Please make sure that you configured PATH and JAVA_HOME properly in advance.
    There are a lot of questions by the 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. Run nGrinder controller with the following command.
    java -jar ngrinder-controller-X.X.war
  3. Then you will see the following error message. nGrinder requires very big PermGen memory because it includes very many libraries such as  SVNKit, maven, Jetty webserver, groovy, and python. Re-run the ngrinder with the PermGen settings.
    nGrinder needs quite big perm-gen memory.
    Please run nGrinder with the following command.
    java -XX:MaxPermSize=200m -jar  ngrinder-controller-3.3.war
  4. By default, nGrinder uses 8080 for web server port. If you want to use the other port, please assign --port port_number as a parameter.
    java -XX:MaxPermSize=200m -jar  ngrinder-controller-3.3.war --port 80
  5. While exuecting the war file, the war will be extracted into ~/.ngrinder/webapp folder and creates serveral default data files like DBs into .ngrinder folder.
  6. If you can see the following logs in the screen, The ngridner controller is now ready to run.
    INFO 14. 1. 20 오후 4:39:liquibase: ChangeSet ngrinder_datachange_logfile/db.changelog_schema_22.xml::22::ngrinder.3.3 r
    an successfully in 4ms
    INFO 14. 1. 20 오후 4:39:liquibase: ChangeSet ngrinder_datachange_logfile/db.changelog_schema_23.xml::23::ngrinder.3.3 r
    an successfully in 7ms
    INFO 14. 1. 20 오후 4:39:liquibase: ChangeSet ngrinder_datachange_logfile/db.changelog_schema_24.xml::24::ngrinder.3.3 r
    an successfully in 2ms
    INFO 14. 1. 20 오후 4:39:liquibase: ChangeSet ngrinder_datachange_logfile/db.changelog_schema_25.xml::25::ngrinder.3.3 r
    an successfully in 7ms
    INFO 14. 1. 20 오후 4:39:liquibase: ChangeSet ngrinder_datachange_logfile/db.changelog_schema_26.xml::26::ngrinder.3.3 r
    an successfully in 8ms
    2014-01-20 16:39:30.633:INFO:/:Initializing Spring FrameworkServlet 'appServlet'
    2014-01-20 16:39:31.141:INFO::Started SocketConnector@@
  7. Then open the browser and go to http://localhost:8080/

Run on Tomcat

  1. Put the war file in the tomcat’s webapps folder ${TOMCAT_HOME}/webapps . If you want to access the ngrinder without the ngrinder-controller context path, you should change the war file name as ROOT.war.
  2. Then open in or catalina.bat and put the following line in the head of the file.
    JAVA_OPTS="-Xms600m -Xmx1024m -XX:MaxPermSize=200m"    # for

    set JAVA_OPTS=-Xms600m -Xmx1024m -XX:MaxPermSize=200m   # for catalina.bat
  3. Then run ${TOMCAT_HOME}/ or startup.bat
  4. Open the browser and go to http://localhost:8080/ngrinder-controller-X.X or http://localhost:8080 if you changed the war file name to ROOT.war


  • nGrinder supports multiple regions(runnging separate sets of agents belong to the multiple network zone) by clustering multiple controllers. See Controller Clustering Guide.
  • There are many configurable options which make nGrinder customized for each needs. See Controller Configuration Guide.

Install Agents

Not like previous nGrinder, nGrinder 3.3 agents is downloaded from the controller. The downloaded agent package already contains the default agent configuration connecting to the controller from which the agent is downloaded.
So just unpacking the tar file and running “” or “run_agent.bat” make the agent connect to the controller.

  1. Log in as admin. The default admin password is admin as well.
  2. Click the top-right menu and click the Download Agent menu.
    Because you’re logged in as admin, the downloadable agent package contains the configurations which let the agents shared by all user.
    If you logged in as not admin account, the link is changed to “Download Private Agent” containning the configurations which let the agents only occupied by the current user.
    See Private Agent for details.
  3. The tar archive which contains agent will be downloaded soon.
    • tar file can be extracted using 7zip in Windows or tar xvf tar_file.tar command.
  4. Then untar the archive and run or run_agent.bat. the agent will be executed using following logic.
    1. Check the ~/.ngrinder_agent folder and see the configuration(agent.conf) is there
    2. If it does not exist, copy the current folder’s __agent.conf file into ~/.ngrinder_agent/agent.conf and load it.
    3. If it exists, just run with existing configuration in ~/.ngrinder_agent/agent.conf.
  5. If you like to overwrite the existing configuration with latest configuration, please put ‘-o‘ option as a parameter -o # for linux / mac -o # If you want to run it in the background for linux / mac
    run_agent.bat –o # for windows
  6. If you want to stop the agent. # for linux / mac
    stop_agent.bat # for windows
  7. From nGrinder 3.3, the connected agent is automatically approved by controller. However if you provided
    configuration in the controller configuration, You have to approve agents by yourself.
  8. To approve agents, go to Agent Management menu and click the approve button.
  9. If you run an agent in Linux, you may need to configure ulimit to run many threads. please check followings.
    > ulimit -a                                                                                                                                         
    core file size          (blocks, -c) 0
    data seg size           (kbytes, -d) unlimited
    scheduling priority             (-e) 0
    file size               (blocks, -f) unlimited
    pending signals                 (-i) 30676
    max locked memory       (kbytes, -l) 64
    max memory size         (kbytes, -m) unlimited
    open files                      (-n) 16000
    pipe size            (512 bytes, -p) 8
    POSIX message queues     (bytes, -q) 819200
    real-time priority              (-r) 0
    stack size              (kbytes, -s) 10240
    cpu time               (seconds, -t) unlimited
    max user processes              (-u) 32768
    virtual memory          (kbytes, -v) unlimited
    file locks                      (-x) unlimited
    If your machine has small "max user processes" and "open files" entry when you run "ulimit -a", please make it at least over 10000. Open /etc/security/limits.conf file in the root account and add followings.
    your_account soft    nproc           32768
    your_account hard    nproc           32768
    root         soft    nproc           32768
    root         hard    nproc           32768
    your_account soft    nofile          16000
    your_account hard    nofile          16000
    root         soft    nofile          16000
    root         hard    nofile          16000

By default, the only one agent per machine is supported. However if you want to run multiple agents in a single machine, you have to configure some agent option. Please refer Agent Configuration Guide.

Install Monitor

nGrinder Monitor is the subset of the agent package and is installed into target machine to collect system statistics(such as CPU, MEM and Network) under the loads.
You can download monitors from the controller as well.

  1. Download the monitor.
  2. Then untar the monitor package and run the batch or shell files.  # for linux / mac
    run_monitor.bat # for windows
  3. If you want to stop the monitor, run following commands. # for linux / mac
    stop_monitor.bat –o # for windows

OK. Now you're ready to run the first performance test. Go to Quick Start
comments powered by Disqus
Page info
viewed 2006 times
translations en
posted 3 months ago by
updated 2 months ago by
View revisions
Share this article