Manual startup

Explore manual startup options for the Hyperfoil controller.

Hyperfoil controller is started with

bin/controller.sh

Any arguments passed to the scripts will be passed as-is to the java process.

By default io.hyperfoil.deployer is set to ssh which means that the controller will deploy agents over SSH, based on the agents configurion. This requires that the user account running the controller must have public-key SSH authorization set up using key $HOME/.ssh/id_rsa. The user also has to be able to copy files to the directory set in agent definition (by default /tmp/hyperfoil) using SCP - Hyperfoil automatically synchronizes library files in this folder with the currently running instance and then executes the agent.

When you don’t intend to run distributed benchmarks you can start the controller in standalone mode:

bin/standalone.sh

This variant won’t deploy any agents remotely and therefore it does not need any agents: section in the benchmark definition; instead it will use single agent started in the same JVM.

Below is the comprehensive list of all the properties Hyperfoil recognizes. All system properties can be replaced by environment variables, uppercasing the letters and replacing dots and dashes with underscores: e.g. io.hyperfoil.controller.host becomes IO_HYPERFOIL_CONTROLLER_HOST.

PropertyDefaultDescription
io.hyperfoil.controller.host0.0.0.0Host for Controller REST server
io.hyperfoil.controller.port8090Port for Controller REST server
io.hyperfoil.rootdir/tmp/hyperfoilRoot directory for stored files
io.hyperfoil.benchmarkdirroot/benchmarkBenchmark files (YAML and serialized)
io.hyperfoil.rundirroot/runRun result files (configs, stats…)
io.hyperfoil.deployersshImplementation for agents deployment
io.hyperfoil.deployer.timeout15000 msTimeout for agents to start
io.hyperfoil.agent.init.timeout120000 msTimeout for each agent to initialize a benchmark, including session allocation and GC
io.hyperfoil.agent.debug.portIf set, agent will be started with JVM debug port open
io.hyperfoil.agent.debug.suspendnSuspend parameter for the debug port
io.hyperfoil.controller.cluster.ipfirst non-loopbackHostname/IP used for clustering with agents
io.hyperfoil.controller.cluster.port7800Default JGroups clustering port
io.hyperfoil.cluster.nameISPNCluster name shared by the controller and deployed agents.
io.hyperfoil.controller.external.uriExternally advertised URI of REST server
io.hyperfoil.controller.keystore.pathFile path to Java Keystore
io.hyperfoil.controller.keystore.passwordJava Keystore password
io.hyperfoil.controller.pem.keysFile path(s) to private TLS key(s) in PEM format
io.hyperfoil.controller.pem.certsFile path(s) to server TLS certificate(s) in PEM format
io.hyperfoil.controller.passwordPassword used for Basic authentication
io.hyperfoil.controller.secured.via.proxyThis must be set to true for Basic auth without TLS encryption
io.hyperfoil.trigger.urlSee below

Set io.hyperfoil.agent.init.timeout on the controller JVM, for example bin/controller.sh -Dio.hyperfoil.agent.init.timeout=180000 to allow three minutes. This timeout starts after agents have registered with the controller. It is separate from the agent deployment timeout and does not change HTTP request timeouts or benchmark SLAs.

If io.hyperfoi.trigger.url is set the controller does not start benchmark run right away after hitting /benchmark/my-benchmark/start ; instead it responds with status 301 and header Location set to concatenation of this string and BENCHMARK=my-benchmark&RUN_ID=xxxx. CLI interprets that response as a request to hit CI instance on this URL, assuming that CI will trigger a new job that will eventually call /benchmark/my-benchmark/start?runId=xxxx with header x-trigger-job. This is useful if the the CI has to synchronize Hyperfoil to other benchmarks that don’t use this controller instance.

Running several benchmarks on one host

A controller and the agents it deploys form a JGroups cluster, and a node only ever talks to nodes of the same cluster name - messages from any other one are dropped. A single controller per host therefore needs no configuration at all: both sides fall back to ISPN and find each other.

To run two benchmarks side by side - say one per git worktree - give each controller its own cluster name, REST port and root directory:

bin/controller.sh -Dio.hyperfoil.cluster.name=runA \
                  -Dio.hyperfoil.controller.port=8090 \
                  -Dio.hyperfoil.rootdir=/tmp/hyperfoil-a
bin/controller.sh -Dio.hyperfoil.cluster.name=runB \
                  -Dio.hyperfoil.controller.port=8091 \
                  -Dio.hyperfoil.rootdir=/tmp/hyperfoil-b

Nothing has to be configured on the agent side: the controller passes its cluster name to every agent it starts, over SSH as well as in Kubernetes. The clustering port needs no configuration either - the first controller takes 7800 and the second one moves to the next free port on its own.

Note that the runs still share the machine’s CPUs. If your agents pin themselves with the cpu property (see agent configuration), give each run a disjoint set of cores, otherwise the two benchmarks compete for the same ones and neither produces trustworthy numbers.

Security

Since Hyperfoil accepts and invoked any serialized Java objects you must not run it exposed to public to prevent a very simple remote code execution. Even if using HTTPS and password protection (see below) we recommend to limit access and privileges of the process to absolute minimum.

You can get confidential access to the server using TLS encryption, providing the certificate and keys either using Java Keystore mechanism (properties above starting with io.hyperfoil.controller.keystore) or via PEM files (properties starting with io.hyperfoil.controller.pem). These options are mutually exclusive. In the latter case it is possible to use multiple certificate/key files, separated by comma (,).

Authentication uses Basic authentication scheme accepting any string as username. The password is set using io.hyperfoil.controller.password or respective environment variable. If you’re exposing the server using plaintext HTTP you must set -Dio.hyperfoil.controller.secured.via.proxy=true to confirm that this is a desired configuration (e.g. if the TLS is terminated at proxy and the connection from proxy does not require confidentiality).


Last modified October 27, 2026: Add 0.30.0 release notes (33375df)