Working in a dsoxlab lab: mission, course, ssh, hints

In a dsoxlab lab, four commands help you work: challenge says what you have to produce, course and guide give the material, ssh opens a machine of the lab, and hint reveals a hint in exchange for points. This lesson is for anyone who has just started a lab and wants to know where to read what. It dwells on the only gesture that has a price, the hint, because its cost is recorded as soon as you ask for it.

What you will learn

• Read a lab's mission with dsoxlab challenge.
• Read a lab's course section by section with dsoxlab course.
• Tell course, which displays the lesson, from guide, which gives the address of the online guide.
• Get onto a machine of the lab with dsoxlab ssh.
• Read the cost of a hint and work out what it takes off the mark, knowing that dsoxlab hint bills it without confirmation.

Prerequisites

You need a started lab, as the lesson Starting a dsoxlab lab with dsoxlab start describes, with the dsoxlab CLI in version 0.8.0 or newer. The commands of this lesson all accept the lab's identifier as an argument: once a lab is active, it becomes optional. On a shell lab, type them in the session opened by run or in a second terminal. On a vm lab, dsoxlab does not exist on the lab's machine: use a second terminal on your own machine.

Where do you read the mission and the course: challenge, course, guide?

dsoxlab challenge displays the mission, that is, what will be checked; dsoxlab course displays the lesson shipped with the lab; dsoxlab guide gives the address of the online guide. The three do not do the same thing, and mixing them up makes you look for the mission in the course or the course in the mission.

The examples of this section use the l2-swap-management lab of the linux catalogue.

dsoxlab challenge l2-swap-management
dsoxlab course l2-swap-management
dsoxlab guide l2-swap-management

The mission is the text to read first, because it says which files or which states to produce, and therefore what check will measure. The course is the material to get there: the lab's scenario, then its README.

When the lab splits its course into sections, course displays one section at a time, with the table of contents on the first pass, and remembers where you stopped. --next and --prev move forward and back, --section jumps to a named section, and --all displays the whole course at once.

The guide is something else: dsoxlab guide displays the address of the lab's online guide, as it is published on the site, with its images and its navigation. It opens the browser only if you add --open, because the address comes from the catalogue and it is up to you to decide whether to go there. --print gives the same result as the default and is meant for scripts. A lab that declares no address answers with an error and exits with code 1.

course and challenge go through a pager (a viewer that scrolls page by page) as soon as their output is taller than the terminal: less -R by default, replaceable with the DSOXLAB_PAGER or PAGER variable, and q quits it. A pipe or a redirection is never paged and receives the whole text; --no-pager displays everything at once.

DSOXLAB_PAGER='bat --plain' dsoxlab course l2-swap-management
dsoxlab challenge l2-swap-management --no-pager
dsoxlab course l2-swap-management > cours.txt

You have understood this step when you can say, without rereading, what the mission asks you to produce. On a vm lab, run displays the mission just before opening the SSH session. On the lab's machine, dsoxlab does not exist: to reread the mission, scroll back up in the terminal, or type dsoxlab challenge in a second terminal.

How do you get onto a lab machine with dsoxlab ssh?

dsoxlab ssh <host> opens an interactive SSH session on a host declared by the catalogue, with the right key and, if there is one, the right bastion (the entry machine you go through to reach the others). You can give the short name (docker) or the full name (docker.lab). An unknown name exits with code 1 and lists the declared hosts. On the containers catalogue, after dsoxlab start epreuve-livrer-une-image, the two hosts are called docker.lab and docker-client.lab, and the command gives this. The outputs of this lesson were captured with DSOXLAB_LANG=fr, so the messages are in French: the same messages exist in English.

dsoxlab ssh docker.lab

ℹ Connexion à docker.lab (10.10.120.11)…

This line announces the host and its address ("Connexion à", connecting to), then the session opens on the machine, with the prompt of docker.lab. For this capture, the command was played in a script, without a terminal: OpenSSH returned immediately, after two messages that the excerpt does not reproduce (no pseudo-terminal allocated, host added to the known hosts). In a real terminal, the session stays open until exit.

dsoxlab ssh only accepts a host name, not a command to run on it. Here is the answer when you add one:

$ dsoxlab ssh docker-client.lab hostname
Usage: dsoxlab ssh [OPTIONS] {host}
Try 'dsoxlab ssh --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Got unexpected extra argument(s) (hostname)                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

The command exits with code 2 and runs nothing: open the session, then type the command on the machine.

dsoxlab ssh is the route that does not depend on your personal SSH configuration. The SSH key belongs to the catalogue: it is the ssh/id_ed25519 file that instructor bootstrap produced. The command uses it, ignores your ~/.ssh/config (-F /dev/null), and goes through the bastion by itself when the infrastructure exposes one. You have succeeded when you find yourself on the machine, with its prompt, as on a real server.

An ssh docker.lab typed by hand can work too, on one condition. dsoxlab provision writes for that a fragment ~/.ssh/config.d/<catalogue>.conf (machine name, key, bastion) and announces "Connexion directe activée : ssh <machine> fonctionne désormais" (Direct connection enabled: ssh <machine> now works). This fragment is only read if your ~/.ssh/config contains the line Include ~/.ssh/config.d/*.conf. Without it, provision writes the fragment and warns you that it will never be read: add the line at the top of the file.

This shortcut disappears with the machines: dsoxlab destroy removes the fragment, and ssh <machine> then stops working until the next provision.

Some labs also leave you on your own machine, at the root of the repository: you then write your code from here and run your commands towards the hosts, and the lab's welcome panel points you to dsoxlab ssh when the subject calls for it. If run has already connected you to a machine, the dsoxlab commands do not exist there: type them after exit, or in a second terminal.

What does a hint cost, and how do you ask for one with dsoxlab hint?

dsoxlab hint reveals the next hint, in the order the author wrote them, and its cost is recorded before the hint is even displayed. The command asks for no confirmation: typing hint is enough to pay. The cost taken off is then visible in the result of check, which builds it into the mark.

dsoxlab hint epreuve-livrer-une-image
dsoxlab hint epreuve-livrer-une-image

Here is the bottom of the hint panel after each of the two calls, on the epreuve-livrer-une-image lab. The text of the hint, replaced by [...], fills the top of the panel, whose title is "Indice 1/4" then "Indice 2/4" (Hint 1/4, then 2/4), with the rank of the hint and the total number the lab offers:

[...]
│ Coût : -10 pts   Pénalité totale hints : -10 pts                             │
╰──────────────────────────────────────────────────────────────────────────────╯
[...]
│ Coût : -15 pts   Pénalité totale hints : -25 pts                             │
╰──────────────────────────────────────────────────────────────────────────────╯

The "Coût" (cost) line, at the bottom of the hint panel, is the one to look at. The first number is what this hint has just cost, the second the running total of the hints taken on this lab. The cost changes from one hint to the next: -10 for the first, -15 for the second, so -25 in total. A dsoxlab check run afterwards shows it in its panel: "2 indices utilisés, -25 pts" (2 hints used, -25 pts).

A hint taken is recorded at once, and running the lab again does not cancel it. Among reset, clean and destroy, only reset erases the lab's hints and brings their cost back to zero: the lesson Starting over or cleaning up a dsoxlab lab covers it.

The mark starts at 100, or at the scale that the lab's hints.yaml declares. The demonstration lab of the lesson Playing your first dsoxlab lab with dsoxlab demo showed it with a 20-point hint: hints cut the scale before the proportion of tests passed applies, not the mark afterwards. Only 80 points are then left to earn, so two tests passed out of three are worth 53 out of 100 (2/3 of 80), not 47. Without a hint, they would be worth 67.

The attempts already recorded keep the list of the hints you had seen at that moment, even after a reset: the lesson Getting your work checked with dsoxlab check and submit details what an attempt keeps.

Three answers cost nothing. hint answers "Tous les indices ont été utilisés" (All the hints have been used) when the lab offers no more, "Aucun indice disponible pour ce lab" (No hint available for this lab) when it declares none, and a message saying that the command is pointless on a validation lab, which defends a published guide and grades nobody. In these three cases, nothing is billed.

Troubleshooting

None of these cases is a breakdown: the command answers what it sees, and the message says what to do.

Symptom	Cause	Solution
guide displays an address but opens nothing	--open was not passed: the address comes from the catalogue, the CLI does not open it by itself	dsoxlab guide <id> --open
guide answers with an error and exits with 1	The lab declares no guide address	Read the course with dsoxlab course <id>
course only displays one section	The lab splits its course	--next to move forward, --all to read everything
ssh exits with 1 and lists hosts	The name given is not a host of the catalogue	Take one of the names listed, short or full
ssh exits with 2 with "Got unexpected extra argument(s)"	A command was added after the host name, and the command accepts none	Open the session with dsoxlab ssh <host>, then type the command on the machine
hint answers "Tous les indices ont été utilisés" (All the hints have been used)	The lab's hints are used up	Reread your notes or your terminal's scrollback; reset erases the hints and lets you ask for them again, but it also undoes the work in progress
The dsoxlab commands fail from the lab's machine	dsoxlab does not exist on the lab's machine	exit, or a second terminal on your own machine

Swipe to see more

Key points

• challenge says what will be checked, course displays the lesson, guide gives the address of the online guide.
• guide only opens the browser with --open.
• course remembers the section where you stopped; --all displays everything.
• course and challenge go through a pager; a pipe or a redirection receives the whole text.
• dsoxlab ssh uses the catalogue's key and the bastion when there is one.
• hint records its cost before displaying the hint, without confirmation.
• Hints cut the scale before the proportion of tests passed: a 20-point hint and two tests out of three are worth 53 out of 100.

Knowledge check

Check that you have the essentials of this guide. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

8 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →