Audience: learners, catalog authors and trainers. This is the reference page the three share, and the only place these locations are written down.
dsoxlab keeps state in two families, and nowhere else: inside the catalog you are playing, and under your home directory. Progress belongs to the first family, so it is per catalog: two catalogs side by side keep separate histories, and deleting a catalog deletes its history with it.
| Path | What it holds | Written by |
|---|---|---|
<catalog>/.dsoxlab.db |
SQLite database: results (scores) and hint_requests |
check, submit, hint |
<catalog>/.dsoxlab-context.json |
active section, level, language, lab, target, provider, and the course position | use, run, course |
Both belong in the catalog's .gitignore. Neither can be moved: they are the
repository, which is what makes progress follow the catalog rather than the
machine.
A catalog that declares vm labs also carries an SSH key pair under
<catalog>/ssh/id_ed25519{,.pub}, generated by dsoxlab instructor bootstrap
on each machine that provisions it. Neither half is committed: the private one
must never be, and the public one is useless without it.
| Path | What it holds | Moved by |
|---|---|---|
~/.local/state/dsoxlab/dsoxlab.log |
full log of every command, whatever the verbosity | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/terraform/<provider>/ |
Terraform working directory and state | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/cloud-init/ |
cloud-init templates copied out of the tool for provisioning | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/dsoxlab.lock |
the per-catalog write lock (flock) |
XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/bootstrap.json |
fingerprint of the catalog's foundation (infra.bootstrap) after it was played successfully. provision replays the playbook when its content no longer matches, or on --bootstrap; destroy removes this file |
XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/provenance.json |
where the resources provisioned by this catalog come from: its id, the absolute path of the clone at provisioning time, the provider, the UTC timestamp, the provisioning id and the resource UUID. Read by dsoxlab infra origin, updated by provision, trimmed by destroy of whatever it actually destroyed. Versioned schema (dsoxlab-provenance-v1), atomic write, one file per catalog because the write lock is per catalog too. No secrets. This file is a readable cache: the same provenance is written onto the resources themselves (libvirt metadata on KVM, configuration keys of the same name on Incus), so deleting it loses nothing and the next provision rebuilds it |
XDG_STATE_HOME |
~/.cache/dsoxlab/<catalog-id>/inventory.json |
generated Ansible inventory | XDG_CACHE_HOME |
~/.cache/dsoxlab/<catalog-id>/ssh_config |
generated OpenSSH config for the lab hosts | XDG_CACHE_HOME |
~/.cache/dsoxlab/version-check.json |
last version seen on PyPI, and when | XDG_CACHE_HOME |
~/.local/share/dsoxlab/demo/ |
demonstration catalog installed by dsoxlab demo |
XDG_DATA_HOME |
~/.local/share/dsoxlab/catalogs/ |
catalogs installed by dsoxlab catalog add, one subdirectory per id |
XDG_DATA_HOME |
~/.local/state/dsoxlab/<catalog-id>/labs/ |
work starting points, to tell a ready lab from one in progress | XDG_STATE_HOME |
~/.local/state/dsoxlab/catalogue-actif |
id of the active catalog, the one used without sitting in its directory | XDG_STATE_HOME |
~/.local/state/dsoxlab/sessions/<portal>-<digest>.json |
portal session opened by dsoxlab login: the tokens that let push write to your account. Mode 0600, one file per portal, removed by dsoxlab logout |
XDG_STATE_HOME |
~/.ssh/config.d/<catalog-id>.conf |
SSH fragment for the lab hosts, so ssh, scp and your IDE reach them by name |
none |
<catalog-id> is repo.id from the catalog's meta.yml. The lock falls back
to the directory name plus a fingerprint of its absolute path when no meta.yml
can be read, so two clones of the same catalog share one lock and one Terraform
state.
The Terraform state is deliberately outside the catalog: a state file in a lab repository gets committed, and a committed state is a state that lies.
Two of these are caches, and losing them costs nothing but a regeneration:
inventory.json and ssh_config are rebuilt on the next command that needs
them. Anything that points at the generated ssh_config (an Include, an IDE
profile) must tolerate its disappearance.
dsoxlab completion install writes outside these families, once: the shell
completion (~/.zfunc/_dsoxlab plus a line in ~/.zshrc, or
~/.bash_completion.d/dsoxlab plus a line in ~/.bashrc).
Up to 0.1.61, dsoxlab install also wrote a wrapper at ~/.local/bin/dsoxlab.
It no longer does: uv tool install and pipx put their launcher exactly
there, and writing over a symlink writes into its target. If an old install left
one behind, it is yours to delete.
These paths have been documented in the past. They are listed here so nobody looks for them again:
- No
~/.config/dsoxlab/config.yaml, and no user configuration file at all. What can be set goes through the contract (meta.yml), the active context (dsoxlab use) or an environment variable. Multi-catalog discovery through such a file is planned (#78); until it lands, no code reads that path. - No
~/.local/share/dsoxlab/progress.db. Scores live in<catalog>/.dsoxlab.db, per catalog. XDG_CONFIG_HOMEis read nowhere. The three variables above are the only XDG variables dsoxlab honours.
| Variable | Effect |
|---|---|
LAB_HOME |
Root of the catalog to work on, instead of auto-detection |
DSOXLAB_LANG |
Display language (en / fr), wins over the context file |
DSOXLAB_PROVIDER |
Infrastructure provider, wins over dsoxlab use --provider |
DSOXLAB_TARGET |
Default target of a vm lab, when the session sets none |
DSOXLAB_PAGER |
Pager for course and challenge (then PAGER, default less -R) |
DSOXLAB_LOG |
DSOXLAB_LOG=debug is the same as -vv |
DSOXLAB_HOST_READY_TIMEOUT |
Seconds to wait for a provisioned host to answer (default 180) |
DSOXLAB_NO_UPDATE_CHECK |
Set to 1 to silence the daily PyPI version check |
DSOXLAB_PORTAL_LOCAL |
Set to 1 to accept an http learning.portal_url towards localhost only, for whoever is writing a portal. Off by default, and never a catalogue's decision |
DSOXLAB_OUTSCALE_PROFILE, DSOXLAB_AWS_PROFILE |
Credentials profile for those providers |
Three more are set by dsoxlab and are not meant to be set by hand:
DSOXLAB_TARGET_HOST (the host the tests must inspect, which is how a
multi-distro lab tests the target you chose) and LAB_NO_REPLAY=1, both exported
to the pytest run; and DSOXLAB_LAB_SESSION (the lab id) inside the session run
opens, which is how submit knows it runs inside one.
tests/test_documentation_synchrone.py derives the real locations by calling
the code — the same functions the CLI calls — and fails when a path cited in
any documentation page matches none of them. The false progress.db and
config.yaml above are what motivated it: they were documented for months
because nothing read the documentation and the code at the same time.