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

A machine must be a Lager Box before you add it to Stout. To make a machine into a Lager Box, see Setting up a Lager Box in the Lager docs. Then make sure that these conditions are true:

• Stout can reach the box at its IP address, on ports 22, 5000, 9000, and 9001. Put the box on the same private network as Stout, for example Tailscale or a company VPN.
• You know the name of the SSH account on the box. It is the account that you gave to lager install.
• You know the password of that account. Stout asks for it one time, and only for a new box.

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 a window over the box tabs. Only owners and admins can start the install. The title of the window tells you which of the two installs this is:

• Password Required — this box is new to Stout. Enter the password of the box account, and then select Install Stout.
• Install Stout before proceeding — Stout manages this box already. There is no password field. Select Install Stout.

Stout uses the password one time, in this install. Stout does not store the password. A box that is new to Stout always needs the password. Lager gives the box account a sudo grant for the Lager commands only, so Stout cannot give itself the access that it needs without it. There is no way past this step: Stout cannot secure a box that it cannot use sudo on. A box that Stout manages already never needs the password, and the window does not ask for it. The first install gave Stout that access. To use the box tabs while the window is open, select Open the box page anyway. 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. One failure names the password. The message tells you that Stout runs on the box, but that the box account cannot use sudo without a password. Stout does not call such a box installed, because it cannot manage the SSH keys of the box or lock down SSH on it. Enter the password of the box account, and then select Install Stout again. The window asks for the password from then on, because Stout now knows that this box needs it. 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. The SSH lockdown can take several minutes to start. 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, look for the Box account password field. The field appears only when one of these boxes is new. Enter the password of the box account.
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.

One password covers the batch. Each install that you start from the import window uses the password in that field. A box that does not need it never reads it. 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.