Runtime variables

How to define runtime variables and use them inside lifecycle scripts or challenge assignments.

Overview

Runtime variables allow you to use dynamic content in challenge assignments and lifecycle scripts. You can define runtime variables via our API or Lifecycle Scripts. These variables are configured per participant per host (e.g a user's VM or container) and can only be accessed from the given participant and host.

It's not recommended to store secrets in runtime variables as the storage is not secure and everyone who has terminal access may be able to view them. Furthermore, cloud account related environment variables are automatically stored in the $INSTRUQT_ENV_VARS variable, and do not need to be redefined as runtime variables.

Set variables

Define variables

You can define variables in lifecycle scripts on Linux and Windows hosts:

Linux

agent variable set <KEY> <VALUE>

For example, the following defines a runtime variable named COLOR with a value of RED.

agent variable set COLOR RED

Windows

Agent-Variable-Set <KEY> <VALUE>

For example, the following defines a runtime variable named COLOR with a value of RED.

Agent-Variable-Set COLOR RED

Retrieve variables

In order to retrieve the value of a runtime variable, use the following command:

Linux

agent variable get {KEY}

For example, the following retrieves a runtime variable named COLOR.

agent variable get COLOR

Windows

Agent-Variable-Get {KEY}

For example, the following retrieves a runtime variable named COLOR.

Agent-Variable-Get COLOR

Use variables

To retrieve the value of a runtime variable in a challenge assignment use following syntax:

[[ Instruqt-Var key="<KEY>" hostname="<HOSTNAME>" ]]

Where KEY is a key you registered a value with and HOSTNAME is a host where the variable resides.

You can only access variables via lifecycle scripts, the GraphQL API, or assignment markdown. It is not possible to get/set them from a terminal session on a host.

Example

Consider the following challenge assignment, which references a runtime variable named INSTRUQT_TEST_VAR on a host named cloud-client.

👋 Introduction
===============

The following line contains the value of INSTRUQT_TEST_VAR: 
[[ Instruqt-Var key="INSTRUQT_TEST_VAR" hostname="cloud-client" ]]

Assuming INSTRUQT_TEST_VAR was registered with a value of TEST123 on the cloud-client host during its setup script, the assignment text would display TEST123 to the user.