Add a box

To add a box, you register it in Stout, and then you install Stout on it. Only owners and admins can add boxes.

​

Before you start

Make sure that these conditions are true:

• The box runs Lager. See Setting up a Lager Box in the Lager docs.
• Stout can reach the box at its IP address.
• You know the name of the SSH account on the box.
• For a box that you never prepared for Stout, you know the password of that account.

Stout refuses some addresses, for example loopback and link-local addresses.

​

Set a default box username

An owner can set a Default Box Username in Settings > General. Stout fills in this username when you add or import a box. You can change the username of each box later on its Settings tab.

​

Register a box

1. Open Boxes, and then select Add Box.
2. Enter the Box Name.
3. Enter the IP Address of the box.
4. Check the Username. Stout uses this SSH account on the box.
5. If you want the box in a group, select the group in Group (optional).
6. If you want to set up nets from a template, select the template in Template (optional). Stout creates the nets when the box first comes online.
7. Select Add Box.

The Group (optional) field appears only when your organization has box groups. For more about templates, see Templates. After you add the box, open its page to install Stout.

​

Install Stout

When the Stout container on a box is not healthy, the box page opens the Install Stout before proceeding window. Only owners and admins can start the install.

1. If this is the first setup of the box, enter the password of the box account in Box account password (optional). If you prepared the box for Stout before, leave the field empty.
2. Select Install Stout.

Stout uses the password once, for this install. Stout does not store the password. The window shows the four steps of the install:

1. Install requested
2. Write control-plane config
3. Start Stout container
4. Verify health on :9001

To see the install output, select View log. If one step takes more than 3 minutes, the window tells you to check the log. If the install fails, the window shows the error. Correct the problem, and then select Install Stout again. The install does these things on the box:

• It writes the connection settings and the Stout SSH key.
• It sets up the sudo rules that Stout needs.
• It installs the rules that let Lager reach USB instruments.
• It starts the stout container and checks that the container is healthy.
• It turns on the access guard and asks for the SSH lockdown. See Security and access.

​

After the install

After the install, the window changes to Securing this box…. It shows two lines: Who can use this box and Who can log in over SSH. The window closes by itself when the box is secure. To use the box page before then, select Open the box page anyway →. To leave, select ← Go Back.

​

Import boxes from the Lager CLI

The Lager CLI keeps its list of boxes in the .lager file in your home directory. You can import that list into Stout.

1. Open Boxes.
2. Open the … menu, and then select Import from Lager.
3. Pick your .lager file. If the file picker does not open, select Choose File.
4. Check the preview. It shows the Name, IP Address, SSH User, and Version of each box.
5. Select the import button, for example Import 3 Boxes.
6. In Step 2: Install Stout on Boxes, find the Box account password (optional) field. If this is the first setup of the boxes, enter the password of the box account. If you prepared the boxes for Stout before, leave the field empty.
7. Select Install from Dashboard for a box. To install on many boxes, select them, and then select Install Selected from Dashboard.
8. Select Done.

The import follows these rules:

• If Stout already has a box with the same name, the import updates its IP address. It also updates the username when the file has one.
• A new box needs a username. The import uses the user value from the file, or else the default box username. If neither exists, the import rejects the box.
• The import rejects a box with an address that Stout refuses.

Each install that you start from the import window uses the password in that field. Stout uses the password only for those installs, and it does not store the password.

​

Export boxes to the Lager CLI

Export to Lager gives you Lager CLI commands that copy your Stout boxes into the Lager CLI on your computer.

1. Open Boxes.
2. Open the … menu, and then select Export to Lager.
3. In Export to Lager CLI, read the commands.
4. Select Copy to Clipboard.
5. Paste the commands into a terminal on your computer, and run them.

The first command is lager boxes delete-all --yes. Each next command adds one box with lager boxes add and the SSH username of that box. The export skips boxes that have no IP address. For the commands, see lager boxes in the Lager docs.