Skip to main content
A variable or a secret is a value with a name. Stout delivers these values to your boxes. A test that you run from Select Test or Import Test reads a value with os.environ.get("NAME"). A Factory suite reads a value with get_secret("NAME"). Only owners and admins can see, add, change, or remove variables and secrets.

​
Organization values and box overrides

You can set a value in two places:
  • Organization: go to Settings, then select Variables & Secrets. Stout delivers these values to every box in the organization.
  • Box: open the box, go to its Settings tab, and find the Variables & Secrets card. A value there applies only to that box.
If a box value and an organization value have the same name, the box value wins on that box. The box card lists the box values and the organization values together. The Scope column shows This box or Organization. To replace an organization value on one box, select Override in its row. The row of a replaced organization value shows Overridden on this box. If you remove a box override, the box uses the organization value again, if one exists.

​
Add a value

  1. Select Add variable.
  2. Enter a Name.
  3. To hide the value after you save it, turn on Secret.
  4. Enter the Value.
  5. Select Add variable.

​
Names

A name must start with a letter or an underscore. It can contain only letters, digits, and underscores, and it can have up to 128 characters. Stout refuses the names that change how programs on the box load code, verify TLS, or use a proxy. It also refuses each name that starts with LAGER_ or STOUT_. For these rules, letter case does not matter.

​
Limits

If the values for one box are larger than 256 KB together, Stout does not deliver them to that box.

​
Secrets

When Secret is on, Stout encrypts the value and never shows it again. The list shows •••• and the last four characters of the value. For a value of fewer than 12 characters, the list shows no characters. To change a secret, select the pencil icon in its row, then enter a new value. If you leave Value blank, Stout keeps the stored value. You can turn a variable into a secret at any time. To turn a secret back into a plain variable, you must enter its value again. For a value that you want to read later, such as an email address, keep Secret off.

​
Certificates and keys

A value can have more than one line, for example a certificate chain. To enter one, select Multi-line (certificate, key) next to the Value label. If you paste text with line breaks into the single-line field, the field changes to multi-line for you. Stout refuses a certificate or a key that lost its line breaks, and the error tells you how to fix the value.

​
How values reach a box

When you add, change, or remove a value, Stout sends the values to each affected box that is online. Stout writes the values for the box to /etc/lager/org_secrets.json on the box. At the start of each Factory run, Stout sends the values again. If that delivery fails, the run ends with an error. If a delivery fails at another time, the Settings tab of the box shows the error. Your values stay saved in Stout, and Stout delivers them when the next Factory run starts. Code on the box reads the values in these ways:
  • A test from Select Test or Import Test gets the values as environment variables.
  • A Factory suite reads a value with get_secret("NAME"). The function reads the environment first, then the file on the box. If neither has the name, it returns an empty string. See Write a Factory suite.
  • A test from Select Test or Import Test does not get a value when the name and the value together are larger than 4 KB. The file on the box still holds that value.

​
Existing secrets files

Some boxes already have a file at /etc/lager/org_secrets.json that a person put there by hand. Stout keeps a copy of that file:
  • The first time that Stout writes the file, it saves the old file on the box as /etc/lager/org_secrets.json.pre-stout. The Settings tab of the box then shows a notice.
  • If no values apply to a box, and Stout never wrote the file, Stout does not touch the file.
  • When you uninstall Stout from the box, Stout puts the saved copy back. If there is no saved copy, Stout deletes the file.
If a box already has a secrets file, copy the values that its suites need into Stout before you add the first value. After the first delivery, Stout replaces the contents of that file.