Skip to content
Russet

How Russet works

Russet is a native implementation of AutoPkg’s recipe engine, command-line interface, and built-in processors. It runs the recipes that you already use, with the same command name and preference keys, but it keeps its own preferences and working folders, and it doesn’t run Python. This page explains the parts of Russet and how a recipe run uses them.

The parts of Russet

Section titled “The parts of Russet”

A Russet installation has the following parts:

  • The russet command: a single native executable for macOS, Linux, or Windows. It reads your preferences, finds recipes, and runs them.
  • The recipe engine: loads a recipe and its parent recipes, merges their input variables, checks trust information, and runs each processor in order.
  • Built-in processors: native implementations of the processors that recipes name in their Process steps, such as URLDownloader, CodeSignatureVerifier, and MunkiImporter. For the full list, see Processors.
  • Helper services: on macOS, two privileged launchd services that build packages and install software for recipes that run as a standard user. Both are the russet command, started as russet --server and russet --installd.

What happens when you run a recipe

Section titled “What happens when you run a recipe”

When you run russet run, Russet does the following:

  1. Reads your preferences and any --prefs file.
  2. Finds each recipe that you named, searching your override folders first and then your recipe search folders.
  3. Loads each recipe’s parent recipes and checks the MinimumVersion of every recipe in the chain.
  4. Verifies trust information for recipe overrides.
  5. Checks every processor that the recipes use. If any recipe names a processor that Russet doesn’t implement, Russet stops before it runs any recipe.
  6. Runs each recipe’s processors in order. Each processor reads variables from the recipe environment and adds its results to it.
  7. Writes a receipt for each recipe and records the run’s results in the cache.

Because Russet checks every recipe before it runs any of them, an unsupported recipe doesn’t leave a run half finished. For details, see Compatibility with AutoPkg.

Helper services

Section titled “Helper services”

On macOS, Russet needs root privileges to build a package or to install software. Russet uses the same design as Python AutoPkg: two launchd services run as root, and recipes ask them to do privileged work over a local socket.

Service Command Socket Used by
russet-server russet --server /var/run/russet-server PkgCreator, AppPkgCreator
russet-installd russet --installd /var/run/russet-installd Installer, InstallFromDMG

launchd starts each service when a recipe connects to its socket, and the service exits after it’s idle for 10 seconds. The services check who sent each request:

  • The package builder accepts a request only if the requesting user owns the package root and the output folder.
  • The package installer installs only packages in the recipe’s cache or on a volume mounted under /private/tmp, where Russet mounts disk images.

The Russet services have their own launchd jobs and sockets, so they don’t conflict with Python AutoPkg’s autopkgserver and autopkginstalld services on the same Mac. On Linux and Windows, the processors that need them report that only macOS supports package creation and installation.

Native tools

Section titled “Native tools”

Russet runs operating system tools where AutoPkg does:

  • Downloads: Russet downloads files with its built-in HTTP downloader, and runs curl for other web requests and for downloads that need curl. For details, see Downloads.
  • Recipe repositories: Russet runs Git to clone and update recipe repositories.
  • macOS operations: Russet runs tools such as hdiutil to mount disk images, pkgutil to expand packages, and codesign to verify signatures.
  • Windows operations: Russet runs choco.exe to build Chocolatey packages and signtool.exe to verify Authenticode signatures.

Russet doesn’t run makepkginfo or any other Munki tool. It generates Munki metadata natively. For details, see Import software into Munki.

Versions

Section titled “Versions”

Russet has two version numbers:

  • The distribution version identifies a Russet release, such as 0.1.0. Each release archive records it in RELEASE.json. An archive that you build from source doesn’t have a distribution version.
  • The compatibility version is the AutoPkg version that Russet implements. russet version prints it, and recipes receive it in the AUTOPKG_VERSION variable. Russet’s compatibility version is 3.0.0.

What’s next

Section titled “What’s next”