<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>AI-Assisted on Tech Philosopher</title><link>https://blog.bktus.com/en/tags/ai-assisted/</link><description>Recent content in AI-Assisted on Tech Philosopher</description><generator>Hugo</generator><language>en-US</language><lastBuildDate>Thu, 19 Nov 2026 21:06:01 +0100</lastBuildDate><atom:link href="https://blog.bktus.com/en/tags/ai-assisted/index.xml" rel="self" type="application/rss+xml"/><item><title>GpgFrontend's New Version Model and Release Mechanism</title><link>https://blog.bktus.com/en/archives/651hln/</link><pubDate>Thu, 19 Nov 2026 21:06:01 +0100</pubDate><guid>https://blog.bktus.com/en/archives/651hln/</guid><description>&lt;p>Updates have always been one of GpgFrontend&amp;rsquo;s biggest pain points. From the very first versions, GpgFrontend relied on GitHub Release to publish versions and to check for updates, and it stayed that way for many years. Starting with 2.2.5, and including the current main line, the version numbering rules, the release process and the way the client checks for updates have all moved to a new model and mechanism. How to use it and how to verify things is already in the user manual. But why I did it this way, and what I was thinking at the time, doesn&amp;rsquo;t come across in the documentation.&lt;/p></description><content:encoded><![CDATA[<p>Updates have always been one of GpgFrontend&rsquo;s biggest pain points. From the very first versions, GpgFrontend relied on GitHub Release to publish versions and to check for updates, and it stayed that way for many years. Starting with 2.2.5, and including the current main line, the version numbering rules, the release process and the way the client checks for updates have all moved to a new model and mechanism. How to use it and how to verify things is already in the user manual. But why I did it this way, and what I was thinking at the time, doesn&rsquo;t come across in the documentation.</p>
<p>For security software like GpgFrontend, transparency is a basic requirement. And updates are directly about what actually ends up on the user&rsquo;s computer: where the client connects in the background and what it sends. Users have every reason to be suspicious about that. So I think it&rsquo;s necessary to explain it clearly, so that users know what the update side really looks like. If you want to know how GpgFrontend got here, you can read my <a href="https://blog.bktus.com/en/archives/u8hywl/">previous post</a>.</p>
<h2 id="many-years-of-github-release">Many Years of GitHub Release</h2>
<p>In the beginning, GitHub Release was actually pretty good, at least until a couple of years ago. One thing is that it gives you free distribution. Another is that its model is simple enough: a release is tied to a Git tag. When I released a version, I just created a tag, wrote a Release Note, and uploaded all the installers built by GitHub Actions in one go, and that was it.</p>
<p>Later, the project started moving faster, especially after I brought in AI coding assistance, and now agents too, and a lot of features were added. You don&rsquo;t always notice these features day to day, but when you really use them, you still find some problems. On the old tick-tock rhythm, I released a version every two months. A lot of the time, a problem I missed before a release would turn up one, two or three days after it, found by me or by someone else. At that point it was hard for me to release again right away, because the rhythm was one version every two months, and releasing in between was a hassle.</p>
<p>But on the other hand, releasing every day isn&rsquo;t good either. Most users care about stability and don&rsquo;t want to try new things. They might check for updates once every two months, or even less often. Anyway, most users don&rsquo;t need most of the new features. What they use is encryption, decryption, key generation and so on. Take email, for example. In the past it could basically only work with EML files, and I&rsquo;ll admit myself that it was pretty hard to use. Now the email module has been reworked quite a bit and can cover most everyday email use, but the people using it are still a minority.</p>
<p>So for most users, waiting two months probably doesn&rsquo;t feel like anything, because I check things before every release and the basic features don&rsquo;t break. But users who really do hit a problem have to wait two months to get a fixed version, and that&rsquo;s pretty uncomfortable. I can feel this myself. Still, when I find a problem I can just fix it, build it myself and use it, so anyway it doesn&rsquo;t affect me. But imagine you don&rsquo;t have the means to build it yourself, or you&rsquo;re not a technical user. Then you have to wait two months.</p>
<p>That&rsquo;s why I later introduced Nightly Builds, which follow my development line. They used to follow the develop branch, and now they follow the main branch. As soon as I commit and push to GitHub, the pipeline starts a build automatically. Nightly and the stable release are of course different. Whatever you say about it, the stable release is a set of features that have been verified, while the main line brings in a lot of new features. Most of the time these new features don&rsquo;t conflict with the stable ones, but sometimes I make architectural changes or optimizations, and at that point I can&rsquo;t yet verify that they won&rsquo;t affect stability. So Nightly uses a different profile from the stable release: it runs as a separate app, GpgFrontend Testing, with its own keys and settings.</p>
<p>As for how it was published, Nightly had only one <code>nightly</code> tag. When the pipeline ran, it pulled the latest commit on the branch and built it, then force-overwrote the existing <code>nightly</code> tag, used an action plugin to create the release, and filled in the Release Note template for the Nightly Build automatically. The stable release kept the usual <code>vX.Y.Z</code> tags. Nightly and the stable release lived side by side on GitHub Release like this for at least a year or two, and it felt fine. But Nightly had no numbering like 1, 2, 3, so users could only see the latest one.</p>
<h2 id="the-turning-point-22-and-multiple-release-lines">The Turning Point: 2.2 and Multiple Release Lines</h2>
<p>The real turning point was version 2.2. 2.2 introduced a second engine, so the GnuPG engine and the RPGP engine can be used at the same time. It was a fairly big architectural change. Back then, I needed time to prove that the changes that came with RPGP wouldn&rsquo;t affect existing users who mainly use GnuPG. So I kept the 2.1 line, the original single-engine release line, and kept updating it as usual, while the 2.2 line also kept moving forward.</p>
<p>At that point, 2.1 users would very likely want to stay on 2.1. For them, I could only push 2.1 updates first, and then recommend upgrading to 2.2 once 2.2 was stable. If you use GitHub Release for this, the only way is to make the client logic thicker. The client calls the GitHub Release API, works out which versions 2.2 has and which versions 2.1 has, gets the metadata of each version, and then calculates locally: does 2.1 have a new version, is 2.2 already stable or still in pre-release, has anything been withdrawn, and so on. Only then does it notify the user. It&rsquo;s doable, but it always felt pretty awkward to me.</p>
<p>GitHub&rsquo;s release model can express two release lines, but it&rsquo;s, how should I put it, missing some flexibility. For example, when you publish a release, you can mark it as latest, but that latest is the latest across all versions. For an older release line, say one kept around for users on older systems, its newest version isn&rsquo;t the newest version of the whole project.</p>
<p>Another thing is EOL (End of Life). Say I plan to end 2.1 on December 31 of some year. With GitHub Release, I can&rsquo;t just take all of 2.1 down, because all of it has to be archived and kept on record. So the only way is to hard-code it in the client: after December 31, 2.1 is EOL, and it recommends upgrading to 2.2. But the client is software installed on the user&rsquo;s computer. Once it&rsquo;s released, that value is very hard to change. If I want to extend support, or end it earlier, there&rsquo;s no way to do it unless the client reads the value remotely from somewhere.</p>
<p>Then there&rsquo;s the rate limit. GitHub&rsquo;s API limits how often you can call it. Once at my company, I downloaded GpgFrontend on my own computer and wanted to check for updates, and it turned out the whole company&rsquo;s exit IP had already hit the limit, so it simply didn&rsquo;t work. With a VPN it was often the same, unless you log in, and the client can&rsquo;t log in, which is pretty awkward. On top of that, it&rsquo;s tied too tightly to the platform: you can only distribute through GitHub. If I wanted my website to detect the user&rsquo;s platform automatically and offer a download link, that link could only point to GitHub. Downloads weren&rsquo;t very stable either, and with a VPN they could be pretty slow, so it wasn&rsquo;t a great experience. (As for the many people who don&rsquo;t want to touch anything GitHub-related since Microsoft bought it, that&rsquo;s a side note, not the main reason.)</p>
<p>Of course, all of this isn&rsquo;t completely impossible on GitHub Release. For example, you can write some agreed-upon data into the Release Note, have the client read it, and decide based on that. But one thing is that it&rsquo;s not a proper standard, and another is that it&rsquo;s fragile. It&rsquo;s like a kitchen knife: you can use it for almost anything, but in some special cases using it is just clumsy.</p>
<p>And precisely because the GitHub approach needed so much extra logic and was so easy to get wrong, I simply didn&rsquo;t add it. I kept the update check plugin very simple: it only talked to GitHub, read some simple metadata and made a decision. The result was that the plugin wasn&rsquo;t very useful, and it did almost no verification. How would the client know that a newly published version was signed? It&rsquo;s hard to conveniently get these signatures from GitHub, or metadata like the “root” behind the signatures. Actually, I rarely used this update plugin myself.</p>
<h2 id="the-new-version-numbering-rules">The New Version Numbering Rules</h2>
<p>Before getting to the new release mechanism, let me talk about the change in version numbers. Under the old rules, a change in the last number didn&rsquo;t mean the release was just a patch. It meant another step forward in a certain direction. For example, the 2.1 direction was about steadily improving all kinds of features on a single engine. 2.2 was multi-engine, and 2.2.1 and 2.2.2 just kept exploring in the multi-engine direction, which didn&rsquo;t mean those updates were small. Someone did raise this as an issue, and that&rsquo;s how I explained it back then. From 1.0 all the way to 2.2.4, that was how I thought about it.</p>
<p>Starting with 2.2.5, to fit the new release model, or rather to make it more sensible, the last number now really is just a patch:</p>
<ul>
<li>The first number is the “Generation”, a change like the one from 1.0 to 2.0. It only changes for a really major architectural change, or when the whole idea of the product changes. It has nothing to do with how many lines of code went in.</li>
<li>The second number is the feature release, which is what the “direction” used to be. 2.2 to 2.3, or 2.3 to 2.4, really means big changes, roughly every two months.</li>
<li>The third number is the fix release. 2.3.1 to 2.3.2, or 2.3.2 to 2.3.3, goes back to what it originally meant: mainly security updates and fixes. It may bring a few features, but as few as possible, unless it&rsquo;s really necessary.</li>
</ul>
<p>The benefit is that stable users can get fixes without needing new features. For example, a user might not want two engines but still want security fixes for the GnuPG engine, or might want to stay on 2.2, which works well for them, rather than move to 2.3. For me, it also makes it fairly easy to control the pace of each release line: I cherry-pick fixes from the main line onto each line, and then push them to the right users through the current update mechanism. Moving from 2.2 to 2.3 is only a recommendation. You can still stay on the 2.2 line and keep receiving patches.</p>
<p>But it&rsquo;s hard for me alone to maintain a lot of release lines. Usually it goes like this: I want to move from 2.2 to 2.3, but 2.3 brings in a lot of new things and doesn&rsquo;t settle down that quickly, so 2.2 definitely has to stay around for a while, and at that point there are two lines. Add the fairly important single-engine 2.1 line, and that&rsquo;s three. Three is the most I&rsquo;ll maintain. The current state is: 2.3 is the main line, 2.2 is stable, and 2.1 is legacy, which only receives security fixes until December 31, 2027. It&rsquo;s also the last series that builds with Qt 5. With the new mechanism, I can update 2.1 once in a while, update 2.2 at the usual pace, and keep pushing 2.3 forward. All of this state is written in <code>release/policy.toml</code> in the repository.</p>
<p>Also, the Nightly version numbers changed. Before, I wrote the version number, say 2.3.0, into the CMake project, so every Nightly Build was 2.3.0, no matter which commit it was built from. Users could see the commit in the build information, but it wasn&rsquo;t convenient to refer to. Now the Nightly version number is derived from git and looks like <code>2.3.0-alpha.138+g&lt;commit&gt;</code>. The number after <code>alpha</code> is the number of commits since the most recent base tag. This makes it easy for other people to refer to and easy for me to find. I don&rsquo;t need to dig through long commit messages and match them up in the repository anymore. When I see alpha.250, I roughly know which day&rsquo;s version it is. Users can also keep the last three or four Nightlies. If a new one doesn&rsquo;t work well, they can go back to the previous one for a while and update again after that stretch of development is over.</p>
<p>Besides stable releases and Nightly, there are also betas and RCs (Release Candidates). Say I&rsquo;m about to release 2.4, and the features on the main line feel about done, but it&rsquo;s not very stable yet, and I want users who are willing to try it to test it first. That&rsquo;s when there&rsquo;s an RC like <code>2.4.0-rc.1</code>. A beta is a test build of the next fix release of a line, with a version number like <code>2.3.2-alpha.3</code>. Betas and RCs are only offered to users who have ticked “Also offer beta versions” in the settings, and that option is off by default.</p>
<h2 id="the-release-mechanism-three-buckets-and-one-update-server">The Release Mechanism: Three Buckets and One Update Server</h2>
<p>With the background of the version model covered, let me talk about the release mechanism. I don&rsquo;t really want to use GitHub Release as the main release channel anymore. The biggest pain points are still the ones I mentioned before: one is that it&rsquo;s pretty slow, and another is the rate limit.</p>
<p>Actually, I&rsquo;ve always been fairly interested in object storage, and I felt something like AWS S3 should host this. A normal web page would also work, but in comparison, the client only needs a metadata file, say a JSON file, and doesn&rsquo;t need the JS and CSS that come with a web page. Also, a web server might let people scan its directories, which is a hassle. I don&rsquo;t want people to be able to grab everything at once. I&rsquo;d rather keep the metadata separate: the client first gets the metadata at the root, and when it needs something else, that metadata tells it where the next index is, and then it goes and fetches that. A lot of technical things can be done in different ways, but sometimes you just have an intuition about which one is better and which one feels more comfortable to me.</p>
<p>I originally wanted to use S3, but its outbound traffic is billed separately, and that&rsquo;s hard for me to control. What if this software gets hit by a DDoS attack and a few hundred TB of traffic gets pulled out at once? With the little money that comes from donations, a few hundred TB every day is not something I could pay for. Later I found that Cloudflare&rsquo;s R2 doesn&rsquo;t charge for distribution traffic, and I&rsquo;ve been using Cloudflare&rsquo;s CDN all along. It did have some incidents a while ago, but for something like software distribution, which doesn&rsquo;t need high availability, it&rsquo;s still OK. So I chose R2.</p>
<p>Then the question is what to store in the buckets, and who puts things into them. The principle I set for myself is that the new mechanism must free up my personal time and make releasing faster, especially for stable releases. In the past, to release a stable version, I had to download the installers one by one, sign them with my Authenticode certificate on my Windows computer, then do an OpenPGP signature on all of them, and then upload them one by one. It took two or three hours and was easy to get wrong. Sometimes I even got the file names wrong. I&rsquo;ve been using scripts since 2.0, and later I had AI write a script for me that downloads automatically from GitHub, asks me to confirm and enter a password for the certificate signature, then a password for the GPG signature, puts everything in one folder, and then slowly uploads it to GitHub Release. That was a lot faster. But I still had to wait for the pipeline to build, with one eye on the pipeline and the other on my own work. And where I live now, access to GitHub Release is pretty slow: the bandwidth isn&rsquo;t high and the VPN is throttled, which made it pretty painful. Another pain point was that Nightly never had a signature. There was no way I could download every build and sign it with my own GPG key, and putting my GPG private key into the pipeline was even more out of the question.</p>
<p>The current structure looks like this:</p>
<pre class="mermaid">
  flowchart LR
  CI[GitHub Actions] --&gt;|builds| Staging[(Staging bucket)]
  Staging --&gt;|stable builds| Me[Maintainer machine]
  Me --&gt;|signed| Staging
  Staging --&gt; Server[Release server]
  Repo[GpgFrontend repository] --&gt;|policy, trust, scripts| Server
  Server --&gt;|promote| Builds[(Builds bucket)]
  Server --&gt;|signed index| Update[(Update bucket)]
  Builds --&gt; Client[GpgFrontend]
  Update --&gt; Client
</pre>
<p>Let me go through them one by one:</p>
<ul>
<li>The pipeline: after a build finishes, it uploads the artifacts and <code>SHA256SUMS.txt</code> to the staging bucket. It also signs <code>SHA256SUMS.txt</code> with Sigstore (cosign), which proves that these files really were built by the <code>build.yml</code> pipeline of the GpgFrontend repository at the matching commit. This kind of signature doesn&rsquo;t need me to hand any private key to the pipeline, so Nightly finally has a signature.</li>
<li>The staging bucket: private and not open to users. It holds things that haven&rsquo;t been checked yet.</li>
<li>My computer: only involved for stable releases. I download the stable build from staging, sign the Windows installers locally with Authenticode using the certificate on my hardware token, sign with my OpenPGP key, and then upload everything back to staging. That certificate lives on a hardware token and can&rsquo;t be exported, so signing in the cloud is impossible, and it wouldn&rsquo;t be safe anyway.</li>
<li>The update server: it checks what&rsquo;s in staging, moves it to the builds bucket once the checks pass, and then updates and signs the index.</li>
<li>The builds bucket (<code>builds.bktus.com</code>): holds the installers, the descriptor of each version and the Release Notes. Users download from here.</li>
<li>The update bucket (<code>update.bktus.com</code>): holds the signed index <code>index.json</code>, plus trust-related files like the root and the index-keys.</li>
</ul>
<p>Why keep builds and update apart? One reason is not to put everything in one basket, so build artifacts and metadata are stored separately. Another is that it&rsquo;s easier to manage: one bucket only holds metadata and the other only holds installers, so they don&rsquo;t get mixed up. Add staging, and three buckets is about right.</p>
<p>The update server sits in the middle and acts as a checkpoint for users. For Nightly, beta and RC, it uses cosign to verify the Sigstore signature and confirms that the build came from <code>build.yml</code> and that both the ref and the commit match. Every file has to match the signed <code>SHA256SUMS.txt</code>, and there can&rsquo;t be any extra files. It derives the version number itself from git instead of trusting the version number the build claims. For stable releases, it also checks my OpenPGP signatures and the signed tag, as well as the Authenticode signer of the Windows installers. Besides that, it reads the guidance file <code>release/policy.toml</code> in the repository, things like when 2.1 reaches EOL and what state 2.2 and 2.3 are in, and generates metadata that&rsquo;s easy for the client to read, which is the index.</p>
<p>The update server is important, because it decides what the client can see. But it&rsquo;s not the most critical link. It doesn&rsquo;t take requests from clients directly, so it doesn&rsquo;t need high concurrency or DDoS protection. It just moves things from the unverified place to the verified place and then updates the related metadata. High availability, high concurrency and DDoS protection are left to Cloudflare&rsquo;s infrastructure. Writing code myself specifically to handle these would be a huge project, and there&rsquo;s no need for it. So the load sits on the buckets, and management and admission sit on the update server. And the client does its own verification too. It treats the update server with suspicion as well, which I&rsquo;ll get to later.</p>
<h2 id="the-signing-root-2-of-3-and-minisign">The Signing Root: 2-of-3 and minisign</h2>
<p>Another question is the signing root. A signing key can&rsquo;t go without rotation forever. I can&rsquo;t use the same key for 30 years. So how do I manage it? I didn&rsquo;t use CA certificates, because that would actually be more complicated. I know X.509 is very flexible and you can add all kinds of fields, but managing it already takes a lot of tools, OpenSSL and so on. It&rsquo;s too flexible and has too many features. This is just a software update. There&rsquo;s no need to do it like Apple: set up a CA root, self-sign it, hold some kind of ceremony, use the CA certificate to sign an intermediate certificate, and then use the intermediate certificate to sign other things. It can be done, but there&rsquo;s no need. Day to day, 2-of-3 plus minisign is already fully enough to handle all of this.</p>
<p>Specifically:</p>
<ul>
<li>The root is made up of 3 keys. As long as 2 of them sign, the next version of the root can take over. The root is valid for two years, which means I update the root roughly every two years, and a new root has to be signed by enough keys from both the old root and the new root.</li>
<li>The root doesn&rsquo;t sign the update server&rsquo;s key directly. It names another offline key, which isn&rsquo;t allowed to be one of the root keys, and that key is only used to sign an index-keys list. This list is valid for one year and states which key the update server may use to sign the index.</li>
<li>The update server only has the one minisign key that signs the index. It has no root key, and none of my OpenPGP keys or my Authenticode certificate. The index is valid for 14 days, and the server re-signs it every day.</li>
</ul>
<p>So the whole chain is: root → offline key → index-keys list → index key on the update server → <code>index.json</code>. If something goes wrong with the update server&rsquo;s key, or if I just feel like changing it once in a while, I only need to sign a new list with the offline key, without touching the root.</p>
<p>There&rsquo;s no way I would write all this JSON by hand, or generate three keys manually and configure them one by one. So I wrote a set of scripts that generate everything automatically according to the design of this mechanism, and I only need to enter passwords. What they generate goes into the project repository under <code>release/root/</code> and <code>release/index-keys/</code>, next to more readable files meant for humans, that is, for me or for other people reviewing the code. The three keys in the current root are <code>4E179325A34DCF45</code>, <code>27458E01B54EAF5D</code> and <code>4D875241843652E8</code>.</p>
<p>Why minisign instead of OpenPGP? GpgFrontend is itself an OpenPGP tool, so this is a natural question. The problem is that OpenPGP needs a context to be prepared before you can use it, and key management is fairly complex. It&rsquo;s also usually tied to a person&rsquo;s identity, so you can&rsquo;t just casually generate a new key, and using subkeys makes it even more complex. At the end of the day, OpenPGP is mainly for individual users in all kinds of situations. For something read by machines and verified by the client itself, it&rsquo;s best to depend on as little context as possible. minisign verification can be done with just libsodium. There&rsquo;s no need to pull in all of GnuPG or RPGP, or to have GpgFrontend&rsquo;s own context load anything. Something lightweight does the job. And here I only need verification, and only the key itself matters. There&rsquo;s no need to look at a User ID like with a personal identity. So in the end I went with minisign.</p>
<p>But the bottom line is still there. Stable releases are still signed in the end with my offline OpenPGP key. No matter how much gets automated, every stable release needs me to personally confirm the version, type in the password by hand and sign with the key on my hardware token. This OpenPGP key is tied to my identity and is trusted by other people. Its fingerprint is <code>12F7E8858CF15BEC9975FF3C5CA3DA246843FD03</code>. This is the last line of defense, and going back to what this project is about, I think it&rsquo;s enough.</p>
<h2 id="the-client-not-blindly-trusting-the-update-server">The Client: Not Blindly Trusting the Update Server</h2>
<p>With the new mechanism, the client can have less logic of its own and rely more on the metadata from the update server: which release lines there are, what state each line is in, which betas are available and which version to recommend. The update server can adjust these for security or other reasons. If version numbers or release lines change later, it can also guide the client fairly easily, without old clients breaking as soon as the rules change.</p>
<p>But the client can&rsquo;t blindly trust the update server. The update server itself could be compromised, and its signing key could be stolen. So the client has the root built in at compile time, and after it gets the index, it verifies things itself:</p>
<ul>
<li>Starting from its built-in root, it walks step by step to the newest root, and each step has to meet 2-of-3. Then it checks the index-keys list and confirms that the key that signed the index is on it;</li>
<li>It verifies the minisign signature of <code>index.json</code> and checks whether it has expired;</li>
<li>It checks the index&rsquo;s serial number and doesn&rsquo;t allow rolling back to an older index;</li>
<li>It uses the sha256 values in the index to check each version&rsquo;s descriptor and Release Note, and then checks downloaded files against the sha256 in the descriptor.</li>
</ul>
<p>If the update server is compromised or does something malicious, the client&rsquo;s verification fails, and at worst you reject it. You just lose the convenience of updating automatically, but you can still download manually from the download page or from GitHub.</p>
<p>The Release Notes are separate now too. They&rsquo;re no longer managed in GitHub Release but kept in the repository under <code>release/notes/</code>. A Release Note has to be signed with my OpenPGP key before it can be published, and its hash is written into the signed index. The links inside are controlled as well. Only https links to <code>bktus.com</code> and its subdomains, plus the GpgFrontend repository on GitHub, are allowed. They can&rsquo;t link to unrelated, possibly malicious addresses, and links that don&rsquo;t meet the rules are only shown as plain text.</p>
<p>As for automatic installation, the Nightly AppImage on Linux can already be installed by clicking “Install” in the update window. The downloaded file only replaces the old one if its size and sha256 match the descriptor. For stable releases, I&rsquo;ll look later at how to do automatic installation safely, so it&rsquo;s convenient for users and still secure.</p>
<h2 id="one-set-of-scripts-gfrelease">One Set of Scripts: gfrelease</h2>
<p>This model comes with a set of scripts, kept right in the GpgFrontend repository (<code>scripts/gfrelease</code>), and they are the concrete implementation of the whole model. The update server reuses these scripts directly to do its checks and handle metadata. I use the same scripts myself too, for example to update the root, update the index-keys list, and download stable builds to sign locally and upload back to staging. In other words, it&rsquo;s not that the update server has one implementation and I have another. We both use the same implementation based on this model. The update server itself only has some peripheral parts, like the bits that keep it from going down, the Dockerfile, and a web page where I can see its current status at a glance. The core things, including the implementation of the model itself, the various checks and the OpenPGP verification, are all in the code repository, where everyone can see and review them.</p>
<p>As for the update server&rsquo;s own repository, I wanted to open source it at first, but later I changed my mind. It involves some configuration of my own servers, and if someone knew that configuration, it might be easier for them to find other things after breaking in. The Dockerfile itself is fine, but the compose file has environment variables, and if some key or something like that got uploaded by accident, that would be a pain. It&rsquo;s a very thin layer anyway, so I chose not to open source it.</p>
<p>So I promise that it uses these scripts from the repository, but does that promise count for anything? I can&rsquo;t prove it myself. In theory I could stop using these scripts, but in practice I do use them. Still, a personal promise doesn&rsquo;t count for much. In security software, there&rsquo;s no such thing as “I say it&rsquo;s secure, so you have to trust me unconditionally.” That just doesn&rsquo;t hold. So you can review the root and the related public keys stored in the repository, check whether your client carries the public keys from the commit in the repository that you trust, and verify for yourself what the update server pushes to the buckets. Whether or not the update server has been compromised, you can see it.</p>
<h2 id="what-the-update-check-sends-and-what-it-doesnt">What the Update Check Sends, and What It Doesn&rsquo;t</h2>
<p>I think this part needs to be explained on its own:</p>
<ul>
<li>The update check is off by default. The setup wizard on first launch has an option to check for updates, and it&rsquo;s unticked by default. Once you turn it on, it checks once a day. You can also check manually under Help &gt; Check for Updates.</li>
<li>The client only sends HTTPS GET requests, to <code>update.bktus.com</code> and <code>builds.bktus.com</code>, the domains of the two buckets. It doesn&rsquo;t talk to GitHub, and there&rsquo;s no other extra server.</li>
<li>The requests contain no user ID and no machine ID, there&rsquo;s no request body, and the User-Agent is a fixed, generic browser string. Information like the operating system version and the architecture is only used locally to pick the right file and is never sent out.</li>
<li>One thing to note: the last request is <code>commits/&lt;commit&gt;</code>, and that path contains the commit of your build. It&rsquo;s used to confirm whether the build comes from the official repository. So the server side can tell which build you&rsquo;re running, and from that which version, even though the version number itself isn&rsquo;t sent.</li>
<li>As with any HTTPS request, the server can see your IP address. The buckets are on Cloudflare, and Cloudflare handles and keeps this request data under its own rules. I don&rsquo;t collect or analyze any access data myself, and there&rsquo;s no need for me to do that.</li>
</ul>
<p>I live in the EU now, and under the EU legal framework, this has to be disclosed publicly. So I&rsquo;ll publish a new version of the privacy policy later to bring it in line with the law, and explain in the documentation exactly what the update check accesses and what requests it sends.</p>
<h2 id="how-this-was-built">How This Was Built</h2>
<p>From the first version of the release model to the current implementation, you can see in the commit history that even with AI assistance, I went back and forth through quite a few rounds. First I came up with an idea and asked the AI to see if it could make a simple implementation first. Then I found that parts of the implementation didn&rsquo;t follow software architecture principles, or had bugs, so I had it fix them. After the fixes I used it on Nightly, found it didn&rsquo;t seem quite OK, and changed it again. Later I thought about what to do with other release lines or betas in the future, and changed it again. After the changes, I still had to have it check everything again for problems and whether the code was any good. For example, there was already something usable in one place, and it wrote another copy somewhere else, or wrote yet another function to calculate hashes. It needs to be made to check for these things itself.</p>
<p>I also read the code it commits myself, to see whether there are code smells and whether it matches my understanding of the model. Over several rounds, the AI might implement what you have in mind in a different way you don&rsquo;t like, or simply misunderstand what you meant. You have to keep an eye on that yourself.</p>
<h2 id="afterword">Afterword</h2>
<p>Starting with 2.2.5, and including the current main line, the main version management has all moved to the new model and mechanism. The guidance files in the repository, the pipeline, the update server, the buckets, the client, plus my own computer, each have their own job, with high cohesion and low coupling, which I&rsquo;d say also reflects my own experience. GitHub Release stays on as a mirror. I feel this mechanism is enough, and it probably won&rsquo;t need big changes for a long time. There may be small fixes here and there.</p>
<p>For how to use it and the details, see these pages in the user manual: <a href="https://gpgfrontend.bktus.com/appendix/version-policy/">Version Numbering Policy</a>, <a href="https://gpgfrontend.bktus.com/appendix/release-updates/">How Releases and Updates Work</a>, <a href="https://gpgfrontend.bktus.com/appendix/code-binary-verify/">how to verify downloaded files</a>, and the <a href="https://gpgfrontend.bktus.com/overview/downloads/">download page</a>.</p>
<p>That&rsquo;s about it. This post mainly explains why I built the new version model and mechanism, and some of the basic ideas behind them. I dictated it, then had AI organize it, and after that I checked whether it matched what I think and whether it drifted from what I meant. It wasn&rsquo;t generated in one click by having AI scan the repository. I don&rsquo;t really like typing, and now that I can dictate, writing posts is much easier, so I don&rsquo;t need to say everything at once either. If I have new ideas later, I&rsquo;ll keep writing posts, and they&rsquo;ll be linked from the Release Notes or the user manual, to help users understand what all these commits every day are actually updating, and what I&rsquo;m thinking. If something is wrong or unclear, please let me know.</p>
]]></content:encoded></item><item><title>Building a Split-Tunneling Personal VPN Gateway: A Practical Setup with WireGuard, sing-box, and Gluetun</title><link>https://blog.bktus.com/en/archives/uqrk3i/</link><pubDate>Sat, 23 May 2026 00:35:00 +0200</pubDate><guid>https://blog.bktus.com/en/archives/uqrk3i/</guid><description>&lt;p>In a &lt;a href="https://blog.bktus.com/en/archives/qqyy2t/">previous post&lt;/a>, I introduced a fairly straightforward chained VPN setup: all devices first connect to a WireGuard server I host myself, the server forwards the traffic to Gluetun, and in the end the traffic reaches the Internet through the exit of an upstream VPN provider.&lt;/p>
&lt;p>The core value of this setup is pretty clear:&lt;/p>
&lt;ul>
&lt;li>All devices only need to set up one WireGuard connection.&lt;/li>
&lt;li>The upstream VPN only has to be maintained on the server.&lt;/li>
&lt;li>Phones, computers, tablets and home devices can all join the same virtual LAN.&lt;/li>
&lt;li>The exit IP comes from a commercial VPN, a company VPN or another upstream VPN, instead of exposing the VPS IP directly.&lt;/li>
&lt;li>The whole system can be deployed with Docker, so it keeps the host environment as clean as possible.&lt;/li>
&lt;li>Compared with connecting to a VPN directly, all the VPN provider can see in this setup is the exit of your VPN gateway (your VPS), not the real IP of each device.&lt;/li>
&lt;li>Also, your local ISP and others can’t tell whether you’re using a mainstream VPN. All they know is that you’re connecting to a VPN gateway (your VPS), but where the traffic finally goes is unknown to them.&lt;/li>
&lt;/ul>
&lt;p>But as I used it in more situations, the original structure started to show some limits. The most typical problem was that traffic control wasn’t fine-grained enough. By default, all traffic had to go into the upstream VPN tunnel, and for some services this could trigger risk-control mechanisms or cause access problems. It also wasn’t easy to do traffic engineering and use different exit strategies for different services. I could already do split routing with iptables and routing tables, but once there were a lot of rules, it got hard to maintain.&lt;/p></description><content:encoded><![CDATA[<p>In a <a href="https://blog.bktus.com/en/archives/qqyy2t/">previous post</a>, I introduced a fairly straightforward chained VPN setup: all devices first connect to a WireGuard server I host myself, the server forwards the traffic to Gluetun, and in the end the traffic reaches the Internet through the exit of an upstream VPN provider.</p>
<p>The core value of this setup is pretty clear:</p>
<ul>
<li>All devices only need to set up one WireGuard connection.</li>
<li>The upstream VPN only has to be maintained on the server.</li>
<li>Phones, computers, tablets and home devices can all join the same virtual LAN.</li>
<li>The exit IP comes from a commercial VPN, a company VPN or another upstream VPN, instead of exposing the VPS IP directly.</li>
<li>The whole system can be deployed with Docker, so it keeps the host environment as clean as possible.</li>
<li>Compared with connecting to a VPN directly, all the VPN provider can see in this setup is the exit of your VPN gateway (your VPS), not the real IP of each device.</li>
<li>Also, your local ISP and others can’t tell whether you’re using a mainstream VPN. All they know is that you’re connecting to a VPN gateway (your VPS), but where the traffic finally goes is unknown to them.</li>
</ul>
<p>But as I used it in more situations, the original structure started to show some limits. The most typical problem was that traffic control wasn’t fine-grained enough. By default, all traffic had to go into the upstream VPN tunnel, and for some services this could trigger risk-control mechanisms or cause access problems. It also wasn’t easy to do traffic engineering and use different exit strategies for different services. I could already do split routing with iptables and routing tables, but once there were a lot of rules, it got hard to maintain.</p>
<p>So I reorganized the original setup into a more complete personal VPN gateway architecture. The new version isn’t just a simple <code>WG-Easy + Gluetun</code> anymore. It has become:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>WG-Easy + sing-box + Gluetun + AdGuard Home + unified config generation from config.yaml
</span></span></code></pre></div><p>For me, this setup is no longer just “VPN over VPN”. It’s a personal network exit that I can maintain, extend and observe over the long term. It works for everyday browsing, and also for remote work, accessing my home network, development and testing, and managing many devices in one place. If you only need the simplest global VPN forwarding, the old approach is still good enough. But if you want a better balance between privacy, control, split routing rules and DNS management, the new architecture is a better fit.</p>
<p>In this post, I’ll go through the design ideas behind the new architecture, its traffic paths, the use cases it fits, and the main improvements over the old setup. If you’re interested in the new version, or just want to deploy it, you can go straight to <a href="https://github.com/saturneric/wg-easy-gluetun">my project repository on GitHub</a>.</p>
<h2 id="why-i-needed-a-new-architecture">Why I Needed a New Architecture</h2>
<p>The earliest chained VPN setup actually solved a lot of problems already. For example, at home, in the office or on any network outside, I could use the same WireGuard config to connect to the VPS, and then get into the upstream VPN through Gluetun on the VPS. This way, all devices share the same upstream VPN exit, and I don’t have to install, log in to and configure different VPN clients on every device over and over again.</p>
<p>In my daily use, this setup has been very stable, and the performance is good enough for what I need. There were basically no big problems. But after using it for a long time, I still ran into a few pain points.</p>
<h3 id="not-all-traffic-should-go-through-the-upstream-vpn">Not All Traffic Should Go Through the Upstream VPN</h3>
<p>In practice, I found that some services may trigger risk-control mechanisms because of the VPN exit, such as account logins, payments and AI services. For example, some streaming platforms I use a lot have strict restrictions on VPNs, and sometimes this traffic is better off going direct. Also, I sometimes need to access course servers inside the campus network, and sometimes that involves remote desktop, which needs fairly low latency. In these cases, going through a VPN gives a really poor experience, even when the exit is in the same country.</p>
<p>So I wanted finer-grained split routing. For example, I could use rule sets to let traffic for some services I trust bypass the upstream VPN and go to the Internet directly from the server. This keeps the privacy protection of the upstream VPN and also avoids some unnecessary access problems. Before, I relied more on iptables, routing tables and container networking. It worked, but once there were a lot of rules, it was hard to maintain.</p>
<p>After some research and testing, I found that sing-box’s TUN mode is a really good fit for this kind of rule-based split routing. It supports many rule types and flexible routing strategies, and it can decide the next hop for traffic based on the domain, the IP and other factors. By putting sing-box between WG-Easy and Gluetun, I can route traffic in a smarter way instead of using a simple global VPN. sing-box can also reference remote rule sets, such as geosite-openai and geosite-paypal, so I don’t need to maintain these rules myself. Another thing is that, compared with running an OpenWrt virtual machine, sing-box is lighter to deploy and maintain, and it’s more Docker-friendly.</p>
<p>This way, I can do traffic engineering much more flexibly. For example, default traffic should go through the VPN for privacy. Some services in a particular region I want to reach from a different VPN exit. Some services I want to access directly, and some I want to send through a specific VPN exit. With sing-box’s rule-based routing, these policies are much easier to set up.</p>
<h3 id="configuration-needs-to-be-managed-in-one-place">Configuration Needs to Be Managed in One Place</h3>
<p>In the original repository, the configuration was scattered across the conf directory, and changing things like subnets was already a bit inconvenient. After I added sing-box, maintaining Docker Compose, the WG-Easy hook, the sing-box JSON, the AdGuard Home config and the iptables rules all together became pretty painful. So in the new version, I use <code>config.yaml</code> as the single entry point for configuration, and generate the runtime files from templates.</p>
<p>After each config change, I just run the <code>up.sh</code> script and it brings all the related config files up to date. That way I no longer run into “changing this one and forgetting that one”.</p>
<h3 id="better-network-monitoring">Better Network Monitoring</h3>
<p>The original setup mainly relied on logs to see what was happening on the network. Sometimes I wanted to see which devices were connected to WireGuard right now, what services they were accessing, whether there was any unusual traffic, and so on. In the old setup, I had to read the logs inside the containers myself or install extra monitoring tools to get this information. In the new version, the API that sing-box provides works with tools like MetaCubeXD, so I can see traffic distribution, rule hits, upstream access and other information in real time. This makes the network much easier to observe.</p>
<p>So the goal of the new architecture isn’t just to “add one more VPN layer”. What I want is to build a controllable network exit that’s closer to something for home or personal use.</p>
<h2 id="components-of-the-new-setup">Components of the New Setup</h2>
<p>The new setup is mainly made up of four core containers.</p>
<h3 id="wg-easy-the-wireguard-access-layer">WG-Easy: The WireGuard Access Layer</h3>
<p>WG-Easy still handles the most basic and most important part: it provides the WireGuard server and a web management interface. All phones, computers, tablets and servers connect to WG-Easy as WireGuard clients. Users can create peers in the WG-Easy web UI, download config files, or scan a QR code to import the config on a phone.</p>
<p>In the new architecture, WG-Easy no longer just hands traffic straight to Gluetun. Instead, it uses a hook and policy routing to send client traffic into a more complex gateway path.</p>
<h3 id="adguard-home-unified-dns-and-filtering-layer">AdGuard Home: Unified DNS and Filtering Layer</h3>
<p>AdGuard Home takes care of DNS resolution, ad filtering, blocking tracking domains and logging DNS queries.</p>
<p>In the new architecture, regular DNS requests from WireGuard clients are restricted to AdGuard Home. In other words, clients can’t just send DNS queries to <code>8.8.8.8</code>, <code>1.1.1.1</code> or other external DNS servers.</p>
<p>The benefits of this are:</p>
<ul>
<li>Upstream DNS can be set in one place.</li>
<li>Filter lists can be managed together.</li>
<li>Client DNS queries can be viewed.</li>
<li>The risk of DNS leaks is lower.</li>
<li>There’s no need to set up filtering software on each device separately.</li>
</ul>
<p>Of course, this doesn’t mean it can fully stop every form of DNS bypass. For example, DoH, DoT or the built-in resolvers in some apps still need extra policies. But for regular DNS requests on UDP/TCP port 53, the gateway can bring them all through one place.</p>
<h3 id="sing-box-the-rule-based-routing-layer">sing-box: The Rule-Based Routing Layer</h3>
<p>sing-box is the most important change in the new architecture.</p>
<p>It receives the traffic forwarded from WG-Easy through a TUN inbound, and then decides the next hop based on rules:</p>
<ul>
<li>Traffic that matches <code>bypass_rule_sets</code> goes out directly.</li>
<li>Private IP traffic goes out directly, so it isn’t sent into the upstream VPN by mistake.</li>
<li>Other default traffic gets a routing mark and is handed to Linux policy routing, which then sends it into Gluetun.</li>
<li>Rule sets can use remote <code>.srs</code> files, such as geosite-openai and geosite-paypal.</li>
</ul>
<p>If you look at the sing-box config file, you’ll notice something a bit strange: the <code>gluetun</code> outbound in sing-box is also of type <code>direct</code>, but it carries a <code>routing_mark</code>. Actually, this mark gets picked up by Linux policy routing, which sends the traffic to Gluetun. So it isn’t “direct” in the usual sense. It’s really “sent to Gluetun through the system’s routing”.</p>
<p>Basically, sing-box works more like a smart traffic splitter here, and Gluetun is the final upstream VPN exit. Besides going through Gluetun, sing-box itself can also be set up in a similar way with other types of outbound, such as WireGuard, VLESS and Trojan, to work with a wider range of upstream services. If you don’t need the various conveniences Gluetun provides, you could even replace it right here with another VPN client or a direct Internet exit.</p>
<p>One thing to note is that sing-box can’t get the domain information here, so we need to turn on sniffing to identify the domain. Only then can it do split routing based on domain rule sets. For protocols or encrypted traffic that sniffing doesn’t support, it may only be able to split traffic based on IP rules.</p>
<h3 id="gluetun-the-upstream-vpn-exit-layer">Gluetun: The Upstream VPN Exit Layer</h3>
<p>Gluetun is responsible for connecting to a commercial VPN, a company VPN or another supported upstream VPN service.</p>
<p>Its strength is that it supports a lot of VPN providers, and it packs the OpenVPN / WireGuard clients, authentication parameters, firewall rules, health checks and other logic into one container.</p>
<p>In the new architecture, most default traffic ends up in Gluetun, and Gluetun then reaches the Internet through the upstream VPN tunnel. This way, clients see their own WireGuard network, while the Internet sees the exit IP of the upstream VPN.</p>
<h2 id="overall-network-topology">Overall Network Topology</h2>
<p>You can think of the new architecture as the following path:</p>
<pre class="mermaid">
  flowchart TD
  subgraph devices[&#34;Your Devices&#34;]
    phone[&#34;Phone&#34;]
    pc[&#34;PC&#34;]
    laptop[&#34;Laptop&#34;]
  end

  subgraph server[&#34;Your Server&#34;]
    wgeasy[&#34;WG-Easy (WireGuard Server)&#34;]
    adguard[&#34;AdGuard Home (DNS Filtering)&#34;]
    singbox[&#34;sing-box (TUN Router / Rule Engine)&#34;]
    gluetun[&#34;Gluetun (VPN Provider Client)&#34;]
  end

  phone -- WireGuard --&gt; wgeasy
  pc -- WireGuard --&gt; wgeasy
  laptop -- WireGuard --&gt; wgeasy

  wgeasy -- DNS only --&gt; adguard
  wgeasy -- regular traffic --&gt; singbox
  singbox -- bypass_rule_sets --&gt; direct[&#34;Direct Internet&#34;]
  singbox -- default route --&gt; gluetun
  gluetun -- VPN tunnel --&gt; provider[&#34;VPN Provider&#34;]
  provider --&gt; internet[&#34;Internet&#34;]
  direct --&gt; internet
</pre>
<p>From the traffic point of view, it can be split into three types:</p>
<ol>
<li><strong>DNS traffic</strong>: DNS requests from WireGuard clients are always forwarded to AdGuard Home.</li>
<li><strong>Traffic that matches bypass rules</strong>: for example, OpenAI, PayPal or other rule sets you put into <code>bypass_rule_sets</code> can go direct.</li>
<li><strong>Default traffic</strong>: regular Internet traffic that doesn’t match any bypass rule goes into Gluetun, and then reaches the Internet through the upstream VPN exit.</li>
</ol>
<p>Also, you can configure <code>direct_subnets</code> to let specific subnets bypass sing-box. This is useful for clear-cut internal network access, such as reaching your home LAN, a specific Docker network or some dedicated subnets.</p>
<h2 id="configuration-management-from-hand-written-configs-to-generated-configs">Configuration Management: From Hand-Written Configs to Generated Configs</h2>
<p>Another important change in the new setup is how configuration is managed.</p>
<p>Before, you might have had to change all of these at the same time:</p>
<ul>
<li><code>docker-compose.yml</code></li>
<li>WireGuard hook</li>
<li>iptables rules</li>
<li>Gluetun environment variables</li>
<li>DNS config</li>
<li>sing-box JSON</li>
<li>AdGuard Home config</li>
</ul>
<p>This is flexible, but it’s expensive to maintain. Especially after even a small change to the network structure, it’s easy to end up “changing it in one place and forgetting the other”. The new setup puts the main configuration in <a href="https://github.com/saturneric/wg-easy-gluetun/blob/master/config.yaml"><code>config.yaml</code></a>, and then a generator script renders it into the actual config files under runtime/.</p>
<p>So regular users only need to edit <code>config.yaml</code>. Advanced users who want to adjust more settings can edit the Jinja2 templates under <code>templates/</code>. This keeps the configuration in one place and still leaves enough flexibility.</p>
<p>One thing to note: I suggest not editing the files under the <code>runtime/</code> directory directly. They’re generated, and they get overwritten every time it runs again.</p>
<h2 id="how-the-sing-box-split-routing-rules-work">How the sing-box Split Routing Rules Work</h2>
<p>In the new setup, the sing-box rules roughly look like this:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;route&#34;</span>: {
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">&#34;rules&#34;</span>: [
</span></span><span style="display:flex;"><span>      { <span style="color:#f92672">&#34;inbound&#34;</span>: <span style="color:#e6db74">&#34;tun-in&#34;</span>, <span style="color:#f92672">&#34;action&#34;</span>: <span style="color:#e6db74">&#34;sniff&#34;</span> },
</span></span><span style="display:flex;"><span>      { <span style="color:#f92672">&#34;ip_is_private&#34;</span>: <span style="color:#66d9ef">true</span>, <span style="color:#f92672">&#34;outbound&#34;</span>: <span style="color:#e6db74">&#34;direct&#34;</span> },
</span></span><span style="display:flex;"><span>      {
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">&#34;rule_set&#34;</span>: [<span style="color:#e6db74">&#34;geosite-openai&#34;</span>, <span style="color:#e6db74">&#34;geosite-paypal&#34;</span>],
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">&#34;outbound&#34;</span>: <span style="color:#e6db74">&#34;direct&#34;</span>
</span></span><span style="display:flex;"><span>      },
</span></span><span style="display:flex;"><span>      { <span style="color:#f92672">&#34;outbound&#34;</span>: <span style="color:#e6db74">&#34;gluetun&#34;</span> }
</span></span><span style="display:flex;"><span>    ]
</span></span><span style="display:flex;"><span>  }
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><p>This means:</p>
<ol>
<li>First, sniff the traffic to identify the domain and other information.</li>
<li>Private IP addresses go direct.</li>
<li>Traffic that matches the rule sets goes direct.</li>
<li>All other traffic goes to the <code>gluetun</code> outbound.</li>
</ol>
<p><code>bypass_rule_sets</code> means “bypass the upstream VPN”, not “bypass your server”.</p>
<p>For example, if you configure:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">singbox</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">bypass_rule_sets</span>:
</span></span><span style="display:flex;"><span>    - <span style="color:#f92672">tag</span>: <span style="color:#e6db74">&#34;geosite-openai&#34;</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">url</span>: <span style="color:#e6db74">&#34;https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-openai.srs&#34;</span>
</span></span><span style="display:flex;"><span>    - <span style="color:#f92672">tag</span>: <span style="color:#e6db74">&#34;geosite-paypal&#34;</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">url</span>: <span style="color:#e6db74">&#34;https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-paypal.srs&#34;</span>
</span></span></code></pre></div><p>then the traffic for these services still goes through your WireGuard server and sing-box. It just doesn’t go into Gluetun’s upstream VPN tunnel anymore, and the server reaches the Internet directly instead.</p>
<p>This really helps with services that are sensitive to VPN exits. For example, some services ask for extra verification when they see a commercial VPN IP, or even refuse access outright. Bypassing the upstream VPN with rules can cut down on this kind of problem.</p>
<h2 id="what-is-extra_rule_sets">What Is extra_rule_sets</h2>
<p>The new config also has an <code>extra_rule_sets</code> option:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">singbox</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">extra_rule_sets</span>:
</span></span><span style="display:flex;"><span>    - <span style="color:#f92672">tag</span>: <span style="color:#e6db74">&#34;geosite-google&#34;</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">url</span>: <span style="color:#e6db74">&#34;https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-google.srs&#34;</span>
</span></span><span style="display:flex;"><span>    - <span style="color:#f92672">tag</span>: <span style="color:#e6db74">&#34;geosite-apple&#34;</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">url</span>: <span style="color:#e6db74">&#34;https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-apple.srs&#34;</span>
</span></span></code></pre></div><p>What it does is download and cache these rule sets, but they don’t take part in the current route matching. That is, <code>extra_rule_sets</code> doesn’t change the traffic path. A rule only really takes effect when it’s put into <code>bypass_rule_sets</code> or explicitly referenced in the sing-box template.</p>
<p>I kept this option to make future extensions easier. For example, I might want to get rule sets for Google, Apple, Amazon and others ready in advance, without turning them on right away. When I need them, I only have to move the rule into <code>bypass_rule_sets</code> or add a new route rule.</p>
<p>If you want the simplest possible config, you can also set <code>extra_rule_sets</code> to an empty array:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">singbox</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">extra_rule_sets</span>: []
</span></span></code></pre></div><p>Note that in YAML, it’s better to write an explicit empty array rather than just an empty key:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#75715e"># Recommended</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">extra_rule_sets</span>: []
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Not recommended, it can easily be parsed as null</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">extra_rule_sets</span>:
</span></span></code></pre></div><h2 id="dns-why-adguard-home-is-included-by-default">DNS: Why AdGuard Home Is Included by Default</h2>
<p>In a VPN gateway, DNS is something that’s easy to overlook. If you only handle regular traffic and ignore DNS, you might end up with this:</p>
<ul>
<li>Browser traffic goes through your VPN gateway.</li>
<li>But DNS queries go to the local network, your ISP’s DNS or some public DNS.</li>
<li>In the end, this causes DNS leaks, or makes the split routing decisions inaccurate.</li>
</ul>
<p>In the new architecture, regular DNS requests from WireGuard clients are restricted to AdGuard Home. This way, you can manage DNS in one place on the gateway.</p>
<p>AdGuard Home brings a few benefits:</p>
<ul>
<li>Filtering of ads and tracking domains</li>
<li>Custom upstream DNS</li>
<li>Query logs</li>
<li>Local domain rewrites</li>
<li>Different policies for different clients</li>
</ul>
<p>But keep in mind that if you want to block every DNS bypass completely, you also need to think about DoH, DoT, QUIC and so on. The DNS restriction in this post mainly targets traditional queries on UDP/TCP port 53.</p>
<h2 id="use-cases">Use Cases</h2>
<p>The new architecture covers more scenarios than the old one. All things considered, it mainly fits the following situations:</p>
<h3 id="1-sharing-one-upstream-vpn-across-many-devices">1. Sharing One Upstream VPN Across Many Devices</h3>
<p>This is the most basic way to use it.</p>
<p>You only configure the upstream VPN once on the server, and all devices connect through WireGuard. Phones, computers, tablets and spare devices don’t each need their own upstream VPN client.</p>
<p>This is especially useful when you have a lot of devices, a mix of platforms, or an upstream VPN client that isn’t very good.</p>
<h3 id="2-remote-access-to-a-home-or-office-network">2. Remote Access to a Home or Office Network</h3>
<p>Once all devices join the same WireGuard network, they form one virtual LAN.</p>
<p>You can use it to access:</p>
<ul>
<li>the NAS at home</li>
<li>internal services at the office</li>
<li>a private Git service</li>
<li>a home media server</li>
<li>SSH management access</li>
</ul>
<p>Together with <code>direct_subnets</code>, you can also let some internal network access skip the more complex sing-box routing logic.</p>
<h3 id="3-different-exit-strategies-for-different-services">3. Different Exit Strategies for Different Services</h3>
<p>Some services work well with a commercial VPN, and some don’t.</p>
<p>For example:</p>
<ul>
<li>Default traffic goes through the Gluetun upstream VPN.</li>
<li>Sensitive services like OpenAI and PayPal go direct.</li>
<li>Torrent and P2P traffic goes through Gluetun or another dedicated VPN exit.</li>
<li>Private IPs and internal addresses don’t go into the upstream VPN.</li>
<li>Specific rule sets are downloaded in advance but not turned on yet.</li>
</ul>
<p>This structure is more flexible than the old “global proxy” approach, and easier to maintain than hand-written iptables rules.</p>
<h3 id="5-low-intrusion-deployment">5. Low-Intrusion Deployment</h3>
<p>The whole setup is based on Docker Compose. The host only needs Docker and Docker Compose installed, and most of the networking logic lives in the containers and the generated config. This makes it pretty friendly to VPSes, home servers, software routers and Raspberry Pis.</p>
<h2 id="deployment-overview">Deployment Overview</h2>
<p>The actual deployment roughly goes like this:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>git clone https://github.com/saturneric/wg-easy-gluetun.git
</span></span><span style="display:flex;"><span>cd wg-easy-gluetun
</span></span></code></pre></div><p>Then edit:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>vim config.yaml
</span></span></code></pre></div><p>At minimum, you need to configure:</p>
<ul>
<li>the WireGuard / OpenVPN parameters for the upstream VPN</li>
<li>the WG-Easy admin password</li>
<li>the server’s public address or domain name</li>
<li>the upstream DNS for AdGuard Home</li>
<li>the sing-box bypass rules</li>
<li>the necessary service ports and fixed container IPs</li>
</ul>
<p>To start it, use:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>./up.sh -d
</span></span></code></pre></div><p>Don’t just run a plain <code>docker compose up</code>, because the runtime compose file and the related config have to be created by the generator first. <code>up.sh</code> runs the config generation first and then starts the full stack.</p>
<h2 id="security-notes">Security Notes</h2>
<p>This kind of gateway setup is convenient, but you also need to pay attention to its security boundaries.</p>
<h3 id="1-dont-use-the-default-passwords">1. Don’t Use the Default Passwords</h3>
<p>The WG-Easy password, the Clash API secret and the AdGuard Home credentials in <code>config.yaml</code> should all be changed. Especially if a management interface is exposed to the public internet, default passwords are very dangerous.</p>
<h3 id="2-be-careful-about-exposing-management-ports">2. Be Careful About Exposing Management Ports</h3>
<p>Usually, only the WireGuard UDP port should be public. It’s best not to expose the WG-Easy, MetaCubeXD or AdGuard Home management interfaces directly to the public internet.</p>
<h3 id="3-check-your-upstream-vpns-terms-of-service">3. Check Your Upstream VPN’s Terms of Service</h3>
<p>Whether sharing across devices, forwarding through a gateway and chained VPNs are allowed depends on your upstream VPN’s terms of service. You should check this yourself before deploying.</p>
<h3 id="4-watch-out-for-dns-bypass">4. Watch Out for DNS Bypass</h3>
<p>This setup restricts regular DNS queries, but it can’t automatically block all DoH / DoT at the application level. If you need a stricter DNS policy, you’ll need extra controls based on domains, IPs, SNI or the application layer.</p>
<h2 id="summary-main-changes-from-the-old-setup">Summary: Main Changes from the Old Setup</h2>
<p>Compared with the old <code>WG-Easy + Gluetun</code>, the new architecture mainly changes these things:</p>
<table>
  <thead>
      <tr>
          <th>Aspect</th>
          <th>Old</th>
          <th>New</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Access layer</td>
          <td>WG-Easy</td>
          <td>WG-Easy</td>
      </tr>
      <tr>
          <td>Upstream VPN</td>
          <td>Gluetun</td>
          <td>Gluetun</td>
      </tr>
      <tr>
          <td>Split routing</td>
          <td>Mainly routing and iptables</td>
          <td>Rule-set split routing with sing-box</td>
      </tr>
      <tr>
          <td>DNS</td>
          <td>Needs extra configuration</td>
          <td>AdGuard Home built in by default</td>
      </tr>
      <tr>
          <td>Configuration</td>
          <td>Multiple files maintained by hand</td>
          <td><code>config.yaml</code> + template generation</td>
      </tr>
      <tr>
          <td>Rule management</td>
          <td>Coarse-grained</td>
          <td>geosite / rule-set level</td>
      </tr>
      <tr>
          <td>Observability</td>
          <td>Mainly logs</td>
          <td>sing-box can be viewed with MetaCubeXD</td>
      </tr>
      <tr>
          <td>Extensibility</td>
          <td>Fairly limited</td>
          <td>Better suited to adding more rules and services later</td>
      </tr>
  </tbody>
</table>
<p>So, to sum up, the old version is simpler and suits users who just want to send all their traffic into the upstream VPN. The new version is better for long-term use, especially if you need split routing, DNS filtering, centralized management and support for many different scenarios.</p>
]]></content:encoded></item><item><title>Long-Term Personal VPS Self-Hosting: Cleanliness and Security</title><link>https://blog.bktus.com/en/archives/vgjftw/</link><pubDate>Sat, 03 Jan 2026 00:36:04 +0100</pubDate><guid>https://blog.bktus.com/en/archives/vgjftw/</guid><description>&lt;p>I’ve been seriously tinkering with personal self-hosting for about five or six years now. Strictly speaking, the time I started managing my own VPS goes back even further. The original motivation was actually pretty simple: there were some services I used every day, like a password manager, music playback, note syncing, a personal website, code repositories and so on. So why not just deploy them myself? That way the data stays in my own hands, and I’m not pushed around by all kinds of platform subscriptions and price increases.&lt;/p></description><content:encoded><![CDATA[<p>I’ve been seriously tinkering with personal self-hosting for about five or six years now. Strictly speaking, the time I started managing my own VPS goes back even further. The original motivation was actually pretty simple: there were some services I used every day, like a password manager, music playback, note syncing, a personal website, code repositories and so on. So why not just deploy them myself? That way the data stays in my own hands, and I’m not pushed around by all kinds of platform subscriptions and price increases.</p>
<p>Looking back on these years, to be honest, self-hosting isn’t hassle-free. I have to maintain the system, back up data, keep an eye on security, and once in a while put out fires. But what I get back is also very clear:</p>
<ul>
<li>My data is fully under my own control</li>
<li>I’m no longer pushed around by subscription prices</li>
<li>I understand systems, networking and security a lot better</li>
</ul>
<p>Now I run a dozen or so services on one server, and the cost is just the price of that one server. After canceling quite a few third-party subscriptions over the past two years, the overall cost may actually be lower when I do the math. For me, this “complex but under control” state feels more reassuring than depending on a pile of external services. Of course, this isn’t for everyone. I feel it suits people who have some technical background, enjoy tinkering, and are willing to put in time for stability and control. When all three come together in one person, this kind of setup fits.</p>
<p>Even now, I don’t think I’ve become any kind of “expert,” but my feelings about two things have grown stronger and stronger: <strong>security</strong> and <strong>how clean the server environment is</strong>. These are also the two main threads of this post. These two questions pretty much decide whether the services on your server can keep running stably over the long term. They also decide how much work it is when you need to migrate, for example when you switch to a cheaper or better VPS provider. (I’ve switched several times myself, and only settled down once I really couldn’t face moving again.)</p>
<h2 id="the-rough-early-days">The Rough Early Days</h2>
<p>In the beginning, my approach was very basic. I installed services directly on the host, and then installed Nginx or Apache2 (httpd). For example, I used Nginx as a reverse proxy. The good thing about web servers like Nginx is that the config files can be split up, one per site, and services are told apart by domain name instead of port number, so everything looks neat and tidy. Back then I thought this setup was pretty elegant.</p>
<p>But as the number of services slowly grew, problems started to show up one by one. Some services needed specific versions of dependencies, and it was hard for me to install different versions of various libraries or databases in the same environment. Some left all kinds of temporary files in the system. Config files were scattered under <code>/etc</code>, data was in <code>/srv</code>, and logs were in <code>/var</code>. At first you could still remember “this belongs to that service,” but after a while it all got mixed up.</p>
<p>During this time, when I wanted to remove a service I no longer used, I wasn’t even sure I could remove it cleanly. This was especially true for services that come with a “one-click install script.” Installing them feels great at the time, but when you want to get rid of them, you find you have no idea what changes the script made back then, or how to undo them. It’s hard to know whether there are leftover configs or background processes, and you don’t even know whether deleting the wrong thing will break other services. This uncertainty is a risk in itself. For someone with a bit of a cleanliness obsession like me, it was deeply uncomfortable every time I thought about it.</p>
<h2 id="the-containerization-phase">The Containerization Phase</h2>
<p>Later I moved almost all of my services into Docker. And these days I lean more and more toward containerizing every service or tool I use before deploying it. For services I really want to use but that don’t offer a standard containerized deployment, I just package them into containers myself and make my own containerized solution.</p>
<p>What really changed the experience wasn’t Docker itself, but <strong>Docker Compose</strong>. Containers basically shouldn’t be treated as “things to maintain long-term.” They can be deleted and rebuilt at any time, and you need to be aware of that. Early on, I thought Docker Compose files were a hassle. Why not just create a container with a command and let it run for a long time? Later, when I needed to update it, or when the service depended on several other containers underneath, the problems slowly showed up. If I had written the deployment down in a config file from the start, I could just run that file every time and reproduce the original deployment perfectly. I wouldn’t need to set up a bridge network, a hostname or a restart policy by hand. This saves a lot of time and energy, and the chance of making mistakes during configuration also goes way down.</p>
<p>Looking back now, I can say there are only three things that really need long-term maintenance:</p>
<ul>
<li>Service configuration (including version, network, storage and so on)</li>
<li>Data (mainly volumes and other mapped directories)</li>
<li>Deployment configuration (the various Docker Compose YAML files)</li>
</ul>
<p>Whether I reinstall the system or switch to another machine, as long as these three are still there, the services can be cloned perfectly to the new place. And the host itself finally became “clean.” Its directories are no longer full of things you installed years ago and have since forgotten the purpose of. So at this stage, I created a separate Git repository to collect and manage the Docker Compose files for all the services I use. After a year with it, I feel this approach holds up in all kinds of situations.</p>
<h2 id="one-service-one-database">One Service, One Database</h2>
<p>This one is worth mentioning. For a long time, all of my services shared one database instance. Logically it looks very reasonable: it saves resources, the structure is simple, and management is centralized. But after maintaining it for a long time, you’ll find this is actually a <strong>very unfriendly design</strong>.</p>
<p>Every new service means another set of users, permissions and passwords. If you want to migrate a service, you have to carefully pull its database out. Once the database version is upgraded, every service has to share the risk. For people who aren’t familiar with a certain database, managing permissions and users is a headache. You have to use the command line or some database management tool to carefully keep each service’s users apart and keep their passwords safe.</p>
<p>Later I just did the opposite: <strong>each service gets its own database instance.</strong> That means each Docker Compose file has its own database service. After watching this for a long time, I found that for personal self-hosting, it’s not as “wasteful” as you might think. A database container usually only takes 100 or 200 MB of memory. On a VPS with 4 cores and 8 GB of RAM, or even 2 cores and 4 GB, or on a home server, that’s acceptable.</p>
<p>But what I get in return is very real. The services are fully isolated from each other, which improves security a lot, and I no longer have endless friction with permissions and compatibility. I can just pack up all the data and config in one go and take it with me, and each database only holds the data of its own service.</p>
<h2 id="the-principle-of-minimal-exposure">The Principle of Minimal Exposure</h2>
<p>Early on, I exposed almost all of my services directly to the public internet, and protected them with a reverse proxy plus login:</p>
<ul>
<li>One Nginx Proxy Manager</li>
<li>A public domain for every service</li>
<li>Username/password protection at the application layer</li>
</ul>
<p>Back then I also thought: “Every service has a username and password, so it should be fine, right?” Only later did I slowly realize that this was just fooling myself. As long as <strong>one service</strong> has a brute-force weakness, an authentication bypass or an RCE (remote code execution) vulnerability, an attacker may get access to the container or even the host. What first happened to me was with a GitLab instance I ran without a container. GitLab once had a serious remote code execution vulnerability, and I didn’t find out about it in time. Then one day I found that a trojan had been planted on my server, and I only knew because my cloud provider told me. If I had kept photos, videos or backups on that server back then, the result would have been a disaster.</p>
<p>Also, the security maturity of different services varies a lot, and their tech stacks vary widely. Some projects are still young, and their security thinking is far from mature. And I can’t watch every security advisory every day. Once one of these services has a vulnerability, or the frameworks or dependencies they use do, like the recent security vulnerabilities around the React stack, that service or those services can blow up in a short time. If containerization and isolation aren’t done well at that point, the attacker may get more than that one service. Quite possibly they get the whole machine. And then come the hidden trojan scripts or crypto-mining scripts.</p>
<p>This is also a core principle I came to later: if a service doesn’t have to be open to the public internet, don’t open it. Blogs and static pages don’t lose much if they get attacked, but things like notes, password managers and admin panels are a disaster if something goes wrong. So you need to take a good look at which services you’re exposing right now. From my own experience, the ones I feel safest about are static websites, or pages that are only generated from parameters with no database behind them. But there are a lot of services I want to use, so how do I expose some and not others? My current practice is to expose only the services that really need it to the public internet, like a static blog and a very small number of public services. Git repositories are kept private as much as possible, or only expose a read-only static view (through gitweb or cgit). Dynamic services, admin panels, notes, password managers and so on are never exposed directly to the public internet.</p>
<h3 id="deploying-a-private-vpn">Deploying a Private VPN</h3>
<p>Later I found that the key to solving this problem is a VPN. I deployed a private VPN on the server (WireGuard, for example) and put all private services into <strong>a network that can only be reached from the internal network</strong>. Only after I connect to the VPN and get a virtual internal IP can I reach these services, starting from that internal IP. The overall idea is:</p>
<ul>
<li>The VPN provides a virtual private subnet (like <code>10.8.x.x</code>)</li>
<li>Docker internal services use another private subnet (like <code>172.x.x.x</code>)</li>
<li>The two subnets can reach each other through routing</li>
<li>The public internet can’t reach these services directly</li>
</ul>
<p>What this step means is that I no longer need to design a separate “defense plan” for each service, because they’re not on the attack surface at all. Add a reverse proxy and DNS that only work inside the internal network, and the experience is actually better than on the public internet: clear domain names, stable services, and real peace of mind.</p>
<h3 id="internal-reverse-proxy-and-dns-resolution">Internal Reverse Proxy and DNS Resolution</h3>
<p>To improve the experience further, I deployed an internal Nginx container inside the internal network (under 172.24.0.0/16), completely isolated from the Nginx instance that serves the public (for example, 172.20.0.0/16). This internal Nginx instance is bound to a fixed private IP (for example, 172.24.0.2), and it only serves traffic that comes in through the VPN network.</p>
<pre class="mermaid">
  flowchart LR
  %% Clients
  PUB[&#34;Public Internet User&#34;] --&gt;|&#34;HTTPS&#34;| PNGX[&#34;Public Nginx (*.example.com)&#34;]
  PNGX --&gt; PBLOG[&#34;Public Service (e.g., blog/static)&#34;]

  %% VPN access
  DEV[&#34;Your Device\n(WireGuard Client)&#34;] --&gt;|&#34;VPN Tunnel&#34;| WG[&#34;WireGuard Server (10.8.0.0/24)&#34;]

  %% Internal name + reverse proxy (VPN-only)
  WG --&gt;|&#34;DNS&#34;| DNS[&#34;Internal DNS (172.24.0.4)&#34;]
  WG --&gt;|&#34;HTTPS&#34;| INGX[&#34;Internal Nginx (172.24.0.2)&#34;]

  %% Private services
  subgraph DOCKER[&#34;Docker Private Networks&#34;]
    INGX --&gt; VAULT[&#34;Vaultwarden&#34;]
    INGX --&gt; NOTES[&#34;Notes / Joplin&#34;]
    INGX --&gt; GIT[&#34;Git Service&#34;]
  end
</pre>
<p>Then I added a mandatory internal DNS service. All traffic coming in through the VPN can only use this DNS for name resolution. There are many mature options for this in practice, like AdGuard Home, which can also take care of ad blocking and DNS hijacking at the same time. Besides resolving the normal network traffic that passes through, this DNS service also specifically handles all DNS resolution under *.vpn.example.com, for example:</p>
<ul>
<li><code>git.vpn.example.com</code></li>
<li><code>notes.vpn.example.com</code></li>
<li><code>vault.vpn.example.com</code></li>
</ul>
<p>All of these resolve to the IP the internal Nginx listens on, 172.24.0.2. So when the VPN is connected, I can just type the domain name into the browser and get straight to the internal service. All the traffic stays inside the internal network. It’s best if this domain is registered under your own name. Then, in your external DNS settings, set *.vpn.example.com to NXDOMAIN or your VPS’s IP address. That way, if you accidentally try to reach an internal service without going through the VPN, the traffic won’t get forwarded somewhere else by mistake.</p>
<h3 id="isolating-database-containers">Isolating Database Containers</h3>
<p>A database shouldn’t be on the same Docker network as unrelated services. So I did one more thing: each service and its database get their own isolated bridge. On this bridge, only these two containers can talk to each other, and the bridge isn’t connected to any external network. In other words, even if a service gets compromised, the only thing it can reach is its own database, not every database on the server. Like this:</p>
<pre tabindex="0"><code>services:
  db:
    image: postgres:16-alpine
    ...
    networks:
      - iso
    restart: unless-stopped

  joplin:
    image: git.stdv.de/saturneric/joplin:latest
    ...
    depends_on:
      - db
    networks:
      - iso
      - vpn
    restart: unless-stopped
networks:
  iso:
    internal: true
  vpn:
    external: true
</code></pre><p>You can see that db only talks one-to-one with joplin on the iso network, and this network blocks direct access from inside it to the outside network (internal: true). So if another service gets compromised, it generally can’t reach my joplin database over the network. But this isn’t “absolutely secure.” It always assumes the attacker hasn’t got access to the host. Still, in the real world, <strong>reducing the chance of lateral movement</strong> is a really important layer of protection in itself.</p>
<p>This actually also helps avoid hostname / database name conflicts. When a lot of databases on the same network use the same hostname, some services may end up connecting to the wrong database now and then.</p>
<h2 id="firewall-strategy">Firewall Strategy</h2>
<p>If you’re using a VPS, my suggestion is to use the firewall from your cloud provider first, and keep host firewall rules to a minimum. For the external firewall, limit the inbound ports you allow as strictly as you can, and reach your services through domain names and the reverse proxy. There are a few reasons. Two layers of firewall get confusing very easily, and it’s easy to forget which one you configured and which one you didn’t. I also found that Docker port mapping sometimes bypasses the local firewall, which can expose internal service ports by accident, and a lot of the time I didn’t even notice. And the cloud firewall can block large-scale scanning traffic early, which moves that compute cost onto the cloud provider.</p>
<p>Usually the cloud firewall only allows these inbound ports:</p>
<ul>
<li>80 / 443</li>
<li>The VPN port</li>
<li>SSH</li>
<li>Other ports you think really need to be open</li>
</ul>
<p>Even if other ports are listening on the host, they’re invisible from the outside as long as the cloud firewall doesn’t allow them. You can only reach them through the VPN, which saves a lot of worry.</p>
<h2 id="ssh-security">SSH Security</h2>
<p>There are lots of other great articles on this topic, so I’ll just cover some very basic but really important points. These are also things I still do all the time:</p>
<ul>
<li>Disable SSH login for root. If you need root, use a normal user plus sudo.</li>
<li>Don’t make the normal user’s SSH username too easy to guess, like admin.</li>
<li>Give the normal user a long random password (I suggest generating it with a password manager), and use <strong>key-based login</strong> by default day to day.</li>
<li>Optional: only allow key-based login for the normal user and disable passwords. (Be careful about the case where the key isn’t backed up and then you lose the device.)</li>
</ul>
<p>A lot of people suggest changing the SSH port. On whether to change it in a personal environment, here’s my own view:</p>
<ul>
<li>In a personal environment, the security benefit is limited</li>
<li>Some configuration later on gets more complicated</li>
<li>In the end it depends on your own habits</li>
</ul>
<h2 id="afterword">Afterword</h2>
<p>Actually, I’ve now moved to a dedicated server instead of a VPS, which is like renting a physical server in a data center that you can actually see. That’s because I now need to host dozens of containers (I went through them all, and I need every one of them). I think this shows that self-hosting really has become technical infrastructure I can’t do without day to day. It also shows that I think spending more money on it every month is really worth it.</p>
<p>Also, I should point out that in some places, the setup in this post, where one private VPN carries both your internal service traffic and your normal browsing traffic, is hard to pull off. For example, the server’s uplink bandwidth may be very expensive there, or the traffic may be metered. In that case, my suggestion is to do split routing ahead of time on the software router at home: separate out the self-hosting traffic first, and let normal browsing traffic go out through your home connection.</p>
<p>One more thing. Even if your server has enough uplink bandwidth to support a private VPN, a lot of the time you probably don’t want to browse the web with your VPS’s IP, because that directly exposes your identity. A better option is to send the traffic on to a VPN server from another VPN provider, and then go out through the exit IP it provides. I have a mature solution for this that I’ve been using myself for a long time. You can check out my blog post: <a href="https://blog.bktus.com/en/archives/qqyy2t/">Building a Personal Chained VPN Network: Efficient Privacy Protection, Unlimited Device Management, and Remote Access</a>.</p>
]]></content:encoded></item><item><title>The Past and Present of GpgFrontend: My Journey with an Open-Source Encryption Tool</title><link>https://blog.bktus.com/en/archives/u8hywl/</link><pubDate>Wed, 12 Nov 2025 23:24:37 +0100</pubDate><guid>https://blog.bktus.com/en/archives/u8hywl/</guid><description>&lt;h2 id="how-it-started-running-into-gnupg-gpg">How It Started: Running into GnuPG (GPG)&lt;/h2>
&lt;p>I first came across GPG around April 2021. Back then I was just a student who was curious about everything in the computer world, and my understanding of cryptography didn&amp;rsquo;t go much further than “a password is an encrypted string”. Then I read about how asymmetric encryption works: anyone can use a public key to encrypt a message, but only the person who holds the private key can decrypt it. That really amazed me. I liked this kind of “mathematical trust”. It&amp;rsquo;s elegant, rigorous and irreversible, and at that moment I felt it was just as beautiful as any piece of art. So I started learning the GPG command line, from generating keys to verifying signatures, trying things again and again to understand the logic behind them.&lt;/p></description><content:encoded><![CDATA[<h2 id="how-it-started-running-into-gnupg-gpg">How It Started: Running into GnuPG (GPG)</h2>
<p>I first came across GPG around April 2021. Back then I was just a student who was curious about everything in the computer world, and my understanding of cryptography didn&rsquo;t go much further than “a password is an encrypted string”. Then I read about how asymmetric encryption works: anyone can use a public key to encrypt a message, but only the person who holds the private key can decrypt it. That really amazed me. I liked this kind of “mathematical trust”. It&rsquo;s elegant, rigorous and irreversible, and at that moment I felt it was just as beautiful as any piece of art. So I started learning the GPG command line, from generating keys to verifying signatures, trying things again and again to understand the logic behind them.</p>
<p>But I also found a problem: the command line is really hard to get into. Sometimes I just wanted to do something simple quickly, and I still had to type a long string of commands, which honestly annoyed me. For non-technical users, the GPG command line is like an obscure wasteland, and it stops almost everyone who wants to try it. So I started thinking: what if GPG had a simple, easy-to-use graphical interface, so it felt like a crypto machine you can actually see and touch? If everyone could easily have a small, durable “crypto machine”, maybe more people would be willing to try it. At the time this idea seemed pretty small, but it was what started the next several years of my technical work.</p>
<blockquote>
<p>The term “crypto machine” immediately evokes a sense of reliability,
something like the mechanical encryption devices of the past, such as the
Enigma. It’s not just technology, but also a belief in security. Such a device
doesn’t need endless features. It just needs to be <strong>precise and dependable</strong>.
When a user presses a button, the result must be <strong>predictable and safe</strong>. That
pursuit of control and predictability is the soul of a crypto machine.</p></blockquote>
<p>I started looking for existing solutions. There were already some GUI tools back then, like Kleopatra. But a lot of them had complicated interfaces and too many features, and some even brought in the X.509 certificate system, which put me off right away. I wanted something lighter and simpler. Later I found a project called <a href="https://git.bktus.com/gpgfrontend/gpg4usb/">gpg4usb</a>, which was very close to what I had in mind: lightweight, portable and cross-platform. Unfortunately, it had stopped being updated long ago and only supported GPG 1.4. That meant compatibility problems with modern systems were almost unavoidable, and it couldn&rsquo;t support subkeys either.</p>
<p>So I started thinking: could I rewrite part of it and bring it back to life? Around May, I spent about half a month in my dorm reading its source code, figuring out how to call GPG&rsquo;s interfaces, and learning about the Qt framework and cross-platform compatibility. It was a lonely process, but a really fulfilling one. Every time I got a new feature working, I felt a sense of achievement that&rsquo;s hard to describe. When I finally got it running with GPG 2 and fixed quite a few of the original bugs, I decided to give the refreshed project a new name: <a href="https://gpgfrontend.bktus.com/">GpgFrontend</a>. It&rsquo;s a graphical frontend for GPG, and it was also the first complete open-source project of my life.</p>
<p><img alt="GpgFrontend" loading="lazy" src="https://img.bktus.com/P7a8YV8G.webp"></p>
<h2 id="going-public-from-dorm-room-code-to-github">Going Public: From Dorm Room Code to GitHub</h2>
<p>After I uploaded the first version to GitHub, I didn&rsquo;t expect much attention. After all, this is a very niche area, and GPG itself isn&rsquo;t something most people use. But a few days later, I got my first issue. A user said the program didn&rsquo;t run on a certain operating system. They provided logs and even suggested a fix. That was the first time I felt something that made me want to keep putting time into this project.</p>
<p>After that, more and more people started using GpgFrontend. They reported problems, made suggestions and even contributed translations. Every piece of feedback showed me that this project was no longer just my own tech toy. It was a tool people actually used. From then on, my understanding of open source changed completely. To me, it&rsquo;s not just sharing code anymore. It&rsquo;s a whole ecosystem that keeps getting feedback and keeps changing.</p>
<p>Over the next two or three years, I gradually understood that GpgFrontend can&rsquo;t be, and doesn&rsquo;t need to be, an all-in-one tool. Its purpose is very clear: to help users encrypt, decrypt, sign and verify more easily. Its value isn&rsquo;t in the number of features, it&rsquo;s in being easy to use and reliable. So now I clearly define it as a <strong>lightweight, secure crypto machine</strong>, which is exactly what I wanted when I first started using GPG.</p>
<p>For experienced users who know the command line, it&rsquo;s a tool that saves time. For beginners, it&rsquo;s a bridge into the world of cryptography. So in the UI, I try to keep things simple, so that every core operation is clear at a glance. Under the hood, every action maps directly to a native GPG command, to keep it stable and compatible. Later I realized that this “small but focused” positioning actually became what makes GpgFrontend different. While other projects go after more features, I chose to keep it focused.</p>
<h2 id="growing-using-the-project-as-my-testing-ground">Growing: Using the Project as My Testing Ground</h2>
<p>As the versions went on, GpgFrontend became my training ground for learning new technology. I kept trying to bring new ideas I picked up at work and in my studies into the project. I studied Chromium&rsquo;s multithreading architecture and brought its ideas of thread scheduling and task isolation into GpgFrontend, so the interface no longer freezes during encryption, and race conditions and other common multithreading bugs are reduced as much as possible. I designed a plugin system and an SDK, so third parties can extend features at runtime. I improved the build scripts and added CI/CD, so packaging for different platforms is more automated and more reliable. Also, through the cross-platform support, I learned about the many implementation differences between Windows, macOS and Linux, and how packaging works on different operating systems and distribution platforms.</p>
<p>These experiments made the tool itself better, and they also gave me real engineering experience: how to design an architecture that can be maintained, how to balance stability and new ideas, and how to refactor without breaking old features. Step by step, GpgFrontend grew from a simple experiment into an open-source tool with a reasonable structure that people can rely on.</p>
<p>When I was taking a network security course, the professor talked about why data security and key management matter so much. Suddenly I realized that some of the things I had implemented early in the project had hidden risks. For example, the key derivation algorithm was too simple, stored data had no key rotation, and some memory wasn&rsquo;t protected. So I started a full security refactoring.</p>
<p>In <a href="https://github.com/saturneric/GpgFrontend/releases/tag/v2.1.9">version 2.1.9</a>, I added security levels, startup self-checks, AES-GCM encryption mode, key rotation and secure memory. I also redesigned the program&rsquo;s data structures, so that temporary secrets in memory are wiped as safely as possible after they&rsquo;re used. These changes happen behind the scenes, but they made GpgFrontend noticeably more secure and reliable. As I&rsquo;ve always believed, security isn&rsquo;t a feature, it&rsquo;s an attitude. Only when security is built in from the design stage can a tool keep people&rsquo;s trust over time.</p>
<p>Over the years of maintaining the project, I&rsquo;ve gradually felt a kind of satisfaction that goes beyond the technology. GpgFrontend isn&rsquo;t a popular project, but it has really helped some real users. Some people use it to verify the signatures of software packages, some use it to handle secure communication quickly at work, and someone told me it was their first way into learning GPG. I don&rsquo;t track users, and I don&rsquo;t collect download numbers from each platform either. Honestly, I don&rsquo;t know how many people are using it. But I like not knowing. It makes me feel that GpgFrontend is a pure contribution. To put it more concretely, it&rsquo;s a small crypto machine that&rsquo;s always within reach, can go anywhere with you, and quietly does its job wherever people need it.</p>
<h2 id="looking-ahead-stable-focused-and-in-it-for-the-long-term">Looking Ahead: Stable, Focused and in It for the Long Term</h2>
<p>Over the next few years, I won&rsquo;t make big changes to GpgFrontend. Updates will continue, but they&rsquo;ll mostly be about a better user experience, more stability, bug fixes and small optimizations. I&rsquo;d rather keep it light and under control. The software industry today is full of fast iteration, and I actually hope GpgFrontend can be an exception: a steady, reliable tool you can trust. Maybe it will never be popular or make the tech headlines. But as long as it keeps helping the people who really need it, I think it&rsquo;s all worth it.</p>
<p>In recent years, I&rsquo;ve been paying close attention to how Rust is growing in the security field. I&rsquo;ve looked into a few Rust-based alternatives to the GPG libraries, like RPGP and Sequoia. They have better memory safety and concurrency management, and they support some of the newest OpenPGP features. I think this is clearly the direction things are going. But I also have to face reality: the Rust ecosystem isn&rsquo;t fully mature yet, and its compatibility with the existing GPG ecosystem still needs to be tested.</p>
<p>So I plan to set up a separate branch in the future, plug in Rust-based crypto libraries there as an experiment, and wrap them with a new key database layer. This kind of gradual migration lets me find out whether the new technology works without breaking the stability of the main line. I&rsquo;ve always believed that steady updates matter more than chasing new things. After all, the value of a security tool isn&rsquo;t in being new, it&rsquo;s in being trusted. And building that kind of trust may take something like ten years.</p>
]]></content:encoded></item><item><title>Running a “Vanilla” Mainline Kernel on Raspberry Pi 5: Full Workflow of Trimming, Cross-Compilation, and Deployment</title><link>https://blog.bktus.com/en/archives/czh2is/</link><pubDate>Sat, 14 Jun 2025 01:09:13 +0200</pubDate><guid>https://blog.bktus.com/en/archives/czh2is/</guid><description>&lt;h2 id="summary">Summary&lt;/h2>
&lt;p>This post records how I turned the Raspberry Pi 5 into a minimal development and testing platform for the mainline Linux kernel (the vanilla kernel). It covers how I trimmed the repository down, a custom kernel config, cross-compilation and automated deployment scripts, a trick for removing overlays, and what I’ve learned from keeping it in sync with the mainline community over time. It should be useful for geeks who follow Linux mainline, ARM64 support, kernel development or upstream contributions, or who just like tinkering with the kernel.&lt;/p></description><content:encoded><![CDATA[<h2 id="summary">Summary</h2>
<p>This post records how I turned the Raspberry Pi 5 into a minimal development and testing platform for the mainline Linux kernel (the vanilla kernel). It covers how I trimmed the repository down, a custom kernel config, cross-compilation and automated deployment scripts, a trick for removing overlays, and what I’ve learned from keeping it in sync with the mainline community over time. It should be useful for geeks who follow Linux mainline, ARM64 support, kernel development or upstream contributions, or who just like tinkering with the kernel.</p>
<h2 id="background-and-motivation">Background and Motivation</h2>
<p>Recently I’ve been studying the theory and architecture of the Linux kernel in depth, and I’m getting ready to properly move into OS kernel work. So I bought a Raspberry Pi 5 as a development board to learn and practice kernel development. But as soon as I started, I found that the Pi 5 can’t run the mainline Linux kernel directly. It can only rely on the <a href="https://github.com/raspberrypi/linux">kernel repository maintained by the Raspberry Pi team</a>. At the time, the latest branch was rpi-6.14.y (now it’s rpi-6.16.y). The repository is maintained by “dynamically pulling upstream mainline code + rebase + lots of custom patches”, which means tens of thousands of lines of changes and a history that keeps getting rewritten.</p>
<p>These custom patches really are important for the official kernel to run stably on the Raspberry Pi with every feature working. But for a developer like me, who <strong>just wants to study mainline kernel features</strong> and cares about the kernel itself, these patches turn into a burden:</p>
<ul>
<li>Syncing with mainline is hard, and merges often run into conflicts.</li>
<li>The version history is rewritten often, so it’s hard to trace back and compare.</li>
<li>Testing new mainline features or giving feedback becomes less straightforward.</li>
</ul>
<p>I looked at x86 development boards and found that most of them can run the mainline kernel directly, but they’re expensive and nowhere near as cost-effective as the Raspberry Pi 5. So I started thinking about how to get the Pi 5 to run the mainline kernel smoothly too. That way I could try out and test the latest kernel features at any time, and it would be easier to report problems and contribute patches for the ARM64 platform. My goal was clear: with as few patches as possible, and staying as close to upstream as possible, make the Raspberry Pi 5 an ideal ARM64 platform for my own mainline kernel experiments and learning.</p>
<h2 id="repository-structure-and-scope-of-changes">Repository Structure and Scope of Changes</h2>
<p>My approach is really simple and goes straight to the point: keep only the drivers and patches that are truly needed, and follow mainline closely for everything else. I only patch the drivers/ directory and focus on core hardware support, mainly:</p>
<ul>
<li>
<p><strong>SD card driver</strong>: makes sure the Raspberry Pi boots normally and the kernel can load the root filesystem. The boot firmware does part of the initialization itself, but the mainline kernel still needs the driver to mount the root filesystem.</p>
</li>
<li>
<p><strong>Wired network card (Ethernet)</strong>: makes it easy to log in remotely over SSH, download new kernel images, and do remote development and debugging. It’s one of the most important I/O channels during kernel development.</p>
</li>
<li>
<p><strong>UART serial port</strong>: the output window for kernel debugging and early print. I can watch the kernel log directly and tell how booting and running are going.</p>
</li>
<li>
<p><strong>USB controller</strong>: for mounting external devices or occasionally moving data offline, which covers more test scenarios.</p>
</li>
<li>
<p><strong>Basic GPIO, power management</strong> and other parts closely tied to the RPi5 hardware.</p>
</li>
<li>
<p>Remove support for subsystems from the official kernel that aren’t needed for kernel development, such as <strong>Wi-Fi, Bluetooth, GPU (VideoCore), HDMI and audio/video acceleration</strong>. They don’t mean much for studying and testing the kernel itself.</p>
</li>
</ul>
<p><strong>Maintain the Raspberry Pi 5 DTS (Device Tree) configuration under arch/arm64/boot/dts/</strong></p>
<ul>
<li>The focus is to make sure the RPi5’s hardware resources, CPU configuration and peripheral mappings are recognized correctly at boot, so the mainline kernel runs smoothly.</li>
</ul>
<p><strong>Keep everything else 1:1 in sync with Linus’s mainline</strong></p>
<ul>
<li>Apart from the few patches above, the rest of the repository stays exactly the same as the <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git">official mainline repository</a>.</li>
<li>Regularly (say, every month or every two weeks) pull the latest code from mainline. Then I only need to apply a handful of patches and resolve a few small conflicts.</li>
</ul>
<p>With this approach, the repository stays minimal and easy to maintain, and it also lays the groundwork for slimming down the config and keeping up with mainline quickly later on.</p>
<h2 id="example-of-a-custom-kernel-config">Example of a Custom Kernel Config</h2>
<p>During the actual deployment, I prepared my own .config for the Raspberry Pi 5 mainline kernel. The goal was to cover my own development, testing and service needs while <strong>cutting out unrelated features as much as possible and keeping build size and build time to a minimum</strong>. Getting there took a lot of trial and error and tuning.</p>
<h3 id="phase-one-trim-everything-keep-only-the-core">Phase One: Trim Everything, Keep Only the Core</h3>
<p>The first version of the .config turned off almost every driver and feature module I didn’t think I needed, including:</p>
<ul>
<li><strong>All network card drivers except the onboard one</strong> (I only kept the driver for the Raspberry Pi 5’s onboard Cadence network card)</li>
<li><strong>Virtualization support</strong> (KVM and so on)</li>
<li><strong>The graphics subsystem, sound cards, HDMI, multimedia acceleration and so on</strong></li>
<li><strong>All network file systems</strong></li>
<li><strong>All file systems except ext4 and the SD card (mmcblk)</strong></li>
<li><strong>Some crypto algorithms and kernel mechanisms</strong> related to the modules above</li>
<li>I even <strong>turned off cgroup</strong></li>
</ul>
<p>After a few rounds of debugging and real testing, the final config may not be the “most minimal” one in theory. But it already cut the kernel build time a lot, and the kernel boots stably and handles the basic functions I need.</p>
<h3 id="phase-two-practical-extensions-for-docker-workloads-and-everyday-services">Phase Two: Practical Extensions for Docker Workloads and Everyday Services</h3>
<p>As my kernel experiments went further, I realized that:</p>
<ul>
<li>I needed Docker to run some real workloads and check the kernel’s stability and compatibility;</li>
<li>I needed to support everyday things like a LAN file server (NAS);</li>
<li>I also wanted another Raspberry Pi to run my self-built kernel long term, hosting services that aren’t so critical.</li>
</ul>
<p>So the newer config files gradually <strong>added back some features</strong>, such as:</p>
<ul>
<li><strong>cgroup, iptables, fuse, overlayfs, wireguard, macvlan, NFS, Samba</strong> and other common kernel modules (to support Docker and file services)</li>
<li>Most of the new features are built as modules and loaded on demand, which further improves boot and runtime efficiency</li>
</ul>
<p>This step made the build a little slower, but the config is still very lean compared with the mainline default, and it fits what I actually use and test much better.</p>
<p><strong>The config files are hosted at:</strong> <a href="https://git.bktus.com/Linux/kernel-configs/">https://git.bktus.com/Linux/kernel-configs/</a></p>
<p>Some key config files, in timeline order:</p>
<ul>
<li>eric-rpi-v1_defconfig</li>
<li>eric-vanilla-c-6.13_defconfig</li>
<li>eric-vanilla-c-6.14_defconfig</li>
<li>eric-vanilla-c-6.15_defconfig</li>
<li>eric-vanilla-v1_defconfig</li>
<li>eric-vanilla-v2_defconfig</li>
<li>eric-vanilla-v3_defconfig</li>
</ul>
<p>From these config files, you can see how I went from extreme trimming to gradually adding things back as I debugged and tuned.</p>
<h2 id="advantages-and-use-cases">Advantages and Use Cases</h2>
<h3 id="close-to-mainline-quick-to-try-and-test-new-features">Close to Mainline, Quick to Try and Test New Features</h3>
<p>The biggest benefit of keeping the patches minimal is that you can take the latest patches from the linux-next branch, or even new features from Linus’s merge window, and run them on the RPi5 at almost “zero cost”. Whether it’s a new scheduler, new file system features, improvements to the virtualization and security subsystems (like KVM, eBPF and LSM), or Zstd compression and new memory management mechanisms, as soon as something changes in mainline, you can <strong>test it on real hardware right away, check its compatibility and performance, and report problems and suggestions to the upstream ARM64 community in time</strong>.</p>
<p>More importantly, <strong>by running a “vanilla” kernel, you can see and understand how the mainline kernel itself is implemented, as faithfully as possible</strong>. You avoid the “side effects” introduced by the Raspberry Pi vendor patches, and you don’t have to worry about mistaking a problem in a vendor patch for a mainline bug.</p>
<p>I maintain the patches with merge rather than rebase, so the repository history is cleaner and the differences between mainline and my local changes are clear at a glance. Almost every mainline merge goes through “instantly”, so you can always keep up with the latest kernel development. For example, you can pull linux-next for testing at any time, or benchmark new kernel features, and it really feels like you’re taking part.</p>
<p>This approach is really valuable for kernel developers, upstream enthusiasts and even “hardcore” hackers. The bugs you run into and the patches you submit are real problems in a mainline environment, <strong>so you can take them straight to the kernel community.</strong></p>
<h3 id="more-efficient-maintenance-and-development">More Efficient Maintenance and Development</h3>
<ul>
<li><strong>Very few patches, very few conflicts</strong>: the repository only covers the hardware support the RPi5 really needs. For each upstream merge, you only have to watch drivers/net/arm/…, drivers/usb/…, drivers/bus/… and arch/arm64/boot/dts/broadcom/…, so conflicts are very limited and there’s little maintenance work.</li>
<li><strong>Debugging and rolling back are really easy</strong>: if mainline introduces a regression or something odd, you only need to check a handful of patches to roll back or adjust. There’s no need to look for a needle in a haystack across thousands of lines of vendor patches.</li>
<li><strong>Easier to contribute upstream</strong>: your driver patches and bug fixes are very “clean”. You can turn them straight into patches and send them to the kernel mailing list, where they’re easy for the community to review and won’t get stuck because of interference from vendor patches.</li>
</ul>
<h3 id="an-ideal-platform-for-development-testing-and-learning">An Ideal Platform for Development, Testing and Learning</h3>
<ul>
<li><strong>Exploring and testing new features</strong>: the RPi5 is a low-cost, mainstream ARM64 development board, so you can easily test linux-next or any mainline branch on it and give test results and feedback to the upstream community.</li>
<li><strong>Performance tuning and driver testing</strong>: you can run performance benchmarks, optimize drivers, do power experiments and so on, and see how new mainline features really perform on ARM64.</li>
<li><strong>A teaching and self-study environment</strong>: for people learning Linux drivers, device trees and HAL, a minimal environment cuts down “environmental noise” as much as possible, so they can focus on understanding the mainline driver framework and hardware abstraction.</li>
</ul>
<p>The official repository has a clear advantage in driver coverage and vendor support, and it suits users who want an “out-of-the-box, full multimedia experience”. My mainline repository focuses on “staying close to upstream, simple maintenance and easy development”. If you just want to watch videos, play games or run a GUI desktop on the Raspberry Pi 5, the official repository is probably more convenient. But for kernel engineers, developers and people who love to experiment, a “lightweight mainline repository” lets you focus more on the kernel itself.</p>
<h2 id="how-to-use-and-contribute">How to Use and Contribute</h2>
<p>In theory, the Raspberry Pi 5 is a lot faster than the Raspberry Pi 4, and it can compile its own kernel just fine. The experience isn’t bad either (with more than 4GB of RAM). But if you need to do kernel or kernel module development and turn on things like code indexing, it doesn’t have enough power.</p>
<p>I also tried adding the official SSD Kit (512GB). That solved the I/O throughput problem, but in the end I still hit a CPU bottleneck, because it only has 4 cores. So if you just need a working, up-to-date kernel and don’t compile often, you can build and install it on the Raspberry Pi itself. But if you need to go further with development and debugging, I still strongly recommend cross-compilation. That means compiling the kernel and kernel modules on a PC or workstation (usually x86), and then copying them to the Raspberry Pi over the network (or with the SD card). For example, my workstation has 12 cores, and builds take several times less time on it (compared with the RPi5’s 4 cores). So below, I’ll use my own cross-compilation setup as the example.</p>
<p>Before that, you need to install an ARM64 cross-compilation environment. I suggest installing ccache to cut the time of repeated builds even more. If you don’t want to use ccache, remove the ccache part from all the commands in the following sections.</p>
<pre tabindex="0"><code>sudo apt install bc bison flex libssl-dev make libc6-dev libncurses5-dev
sudo apt install crossbuild-essential-arm64
sudo apt install ccache
</code></pre><h3 id="clone-the-repositories-and-check-out-the-latest-branch">Clone the Repositories and Check Out the Latest Branch</h3>
<p>My repository is on my own private Git server, but you can use my mirror on GitHub. I regularly track Linus’s mainline repository and update the main branch.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>git clone https://git.bktus.com/Linux/kernel-configs.git
</span></span><span style="display:flex;"><span>git clone https://github.com/saturneric/linux <span style="color:#f92672">(</span>recommand<span style="color:#f92672">)</span> or https://git.bktus.com/linux/kernel.git
</span></span><span style="display:flex;"><span>cd linux
</span></span><span style="display:flex;"><span>git checkout main
</span></span></code></pre></div><p>Note: the first command clones the <a href="https://git.bktus.com/Linux/kernel-configs/">kernel config repository</a> I mentioned earlier. So <strong>don’t use the config files provided by the Raspberry Pi team in the later steps</strong> (they turn on lots of features), because that will most likely give you a compiled kernel that doesn’t boot.</p>
<p>Of the two, <a href="https://github.com/saturneric/linux">https://github.com/saturneric/linux</a> is on GitHub and should be the fastest in theory, so if you don’t have any special needs, try to clone from there. <a href="https://git.bktus.com/linux/kernel.git">https://git.bktus.com/linux/kernel.git</a> is the repository hosted on my own server, and the GitHub repository above is a mirror of it.</p>
<h3 id="basic-configuration">Basic Configuration</h3>
<p>You need to pick a config file from the kernel-configs repository that fits the current version, rename it to <code>.config</code> and copy it into the root of the kernel repository.</p>
<pre tabindex="0"><code>cp ../kernel-configs/eric-vanilla-c-6.16_defconfig .config
</code></pre><p>You can trim the kernel further on top of my config, or add features.</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; menuconfig
</code></pre><h3 id="build">Build</h3>
<p>Once the cross-compilation environment is ready, you can build right away. How long it takes depends on your config and your machine. For me, it takes about 10 minutes.</p>
<pre tabindex="0"><code>make ARCH=arm64 CROSS_COMPILE=&#34;ccache aarch64-linux-gnu-&#34; -j$(nproc)
</code></pre><h3 id="copy-the-kernel-and-kernel-modules-to-the-raspberry-pi">Copy the Kernel and Kernel Modules to the Raspberry Pi</h3>
<p>You can use the script I provide to quickly transfer the kernel image and kernel modules you just built to the home directory of the default user on the Raspberry Pi. I strongly recommend not giving the kernel image and device tree the same names as the Raspberry Pi 5’s default kernel. Use names like <code>kernel-vanilla.c.img</code> and <code>bcm2712d0-rpi-5-b.vanilla.c.dtb</code> instead, so even if something goes wrong, we can quickly switch back to the original working kernel or device tree through the config file. Also, the rsync in the script needs passwordless SSH, so I suggest setting up your public key beforehand.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== Configurable parameters (change them to fit your setup) ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Local directory for the kernel build artifacts</span>
</span></span><span style="display:flex;"><span>LOCAL_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;./kernel-artifacts&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># SSH connection info for the target Raspberry Pi (e.g. pi@192.168.1.100)</span>
</span></span><span style="display:flex;"><span>REMOTE_HOST<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;pi@192.168.1.100&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Target directory on the Raspberry Pi (an absolute path is recommended, e.g. /home/pi/kernel)</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Target kernel file name (customizable, default kernel_2712.img)</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Device tree file name (customizable)</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>DTB_SOURCE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;arch/arm64/boot/dts/broadcom/bcm2712d0-rpi-5-b.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Cleaning and preparing the local directory &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>rm -rf <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>mkdir -p <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Installing kernel modules into the local output directory &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>make ARCH<span style="color:#f92672">=</span>arm64 CROSS_COMPILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;aarch64-linux-gnu-&#34;</span> INSTALL_MOD_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span> modules_install
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Copying the kernel image and device tree &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f arch/arm64/boot/Image.gz         <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>cp -v -f <span style="color:#e6db74">&#34;</span>$DTB_SOURCE<span style="color:#e6db74">&#34;</span>                    <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Uploading the kernel artifacts to the Raspberry Pi &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>ssh <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;sudo mkdir -p </span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>rsync -avz --progress --delete <span style="color:#e6db74">&#34;</span>$LOCAL_KERNEL_ARTIFACTS<span style="color:#e6db74">/&#34;</span> <span style="color:#e6db74">&#34;</span>$REMOTE_HOST<span style="color:#e6db74">:</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Upload complete. You can now log in to the Raspberry Pi and configure/switch the boot kernel &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><p>So after the script finishes, all the files you’re about to install are already on the Raspberry Pi. But note that they’ve only been copied over. The new kernel isn’t actually in use yet.</p>
<h3 id="install-the-kernel-and-kernel-modules-on-the-raspberry-pi">Install the Kernel and Kernel Modules on the Raspberry Pi</h3>
<p>With the script below, you can easily install the files you just copied to the Raspberry Pi (device tree, kernel and kernel modules) to where they should go. <strong>Note: this script touches several critical system directories, so double-check the parameters to avoid deleting or overwriting important files by mistake.</strong></p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e">#!/bin/bash
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># RPi5 mainline kernel local deployment/flashing script</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Installs the kernel image, device tree and kernel modules into /boot and /lib/modules</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Make sure you run it on the Raspberry Pi with sudo privileges</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>set -e
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ====== Configurable parameters (change them to fit your setup) ======</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Directory holding the uploaded artifacts (the ones just synced over with rsync)</span>
</span></span><span style="display:flex;"><span>REMOTE_KERNEL_ARTIFACTS<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/home/pi/kernel&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel image name (keep it the same as in the upload script)</span>
</span></span><span style="display:flex;"><span>KERNEL_IMG<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;kernel-vanilla.c.img&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Device tree file name</span>
</span></span><span style="display:flex;"><span>DTB_FILE<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;bcm2712d0-rpi-5-b.vanilla.c.dtb&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Location of the kernel image and device tree</span>
</span></span><span style="display:flex;"><span>BOOT_FIRMWARE_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/boot/firmware&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Actual install directory for kernel modules (target)</span>
</span></span><span style="display:flex;"><span>LIB_MODULES_PATH<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/lib/modules&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># ==============================================</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 1. Installing the kernel image and device tree &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo cp -v <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 2. Setting permissions for the image and DTB &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown root:root <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$KERNEL_IMG<span style="color:#e6db74">&#34;</span> <span style="color:#e6db74">&#34;</span>$BOOT_FIRMWARE_PATH<span style="color:#e6db74">/</span>$DTB_FILE<span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 3. Installing kernel modules &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Modules with the same version number are overwritten automatically</span>
</span></span><span style="display:flex;"><span>sudo rsync -av --progress <span style="color:#e6db74">&#34;</span>$REMOTE_KERNEL_ARTIFACTS<span style="color:#e6db74">/lib/modules/&#34;</span> <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; 4. Setting permissions for kernel modules &lt;&lt;&lt;&#34;</span>
</span></span><span style="display:flex;"><span>sudo chown -R root:root <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type d -exec sudo chmod <span style="color:#ae81ff">755</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>find <span style="color:#e6db74">&#34;</span>$LIB_MODULES_PATH<span style="color:#e6db74">/&#34;</span> -type f -exec sudo chmod <span style="color:#ae81ff">644</span> <span style="color:#f92672">{}</span> <span style="color:#ae81ff">\;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>echo <span style="color:#e6db74">&#34;&gt;&gt;&gt; Kernel and modules deployed. If needed, update /boot/config.txt to point to the new kernel &lt;&lt;&lt;&#34;</span>
</span></span></code></pre></div><h3 id="configure-the-raspberry-pi-firmware-to-boot-the-new-kernel">Configure the Raspberry Pi Firmware to Boot the New Kernel</h3>
<p>You need to edit <code>/boot/firmware/config.txt</code> so that the Raspberry Pi firmware boots the new kernel and passes it the matching device tree to use. Mainly, you change or add the two lines below.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># DTB</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h2 id="removing-the-raspberry-pis-dts-overlay-feature-and-avoiding-common-boot-problems">Removing the Raspberry Pi’s DTS Overlay Feature (and Avoiding Common Boot Problems)</h2>
<p>The Raspberry Pi team added a DTS overlay mechanism to their platform. When the main device tree is loaded, this design lets extra overlay fragments be stacked on top of it dynamically, depending on what the firmware or the user needs. That way, peripherals, parameters or features can be turned on or adjusted flexibly. For example, if you add a new module or feature to your Raspberry Pi, you only need to configure an overlay to activate it, which is pretty convenient.</p>
<p>But this mechanism is currently <strong>not supported by the mainline Linux kernel</strong>.</p>
<p>If overlay settings are enabled in <code>/boot/firmware/config.txt</code> and the overlay files don’t match the device tree (DTB) version of the mainline kernel, it’s very easy to end up with boot failures, devices that aren’t recognized and similar problems. For kernel developers who want a minimal, pure mainline kernel experience, this often causes more trouble than it saves.</p>
<h3 id="my-approach">My Approach</h3>
<p>For me personally, DTS overlays are very flexible, but the mainline kernel doesn’t support them natively, and they get in the way of kernel debugging and a clean environment. So I chose to <strong>remove the overlay feature completely</strong> and keep only the main device tree file. The direct side effect is that <strong>some hardware parameters (like CPU boot parameters) are normally injected through overlays, so just removing overlays will stop the Raspberry Pi from booting.</strong></p>
<p><strong>The fix</strong>: I got around this by writing the required CPU parameters directly into the main device tree file. Actually, the official device tree file bcm2712d0-rpi-5-b.dtb is made for the no-overlay case. As long as you use it as the main device tree, the system boots normally without any overlay.</p>
<h3 id="how-to-remove-the-overlay-config-step-by-step">How to Remove the Overlay Config (Step by Step)</h3>
<p>Edit /boot/firmware/config.txt, make sure only device_tree is set, and remove or comment out all overlay settings (such as the dtoverlay= lines). Here’s an example:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#75715e"># Specify the main device tree file (bcm2712d0-rpi-5-b.vanilla.c.dtb is recommended)</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">device_tree</span><span style="color:#f92672">=</span><span style="color:#e6db74">bcm2712d0-rpi-5-b.vanilla.c.dtb</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Don&#39;t load any overlay</span>
</span></span><span style="display:flex;"><span><span style="color:#75715e">#dtoverlay=xxx      # Comment out or delete all of these</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># It&#39;s best to also turn off the other overlay auto-detection features</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">camera_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">display_auto_detect</span><span style="color:#f92672">=</span><span style="color:#e6db74">0</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Kernel image to boot</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">kernel</span><span style="color:#f92672">=</span><span style="color:#e6db74">kernel-vanilla.c.img</span>
</span></span></code></pre></div><h3 id="check-other-overlay-related-settings">Check Other Overlay-Related Settings</h3>
<ul>
<li>I recommend turning off camera_auto_detect and display_auto_detect.</li>
<li>Make sure no dtoverlay= entry is enabled.</li>
</ul>
<h3 id="reboot-the-raspberry-pi">Reboot the Raspberry Pi</h3>
<p>Once the changes above are in place, reboot the device. The system will load the main device tree file directly and <strong>won’t apply any overlay anymore</strong>, which keeps the mainline kernel as clean and controllable as possible. If everything works fine afterward, you can remove the <code>/boot/firmware/overlays</code> directory to save space. This also makes sure these overlays can never be loaded at boot again, no matter what, so they can’t pollute the environment.</p>
<h3 id="recommended-minimal-configtxt-template">Recommended Minimal config.txt Template</h3>
<pre tabindex="0"><code># Only specify the main device tree and the mainline kernel image
device_tree=bcm2712d0-rpi-5-b.vanilla.c.dtb
kernel=kernel-vanilla.c.img

# Turn off overlay auto-detection
camera_auto_detect=0
display_auto_detect=0

# Other common parameters can stay
disable_fw_kms_setup=1
arm_64bit=1
disable_overscan=1
arm_boost=1
</code></pre><h2 id="submitting-patches-or-issues">Submitting Patches or Issues</h2>
<ul>
<li>If you run into any problems while following this post, or find a step that keeps the process from working, feel free to let me know anytime.</li>
<li>If you fix a compatibility problem or find a bug while using it, you’re also welcome to open an issue directly, so we can discuss it with other users and improve the project together.</li>
<li>If you add hardware support, make performance improvements or port new mainline patches on top of this repository, I suggest generating standard patches with scripts/format-patch.sh and then sending them straight to the upstream Linux kernel mailing list, so the community can take in the improvements.</li>
</ul>
<p>GitHub repository: <a href="https://github.com/saturneric/linux">https://github.com/saturneric/linux</a></p>
<h2 id="long-term-maintenance-notes">Long-Term Maintenance Notes</h2>
<p>Neither this repository nor this post is a one-off “pop-up project”. Since I’ll be studying the Linux kernel and operating system theory for a long time, I’ll keep following every major mainline kernel release (including the rc1 … rcX stages) and merge the key changes and adaptations into the main branch in time. Before each mainline sync, I first build it on my workstation (Debian Testing) and then test it on a real Raspberry Pi 5, to make sure the repository always works and the process runs smoothly.</p>
<p>If you’re also doing mainline kernel development on a Raspberry Pi, or you run into compatibility or adaptation problems, feel free to leave a comment. I also hope you’ll join the mainline kernel community and help the ARM64 platform keep getting better.</p>
]]></content:encoded></item><item><title>Building a Personal Chained VPN Network: Efficient Privacy Protection, Unlimited Device Management, and Remote Access</title><link>https://blog.bktus.com/en/archives/qqyy2t/</link><pubDate>Mon, 02 Jun 2025 19:20:00 +0200</pubDate><guid>https://blog.bktus.com/en/archives/qqyy2t/</guid><description>&lt;p>In some situations, you might want to set up a chained VPN. That means your devices on the internal network first connect to a self-hosted WireGuard server (a personal VPS, for example), and that server then forwards all traffic to another VPN (a company, school or commercial VPN service) before it goes out to the Internet. This kind of “VPN over VPN” setup has some clear advantages:&lt;/p>
&lt;ul>
&lt;li>
&lt;p>Strong privacy protection: Traffic from your devices first goes through your own encrypted WireGuard tunnel to your personal VPS. The VPS then forwards it a second time through the commercial or company VPN, and it finally reaches the Internet from that VPN’s exit IP. This way, the VPS never uses its own IP address to access the target network directly, which greatly reduces the risk of your personal IP being tracked or leaked.&lt;/p></description><content:encoded><![CDATA[<p>In some situations, you might want to set up a chained VPN. That means your devices on the internal network first connect to a self-hosted WireGuard server (a personal VPS, for example), and that server then forwards all traffic to another VPN (a company, school or commercial VPN service) before it goes out to the Internet. This kind of “VPN over VPN” setup has some clear advantages:</p>
<ul>
<li>
<p>Strong privacy protection: Traffic from your devices first goes through your own encrypted WireGuard tunnel to your personal VPS. The VPS then forwards it a second time through the commercial or company VPN, and it finally reaches the Internet from that VPN’s exit IP. This way, the VPS never uses its own IP address to access the target network directly, which greatly reduces the risk of your personal IP being tracked or leaked.</p>
</li>
<li>
<p>Centralized and easy management: All client devices connect to one WireGuard service, so you don’t have to configure every device one by one. More importantly, it also neatly gets around the device limit per account that some commercial VPN providers set. You pay once, and all your devices share it.</p>
</li>
<li>
<p>Flexible and easy to switch: The commercial or company VPN configuration only needs to be changed once, on your self-hosted WireGuard server, and downstream clients (phones, computers and so on) don’t need any changes. So replacing or reconfiguring the upstream VPN is much faster and easier, and day-to-day maintenance gets a lot more efficient.</p>
</li>
<li>
<p>Your own virtual LAN, so devices can talk to each other: Once all your devices are connected to your self-hosted WireGuard VPN server, each one automatically gets an IP address in the same VPN virtual LAN (for example, 10.8.0.0/16). Devices in this network can talk to each other directly, without any extra setup.</p>
</li>
</ul>
<p>This convenience means that wherever you are, you can easily do things like:</p>
<ul>
<li>Remote SSH login: access your servers at home or in the office at any time.</li>
<li>Private NAS media access: reach the media files on your home NAS while you’re out.</li>
<li>Remote work: securely access internal company network resources from anywhere, at any time.</li>
</ul>
<h2 id="the-solution">The Solution</h2>
<p>After some exploring and hands-on work, I gradually worked out my own chained VPN setup. In general, it’s deployed entirely with Docker, and the core components are:</p>
<ol>
<li><strong>Gluetun</strong>: a Docker image with built-in OpenVPN/WireGuard clients that can connect to all the major VPN providers. In this example, we configure it to act as a VPN gateway inside a Docker network.</li>
<li><strong>WG-Easy</strong>: a simplified WireGuard Docker image with a built-in web interface, which makes it easy to create and manage WireGuard configuration files. Downstream devices connect to this service with a WireGuard client, and all their traffic is forwarded to the Gluetun container, which then sends it on to the upstream VPN.</li>
</ol>
<p>The advantage of this setup is that it’s fully containerized, so it doesn’t pollute the environment of your server or VPS. It’s also fairly stable. In my own daily use, I haven’t noticed any obvious latency, stuttering or dropped connections, and the performance is good (tested on my home connection). Also, the setup now supports IPv6. Even if a device is on an IPv4-only network, it can still reach IPv6 resources through the chain.</p>
<p>In terms of network topology, the whole system only needs one Docker bridge network:</p>
<ul>
<li><strong>vpn</strong>: the “VPN network” between Gluetun and WG-Easy. Gluetun acts as the gateway in it, and all traffic from WG-Easy enters this network and is forwarded by Gluetun to the upstream VPN.</li>
</ul>
<pre class="mermaid">
  flowchart TD
 subgraph s1[&#34;Your Devices&#34;]
        n1[&#34;Phone&#34;]
        E[&#34;PC&#34;]
        D[&#34;Laptop&#34;]
  end
 subgraph s2[&#34;Your Server (VPS)&#34;]
        n2[&#34;WG-Easy (WireGuard Server)&#34;]
        F[&#34;Gluetun (VPN Client)&#34;]
  end
    n1 -- WireGuard Tunnel --&gt; n2
    n2 --&gt; F
    E -- &#34;WireGuard Tunnel&#34; --&gt; n2
    D -- &#34;WireGuard Tunnel&#34; --&gt; n2
    F -- VPN Tunnel --&gt; B[&#34;VPN Provider&#34;]
    B --&gt; n3[&#34;Internet&#34;]
    n1@{ shape: rect}
    B@{ shape: rect}
    n3@{ shape: rect}
</pre>
<p>Here, WG-Easy listens on UDP 51820. When a client (your own phone or computer) connects, WG-Easy (inside its container) sends the traffic over the Docker network <code>vpn</code> to the Gluetun container, and Gluetun connects to the upstream VPN over WireGuard/OpenVPN. All downstream traffic finally leaves through Gluetun’s <code>tun0</code> interface, and that’s how you get the chained VPN.</p>
<hr>
<p>If you want to skip the detailed setup steps below and just use the complete, integrated setup, you can check out my repository on GitHub:</p>
<p>👉 <strong><a href="https://github.com/saturneric/wg-easy-gluetun">https://github.com/saturneric/wg-easy-gluetun</a></strong></p>
<h2 id="environment-and-prerequisites">Environment and Prerequisites</h2>
<ul>
<li>A Linux server or VPS that supports Docker and Docker Compose (with kernel support for WireGuard and iptables/NFT). I recommend kernel version 5.10 or later.</li>
<li>Docker and Docker Compose v2+ installed.</li>
<li>An account with a commercial VPN provider that supports OpenVPN/WireGuard.</li>
<li>Make sure the host allows the CAP_NET_ADMIN and SYS_MODULE capabilities and can load the WireGuard kernel module (you can check with <code>lsmod | grep wireguard</code>).</li>
</ul>
<h2 id="create-a-custom-network"><strong>Create a Custom Network</strong></h2>
<p>Before the actual deployment, first create the bridge network on the host:</p>
<pre tabindex="0"><code>docker network create \
  --driver bridge \
  --subnet 172.31.0.0/16 \
  --subnet fd01:beee:beee::/48 \
  vpn
</code></pre><p>Note: If an existing network conflicts with these subnets, adjust them to fit your own situation. This example assumes the Docker bridge supports IPv6 (for the IPv6 forwarding in the example). If you don’t use IPv6, you can leave out the related configuration or set disable_ipv6=1.</p>
<h2 id="docker-compose-configuration-explained">Docker Compose Configuration Explained</h2>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">version</span>: <span style="color:#e6db74">&#34;3&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">services</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">gluetun</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">image</span>: <span style="color:#ae81ff">qmcgaw/gluetun</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">cap_add</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">NET_ADMIN</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">SYS_MODULE</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">devices</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">/dev/net/tun:/dev/net/tun</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">environment</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">VPN_SERVICE_PROVIDER=${VPN_SERVICE_PROVIDER}</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">VPN_TYPE=${VPN_TYPE}</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">WIREGUARD_PRESHARED_KEY=${WIREGUARD_PRESHARED_KEY}</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">WIREGUARD_ADDRESSES=${WIREGUARD_ADDRESSES}</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">SERVER_REGIONS=${SERVER_REGIONS}</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">configs</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">source</span>: <span style="color:#ae81ff">post-rules.txt</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">target</span>: <span style="color:#ae81ff">/iptables/post-rules.txt</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">volumes</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">/lib/modules:/lib/modules:ro</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">/data/gluetun-ws:/gluetun</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">sysctls</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv4.ip_forward=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv4.conf.all.src_valid_mark=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.all.disable_ipv6=0</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.all.forwarding=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.default.forwarding=1</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">ipv4_address</span>: <span style="color:#ae81ff">172.31.0.4</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">ipv6_address</span>: <span style="color:#e6db74">&#34;fd01:beee:beee::4&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">restart</span>: <span style="color:#ae81ff">unless-stopped</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">wg-easy</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">image</span>: <span style="color:#ae81ff">ghcr.io/wg-easy/wg-easy:15</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ports</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;51820:51820/udp&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">ipv4_address</span>: <span style="color:#ae81ff">172.31.0.8</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">ipv6_address</span>: <span style="color:#e6db74">&#34;fd01:beee:beee::8&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">cap_add</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">NET_ADMIN</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">SYS_MODULE</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">sysctls</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv4.ip_forward=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv4.conf.all.src_valid_mark=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.all.disable_ipv6=0</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.all.forwarding=1</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">net.ipv6.conf.default.forwarding=1</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">volumes</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">/lib/modules:/lib/modules:ro</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">/data/wg-easy:/etc/wireguard</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">restart</span>: <span style="color:#ae81ff">unless-stopped</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">external</span>: <span style="color:#66d9ef">true</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">configs</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">post-rules.txt</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">content</span>: |<span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      iptables -A FORWARD -i eth0 -o tun0 -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      iptables -t nat -A POSTROUTING -o tun0 -j MASQUERADE
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      ip6tables -I INPUT -p icmpv6 -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      ip6tables -I OUTPUT -p icmpv6 -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      ip6tables -A FORWARD -i eth0 -o tun0 -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      ip6tables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">      ip6tables -t nat -A POSTROUTING -o tun0 -j MASQUERADE</span>
</span></span></code></pre></div><p>Next, let’s go through it piece by piece:</p>
<ul>
<li><code>image: qmcgaw/gluetun</code>: “Lightweight swiss-army-knife-like VPN client to multiple VPN service providers”. It can provide VPN service in a container environment and give a VPN connection to other containers that need one. This is the officially maintained Gluetun image, and it supports many VPN protocols and providers.</li>
<li><code>cap_add: [NET_ADMIN, SYS_MODULE]</code>: The container needs the NET_ADMIN and SYS_MODULE capabilities, plus settings like IP forwarding (the same for WG-Easy and Gluetun). These give the container permission to manage the network and load kernel modules, so it can create the TUN device and configure routes, and the WireGuard tunnel and routing work properly.</li>
<li><code>devices: [&quot;/dev/net/tun:/dev/net/tun&quot;]</code>: mounts the host’s TUN device into the container, so Gluetun can create a virtual network interface.</li>
<li><code>image: ghcr.io/wg-easy/wg-easy:15</code>: the official WG-Easy image (you can change the version as needed).</li>
<li><code>&quot;51820:51820/udp&quot;</code>: maps UDP port 51820 on the host to the container, so downstream devices can connect to WireGuard through the host or directly through the Docker network. If you need to expose WG-Easy’s web admin interface, you also need to add <code>&quot;51821:51821/tcp&quot;</code>.</li>
</ul>
<p>For the specific parameters in the environment variables, see the <a href="https://github.com/qdm12/gluetun-wiki/tree/main">official Gluetun documentation</a>.</p>
<p>Note that the two settings below fix each container’s IP address on the Docker bridge. They’re referenced a lot later, when configuring WG-Easy’s routing table and firewall rules. If you change them, remember to update the corresponding values in the later configuration too.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ipv4_address</span>: <span style="color:#ae81ff">172.31.0.4</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ipv6_address</span>: <span style="color:#e6db74">&#34;fd01:beee:beee::4&#34;</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ipv4_address</span>: <span style="color:#ae81ff">172.31.0.8</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ipv6_address</span>: <span style="color:#e6db74">&#34;fd01:beee:beee::8&#34;</span>
</span></span></code></pre></div><p>Here’s what the firewall rules added by Gluetun’s extra startup script <code>post-rules.txt</code> do:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e"># 1. IPv4 forwarding rules (allow forwarding in both directions, eth0 &lt;-&gt; tun0)</span>
</span></span><span style="display:flex;"><span>iptables -A FORWARD -i eth0 -o tun0 -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 2. IPv4 NAT masquerade (SNAT for every packet going out through tun0)</span>
</span></span><span style="display:flex;"><span>iptables -t nat -A POSTROUTING -o tun0 -j MASQUERADE
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 3. Allow IPv6 ICMP (so Neighbor Discovery Protocol and similar protocols work)</span>
</span></span><span style="display:flex;"><span>ip6tables -I INPUT -p icmpv6 -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -I OUTPUT -p icmpv6 -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 4. IPv6 forwarding rules (allow forwarding in both directions, eth0 &lt;-&gt; tun0)</span>
</span></span><span style="display:flex;"><span>ip6tables -A FORWARD -i eth0 -o tun0 -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># 5. IPv6 NAT masquerade (SNAT for every IPv6 packet going out through tun0)</span>
</span></span><span style="display:flex;"><span>ip6tables -t nat -A POSTROUTING -o tun0 -j MASQUERADE
</span></span></code></pre></div><p>With these rules, downstream traffic (coming from WG-Easy) can be forwarded to the <code>tun0</code> interface inside the Gluetun container and go into the upstream VPN tunnel. Packets coming back from upstream can also get back into the Docker network, reach WG-Easy and then return to the client. That’s how it works as a VPN gateway.</p>
<h2 id="wg-easy-post-up-script-explained">WG-Easy “Post Up” Script Explained</h2>
<p>Besides Gluetun’s network rules, you also need to set up “Post Up” and “Post Down” scripts in WG-Easy. They add routes and ip rules dynamically after the WireGuard tunnel comes up, so all downstream client traffic goes through Gluetun. This example is for WG-Easy v15, because WG-Easy only supports IPv6 from v15 on. If you want to see the configuration for v14, you can check <a href="https://github.com/qdm12/gluetun/discussions/1192#discussioncomment-12689316">the post I published on GitHub</a>.</p>
<p><img alt="Post Up and Post Down hooks in the WG-Easy admin panel" loading="lazy" src="https://img.bktus.com/One7gB5U.webp"></p>
<p>In the current version, v15.0.0, <strong>you need to turn my example into a single line (with the commands separated by semicolons) and fill it into the input box shown in the screenshot</strong>. Or you can write the script into a file, add it to a directory in WG-Easy and reference it from there. Then click <code>Save</code> and wait for WG-Easy to show a message that the configuration was saved. If needed, restart the WG-Easy container after configuring it.</p>
<h3 id="configuration-example">Configuration Example</h3>
<p>Here’s the full example with explanations (note that this needs to be configured on WG-Easy’s web admin page):</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e"># WG-Easy Post Up script (example)</span>
</span></span><span style="display:flex;"><span>VPN<span style="color:#f92672">=</span><span style="color:#66d9ef">$(</span>ifconfig | grep -B1 172.31.0.8 | grep -o <span style="color:#e6db74">&#34;^\w*&#34;</span><span style="color:#66d9ef">)</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># First, drop all forwarded traffic by default</span>
</span></span><span style="display:flex;"><span>iptables -P FORWARD DROP
</span></span><span style="display:flex;"><span>ip6tables -P FORWARD DROP
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Open the WireGuard UDP port ({{port}} is replaced with the WireGuard port, usually 51820)</span>
</span></span><span style="display:flex;"><span>iptables -A INPUT -p udp -m udp --dport <span style="color:#f92672">{{</span>port<span style="color:#f92672">}}</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A INPUT -p udp -m udp --dport <span style="color:#f92672">{{</span>port<span style="color:#f92672">}}</span> -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Allow forwarding between the local side and the WireGuard tunnel</span>
</span></span><span style="display:flex;"><span>iptables -A FORWARD -i wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -A FORWARD -o wg0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -A FORWARD -s <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -d <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -i wg0 -o wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>ip6tables -A FORWARD -i wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A FORWARD -o wg0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A FORWARD -s <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> -d <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> -i wg0 -o wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Configure the IPv4 routing table (table 200 is used only for downstream traffic)</span>
</span></span><span style="display:flex;"><span>iptables -t nat -A POSTROUTING -s <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -o $VPN -j MASQUERADE
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Add an ip rule so traffic from {{ipv4Cidr}} uses table 200</span>
</span></span><span style="display:flex;"><span>ip rule add from <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route add default via 172.31.0.4 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route add 172.31.0.0/16 via 172.31.0.1 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route add <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> dev wg0 table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Configure the IPv6 routing table (same idea, also table 200)</span>
</span></span><span style="display:flex;"><span>ip -6 rule add from <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route add default via fd01:beee:beee::4 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route add fd01:beee:beee::/48 via fd01:beee:beee::1 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route add <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> dev wg0 table <span style="color:#ae81ff">200</span>
</span></span></code></pre></div><p>The three variables below are WG-Easy template variables. WG-Easy fills them in automatically, but you need to make sure the values are valid:</p>
<ul>
<li><code>{{port}}</code>: the port WireGuard listens on, usually the same as the port mapped in Docker (51820).</li>
<li><code>{{ipv4Cidr}}</code>: the downstream client subnet, for example <code>10.8.0.0/24</code>. WG-Easy assigns addresses from it to peers.</li>
<li><code>{{ipv6Cidr}}</code>: the downstream client IPv6 subnet, for example <code>fdcc:ad94:bacf:61a4::/64</code>.</li>
</ul>
<p>Here’s the script for PostDown (it simply replaces <code>-A</code> with <code>-D</code> and <code>add</code> with <code>del</code>):</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>VPN<span style="color:#f92672">=</span><span style="color:#66d9ef">$(</span>ifconfig | grep -B1 172.31.0.8 | grep -o <span style="color:#e6db74">&#34;^\w*&#34;</span><span style="color:#66d9ef">)</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>iptables -P FORWARD DROP
</span></span><span style="display:flex;"><span>ip6tables -P FORWARD DROP
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>iptables -D INPUT -p udp -m udp --dport <span style="color:#f92672">{{</span>port<span style="color:#f92672">}}</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -D INPUT -p udp -m udp --dport <span style="color:#f92672">{{</span>port<span style="color:#f92672">}}</span> -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>iptables -D FORWARD -i wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -D FORWARD -o wg0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -D FORWARD -s <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -d <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -i wg0 -o wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>ip6tables -D FORWARD -i wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -D FORWARD -o wg0 -m state --state RELATED,ESTABLISHED -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -D FORWARD -s <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> -d <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> -i wg0 -o wg0 -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>iptables -t nat -D POSTROUTING -s <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> -o $VPN -j MASQUERADE
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>ip rule del from <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route del default via 172.31.0.4 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route del 172.31.0.0/16 via 172.31.0.1 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip route del <span style="color:#f92672">{{</span>ipv4Cidr<span style="color:#f92672">}}</span> dev wg0 table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>ip -6 rule del from <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route del default via fd01:beee:beee::4 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route del fd01:beee:beee::/48 via fd01:beee:beee::1 dev $VPN table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route del <span style="color:#f92672">{{</span>ipv6Cidr<span style="color:#f92672">}}</span> dev wg0 table <span style="color:#ae81ff">200</span>
</span></span></code></pre></div><h3 id="using-multiple-docker-bridges">Using Multiple Docker Bridges</h3>
<p>In my environment, WG-Easy is connected to several Docker bridges. Besides <code>vpn</code>, there are other bridges dedicated to other services. If you need to connect WG-Easy to another bridge network, I recommend keeping the <code>$VPN</code> variable from the configuration above instead of using the <code>{{device}}</code> template variable that WG-Easy provides. The <code>$VPN</code> variable automatically picks the network interface for the matching subnet, so the routing and firewall rules only apply to that interface and won’t accidentally affect other network services. For a second Docker bridge, you can add this command to PostUp:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>VPN_IF<span style="color:#f92672">=</span><span style="color:#66d9ef">$(</span>ifconfig | grep -B1 172.31.0.8 | grep -o <span style="color:#e6db74">&#34;^\w*&#34;</span><span style="color:#66d9ef">)</span>
</span></span></code></pre></div><p>Remember to replace <code>172.31.0.8</code> with the IP of the WG-Easy container on that Docker bridge, which means you need to give WG-Easy a fixed IP on that bridge. Or you can adjust this pattern so grep filters by subnet instead of by IP address. That way, <code>$VPN_IF</code> resolves to the network interface the subnet is using. Then update the routing table and firewall rules as well, so traffic between the service networks stays isolated and still gets forwarded properly:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>iptables -t nat -A POSTROUTING -s &lt;NETWORK_CIDR&gt; -o &lt;NETWORK_INTERFACE&gt; -j MASQUERADE
</span></span><span style="display:flex;"><span>ip6tables -t nat -A POSTROUTING -s &lt;NETWORK_CIDR&gt; -o &lt;NETWORK_INTERFACE&gt; -j MASQUERADE  <span style="color:#75715e"># if this bridge has IPv6</span>
</span></span><span style="display:flex;"><span>ip route add &lt;NETWORK_CIDR&gt; via &lt;NETWORK_GATEWAY&gt; dev &lt;NETWORK_INTERFACE&gt; table <span style="color:#ae81ff">200</span>
</span></span><span style="display:flex;"><span>ip -6 route add &lt;NETWORK_CIDR&gt; via &lt;NETWORK_GATEWAY&gt; dev &lt;NETWORK_INTERFACE&gt; table <span style="color:#ae81ff">200</span>  <span style="color:#75715e"># if this bridge has IPv6</span>
</span></span></code></pre></div><p>Some readers need to provide VPN service to multiple containers but don’t want to attach multiple Docker bridges to WG-Easy directly. For them, here’s a more fine-grained approach that gives you more control. Bind each service that needs the VPN to its own WireGuard client container (such as linuxserver/wireguard or an image like Gluetun), then use WG-Easy (or a similar admin interface) to create a separate WireGuard account for each service. Finally, import the matching configuration into that service’s WireGuard client container. The advantages are:</p>
<ul>
<li>Each service has its own WireGuard configuration file, so traffic isolation is more thorough;</li>
<li>You can monitor and limit a single service’s network access more directly in WG-Easy;</li>
<li>You no longer need rules like <code>iptables -A FORWARD -i eth+ -o tun0</code> that let everything through a network interface. Instead, you only grant trust to specific containers.</li>
</ul>
<p>This approach gives you finer-grained permission control for each container, for example real-time traffic monitoring, or revoking a service’s VPN access at any time. But running multiple WireGuard client containers does cost extra CPU and memory.</p>
<h2 id="deployment">Deployment</h2>
<h3 id="create-and-load-the-environment-variables">Create and Load the Environment Variables</h3>
<p>In the same directory as docker-compose.yml, create a .env file with the following content (see the Gluetun documentation linked above):</p>
<pre tabindex="0"><code>VPN_SERVICE_PROVIDER=XXX
VPN_TYPE=XXXX
WIREGUARD_PRIVATE_KEY=YOUR_PRIVATE_KEY
WIREGUARD_PRESHARED_KEY=YOUR_PSK
WIREGUARD_ADDRESSES=XXX
SERVER_REGIONS=XXX
</code></pre><h3 id="make-sure-the-docker-network-exists">Make Sure the Docker Network Exists</h3>
<p>As mentioned earlier, make sure the custom network named <code>vpn</code> has been created.</p>
<h3 id="start-the-containers">Start the Containers</h3>
<p>Run the command below and watch the startup logs of the wg-easy and gluetun-ws containers, to confirm that both the WireGuard client and the server come up properly.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>$ docker-compose up -d
</span></span></code></pre></div><h3 id="add-a-wireguard-client">Add a WireGuard Client</h3>
<ul>
<li>Open <code>http://&lt;WG-Easy-container-IP&gt;:51821</code> in a browser (depending on your WG-Easy configuration) to get to WG-Easy’s web interface. Or you can add a TCP mapping for port 51821 in Docker Compose and open the web admin interface at <code>http://&lt;host-IP&gt;:51821</code>. Using Nginx as a reverse proxy works too.</li>
<li>In the Hooks section of the Admin Panel, fill in the Post Up and Post Down configuration given above and save it. <strong>This step is really important.</strong></li>
<li>Create a new Peer (enter a name for it). WG-Easy generates the matching configuration file with AllowedIPs = 0.0.0.0/0, ::/0, and you download the .conf file.</li>
<li>Import this configuration on your local device (Windows/Mac/Linux/phone), start WireGuard and test it.</li>
</ul>
<h3 id="verify-the-vpn2vpn-tunnel">Verify the VPN2VPN Tunnel</h3>
<ul>
<li>After the client connects to WireGuard, open <a href="https://ipleak.net">https://ipleak.net</a> or <a href="https://ifconfig.co">https://ifconfig.co</a> and check the exit IP.</li>
<li>If it shows the IP of the upstream commercial VPN, the chained VPN tunnel is working.</li>
<li>You can run <code>curl ifconfig.co</code> in the Gluetun container, and you should see the public IP from the commercial VPN. Run the same thing in the WG-Easy container, and you should see the same exit IP (through the upstream VPN).</li>
</ul>
<h3 id="check-traffic-routing">Check Traffic Routing</h3>
<ul>
<li>In the WG-Easy container, run <code>ip rule show</code> / <code>ip route show table 200</code> to confirm that routing table 200 is in effect and the default route points to 172.31.0.4 (Gluetun).</li>
<li>In the Gluetun container, run <code>iptables -t nat -L -nv</code>, and you’ll see the matching MASQUERADE rules.</li>
<li>If you need to troubleshoot, run <code>tcpdump -i</code> on the relevant interface in each container to capture packets and check what the traffic is doing.</li>
</ul>
<h2 id="notes-and-considerations">Notes and Considerations</h2>
<h3 id="dns-leaks">DNS Leaks</h3>
<p>In this example, if you don’t take extra DNS security measures, there’s a risk of DNS leaks. When a container or client uses the host’s DNS or a public DNS directly, DNS queries may bypass the VPN tunnel and go upstream directly, which exposes your real IP and the websites you visit. Actually, Gluetun creates its own internal DNS server and forces all DNS traffic through it, so that using the local DNS doesn’t cause DNS leaks. But by default Gluetun only listens for DNS requests inside its own container, so other containers and the host can’t reach it. This also means WG-Easy can’t use Gluetun’s internal DNS service directly, so we can’t simply forward WG-Easy’s DNS traffic to Gluetun.</p>
<p>To avoid these problems, you usually need to deploy a separate DNS service (such as AdGuard Home or Pi-hole) and send all DNS queries through it, with upstream resolution going out through the VPN exit. This way, DNS queries also go through the VPN, and you get ad blocking and malicious domain filtering as well.</p>
<h4 id="deploy-adguard-home-or-a-similar-dns-service">Deploy AdGuard Home or a Similar DNS Service</h4>
<p>We can run a separate AdGuard Home container in the same Docker network (the <code>vpn</code> network, for example). AdGuard Home listens on both UDP and TCP port 53, and it has stronger features like ad blocking and malicious domain filtering. For example, you can add a service like the one below to docker-compose.yml (just as a demonstration):</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#f92672">adguard</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">image</span>: <span style="color:#ae81ff">adguard/adguardhome</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">restart</span>: <span style="color:#ae81ff">unless-stopped</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">networks</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">vpn</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">ipv4_address</span>: <span style="color:#ae81ff">172.31.0.16</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">ipv6_address</span>: <span style="color:#e6db74">&#34;fd01:beee:beee::16&#34;</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">ports</span>:
</span></span><span style="display:flex;"><span>    - <span style="color:#e6db74">&#34;53:53/udp&#34;</span>
</span></span><span style="display:flex;"><span>    - <span style="color:#e6db74">&#34;53:53/tcp&#34;</span>
</span></span><span style="display:flex;"><span>    - <span style="color:#e6db74">&#34;3000:3000/tcp&#34;</span> <span style="color:#75715e"># Web interface port</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">volumes</span>:
</span></span><span style="display:flex;"><span>    - <span style="color:#ae81ff">/data/adguard/workdir:/opt/adguardhome/work</span>
</span></span><span style="display:flex;"><span>    - <span style="color:#ae81ff">/data/adguard/conf:/opt/adguardhome/conf</span>
</span></span></code></pre></div><p>This way, AdGuard Home is exposed on port 53 of the host and also gets an IP in the Docker <code>vpn</code> network (here, 172.31.0.16). After that, we can reach this AdGuard Home container directly from WG-Easy, from client devices and even from other containers. You can also choose not to expose port 53 at all and only provide DNS through the <code>vpn</code> bridge.</p>
<p>Open AdGuard Home’s web interface (usually at <code>http://&lt;Host-IP&gt;:3000</code>) and check that the upstream DNS settings are correct and that ad blocking and the other policies work. Then you need to test it. Ideally, run <code>nslookup hostname 172.31.0.16</code> in the WG-Easy container to check whether the DNS path from WG-Easy to AdGuard Home works.</p>
<h4 id="change-the-dns-settings">Change the DNS Settings</h4>
<p>After AdGuard Home is deployed, configured and tested, we need to adjust the client DNS settings that WG-Easy generates, because by default WG-Easy sets the DNS servers to <code>1.1.1.1</code> and <code>2606:4700:4700::1111</code>. To do this, change the DNS in WG-Easy’s Admin Panel to the IPs of the AdGuard Home container: <code>172.31.0.16</code> and <code>fd01:beee:beee::16</code>.</p>
<p><img alt="DNS settings in the WG-Easy admin panel" loading="lazy" src="https://img.bktus.com/pinDVKdk.webp"></p>
<p>Note that the DNS settings of devices you’ve already added don’t follow the DNS settings in the Admin Panel automatically. You need to update the DNS settings in WireGuard on the device by hand, or adjust that device separately in WG-Easy, then download the configuration file again and apply it to the device.</p>
<p>Finally, to strictly limit WG-Easy’s outbound DNS access and rule out DNS leaks, we can add the following commands to the PostUp hook script:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e"># Allow packets to the AdGuard Home DNS port</span>
</span></span><span style="display:flex;"><span>iptables -A OUTPUT -o $VPN -d 172.31.0.16 -p udp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -A OUTPUT -o $VPN -d 172.31.0.16 -p tcp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A OUTPUT -o $VPN -d fd01:beee:beee::16 -p udp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -A OUTPUT -o $VPN -d fd01:beee:beee::16 -p tcp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#75715e"># Reject DNS queries from the rest of the network stack, so nothing leaks to the host</span>
</span></span><span style="display:flex;"><span>iptables -A OUTPUT -p tcp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>iptables -A OUTPUT -p udp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>ip6tables -A OUTPUT -p tcp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>ip6tables -A OUTPUT -p udp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span></code></pre></div><p>The matching PostDown script is:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>iptables -D OUTPUT -o $VPN -d 172.31.0.16 -p udp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>iptables -D OUTPUT -o $VPN -d 172.31.0.16 -p tcp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -D OUTPUT -o $VPN -d fd01:beee:beee::16 -p udp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>ip6tables -D OUTPUT -o $VPN -d fd01:beee:beee::16 -p tcp --dport <span style="color:#ae81ff">53</span> -j ACCEPT
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>iptables -D OUTPUT -p tcp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>iptables -D OUTPUT -p udp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>ip6tables -D OUTPUT -p tcp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span><span style="display:flex;"><span>ip6tables -D OUTPUT -p udp --dport <span style="color:#ae81ff">53</span> -j REJECT
</span></span></code></pre></div><h3 id="ipv6-support">IPv6 Support</h3>
<ul>
<li>If you don’t use IPv6, you can remove <code>ipv6_address</code>, the ip6tables rules and the other related settings from docker-compose.yml, and don’t enable IPv6 when you create the network.</li>
<li>If you do use IPv6, make sure both the host and the VPN provider support IPv6 tunnels.</li>
</ul>
<h3 id="performance-and-resources">Performance and Resources</h3>
<p>WireGuard itself is fairly demanding on the CPU, especially when it runs at full speed, so it needs reasonably good hardware.</p>
<h3 id="multi-hop">Multi-Hop</h3>
<p>This architecture is already a double hop (downstream → WG-Easy → Gluetun → upstream VPN → Internet). If you want to go further and set up more hops, you can pick a different region for the upstream VPN, or stack another VPN container on top. But keep in mind that performance goes down and maintenance gets more complex.</p>
<h3 id="firewall-and-security">Firewall and Security</h3>
<p>In this example, the WG-Easy container only opens UDP port 51820 by default. If you need to access it from the public internet, open that port in the host firewall (iptables/nftables) and only allow trusted IPs, to keep the attack surface small.</p>
<h3 id="postdown-script">PostDown Script</h3>
<p>To avoid leaving rules behind after teardown, make sure to add the matching <code>iptables -D</code>, <code>ip rule del</code>, <code>ip route del</code> and similar commands to WG-Easy’s PostDown. Otherwise you may end up with duplicate routes or conflicts after a restart.</p>
<h2 id="network-troubleshooting-example">Network Troubleshooting Example</h2>
<p>When a client can’t reach the LAN or the Internet, here are some common steps to find the problem quickly. This is also what I usually do myself. I believe that by going from coarse to fine like this, you can find the root cause of most network connection problems.</p>
<p>Below are the concrete steps. I only show the IPv4 commands here, but for IPv6 you can easily do the same checks by adjusting the commands a little.</p>
<h3 id="ping-tests-in-stages-local">Ping Tests in Stages (Local)</h3>
<ul>
<li><code>ping 10.8.0.1</code>: check whether the VPN tunnel is up.</li>
<li><code>ping 172.31.0.8</code>: check whether the client can reach the WG-Easy container (Docker bridge network).</li>
<li><code>ping 172.31.0.4</code>: check connectivity from the bridge network to the Gluetun container.</li>
<li><code>ping 8.8.8.8</code>: test whether Gluetun can reach the Internet.</li>
</ul>
<p>If a step fails, check the routing or firewall rules for that specific step.</p>
<h3 id="check-dns-resolution-local">Check DNS Resolution (Local)</h3>
<p>If you pass the tests above, the path is fine at the IP level, so next we look at DNS.</p>
<ul>
<li><code>nslookup example.com</code>: through the default DNS server.</li>
<li><code>nslookup example.com 172.31.0.16</code>: through AdGuard Home.</li>
<li><code>nslookup example.com 8.8.8.8</code>: test whether public DNS works.</li>
</ul>
<p>If you can’t get a correct response, the DNS request isn’t reaching the server it should reach.</p>
<h3 id="debug-inside-the-containers">Debug Inside the Containers</h3>
<p>If DNS is also fine, the problem may be a deeper conflict in the routing tables or firewall rules. We can go into the WG-Easy or the Gluetun container to debug:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>docker exec -it &lt;container-name/id-of-wg-easy&gt; /bin/bash
</span></span><span style="display:flex;"><span>docker exec -it &lt;container-name/id-of-gluetun&gt; /bin/sh
</span></span></code></pre></div><p>Run these inside the container:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-shell" data-lang="shell"><span style="display:flex;"><span>ip rule show             <span style="color:#75715e"># Check whether the routing rules are correct</span>
</span></span><span style="display:flex;"><span>ip route show table <span style="color:#ae81ff">200</span>  <span style="color:#75715e"># Verify routing table 200</span>
</span></span><span style="display:flex;"><span>ping -c <span style="color:#ae81ff">2</span> 8.8.8.8        <span style="color:#75715e"># Test outbound access from the container</span>
</span></span><span style="display:flex;"><span>ping -c <span style="color:#ae81ff">2</span> example.com    <span style="color:#75715e"># Test DNS inside the container</span>
</span></span><span style="display:flex;"><span>iptables-save            <span style="color:#75715e"># Check the firewall rules</span>
</span></span><span style="display:flex;"><span>ip route                 <span style="color:#75715e"># Verify the default routing table</span>
</span></span></code></pre></div><h3 id="more-advanced-methods-tcpdump-routing-tables-and-firewall-checks">More Advanced Methods: tcpdump, Routing Tables and Firewall Checks</h3>
<p>If these simple methods still can’t find the problem, there’s probably a deeper conflict in the routing table or firewall configuration. At this point, you can use <code>tcpdump -i &lt;interface&gt;</code> to capture packets and see whether DNS (UDP/TCP 53) or other traffic reaches the container or gets dropped. Then carefully check the routing tables on the host and in the containers (<code>ip rule show</code>, <code>ip route show</code>) for overlapping or conflicting entries, and make sure the ip rule priorities and table entries actually take effect. After that, go through the iptables/ip6tables rules again, especially the FORWARD, OUTPUT and nat tables, to see whether a wrong or duplicate rule is blocking the traffic.</p>
<h3 id="problems-caused-by-updates">Problems Caused by Updates</h3>
<p>Keep in mind that your problem may also come from an image update of one of the containers. In that case, check whether there was an automatic update recently, and try downgrading the version to fix it. If the problem goes away, you can pin the old image version to keep the service working until the issue is finally solved.</p>
]]></content:encoded></item><item><title>Fix grub2 boot UEFI after Ubuntu dual system reinstallation of Windows</title><link>https://blog.bktus.com/en/archives/0vspvh/</link><pubDate>Fri, 26 Nov 2021 11:51:13 +0800</pubDate><guid>https://blog.bktus.com/en/archives/0vspvh/</guid><description>&lt;p>Say you have Ubuntu and Windows installed as a dual-boot system, and then you reinstall Windows. The Grub boot entry will very likely be overwritten by Windows Boot Manager, and at that point you can&amp;rsquo;t get into Ubuntu anymore. But don&amp;rsquo;t panic. You can fix the grub2 boot entry with the steps below, and you don&amp;rsquo;t need to install any extra software.&lt;/p>
&lt;h2 id="making-an-ubuntu-usb-boot-drive">Making an Ubuntu USB Boot Drive&lt;/h2>
&lt;p>To repair the boot entry, we need the software tools that come with Ubuntu. We can&amp;rsquo;t get into the original Ubuntu system for now, but we can use the image written to an Ubuntu USB drive to get a basic, working Ubuntu environment. Download the image file from the &lt;a href="https://ubuntu.com/download/desktop">Ubuntu website&lt;/a>.&lt;/p></description><content:encoded><![CDATA[<p>Say you have Ubuntu and Windows installed as a dual-boot system, and then you reinstall Windows. The Grub boot entry will very likely be overwritten by Windows Boot Manager, and at that point you can&rsquo;t get into Ubuntu anymore. But don&rsquo;t panic. You can fix the grub2 boot entry with the steps below, and you don&rsquo;t need to install any extra software.</p>
<h2 id="making-an-ubuntu-usb-boot-drive">Making an Ubuntu USB Boot Drive</h2>
<p>To repair the boot entry, we need the software tools that come with Ubuntu. We can&rsquo;t get into the original Ubuntu system for now, but we can use the image written to an Ubuntu USB drive to get a basic, working Ubuntu environment. Download the image file from the <a href="https://ubuntu.com/download/desktop">Ubuntu website</a>.</p>
<p><img alt="Ubuntu download page" loading="lazy" src="https://img.bktus.com/yxvShcvU.webp"></p>
<p>To make the USB boot drive, you can use <a href="https://rufus.ie/zh/">rufus</a>, which is small, easy to use and doesn&rsquo;t need to be installed. With rufus you can quickly create a USB boot drive. Just make sure you choose GPT mode.</p>
<p><img alt="Creating a USB boot drive with rufus" loading="lazy" src="https://img.bktus.com/2Epyqvjl.webp"></p>
<h2 id="booting-from-the-usb-boot-drive">Booting from the USB Boot Drive</h2>
<p>Restart the computer and choose the USB drive in the BIOS boot settings. When the Ubuntu installer comes up, select Try Ubuntu on the installation screen to enter Ubuntu Live.</p>
<h2 id="rebuilding-grub2">Rebuilding Grub2</h2>
<p>Use fdisk to find the EFI partition and the partition that holds the /boot mount point (if you didn&rsquo;t set up a separate /boot mount point, use the / mount point instead). Mount the partition that holds the /boot mount point to /mnt (my partitions are on an NVMe SSD).</p>
<pre tabindex="0"><code>% sudo mount /dev/nvme0n1p6 /mnt/
</code></pre><p>Mount the EFI partition. Here you need to know which partition on your disk is the EFI system partition (for me it&rsquo;s the fifth one).</p>
<pre tabindex="0"><code>% sudo mount /dev/nvme0n1p5 /mnt/boot/efi
</code></pre><p>Bind the other directories we need</p>
<pre tabindex="0"><code>% sudo mount --bind /dev /mnt/dev
% sudo mount --bind /dev/pts /mnt/dev/pts
% sudo mount --bind /proc /mnt/proc
% sudo mount --bind /sys /mnt/sys
</code></pre><p>Change the root directory to /mnt</p>
<pre tabindex="0"><code>% sudo chroot /mnt
</code></pre><h2 id="repairing-the-grub2-boot-entry">Repairing the Grub2 Boot Entry</h2>
<p>The command you need to run here is different for 32-bit and 64-bit systems. Both are given below. 32-bit systems:</p>
<pre tabindex="0"><code>% sudo grub-install --target=i386-efi /dev/nvme0n1
</code></pre><p>64-bit systems:</p>
<pre tabindex="0"><code>% sudo grub-install --target=x86_64-efi /dev/nvme0n1
</code></pre><p>After running one of the commands above, run a recheck as well</p>
<pre tabindex="0"><code>% grub-install --recheck /dev/nvme0n1
</code></pre><p>Cleanup afterwards (optional)</p>
<pre tabindex="0"><code>% exit
% sudo umount /mnt/sys
% sudo umount /mnt/proc
% sudo umount /mnt/dev/pts
% sudo umount /mnt/dev
% sudo umount /mnt
</code></pre><p>Then reboot. You&rsquo;ll see that you can get into the grub2 menu again, and grub2 has found both Ubuntu and Windows Boot Manager.</p>
<h2 id="rebuilding-the-windows-boot-manager-entry-in-grub2">Rebuilding the Windows Boot Manager Entry in Grub2</h2>
<p>Restart the computer, boot into Ubuntu through Grub, and run the following command to regenerate the configuration file</p>
<pre tabindex="0"><code>% sudo update-grub
</code></pre>]]></content:encoded></item><item><title>Implementation of a Hybrid Simulated Annealing Algorithm for Solving the Three-Dimensional Boxing Problem MATLAB</title><link>https://blog.bktus.com/en/archives/3my0wu/</link><pubDate>Thu, 30 Sep 2021 17:02:00 +0800</pubDate><guid>https://blog.bktus.com/en/archives/3my0wu/</guid><description>&lt;p>For a mathematical modeling project, I needed to solve a three-dimensional container loading problem. After some searching, I chose the paper “A Hybrid Simulated Annealing Algorithm for Solving the Three-Dimensional Container Loading Problem” by Prof. Zhang Defu and others, published in the &lt;em>Chinese Journal of Computers&lt;/em>, as the theoretical basis for my solution.&lt;/p>
&lt;h3 id="the-papers-abstract">The Paper&amp;rsquo;s Abstract&lt;/h3>
&lt;blockquote>
&lt;p>This paper proposes a hybrid simulated annealing algorithm for efficiently solving the three-dimensional container loading problem (3D-CLP). The 3D-CLP requires loading a subset of a given set of boxes into a container so that the total volume of the loaded boxes is maximized. The hybrid simulated annealing algorithm in this paper is based on three important algorithms. (1) A composite block generation algorithm. Unlike traditional algorithms, the composite blocks proposed in this paper don&amp;rsquo;t contain only a single type of box, and can contain boxes of any type under certain constraints. (2) A basic heuristic algorithm, which is based on block loading and can generate a placement plan from a given loading sequence. (3) A simulated annealing algorithm. Built on composite block generation and the basic heuristic algorithm, it uses the loading sequence as the encoding of a feasible placement plan, and searches the encoding space with simulated annealing to find an approximately optimal solution to the problem. The algorithm is tested on 1,500 weakly and strongly heterogeneous container loading instances. The experimental results show that the fill rate of the hybrid simulated annealing algorithm is higher than that of the best known algorithms.&lt;/p></description><content:encoded><![CDATA[<p>For a mathematical modeling project, I needed to solve a three-dimensional container loading problem. After some searching, I chose the paper “A Hybrid Simulated Annealing Algorithm for Solving the Three-Dimensional Container Loading Problem” by Prof. Zhang Defu and others, published in the <em>Chinese Journal of Computers</em>, as the theoretical basis for my solution.</p>
<h3 id="the-papers-abstract">The Paper&rsquo;s Abstract</h3>
<blockquote>
<p>This paper proposes a hybrid simulated annealing algorithm for efficiently solving the three-dimensional container loading problem (3D-CLP). The 3D-CLP requires loading a subset of a given set of boxes into a container so that the total volume of the loaded boxes is maximized. The hybrid simulated annealing algorithm in this paper is based on three important algorithms. (1) A composite block generation algorithm. Unlike traditional algorithms, the composite blocks proposed in this paper don&rsquo;t contain only a single type of box, and can contain boxes of any type under certain constraints. (2) A basic heuristic algorithm, which is based on block loading and can generate a placement plan from a given loading sequence. (3) A simulated annealing algorithm. Built on composite block generation and the basic heuristic algorithm, it uses the loading sequence as the encoding of a feasible placement plan, and searches the encoding space with simulated annealing to find an approximately optimal solution to the problem. The algorithm is tested on 1,500 weakly and strongly heterogeneous container loading instances. The experimental results show that the fill rate of the hybrid simulated annealing algorithm is higher than that of the best known algorithms.</p></blockquote>
<p>DOI: 10.3724/SP.J.1016.2009.02147</p>
<h3 id="computation-results-of-my-implementation">Computation Results of My Implementation</h3>
<p><img loading="lazy" src="https://img.bktus.com/5B5A5X2x.webp"></p>
<h3 id="matlab-code-of-the-core-function">MATLAB Code of the Core Function</h3>
<pre tabindex="0"><code>function [solution, newPlan, rate] = container_packeting(bcon, plan, blockTable, blockNeed)
%UNTITLED2 Compute a packing plan from the sizes of the big and small containers and the number of small containers
%   bigContainer size vector of the big container [L W H]
%   smallContainers size matrix of the small containers [L W H;]
%   smallContainersNumber vector of small container counts [n]

solution = {};
newPlan = [];
searchDeep = 40960;

clf;
draw_container([0,0,0], bcon);

% Remaining space stack
lspace_s = get_stack();
% Gap stack
iterval_s = get_stack();
itervalSpace_s = get_stack();
% Initialize the remaining space to the whole big container
lspace_s = stack_push(lspace_s, get_space([0,0,0], bcon));

psCount = 0;
while lspace_s.count &gt; 0
    psCount = psCount + 1;
    % Take an available remaining space from the remaining space stack
    lspace = stack_top(lspace_s);
    lspace_s = stack_pop(lspace_s);
    lspace_size = lspace.size;
    lspace_base = lspace.base_point;

    if_input = 0;

    [blockList, blockListNeed] = get_block_list(blockTable, blockNeed, lspace_size(1), lspace_size(2), lspace_size(3));
    theBlockNeed = NaN;
    find_idx = 1;
    if size(blockList, 1) == 0
        find_avaliable = 0;
    else
        find_avaliable = 1;
        if plan(psCount) &lt;= size(blockListNeed, 1)
            theBlockNeed = blockListNeed(plan(psCount),:);
            find_idx = plan(psCount);
        else
            theBlockNeed = blockListNeed(size(blockListNeed, 1),:);
            find_idx = size(blockListNeed, 1);
        end
        newPlan = [newPlan, find_idx];
    end

   %% locate container
    if find_avaliable == 1
        newLocatedBlock = {lspace_base, blockList(find_idx, :), theBlockNeed{1}, theBlockNeed{2}};
        solution(size(solution, 1) + 1, :) = newLocatedBlock;
        spaceInfo = newLocatedBlock{4};
        spaceLastInfo = spaceInfo(size(spaceInfo,1), :);
        locateInfo = newLocatedBlock{2};
        hold on;
        draw_container(lspace_base, locateInfo(1:3));
        itervalSpace_s = stack_push(itervalSpace_s, (1-spaceLastInfo(1)) * prod(locateInfo(1:3)));

        if_input = 1;
        % Compute the remaining spaces

        % Remaining space in the H direction
        location = lspace_base;
        location(2) = location(2) + locateInfo(2);
        iterval_space = get_space(location, [locateInfo(1) , lspace_size(2) - locateInfo(2), locateInfo(3)]);
        lspace_s = stack_push(lspace_s, iterval_space);

        % Remaining space in the L direction
        location = lspace_base;
        location(1) = location(1) + locateInfo(1);
        left_space = get_space(location, [lspace_size(1) - locateInfo(1), lspace_size(2), lspace_size(3)]);
        lspace_s = stack_push(lspace_s, left_space);

        % Remaining space in the W direction
        location = lspace_base;
        location(3) = location(3) + locateInfo(3);
        iterval_space = get_space(location, [locateInfo(1) , lspace_size(2), lspace_size(3) - locateInfo(3)]);
        lspace_s = stack_push(lspace_s, iterval_space);
    end

    if if_input == 1

    else
        % Push onto the gap stack
        iterval_s = stack_push(iterval_s, lspace);
        % lspace_s = stack_push(lspace_s, lspace);
    end

end
rate = space_used_rate(bcon, solution);
end

function rate = space_used_rate(container, solution)
    spaceHasTotal = 0.0;
    for i = 1:1:size(solution, 1)
        mergeMessage = solution{i, 4};
        for k = 1:1:size(mergeMessage,1)
            spaceHasTotal = spaceHasTotal + prod(mergeMessage(k, 3:5));
        end
    end
    rate = spaceHasTotal / prod(container);
end
</code></pre><h3 id="block-generation-function">Block Generation Function</h3>
<pre tabindex="0"><code>function [blockTable, boxNeedTable] = simple_block_generate_indepent(container, box, num)

simBlockCount = 0;
simBlockTable = zeros(256, 8);
for type = 1:1:size(box, 1)
    for nx = 1:1:num(type)
        for ny = 1:1:num(type)/nx
           for nz = 1:1:num(type)/ny/nx
                if box(type,3) * nx &lt; container(3) &amp;&amp; box(type, 1) * ny &lt; container(1) &amp;&amp; box(type, 2) * nz &lt; container(2)
                    newSimBlock = [box(type, :), nx, ny, nz, type, prod(box(type, :)) * nx * ny * nz];
                    simBlockTable(simBlockCount + 1, :) = newSimBlock;
                    simBlockCount = simBlockCount + 1;
                end
           end
        end
    end
end

simBlockTable = simBlockTable(1:simBlockCount, :);
simBlockTable = sortrows(simBlockTable, 8);
simBlockTable = simBlockTable(:, 1:7);

% Convert to a format the heuristic algorithm can handle
simBlockTable(:, 13) = ones(size(simBlockTable, 1), 1);

simBlockTable(:, 11) = simBlockTable(:,4) .* simBlockTable(:,3);
simBlockTable(:, 12) = simBlockTable(:,5) .* simBlockTable(:,1);

% ly = ay
simBlockTable(:, 8) = simBlockTable(:, 12);
% lx = ax
simBlockTable(:, 10) = simBlockTable(:, 11);
% lz = lz0 * nz
simBlockTable(:, 9) = simBlockTable(:, 2) .* simBlockTable(:, 6);

boxNeedTable = cell(size(simBlockTable, 1), 2);

for i = 1:1:size(simBlockTable, 1)
    boxNeedTable{i, 1} = zeros(1, size(box ,1));
    boxNeedTable{i, 1}(simBlockTable(i, 7)) = simBlockTable(i, 4) * simBlockTable(i, 5) * simBlockTable(i, 6);
    boxNeedTable{i, 2} = [simBlockTable(i, 7), 0, simBlockTable(i, 8:10)];
end

blockTable = simBlockTable(:, 8:13);
blockTable(:,7) = blockTable(:, 1) .* blockTable(:, 2) .* blockTable(:, 3);
[blockTable, idx] = sortrows(blockTable, [ 7 ]);
boxNeedTable = boxNeedTable(idx, :);
end
</code></pre><h3 id="combined-block-generation-function">Combined Block Generation Function</h3>
<pre tabindex="0"><code>function [blockTable, boxNeedTable] = complex_block_genrate(container, box, num, level)
simBlockTable = simple_block_generate(container, box, num);
simBlockTable(:, 13) = ones(size(simBlockTable, 1), 1);

simBlockTable(:, 11) = simBlockTable(:,4) .* simBlockTable(:,3);
simBlockTable(:, 12) = simBlockTable(:,5) .* simBlockTable(:,1);

spaceUsedRateMin = 0.90;

% ly = ay
simBlockTable(:, 8) = simBlockTable(:, 12);
% lx = ax
simBlockTable(:, 10) = simBlockTable(:, 11);
% lz = lz0 * nz
simBlockTable(:, 9) = simBlockTable(:, 2) .* simBlockTable(:, 6);

boxNeedTable = cell(size(simBlockTable, 1), 2);

for i = 1:1:size(simBlockTable, 1)
    boxNeedTable{i, 1} = zeros(1, size(box ,1));
    boxNeedTable{i, 1}(simBlockTable(i, 7)) = simBlockTable(i, 4) * simBlockTable(i, 5) * simBlockTable(i, 6);
    boxNeedTable{i, 2} = [simBlockTable(i, 7), 0, simBlockTable(i, 8:10)];
end

blockTable = simBlockTable(:, 8:13);
for level = 1:1:level
    newBlockTable = zeros(128,6);
    newBlockCount = 1;
    boxNeedCount = size(boxNeedTable, 1);
    for a = 1:1:size(blockTable,1)
        for b = a:1:size(blockTable, 1)
            if b == a
                continue;
            end

            if blockTable(a, 6) == blockTable(b, 6)
                % Merge along the x direction
                if blockTable(a, 1) == blockTable(a, 5) &amp;&amp; blockTable(a, 3) == blockTable(a, 4) &amp;&amp; blockTable(a, 2) == blockTable(b, 2)
                    tempBlockMerged = [max(blockTable(a,1), blockTable(b,1)), max(blockTable(a,2), blockTable(b, 2)), blockTable(a,3) + blockTable(b,3), blockTable(a,4) + blockTable(b,4), min(blockTable(a,5), blockTable(b,5)), max(blockTable(a, 6), blockTable(b, 6)) + 1];
                    rate = space_used_rate(tempBlockMerged(1:3), blockTable(a,1:3), blockTable(b,1:3));
                    if  rate &gt; spaceUsedRateMin
                        newBlockTable(newBlockCount, :) = tempBlockMerged;
                        boxNeedCount = boxNeedCount + 1;
                        newBlockCount = newBlockCount + 1;

                        boxNeedTable{boxNeedCount, 1} = boxNeedTable{a,1} + boxNeedTable{b,1};
                        boxNeedTable{boxNeedCount, 2} = [boxNeedTable{a, 2}; rate, 1, blockTable(b, 1:3)];
                    end

                end

                % Merge along the y direction
                if blockTable(a, 5) == blockTable(a, 1) &amp;&amp; blockTable(b, 5) == blockTable(b, 1) &amp;&amp; blockTable(a, 2) == blockTable(b, 2)
                    tempBlockMerged = [blockTable(a,1) + blockTable(b,1), max(blockTable(a, 2), blockTable(b, 2)), max(blockTable(a, 3), blockTable(b, 3)), min(blockTable(a, 4), blockTable(b, 4)), blockTable(a, 5) + blockTable(b, 5), max(blockTable(a, 6), blockTable(b, 6)) + 1];
                    rate = space_used_rate(tempBlockMerged(1:3), blockTable(a,1:3), blockTable(b,1:3));
                    if  rate &gt; spaceUsedRateMin
                        newBlockTable(newBlockCount, :) = tempBlockMerged;
                        newBlockCount = newBlockCount + 1;
                        boxNeedCount = boxNeedCount + 1;

                        boxNeedTable{boxNeedCount, 1} = boxNeedTable{a,1} + boxNeedTable{b,1};
                        boxNeedTable{boxNeedCount, 2} = [boxNeedTable{a, 2}; rate, 2, blockTable(b, 1:3)];
                    end
                end

                % Merge along the z direction
                if blockTable(a,4) &gt;= blockTable(b,3) &amp;&amp; blockTable(a, 5) &gt;= blockTable(b, 1)
                   tempBlockMerged = [max(blockTable(a,1), blockTable(b, 1)), blockTable(a, 2) + blockTable(b, 2), max(blockTable(a, 3), blockTable(b, 3)), blockTable(b, 4), blockTable(b, 5), max(blockTable(a, 6), blockTable(b, 6)) + 1];
                   rate = space_used_rate(tempBlockMerged(1:3), blockTable(a,1:3), blockTable(b,1:3));
                   if  rate &gt; spaceUsedRateMin
                       newBlockTable(newBlockCount, :) = tempBlockMerged;
                       newBlockCount = newBlockCount + 1;
                       boxNeedCount = boxNeedCount + 1;

                       boxNeedTable{boxNeedCount, 1} = boxNeedTable{a,1} + boxNeedTable{b,1};
                       boxNeedTable{boxNeedCount, 2} = [boxNeedTable{a, 2}; rate, 3, blockTable(b, 1:3)];
                   end
                end
            end
        end
    end
    blockTable = cat(1, blockTable, newBlockTable(1:newBlockCount-1, :));
    % Remove equivalent complex blocks
    blockTableTemp = blockTable(:, 1:5);
    [~, ia] = unique(blockTableTemp, &#39;stable&#39;, &#39;rows&#39;);
    blockTable = blockTable(ia, :);
    boxNeedTable = boxNeedTable(ia, :);
end
blockTable(:,7) = blockTable(:, 1) .* blockTable(:, 2) .* blockTable(:, 3);
[blockTable, idx] = sortrows(blockTable, [ 7 ]);
boxNeedTable = boxNeedTable(idx, :);
end


function [rate] = space_used_rate(container, box1, box2)
    rate = (prod(box1) + prod(box2)) /prod(container);
end
</code></pre><h3 id="main-function">Main Function</h3>
<pre tabindex="0"><code>ts = 1;
tf = 0.005;
dt = 0.98;
length = 50;
maxSeq = 64;
maxChoice = 1024;

click = 1;

tempRate = [];
tempRateX = [];
numList = [64,64,64,64,64,64,64,128,128,128];
container = StandardISOContainer;

% [blockTable, blockNeed] = complex_block_genrate(StandardISOContainer, Packets, numList, 1);


ps = ones(1, maxSeq);
ps(1) = 1;
[solution, plan, rate] = container_packeting(container, ps, blockTable, blockNeed);
best = plan;
best_rate = rate;
best_solution = solution;
t = ts;

while t &gt; tf
   for i = 1:1:length
      k = randi(size(ps));
      nps = ps;
      nps(k) = randi(maxChoice);
      [solution, nplan, nrate] = container_packeting(container, nps, blockTable, blockNeed);
      % disp([&#39;TempPlan: &#39;, mat2str(nplan)]);
      % fprintf(&#34;TempRate: %f\n&#34;,nrate);
      click = click + 1;
      if nrate &gt; rate
        ps = nps;
        plan = nplan;
        rate = nrate;
        tempRateX = [tempRateX, click];
        tempRate = [tempRate, nrate];
      elseif rand(0, 1) &gt; exp((nrate - rate) * 10 / t)
        ps = nps;
        plan = nplan;
        rate = nrate;
      end

      if nrate &gt; best_rate
          best = nplan;
          best_rate = nrate;
          best_solution = solution;
          disp([&#39;BestPlan: &#39;, mat2str(best)]);
          fprintf(&#34;BestRate: %f\n&#34;,best_rate);
      end
   end
   t = (1 - t * dt) * t;
end

disp([&#39;BestPlan: &#39;, mat2str(best)]);
fprintf(&#34;BestRate: %f\n&#34;,best_rate);
figure(1)
draw_solution(container, best_solution);
figure(2)
plot(tempRateX, tempRate);
save Solution best_solution best_rate tempRateX tempRate
</code></pre>]]></content:encoded></item><item><title>TransRepair: Automatic Testing and Improvement of Machine Translation</title><link>https://blog.bktus.com/en/archives/8cnojv/</link><pubDate>Thu, 30 Sep 2021 16:38:59 +0800</pubDate><guid>https://blog.bktus.com/en/archives/8cnojv/</guid><description>&lt;p>A while ago I read the paper TransRepair: Automatic Testing and Improvement of Machine Translation. It proposes a method called TransRepair, which automatically tests machine translation models from a software testing point of view. Below I&amp;rsquo;ll go through my understanding of it from a few angles.&lt;/p>
&lt;h2 id="introduction-to-transrepair">Introduction to TransRepair&lt;/h2>
&lt;p>TransRepair is a method for automatically detecting and repairing consistency problems in machine translation software. It offers two ways to solve this problem, a black-box one and a gray-box one. Its main steps are generating test cases, building the test oracle and running the automatic repair. The algorithm the paper gives for generating test cases is fairly clear, rigorous and detailed, and it uses four quantification methods to compare the differences between sentences. TransRepair also uses structural consistency as its assertion, the experimental design is fairly thorough, and the results are pretty rich.&lt;/p></description><content:encoded><![CDATA[<p>A while ago I read the paper TransRepair: Automatic Testing and Improvement of Machine Translation. It proposes a method called TransRepair, which automatically tests machine translation models from a software testing point of view. Below I&rsquo;ll go through my understanding of it from a few angles.</p>
<h2 id="introduction-to-transrepair">Introduction to TransRepair</h2>
<p>TransRepair is a method for automatically detecting and repairing consistency problems in machine translation software. It offers two ways to solve this problem, a black-box one and a gray-box one. Its main steps are generating test cases, building the test oracle and running the automatic repair. The algorithm the paper gives for generating test cases is fairly clear, rigorous and detailed, and it uses four quantification methods to compare the differences between sentences. TransRepair also uses structural consistency as its assertion, the experimental design is fairly thorough, and the results are pretty rich.</p>
<h2 id="understanding-the-key-questions">Understanding the Key Questions</h2>
<ol>
<li>A consistency problem is when machine translation software handles a group of sentences that have similar meaning and structure but differ slightly in certain words, and then one or more parts of one or more of the translated sentences turn out to be inconsistent in meaning or structure.</li>
<li>TransRepair generates test cases by replacing words in the input sentence to form a group of mutated sentences. To do this, it uses a word vector model to calculate how closely words are related. After picking a candidate word, it also puts the word into the sentence and runs constituency analysis, to make sure the meaning and grammar of the sentence haven&rsquo;t changed much.</li>
<li>To check whether the output sentence pairs of a test case are consistent, TransRepair first uses Widiff to compare the strings and find the parts that differ. To make the similarity measure more reliable, it also partially deletes the differing parts of the original and translated sentences to build a set, calculates the similarity between the elements of this set and takes the highest value. The paper uses four different methods to quantify similarity, and some of them are similar to the SIT method I mentioned before.</li>
<li>The experimental design in the paper is fairly distinctive. It first raises its questions and discusses how to answer them, then designs experiments around these four questions and presents the data in a suitable form. The experiments show that the method works from several angles, including accuracy, effectiveness, repair ability and a comparison with manual approaches. The data is also presented in a fairly intuitive way that&rsquo;s easy to understand.</li>
<li>TransRepair handles thresholds differently from SIT. It gets a statistically optimal threshold by having the machine go through candidate values in small steps, and it judges consistency with the help of manual checks and statistical analysis. I think this way of setting the threshold is more convincing. SIT, on the other hand, sets its threshold mostly by experience, which is less convincing and harder to apply.</li>
<li>In TransRepair, automatic repair comes in two forms, black-box and gray-box. The black-box form is for Google Translate. Since that software isn&rsquo;t open source, we know little about the parameters behind its input and output, so the repair can only work on the input and output themselves. The gray-box form is for Transformer. Its source code and training set are available, so we can get a handle on the probabilities of its outputs and do the repair on the training set and the model structure.</li>
<li>TransRepair&rsquo;s strength is that it detects and repairs consistency problems automatically. The method is highly accurate, practical and reproducible. I think this has a lot to do with its precise implementation and with the way it takes the flaws of existing methods into account and makes up for them. But the method is fairly inefficient, and it only works for consistency problems.</li>
</ol>
<p>So, to sum up, the TransRepair method proposed in this paper is an effective way to automatically test and improve machine translation software, especially for consistency problems. The paper explains the method in detail and also gives experimental evidence and comparative analysis.</p>
]]></content:encoded></item><item><title>Structure-Invariant Testing for Machine Translation (SIT) Paper Reading Summary</title><link>https://blog.bktus.com/en/archives/drraab/</link><pubDate>Thu, 30 Sep 2021 16:36:04 +0800</pubDate><guid>https://blog.bktus.com/en/archives/drraab/</guid><description>&lt;p>A while ago I read the paper Structure-Invariant Testing for Machine Translation. It proposes a method for detecting robustness problems in machine translation software systems. Below I&amp;rsquo;ll go through my understanding of it from a few angles.&lt;/p>
&lt;h2 id="main-content">Main Content&lt;/h2>
&lt;p>SIT is a method for detecting robustness problems in machine translation software systems. It uses a metamorphic relation from metamorphic testing called “structural invariance”. SIT picks original sentences, generates similar sentences, gets their translations from the translation software, runs constituent parsing to quantify the differences between sentences, and then filters by a preset threshold to find problems. This way it can detect robustness problems in machine translation software systems efficiently. According to the experimental results, SIT can process more than 2k sentences in 19 seconds, and its accuracy on Google Translate and Bing Translate reaches 70%. But there&amp;rsquo;s still room for improvement, probably because of how the threshold is chosen.&lt;/p></description><content:encoded><![CDATA[<p>A while ago I read the paper Structure-Invariant Testing for Machine Translation. It proposes a method for detecting robustness problems in machine translation software systems. Below I&rsquo;ll go through my understanding of it from a few angles.</p>
<h2 id="main-content">Main Content</h2>
<p>SIT is a method for detecting robustness problems in machine translation software systems. It uses a metamorphic relation from metamorphic testing called “structural invariance”. SIT picks original sentences, generates similar sentences, gets their translations from the translation software, runs constituent parsing to quantify the differences between sentences, and then filters by a preset threshold to find problems. This way it can detect robustness problems in machine translation software systems efficiently. According to the experimental results, SIT can process more than 2k sentences in 19 seconds, and its accuracy on Google Translate and Bing Translate reaches 70%. But there&rsquo;s still room for improvement, probably because of how the threshold is chosen.</p>
<h2 id="understanding-several-key-questions">Understanding Several Key Questions</h2>
<ol>
<li>Why does machine translation software have robustness problems? The core modules of machine translation software systems are usually built with deep learning methods or techniques. Each layer of a deep learning model has a high number of dimensions, so the boundaries the trained model draws between different label regions in the vector space can be blurry. When an input is close to one of these boundaries, even a tiny change can make the model&rsquo;s output change drastically.</li>
<li>What is structural invariance? Structural invariance means that if we make some specific, small word-level changes to a sentence in a language, the semantic and syntactic structure of its translation usually stays the same. Structural invariance is an empirical and statistical starting point for studying problems in machine translation software systems.</li>
<li>Why introduce structural invariance? Structural invariance is introduced so we can do metamorphic testing and explore the robustness problems of machine translation software systems. There are two reasons for it. First, the relations and variations in natural language are complex and varied, so it&rsquo;s hard to find a general test theorem to use as a baseline. By controlling variables, we get a starting point that is correct in an empirical or statistical sense, and testing can start from there. Second, test cases for natural language testing are hard to build by hand. With structural invariance, we can easily generate a large number of test cases from a small number of existing samples.</li>
<li>How does SIT use structural invariance to generate sentences that are semantically and syntactically similar? SIT uses the BERT model to generate them. It relies on BERT&rsquo;s training on a large corpus and on techniques like masking and bidirectional feedback learning, so that replacing a word is less likely to change the meaning of the whole sentence or make it ungrammatical or unnatural. SIT also adds a lightweight classifier after BERT to help build the candidate list of replacement words.</li>
<li>How do we quantify the differences between sentences to decide whether a machine translation software system has a robustness problem? SIT uses three methods: string difference analysis, constituent parse tree analysis and dependency parse tree analysis. It runs all three directly on the output of the translation software and compares how well they work. But each of the three methods has its limitations. Future work could look at combining all three to make the decision.</li>
<li>What are SIT&rsquo;s strengths and weaknesses? The authors discuss both in the paper. In general, SIT&rsquo;s strength is that it can detect several types of errors (under-translation, over-translation, incorrect modification and unclear logic). But I think the way it generates test cases, and the way it quantifies and detects errors, are fairly rough, so its accuracy in the experiments isn&rsquo;t very high. Another weakness is that repairs and threshold settings need manual work.</li>
<li>What can SIT be used for? SIT is mainly used for robustness testing of machine translation software systems built on AI models. With SIT&rsquo;s automatic detection plus manually repaired training samples, the robustness of machine translation software can be improved.</li>
</ol>
<h2 id="summary">Summary</h2>
<p>SIT is a method for detecting robustness problems in machine translation software systems. By picking original sentences, generating similar sentences, getting the translations, running constituent parsing and quantifying the differences between sentences, SIT can detect robustness problems in machine translation software systems efficiently. The experimental results show that SIT can process more than 2k sentences in 19 seconds, and its accuracy on Google Translate and Bing Translate reaches 70%. But there&rsquo;s still room for improvement, probably because of how the threshold is chosen. SIT uses the BERT model to generate semantically and syntactically similar sentences, and uses three methods to quantify the differences between sentences. In general, SIT&rsquo;s strength is that it can detect many types of errors, but the way it generates test cases and its detection methods can still be improved. SIT is mainly used for robustness testing of machine translation software systems built on AI models, and it helps improve their robustness through automatic detection and manually repaired training samples.</p>
]]></content:encoded></item><item><title>Solve the problem of oh-my-zsh plugin 'zsh-autosuggestions' not found and plugin 'zsh-syntax-highlighting' not found</title><link>https://blog.bktus.com/en/archives/qvsol9/</link><pubDate>Tue, 25 May 2021 17:49:23 +0800</pubDate><guid>https://blog.bktus.com/en/archives/qvsol9/</guid><description>&lt;p>When we install the zsh plugins zsh-autosuggestions or zsh-syntax-highlighting, we usually run into the oh-my-zsh error “plugin &amp;lsquo;xxx&amp;rsquo; not found”. So let&amp;rsquo;s look at why oh-my-zsh reports “plugin &amp;lsquo;zsh-autosuggestions&amp;rsquo; not found” and “plugin &amp;lsquo;zsh-syntax-highlighting&amp;rsquo; not found”, and how to fix it. The cause is that the plugin&amp;rsquo;s code repository was never cloned to your local machine, so the plugin you want isn&amp;rsquo;t actually installed. The fix is really simple. Just run the following commands:&lt;/p></description><content:encoded><![CDATA[<p>When we install the zsh plugins zsh-autosuggestions or zsh-syntax-highlighting, we usually run into the oh-my-zsh error “plugin &lsquo;xxx&rsquo; not found”. So let&rsquo;s look at why oh-my-zsh reports “plugin &lsquo;zsh-autosuggestions&rsquo; not found” and “plugin &lsquo;zsh-syntax-highlighting&rsquo; not found”, and how to fix it. The cause is that the plugin&rsquo;s code repository was never cloned to your local machine, so the plugin you want isn&rsquo;t actually installed. The fix is really simple. Just run the following commands:</p>
<pre tabindex="0"><code>$ git clone https://github.com/zsh-users/zsh-autosuggestions ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
$ git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
$ source ~/.zshrc
</code></pre><p>Then reopen your shell and you&rsquo;ll see the problem is gone. You can use the same method to fix this kind of problem with other plugins too.</p>
]]></content:encoded></item></channel></rss>