Skip to content

Manage Moss States and Packages

moss keeps track of packaging-related operations that change the state of the /usr directory by creating a new filesystem transaction (fstx) for each associated moss operation, be it adding or removing packages, or upgrading packages.

Use the commands below to manage your installed software packages, and keep your system current.

Keep the entire system current with a sync operation.

Terminal window
sudo moss sync --update
# This combines `sudo moss repository update` and then `sudo moss sync` into a single command
# `sudo moss repository update` pulls fresh repository metadata where `sudo moss sync` will sync your system to the

moss records the result as a new state so you can roll back if something goes wrong.

Use keyword searches to discover software by name or summary.

Terminal window
moss search something

Add --installed (-i) if you only want to search software that is already present on the system.

Look up which package delivered a specific file when you troubleshoot or audit an installation.

Terminal window
moss search-file filename

moss search-file scans files from installed packages only.

  1. Refresh repository metadata when needed.
Terminal window
sudo moss repo update
  1. Install one or more packages.
Terminal window
sudo moss package add somepackage

moss creates a new state automatically. Confirm success with moss state list to confirm the last state was just successfully created.

To remove packages you no longer need:

Terminal window
sudo moss package remove somepackage

moss snapshots the removal in a new state. Use moss state list to find the previous state if you have to recover.

List currently installed software packages

Section titled “List currently installed software packages”
Terminal window
moss package list --installed

Information about a software package, such as the version and dependencies. Works for both installed and non-installed packages.

Terminal window
moss package info somepackage

In the preceding examples, it was briefly mentioned that moss creates new “states”.

When using moss, state management is an important concept. This section details the fundamentals of moss state management.

moss is based on the concept of atomic updates. Atomic in this context means “independent units”. Each time the user instructs moss to change the state of the system, moss creates a new, independent state. Because each state is independent, it allows moss to roll back to an earlier state, and roll forward to a later state.

  1. List the active state to confirm what is running right now.
Terminal window
moss state get-active
  1. Review the state history when you need context for a rollback.
Terminal window
moss state list

Use the state ID (the number after State #) when you need to query, activate, or remove a specific state.

Follow these steps to roll back or advance to another state safely.

  1. Identify the target state ID with moss state list.
  2. Activate that state.
Terminal window
sudo moss state activate 128
  1. Verify the change.
Terminal window
moss state get-active

Activating a state atomically swaps the currently active state’s /usr directory with the new state’s /usr directory, using the Linux kernel renameat2 syscall.

On successful activation of the new state, it is recommended to reboot the system, so that long-running services start with the expected binaries, libraries, and configurations.

Over time, a system managed by moss will accumulate more and more states. Each state takes up space that is equivalent to the difference in packages between one state to another. If two states share a lot of package versions, the storage needed to keep the difference between states will be small.

There are a few ways to clean up retained states:

  • Remove, where you need to specify the state numbers you want to remove
  • Remove -k, where you remove all barring the last k number of states
  • Remove -p, where you remove all but the currently bootable states

This will prune state history to keep only the 10 latest states, including the current active state:

Terminal window
# Remove state number 5
sudo moss state remove 5
# Remove states 11, 12, 13 and 14
sudo moss state remove 11-14
# Remove states 5, 11, 12, 13, 14, 16, 20 and 21
sudo moss state remove 5 11-14 16 20-21

As you can see, state remove enables you to remove both individual states and ranges of states. Ranges are inclusive, meaning the start and end states of the specified range are also removed.

If you want to keep a different number of states, the -k / --keep parameter will let you specify the number of states you wish to keep:

Terminal window
# Keep the five latest states, including the active state
sudo moss state remove -k 5

If you want to keep prune everything but the currently bootable states, use the -p or --prune parameter:

Terminal window
# Remove everything but bootable states
sudo moss state remove -p

Fetch package .stone files for backup purposes

Section titled “Fetch package .stone files for backup purposes”

If you would like to keep an archive of stones, moss supports a fetch operation.

Use moss package fetch to download one or more package .stone files by name without installing them on the current system.

Terminal window
moss package fetch somepackage

Fetch multiple packages into a custom output directory:

Terminal window
moss package fetch package1 package2 --output-dir ~/stones

moss package fetch writes downloaded files to the current directory by default. Add --verbose when you need more detailed progress output. If a package cannot be resolved, refresh repository metadata and try again.

Note also that moss fetches .stones against currently active repository stone.index files.

You can list your currently active repository index with moss repo list.