Honoring Asian Pacific American Heritage Month. See how.

Software delivery

Fuchsia software is delivered on demand to the system through packages. This is a critical component to Fuchsia's core design principles of security and updatability. Packages can be updated independently and delivered on demand, like a web page. This enables a vulnerability patch to be pushed to all Fuchsia products at once without the need for individual product coordination.

A package is not a single archive or image file, but rather a tree of Binary Large Objects (BLOBs). The root of the tree is a BLOB called "meta.far" which contains metadata for the package, including a "meta/contents" file which contains references to the rest of the BLOBs. The BLOBs inside Fuchsia packages are content-addressed, meaning they are referenced using a hash of their contents. The content address of the meta.far itself is known as the package hash.

The meta.far contains a meta/ directory with at least the following two items:

  • meta/package: JSON file containing the package's identity information such as name and version.
  • meta/contents: A map of the human-readable file names in a package to their content addresses.

Diagram showing the contents of a Fuchsia package consisting of "meta.far"
metadata and a collection of content BLOBs.

If two or more packages share the same content (such as a library dependency, or font resource), their metadata will point to the same content address for that resource. This enables Fuchsia to optimize package distribution and storage by avoiding the need to fetch and save a content BLOB that already exists.

Hosting and serving packages

Packages are hosted in repositories based on The Update Framework (TUF). This framework is a specification designed to enable secure delivery of software updates. TUF repositories secure updates through signed metadata attached to records that are verifiable against known trusted public and private keys. This means that any HTTP server can serve a TUF repository without the need for transport-level security, including a developer's workstation!

Packages within a repository are identified by a URL with the fuchsia-pkg scheme:

  • repo-hostname: Hostname of a trusted package repository, such as fuchsia.com.
  • pkg-name: Unique identifier for the package in this repository.
  • resource-path: Resource contained within the package, such as a component manifest.

Diagram showing how packages are resolved from a TUF repository and cached
locally on the device.

Requests for software on a Fuchsia device are handled by the package resolver. The package resolver determines if the system already has the package cached locally. If not, the resolver fetches the meta.far from the repository and updates the necessary content BLOBs.

Storing packages

On the device, package BLOBs are stored in a content-addressable filesystem optimized for write-once, read-often files called blobfs. This allows them to be de-duplicated across all packages and cryptographically verified using their hash. Fuchsia runs the pkg-cache service on top of blobfs to facilitate package management.

Diagram illustrating how the package cache is built on top of "blobfs" — a
content-addressable filesystem that de-duplicates BLOBs allowing them to be
shared between packages.

The pkg-cache layer tracks which packages in the system are currently active. Packages are not explicitly installed or removed in Fuchsia. Software is delivered on demand and likewise space can be reclaimed from packages that are no longer active through periodic garbage collection. When pkg-cache triggers garbage collection to reclaim space, content BLOBs not referenced by any active package are deleted.

Exercise: Packages

So far in this codelab, you've been experiencing on demand software delivery to your device and you probably didn't even know it! In this exercise, you'll peel back the covers and see the details of how packages are delivered and stored on a Fuchsia device.

Start the emulator

If you do not already have an instance running, start FEMU with networking support:

ffx emu start --headless workstation.qemu-x64

Register a new package server

List the package repositories configured in your package server:

ffx repository list

This command prints output similar to the following:

| NAME                 | TYPE | EXTRA                                         |
| fuchsiasamples.com   | pm   | /home/alice/.package_repos/sdk-samples        |
| workstation.qemu-x64 | pm   | /home/alice/.local/share/Fuchsia/.../packages |

The workstation.qemu-x64 repository is created when you run the ffx product-bundle get command (previously in "Get started with the Fuchsia SDK" quickstart guide). This repository contains additional system packages for the workstation.qemu-x64 prebuilt image.

Start a local package server instance to begin serving these packages:

ffx repository server start
server is listening on [::]:8083

Configure the emulator to resolve package URLs for fuchsia.com from the local package server:

ffx target repository register -r workstation.qemu-x64 --alias fuchsia.com

Examine the package server

With the local package server running, you can explore the list of packages that are available in the repository:

ffx repository package list -r workstation.qemu-x64

This command prints additional details about each package in the repository, including the individual components.

Monitor package loading

Packages are resolved and loaded on demand by a Fuchsia device. Take a look at this in action with the bouncing_ball example package.

From the device shell prompt, you can confirm whether a known package is currently on the device:

fssh pkgctl pkg-status fuchsia-pkg://fuchsia.com/bouncing_ball
Package in registered TUF repo: yes (merkle=ef65e2ed...)
Package on disk: no
fssh ERROR: Error running ssh: exit status 2

Open a new terminal and begin streaming the device logs for pkg-resolver:

ffx log --filter pkg-resolver

This shows all the instances where a package was loaded from the package server.

From the device shell prompt, attempt to resolve the package:

fssh pkgctl resolve fuchsia-pkg://fuchsia.com/bouncing_ball

Notice the new lines added to the log output for pkg-resolver:

[128.297][core/pkg-resolver][pkg-resolver][I] Fetching blobs for fuchsia-pkg://workstation.qemu-x64/bouncing_ball: [
[128.386][core/pkg-resolver][pkg-resolver][I] resolved fuchsia-pkg://fuchsia.com/bouncing_ball as fuchsia-pkg://workstation.qemu-x64/bouncing_ball to bb0515ee231c3b07da82234d015508f8799ed26b828e8dae16b3e9c59bd87cf2 with TUF

From the device shell prompt, check the package status again on the device:

fssh pkgctl pkg-status fuchsia-pkg://fuchsia.com/bouncing_ball
Package in registered TUF repo: yes (merkle=ef65e2ed...)
Package on disk: yes (path=/pkgfs/versions/ef65e2ed...)

Fuchsia resolved the package and loaded it from the local TUF repository on demand!

Explore package metadata

Now that the bouncing_ball package has successfully been resolved, you can explore the package contents. Once resolved, the package is referenced on the target device using its content address.

From the device shell prompt, use the pkgctl get-hash command to determine the package hash for bouncing_ball:

fssh pkgctl get-hash fuchsia-pkg://fuchsia.com/bouncing_ball

Provide the full package hash to the pkgctl open command to view the package contents:

fssh pkgctl open ef65e2ed...
opening ef65e2ed...
package contents:

This lists the package metadata and each of the content BLOBs in the package. You can see bin/ entries for executables, lib/ entries for shared library dependencies, additional metadata and resources.

What's Next?

Congratulations! You now have a better understanding of what makes Fuchsia unique and the goals driving this new platform's design.

In the next module, you'll learn more about building Fuchsia's fundamental unit of software:

Fuchsia components