Cascade: Fixing Offline Build Issues In NLnetLabs Project

Nov 8, 2025 by Admin 58 views

Hey everyone!

During the RIPE91 meeting, some of the NLnetLabs folks asked me to test Cascade. So, naturally, my first step was to package it for my distro to make installation a breeze. But, surprise! It looks like the package can’t be built offline. This seems pretty similar to issue #165, if I’m not mistaken.

Here’s the error I’m seeing on my end:

alarig@x280 cascade % (master *%=) ebuild cascade-0.1.0_alpha4.ebuild install                  
>>> Existing ${T}/environment for 'cascade-0.1.0_alpha4' will be sourced.
>>> Run 'clean' to start with a fresh environment.
>>> Not marked as unpacked; recreating WORKDIR...
 * cascade-0.1.0_alpha4.tar.gz BLAKE2B SHA512 size ;-) ...                                                                     [ ok ]
 * cascade-0.1.0_alpha4-vendor.tar.xz BLAKE2B SHA512 size ;-) ...                                                              [ ok ]
 * Checking whether Rust 9999 is suitable ...
 *  Checking for dev-lang/rust:9999 ...
 *  Checking for dev-lang/rust-bin:9999 ...
 * Checking whether Rust 1.91.0 is suitable ...
 *  Checking for dev-lang/rust:1.91.0 ...
 *  Checking for dev-lang/rust-bin:1.91.0 ...
 * Checking whether Rust 1.90.0 is suitable ...
 *  Checking for dev-lang/rust:1.90.0 ...
 *  Checking for dev-lang/rust-bin:1.90.0 ...
 * Checking whether Rust 1.89.0 is suitable ...
 *  Checking for dev-lang/rust:1.89.0 ...
 * Using Rust 1.89.0 (source)
>>> Unpacking source...
>>> Unpacking 'cascade-0.1.0_alpha4.tar.gz' to /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work
>>> Unpacking 'cascade-0.1.0_alpha4-vendor.tar.xz' to /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work
>>> Source unpacked in /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work
>>> Preparing source in /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4 ...
>>> Source prepared.
>>> Configuring source in /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4 ...
>>> Source configured.
>>> Compiling source in /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4 ...
 * /usr/lib/rust/1.89.0/bin/cargo build --release
   Compiling proc-macro2 v1.0.101
   Compiling unicode-ident v1.0.19
   Compiling quote v1.0.41
   Compiling libc v0.2.176
   Compiling cfg-if v1.0.3
   Compiling pin-project-lite v0.2.16
     Running `/usr/lib/rust/1.89.0/bin/rustc --crate-name build_script_build --edition=2021 /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/vendor/proc-macro2/build.rs --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --crate-type bin --emit=dep-info,link -C embed-bitcode=no -C debug-assertions=off --cfg 'feature="default"' --cfg 'feature="proc-macro"' --check-cfg 'cfg(docsrs,test)' --check-cfg 'cfg(feature, values("default", "nightly", "proc-macro", "span-locations"))' -C metadata=f4b2f0329651dfc2 -C extra-filename=-5fa51e3e58ea516a --out-dir /home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/build/proc-macro2-5fa51e3e58ea516a -C strip=debuginfo -L dependency=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps --cap-lints allow -C strip=none -C linker=x86_64-pc-linux-gnu-gcc -C target-feature=-crt-static -C link-arg=-Wl,-O1 -C link-arg=-Wl,--as-needed -C link-arg=-Wl,-z,pack-relative-relocs -C target-cpu=native`
[...]
     Running `/usr/lib/rust/1.89.0/bin/rustc --crate-name cascade --edition=2021 src/bin/cascade.rs --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --crate-type bin --emit=dep-info,link -C opt-level=3 -C panic=abort -C embed-bitcode=no --cfg 'feature="default"' --check-cfg 'cfg(docsrs,test)' --check-cfg 'cfg(feature, values("default"))' -C metadata=a0040ff6fd06c46c -C extra-filename=-05e4495ebea6ce23 --out-dir /home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps -C strip=debuginfo -L dependency=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps --extern anstream=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libanstream-63192fb96169aeba.rlib --extern arc_swap=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libarc_swap-2344afb22372ac28.rlib --extern async_trait=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libasync_trait-78754e2871a43672.so --extern axum=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libaxum-6ef93be9375bd6b5.rlib --extern bytes=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libbytes-9a31884d137a868b.rlib --extern camino=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libcamino-eeef5fc606cf7cb8.rlib --extern cascade=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libcascade-2344e523521510c9.rlib --extern chrono=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libchrono-772ba82ba6718137.rlib --extern clap=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libclap-2abe5607ec1426dc.rlib --extern crossbeam_utils=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libcrossbeam_utils-555dc2f8eebf47fc.rlib --extern daemonbase=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libdaemonbase-1aee6ac0c66e29ef.rlib --extern domain=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libdomain-5e238379dd604e85.rlib --extern foldhash=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libfoldhash-580bdf77c0187d58.rlib --extern futures=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libfutures-25ba98840b669606.rlib --extern futures_util=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libfutures_util-87093b2e76d86e20.rlib --extern hostname=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libhostname-19312cbd8e48b0d4.rlib --extern humantime=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libhumantime-06a402aa002695b3.rlib --extern jiff=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libjiff-56b26ad6e9c5ba0e.rlib --extern octseq=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/liboctseq-f9035dcb339eaa6d.rlib --extern rayon=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/librayon-35ca8f82a577d1b8.rlib --extern reqwest=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libreqwest-31a26b87f5038662.rlib --extern ring=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libring-dcc0e5a4134253d4.rlib --extern serde=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libserde-7ae378e27a656005.rlib --extern serde_json=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libserde_json-3a4ffde86d078dda.rlib --extern serde_with=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libserde_with-7cbd14c6d5fd2f6d.rlib --extern supports_color=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libsupports_color-6e6fae3d4df39575.rlib --extern syslog=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libsyslog-3ff2c8838102d5bc.rlib --extern tempfile=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libtempfile-f2cef0eb3744d8d5.rlib --extern tokio=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libtokio-2ce4f410ad36e246.rlib --extern toml=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libtoml-0809e9ec6a38b771.rlib --extern tracing=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libtracing-e78504dbfe1ff677.rlib --extern tracing_subscriber=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/libtracing_subscriber-3580159a2082fc52.rlib --extern url=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/deps/liburl-12c0a00ab899229c.rlib -C strip=none -C linker=x86_64-pc-linux-gnu-gcc -C target-feature=-crt-static -C link-arg=-Wl,-O1 -C link-arg=-Wl,--as-needed -C link-arg=-Wl,-z,pack-relative-relocs -C target-cpu=native -L native=/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target/release/build/ring-17bf39144e6f7388/out`
    Finished `release` profile [optimized] target(s) in 3m 27s
>>> Source compiled.
>>> Test phase [not enabled]: net-dns/cascade-0.1.0_alpha4

>>> Install net-dns/cascade-0.1.0_alpha4 into /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/image
 * /usr/lib/rust/1.89.0/bin/cargo install --path ./ --root /var/tmp/portage/net-dns/cascade-0.1.0_alpha4/image/usr
  Installing cascade v0.1.0-alpha4 (/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4)
error: failed to compile `cascade v0.1.0-alpha4 (/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4)`, intermediate artifacts can be found at `/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4/target`.
To reuse those artifacts with a future compilation, set the environment variable `CARGO_TARGET_DIR` to that path.

Caused by:
  failed to get `domain` as a dependency of package `cascade v0.1.0-alpha4 (/home/tmp-portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4)`

Caused by:
  failed to load source for dependency `domain`

Caused by:
  Unable to update https://github.com/NLnetLabs/domain?branch=patches-for-nameshed-prototype

Caused by:
  the source git+https://github.com/NLnetLabs/domain?branch=patches-for-nameshed-prototype requires a lock file to be present first before it can be
  used against vendored source code

  remove the source replacement configuration, generate a lock file, and then
  restore the source replacement configuration to continue the build
 * ERROR: net-dns/cascade-0.1.0_alpha4::SwordArMor failed (install phase):
 *   cargo install failed
 * 
 * Call stack:
 *     ebuild.sh, line  143:  Called src_install
 *   environment, line 1559:  Called cargo_src_install
 *   environment, line  970:  Called die
 * The specific snippet of code:
 *       cargo_env "${@}" || die "cargo install failed";
 * 
 * If you need support, post the output of `emerge --info '=net-dns/cascade-0.1.0_alpha4::SwordArMor'`,
 * the complete build log and the output of `emerge -pqv '=net-dns/cascade-0.1.0_alpha4::SwordArMor'`.
 * The complete build log is located at '/var/tmp/portage/net-dns/cascade-0.1.0_alpha4/temp/build.log'.
 * The ebuild environment file is located at '/var/tmp/portage/net-dns/cascade-0.1.0_alpha4/temp/environment'.
 * Working directory: '/var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4'
 * S: '/var/tmp/portage/net-dns/cascade-0.1.0_alpha4/work/cascade-0.1.0-alpha4'
zsh: exit 1     ebuild cascade-0.1.0_alpha4.ebuild install
ebuild cascade-0.1.0_alpha4.ebuild install  1132.85s user 38.03s system 546% cpu 3:34.15 total
alarig@x280 cascade % (master *%=)

Let's dive into what's happening and how we can tackle this issue.

Understanding the Offline Build Challenge

When we talk about offline builds, we're referring to the process of compiling and packaging software without relying on an active internet connection. This is super important for reproducibility, security, and situations where you just don't have a stable connection. In the context of the NLnetLabs' Cascade project, the inability to build offline, as highlighted during the RIPE91 meeting, poses a significant hurdle. The core problem stems from how the project manages its dependencies, particularly the domain crate, which appears to be fetched directly from a Git repository. The error message clearly indicates that Cargo, Rust's package manager, is struggling to resolve this dependency without an internet connection. Specifically, it mentions the need for a lock file and issues related to vendored source code.

The error message, "Unable to update https://github.com/NLnetLabs/domain?branch=patches-for-nameshed-prototype", is a dead giveaway. It shows that the build process is trying to access a specific branch of the domain crate on GitHub. This is problematic for offline builds because Cargo can't just magically download the necessary files without a network connection. The subsequent error, "the source git+https://github.com/NLnetLabs/domain?branch=patches-for-nameshed-prototype requires a lock file to be present first before it can be used against vendored source code", further clarifies the issue. It suggests that the project is attempting to use vendored source code (i.e., pre-packaged dependencies), but the necessary lock file, which ensures consistent dependency versions, is either missing or outdated.

To summarize, the offline build is failing because the build process is trying to fetch a dependency (domain) from a Git repository without a network connection and is encountering issues with vendored source code due to a missing or outdated lock file. This situation underscores the importance of properly managing dependencies and ensuring that all necessary files are available locally for offline builds.

Diagnosing the Root Cause

To effectively address the offline build issue with the Cascade project, a thorough diagnosis of the root cause is essential. The error messages provide valuable clues, pointing towards problems with dependency resolution and the handling of vendored source code. Specifically, the inability to fetch the domain crate from GitHub and the requirement for a lock file suggest that the project's dependency management strategy is not fully optimized for offline builds. Let’s break down the potential culprits:

Missing or Outdated Lock File: Cargo uses a Cargo.lock file to ensure that all dependencies are resolved to specific versions. This file is crucial for reproducibility and is particularly important for offline builds. If the Cargo.lock file is missing, Cargo will attempt to resolve dependencies from scratch, which requires an internet connection. If the Cargo.lock file is outdated, it may contain references to older versions of dependencies that are no longer available locally.
Incorrect Vendoring Configuration: Vendoring is a technique for including all project dependencies directly within the source code repository. This ensures that all necessary files are available locally, making offline builds possible. However, if the vendoring configuration is incorrect, Cargo may still attempt to fetch dependencies from external sources, even if they are already present in the vendor directory. This can happen if the Cargo.toml file is not properly configured to use the vendored dependencies.
Git Dependency Resolution: The project's dependency on a specific branch of the domain crate in a Git repository introduces additional complexity. Cargo's default behavior is to fetch Git dependencies over the network, which is incompatible with offline builds. To resolve this, the Git dependency must be properly vendored, and the Cargo.toml file must be configured to use the vendored version.
Build Script Issues: Build scripts can sometimes introduce unexpected dependencies or network access. If the project's build script attempts to download files from the internet, this will obviously fail in an offline build environment. It's important to review the build script and ensure that it does not rely on any external resources that are not available locally.

By carefully examining these potential causes, we can narrow down the specific issue that is preventing offline builds and develop a targeted solution.

Solutions and Workarounds

Alright, let's get practical. Here’s how we can tackle this offline build issue for the NLnetLabs Cascade project. Based on the error messages and the diagnostic steps, here are several solutions and workarounds you can try:

Ensure a Complete and Updated Cargo.lock File:
- The Fix: First, make sure you have a Cargo.lock file in your project. If it's missing, generate one by running cargo generate-lockfile while you're online. This command resolves all dependencies and pins them to specific versions. If you already have a Cargo.lock file, ensure it’s up-to-date by running cargo update. This will update the dependencies to the latest compatible versions and update the lock file accordingly.
- Why it Works: The Cargo.lock file tells Cargo exactly which versions of dependencies to use. When building offline, Cargo will use the versions specified in this file, preventing it from trying to fetch anything from the internet.
Properly Vendor Dependencies:
- The Fix: Use cargo vendor to copy all project dependencies into a local vendor directory. This command downloads all dependencies and places them in the vendor directory within your project. Next, configure Cargo to use the vendored dependencies by adding the following to your .cargo/config file:
```
[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "vendor"
```
- Why it Works: By vendoring dependencies, you ensure that all necessary files are available locally. The .cargo/config file tells Cargo to look in the vendor directory first when resolving dependencies.
Address Git Dependencies:
- The Fix: For Git dependencies like the domain crate, you'll need to vendor them as well. Since cargo vendor doesn't directly support Git dependencies, you might need to manually download the source code for the domain crate and place it in the vendor directory. Then, update your Cargo.toml to point to the local path:
```
[dependencies]
domain = { version = "<version>", path = "vendor/domain" }
```
Replace <version> with the appropriate version number. Alternatively, you can use a tool like cargo-local-git-registry to create a local Git registry and add the domain crate to it.
- Why it Works: By pointing directly to the local path of the Git dependency, you bypass the need to fetch it from GitHub during the build process.
Review and Modify Build Scripts:
- The Fix: Examine the project’s build script (if any) for any network-related activities. Comment out or remove any lines that attempt to download files from the internet. If the build script requires external resources, ensure they are included in the vendor directory or are otherwise available locally.
- Why it Works: By eliminating network access from the build script, you prevent it from failing in an offline build environment.
Use Cargo Offline Mode:
- The Fix: When building, use the --offline flag with Cargo commands: cargo build --release --offline. This tells Cargo to avoid accessing the network.
- Why it Works: The --offline flag instructs Cargo to only use locally available dependencies and prevents it from attempting to download anything from the internet.

By implementing these solutions, you should be able to successfully build the NLnetLabs Cascade project offline. Remember to test each solution thoroughly to ensure it resolves the issue without introducing new problems.

Step-by-Step Guide to Resolve Offline Build Issues

Okay, let's make this super clear with a step-by-step guide to fix those pesky offline build problems with the Cascade project. Follow these steps, and you should be golden:

Step 1: Initial Setup (Online)

Clone the Repository: Start by cloning the Cascade repository to your local machine. Make sure you have Git installed.
```
git clone <repository_url>
cd <cascade_directory>
```
Generate the Lock File: Generate a Cargo.lock file to pin the dependencies. This needs to be done while you're online.
```
cargo generate-lockfile
```
Vendor Dependencies: Use cargo vendor to copy all dependencies to the vendor directory.
```
cargo vendor
```
Configure Cargo: Create a .cargo directory in the project root if it doesn't exist, and add a config file inside it.
```
mkdir .cargo
nano .cargo/config
```
Add the following configuration to the .cargo/config file:
```
[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "vendor"
```
Save and close the file.
Handle Git Dependencies (Domain Crate):
- Download the source code for the domain crate from the specified branch (patches-for-nameshed-prototype). You can do this by cloning the repository and checking out the correct branch:
```
git clone https://github.com/NLnetLabs/domain
cd domain
git checkout patches-for-nameshed-prototype
```
- Copy the domain crate source code into the vendor directory:
```
cp -r <path_to_domain_source> <cascade_directory>/vendor/domain
```
- Update the Cargo.toml file to point to the local path of the domain crate:
```
[dependencies]
domain = { version = "<version>", path = "vendor/domain" }
```
  Replace <version> with the appropriate version number.

Step 2: Build Offline

Disconnect from the Internet: Disable your internet connection to simulate an offline build environment.
Build the Project: Use the cargo build command with the --offline flag:
```
cargo build --release --offline
```
This command tells Cargo to use only the locally vendored dependencies and to avoid accessing the network.

Step 3: Verify the Build

Check the output for any errors. If the build is successful, you should see the compiled binaries in the target/release directory.

By following these steps, you can ensure that the Cascade project builds successfully in an offline environment. This approach ensures that all dependencies are available locally and that Cargo is configured to use them without attempting to access the network.

Conclusion

Alright, guys, we've covered a lot! Building software offline can be a bit of a headache, but it's super important for reliability and security. For the NLnetLabs Cascade project, the key is to manage those dependencies like a pro. Make sure your Cargo.lock file is up-to-date, vendor those dependencies correctly (including those pesky Git ones), and double-check your build scripts for any sneaky network calls. By following the steps outlined in this article, you should be able to get Cascade building offline without any issues. Happy building!