The main dsoxlab commands, in the order you use them

A dsoxlab lab is played with a dozen commands, and they always follow each other in the same order: install a catalogue, diagnose the machine, set a context, read the course, prepare the environment, accomplish the mission, validate, then follow your progress. This lesson takes every command in that order, says what it does and what it assumes, and dwells on the three pairs people confuse: run and start, status and infra status, check and submit. It describes version 0.2.5 of the CLI and is written for anyone who has already played the demonstration lab.

What you will learn

Install, list and activate a catalogue with the catalog family.
Set a context with use, so that the next commands stop asking.
Read a course and a mission with course, guide and challenge.
Play a lab with run, or the whole sequence with start.
Validate with check or submit, then follow with status, progress and scores.
Provision and tear down the machines of a vm lab with provision, ssh and destroy.

The order of the commands, in one table

Nothing tells you that a command assumes another one, except the failure message of the one you typed too early. The table below is the complete order, and each line points to the section that details it. On a shell lab, the infrastructure lines simply do not exist.

Step	Command	What it produces
1	`dsoxlab catalog add <id or URL>`	A catalogue cloned and made active
2	`dsoxlab doctor`	What this catalogue requires, and what is missing
3	`dsoxlab use <section>`	A context the next commands reuse
4	`dsoxlab list-labs`, `dsoxlab show <id>`	The catalogue, then the detail of one lab
5	`dsoxlab course <id>`	The lesson, in the terminal
6	`dsoxlab instructor bootstrap`, `dsoxlab provision`	The machines of a `vm` lab
7	`dsoxlab run <id>`, or `dsoxlab start <id>` which chains steps 2, 3, 6 and 7	The environment prepared, and a session opened inside it
8	`dsoxlab challenge <id>`, `dsoxlab hint <id>`	The mission, then a hint that costs points
9	`dsoxlab check <id>` or `dsoxlab submit <id>`	The tests, the score, and its recording
10	`dsoxlab status`, `dsoxlab progress`, `dsoxlab next`, `dsoxlab scores`	Where you stand
11	`dsoxlab reset <id>`, `dsoxlab clean <id>`, `dsoxlab destroy`	Start from scratch, or tear everything down

As soon as a lab is active in the session, its identifier becomes optional: dsoxlab check knows which lab you are in. Identifiers are long, and the installation lesson explains how to enable shell completion.

Installing and choosing a catalogue

Labs live in their own repositories, published separately from the engine, and the catalog family manages them. catalog add accepts an identifier from the embedded manifest, linux, ansible or terraform, or any git URL, which is the route for the Kubernetes catalogue. The repository is cloned under ~/.local/share/dsoxlab/catalogs/ and becomes active, that is, the one dsoxlab serves when you are not standing in a catalogue directory.

dsoxlab catalog list            # the known catalogues, and the installed ones
dsoxlab catalog add linux       # clones and activates
dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training
dsoxlab catalog use linux       # changes the active catalogue
dsoxlab catalog update          # updates every installed catalogue
dsoxlab catalog remove linux    # removes an installed catalogue

A plain git clone works too, and then the catalogue you are standing in is the one the CLI serves: discovery happens from the current directory, and the active catalogue is only the fallback. Remember that progress lives in the catalogue itself, in a .dsoxlab.db file at its root: removing a catalogue removes its history with it.

Diagnosing with doctor

dsoxlab doctor is the command to type after every catalog add, because what it reports depends on the catalogue: a catalogue made of shell labs never asks for a hypervisor, and a catalogue of vm labs moves Terraform and the hypervisor to required. Its two tables, its --fix, --strict and --json options, and its three outcomes ok, failed and unknown are detailed in the lesson Installing dsoxlab locally.

Setting a context with use

dsoxlab use sets an active context for the current catalogue: a section, optionally a level, and three settings that have no other home. Without it, next has no section to look for the next lab in, and the infrastructure commands do not know which provider to use when the catalogue offers several.

dsoxlab use l2                  # active section: the next commands stay within it
dsoxlab use linux --lang en     # display language, durably for this catalogue
dsoxlab use --provider kvm      # the hypervisor, when meta.yml offers several
dsoxlab use --target ubuntu     # the default target machine of a multi-host lab
dsoxlab use --reset             # clears the context

The context is written to .dsoxlab-context.json, at the root of the catalogue. Two environment variables take precedence over it, for one command: DSOXLAB_PROVIDER for the provider and DSOXLAB_LANG for the language.

Browsing the catalogue: list-labs, show, next

dsoxlab list-labs prints one line per lab, with its section, its identifier, its type, its runtime, its estimated duration and its best score. Four filters narrow it down, --section, --level, --type and --bloc, and the active context applies on its own. dsoxlab show <id> gives the detail of a lab: skills, distributions, runtime, target, status, and the pass mark when it is a mock exam.

dsoxlab list-labs --type capstone   # only the mock exams
dsoxlab show cka-etcd-backup-restore
dsoxlab next                        # the first lab with no result, in teaching order

dsoxlab next recommends the next lab in the active section, in the order the catalogue's meta.yml declares. It returns all_done when the section holds labs and every one has a result, and exits 1 with no active context: that is the most frequent case where it seems to do nothing.

Reading the course: course, guide, challenge

Two commands give the material, and they do not do the same thing. dsoxlab course prints the lesson shipped with the lab, in the terminal; on the catalogues of this site, it points to the matching lesson. dsoxlab guide opens the lab's online guide in the browser, as published, with its images and navigation; --print prints the URL instead, which is what you want over an SSH session. dsoxlab challenge prints the mission, that is, what will be checked.

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

course and challenge go through a pager as soon as their output exceeds the height of the terminal, less -R by default, replaceable through the DSOXLAB_PAGER variable. A pipe or a redirection is never paged and receives the whole text; --no-pager prints everything at once. When the lab splits its course into sections, course shows one at a time, with --next, --prev and --section, and remembers where you stopped.

Playing: run, start, hint

dsoxlab run <id> prepares the lab's environment and opens a session inside it. On a shell lab, that is a sub-shell in the working directory, challenge/work/ by default, with the lab's fixtures copied into it. On a vm lab, it is an SSH session on the target machine, after the lab's preparation playbook has been played. Either way, you leave it with exit, and dsoxlab check works from that session as well as from outside.

What run does not do explains most first failures: it does not provision the machines. On a vm lab whose infrastructure does not exist, it exits with code 2 and names provision. That is why dsoxlab start <id> exists: it plays the whole sequence, context, prerequisites, infrastructure if the lab wants some, then preparation and session, announcing each step with the command that replays it alone.

▶ 1/4 · active context  (dsoxlab use l2)
▶ 2/4 · prerequisites  (dsoxlab doctor)
  16 required checks, all green
▶ 3/4 · infrastructure  (dsoxlab provision)
▶ 4/4 · preparation and session  (dsoxlab run l2-swap-management)

When a step fails, start names it with its command, attempts nothing beyond it, and returns the exit code of that step, never a code invented for itself. It is idempotent: it reads the Terraform state and skips provisioning when the declared hosts already have an address. Without an identifier, it takes the lab that next suggests. What it shortens is the typing and the order to remember, never the understanding: every single command works exactly as before.

dsoxlab hint <id> gives the next hint, in the order the author wrote them, and its cost is deducted from the final score. A hint taken is recorded immediately: it cannot be given back.

Validating: check, submit, status

dsoxlab check <id> runs the lab's tests, computes the score, hints deducted, records it, and prints the detail of every test. It exits 1 when a test fails, which is about your work, and 2 when it could not run, which is about your installation. It can be run as many times as you like: every run records a result, and the best one becomes the best_score that show and list-labs display.

dsoxlab check l2-swap-management
dsoxlab check drill-storage --target ubuntu   # test the chosen target of a multi-host lab
dsoxlab submit l2-swap-management             # the same, then close the session

dsoxlab submit does the same thing then closes the session: you then have to type exit. On a lab that declares a pass mark, a mock exam, submit also renders a verdict, passed or failed, expressed as a percentage of the scale. The --target option of check matters on labs that offer several distributions: without it, such a lab only ever tests its default host.

dsoxlab status says where the active lab stands, or the one you name, through a stable state: not_started, ready, in_progress, validated, or degraded when a declared service no longer runs. It never talks about the machines: that is the job of infra status, described further down, and the two are easy to confuse.

Following your progress: progress, scores

dsoxlab progress shows your progress by block: labs completed, average score, challenges and capstones. That is the point of view most missing on a long training path, knowing what is left to prove, and it follows the teaching order of the meta.yml. dsoxlab scores lists the complete history of recorded scores, failed attempts included, and carries a Verdict column on catalogues that declare at least one exam.

dsoxlab progress
dsoxlab scores --top 10

Both accept --json, like list-labs, show, next, check, status, doctor, validate-structure and support. The document rendered carries a schema field, and verdicts are read there in stable tokens, never in a translated label: an integration filters on state, not on "validated".

Starting over: reset, clean

Two commands undo what a lab has done, and they do not go equally far. dsoxlab reset <id> returns the lab to its initial state: on a vm lab, it replays the cleanup playbook then the preparation one, or returns to the disk restore point when the lab requires one. dsoxlab clean <id> removes every resource the lab created, including the containers of its services and the restore point. Neither touches your score history.

The infrastructure commands of vm labs

These commands only exist for a catalogue that declares an infra: block; on the Terraform catalogue, they have no object. They read the meta.yml and nothing else, which incidentally lets you use dsoxlab as a plain provisioner of throwaway VMs, without any exercise.

dsoxlab instructor bootstrap    # generates ssh/id_ed25519 in the catalogue, if missing
dsoxlab provision               # terraform apply on the current provider, then wait for SSH
dsoxlab provision --host alma-rhcsa-1.lab   # a single machine; the option is repeatable
dsoxlab infra status            # who answers over SSH, and why the silent ones do not
dsoxlab ssh alma-rhcsa-1.lab    # an interactive session on a host
dsoxlab destroy                 # tear everything down, machines outside the state included
dsoxlab destroy --yes           # without confirmation

instructor bootstrap is played once per clone, learners included: a published catalogue embeds no SSH key, and provision refuses to start without the private half. The word "instructor" names the command, not its audience. provision copies the packaged Terraform templates to ~/.local/state/dsoxlab/<catalog-id>/, generates the variables from the meta.yml, applies, then waits for each host to answer over SSH.

destroy also removes the machines a failed provision left outside the Terraform state, after confirmation, and exits non-zero if one remains. It is the habit to take after every session: those machines keep consuming memory and disk long after the lab is over. infra status checks SSH reachability of every declared host and names the cause when one stays silent, a machine powered off for instance, rather than returning a bare timeout.

The options that apply to every command

Three options go before the command: --verbose or -v, repeatable, --debug, equivalent to -vv, and --version. Whatever the verbosity, the full log is written to ~/.local/state/dsoxlab/dsoxlab.log, never to standard output: no need to replay a command to know what it did, and --json stays machine-readable even in verbose mode.

dsoxlab -vv provision
dsoxlab --version
dsoxlab fullhelp                 # the complete platform guide, in the terminal
dsoxlab <command> --help         # the options of one command

The rest of the CLI, validate-structure, new, support and completion, serves the catalogue author and diagnosis, and has its place in the next lessons of this path.

Troubleshooting

These four cases are ordering errors, not failures: the command typed assumed another one. The message says so every time, and start avoids all of them.

Symptom	Cause	Solution
`run` exits 2 on a `vm` lab and names `provision`	The machines do not exist yet	`dsoxlab provision`, or `dsoxlab start <id>` which chains it
`provision` exits 1 without starting, for want of a key	No SSH key in the catalogue's `ssh/`, never committed	`dsoxlab instructor bootstrap`, once per clone
`next` exits 1 and suggests nothing	No active section	`dsoxlab use <section>`
`provision` refuses to go on and talks about a provider choice	The `meta.yml` offers several and none is chosen	`dsoxlab use --provider kvm`, or `DSOXLAB_PROVIDER=kvm` for one command

Key points

The order is always the same: catalog add, doctor, use, course, then run, challenge, check, and progress to know where you stand.
start chains use, doctor, provision and run, announcing each step with the command that replays it alone; on failure, it returns the step's code.
run prepares and opens a session, a sub-shell or an SSH session; it never provisions.
check records a score and can be run again at will; submit does the same then closes the session, with a verdict on a mock exam.
status talks about the lab, infra status talks about the machines.
On a vm lab: instructor bootstrap once per clone, provision before, destroy after.
The full log is always in ~/.local/state/dsoxlab/dsoxlab.log, whatever the verbosity.

Next steps

Creating a course and its challenges from scratch: what validate-structure and new do for the author, and how a lab declares its tests.
Bringing up the infrastructure of vm labs: provision, infra status and destroy seen from the side of whoever declares the machines.