Dedicated locations configuration

Deploy load generators on dedicated machines that you manage.

Instance specifications#

We recommend that you use load generator instances with at least 4 cores.

You might want to tune the Xmx JVM options to half of the physical memory. See jvm-options configuration below. If you don’t, the JVM will use a max heap size of 1/4th of the physical memory.

Permissions#

You can configure private locations with pre-existing servers. The control plane will be able to use configured dedicated machines as load generators during your simulations.

The control plane must have access to your dedicated machines. Ensure that each host is reachable through SSH on a specific port.

The control plane possesses a private key for establishing connections, while the corresponding public key is shared and configured on every host in the location.

System requirements#

Dedicated Machines private locations rely on some dependencies.

So, make sure following are available on the location configured hosts:

• bash the GNU Project’s shell
• jq a lightweight and flexible command-line JSON processor.
• curl a command line tool and library for transferring data with URLs
• Java runtime environment:
  • For Gatling Java and Scala support: OpenJDK 64bits LTS versions: 11, 17 or 21 (see Gatling prerequisites)
  • For Gatling JS and Postman support: either GraalVM CE or Oracle GraalVM. You need at least GraalVM for JDK 21.0.2, but we recommend installing the latest version.
• ~/.ssh/authorized_keys with control plane public key

Control plane configuration file#

control-plane {
  # Control plane token
  token = "cpt_example_c7oze5djp3u14a5xqjanh..."
  # Control plane token with an environment variable
  token = ${?CONTROL_PLANE_TOKEN}
  # Control plane description (optional)
  description = "my control plane description"
  # Locations configurations
  locations = [
    {
      # Private location ID, must be prefixed by prl_, only consist of numbers 0-9, 
      # lowercase letters a-z, and underscores, with a max length of 30 characters
      id = "prl_private_location_example"
      # Private location description (optional)
      description = "Private Location on Dedicated Machines"
      # Private location type
      type = "dedicated"
      # Engine (optional, default classic)
      engine = "classic" # Possible values: classic or javascript
      ssh {
        # SSH user
        user = "gatling"
        ## SSH private key
        private-key {
          # SSH private key path used to secure connections
          path = "private/key/path"
          # SSH private key password (optional, default: none)
          password = "password"
           # SSH private key password with an environment variable
          password = ${?PRIVATE_KEY_PASSWORD}
        }
        # SSH port (optional, default: 22)
        # port = 22
        # SSH connection timeout (optional, default 15 seconds)
        # connection-timeout = 15 seconds
      }
      # Working directory on hosts, must be executable (optional, default: /tmp)
      # working-directory = "/tmp
      
      # Hosts accessible with the SSH private key, on configured port (hostnames or IP addresses)
      hosts = [
        # "my.domain.example.com",
        # "1.2.3.4"
      ]
      
      # Java configuration (following configuration properties are optional)
      # System properties (optional)
      system-properties {
        # ExampleKey = ExampleValue
      }
      # Overwrite JAVA_HOME definition (optional)
      # java-home = "/usr/lib/jvm/zulu"
      # JVM Options (optional)
      # Default ones, that can be overridden with precedence:
      # [
      #   "-XX:MaxInlineLevel=20", 
      #   "-XX:MaxTrivialSize=12", 
      #   "-XX:+IgnoreUnrecognizedVMOptions", 
      #   "--add-opens=java.base/java.nio=ALL-UNNAMED", 
      #   "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED"
      # ]
      # Based on your instance configuration, you may want to update Xmx and Xms values.
      # jvm-options = ["-Xmx4G", "-Xms512M"]
    }
  ]
}

Troubleshooting#

This section contains tips for troubleshooting common issues with dedicated machines. If you have an issue not covered here, contact your Sales or Customer Success representative.

SSH keys#

Execute the command ssh-keygen -t ed25519 -f control-plane to generate your key pair. (You have the option to configure a password during this process)

This will generate the control-plane private key and control-plane.pub public key in the current directory where the command was executed.

Next, you’ll need to configure the authorized keys on the host for a user named, for example, gatling.

To configure the authorized keys on the host:

1. Create the authorized_keys file in the gatling/.ssh directory on the host:

touch gatling/.ssh/authorized_keys
chmod 600 gatling/.ssh/authorized_keys

2. Add the public key to gatling/.ssh/authorized_keys on the host. You can do this either by using the ssh-copy-id command:

ssh-copy-id -i control-plane.pub gatling@host

Or, manually by appending the public key to the file with:

cat control-plane.pub >> gatling/.ssh/authorized_keys

3. Add the private key to the control plane. Refer to your control plane config file for the expected private key file path: for your location, the value of ssh.private-key.path.

Timeout#

If your execution results in a timeout without any additional information, it indicates that the script failed unexpectedly. To investigate this issue, you can configure a location to remain active by using the following settings:

locations = [
  {
    id = "prl_dedicated"
    type = "dedicated"
    ...
    debug {
      keep-load-generator-alive = true
    }
  }
]

Afterward, you can examine the logs via systemd logs using the identifier gatling with journalctl --identifier gatling.

Edit this page on GitHub