Marionnet: quick install

The commands to copy, in order. The explanations, the precautions and the troubleshooting are in the full guide, INSTALL.md, cited here as “full guide, § n”.

Image
the disk of a virtual machine: Debian trixie, Debian wheezy, or guignol, the small image that also serves as a router.
UML kernel
the Linux kernel that runs a Marionnet virtual machine as an ordinary program of your machine. There are two of them, 64-bit and 32-bit.
Precompiled archive
the application, already compiled, in a .tar.xz file (a tarball), for the distributions that have no Marionnet repository.
Sudoers rule
the permission that lets Marionnet create its network interfaces on your machine. No package sets it: the administrator grants it.

The installation at a glance

1. the application    apt repository, dnf/zypper
        │             repository, or precompiled archive
        ▼
2. images, kernels    data packages,
        │             then marionnet-get-images
        ▼
3. sudoers rule       marionnet-sudoers.sh install
        │
        ▼
4. launch             marionnet

At step 1, the methods are alternatives: only one concerns you. Steps 2, 3 and 4 then apply to all of them.

1. Install the application: one method, your choice

Choose one of the four methods 1.A to 1.D, according to your machine; the others do not concern you. Sections 2, 3 and 4 then apply to every method.

Your machine Go to
Debian, Ubuntu and derivatives § 1.A
Fedora, RHEL family (Rocky, AlmaLinux), openSUSE § 1.B
any other distribution § 1.C
you want to modify Marionnet § 1.D

The installation was measured on Ubuntu 20.04, 22.04, 24.04 and 26.04, on Debian 11, 12 and 13, on Rocky Linux and AlmaLinux 9 and 10, on Fedora 42 and on openSUSE Leap 15.6 and 16.0. The figures are in the full guide, § Which systems this was tested on.

The RHEL 10 family has no router yet (§ 1.B).

Sections 1.A and 1.B use the archive signing key. Compare its fingerprint with a source that is not this page: the git repository, a printed handout, or a machine where Marionnet already runs (full guide, § 1.A).

Marionnet Archive Signing Key <loddo@lipn.univ-paris13.fr>
4A65 3434 0BF9 7733 E74C  9DFC 12E4 6000 225F 0E56

1.A Debian and Ubuntu

Certificates and curl

Not needed if curl --version already answers. A minimal Debian or Ubuntu installation has neither, and without certificates nothing can read the site over https.

sudo apt update && sudo apt install ca-certificates curl

The key: fetch it, then look at it

sudo install -d /etc/apt/keyrings
sudo curl -o /etc/apt/keyrings/marionnet.asc \
     https://git.launchpad.net/marionnet/plain/marionnet-archive-keyring.asc
sudo apt install gnupg
# must print the fingerprint above
gpg --show-keys /etc/apt/keyrings/marionnet.asc

If gpg prints something else, or nothing, fetch the key again.

Never add -L to this curl. The key's server sometimes redirects to its login page, and -L would save that page instead of the key (full guide, § 1.A).

The repository and the application

echo 'deb [signed-by=/etc/apt/keyrings/marionnet.asc] https://www.marionnet.org/download/apt/ ./' \
  | sudo tee /etc/apt/sources.list.d/marionnet.list
sudo apt update
sudo apt install marionnet

The 64-bit kernel, marionnet-kernels, comes with the application.

If a Marionnet precompiled archive (§ 1.C) was already installed on this machine, replace the last line with this one, which keeps your configuration file:

sudo apt install -o Dpkg::Options::=--force-confold marionnet

The data packages

On its own, the application starts no virtual machine: it needs at least one image, and a kernel able to run it.

# the only router image
sudo apt install marionnet-fs-guignol
# the 32-bit kernel, the one for guignol and for .mar projects older than 2026
sudo dpkg --add-architecture i386 && sudo apt update
sudo apt install marionnet-kernels-i386

A router needs both packages: marionnet-fs-guignol and marionnet-kernels-i386. Guignol does not run on the 64-bit kernel.

An image for which no kernel is installed does not appear in Marionnet, and no message says so (full guide, § 1.A).

Whatever the method, go on to § 2 (images and kernels), then § 3 (sudoers rule) and § 4 (launch).

1.B Fedora, RHEL family and openSUSE

EPEL, for the RHEL family only

sudo dnf install epel-release

The key, the repository, the application

First the key, fetched and looked at before it is imported:

sudo install -d /etc/pki/rpm-gpg
sudo curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-marionnet \
     https://git.launchpad.net/marionnet/plain/marionnet-archive-keyring.asc
# must print the fingerprint of § 1
gpg --show-keys /etc/pki/rpm-gpg/RPM-GPG-KEY-marionnet
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-marionnet

If gpg is missing: sudo dnf install gnupg2, or sudo zypper install gpg2 on openSUSE.

Then the repository and the application, on Fedora and the RHEL family:

sudo curl -o /etc/yum.repos.d/marionnet.repo \
     https://www.marionnet.org/download/rpm/marionnet.repo
sudo dnf install marionnet

On openSUSE, zypper does not read the .repo file; give it the address of the repository:

sudo zypper addrepo --gpgcheck https://www.marionnet.org/download/rpm/ marionnet
sudo zypper install marionnet

The data packages

The same three packages as in § 1.A, for the same reasons. Here dnf installs none of them by itself, not even the 64-bit kernel.

# on openSUSE: sudo zypper install ...
sudo dnf install marionnet-kernels marionnet-fs-guignol
# the router needs it; not on RHEL 10
sudo dnf install marionnet-kernels-i386

RHEL 10 has removed the 32-bit libraries: marionnet-kernels-i386 cannot be installed there. Without it neither guignol nor wheezy runs, so there is no router. A 64-bit router image is planned.

Whatever the method, go on to § 2 (images and kernels), then § 3 (sudoers rule) and § 4 (launch).

1.C Any other distribution: the precompiled archive

wget https://www.marionnet.org/download/marionnet-install.sh/marionnet-install.sh
# optional: what is published, what your machine refuses, and why
bash marionnet-install.sh --binary --fetch-only --list
# the installer calls sudo itself when it needs to
bash marionnet-install.sh --binary --with-deps

--with-deps only knows Debian package names. Elsewhere, install yourself the equivalents of the packages it names (full guide, § 1.C).

Whatever the method, go on to § 2 (images and kernels), then § 3 (sudoers rule) and § 4 (launch).

1.D From source

Beforehand, only git and make are needed: make dependencies installs the rest (opam, the C compiler, the GTK libraries).

git clone https://git.launchpad.net/marionnet && cd marionnet
# Debian/Ubuntu: apt packages (build and run time), opam environment
make dependencies
# in every new shell: put the opam environment in the PATH
eval $(opam env)
# a fresh clone needs nothing else
dune build
# the target calls sudo itself, for the one step that needs it
make install-final-as-root

Whatever the method, go on to § 2 (images and kernels), then § 3 (sudoers rule) and § 4 (launch).

2. The images and the kernels, for every method

marionnet-get-images

marionnet-get-images is another name of marionnet-install.sh, installed with the application. The command shows the published images and kernels as a checklist, then fetches what you checked. Run it under your own account (it calls sudo to write the files) or as root. The images go where the installed Marionnet looks for them, hence for every account on the machine.

The two large images, Debian wheezy and Debian trixie, are published only this way and weigh several gibibytes. Without them you only have guignol, which serves both as a machine and as a router. If guignol is enough for you and you installed the data packages (§ 1.A, § 1.B), you can skip this step.

After a package installation, never give --prefix to this command: the images would land where the application does not look (full guide, § 2).

A computer lab without Internet access. Make a copy (a mirror) of the publication directory once: the file SHA256SUMS lists everything it contains.

# once, on a machine that has Internet access (about 1.5 GiB, compressed)
U=https://www.marionnet.org/download/marionnet-install.sh/1.0.x
mkdir -p /srv/marionnet-mirror && cd /srv/marionnet-mirror
wget "$U/SHA256SUMS"
awk -v u="$U" '{ print u "/" $2 }' SHA256SUMS | wget -i -
sha256sum -c SHA256SUMS

Then, on each machine, with /srv/marionnet-mirror shared or copied:

# --yes: no confirmation asked, for a deployment script
marionnet-install.sh --fetch-only --from /srv/marionnet-mirror --yes

marionnet-install.sh is installed with the application, whatever the method.

3. The sudoers rule, required for every method

No package sets it: a package cannot know which accounts the machine is meant for. Without it, Marionnet cannot create the network interfaces of its virtual machines.

For one account, or several:

sudo marionnet-sudoers.sh install <login>...

For a whole lab, even before the students have an account, grant a group:

# if the site has no group of its own yet
sudo groupadd marionnet
# each account, once created (or your LDAP/AD group)
sudo gpasswd -a <login> marionnet
sudo marionnet-sudoers.sh install %marionnet

This command grants block (a). It is the one that creates the network interfaces of the virtual machines, and that lets xterm or wireshark, started inside a virtual machine, show up on your screen.

The two other blocks serve the components that connect the virtual network to the real one: (b) the NAT bridge and (c) the LAN bridge. Marionnet asks for them the first time the component starts, with the user's own sudo password.

Block (c) reconfigures the network card of the host machine. Read the full guide, § 3.2, before granting it.

Students without sudo rights will therefore never get the NAT bridge by themselves. To give it to them in advance, without ever granting (c):

sudo marionnet-sudoers.sh install --enable-natbridge %marionnet

This command also grants block (a): it can replace the previous one, or follow it, since each install adds to the permissions already given.

To forbid a block on this machine, for everyone and for good:

sudo marionnet-sudoers.sh deny --lanbridge     # or --natbridge, or --bridges

To see where things stand, without privileges:

# exit code 0 if the block is allowed, 3 if it is forbidden
marionnet-sudoers.sh policy

To remove everything:

sudo marionnet-sudoers.sh uninstall

4. Launch Marionnet, and check the installation

marionnet                    # or: marionnet -r lab.mar, marionnet --exam, marionnet --help
marionnet -v                 # version and revision
marionnet --paths            # where this installation looks for images, kernels and scripts

Marionnet needs an X display.

5. Uninstall

sudo apt purge marionnet marionnet-kernels marionnet-kernels-i386 marionnet-fs-guignol
sudo dnf remove marionnet marionnet-kernels marionnet-kernels-i386 marionnet-fs-guignol

For the precompiled archive, the README file it contains lists what to delete.

In every case, the sudoers rule stays in place until sudo marionnet-sudoers.sh uninstall.

6. It does not work

What you see Read
server down, no route, wrong URL?, while the site answers full guide, § 1: no certificates
apt ignores the repository, and apt-get update still returns 0 full guide, § 6
Missing key, signature verification failed, Failed to import OpenPGP keys full guide, § 1.A and § 1.B: fetch the key again, check the fingerprint
the precompiled archive is refused, naming a glibc full guide, § 1.C: your distribution is too old
Marionnet starts, but the images do not appear full guide, § 2, then marionnet --paths
a virtual machine refuses to start, or nothing opens from it full guide, § 3: the sudoers rule