TT Lab
Blog Get started
Learn Learning paths Courses

Package Management

Building an Offline Transfer Bundle

Continue in TT Lab

Goal

You bundle one package and all of its dependencies into an "import bundle", verify it with a checksum manifest, and reproduce the installation from that bundle alone. It is a scaled-down version of the procedure for importing into an air-gapped network. At the end, when a bundle someone else made fails on the inside, you separate what to fix on the inside from what to pass on to the next import.

Why it matters

The most common failure on an air-gapped network is "I took it in but the dependencies were short, so I have to go back out". In an organization where the import review happens only once a day, one round trip is a day. That is why an experienced person goes in carrying the result of solving the dependency graph in full on the outside. And you need a way to confirm that the files that passed through the medium are intact — a checksum catches corruption in transit, and a signature guarantees the origin. This lab gets the skeleton of that procedure into your hands.

The incident in the last step shows what happens when that procedure misses a spot here and there. A bundle has three layers (files, manifest, and index), so the same symptom, "it won't install", becomes either "just regenerate the index on the inside" or "wait a week for the next import", depending on which layer is wrong. Get that judgment wrong and you add one more round trip.

Steps

  1. Create the /root/offline directory and save the list of URIs of the files you would need to download to install cowsay to /root/offline/uris.txt. (You must not actually install it.)
  2. Only download cowsay and its dependencies, and gather the downloaded .deb files in /root/offline/pool/. There must be at least 2.
  3. Create a SHA-256 manifest for all the .deb files in /root/offline/pool as /root/offline/manifest.sha256.
  4. Run the verification with that manifest and save the result to /root/offline/verify.txt. Every line must be OK.
  5. To turn /root/offline/pool into a repository, generate Packages and Packages.gz.
  6. Register this repository as /etc/apt/sources.list.d/labhub-airgap.list and refresh the index.
  7. Reinstall cowsay to confirm that the install also works from the imported files, and after installing, save the result of running cowsay labhub to /root/offline/run.txt.
  8. Incident: run incident pk-bundle-broken and read the ticket. Three of the four packages in an import bundle will not install. Fix and install those that can be fixed on the inside, and in /root/incident/pk-bundle-broken/report.txt write a cause code for each package (corrupt-file, missing-dep, stale-index, unsigned, wrong-arch), what to bring in the next import (refetch:), and one evidence: line.

Notes

First calculate what must be downloaded

Create the /root/offline directory and save the list of URIs of the files you would need to download to install cowsay to /root/offline/uris.txt. (You must not actually install it.)

apt-get install has an option that does not actually download and only prints the list of URIs to download. Look for the simulation-family options.

Downloading the packages

Only download cowsay and its dependencies, and gather the downloaded .deb files in /root/offline/pool/. There must be at least 2.

There is an option that only downloads without installing. The downloaded files pile up in the apt cache directory.

Creating the checksum manifest

Create a SHA-256 manifest for all the .deb files in /root/offline/pool as /root/offline/manifest.sha256.

If you run sha256sum on several files at once, you get the 'hash, space, file name' format. It is a format you can use as is for verification later.

Verifying with the manifest

Run the verification with that manifest and save the result to /root/offline/verify.txt. Every line must be OK.

sha256sum has an option that reads a manifest instead of a file and checks against it. You have to run the verification in the directory that holds the manifest for the paths to match.

Making a repository index from the imported files

To turn /root/offline/pool into a repository, generate Packages and Packages.gz.

It is the same method as in the previous lab. This time, though, there are several files, so check the number of Package entries in the index.

Registering the import repository

Register this repository as /etc/apt/sources.list.d/labhub-airgap.list and refresh the index.

Give the repository a name different from the previous lab. It is fine if both repositories are valid at the same time.

Reinstalling from the import repository

Reinstall cowsay to confirm that the install also works from the imported files, and after installing, save the result of running cowsay labhub to /root/offline/run.txt.

To install an already installed package again at the same version, you need the reinstall option.

Incident: three of four packages in an import bundle will not install

Running incident pk-bundle-broken gives you a server with a bundle brought into the air-gapped network (/srv/airgap/bundle-2026-11) attached as an apt repository (read the ticket first). Symptom: of ttdata, ttfmt, ttplot, and ttcli, only ttdata installed. Fix and install what can be fixed on the inside, and leave what must be brought in again from outside on the next import list. Only files that match the approved manifest and hashes may remain in the bundle, and the index must match those files exactly. Editing the manifest or forcing things in while ignoring dependencies is a failure. In /root/incident/pk-bundle-broken/report.txt, write three lines <패키지>: <코드> (package: code; ttfmt, ttplot, ttcli), refetch: <다음 반입에 가져올 패키지 이름들> (the package names to bring in the next import), and evidence: <관찰한 출력 한 줄> (one line of output you observed). The code is one of corrupt-file (the file was damaged passing through the media), missing-dep (a dependency package is not in the bundle), stale-index (the index is older than the bundle contents), unsigned (refused because there is no signature), or wrong-arch (the architecture differs).

Direction: a bundle has three layers, "files + manifest + index". If you work out which layer is wrong for each package, what can be fixed on the inside and what must be brought in again from outside separate by themselves. Tools: the import log (/var/log/airgap-install.log), sha256sum's manifest check, the bundle's Packages, dpkg-deb -f (control fields), dpkg-scanpackages. Concretely: look at the lines that failed the manifest check, the difference between the Package list in the index and the list of .deb files in the pool, and whether the name ttplot's Depends points to is in the bundle. If a broken file remains in the pool when you regenerate the index, it goes into the index too.