Avasile System Management

From Argent Linux Wiki
Revision as of 20:29, 25 September 2026 by Stefan (talk | contribs) (Argent Avasile management of the system.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Avasile

First of all, the holy avasile --help.

Vasile stands for "Versatile Advanced Script for ISOs and Latest Enhancements", and avasile is "Argent Vasile". It does two different jobs:

  • for users: it puts your system in one of the Argent modes (user mode, devmode, srcmode, ...), which decide if you install binaries, compile, or both
  • for developers: it builds packages and live ISO images in a clean chroot

The mode switches and the build commands need root. If you run them as a normal user, avasile tries to restart itself with sudo. avasile refuses to run on a live ISO.

To see every command avasile runs, step by step, add AVASILE_VERBOSE=1 in front:

AVASILE_VERBOSE=1 avasile --devmode

Which mode am I on?

avasile --status

It prints one of:

  • avasile is on --usermode
  • avasile is on --devmode!
  • avasile is on --srcmode!
  • avasile is on your own custom mode!
  • avasile is not on any known modes

The mode is simply which Argent make.conf your /etc/portage/make.conf/ points to. See the System Administration page for what that means for /etc/portage.

The modes

Mode Binaries Compiling Portage tree Who is it for
--usermode only binaries never minimal (no ebuilds) everybody, Gentoo newcomers
--devmode when they match your config when they don't full developers, advanced users
--srcmode no everything full people who want a pure Gentoo
--custom optional yes full people who want their own /etc/portage

Every mode switch starts from zero. --usermode, --devmode, --srcmode and --custom first remove:

  • the Gentoo portage tree (/var/db/repos/gentoo), except its packages and distfiles
  • the argent-ws overlay (/var/db/repos/argent-ws), except its packages and distfiles
  • the whole /etc/portage and /opt/argentws-build, including every file you made in there (your 100-my.* files, your 01-my.make.conf, your repos.conf additions)

and then download everything again. Keep a copy of your own files before you switch. It also needs internet and takes a while.

After the download, every mode:

  • makes /etc/portage a symlink to /opt/argentws-build/conf/intel/portage
  • points /etc/portage/make.conf/00-main.conf to the make.conf of that mode
  • sets the profile default/linux/amd64/23.0/desktop/plasma/systemd
  • runs env-update
  • refreshes the keys used to verify binary packages (unless you add --skip-keys)

If you run it from inside /etc/portage, avasile moves you to /etc first, since that directory is about to disappear.

User mode

avasile --usermode

This is the default Argent. Only binary packages from our binhost, nothing gets compiled. The Gentoo tree and the argent-ws overlay are downloaded minimal, only profiles, metadata and eclass, so they take very little space.

Don't change anything in /etc/portage in this mode.

You can also consider user mode your system rescue mode. Whatever you did to your configuration, avasile --usermode throws it away and puts your system back in complete obedience to the Argent remote repositories and configuration, the same ones our binaries were built with. When your system is lost, this is how you get it back on track. After that:

epkg upgrade

and your packages follow our binhost again.

Development mode

avasile --devmode

Binaries when they match your configuration, compiling when they don't, and what you compile is saved in /var/cache/binpkgs. You get the full Gentoo tree and the full argent-ws overlay. You can change USE flags and keywords, in your own files, like /etc/portage/package.use/100-my.package.use.

This is the mode you need for epkg compile, epkg recompile-depend and the rest of the developer commands.

Source mode

avasile --srcmode

Pure Gentoo: no binaries, everything is compiled from ebuilds, still synced with our overlay and our configuration.

epkg refuses to run in this mode, you use emerge, equery, eix, qlist and the rest of the Gentoo tools directly. You need to know them well.

Custom mode

avasile --custom

Alpha feature, not yet recommended.

Like source mode, but /etc/portage becomes yours:

  • your make.conf is make.conf.amd64-custom, a copy of the devmode one, which you can change freely
  • /opt/argentws-build is disconnected from our git, so epkg update no longer brings you our configuration
  • our package.use and package.accept_keywords files are deleted, you start with your own

avasile --status shows it as "your own custom mode".

Decentralized modes

avasile --decentralize-user

avasile --decentralize-dev

avasile --decentralize-source

avasile --decentralize-custom

These are for advanced Gentoo users who run their own independent system, with their own binhost configuration. Unlike the modes above, they don't delete and don't download anything: they only switch the make.conf (user, devel, srcmode or custom), set the profile and run env-update. They need /opt/argentws-build to already exist.

Run epkg update (or emerge --sync) after switching.

avasile --decentralize-gentoo

One way ticket. Your system forgets it was ever Argent: it switches to the custom make.conf, removes the Argent git link and deletes our package.use and package.accept_keywords files. There is no central authority anymore, you are on your own. If you ever want to come back to Argent: 

cd /etc/portage && git init
git remote add origin https://gitlab.com/argent/argentws-build.git
git pull --depth=1 origin master
git branch -u origin/master master

Resetting

avasile --resetmode

Removes the Gentoo tree, the argent-ws overlay and all of /etc/portage, and doesn't put anything back. Never leave your system like this: you can't install, remove or upgrade anything until you choose a mode again (or configure portage by hand).

Binary package keys

Every mode switch refreshes the keyring that portage uses to verify our binary packages (/etc/portage/gnupg, with getuto). If you have no access to the keyservers, skip it:

avasile --devmode --skip-keys

(--no-keys is the same thing.)

If the keyring is broken, rebuild it from scratch:

avasile --regen-keys

This is the same as epkg regen-keys.


For developers: building packages and ISOs

These two commands are what we use to build Argent itself. They work in a clean chroot made from the Argent core squashfs, so your own system is never touched.

What you need:

  • a kernel with CONFIG_OVERLAY_FS, CONFIG_SQUASHFS and CONFIG_BLK_DEV_LOOP, and with /proc/config.gz enabled, avasile checks them there
  • sys-boot/grub:2, sys-fs/squashfs-tools, dev-libs/libisoburn, sys-fs/mtools, net-misc/rsync, sys-kernel/dracut, dev-vcs/git
  • optionally sys-fs/zerofree, which makes the ISO smaller
  • a working directory with the core squashfs and its checksum:
argent_ws_1_core_x64.squashfs
argent_ws_1_core_x64.squashfs.md5

The core squashfs is a minimal Gentoo stage3, with our argentws-build settings. We don't distribute it, you make it yourself.

Run avasile from that directory, otherwise it doesn't find the squashfs and stops. It also stops if the md5 doesn't match.

Building packages

avasile --makepkg <package(s)>

For example:

avasile --makepkg wine playonlinux q4wine

The working directory also needs a packages and a distfiles directory, they are mounted in the chroot as /var/cache/binpkgs and /var/cache/distfiles.

What happens:

  • the core squashfs is mounted read only, with an overlay on top of it (rodir, rwdir, workdir, overlaydir in your working directory)
  • inside the chroot, avasile --srcmode sets up the full trees and our configuration
  • emerge -kav <package(s)> builds your packages, using the binaries you already have in packages for the dependencies
  • you are dropped into a root shell in the chroot, to fix build failures, try USE flags and keywords, and so on
  • when you exit the shell, everything is unmounted

Everything you change in the chroot stays in rwdir, so the next --makepkg starts from where you left. Delete rwdir and workdir to start from a clean core again.

If you give no package, avasile only prepares the chroot and gives you the shell.

Known issue: the packages directory is mounted read only in the chroot, so the packages you build there can't be saved into it yet. This will be fixed in avasile.

Building a live ISO

avasile --makeiso (interactive)

avasile --makeiso /etc/portage/sets/artwork (automated)

The arguments are files with one package per line, like our sets in /etc/portage/sets/. You can give more than one, they are all installed together.

What happens:

  • a 20 GiB ext4 image is created, and the core squashfs is copied into it
  • the kernel kernel-genkernel-x86_64-6.12.110-argent is taken as boot/vmlinuz
  • inside the image, avasile --usermode sets up the configuration
  • a live initramfs is generated with dracut (dmsquash-live), as boot/initrd
  • the EFI (bootx64.efi) and BIOS (core.img, lnxboot.img) boot images are generated
  • a live INSTALL_MASK is added (/etc/portage/make.conf/zz-live.conf), so documentation, man pages, debug files and static libraries are not installed on the ISO
  • the packages are installed: from your lists with epkg autoinstall, or, without lists, you get a root shell in the image to install and configure whatever you want, and you exit when you are done
  • the live INSTALL_MASK is removed again
  • the live services are enabled (argentlive, sddm, NetworkManager, cups, avahi-daemon, the VirtualBox guest services, ...), and PipeWire replaces PulseAudio
  • the free space in the image is zeroed (with zerofree), and everything is compressed into a squashfs
  • the GRUB configuration is downloaded from https://gitlab.com/argent/boot-core.git
  • the ISO is made with grub-mkrescue

The result is in your working directory:

argent-ws-1-x86_64.iso

The binary packages installed in the ISO come from ISO_BINPKGS_SOURCE (see below), mounted read only in the image as /var/cache/binhost/binhost-main. The default is the path on our build server, so you have to set it to your own packages directory.

If something fails in the middle, --makeiso unmounts everything on exit.

Environment variables

You can change these on the command line, for example:

KERNEL_VERSION=6.12.100 ISO_BINPKGS_SOURCE=/srv/binpkgs avasile --makeiso /etc/portage/sets/artwork

Variable Default What it does
AVASILE_VERBOSE 0 1 prints every command avasile runs
AVASILE_SKIP_KEYS 0 1 is the same as --skip-keys
KERNEL_VERSION 6.12.110 the Argent kernel used for the ISO
ISO_BINPKGS_SOURCE our build server path the binary packages installed in the ISO
ISO_BINPKGS_TARGET /var/cache/binhost/binhost-main where they are mounted inside the ISO
ISO_LIVE_CONF /etc/portage/make.conf/zz-live.conf the file with the live INSTALL_MASK
ISO_INSTALL_MASK docs, man, info, debug, *.la, *.a what is not installed on the ISO
PORTAGE_REPO https://gitlab.com/argent/argentws-build.git the central configuration repository
PORTAGE_MAIN_CONFDIR /opt/argentws-build where it is cloned
PORTAGE_GITDIR /opt/argentws-build/conf/intel/portage what /etc/portage points to
PORTAGE_MAIN_CONF 00-main.conf the name of the main make.conf, when there is none yet
ARGENT_MAIN_DIR /var/db/repos/argent-ws where the argent-ws overlay lives
Retrieved from "https://wiki.argentlinux.io/index.php?title=Avasile_System_Management&oldid=63"