Blog on Giovanni Bassi

NixOS: Installation Guide with RAID 1, encryption, and TPM unlock (part 7 - Mitigating the OS swap attack)

giggio@giggio.net (Giovanni Bassi) — Mon, 01 Jun 2026 11:00:00 -0300

There is still a loophole where one could obtain the LUKS volume encryption key using another operating system. Let’s fix that.

This is the seventh post in the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot
Unlocking the disk with TPM
Mitigating the volume swap attack
Mitigating the OS-switch attack (this post)

If you are only using your own keys in Secure Boot, this post doesn’t apply to your scenario. If you are also using Microsoft’s keys, you need to implement this mitigation.

The Problem

So far, we have been linking disk decryption to PCR 7 (and PCR 15 for system loading, as described in the last post). As seen in previous posts, PCR 7 depends exclusively on the Secure Boot state. This means that, regardless of which operating system is loaded, PCR 7 will have the same values.

If you also trust third-party keys (such as Microsoft’s or another manufacturer’s, like Canonical’s) in Secure Boot, there is still an attack surface that allows booting another system signed by those authorities. Therefore, it’s necessary to bind the protection to something beyond just PCR 7.

With the operating system loaded and PCR 7 in the correct configuration, it’s possible to obtain the LUKS volume header data and decrypt it using the TPM to get the LUKS master key, and then decrypt the volume. This could even be done using a Live CD with a correctly signed boot loader.

Naively sealing the LUKS key with the NixOS boot loader

Sealing the volume key only with PCR 7 is risky, so let’s also use another PCR that is closely tied to our operating system. PCR 4 measures the boot loader and additional drivers — the boot loader/PE binary code executed in the boot path. This means only an operating system that loads using the NixOS .efi files we are using would be able to retrieve the LUKS key via the TPM.

Since these .efi files are generated on-demand for our specific NixOS configuration and signed with Lanzaboote using our private keys, this prevents another OS from decrypting the LUKS key. For instance, if you load Ubuntu, the boot loader will be Ubuntu’s, with different .efi files, and therefore the content extended into PCR 4 will also be different. Because PCR 4 measures the EFI/PE binary actually executed at boot, a different boot path produces a different measurement and cannot reuse the same TPM token.

This would be simple if the boot loader didn’t change every time the Kernel, initrd, or any boot configuration is updated, which ends up changing PCR 4. If that weren’t the case, we could simply run:

# remove previous token from disk 1
sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/disk/by-label/NIXLUKS1
# enroll new token using PCR 4 and PCR 7 on disk 1
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=4+7 /dev/disk/by-label/NIXLUKS1
# do the same for disk 2...

Note: The commands above can be combined into one, which will wipe and enroll in a single operation.

This will only work until the next time the boot loader files (the .efi files) are changed. On the first boot after such a change, the volume will no longer decrypt automatically, it will ask for the password, and you would need to run the commands above again. If that’s acceptable to you, you don’t even need to read the rest of the post, but I can tell you there is a better and equally secure way to solve this.

Sealing the LUKS key with the NixOS boot loader using a PCR policy

Important: Before starting, verify that your virtual machine is configured to use only one of the disks as a boot disk. I noticed that if both disks are marked as boot disks, PCR 4 is not correctly evaluated and the policy is not created. In the virtual machine settings, you can see this in the “Boot Options” menu. This might be a quirk of Virtual Machine Manager (and virsh), the Firmware used, or something related to Secure Boot and TPM protocols. The problem doesn’t occur on my physical machine, only on the virtual one.

The secret to solving this problem is a system that can predict the values that will be in the PCR and create an appropriate policy, and that is exactly what systemd-pcrlock does. While the process can be done manually, Lanzaboote recently implemented TPM measurement alongside Secure Boot integration, using systemd-pcrlock. At the time of writing, this hasn’t made it into a release yet, meaning it might contain bugs. By the time you read this, the functionality may have stabilized.

To enable it, simply add this to your configuration:

boot.lanzaboote = {
 enable = true;
 pkiBundle = "/var/lib/sbctl";
 configurationLimit = 8;
 measuredBoot = {
 enable = true;
 pcrs = [ 4 7 ];
 };
};

Finally, you need to perform a nixos-rebuild, but use boot instead of switch:

sudo nixos-rebuild boot

This will prepare the configuration, but it will only be used on the next boot. This is important to ensure that the boot loader files are correctly signed, in addition to preparing the PCR 7 files.

Note: systemd-pcrlock has several subcommands that allow you to “lock” a specific PCR. “Locking,” as used here, means inspecting the events of each PCR and generating .pcrlock files in the /var/lib/pcrlock.d directory. For example, systemd-pcrlock lock-firmware-code generates the file /var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock with PCR 0 and 2 measurements. Lanzaboote uses this system when you enable PCR 7 by running systemd-pcrlock lock-secureboot-authority and systemd-pcrlock lock-secureboot-policy. This is done by creating two oneshot systemd services: systemd-pcrlock-secureboot-authority and systemd-pcrlock-secureboot-policy.

Reboot the system. The LUKS key is still tied only to PCR 7, and the disks will be decrypted automatically. After the reboot, the policy file will have been created. You can verify if both PCRs are present in the file by running:

$ jq '.pcrValues.[].pcr' /var/lib/systemd/pcrlock.json
4
7

If this is correct, you can now remove the token from the disk headers that was tied only to PCR 7 and create a new one using the policy via the generated file:

# remove previous token and enroll new token using the policy on disk 1
sudo systemd-cryptenroll --tpm2-device=auto --wipe-slot=tpm2 --tpm2-pcrlock=/var/lib/systemd/pcrlock.json /dev/disk/by-label/NIXLUKS1
# remove previous token and enroll new token using the policy on disk 2
sudo systemd-cryptenroll --tpm2-device=auto --wipe-slot=tpm2 --tpm2-pcrlock=/var/lib/systemd/pcrlock.json /dev/disk/by-label/NIXLUKS2

With this, you can reboot again. The disk should continue to unlock automatically, but this time it is using the policy file, and therefore PCRs 4 and 7.

The functionality is now complete. Whenever the boot loader files are updated, the policy will also be updated, and the disk will be decrypted automatically without requiring any manual interaction. In the following sections, I will dive deeper into what is happening.

Inspecting TPM events

You can check TPM events by running sudo systemd-pcrlock log, or just sudo systemd-pcrlock. Unfortunately, the command doesn’t allow showing events for a specific PCR, so you can do it using JSON and jq. To see only PCR 4 events, run:

sudo systemd-pcrlock log --json=short 2>/dev/null | jq '[.log[] | select(.pcr == 4)]'

To see the components registered in systemd-pcrlock, use the list-components command:

$ sudo systemd-pcrlock list-components
ID VARIANTS
240-secureboot-policy /var/lib/pcrlock.d/240-secureboot-policy.pcrlock.d/generated.pcrlock
350-action-efi-application /nix/store/f4s218swc4kw35apcqg9al8d7s287x7y-pcrlock.d/350-action-efi-application.pcrlock
400-secureboot-separator /nix/store/f4s218swc4kw35apcqg9al8d7s287x7y-pcrlock.d/400-secureboot-separator.pcrlock.d/300-0x00000000.pcrlock
500-separator /nix/store/f4s218swc4kw35apcqg9al8d7s287x7y-pcrlock.d/500-separator.pcrlock.d/300-0x00000000.pcrlock
620-secureboot-authority /var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock
630-bootloader /var/lib/pcrlock.d/630-bootloader.pcrlock.d/current.pcrlock
635-lanzaboote /var/lib/pcrlock.d/635-lanzaboote.pcrlock.d/7.pcrlock

These components are used to predict the values of each PCR. They are what “lock” the TPM. The idea is that systemd-pcrlock lock-* commands check TPM events and generate these components, along with Lanzaboote generating the PCR 4 (boot loader) ones at every nixos-rebuild.

Finally, you can check the measurements being used by running systemd-pcrlock predict:

$ sudo systemd-pcrlock predict --pcr=4,7
Event log record 0 (PCR 0, "Raw: 2\0008\000\000\000") not matching any component.
Event log record 9 (PCR 1, "Raw: ACPI DATA") not matching any component.
Event log record 13 (PCR 2, "Raw: \030\377\004\000") not matching any component.
Event log record 27 (PCR 5, "GPT: disk 8118a150-5781-4514-94f0-517c327f4ca7") not matching any component.
Event log record 40 (PCR 9, "Linux: kernel command line") not matching any component.
Event log record 31 (PCR 11, "String: .linux") not matching any component.
Event log record 39 (PCR 12, "String: Global credentials initrd") not matching any component.
Event log record 44 (PCR 15, "cryptsetup:crypt_disk1:5a2876f5-9220-4040-8b56-7bc226c9d649") not matching any component.
3 combinations of components.
PCR 4 (boot-loader-code) matches event log and fully consists of recognized measurements. Including in set of PCRs.
PCR 7 (secure-boot-policy) matches event log and fully consists of recognized measurements. Including in set of PCRs.
PCRs in protection mask: 4 (boot-loader-code), 7 (secure-boot-policy)
Results for PCR 4 (boot-loader-code):
 sha256: 19d6c3ffa28c30062e84d8e90a357a6319ce921dfa15ee6618a5f9c38a5e9890
 sha256: 58d68b2aa60262d9831fdd1b8b0f50fd30610162bf3ae7f19d4722e21ba24277
 sha256: 480319eadf7ad52de18d44758204505cf34a4def787c762e1da3024a69b2ec8e
Results for PCR 7 (secure-boot-policy):
 sha256: cc1dc9cbd11e3ad0a695744ab152362d388e2e97f165117e3e45b8248f4a5078

The initial lines show event records that were not recognized. Since predict only generates predictions for PCRs whose component coverage is complete, those PCRs are excluded from this specific policy. If we wanted to use them, some could have components created by running systemd-pcrlock lock-* commands, while others would need manual component creation.

Lastly, let’s compare the PCR 7 logs used in the fifth post. The only difference is the inclusion of the component field (which “locks” the PCR), highlighted below:

sudo systemd-pcrlock log --json=short 2>/dev/null | jq '[.log[] | select(.pcr == 7)]'

[
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-driver-config",
 "match": true,
 "sha256": "9f75b6823bff6af1024a4e2036719cdd548d3cbc2bf1de8e7ef4d0ed01f94bf9",
 "phase": "F",
 "component": "240-secureboot-policy",
 "description": "Variable: dbx-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 },
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-authority",
 "match": true,
 "sha256": "f35567246a92b2fcdd2901e4ad2febdfd80173f25527c5a73033bf100a8eb980",
 "phase": "F",
 "component": "620-secureboot-authority",
 "description": "Authority: db-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 }
]

Evaluating the LUKS header token

We can also compare the LUKS header, which was updated when we ran systemd-cryptenroll with the --wipe-slot argument and then --tpm2-pcrlock. In the fifth post, the policy wasn’t used, so the tpm-pcrs field (a list) had the value 7, and now it’s empty. The tpm2-pcr-bank field is no longer used, and the tpm2_pcrlock_nv field now has a hash:

sudo cryptsetup luksDump --dump-json-metadata /dev/disk/by-label/NIXLUKS1 | jq -r '.tokens."0"'

{
 "type": "systemd-tpm2",
 "keyslots": ["1"],
 "tpm2-blob": "<a base64 value>",
 "tpm2-pcrs": [],
 "tpm2-policy-hash": "<a hash>",
 "tpm2_pcrlock": true,
 "tpm2_srk": "<another base64 value>",
 "tpm2_pcrlock_nv": "<yet another base64 value>"
}

This last field, ending in _nv, is especially important. It points to a non-volatile area of the TPM, which is not erased when the computer turns off. The pcrlock policy data is stored there, and if the TPM is cleared, it forces the recreation of the policy (more on this below).

Removing the TPM policy

If you ever remove the NixOS TPM measurement settings (boot.lanzaboote.measuredBoot), you will need to remove the policy manually. It is registered in the aforementioned policy file, but also in the TPM’s non-volatile memory. This should be automated by Lanzaboote (I opened an issue), but from what I’ve seen, it isn’t yet. After running nixos-rebuild switch, run:

# remove the policy from the TPM's non-volatile memory and also the files:
# /var/lib/systemd/pcrlock.json and
# /boot/loader/credentials/pcrlock.nixos.cred
sudo systemd-pcrlock remove-policy

Don’t forget to remove the TPM keyslot from the LUKS volume headers:

sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/disk/by-label/NIXLUKS1
sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/disk/by-label/NIXLUKS2

Dealing with a cleared/wiped TPM

If the TPM’s non-volatile memory is wiped, the reference to the TPM policy registered in the LUKS volume header will become outdated, pointing to a record that no longer exists. This will force us to re-enroll the policy into the LUKS header. You can test this safely by clearing the TPM directly from Linux. Run the following commands and reboot:

nix-shell -p tpm2-tools
sudo tpm2 clear
exit

As a result, the operation to decrypt the disk using the TPM during boot will fail, and you will need to decrypt using your password. To re-enable automatic TPM decryption, you first need to remove the policy from the disk (the /var/lib/systemd/pcrlock.json and /boot/loader/credentials/pcrlock.nixos.cred files—explained in the previous section), run nixos-rebuild boot, and reboot to recreate the wiped policy. Then, redo the LUKS header with the systemd-cryptenroll --wipe-slot and systemd-cryptenroll --tpm2-pcrlock commands:

sudo systemd-pcrlock remove-policy
sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/disk/by-label/NIXLUKS1
sudo systemd-cryptenroll --wipe-slot=tpm2 /dev/disk/by-label/NIXLUKS2
sudo nixos-rebuild boot
# reboot, enter LUKS password
jq '.pcrValues.[].pcr' /var/lib/systemd/pcrlock.json # validate that the result is: 4 7
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrlock=/var/lib/systemd/pcrlock.json /dev/disk/by-label/NIXLUKS1
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrlock=/var/lib/systemd/pcrlock.json /dev/disk/by-label/NIXLUKS2

Reboot once more, and you should no longer be prompted for a password.

You’ve already seen these commands in this article, so I won’t detail them further.

Conclusion

With this, your operating system is now protected, and you have the convenience of a system that starts without constantly asking for a decryption password. Better yet, since everything was done using NixOS, the configuration is ready to be reused: if it worked once, it will work forever.

The series was supposed to end here, but since I wrote this post, a few days have passed and I’ve used everything I wrote here to migrate my own machine from Ubuntu to NixOS. I learned a lot and have a few more things to share, so the series will have at least one more post.

If you’ve followed along this far, ran a proof of concept with the examples, or have ideas or criticisms, leave a comment so I know!

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 6 - Mitigating the volume swap attack)

giggio@giggio.net (Giovanni Bassi) — Tue, 26 May 2026 10:00:00 -0300

The NixOS disk is encrypted, but a careful LUKS volume swap attack can still be used to obtain the encryption master key.

In this post, I show how to mitigate it!

This is the sixth post in the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot
Unlocking the disk with TPM
Mitigating the volume swap attack (this post)

As I said in the previous post, this kind of attack would not be carried out by an average person. The computer shop technician who is repairing your laptop probably will not be able to read your LUKS encrypted disk and with the key sealed with the help of PCR 7. But someone who knows what they are doing will find the weakness. This post and the next one are for those who want to be fully protected, both from the technician at the shop around the corner and from a hostile government or corporate agent. By the end of these two posts, the attacks described here will be mitigated, significantly increasing security (keeping in mind that it is always prudent to consider other attack surfaces outside these scenarios).

The problem

The attack was described by Oddlama, and it basically consists of removing the disk from the original computer, creating a fake encrypted partition with the same identification data as the original partition, and then using that to obtain the key. He even describes how to do this against NixOS.

This is possible because the UKI (Unified Kernel Image — the binary loaded by UEFI that contains the kernel and the initrd) is not encrypted — if it were, UEFI would not be able to load it. The LUKS volume header is also not encrypted, since it must be read by the system in initrd so that the LUKS volume can be decrypted. It is possible to inspect what will be loaded during boot and replace the LUKS volume with another one carefully prepared to steal the master key from the original LUKS volume.

I will not go into more detail because the explanation is long. You can read Oddlama’s post; it is quite interesting. The important point is that this attack is only possible because the UKI does not validate the identity of the LUKS volume, which allows it to be replaced.

Closing the breach

To solve the problem, we just need to start validating the decrypted volume before proceeding, something that is not being done yet and will be addressed using PCR 15 (system-identity). In the previous post, I showed how to list the hashes of all PCRs with systemd-analyze pcrs. Notice that PCR 15 was zeroed out, meaning it had not been extended. systemd can start writing to it by simply enabling tpm2-measure-pcr=yes for systemd-cryptsetup during the boot process.

To start writing to PCR 15 in the NixOS way, we need a Nix configuration. Fortunately, Oddlama himself provided the solution, pointing to a Forgejo repository by PatrickDaG, with the file ensure-pcr.nix, which has already been adapted in the repository cloned into /etc/nixos, and which makes it possible to read this PCR through a NixOS module.

I incorporated this module into my solution, which made it very easy to apply. The example commit is f690b88, described as “Enable PCR15”, but we do not need to check it out; it is enough to update the configuration in /etc/nixos/configuration.nix (it is already in the code, just remove the comment):

systemIdentity = {
 enable = true;
};

Then apply it:

nixos-rebuild switch

Restart the virtual machine, and after the reboot, confirm that the value of PCR 15 is present (the value below is just an example — replaced by a sequence from 0 to 9):

$ systemd-analyze pcrs 15
NR NAME SHA256
15 system-identity 0123456789012345678901234567890123456789012345678901234567890123

That is the hash of the system identity (derived from the activated LUKS volume key); it is what will ensure that the unlocked volume is the expected one, reducing the volume swap attack.

The value found must be copied into the pcr15 field in the configuration. For example, using the fictitious sequence above from 0 to 9:

systemIdentity = {
 enable = true;
 pcr15 = "0123456789012345678901234567890123456789012345678901234567890123";
};

Change this value, reboot once more, and everything should continue working.

How this solution prevents volume swapping

The explanation is in the Nix module defined in the file ensure-pcr.nix.

It creates a systemd service that starts extending PCR 15 when systemIdentity.enable is enabled, running:

systemd-cryptsetup attach crypt_disk1 /dev/disk/by-partlabel/NIXLUKS1 - 'tpm2-device=auto,tpm2-measure-pcr=yes,discard';

And when the hash of PCR 15 has been defined in systemIdentity.pcr15, it creates a check-pcrs service that runs in initrd and, if it fails, prevents boot from continuing. This service is very simple: it just compares the hash stored in the configuration with the value found in PCR 15:

if [[ $(systemd-analyze pcrs 15 --json=short | jq -r ".[0].sha256") != "${config.systemIdentity.pcr15}" ]] ; then
 echo "PCR 15 check failed"
 exit 1
else
 echo "PCR 15 check succeed"
fi

As this service is required by sysroot.mount, if check-pcrs fails the root disk cannot be mounted and the entire boot fails, entering emergency mode.

What if the boot fails?

If the value of PCR 15 changes for any reason, the boot will fail and enter emergency mode. In that case, you will need to log in with the emergency password configured in initrd and run:

systemctl disable check-pcrs
systemctl default

Note: see the boot.initrd.systemd.emergencyAccess attribute in configuration.nix, that is what defines the emergency initrd password (using a hash of the password). To create the password as test, run (replace the salt, xyz, and the password):

openssl passwd -6 -salt xyz test

Tip: I recommend that you test this by changing the configuration value to the wrong hash, running switch, and confirming that the boot failed. Then test the commands above: you will need to provide the initrd emergency password, disable the check-pcrs service, and continue the boot. In the worst-case scenario, if you cannot do that, you can choose the previous configuration from the boot menu. After logging in again, set the PCR 15 value in the configuration back to the correct one, run a new switch and reboot, making sure that boot works again without issues.

Is it secure?

Again: not yet.

The attack described by Oddlama no longer works, but there is still another one: since we only bind the disk encryption to PCRs 7 and 15, it is still possible to replace the operating system with another one and use the TPM to decrypt the disk. We will solve that in the next post.

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 5 - unlocking the disk with TPM)

giggio@giggio.net (Giovanni Bassi) — Mon, 18 May 2026 11:00:00 -0300

At last, we are going to automatically decrypt the NixOS disk using the TPM!

This is the fifth post in the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot
Unlocking the disk with TPM (this post)

Up to now, every boot has required the LUKS password to decrypt the disk. But if the machine’s integrity has not been compromised, there is no problem in doing this automatically. But how?

Now it is time to orchestrate everything we have put together so far, connecting LUKS, Secure Boot, and the TPM.

Why this is safe

Assuming the machine has not been compromised, when the operating system comes up, the only safe way to access it is with valid credentials — assuming the system has no exploitable vulnerability. That means logging in through the console, SSH, the graphical interface, or a serial connection. In practice, that means that without a login password there is no access to the computer, and no privilege is gained.

Everything works based on this principle: an uncompromised and intact system protects itself, and if it is compromised (firmware modification, disk removal, etc), encryption protects the data.

Understanding the TPM

The TPM (Trusted Platform Module) is a dedicated processor that stores, in an inviolable way, measurements taken of the hardware and software running on the computer. These measurements are stored in PCRs (Platform Configuration Registers), whose values can be extended, but never set directly. Every value sent to the TPM extends the previous value and produces a new one. If we were to model this as a formula, it would be something like this:

PCR = HASH(PCR || new_measurement)

In other words, the PCR hash is used together with the new measured value to create the new hash.

You can see the hashes of each PCR on your running TPM (fictitious values):

$ systemd-analyze pcrs
NR NAME SHA256
 0 platform-code 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 1 platform-config 123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0
 2 external-code 23456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01
 3 external-config 3456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012
 4 boot-loader-code 456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123
 5 boot-loader-config 56789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234
 6 host-platform 6789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012345
 7 secure-boot-policy 789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456
 8 - 89abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567
 9 kernel-initrd 9abcdef0123456789abcdef0123456789abcdef0123456789abcdef012345678
10 ima abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
11 kernel-boot 0000000000000000000000000000000000000000000000000000000000000000
12 kernel-config 0000000000000000000000000000000000000000000000000000000000000000
13 sysexts 0000000000000000000000000000000000000000000000000000000000000000
14 shim-policy bcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789a
15 system-identity 0000000000000000000000000000000000000000000000000000000000000000
16 debug 0000000000000000000000000000000000000000000000000000000000000000
17 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
18 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
19 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
20 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
21 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
22 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
23 application-support 0000000000000000000000000000000000000000000000000000000000000000

Each PCR is independent and is extended freely, without depending on the others. On compatible TPMs there are 24 PCRs; the UAPI (Linux Userspace API Group) in its specifications considers 0–7 to be firmware and 8–15 to be the range available to the operating system, although the systemd ecosystem also uses specific PCRs for additional measurements, and PCRs 16–23 are also usable.

When the computer powers on, all PCRs start out with no value. The firmware then begins extending the PCRs. For example, PCR 0 depends on the software running in the firmware — what we normally call the BIOS. When you “update the BIOS”, PCR 0 changes. PCR 1 may change if you replace a hardware component. PCR 4 is tied to the operating system; it measures the boot loader and additional drivers. And so on.

PCR 7 depends on the Secure Boot state. Its values are commonly extended using the keys enrolled in Secure Boot, as well as the Secure Boot Authority. It is this PCR that we will use to unlock the disk, at this moment.

I will come back to PCRs in the next posts, but it is important to understand what they are for. If you decide to use what I am proposing in these posts, this knowledge may be useful if you run into trouble.

You can see all the events that led to PCR extensions by running sudo systemd-pcrlock log. Using jq, you can show only the events that led to PCR 7:

sudo /run/current-system/systemd/lib/systemd/systemd-pcrlock log --json=short 2>/dev/null | jq '[.log[] | select(.pcr == 7)]'

The result, simplified so it does not get too long, is this:

[
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-driver-config",
 "match": true,
 "sha256": "9f75b6823bff6af1024a4e2036719cdd548d3cbc2bf1de8e7ef4d0ed01f94bf9",
 "phase": "F",
 "component": null,
 "description": "Variable: dbx-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 },
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-authority",
 "match": true,
 "sha256": "f35567246a92b2fcdd2901e4ad2febdfd80173f25527c5a73033bf100a8eb980",
 "phase": "F",
 "component": null,
 "description": "Authority: db-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 }
]

Note that the hash value, stored in the sha256 field, changes with each event. When the TPM receives a request to decrypt a value, its state must match exactly what was used when the value was encrypted (this is done through TPM policies). That means a value encrypted early in the boot process may no longer be decryptable at the end of the boot process, if the PCR has been extended again. This is especially useful for this very reason: allowing a value to be accessible only at a specific point in the boot sequence, such as during initrd startup (PCR 11 has measurements that make this possible).

Systemd documents how it uses PCRs, and since nowadays there is practically no Linux without systemd, it is worth understanding. This document will be useful later, when we look more closely at PCR 15 (system identity).

Unlocking the disk during boot

Only one command is needed to make everything happen. In our case, since we have two disks and two partitions, we run the command once for each of them (you will need to enter your LUKS password for the process to complete):

sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/disk/by-label/NIXLUKS1
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/disk/by-label/NIXLUKS2

When this command runs, the volume master key is obtained using your password. It is then encrypted (sealed) using the TPM, and this sealed value is stored in the LUKS volume header. In this case, only PCR 7 is being used to seal the value, meaning only the Secure Boot state. That means if the Secure Boot state changes (if it is reset, or if a new key is removed or added), the TPM’s PCR 7 state will also change, and the disk will no longer be decrypted during boot. In this post, the goal is to tie automatic disk decryption to the Secure Boot state, and that is what we have done.

You can see the details stored in the LUKS volume header by running the following command after systemd-cryptenroll has been executed:

sudo cryptsetup luksDump /dev/disk/by-label/NIXLUKS1

Notice the Tokens field, with the first one being systemd-tpm2, with a Keyslot:

Tokens:
 0: systemd-tpm2
 Keyslot: 1

To see more details about the sealed value, run:

sudo cryptsetup luksDump --dump-json-metadata /dev/disk/by-label/NIXLUKS1 | jq -r '.tokens."0"'

The result will look something like this:

{
 "type": "systemd-tpm2",
 "keyslots": ["1"],
 "tpm2-blob": "<a base64 value>",
 "tpm2-pcrs": [7],
 "tpm2-pcr-bank": "sha256",
 "tpm2-policy-hash": "<a hash>",
 "tpm2_srk": "<another base64 value>",
}

The tpm2-blob contains the value encrypted by the TPM (plus metadata). Using the tools from the tpm2-tools package and root access, you could recover the master password from this value. That is not a security problem: the system is already running and the disk is already decrypted. The purpose of TPM protection is not to protect a healthy running system from its administrator, but to protect against integrity violations that happen before, during, and after boot.

With just these two commands, the TPM will start unlocking both LUKS volumes. Reboot to confirm that it no longer asks for the password. If it does, inspect the boot logs with sudo journalctl --boot.

Is it secure?

Not yet.

There are two vulnerabilities, and I will address them in the next posts. Neither is trivial, but someone who understands how all of this works could gain access to the data in a short amount of time. None of the work done so far will be lost; we will build on the current solution. The good news is that both issues are easy to fix.

That said, it is fair assume that most people, including technicians who are not systems penetration experts, would no longer be able to read the disk of a computer encrypted this way. In other words, sending a laptop for repair with this configuration would probably not present a risk. But that is still not good enough.

In the next post we will start closing the gaps.

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 4 - Secure Boot)

giggio@giggio.net (Giovanni Bassi) — Thu, 14 May 2026 11:00:00 -0300

In the fourth post of our series, we are going to configure Secure Boot to ensure that only trusted operating systems can be executed.

This is the fourth post of the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot (this post)

Secure Boot is a fundamental component for tightening the security, especially when using the TPM to automatically decrypt the disk. I will explain what it is, what it’s for, and how to implement it in NixOS using Lanzaboote.

Understanding Secure Boot

Secure Boot is a protocol that is part of the UEFI (Unified Extensible Firmware Interface). When enabled, it verifies if the operating system’s bootloader has a valid digital signature recognized by the keys registered in the motherboard’s firmware.

This prevents boot-level malware (rootkits) or unauthorized operating systems from loading. Additionally, the TPM uses the Secure Boot state as one of the metrics to decide whether or not to release the disk encryption keys.

There are three main ways to manage Secure Boot keys:

Factory default keys: Usually the Microsoft keys that come with almost every computer;
Custom keys (User Mode): You remove the Microsoft keys and install only your own;
Hybrid Mode: You keep the Microsoft keys (for dual-booting with Windows) and add your own.

If you don’t intend to run Windows, the second option is the most restrictive and secure. If you need dual boot, the third is mandatory. It’s worth noting that NixOS does not have a bootloader signed by Microsoft (unlike Ubuntu or Fedora), so we always need to generate our own keys.

And why Microsoft keys, specifically? Because they were the first company to push Secure Boot as mandatory, and they hold the largest share of the PC market. There is quite a bit of controversy regarding this.

The important thing for our setup is knowing that once you define how Secure Boot will be used, it cannot be changed without breaking the automatic decryption process (which will be done with the help of the TPM). In our case, we will use the third option (mixing Microsoft keys with our own). If Secure Boot is turned off on the machine or a new platform key is loaded, the TPM will refuse to decrypt the disk. I’ll explain this in future posts, so for now, what matters is enabling Secure Boot.

Putting the Firmware into Setup Mode

In the first post, we cleared the keys in the VM’s boot menu to enter Setup Mode. This is essential: for us to write our keys via software, the firmware must be “open” to new signatures.

Confirm the status by running:

$ sudo bootctl status
...
Secure Boot: disabled (setup)
...

If disabled (setup) appears, we are ready to proceed.

Generating Keys with sbctl

We will use sbctl to create and register our keys. Since it isn’t installed by default, let’s use nix-shell:

nix-shell -p sbctl

Note: In NixOS, you can bring any application into your terminal’s context using nix-shell. With this, the sbctl command becomes available in a subshell — to exit, just run exit.

To generate the keys, we will run the create-keys subcommand:

sudo sbctl create-keys

The keys will be generated in /var/lib/sbctl/. You can see the structure with the tree command:

$ tree /var/lib/sbctl/
/var/lib/sbctl/
├── GUID
└── keys
 ├── db
 │   ├── db.key
 │   └── db.pem
 ├── KEK
 │   ├── KEK.key
 │   └── KEK.pem
 └── PK
 ├── PK.key
 └── PK.pem

Install the keys into the machine’s firmware with enroll-keys. This will use the keys we created earlier with sbctl. With the --microsoft argument, Microsoft’s platform keys will also be installed:

sudo sbctl enroll-keys --microsoft

Verify that Secure Boot has been re-enabled with:

sudo bootctl status

It should show Secure Boot: enabled (user). It might not show as enabled yet until the next boot, showing up as Secure Boot: disabled, but without setup. But don’t reboot just yet!

Signing the Boot with Lanzaboote

At this point, if you restart the machine, NixOS will no longer boot, as the NixOS bootloader is not yet signed with the Secure Boot keys we created in the previous step. That’s where Lanzaboote comes in. It automates the signing of NixOS generations. It replaces the default systemd-boot manager with one that handles the keys generated by sbctl. Once enabled, whenever a new bootloader is created in the /boot directory, it will be signed with the keys located in /var/lib/sbctl.

To enable Lanzaboote and then sign the files, first go to the configuration directory that was copied in previous posts to /etc/nixos, and check out the correct commit. Be careful not to forget the git checkout, or it won’t work:

cd /etc/nixos
# ensuring the current user owns the files:
sudo chown -R giggio:users .
# checkout with the message "Enable lanzaboote":
git checkout dab0fd4

The change in your configuration.nix disables the native systemd-boot and activates lanzaboote, pointing to the keys directory:

 boot.loader.systemd-boot.enable = false;
 boot.lanzaboote = {
 enable = true;
 pkiBundle = "/var/lib/sbctl";
 };

The Lanzaboote configuration was already present; it was just disabled. And with it enabled, systemd-boot can be disabled. Note also that the keys directory, defined in the pkiBundle attribute, is already correctly pointed to /var/lib/sbctl.

That’s all; now just install the new configurations, which take effect immediately and will also be effective on the next boot:

sudo nixos-rebuild switch

Validating the Signature

To ensure Lanzaboote did its job and signed the .efi binaries, run:

$ sudo sbctl verify
Verifying file database and EFI images in /boot...
✓ /boot/EFI/BOOT/BOOTX64.EFI is signed
✓ /boot/EFI/Linux/nixos-generation-1-xxx.efi is signed
✓ /boot/EFI/Linux/nixos-generation-2-yyy.efi is signed
✗ /boot/EFI/nixos/kernel-7.0-zzz.efi is not signed
✓ /boot/EFI/systemd/systemd-bootx64.efi is signed

Note about the Kernel: It is normal to see an ✗ on the isolated kernel file. What matters are the files inside /boot/EFI/ and the boot managers. Lanzaboote creates a Unified Kernel Image (UKI), which bundles the kernel and the initrd into a single signed executable that the UEFI can run directly.

Now you can reboot. If everything went well, the system will come up normally and bootctl status will confirm: Secure Boot: enabled (user).

The machine still asks for the password to decrypt the disk. This is expected, as we haven’t yet implemented the structure for automatic decryption with the TPM.

Troubleshooting Secure Boot

If something goes wrong and the VM won’t start, you can reset the NVRAM (the VM’s “BIOS”). On your host, turn off the VM and run:

# on the host:
virsh start <vm_name> --reset-nvram

This will start the virtual machine normally, but with all the firmware boot settings lost, including Secure Boot settings.

The following commands will re-apply the boot settings to the firmware’s non-volatile memory and the disk:

# on the vm:

# registering platform keys in the firmware again:
sudo sbctl enroll-keys --microsoft
# installing the boot menu option:
sudo bootctl install
# re-signing the UKIs:
sudo nixos-rebuild switch

Why run switch again: When running bootctl install, the files /boot/EFI/systemd/systemd-bootx64.efi and /boot/EFI/BOOT/BOOTX64.EFI will not be signed, so it is necessary to run switch so that these two files become signed again.

Declarative Approach

Lanzaboote allows generating platform keys automatically via Nix config:

boot.lanzaboote = {
 autoGenerateKeys.enable = true;
 autoEnrollKeys = {
 enable = true;
 autoReboot = true;
 };
};

This is described in more detail in the docs on automatic provisioning.

While practical for testing, I don’t recommend using this in production systems. The ideal approach is to generate keys manually (as I demonstrated here) and store them securely somewhere. A good option is to use sops-nix, keeping the keys encrypted within the repository itself. The inconvenience would be during application, where you would always need the keys or devices to decrypt the sops secrets at every nixos-rebuild.

Next Up: Using TPM to Decrypt the Disk

Secure Boot is active. The disk is encrypted. But we still have to type the LUKS password at every boot.

If someone tries to start another operating system, it will need to be signed with your platform key or Microsoft’s. You can make the system more secure by removing the --microsoft option from the enroll-keys command and not allowing any other operating system.

In the next post, we will configure the TPM (Trusted Platform Module) so that it “measures” the Secure Boot state and releases the encryption key automatically if the system hasn’t been tampered with. Maximum security with convenience.

See you then!

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 3 - Installing the OS)

giggio@giggio.net (Giovanni Bassi) — Mon, 11 May 2026 11:00:00 -0300

I’m continuing my journey of setting up a NixOS machine with secure and redundant storage. In this post, we’re going to perform the actual OS installation!

This is the third post in the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing NixOS (this post)

At this point, we have a virtual machine with formatted disks and the file system configured and mounted, ready to receive the NixOS binaries.

Why aren’t we using disko-install?

The Disko project includes a tool called disko-install that allows you to format partitions and install NixOS in a single step. The tool is excellent and even allows for disk parameterization via the command line.

However, a bug prevents its use when the machine’s RAM is smaller than the size of the system being created. Until this is resolved, we will follow the process in two stages: disk preparation (previous post) and the manual installation of the operating system (this post).

But… if that bug is ever fixed, the command would look like this:

sudo nix --experimental-features "nix-command flakes" run 'github:nix-community/disko/latest#disko-install' -- \
 --flake ~/nixos#nixos3 --disk disk1 /dev/vda --disk disk2 /dev/vdb

Installing the operating system

We are starting from the final state of the previous post, with the system mounted at /mnt. If you restarted the virtual machine, just run the following command to mount them again without needing to reformat everything:

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- \
 --mode mount ~/nixos/disko.nix

With everything mounted, we start the NixOS installation by pointing to our flake:

sudo nixos-install --root /mnt --no-root-passwd --flake ~/nixos#nixos3

This command will take a few minutes. NixOS will download and build the entire system from scratch within the /mnt directory.

Configuration Persistence

To manage your system in the future (using nixos-rebuild), we need to move our configuration files into the new system by copying the repository to your /etc/nixos directory, which is mounted at /mnt/etc/nixos:

sudo cp -R ~/nixos /mnt/etc/nixos

Setting the User Password

Although I left a default password in the settings (luks) to make the lab easier, let’s define the password manually. We will use nixos-enter, which creates a chroot environment in the new system:

sudo nixos-enter --root /mnt -c "passwd giggio"

Note: nixos-enter is extremely useful for maintenance. It allows you to “enter” the installed system even before the first boot to fix configurations or reset passwords.

NixOS is installed! At this stage, we have partitioned and encrypted disks with a password entered during boot, the btrfs file system is formatted, and the operating system is installed. Everything should work; shut down the VM, remove the ISO from your settings, and start the VM again.

First Access and SSH

After booting, log in with the user giggio and the password defined via passwd in the previous step.

To access via SSH from your host machine, remember to clear the old key (from the installation environment) from your known_hosts file (created during the first access to the VM):

ssh-keygen -R <ip>

Now, connect with the new user:

ssh giggio@<ip>

What do we have so far?

If you’ve never used NixOS, now is the time to experiment. In practice, it’s a modern Linux with GNOME. You’ll see that it runs with GNOME 49 (with 50 about to be integrated into nixpkgs), and it’s on the latest Kernel version - currently version 7.0.0.

The system already features RAID 1 via btrfs and LUKS encryption. However, you’ll notice that it still asks for the encryption password manually at every boot.

In the next post, we’ll dive deep into Secure Boot, so I’ll stop here to keep the next one from getting too long. It’s coming soon! See you then!

NixOS: Installation Guide with RAID 1, encryption, and TPM unlock (part 2 - Disko, LUKS, and btrfs)

giggio@giggio.net (Giovanni Bassi) — Wed, 06 May 2026 11:00:00 -0300

In this post I keep on building a NixOS setup with secure storage, now going deeper into Disko, LUKS, and btrfs.

This is the second post in the series. Read the first one.

In the previous post I showed how to create the virtual machine and partition the disks using Disko. The main command was:

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- \
 --mode destroy,format,mount ~/nixos/disko.nix

Although the file disko.nix is part of a flake (a versioned Nix configuration), in this case I ran only the file on its own with nix run.

It is also possible to run only the mount step, after the disk has already been partitioned and formatted, with --mode mount.

What Disko is

Disko is a project that brings Nix a declarative way to partition and format disks. In Nix, everything is done declaratively, except disk partitioning and formatting. Disko solves that. Partitioning and formatting disks is done only at the start of an installation, and that is exactly where the project is useful.

In addition, Disko provides a NixOS module that lets you use what was declared to define NixOS file systems, which are normally declared in the file hardware-configuration.nix. I will talk more about that at the end.

Disko can also be used in the installation process imperatively, through the command line. That is what I did when installing my servers.

Configuring the disk and its first partition

I am working with two disks. The second disk is where all the file system declarations live, so I will focus on it. The first disk ends up being a bit simpler, since it will be mirrored from the first one (I will talk about that below, in the RAID section).

At the beginning I declare the disk, the device I am referring to (/dev/vdb — that is, the second virtual disk), and the first partition, which will be the EFI system partition, or ESP (EFI System Partition):

{
 disko.devices = {
 disk = {
 # disk1 omitted
 disk2 = {
 type = "disk";
 device = "/dev/vdb";
 content = {
 type = "gpt";
 partitions = {
 ESP = {
 size = "1G";
 type = "EF00";
 label = "EFI2";
 content = {
 type = "filesystem";
 extraArgs = [ "-n" "EFI2" ];
 format = "vfat";
 mountpoint = "/boot";
 mountOptions = [ "umask=0077" ];
 };
 };
 # crypt_disk2 partition omitted
 };
 };
 };
 };
 };
}

Note that the mount options are included, and are used both by Disko’s mount command and by the Disko module when defining file systems.

In this case, an ESP partition needs to have type EF00 and be formatted as vfat. I also set the label of the partition to EFI2, and the file system label to the same value (with -n EFI, an argument passed to mkfs.vfat).

This part will generate something roughly like these commands:

parted /dev/vdb mklabel gpt
parted /dev/vdb mkpart primary 1MiB 1025MiB
parted /dev/vdb set 1 esp on
mkfs.fat -F 32 -n EFI2 /dev/vdb1
# and, for mount:
mount /dev/disk/by-label/EFI2 /boot

Second partition: LUKS + btrfs

Next, I need to create the Linux partition, which I want to be encrypted. The encryption will be handled by LUKS, so the type is defined as luks (in the ESP it was defined as filesystem). That means the command used to set up the partition will be cryptsetup luksFormat, and it is what receives the partition label parameter --label NIXLUKS2:

{
 disko.devices = {
 disk = {
 disk2 = {
 content = {
 partitions = {
 # ESP partition omitted
 crypt_disk2 = {
 size = "100%";
 label = "NIXLUKS2";
 content = {
 type = "luks";
 name = "crypt_disk2";
 extraFormatArgs = [ "--label" "NIXLUKS2" ];
 passwordFile = "${./luks-password.txt}";
 settings = { allowDiscards = true; };
 content = { }; # btrfs details omitted
 }; # other curly braces omitted

On a real NixOS system the password coming from the luks-password.txt file would be encrypted. I usually use sops-nix for that.

That previous part will generate something roughly like these commands:

parted /dev/vdb mkpart primary 1025MiB 100%
cryptsetup --label=NIXLUKS2 luksFormat --type luks2 /dev/vdb2
# and, for mount:
cryptsetup open /dev/vdb2 crypt_disk2

Note: The password is entered interactively in the commands above.

Then, in the content part, we define what goes inside the LUKS encrypted volume, in this case, a btrfs file system.

# beginning omitted
partitions = {
 # ESP partition omitted
 crypt_disk2 = {
 content = {
 # LUKS details omitted
 content = {
 type = "btrfs";
 extraArgs = [ "--label" "NIXOS" "-d" "raid1" "-m" "raid1" "/dev/mapper/crypt_disk1" ];
 subvolumes = {
 "/@" = { mountpoint = "/"; };
 "/@home" = { mountpoint = "/home"; };
 "/@root" = { mountpoint = "/root"; };
 "/@nix" = { mountpoint = "/nix"; };
 };
 };
 };
 };
};

This part will generate something roughly like these commands:

cryptsetup open /dev/vdb2 crypt_disk2
mkfs.btrfs --label NIXOS -d raid1 -m raid1 /dev/mapper/crypt_disk1 /dev/mapper/crypt_disk2
mkdir -p /mnt
mount /dev/mapper/crypt_disk2 /mnt
btrfs subvolume create /mnt/@
btrfs subvolume create /mnt/@home
btrfs subvolume create /mnt/@root
btrfs subvolume create /mnt/@nix
umount /mnt
# and, for mount:
mount -o subvol=@ /dev/mapper/crypt_disk2 /
mkdir /mnt/{home,nix,root,boot}
mount -o subvol=@home /dev/mapper/crypt_disk2 /home
mount -o subvol=@nix /dev/mapper/crypt_disk2 /nix
mount -o subvol=@root /dev/mapper/crypt_disk2 /root

At the end of the operation, Disko will mount btrfs at /mnt. You can verify everything by running:

# list the partitions and file systems
lsblk -f
# list the btrfs subvolumes
sudo btrfs subvolume list /mnt

RAID 1 on btrfs

Notice that I passed the parameters -d raid1 -m raid1 /dev/mapper/crypt_disk1, which means btrfs will be running in RAID 1 for both metadata and data, and in parity with the first disk, which has also already been configured for encryption with LUKS. The reason for defining everything on the second disk is because Disko operates in the order defined, so when disk 1 is being prepared disk 2 still has not been partitioned.

In RAID 1, everything written to one disk is immediately copied (mirrored) to the other disks. In this case, we have a RAID 1 with two disks, controlled directly by the btrfs file system. With Linux, it is very common to do this with mdadm, but in this case mdadm is unnecessary because btrfs has native RAID support.

You can check the RAID status by running:

btrfs device stats /mnt

Subvolumes on btrfs

I defined several btrfs subvolumes. They are useful because they let us manage them independently. For example, we can save everything written to a volume using snapshots, as well as define several settings that on other file systems are available only for partitions, such as quotas, for example. They can also be nested, inheriting the settings and actions performed within the hierarchy.

Subvolumes can also be mounted wherever we want, and that is exactly what we did, for example by mounting /home from the @home volume.

On an already prepared system, this is the list of subvolumes:

$ sudo btrfs subvolume list /
ID 256 gen 1103 top level 5 path @
ID 257 gen 923 top level 5 path @home
ID 258 gen 923 top level 5 path @nix
ID 259 gen 695 top level 5 path @root
ID 260 gen 19 top level 256 path srv
ID 261 gen 19 top level 256 path var/lib/portables
ID 262 gen 19 top level 256 path var/lib/machines
ID 263 gen 1080 top level 256 path tmp
ID 264 gen 1080 top level 256 path var/tmp

The root volume is always 5, which is why the four subvolumes created point to it as the parent subvolume.

It is still possible to create subvolumes with btrfs subvolume create and make snapshots with btrfs subvolume snapshot.

Using Disko as a module

As I mentioned at the start of the post, Disko lets you use it as a module that declares file systems, without needing to declare them in the hardware-configuration.nix file.

To use it, just add disko.nixosModules.disko to the system modules, along with your Disko configuration file, which in this example is disko.nix, the same one that was used on its own to create the file system. It looks like this:

{
 inputs = {
 nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 disko = {
 url = "github:nix-community/disko/latest";
 inputs.nixpkgs.follows = "nixpkgs";
 };
 };
 outputs =
 { self, nixpkgs, disko, ... }@inputs:
 {
 nixosConfigurations = {
 nixos = nixpkgs.lib.nixosSystem {
 system = "x86_64-linux";
 modules = [
 ./configuration.nix
 ./disko.nix
 disko.nixosModules.disko
 ];
 };
 };
 };
}

Note that my hardware-configuration.nix file does not declare any file systems. See NixOS docs about file systems for how this is normally declared, and, because I used Disko, I did not need to do it.

If I had to do it manually, it would be more or less like this:

{
 fileSystems = {
 "/" = {
 device = "/dev/mapper/crypt_disk1";
 fsType = "btrfs";
 options = [ "subvol=@" ];
 };
 "/home" = {
 device = "/dev/mapper/crypt_disk1";
 fsType = "btrfs";
 options = [ "subvol=@home" ];
 };
 "/nix" = {
 device = "/dev/mapper/crypt_disk1";
 fsType = "btrfs";
 options = [ "subvol=@nix" ];
 };
 "/root" = {
 device = "/dev/mapper/crypt_disk1";
 fsType = "btrfs";
 options = [ "subvol=@root" ];
 };
 "/boot" = {
 device = "/dev/disk/by-label/EFI1";
 fsType = "vfat";
 options = [ "fmask=0022" "dmask=0022" ];
 };
 };
}

And that only after manually partitioning the main disks with LUKS and formatting them with btrfs.

It becomes obvious how much Disko simplifies the whole process: we use its definitions to configure the disks during installation, and later to bring up the operating system itself.

Conclusion

With a disk and file system declaration that is later used to configure it, it is possible to prepare all the storage for a future Linux operating system using just one command line.

Instead of having to keep commands in documentation or build a shell script to prepare everything, we have it all versioned in executable files.

In the next post I will show how to finally install NixOS on the file system that was mounted. In the following ones I will demonstrate how to use TPM to obtain an encryption key that will be used to unlock LUKS without human interaction, directly at boot.

NixOS: Installation Guide with RAID 1, encryption, and TPM unlock (part 1)

giggio@giggio.net (Giovanni Bassi) — Tue, 28 Apr 2026 16:34:00 -0300

It is time to migrate from Ubuntu to NixOS!

For a long time, I have been using Nix on Ubuntu through Home Manager, and I have been automating my dotfiles more and more, steadily removing my custom setup and using Nix instead. Recently, I adopted the new System Manager project, whose goal is to bring system-level configuration to operating systems other than NixOS, where it was previously only available.

After quite a while on that journey, and after already migrating my home servers, it is time to move to NixOS and leave Ubuntu behind.

I want to live on the edge of what is new and configure my Linux exactly the way I want, and NixOS will let me do that. I have also come to really like the way it keeps configuration in versioned file systems that I can control in detail.

This post will show how to meet what I consider the bare minimum for security: I am going to create a NixOS system with an encrypted disk, mirrored with RAID 1, using the most modern file system available right now (btrfs), and use the TPM to decrypt the system without human interaction.

Already know NixOS, TPM, btrfs, and the rest, and just want the code? It is free and available in a repository on my Codeberg. The README explains what is going on, but I will go into more detail here on the blog, explaining the concepts in more depth. This will be a series of posts, where I intend to explain each piece.

The plan is to do something like this:

Creating the VM and the initial partitions (this post)
More information about Disko, LUKS and btrfs
Installing NixOS
Preparing Secure Boot
Using the TPM to decrypt the disks
Mitigating the volume-swapping attack
Mitigating the OS-swapping attack
Review and conclusions

I am sure the plan will fall apart, but it gives you an idea of what I intend to cover.

In this first part, we will prepare the VM and the initial partitions.

Preparing the virtual machine

I am on Ubuntu 24, using Virtual Machine Manager 5.1, installed through NixOS. Adapt this to your own OS setup.

Download the NixOS ISO. I used the graphical ISO, but I imagine the minimal image should work just fine too.

I chose to create the disks ahead of time with qemu-img, because it creates disks that do not consume all the reserved space right away; they grow as needed (sparse files). I noticed that when creating the disks through the VMM UI, it creates them with the full size by default, unless you go through the custom storage option, where there is a checkbox for “Allocate entire volume now”. In any case, I prefer the command line, so I will leave it here for reference. In my case, I will keep the VM files under /mnt/data/vms/vmm, so adapt that to whatever directory you prefer.

cd /mnt/data/vms/vmm
qemu-img create -f qcow2 nixos1-1.qcow2 200G
qemu-img create -f qcow2 nixos1-2.qcow2 200G

Copy the downloaded .iso into that same directory.

Create the virtual machine with those two disks and with the NixOS ISO. Configure the TPM for version 2. Enable the boot menu. Configure the network as NAT. If you want to see my configuration, it is available in nixos.xml.

Delete all Secure Boot keys and disable Secure Boot in the VM, because the installer does not have a signed .efi file and will not boot with Secure Boot enabled.

To do that: when the VM starts, press ESC to enter the boot menu. Then choose “Device Manager” and “Secure Boot Configuration”. Select “Reset Secure Boot Keys” and confirm. That will disable Secure Boot as well. Go back to the main menu and choose “Reset”, which will restart the boot process. It is possible that during this process it will eject the virtual installation CD (.iso); add it back in the VM settings and restart it.

Starting the installation

Choose one of the installation options. I went with Gnome and the latest Kernel, but I imagine it will make little difference; all we need is a shell. When the installer opens, close it and open a terminal.

From that point on, you can continue from that terminal.

Tip: I preferred to connect via SSH, since that makes it easier to copy and paste commands into the terminal. To do that, create a password with passwd. Find the VM IP with ip a and connect to it from the host with ssh nixos@<ip>.

Declarative partitioning with Disko

First, check the current partition status with lsblk -f.

I am using Disko to create the partitions and file systems.

Clone the repository into ~/nixos: https://codeberg.org/giggio/nixos_raid_btrfs_luks_tpm

git clone https://codeberg.org/giggio/nixos_raid_btrfs_luks_tpm.git ~/nixos
cd ~/nixos
git checkout 397fb28 # checkout the commit with message "Updated config"
# create the partitions
sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount ~/nixos/disko.nix
# check the results
lsblk -f
sudo fdisk -l /dev/vd{a,b}
# or
sudo parted /dev/vda print all

See the file used by Disko: disko.nix. Note that the password is luks, and it comes from the file luks-password.txt.

In the next post, I will explain in more detail what Disko did. For now, I can say that it already created two partitions on each disk: one partition for EFI (ESP) and another for Linux, which will be encrypted using LUKS, and will internally use btrfs, with subvolumes already created. I will explain all of that later.

For now, enjoy figuring out how Disko managed to do all that with just one file. That is the beauty of NixOS: no endless command typing in the terminal, everything is versioned and declarative.

See you in the next post.

MVP: End of a Cycle, Beginning of Another

giggio@giggio.net (Giovanni Bassi) — Thu, 10 Jul 2025 21:01:36 -0300

In April 2009, 16 years ago, I received the Microsoft MVP award for the first time, and I renewed it every year. Until today.

I’m leaving the program with a good feeling. I joined amazing communities, met so many great people, and the MVP program opened countless doors for me. It was fantastic for my career, and I still say that this and similar programs are invaluable for anyone who, like me, enjoys contributing to the various software communities in Brazil and around the world. I have lots of friends who are MVPs, GDEs, GitHub Stars, Java Champions, etc.—truly wonderful people whom I’ve been privileged to know. Some became so close that we founded a successful company together, where we’ve helped train many people who also went on to win the award. At one point, we were one of the companies with the highest number of awarded professionals globally—with ten awardees!

The program renews every 12 months, in July, and lately my desire to participate by speaking, writing articles, and producing Microsoft‑related content has all but vanished. That was reflected in how little content I produced in that period, which, if not zero, was pretty close to it. My decision to step away from the program is justified, and I saw it coming.

I thought I’d feel upset when it happened. When the farewell email arrived, I analyzed my feelings, and now—ten hours later—I’m still at peace. I see this as the end of a cycle. It was time.

I won’t lose the connections I’ve made along the way—those remain, and that makes me happy. And I’ve been making many other connections outside the Microsoft community for years, and I’m very happy about that too.

At the same time, it’s the start of a new cycle. Actually, it confirms a cycle that began some years ago. I’ve been contributing more and more to technologies completely unrelated to Microsoft, like Rust, Linux, and all sorts of infrastructure and DevOps tools I know. Also, since I’m on sabbatical, my demand for C# is very low, and I’ve had more opportunities to explore other areas. C# remains one of my favorite languages—it just keeps getting better—but I know it inside and out, and anyone who knows me knows I love learning constantly. So, for now, my main focus is Rust.

Communities have changed a lot too. Nowadays, we meet mostly online, many events are virtual, and much of the interaction isn’t face‑to‑face anymore—which I do miss sometimes. One of my earliest community involvements—a study group called .NET Architects—started in person but quickly gained a strong online presence through an (almost) still‑alive email group that’s still available for anyone who wants to read our old conversations. Our in‑person meetups were important and took place in several Brazilian cities.

The MVP program itself has changed dramatically. When I joined, one of the biggest perks was access to confidential info about upcoming products. For example, I learned about the .NET Core project in 2014, long before it went public, and I was able to use that intel strategically in the businesses I was involved in. Even though I couldn’t share details, that knowledge was crucial for making major decisions that I took—and helped my business partners take. Nowadays, most of Microsoft’s software development is open source, and planning happens openly, with meetings and minutes posted on GitHub. It’s wonderful to see open source win, but conversely that perk was watered down. There were also cases of people breaking NDAs and leaking confidential info, which led some teams to share less than they’d planned. A pity.

When I joined, the program still offered a $100 voucher to buy anything in the MVP store, shipped to Brazil tax‑free. I got one and gifted a bunch of stuff—it was really cool. That benefit ended in 2010, so I only got it once.

Another huge benefit was the annual event at Microsoft headquarters—the MVP Summit in Redmond—where I had the chance to meet and spend a few days with the people working day in and day out on the products I used. It was incredible to meet some of the top designers of languages, frameworks, tools, and operating systems in the world, and even challenge them a bit. How many times did I ask the C# team to add more metaprogramming features, like macros? Many—pretty much every year. I even made a public request for the main DevOps tool (now Azure DevOps) to support Git, which caused quite a stir and put me in a tricky spot with some Microsoft internal teams. At that event, I met the team working on WSL (Windows Subsystem for Linux) and spent an hour in the hallway listening to the engineering lead talk about their technical and political challenges—a Linux guy inside Microsoft!

During the pandemic, the event became fully online, and with its return it adopted a hybrid model—but they cut the free lodging; before, we only had to cover transport costs. That reduced participation—dozens of Brazilians used to go; in recent years, fewer than ten. I haven’t gone. The event overall seems to have shrunk, and many prefer to stay online. Another pity.

The recognition the award brings, however, remains strong. But after nearly 30 years of experience, and more than half that time as a continuous awardee, I already have plenty of recognition. I think it’s good to contribute now without that affiliation, and at the same time free up space for the newer folks coming up.

Thanks to everyone who was close on this journey—you know who you are. And I’m not disappearing from tech communities. Nothing changes in that regard. Only now I’ll be Giovanni, not “MVP.”

Some photos from MVP Summits over the years:

Data Centers and Digital Sovereignty

giggio@giggio.net (Giovanni Bassi) — Wed, 02 Jul 2025 15:00:00 -0300

The Brazilian government, in May 2025, was in the USA to meet with big techs and discuss investments in data centers in Brazil. I will argue why the proposals presented by the government are bad for the Brazilian people and for the national economy, as well as point to a possible alternative path for an initiative of this kind.

Federal government proposals

The federal government’s project can be summarized in five main points:

Exemptions from IPI, PIS/Cofins, and Import taxes for 5 years

Named Redata, the program provides exemptions from IPI, PIS/Cofins, and import tax on equipment for five years. According to estimates from the Ministry of Finance, the framework can boost up to R$ 2 trillion in investments over the next decade. ¹
No study presented

The departments limited themselves to saying that “the national data center policy is being developed, still in study phase, by the federal government based on the joint work of various sectors and ministries” and that “technical meetings are being held with all involved sectors and there is no conclusion at the moment.” ²
Expectation of R$ 2 trillion investment in 10 years

The department led by Haddad has repeatedly stated that this new policy can unlock about R$ 2 trillion in investments over the next ten years. ²
Transfers of gross revenue

As anticipated counterparts in the policy, the government plans to require data center companies to transfer 2% to 8% of their gross revenue to the National Fund for Industrial and Technological Development (FNDIT). The fund aims to foster domestic technological development. ²
10% capacity reserved for the domestic market

Another counterpart would be the requirement that 10% of the data centers’ processing capacity be reserved for the domestic market. The intention is to prevent foreign companies from coming to Brazil only to take advantage of the benefits while continuing to serve international demand. But, according to experts, verifying whether this requirement is being met is technically difficult. ²

Official sources:

Haddad details Data Center Policy at conference in the USA (Agência gov) ³
Haddad presents sustainable growth plan and announces Data Center Policy at conference in the USA (Ministry of Finance) ⁴

At first glance, the initiative sounds great: trillions of reais in investments in a cutting-edge industry. But the proposal inflates the numbers — far from business reality and Brazil’s actual needs — and ignores the fact that, if implemented as-is, it would result in yet another case of capital outflow, exploiting our natural resources and labor, with no real compensation in return.

Unrealistic promises

R$ 2 trillion investment

The figure of R$ 2 trillion over ten years (roughly US$ 350 billion), or R$ 200 billion per year (US$ 35 billion), is unrealistic. Here’s why:

A modern data center costs between US$ 500 million and US$ 1.5 billion. I’ll use the average of US$ 1 billion in this article for cost and output estimates.
Combined, the three largest cloud providers operate over 500 data centers (117 AWS, 300 Azure, 127 GCP), and Brazil has 163 (MDIC ⁵).
To reach R$ 2 trillion, Brazil would need 350 new data centers in ten years — a 64% increase over the global infrastructure of the top three clouds, and 214% more than the number of data centers currently in Brazil.
If we considered smaller data centers at US$ 100 million each, we’d need 3,500 of them.

If such an investment were to happen, the project’s assumptions wouldn’t hold: sustainability, allocating part of the processing power to Brazil, job creation, and so on. I’ll dig deeper into these and other aspects of the project, showing that the numbers are unachievable, and that even if we got close, the result would be dysfunctional — in some cases going in the opposite direction of what the project claims to want. I’ll work with 50% of the proposed figure — 175 data centers in ten years — an optimistic scenario, but already strategically unfeasible based on the arguments that follow. Even far below the proposed value, the negative impact would already be substantial.

Job creation

The government hasn’t shared job creation estimates, but the Secretary of the Ministry of Development, Industry, Commerce, and Services said that “on average, each data center creates 166 direct jobs,” according to Neofeed ⁵.

They already know the impact on this front is small. And it’s true: modern data centers require modest staffing. They are industrially operated, need little constant intervention, and a large part of operations can be done remotely.

This is confirmed by countries more advanced than Brazil in this area:

In the United States, for example, employment numbers have shown that data centers don’t generate as many jobs as expected. While a larger workforce is needed to build these structures, the number shrinks when it comes to the operation of data centers. In Abilene, Texas, around 1,500 people are building Stargate’s first data center. But after it is completed, only 100 full-time employees will work at the facility, according to a Wall Street Journal report from February. ⁶

So maybe Brazilians will participate in the technological development of these data centers, right? Not really. That investment is globalized, managed by teams built up over the past decades. We might get some peripheral demand, but nothing central to the operation.

A large data center might generate up to 300 direct jobs — an optimistic figure — which I’ll use in the estimates below. I’ll disregard indirect jobs, such as in R&D, for reasons already discussed in the previous paragraph.

Even if 175 data centers were built (they won’t be), assuming twice the number estimated by the MDIC (300 jobs per data center), only 53,000 direct jobs would be created. With around 110 million economically active people in Brazil (PEA - Dec/24) ⁷, that represents a measly 0.05% growth in the current workforce. Unemployment in Brazil is currently low (historically speaking), but even if it were high, the impact would be negligible.

It’s important to remember that it’s demand — not companies — that creates jobs. The demand for data center labor already exists, as the world needs more of them, but under the current project, even if the center is built in Brazil, that demand will remain concentrated abroad and highly mechanized (even there). For the demand to appear in Brazil, we’d need to develop and run the high-tech needs of these data centers ourselves. I’ll expand on this in the alternative proposals at the end, but it’s important to remember that not all job demand is necessarily good. If we started a project to cut down the entire Amazon, we’d employ thousands of people — but that’s not work that benefits the Brazilian people. It’s not about generating demand, but about what kind of demand we want to encourage.

Technology transfer

We shouldn’t expect access to cutting-edge technologies, which are closely guarded secrets by data center operators. These companies don’t share their industrial secrets with potential competitors — let alone with a foreign government.

If we want to develop our own data centers, it won’t be using the technology of the Silicon Valley companies the government spoke with.

Brazil also doesn’t develop advanced logic or memory chips, the kind required by this type of data center — they would all be imported tax-free. Developing an industry in this area would take decades anyway, and it’s not on the agenda of any influential politician today.

Tax revenue gains

We’re also not going to collect much in taxes from these foreign-owned data centers. The government is proposing exemptions from IPI, PIS, Cofins, and import taxes. It’s set for five years, but we know how these benefits tend to get renewed indefinitely — the government is currently facing a crisis on this front, trying to revoke past benefits, without success.

Even the purchase of equipment — servers, switches, etc. — could be made abroad, with funds transferred from one multinational to another, never passing through Brazil, never paying IOF or any other tax. And import taxes would be exempt (but not when you buy a processor for your home or business).

BNDES is even planning to finance part of the effort. So not only would we fail to collect taxes, Brazilian society would actually be financing foreign companies in their extractive efforts with billions of reais ⁸ ⁹, and even donating half a billion reais to build data centers and other infrastructure for AI initiatives ¹⁰.

The proposed 2% to 8% revenue transfer to FNDIT is a good idea and perhaps the only real counterpart offered so far, but it’s clearly not enough.

Reserving 10% for domestic processing

Today, there are only a few public cloud regions in Brazil: two from Azure, and one each from AWS and GCP — all launched years ago, with a good portion of their processing already targeting Brazil and South America.

We also have other data center companies operating here. Numbers vary, but there are around 175 publicly offered and another 100 or so private ¹¹ ¹² ¹³. MDIC estimates 163 data centers in Brazil ⁵. The number varies because the methodology for counting a data center varies too (private, public, size, etc.).

This is already a mature market. New data centers operating here, at the proposed scale, would have almost all of their processing aimed abroad. To be blunt: exported.

Environmental impacts

If there’s one glaring omission in this project, it’s the Ministry of the Environment. As we’ll see next, the environmental impacts are significant, and without careful attention to the sustainability of these initiatives, we put the future of Brazilians at risk. We’re talking about the exploitation of natural resources — and the ministry responsible for overseeing this area is absent from the project ¹⁴. Why?

Electricity demand

According to Empresa de Pesquisa Energética (EPE – a state-owned company), in its 2024 national energy report ¹⁵ and executive summary ¹⁶, Brazil generated 708 TWh (terawatt-hours) of electricity in 2023. A cloud data center from one of the three major providers consumes on average 100 MW, which adds up to about 876 GWh per year. In other words, just 808 of these data centers would consume the entirety of Brazil’s electricity production. The (unrealistic) government projection of building about 350 data centers would require a 43% increase in electricity generation — and that’s not even considering the needs of the population or other industries. Between 2014 and 2023 (ten years), growth was only 18%, or 112 TWh, while GDP growth in the same period was 5.7%. So, while energy production has outpaced economic growth, it still falls far short of what would be needed to meet such demand.

Even if only half of the government’s proposed investment were realized, production would still need to increase by 21.7% — in a country that already frequently faces blackout threats. We’re talking about an additional annual demand of 153 TWh, which is 36% more than the growth of the last decade — and again, that’s without factoring in other sectors or the data centers already in the pipeline.

The National Electric System Operator (ONS) also identified data centers as major upcoming consumers in its medium-term energy studies for 2025–2029 ¹⁷. According to the report:

Forecasts from the Ministry of Mines and Energy (MME) project 10.5 GW of electricity demand from data centers by 2037, in the Southeast, Northeast, and South regions.

This forecast doesn’t even include the new projects that would be spurred by the government’s proposed policy. Again, if 175 new data centers were built, the added demand would reach 17.5 GW, or 153.3 TWh per year. That’s 166% beyond the forecast for the next 12 years — squeezed into just 10 — and current demand is already heavily concentrated in São Paulo, which hosts nearly 70% of existing data centers. Meanwhile, half of the forecasted electricity demand is concentrated in Rio Grande do Sul, creating bottleneck challenges (data from EPE ¹⁸).

We also need to consider that building a data center — even when starting from the planning phase — typically takes significantly less time than building the required energy infrastructure. A large data center usually takes around three years to complete, while smaller ones can be ready in under a year. In contrast, building power transmission lines — from planning to deployment — takes at least four and a half years (58 months), and can stretch to nearly nine years (104 months), again according to EPE ¹⁸. The uncertainty around this potential growth is one of the biggest planning challenges, according to EPE, and it puts both residential and industrial consumers at risk — as well as the viability of the data center projects themselves.

Water demand

Microsoft claims to be highly focused on minimizing environmental impact. On its page about sustainability and data center efficiency ¹⁹, it publishes a table stating that it uses, on average, 0.3325 liters of water per kWh.

Given that a modern data center consumes around 876 GWh per year, this translates to 291 million liters of water annually (876 million kWh times 0.3325). According to a UOL article ²⁰, Sabesp produced 815 million liters of water in the first quarter of 2025. Extrapolating, that’s 3.2 billion liters per year, supplying 29 million people across 375 municipalities ²¹.

A single data center would require almost 9% of that total. Half of the government’s goal — 175 data centers — would be devastating. There simply isn’t enough water.

There are lower-impact water recirculation technologies available — but they are more expensive. In a public program with no incentives for investment, in a peripheral country exploited by multinationals seeking deregulation, it’s highly unlikely these would be adopted.

Who benefits?

An analogy illustrates well what’s being proposed. Imagine the government owns a vast rural property, suitable for agricultural and livestock investments, but currently inactive. Seeing all this potential going to waste, it decides to stimulate the economy. It talks to foreign investors and offers all sorts of incentives for them to occupy this idle land. They agree and, in return, offer to pay 2% to 8% of the revenue generated from using the property — and all production will be mechanized. Our land would be used to feed the world, our natural resources — which belong to all Brazilians — would be handed over to foreign nations, enriching only a few intermediaries along the way.

Back to the real scenario: with no significant job creation, no technology transfer, and no meaningful tax revenue, but enormous pressure on our natural resources, it becomes clear that the only real winners would be the foreign companies that take the deal — along with those who profit from the commercialization of natural resources, like companies trading in energy and water. There would be some secondary, non-strategic gains — for example, low-value suppliers of products and services. But it’s not as if selling and maintaining air conditioners is going to change Brazil’s situation in any meaningful way.

So once again we return to the core question: What is Brazil’s strategic interest in this project?

This is a debate about the exploitation of our natural resources.

Around 12% of the planet’s freshwater is in Brazilian territory. While the North region holds roughly 80% of the country’s available water, regions near the Atlantic Ocean hold less than 3% of Brazil’s water resources. ²²

Our energy matrix is mostly renewable, lowering the environmental compensation costs for the companies that own the data centers. But the destruction caused by hydroelectric plants — and all other externalities — is borne by the Brazilian people. If we’re going to exploit this potential, the question is: why? What does Brazil gain?

This is a debate about capital outflow.

These companies are looking for cheap water and energy in Brazil to export processing capacity — a modern version of soybean exports, with far greater demands and no real benefits in return.

So you process the data here and send it abroad. Folks, this is nothing more than exporting energy. Right now we have a 20% energy surplus in an industry that’s only just starting to recover, and still slowly. This is our chance to grow our energy consumption by exporting clean energy, which is exactly what this industry demands. ¹⁸

Gustavo Estrella - CEO of CPFL Energia

Real need

As we’ve already seen in the section on electricity demand, the Ministry of Mines and Energy (MME) is forecasting a 10.5 GW increase over the next 12 years — without any additional incentives. Assuming 100 MW per data center, that comes out to just over 100 new data centers in the period — or roughly ten per year. This already represents a 64% growth, based on the current number of 163 data centers, according to the Ministry of Development, Industry, Trade and Services (MDIC) ⁵.

The numbers vary, and it’s hard to be precise, but other sources confirm ²³ this level of growth. While there may be some shortage in this market, it’s already being addressed. There’s already immense interest in Brazil’s data center market, with concrete investments underway, such as Scala Data Centers’ project in Rio Grande do Sul ²⁴, currently one of the largest in the country.

Industry players claim processing costs are high in Brazil, arguing it’s due to an imbalance between supply and demand. In reality, the imbalance comes mainly from other causes — the infamous “Brazil cost” also affects the tech sector. It’s no surprise that the country with the highest real interest rate in the world also faces high operational costs. The real issue isn’t a lack of incentives for data centers — it’s how Brazilian society is structured, choosing to reward rent-seekers rather than labor and innovation.

There is national demand, and we already have projects underway to meet it. What’s really at stake in the new federal proposal is whether Brazil wants to serve foreign demand by exporting capital while exploiting its own natural resources.

Railroading through

When data centers in Brazil became a topic of public debate, a range of actors began lobbying to influence related matters. And it’s showing results — some authorities are already echoing those interests.

One example is the discussion around artificial intelligence regulation — or any sort of regulation on technology at all. The data center sector is actively pushing for no regulation ²⁵, claiming that a deregulated environment is essential for the installation of these extractive data centers.

Some relevant statements from these areas:

In December 2024, while the Senate was debating a bill to regulate artificial intelligence, the data center sector published a letter requesting the removal of an article that would have mandated payment of royalties to content owners for material used to train AI. ¹⁴

According to Alckmin, the main bottleneck for AI worldwide is energy, and Brazil, he said, “has abundant and renewable energy”. ²⁶

Technology and digital infrastructure are a win-win agenda for Brazil and the US. Our role is to help ensure the regulatory environment keeps pace with that ambition. ¹

Fabrizio Panzini, Director of Public Policy at Amcham

This kind of initiative is opportunistic — it has no real connection to building data centers in Brazil. If the government’s proposal only requires 10% of processing to stay local, then the vast majority — the other 90% — would be exported and not subject to Brazilian regulation.

The processing of Brazilian citizens’ data should be governed by strict legal standards and aligned with the values of Brazilian society — which doesn’t want to see its data mined by foreign companies. The demand for data centers in Brazil already exists under current regulations, and the argument that deregulation is necessary to attract interest is simply false. The interest is already here.

Brazilian AI

The federal government is already planning the creation and promotion of a Brazilian artificial intelligence initiative ¹⁰. While such an effort does require computing resources, it has no direct connection to the proposal of bringing in foreign companies to exploit our resources through a data center project.

First, it’s important to distinguish between training an AI model and running it. Running a model scales like any other computing service — it grows with demand. Training, on the other hand, requires a large upfront investment before any result can be seen. And as companies like China’s DeepSeek have already demonstrated, it’s possible to train models more cheaply using distilled (derived) models, and there are also already-pretrained models available.

But the bigger issue here is something else — and I’ll only touch on it briefly: building an AI isn’t something you pay for once and then it’s done. It needs constant updates; it’s a continuous investment project. The Brazilian state is currently struggling to maintain fiscal balance, and it needs to seriously consider whether this should be a priority. The way this topic is being discussed, it gives the impression that it would be a one-time expense. It’s not.

Some are concerned that Brazil will miss the opportunity to join the AI race. But if Brazilian companies or the government decide to enter this market and compete on equal footing with global leaders, the main challenge won’t be the current or future supply of processing power. The current market is already mature.

Alternative proposals

There are several ways to invest in data centers in Brazil. Let’s go through the alternatives, from worst to best.

“National champions”

This is the model China has adopted. Unsurprisingly, they now compete with Western cloud providers on equal footing. This model involves incentivizing private companies, within a strategic framework. There are serious distortions in this kind of setup, as it creates a new tech oligarchy — or reinforces an existing one — and Brazil has been ruled by the same oligarchies since the time of slavery.

But there’s a problem with copying the Chinese model: the Brazilian state does not steer the economy strategically like China does. There’s a high risk that such investment would fail and end up enriching a few capitalists in another chapter of accumulation and patrimonialism (br: patrimonialismo). There’s a world of difference between a country that plans 25 years ahead and one that fights every week to push through basic state policies. So we’d have to accept the creation of large, functional companies that would be corrupt and uninterested in improving life for the Brazilian people — though at least the investments would remain here. Until, of course, a new government came along and allowed those companies to be sold to foreign capitalists — exactly what happened to our aerospace industry ²⁷, once considered strategic for national defense and sovereignty, until it wasn’t anymore.

This is a bad model — one we’ve tried before and that is doomed to fail because it relies on the good will of oligarchs and monopolists.

Foreign companies + real counterparts

Assuming we are willing to hand over our natural resources to foreign companies, we can still demand something in return that isn’t pure surrender and could actually benefit the Brazilian people. Let’s remember: we are under no obligation to give up our resources. If there’s external interest, we have the sovereign right to negotiate.

The first steps are obvious: undo the harmful proposals already outlined — reinstate taxes, enforce regulation, require technology transfer. But we can go further. For example, to offset water and energy consumption, we could require that data centers be built alongside sustainable infrastructure, such as solar panels and closed-loop water cooling systems — more expensive, yes, but far less wasteful.

We could also require partnerships with national companies, just as China does. Foreign firms could operate here, but at least 51% of the capital and operation would need to be held by a company with domestic ownership. This would also help drive technology transfer. But it’s important to recall what I pointed out earlier: large cloud providers are not interested in sharing their technology or forming joint ventures. Measures like this would push them away. Just look at how many don’t operate in China for precisely this reason — not because of so-called censorship. We know by now that the West is willing to work with any (so called) authoritarian regime that makes strategic sense — but sharing technology never does.

This model might be beneficial, but it doesn’t move the country forward strategically. Brazil would act like a landlord renting property to an entrepreneur at a fair rate: we wouldn’t be the entrepreneurs ourselves, and we wouldn’t advance in terms of sovereignty or national development. Still a bad deal.

Public investment in data centers

This could be done with or without private partnerships, and it’s the model we adopted with Petrobras. Drawing that parallel, it’s important to remember that Petrobras is constantly under attack — politicians often want to privatize it, and both domestic and foreign oligarchies dream of owning this market. We saw the consequences of that recently with the sale of refineries, which led to higher fuel prices (and increased inflation), and the sell-off of BR Distribuidora, which stripped the state of its ability to pass on international oil price reductions to consumers. As a result, lower oil prices benefited only a few, rather than the majority — and once again, the government lost an important tool of monetary policy.

Now imagine what would have happened if Petrobras and its predecessors had not been created. Brazil would never have found oil and would now be completely dependent on imports, unbalancing its already fragile trade balance. Or, if the oil had been found, its exploration would be in foreign hands, and we’d receive little from the exploitation of our own natural resources — the outcome would have been purely financial.

The parallels are obvious. This is the only option that truly makes sense. The creation of a competent, national, state-owned tech industry — just like we did with oil — would ensure that the benefits of exploiting Brazilian natural resources with technology actually stay in Brazil. It would face the same challenges as Petrobras: corruption, inefficiency, and so on. But it’s still better than the alternatives.

That said, the oil-data center analogy has its limits. The data center market is very different. Petrobras is a monopolist in a protected market, while a state-owned data center initiative would face fierce competition from established domestic and foreign players. Any such project would need to be designed with that reality in mind.

This is the best alternative if Brazil’s long-term interests are taken seriously — but it’s not an easy path. It’s made harder by the fact that such a project would only bear fruit in decades. It would require commitment from successive governments — often from opposing parties and ideologies. How do you ensure a 25-year plan in a country facing constant political instability? This kind of initiative requires a state policy, not a government policy.

Sovereignty and cutting-edge technological development

Brazil must decide whether it wants to be part of cutting-edge technological development — in areas like logic processors, memory, and software — or remain dependent on foreign partners. Today, such development happens in countries that do not see us as partners, but as consumers. The current hardware production network is concentrated in just a few countries, like the Netherlands, Taiwan, the U.S., and South Korea, with China pushing ahead and showing it may become the leader in this field within a decade, more or less — and doing so with less reliance on foreign suppliers. China took 40 years to reach this position, always through centralized planning, where companies are expected to execute what’s laid out in national strategic plans that serve the needs of the country. Without a similar strategic direction, any effort on our part is doomed to fail.

Forget about any partnership for strategic technology transfer with ASML, TSMC, Samsung, Intel, AMD, Microsoft, Google, or any other similar company — such initiatives are simply not in their interest. But there is the possibility of discussing a partnership with China. Perhaps the BRICS framework can also open space for such a relationship, and this kind of alliance could allow Brazil to take a leading role in just over a decade. That is the only viable option I see in the current global context, and it depends entirely on China’s willingness — which, it’s worth noting, has shown signs of interest ²⁸.

Such an initiative would allow the creation of a national hardware and software market that could support the development of sovereign data centers in Brazil, while also advancing the country’s overall sovereignty. Any other effort might yield short-term economic benefits, but would lock us into dependence, with no real autonomy, since all the technology would come from abroad. And if we’re going to accept such dependence, it makes no sense to do it with countries that don’t consider us part of their bloc (e.g., the U.S., Europe, Japan, etc.).

Meanwhile, the Brazilian government has already launched a plan to build a sovereign cloud and has invested R$1.2 billion in it ²⁹. That initiative could be positive — if it weren’t relying on foreign software ³⁰ to manage the data centers. Leaving aside the (unnecessary) costs of such a project, one thing must be made clear: there is no such thing as sovereignty when the brain of the so-called sovereign cloud is built with foreign technology, which may contain strategically placed vulnerabilities — usable to extract data from Brazilians or even shut down the entire operation in a scenario of conflict or sanctions. This kind of infrastructure must be treated as a matter of national security, like military technology.

Relying on foreign proprietary software for something this strategic is lazy. There are open-source-based technologies available to build a national solution, and Brazil has enough talent to make that work — as demonstrated by Magazine Luiza when it repatriated several Brazilians to build its own cloud infrastructure.

Another topic that should be central to this conversation about technology and sovereignty is education — yet it’s absent from all the plans mentioned by those involved in the federal government’s data center project. Brazil already suffers from a serious shortage of tech professionals and a significant brain drain. Not only do we fail to train enough people for high-tech fields, we also lose a big chunk of those we do train to foreign countries — yet another form of capital export. There is no future for technological sovereignty without brains, and yet this issue is shockingly left out of the conversation. The Ministry of Education is just as absent from this debate as the Ministry of the Environment.

Conclusion

Brazil has had a mature data center market for decades. It is a competitive industry with a large number of new projects currently underway — many of which pay taxes and are operated by companies with Brazilian capital.

The current proposal is a disaster for Brazil. The government needs to listen to our experts and build a long-term strategy that guarantees sovereignty and sustainability — rather than behaving like a servant to foreign interests. We are a globally valued market; we must develop our potential based on our sovereign interests, generating positive outcomes for the entire Brazilian population — not at their expense.

To learn more

References

Modernizing the website using Bootstrap 5

giggio@giggio.net (Giovanni Bassi) — Wed, 02 Apr 2025 13:00:00 -0300

In the last few days, I updated this site to Bootstrap 5. I took the opportunity to make several improvements and I want to share how that process went.

More than just an update, I used this chance to enhance various parts of the site, including where it touches Hugo.

Bootstrap 5

Migrating to Bootstrap 5 turned out to be much smoother than I expected. I thought it would be an extremely laborious process, but in practice, it was pretty straightforward. There are countless articles and even the official documentation that explain every step, so I won’t dive too deep into the technical details of the update itself. During the process, I realized I could improve other parts of the site, so I decided to work on them as well.

If you want to check out the update, the commit is on Github.

EcmaScript modules

Bootstrap 5, released in mid-2021 (three and a half years after version 4.0), brought full support for ES Modules, which are widely supported by 2025. Previously, my code loaded scripts and styles via CDN. That took advantage of users’ caches but ended up downloading the entire library, including unnecessary code and styles since not everything was used. Plus, it didn’t use ESM.

With ESM, I was able to apply tree shaking – the removal of unused code. Luckily, Hugo already offers an option to perform this process, making everything extremely simple.

I created a file called vendor.mjs to list only the dependencies I actually use. This is the file that gets compiled. It basically exports the libraries, like this:

export { Popover, Tooltip } from 'bootstrap';

Using Hugo’s js.Build method, the bundle is generated automatically. In short, it looks like this:

{{ with resources.Get "/js/vendor.mjs" }}
 {{ $opts := dict
 "minify" hugo.IsProduction
 "sourceMap" "linked"
 "format" "esm"
 }}
 {{
 printf `<!-- Vendor file: %q -->`
 (js.Build $opts | fingerprint "sha256").RelPermalink | safeHTML
 }}
{{ end }}

This file is then imported into my main script, the script.js, with a simple import. It starts off like this:

import { Popover, Tooltip } from './vendor.mjs';

I simply import this file, without building it, which means the vendor file isn’t inlined. The challenge was that the file name changes (because of the fingerprint), but I solved that with an importmap script.

I started using Bootstrap installed via Npm, which made the process a lot easier because Hugo’s js.Build uses esbuild to automatically search within the node_modules directory.

Another advantage is that the vendor file remains static, which allows browsers to leverage their cache extensively. It only changes when I update the dependencies. When that happens, the compiled file name changes, solving browser cache issues. The same goes for script.mjs, though that one tends to change more often as new features are added.

Fun fact: rewriting this script was the only part that Github Copilot managed to automate during this migration – and it generated a bug that I fixed right away.

Sass compilation

I had already been performing tree shaking and analyzing all of my Sass/CSS, but the Bootstrap CSS was loaded entirely via CDN. Since Bootstrap’s Sass is already available in node_modules, I started integrating it directly, eliminating all of the unused Bootstrap CSS. I lost the potential cache benefits from the CDN, but I believe the vendor file will make up for that.

The challenge was tweaking my unused CSS analysis function, as much of the CSS remaining in the final file (before tree shaking) wasn’t written by me. This script cross-references the generated HTML with the CSS and points out unused selectors, allowing me to remove them manually afterward. With a bit of Bash and open-source tools, I managed to sort it out. If you’re interested, check out the unused-css script in the package.json.

Goodbye jQuery

I’m incredibly grateful to jQuery – it paid many of my bills and was a great companion – but by 2025, it just doesn’t make sense anymore. While Bootstrap 4 depended on jQuery, Bootstrap 5 does not. So, I removed it.

The problem was that the lightbox library I had chosen depended on jQuery, and I didn’t want to keep it around just for that reason. I decided to replace it with Photoswipe, which already supports ESM, making implementation easier. To import it, I used another script with importmap, pointing directly to the CDN. And with that, I also eliminated the extra files from the previous library, which required me to also deliver its images. Now, everything comes from the CDN.

Switching FontAwesome to JS + SVG

After optimizing Bootstrap’s JavaScript and CSS, I decided to tackle other areas of the site. I noticed that the web font files for FontAwesome were quite large – with three groups of free fonts (solid, regular, and brands), totaling over 300KB. On the other hand, FontAwesome offers an option to use JavaScript + SVG instead of fonts, without changing the HTML. This approach even allows for tree shaking, as described in the documentation.

The biggest challenge was the documentation, which ended up being confusing, especially with the constant promotion of premium icons. I’m considering switching to Bootstrap’s own icons or at least mixing some of them in, but I’m still evaluating. Either way, figuring out how to use FontAwesome’s JavaScript APIs wasn’t simple since there isn’t a complete example available.

I used the same technique with the vendor.mjs file, including only the icons I need. Creating this file correctly was challenging, but with some Bash-fu, I managed to generate a file whose sole purpose is to import the icons I’m using – the fontawesome.generated.mjs. If you want to see how it was done, all of the project’s Bash code is concentrated in one file (and I promise I’ll write a detailed post about it soon): find it here.

The generated file, in simplified form, looks like this:

import { dom, library } from '@fortawesome/fontawesome-svg-core';
import { faMastodon } from "@fortawesome/free-brands-svg-icons";
import { faCheck } from "@fortawesome/free-solid-svg-icons";
library.add(faMastodon, faCheck);
export { dom, library };

In the actual file, lines 2 and 3 contain all the icons.

Using it is super simple: I created another file called fontawesome.mjs, which imports the generated file and contains a single function responsible for initializing the icons:

import { dom } from './fontawesome.generated.mjs';
export function initFontawesome(...nodes) {
 if (nodes.length === 0)
 // essa chamada inicializa os ícones da página inteira:
 dom.i2svg();
 else
 for (const node of nodes)
 // essa chamada inicializa apenas os ícones dos
 // elementos recebidos e é usada quando um elemento
 // com ícone é adicionado dinamicamente à página:
 dom.i2svg({ node });
}

Finally, this file is imported and exported in vendor.mjs.

You might have noticed that the initFontawesome function optionally accepts a list of nodes. To avoid having to call it manually everywhere, I created a MutationObserver that triggers it whenever an <i> element is added to the DOM. So when that happens, the <i> is removed by FontAwesome’s code and replaced with an <svg>.

Dark Mode

One of the reasons for updating to Bootstrap was its new implementation of light and dark themes, something essential for me as a dark mode fan. My site’s all-white look was really bugging me, so this change was a top priority!

Moving Sass variables to CSS

The documentation for Bootstrap explains the process well, and the implementation was very straightforward. The challenge was that my code, inherited from a theme, made heavy use of Sass variables. For an effective dark mode implementation, I needed to migrate to CSS variables (or, more accurately, CSS custom properties). I carried out this migration in this commit – and it was super easy.

Implementing dark mode

The implementation was super straightforward. Preferably, Bootstrap doesn’t rely solely on the prefers-color-scheme media query, since that would make it hard for users to switch themes without altering their browser or OS settings. Instead, it uses the data-bs-theme-value attribute, which you can place anywhere (typically on the <html>).

With that done, you just need to create a section for default CSS variables (which in my case became the light theme), and another for the alternative (dark) theme, something like this:

:root {
 --body-color: white;
 --text-color: black;
}
@include bootstrap.color-mode(dark) {
 --body-color: black;
 --text-color: white;
}

The importance of migrating to CSS variables beforehand becomes clear here.

The Sass color-mode mixin basically inserts the content inside the mentioned attribute, like so:

@mixin color-mode($mode) {
 [data-bs-theme="#{$mode}"] {
 @content;
 }
}

And the above code compiles to:

:root {
 --body-color: white;
 --text-color: black;
}
[data-bs-theme="dark"] {
 --body-color: black;
 --text-color: white;
}

Since the [data-bs-theme] attribute is defined on the <html>, it has higher specificity than :root, altering the CSS variables and consequently, all the site’s colors.

Bootstrap’s documentation provides a base code for this functionality, which I used and tweaked slightly. It only uses the media query until the user opts to switch themes, ensuring a very flexible system.

The biggest challenge wasn’t implementing dark mode, but finding a color scheme that I liked while still respecting the visual identity of the light theme, especially for blog post readability. For that, the predominant background needed to be black – for me, dark mode is truly black. On OLED screens, every turned-off pixel counts! No dark gray. In the end, I liked the result, but I still need to live with it a bit longer to see if it really works for me.

So, did you like dark mode? Any suggestions for improvement? Leave your comment down below!

Adapting generated themes from tools

Two widgets didn’t automatically adapt: the Giscus comments and Hugo’s syntax highlighting. Both used fixed themes, but luckily they offer customization options with just a few lines of JavaScript. Giscus provides an API to adjust the theme, while Hugo’s syntax highlighting allows using external CSS – you just need to change the href of the <link> that loads the highlight CSS.

I’m even thinking about offering users the option to change just the syntax highlighting theme, with a subtle screen element that allows for this change. It’s the kind of customization that’s only possible when you have complete control over the HTML, something that would be quite labor-intensive in WordPress.

Conclusion

This journey took me about 30 hours, with a good portion of that time dedicated to research. If I had to do it again, it would definitely be faster now that I’ve learned the parts of the work I didn’t know before. It was an extremely enjoyable experience getting back into frontend development after a few years, without relying on SPA libraries/frameworks or even TypeScript. Seeing how modern and accessible CSS and JavaScript have become was refreshing. Perhaps soon, Sass won’t even be necessary. JavaScript handles a codebase of this size very well, especially with the TypeScript compiler constantly checking the code, which ends up being a huge help.

I still have other stories from this update to tell, but since they aren’t directly related to adopting Bootstrap 5, I’ll save them for another post.

So, did you know you could do all this with a static site generator? Were you aware of these new JavaScript and CSS innovations? Drop a comment below and let me know what you think!

It’s so much fun working with Hugo, Bootstrap, modern JavaScript, and CSS!

Under the hood: creating a site with Hugo

giggio@giggio.net (Giovanni Bassi) — Mon, 24 Mar 2025 15:00:00 -0300

Evaluating the Options

When I decided to create a new website, the first option that came to mind was WordPress. I’ve been using it for many years and I like it. Since I’m also well-versed in infrastructure, setting up a service in the cloud and running it is very simple. It’s tempting.

But there are performance challenges. While I maintained the Lambda3 site, we faced several problems. Initially, we solved them with cache plugins, but over time, even that wasn’t enough, and we started using Cloudflare’s cache, which in fact solved the problem definitively.

It was a bit much: PHP + MariaDB + Cloudflare, all just to serve a static site. And it still needed plugins to write in Markdown, which was what I wanted from the start. Wasn’t there a better solution?

My main argument in favor of WordPress is its ecosystem of plugins, which is unbeatable. But for a static site, that seemed excessive. I just wanted a site with a blog and a few sections. Did I really need all of that?

Giving up WordPress meant having to deliver everything it and its plugins do. My minimum requirements included static pages, a blog, and RSS. Along the way, other needs emerged: posts categorization and tagging, blocking generative AI robots, image optimization, among others. Not to mention the common frontend needs, like compiling styles written in Sass.

Choosing Hugo

Decided to use a static site generator, I went to evaluate options. I wanted fast software, under constant development, mature and free. It needed to meet my needs and offer flexibility for the future. Hugo won, but other good options were Astro, Jekyll, and Zola. I evaluated others, but these were the ones I considered the most. It’s been a while since I made the decision for Hugo; I started the project months ago, and it was shelved for a while.

Hugo met everything I needed. With almost 80 thousand stars on GitHub, it is a tool in constant update, with almost 9 thousand commits. Made in Golang, it has good documentation and an active forum for questions.

Moreover, it features hundreds of themes distributed across the internet. Since I’m not a designer, that was essential. I chose the Roxo theme, which I ended up completely customizing. The only thing that will still give me trouble is updating Bootstrap 4 to version 5, something that isn’t so trivial.

What’s Good About Hugo

Development Experience

The development experience with Hugo is excellent. The built-in server, started with hugo server, runs the site and hot reloads whenever a file is changed. Changes in CSS don’t even reload the page; they are applied dynamically. On my machine, a Markdown post takes 22ms to process, and the entire site half a second. On GitHub Actions, the build takes 2.5s, so YMMV. Template development is equally fast; you save and immediately see the result, without delay. The experience is the same as developing a dynamic site with server-side rendering, and with immediate feedback, somewhat better than working on an Angular or React SPA.

Flexibility

With Hugo, you have full control over HTML, CSS, and JavaScript. You don’t depend on whoever wrote a plugin to adapt it to get to the result you want. There are plugins for Hugo (called modules), but the most common is to find code snippets to customize as needed. Since it is very extensible, that’s enough. I really liked this approach, which allows for enormous freedom.

Template System

Hugo uses HTML templates to structure the site and Markdown for content. This is useful because metadata remains in the front matter, facilitating translations, RSS, and other features.

Its template system is powerful. The templates are divided into types, such as sections (lists of pages) and individual pages. There is support for partials, allowing for the componentization of reusable elements like header and footer.

The templates can generate any format, such as JSON, XML, or others. This is essential for features like sitemap.xml and RSS.

Data Features

At the footer there is a section of podcasts I listen to and blogs I read. Both were built using a Hugo feature to reference data sources. You can create CSV, JSON, TOML, YAML, and XML files (I used YAML) and use them as a source.

For example, creating a YAML data file for podcasts, like this:

- name: Medo e delírio em Brasília
 url: https://medoedelirioembrasilia.com.br/
- name: Hipsters.tech
 url: https://www.hipsters.tech/

And then using it, like this:

{{ with hugo.Data.podcasts }}
 <li><a href="{{ .url }}">{{ .name }}</a></li>
{{ end }}

Shortcodes and Code Fences

There are also shortcodes, which are ways to easily create HTML, like embedding a YouTube video, or creating code with syntax highlighting.

{{< youtube EFAe8W3n2ks >}}

The codes above were generated solely with code fences — those codes with three or four backticks in the markdown — and they use a shortcode under the hood. This is an example of code fences with yaml:

```yaml
prop: true
```

Taxonomy

Hugo has a taxonomy system, which is a way to categorize your pages. The most common, and what I’m using, are categories and tags for blog posts, but you could use it to organize anything. I also used it to build pages for types of contributions (for example, videos – check its code on Github).

The example they use in the documentation is with movies and actors. Thus, a movie page can list its actors. Actor is the taxonomy, the actor’s name becomes the term. The cool thing is that you can create pages for these classifications, both for the taxonomy and for the term. That’s how I have here the categories page, tags, and each of their terms, such as the tag blog. The pages, the taxonomies, and the terms are data that you can manipulate.

Build

During the build, all pages are generated, the entire site. With the dev server running you can choose whether to rebuild everything or just the page that changed. It builds the lists of pages, the taxonomies, everything. It also caches everything it did, such as image manipulations and files it may have downloaded.

Hugo supports environments. In dev, it doesn’t optimize anything (and this is configurable). The prod build, on the other hand, can do a series of things. Just look at what happens on my site:

Sass compilation, concatenation of all CSS, tree shaking (with PostCSS), minification, and fingerprinting.
Optimization of all images, which are converted to webp and in some cases resized.
HTML minification

I also perform critical CSS analysis with the critical tool, which is run for each individual page. I also generate search with pagefind (you can try it at /search – and I admit I spent little time on it, but it’s working).

This happens locally, if I want to test, and also using the workflow from GitHub Actions, which also performs linting and spell checking (with cspell).

Other Features

Hugo supports multiple languages, and I’m using that on this site (click the little flag at the top in the header).
The index, at the beginning of this post, was also built using a page metadata, the .TableOfContents (check out the source code).
You can use external resources that can be downloaded, such as an image, or a CSS file, or JSON, and then process them and generate content from them. That’s how I’m generating my robots.txt file (see the source on Github), like this:
```
{{- with try (resources.GetRemote "https://link/para/robots.json") -}}
```
(notice the try?)
The integration with Node.js resources is excellent, thanks to the ability to mount directories and files. You can specify that any directory should be available for the site, and when accessing the resource, it copies the necessary files. That’s how I’m doing it with the files from Font Awesome, check out how the configuration file looks:
```
module:
 mounts:
 - source: node_modules/@fortawesome/fontawesome-free
 target: assets/css/fontawesome
```

What Could Improve

Hugo’s main problem is the lack of debugging. When you’re deep into template developing and something doesn’t work as you’d like, ideally you would be able to debug the problem while the site is being generated, but the tool does not offer that.

We’re stuck with good and old writing to HTML approach, using the debug.Dump instruction, when the result appears directly in the HTML, or the warnidf function, which generates a log in the terminal. It helps, but it’s an experience that could be improved. I struggled a bit until I discovered that these existed, so here’s a tip for those who are starting.

Conclusion

I still have more to say about Hugo, but this post is already long. The main point is that Hugo is an excellent tool for static sites. It perfectly solved my problem, it’s a pleasure to use, and from what I see, it will continue to serve me for a long time.

I still have more to talk about regarding the entire structure around it, such as how I used GitHub Pages, the use of Nix to structure the tools, and much more, and that will also be saved for future posts.

What do you think of Hugo? Comment below!

Returning to the World

giggio@giggio.net (Giovanni Bassi) — Fri, 21 Mar 2025 11:00:00 -0300

Fifteen years ago, I shut down my personal website and blog and redirected the domain giggio.net to the website of the company I had created, Lambda3. My blog, .NET Unplugged, was transferred to the company’s blog, with the posts integrated there.

Today, one year and three months after leaving the company, I’m revisiting that — perhaps slightly outdated — idea of writing on the internet autonomously, without depending on a platform or a billionaire’s social network.

The first time I did this was about 25 years ago. Just like back then, this site has an RSS feed, reflecting my insistence on keeping the online world more anarchic and free of intermediaries. I still use RSS to access a variety of content, and I believe everyone should give it a try: less doom scrolling and more deep reading. At the bottom, in the footer, there’s a list of some of these sources, which I plan to expand into a “friends’ blogs” section (another idea over 25 years old) and include other blogs I follow. There’s also a section listing some of the countless podcasts I listen to. This initial version of the site is an MVP, and much more is coming.

(For those who don’t know what RSS is: it’s a way to distribute content without depending on any platform. I use a free RSS reader called Inoreader. Try creating an account there and putting giggio.net/en there as your first feed to see how it works.)

I’m creating this space to express my ideas in a more structured way. Besides blogging, I’ve been writing long posts on BlueSky and Twitter for many years — a spontaneous form of expression. Over the last year, I felt the need for a space to develop something more elaborate than a 15-minute thought. And that’s exactly what I’m doing here.

If you’re here expecting me to talk only about technology, rest assured, I will. But I also plan to reflect on politics, philosophy, and other topics that, frankly, I can’t yet predict. I’m already organizing the posts into categories, so if you prefer to follow just one subject, that’s perfectly fine. And, of course, everything is available via RSS. I’ll also use tags more freely — also with RSS support. I’ll always let you know on social media whenever I write something I find interesting, so it’s worth following me on one of those platforms. Right now, I’m most active on BlueSky 🦋, where I go by giggio.net.

For the first time, I’m also publishing in English. The whole site was built with support for this language, and I plan to translate much of what I publish in Brazilian. Now you can share my posts with your friends and colleagues who don’t speak our language.

Between my personal blog and the one at Lambda3, I’ve published over 700 posts. I’m proud to have written most of them, but unfortunately, they’re currently unavailable for reading, since the company’s old site is blocked and the posts weren’t republished. On the other hand, many of them need to be reviewed — they’ve become outdated, or my opinions have changed. I plan to review each one and re-edit the best ones, updating them to reflect what I think today and the current state of technology. It’ll be an interesting process, both to have fun with my own youthful naivety and to see where I got it right or wrong in my predictions. In any case, some content remains very relevant and deserves to see the light of day again. And for those who didn’t know me many years ago, I believe many will enjoy reading these ideas. Let’s see how it goes.

This space starts off simple, with a few sections. I have an area where I list some of my most recent contributions to the software community and related fields (with some older gems). There, you’ll find videos, interviews, podcasts, lectures, and other content—useful for those who want to access material they might have missed. And, again, everything is available via RSS. There’s also a section where I introduce myself, a contact page, a search function, and that’s it for now.

Soon, I’ll write a post explaining in detail how this site was built. I can already share the basics: all the content is free and available on GitHub at giggio/giggionet. The site was built using a static site generator called Hugo, which is absurdly fast and loaded with features. I’m seriously impressed by the tool’s capabilities — it sometimes comes close to what a dynamic site can deliver. This site, with around 200 files, is generated in 539 milliseconds, while the development server rebuilds this page in 21 milliseconds, with hot reload. An excellent user experience.

I built the entire site with a focus on web standards and accessibility. It scores a perfect 100 on Lighthouse, both on mobile and desktop. I’m not an accessibility expert, but I had help from Marcelo Sales from tudoeacessibilidade.com.br, who gave me some valuable tips on what to check. I’ll talk a bit more about that when I post about how the site was built. If you’re blind or have low vision and notice any difficulty in reading or navigating the site, please let me know — I’ll make sure to fix whatever isn’t working.

Since the code is freely hosted on GitHub, the site is obviously hosted on GitHub Pages, which, when the site is public, offers hosting, a custom domain and HTTPS certificate for free. This is so powerful that I plan to recommend it to many people and organizations, like NGOs etc. In 2025, all you need to have a public site is a domain — the rest is free. What a wonderful moment!

And, since everything is on GitHub, I’m open to corrections, suggestions, and the like. Soon, I’ll add a link to make this easier, something like an “edit this on GitHub” link on each page. The backlog will also be moved there soon, using Github Issues.

I’ll start by getting out of my head those posts I’ve been meaning to write for over a year. Besides diving deeper into some technologies, I plan to elaborate on topics like home automation, Hugo, the PC I built last year, politics, and my current state.

Welcome to this (re)start. I hope you enjoy it. At the end of each post, there’s a comments section — feel free to join in. It’s also based on GitHub (discussions), which helps avoid spam and, therefore, is free.

See you in the next posts.