Building an Offline Transfer Bundle
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
- Create the
/root/offlinedirectory and save the list of URIs of the files you would need to download to installcowsayto/root/offline/uris.txt. (You must not actually install it.) - Only download
cowsayand its dependencies, and gather the downloaded.debfiles in/root/offline/pool/. There must be at least 2. - Create a SHA-256 manifest for all the
.debfiles in/root/offline/poolas/root/offline/manifest.sha256. - Run the verification with that manifest and save the result to
/root/offline/verify.txt. Every line must be OK. - To turn
/root/offline/poolinto a repository, generatePackagesandPackages.gz. - Register this repository as
/etc/apt/sources.list.d/labhub-airgap.listand refresh the index. - Reinstall
cowsayto confirm that the install also works from the imported files, and after installing, save the result of runningcowsay labhubto/root/offline/run.txt. - Incident: run
incident pk-bundle-brokenand 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.txtwrite a cause code for each package (corrupt-file,missing-dep,stale-index,unsigned,wrong-arch), what to bring in the next import (refetch:), and oneevidence:line.
Notes
- Downloaded files usually pile up in
/var/cache/apt/archives/. If you empty the cache beforehand, only what was downloaded this time remains, which makes it easy to tell apart. - Common mistake 1: if you make the manifest in step 3 with absolute paths, the verification in step 4 breaks from a different directory. It is safer to go into the pool directory and make it with relative paths.
- Common mistake 2: if you actually install in step 1, step 2 downloads nothing, saying "already the newest version".
- Common mistake 3: the index refresh fails with
Permission deniedin step 6. apt drops to an unprivileged user called_aptonly when it downloads files, and because/rootis 700, that user cannot pass through. Opening just the one "enter" bit (x) for other users is enough; listing (r) is still blocked. - Common mistake 4: in the incident, regenerating the index while leaving the broken file in place. The index tool writes an entry after reading just the front of the file (the control information), so the broken file masquerades as "installable".
- Incident tools:
incident listshows the list, andincident show <이름>(name) shows the ticket (a colleague's report) again. Raising the same incident again returns it to its original broken state. - Write the report to
/root/incident/<이름>/report.txt(name is the incident name): one line<이름>: <원인 코드>(name: cause code) per target, plusevidence: <관찰한 출력 한 줄>(one line of output you observed). The evidence line is checked against the output actually seen in the incident. - Grading does not look only at the report. The actual state, such as the dpkg status DB, apt's candidate, and signature verification, must be right, and workarounds that only erase the symptom (forced installs, removals, turning off signatures) fail.
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.