Alex Rosenfeld

Reel Rewrite: How Relm4 Saved My Media Streaming Client

Alex Rosenfeld — Tue, 16 Sep 2025 00:00:00 +0000

A few months ago, I introduced Reel</a>, my native GTK4 media streaming client for GNOME. I was excited about the progress and using it daily. But behind the scenes, I was fighting a losing battle against an architecture that was fundamentally broken. This is the story of how I nearly gave up, discovered Relm4, and rebuilt everything from the ground up.</p>

TL;DR</h2>
After months of battling cascading bugs and an unmaintainable state machine, I rewrote Reel using Relm4</a>. The new architecture uses proper reactive components, message passing, and async workers. The migration is about 85% complete, and the result? Bugs that haunted me for weeks disappeared overnight, and adding features no longer breaks existing functionality. It’s been a journey of three false starts, but the payoff has been worth every refactored line.</p>

When Everything Is Connected to Everything</h2>

The original Reel codebase had become what I call a “spaghetti state machine.” Every component talked to every other component. Fix authentication? Suddenly sync breaks in mysterious ways. Update the cache? The UI starts behaving erratically. Add a new feature? Watch three unrelated things break.</p>

graph TD</span></span>
    UI[UI Components] -->|Direct Access| Cache[Cache/AppState]</span></span>
    UI -->|Mutates| Services[Services]</span></span>
    Services -->|Updates| Cache</span></span>
    Services -->|Calls| UI</span></span>
    Auth[Auth Manager] -->|Modifies| Cache</span></span>
    Auth -->|Triggers| Services</span></span>
    Sync[Sync Manager] -->|Writes to| Cache</span></span>
    Sync -->|Updates| UI</span></span>
    Player[Player] -->|Reads| Cache</span></span>
    Player -->|Notifies| UI</span></span>
    Cache -->|Controls| Everything[Everything Else]</span></span>
</span>
    style Cache fill:#ff6b6b,stroke:#c92a2a</span></span>
    style UI fill:#ffd43b,stroke:#fab005</span></span>
    style Services fill:#ffd43b,stroke:#fab005</span></span></code></pre>
Figure 1: The old architecture - everything connected to everything</em></p>
Here’s what the codebase structure looked like—notice how services were deeply entangled:</p>
src/</span></span>
├── services/           # The problematic service layer</span></span>
│   ├── cache.rs       # God object managing everything</span></span>
│   ├── auth.rs        # Directly manipulates cache</span></span>
│   ├── sync.rs        # Updates UI through cache</span></span>
│   └── player.rs      # Stateful, tightly coupled</span></span>
├── ui/</span></span>
│   ├── windows/       # GTK windows with business logic</span></span>
│   ├── widgets/       # Widgets directly calling services</span></span>
│   └── state.rs       # Global mutable state</span></span>
└── models/            # Data structures mixed with logic</span></span></code></pre>
The problems started from day one with fundamental architectural mistakes:</p>
Wrong Abstractions</h3>
I initially designed around a single backend to Plex. Simple, right? Except users have multiple Plex servers on one account. And then Jellyfin support meant multiple account types. The entire foundation was wrong, and every feature built on top inherited these flaws.</p>
The Cache That Ate Everything</h3>
What started as a simple key-value cache for performance became the backbone of the entire data service. It had to know about every data type in the application—movies, shows, episodes, servers, users, settings. The cache became an accidental god object, orchestrating the entire application state.</p>
Here’s what the old AppState looked like—notice how everything is mutable and interconnected:</p>
// Before: src/core/state.rs - The god object that ruled them all</span></span>
pub struct</span> AppState</span> {</span></span>
    pub</span> auth_manager</span>:</span> Arc</span><</span>AuthManager</span>>,</span></span>
    pub</span> source_coordinator</span>:</span> Arc</span><</span>SourceCoordinator</span>>,</span></span>
    pub</span> current_user</span>:</span> Arc</span><</span>RwLock</span><</span>Option</span><</span>User</span>>>>,</span></span>
    pub</span> current_library</span>:</span> Arc</span><</span>RwLock</span><</span>Option</span><</span>Library</span>>>>,</span></span>
    pub</span> libraries</span>:</span> Arc</span><</span>RwLock</span><</span>HashMap</span><</span>String</span>,</span> Vec</span><</span>Library</span>>>>>,</span></span>
    pub</span> library_items</span>:</span> Arc</span><</span>RwLock</span><</span>HashMap</span><</span>String</span>,</span> Vec</span><</span>MediaItem</span>>>>>,</span></span>
    pub</span> data_service</span>:</span> Arc</span><</span>DataService</span>>,</span></span>
    pub</span> sync_manager</span>:</span> Arc</span><</span>SyncManager</span>>,</span></span>
    pub</span> playback_state</span>:</span> Arc</span><</span>RwLock</span><</span>PlaybackState</span>>>,</span></span>
    pub</span> config</span>:</span> Arc</span><</span>RwLock</span><</span>Config</span>>>,</span></span>
    pub</span> database</span>:</span> Arc</span><</span>Database</span>>,</span></span>
    pub</span> db_connection</span>:</span> DatabaseConnection</span>,</span></span>
    pub</span> event_bus</span>:</span> Arc</span><</span>EventBus</span>>,</span></span>
}</span></span>
</span>
// UI components directly mutated this shared state</span></span>
impl</span> AppState</span> {</span></span>
    pub async fn</span> set_library</span>(</span>&</span>self</span>, library</span>:</span> Library</span>) {</span></span>
        let mut</span> current_library</span> =</span> self</span>.</span>current_library</span>.</span>write</span>()</span>.await</span>;</span></span>
        *</span>current_library</span> =</span> Some</span>(library);</span></span>
    }</span></span>
</span>
    pub async fn</span> sync_all_backends</span>(</span>&</span>self</span>)</span> -></span> Result</span><</span>Vec</span><</span>SyncResult</span>>> {</span></span>
        // Direct coordination between services</span></span>
        let</span> all_backends</span> =</span> self</span>.</span>source_coordinator</span>.</span>get_all_backends</span>()</span>.await</span>;</span></span>
        // ... sync logic mixed with state management ...</span></span>
    }</span></span>
}</span></span></code></pre>
Every bug fix made it worse. Every feature made it more entangled.</p>
The False Hope of Home-Grown Reactivity</h2>
Desperate for a solution, I introduced reactivity with an event bus and a property system. The idea was sound: components would react to state changes instead of directly manipulating each other. For a brief, glorious moment, it felt like salvation.</p>
I went all in, converting code piece by piece to this new system. UI components would update through ViewModels. State changes would propagate through events. It was going to fix everything.</p>
It didn’t.</p>
What I ended up with was worse—a hybrid monster with half the code using the old direct manipulation and half using my buggy home-grown property system. The reactive parts had their own bugs. The boundaries between old and new code were unclear. I’d created two problems instead of solving one.</p>
The Breaking Point</h2>
The moment I knew something had to change was when I broke the video player—again. This was supposed to be the stable part of the application, carefully designed and tested. But a seemingly unrelated change to the authentication flow cascaded through the system and broke video playback in a way I couldn’t even understand.</p>
I was tired. Really tired.</p>
Enter Relm4</h2>
That’s when I discovered Relm4</a>. It’s a reactive GTK4 framework for Rust that provides proper component architecture, message passing, and state management. Reading through the documentation felt like finding exactly what I’d been trying to build myself, but actually working.</p>
But I hesitated. A lot.</p>
Two False Starts</h3>
Twice I started converting code to Relm4. Twice I gave up. The problem wasn’t Relm4—it was that I was trying to retrofit it onto a broken architecture. I was putting lipstick on a pig.</p>
The service layer I’d built was inherently stateful and completely incompatible with Relm4’s functional approach. The cache system fought against proper component isolation. Every conversion attempt hit the same walls because I was trying to preserve too much of the old code.</p>
Going All In</h2>
One particularly frustrating evening, after breaking the video player yet again while trying to add a minor feature, something snapped. I decided to burn it all down and rebuild from scratch using Relm4 properly.</p>
This meant:</p>

Throwing away the entire service layer</li>
Deleting the god-object cache</li>
Redesigning the data flow from first principles</li>
Starting with the correct abstractions this time</li>
</ul>
The actual rewrite happened remarkably fast. Over the course of just a few days, I implemented the core components: the MessageBroker for sync integration, a complete UI overhaul with modern Adwaita design, an immersive player with proper window chrome management, and thread-safe player communication using channels.</p>
The New Architecture</h2>
The rewrite brought clarity. With Relm4, I could finally map concepts to architecture the right way.</p>
graph TD</span></span>
    subgraph "UI Layer (Relm4 Components)"</span></span>
        MW[MainWindow]</span></span>
        HP[HomePage]</span></span>
        PP[PlayerPage]</span></span>
        LP[LibraryPage]</span></span>
    end</span></span>
</span>
    subgraph "Message System"</span></span>
        MB[MessageBroker]</span></span>
    end</span></span>
</span>
    subgraph "Business Logic"</span></span>
        PC[PlayerController]</span></span>
        SM[SyncManager]</span></span>
        AM[AuthManager]</span></span>
    end</span></span>
</span>
    subgraph "Data Layer"</span></span>
        DB[(Database)]</span></span>
        Repo[Repositories]</span></span>
    end</span></span>
</span>
    MW -->|Message| MB</span></span>
    HP -->|Subscribe| MB</span></span>
    PP -->|Subscribe| MB</span></span>
    LP -->|Subscribe| MB</span></span>
</span>
    MB -->|Broadcast| HP</span></span>
    MB -->|Broadcast| PP</span></span>
    MB -->|Broadcast| LP</span></span>
</span>
    PP -->|Commands| PC</span></span>
    PC -->|Response| PP</span></span>
</span>
    SM -->|Notify| MB</span></span>
    AM -->|Notify| MB</span></span>
</span>
    Repo -->|Query| DB</span></span>
    SM -->|Use| Repo</span></span>
</span>
    style MB fill:#51cf66,stroke:#37b24d</span></span>
    style MW fill:#74c0fc,stroke:#339af0</span></span>
    style HP fill:#74c0fc,stroke:#339af0</span></span>
    style PP fill:#74c0fc,stroke:#339af0</span></span>
    style LP fill:#74c0fc,stroke:#339af0</span></span></code></pre>
Figure 2: The new architecture - clean message-based communication</em></p>
Here’s the new structure—notice the clean separation of concerns:</p>
src/</span></span>
├── backends/            # Backend implementations (Plex, Jellyfin)</span></span>
│   ├── traits.rs       # Clean interface definitions</span></span>
│   ├── plex/           # Plex-specific logic only</span></span>
│   └── jellyfin/       # Jellyfin-specific logic only</span></span>
├── platforms/</span></span>
│   └── relm4/</span></span>
│       └── components/ # Isolated UI components</span></span>
│           ├── main_window.rs</span></span>
│           ├── pages/  # Each page is a component</span></span>
│           └── shared/</span></span>
│               ├── broker.rs    # Central message passing</span></span>
│               ├── messages.rs  # Message types</span></span>
│               └── commands.rs  # Async workers</span></span>
├── player/</span></span>
│   ├── controller.rs   # Thread-safe controller</span></span>
│   └── factory.rs      # Player abstraction</span></span>
└── db/                  # Clean data layer</span></span>
    ├── entities/       # Database models</span></span>
    └── repository/     # Data access patterns</span></span></code></pre>Async Components</h3>
Each major UI element is now a proper component with its own state, update logic, and message handling. Components don’t know about each other—they communicate through messages. Worker components handle heavy tasks like image loading and search operations without blocking the UI.</p>
Message Broker</h3>
Instead of direct component communication, there’s now a central message broker. Components publish events; interested parties subscribe. Clean boundaries, clear data flow. The MessageBroker handles sync integration and eliminates race conditions that plagued the old architecture.</p>
// After: src/platforms/relm4/components/shared/broker.rs</span></span>
#[derive(</span>Debug</span>,</span> Clone</span>)]</span></span>
pub enum</span> BrokerMessage</span> {</span></span>
    Navigation</span>(</span>NavigationMessage</span>),</span></span>
    Data</span>(</span>DataMessage</span>),</span></span>
    Playback</span>(</span>PlaybackMessage</span>),</span></span>
    Source</span>(</span>SourceMessage</span>),</span></span>
}</span></span>
</span>
// Components subscribe to specific messages</span></span>
impl</span> AsyncComponentParts</span> for</span> HomePage</span> {</span></span>
    fn</span> init</span>() {</span></span>
        // Subscribe to broker messages</span></span>
        let</span> broker_sender</span> =</span> sender</span>.</span>clone</span>();</span></span>
        relm4</span>::</span>spawn</span>(</span>async move</span> {</span></span>
            BROKER</span>.</span>subscribe</span>(</span>"HomePage"</span>.</span>to_string</span>(), broker_sender)</span>.await</span>;</span></span>
        });</span></span>
    }</span></span>
</span>
    fn</span> update</span>(</span>&mut</span> self</span>, msg</span>:</span> Input</span>) {</span></span>
        match</span> msg {</span></span>
            Input</span>::</span>BrokerMsg</span>(BrokerMessage</span>::</span>Data</span>(DataMessage</span>::</span>LibraryUpdated</span> {</span> ..</span> }))</span> =></span> {</span></span>
                // React to library updates without direct coupling</span></span>
                self</span>.</span>refresh_content</span>();</span></span>
            }</span></span>
            _</span> =></span> {}</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>Thread-Safe Player Controller</h3>
The video player now uses a channel-based PlayerController with PlayerHandle and PlayerCommand patterns. This eliminates all the threading issues that made the player so fragile before. The immersive mode properly manages window chrome and cursor hiding.</p>
sequenceDiagram</span></span>
    participant UI as UI Component</span></span>
    participant H as PlayerHandle</span></span>
    participant C as Controller Thread</span></span>
    participant P as Player Backend</span></span>
</span>
    UI->>H: load_media(url)</span></span>
    H->>H: Create oneshot channel</span></span>
    H->>C: Send PlayerCommand::LoadMedia</span></span>
    C->>P: Initialize player</span></span>
    P-->>C: Success</span></span>
    C-->>H: Send Result via channel</span></span>
    H-->>UI: Return Result</span></span>
</span>
    Note over UI,P: All communication is async and thread-safe</span></span></code></pre>
Figure 3: Thread-safe player communication flow</em></p>
// After: src/player/controller.rs - Thread-safe player communication</span></span>
#[derive(</span>Debug</span>)]</span></span>
pub enum</span> PlayerCommand</span> {</span></span>
    LoadMedia</span> {</span></span>
        url</span>:</span> String</span>,</span></span>
        respond_to</span>:</span> oneshot</span>::</span>Sender</span><</span>Result</span><()>>,</span></span>
    },</span></span>
    Play</span> {</span></span>
        respond_to</span>:</span> oneshot</span>::</span>Sender</span><</span>Result</span><()>>,</span></span>
    },</span></span>
    Seek</span> {</span></span>
        position</span>:</span> Duration</span>,</span></span>
        respond_to</span>:</span> oneshot</span>::</span>Sender</span><</span>Result</span><()>>,</span></span>
    },</span></span>
    // ... more commands with response channels</span></span>
}</span></span>
</span>
// Clean handle for UI components</span></span>
pub struct</span> PlayerHandle</span> {</span></span>
    sender</span>:</span> mpsc</span>::</span>Sender</span><</span>PlayerCommand</span>>,</span></span>
}</span></span>
</span>
impl</span> PlayerHandle</span> {</span></span>
    pub async fn</span> load_media</span>(</span>&</span>self</span>, url</span>:</span> String</span>)</span> -></span> Result</span><()> {</span></span>
        let</span> (tx, rx)</span> =</span> oneshot</span>::</span>channel</span>();</span></span>
        self</span>.</span>sender</span></span>
            .</span>send</span>(PlayerCommand</span>::</span>LoadMedia</span> { url, respond_to</span>:</span> tx })</span></span>
            .await?</span>;</span></span>
        rx</span>.await?</span></span>
    }</span></span>
</span>
    // No shared mutable state, just message passing</span></span>
}</span></span></code></pre>
Compare this to the old player design where UI components directly manipulated player state through Arc<RwLock<>> patterns, leading to deadlocks and race conditions.</p>
Proper State Management</h3>
State lives where it belongs. UI state in components, server data in dedicated stores, settings in a configuration manager. The reactive property system provides observable data without the complexity of the home-grown solution.</p>
Here’s a complete Relm4 component showing the new pattern:</p>
// After: Clean component with isolated state and message passing</span></span>
pub struct</span> MainWindow</span> {</span></span>
    db</span>:</span> DatabaseConnection</span>,</span></span>
    sidebar</span>:</span> Controller</span><</span>Sidebar</span>>,</span></span>
    home_page</span>:</span> AsyncController</span><</span>HomePage</span>>,</span></span>
    player_page</span>:</span> Option</span><</span>AsyncController</span><</span>PlayerPage</span>>>,</span></span>
    navigation_view</span>:</span> adw</span>::</span>NavigationView</span>,</span></span>
}</span></span>
</span>
#[derive(</span>Debug</span>)]</span></span>
pub enum</span> MainWindowInput</span> {</span></span>
    Navigate</span>(</span>NavigationTarget</span>),</span></span>
    BrokerMsg</span>(</span>BrokerMessage</span>),</span></span>
    ShowPlayerPage</span>(</span>MediaItemId</span>,</span> PlaylistContext</span>),</span></span>
    UpdateWindowChrome</span> { fullscreen</span>:</span> bool</span> },</span></span>
}</span></span>
</span>
impl</span> AsyncComponent</span> for</span> MainWindow</span> {</span></span>
    type</span> Input</span> =</span> MainWindowInput</span>;</span></span>
    type</span> Output</span> =</span> ();</span></span>
</span>
    async fn</span> update</span>(</span>&mut</span> self</span>, msg</span>:</span> Self</span>::</span>Input</span>, sender</span>:</span> AsyncComponentSender</span><</span>Self</span>>) {</span></span>
        match</span> msg {</span></span>
            MainWindowInput</span>::</span>Navigate</span>(target)</span> =></span> {</span></span>
                // Clean navigation without side effects</span></span>
                self</span>.</span>navigate_to</span>(target)</span>.await</span>;</span></span>
            }</span></span>
            MainWindowInput</span>::</span>ShowPlayerPage</span>(media_id, context)</span> =></span> {</span></span>
                // Create isolated player component</span></span>
                let</span> player</span> =</span> PlayerPage</span>::</span>builder</span>()</span></span>
                    .</span>launch</span>(</span>PlayerPageInit</span> { media_id, context })</span></span>
                    .</span>forward</span>(sender</span>.</span>input_sender</span>(),</span> |</span>msg</span>|</span> {</span></span>
                        MainWindowInput</span>::</span>BrokerMsg</span>(msg</span>.</span>into</span>())</span></span>
                    });</span></span>
                self</span>.</span>player_page </span>=</span> Some</span>(player);</span></span>
            }</span></span>
            MainWindowInput</span>::</span>UpdateWindowChrome</span> { fullscreen }</span> =></span> {</span></span>
                // UI updates are explicit and traceable</span></span>
                self</span>.</span>set_chrome_visibility</span>(</span>!</span>fullscreen);</span></span>
            }</span></span>
            _</span> =></span> {}</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
Compare this to the old GTK approach with its 150+ lines of wrapper enums and direct state manipulation. Each Relm4 component is self-contained, testable, and communicates only through messages.</p>
The Payoff</h2>
The difference has been night and day. Let me show you the numbers:</p>
graph LR</span></span>
    subgraph "Before"</span></span>
        B1[15+ Critical Bugs]</span></span>
        B2[3-4 Days per Feature]</span></span>
        B3[~50% Time Debugging]</span></span>
        B4[UI Freezes Common]</span></span>
    end</span></span>
</span>
    subgraph "After"</span></span>
        A1[2 Known Issues]</span></span>
        A2[<1 Day per Feature]</span></span>
        A3[~10% Time Debugging]</span></span>
        A4[Zero UI Freezes]</span></span>
    end</span></span>
</span>
    B1 -.->|🎉| A1</span></span>
    B2 -.->|🚀| A2</span></span>
    B3 -.->|✨| A3</span></span>
    B4 -.->|⚡| A4</span></span>
</span>
    style A1 fill:#51cf66,stroke:#37b24d</span></span>
    style A2 fill:#51cf66,stroke:#37b24d</span></span>
    style A3 fill:#51cf66,stroke:#37b24d</span></span>
    style A4 fill:#51cf66,stroke:#37b24d</span></span>
    style B1 fill:#ff6b6b,stroke:#c92a2a</span></span>
    style B2 fill:#ff6b6b,stroke:#c92a2a</span></span>
    style B3 fill:#ff6b6b,stroke:#c92a2a</span></span>
    style B4 fill:#ff6b6b,stroke:#c92a2a</span></span></code></pre>
Figure 4: The dramatic improvement in development metrics</em></p>
Concrete Improvements</h3>

Bugs disappeared</strong>: Issues that had plagued the project for months just vanished. Proper component isolation meant fixes stayed fixed.</li>
Features don’t break things</strong>: Adding new functionality no longer feels like playing Jenga. Components are isolated; changes don’t cascade.</li>
Code is maintainable</strong>: I can now look at a component and understand it without needing to trace through five other files.</li>
Async actually works</strong>: Proper async components mean no more UI freezes during sync operations.</li>
</ul>
What’s Left</h2>
The migration is about 85% complete, with core functionality working but some polish needed:</p>
Working:</strong></p>

Plex and Jellyfin server connections</li>
Media browsing and playback</li>
The new Adwaita UI with theme support</li>
Thread-safe player with immersive mode</li>
Reactive components and message passing</li>
</ul>
Still In Progress:</strong></p>

Jellyfin sync completion</li>
Seek functionality refinement</li>
Keyboard shortcuts</li>
Some UI polish and missing features</li>
Library view optimizations</li>
</ul>
But here’s the crucial difference: these are implementation tasks, not architectural battles. The foundation is solid. With 70+ tasks tracked in the backlog, I can methodically work through features knowing each addition won’t destabilize the entire system.</p>
Lessons Learned</h2>
This rewrite taught me some hard lessons:</p>


Wrong abstractions compound</strong>: Every feature built on a bad foundation makes things exponentially worse.</p>
</li>

Home-grown frameworks are rarely the answer</strong>: Unless you’re solving a genuinely unique problem, use battle-tested solutions.</p>
</li>

Sometimes you need to start over</strong>: I wasted months trying to fix unfixable architecture. The rewrite took weeks and solved everything.</p>
</li>

Functional components work</strong>: The Relm4 approach of isolated components with message passing isn’t just theory—it actually makes complex UIs manageable.</p>
</li>
</ol>
Looking Forward</h2>
With a solid foundation, I can finally focus on what matters: features and user experience. The roadmap from the original post</a> is still valid, but now it’s actually achievable.</p>
The next few releases will bring:</p>

Completed Jellyfin support</li>
Search and filtering</li>
Local file playback</li>
Music library support</li>
</ul>
But more importantly, I can now add these features with confidence that they won’t break everything else.</p>
For Fellow Developers</h2>
mindmap</span></span>
  root((Architecture Rewrite))</span></span>
    Signs You Need It</span></span>
      Every fix breaks something else</span></span>
      Features take exponentially longer</span></span>
      You dread touching the code</span></span>
      Simple changes require complex workarounds</span></span>
</span>
    The Right Approach</span></span>
      Accept the current design is broken</span></span>
      Choose battle-tested frameworks</span></span>
      Start completely fresh</span></span>
      Focus on architecture first</span></span>
</span>
    Relm4 Benefits</span></span>
      True component isolation</span></span>
      Message-based communication</span></span>
      Async that actually works</span></span>
      Testable by design</span></span>
</span>
    The Payoff</span></span>
      10x faster feature development</span></span>
      Bugs stay fixed</span></span>
      Code is enjoyable again</span></span>
      Confidence in changes</span></span></code></pre>
Figure 6: Should you rewrite? A decision framework</em></p>
If you’re fighting your architecture daily, if every bug fix creates two new problems, if you dread adding features because of what might break—consider a rewrite. Not a refactor, not a gradual migration, but a ground-up rebuild with the right tools.</p>
Yes, it’s scary. Yes, you’ll lose some work. But the alternative is death by a thousand cuts, slowly losing the will to work on your project as it becomes increasingly unmaintainable.</p>
For GTK4 and Rust developers specifically: give Relm4</a> a serious look. It’s not just another framework—it’s a fundamentally better way to build reactive UIs.</p>

Reel is available on GitHub</a>. The Relm4 migration is 85% complete and already more stable than the original ever was. Downloads are available as AppImage, .deb, and .rpm packages. Built with Rust, GTK4, Relm4, libadwaita, and hard-won lessons about software architecture.</em></p>



Reel: Bringing Native Media Streaming to the GNOME Desktop
Alex Rosenfeld — Mon, 25 Aug 2025 00:00:00 +0000

  
</div>
It’s always been a dream of mine to have a proper, native media streaming client for GNOME. Not a web wrapper, not a half-maintained GTK3 app from years ago, but a real, modern, performant application that feels like it belongs on my desktop. After years of waiting and watching the landscape, I decided to build it myself. Enter Reel</a>.</p>
TL;DR</h2>
Reel</a> is a native GTK4 media streaming client for GNOME that supports Plex and Jellyfin. Built with Rust, it offers multiple video backends (GStreamer and MPV), handles large libraries, and feels like a proper desktop app—not another web wrapper. Still in active development but already my daily driver for watching movies and shows.</p>
Why Build This?</h2>
Let’s be honest about where we stand today with media streaming on the Linux desktop. It’s… not great.</p>


Girens</strong>: Was a GTK-based Plex client that showed what was possible with native integration. While I haven’t tried it in years, at the time the design felt dated and it didn’t quite hit the mark for what I was looking for in a modern media client.</p>
</li>

Official Plex App</strong>: Exists for Linux and works fine, though it’s essentially an Electron wrapper around their web app. It gets the job done but doesn’t feel native to the desktop.</p>
</li>

Infuse</strong>: On macOS, I use Infuse</a> daily—it’s a fantastic native media client that shows what’s possible with proper desktop integration. It’s been my inspiration for what a Linux media app could be.</p>
</li>
</ul>
Well, now we’re building it.</p>
</a></p>
Building Reel: The Technical Journey</h2>
Why Rust?</h3>
Why not? 🦀</p>
The Architecture: Flexibility First</h3>
One of my key design decisions was to build a multi-backend architecture from day one. I didn’t want to create “just another Plex client”—I wanted to build a media streaming platform for GNOME that could adapt to whatever service users prefer. Each service (Plex, Jellyfin, and eventually local files) implements a common interface, making the UI completely agnostic about where the media comes from.</p>
The Player Backend Saga</h3>
Here’s where things got interesting. Video playback on Linux is… complicated.</p>
GStreamer is the obvious choice for GTK applications—it’s lighter on resources, well-integrated with the GNOME stack, and powerful. However, I hit a frustrating wall: subtitle rendering. On my machine, GStreamer has colorspace issues with certain subtitle formats that make them nearly unreadable.</p>
As a pragmatic solution, I added support for multiple player backends. Now Reel ships with both:</p>

GStreamer</strong>: The preferred backend—lighter and better integrated with GNOME</li>
MPV</strong>: A fallback option that handles subtitles correctly while we work on fixing the GStreamer issue</li>
</ul>
Once the subtitle bug is resolved, MPV will purely be a fallback option, but for now this flexibility ensures everyone can enjoy their media regardless of subtitle formats.</p>
</a></p>
The Jellyfin Milestone</h2>
Just this week (v0.3.0), I reached a personal milestone: Jellyfin support. This wasn’t just about adding another backend—it was about proving the architecture works.</p>
Jellyfin represents something important in the media server space: true open-source freedom. While Plex is great, having an open alternative that users can self-host without restrictions matters. The implementation came together surprisingly smoothly, validating the multi-backend design.</p>
Now users can:</p>

Connect to multiple servers (Plex and Jellyfin)</li>
Switch between them seamlessly</li>
Use the same intuitive interface regardless of the backend</li>
</ul>
</a></p>
Current Challenges and Solutions</h2>
There are plenty of bugs still to squash, but I’m already using it as my daily driver to watch movies and shows. Here are the main areas I’m working on:</p>
The Subtitle Situation</h3>
As mentioned, GStreamer subtitle rendering has some colorspace issues that I’m investigating. The MPV backend provides a workaround for now, but fixing the GStreamer issue properly is a priority—it’s the better integrated solution for GNOME.</p>
Performance Optimization</h3>
Loading large libraries can still feel sluggish. I’m working on:</p>

Better caching strategies with SQLite</li>
Predictive prefetching for smoother browsing</li>
Investigating why Jellyfin is hit particularly hard when loading libraries</li>
Fixing MPV backend smoothness under system load (can show skipped frames occasionally)</li>
</ul>
Feature Parity</h3>
Compared to official clients, we’re still missing:</p>

Advanced search filters</li>
Music library support (also on the roadmap)</li>
Displaying cast and crew information</li>
Marking episodes as watched</li>
Downloading subtitles (you can select them in the player already)</li>
Tons of small features that official clients have</li>
</ul>
The Road Ahead</h2>
Looking at my TASKS.md</a>, the focus is on polish and usability:</p>
Near Term (Next Few Releases)</h3>

Search functionality</strong>: Full-text search across all your media</li>
Filtering and sorting</strong>: Better ways to browse large libraries</li>
Performance optimizations</strong>: Faster loading and smoother scrolling</li>
Bug fixes and polish</strong>: Making the experience more reliable</li>
Meson build system</strong>: Adding support to fully integrate with the GNOME ecosystem, including translations</li>
</ul>
Medium Term</h3>

Local files backend</strong>: For your personal collection</li>
Music support</strong>: Because media isn’t just video</li>
Flatpak distribution</strong>: Easy installation for everyone (PR in progress</a>)</li>
</ul>
The Role of LLMs in Building This</h2>
I need to be honest about something: without LLMs, I wouldn’t have gotten even close to this far with Reel. Whatever your opinion on AI tools, there’s no denying they’ve made side projects like this dramatically more feasible.</p>
As a parent, my coding time is precious—usually just those quiet hours after the kids are asleep. LLMs have been invaluable for:</p>

Getting the basic project up and running with Rust and GTK4</li>
Debugging those cryptic GStreamer errors at 11 PM</li>
Refactoring code became so much easier—we can try different approaches very quickly and discard anything that doesn’t work</li>
The MPV backend was only possible because of AI—I wouldn’t have known where to start, and even once the code was in place, it took forever to get the flow of GLArea and MPV to work just right</li>
</ul>
More importantly, they’ve helped maintain momentum. When you’re exhausted after a full day and finally sit down to code, having an AI assistant to help push through blockers makes the difference between making progress and giving up for the night. It’s brought back some of the joy and motivation to work on passion projects, even when time and energy are limited.</p>
One lesson learned is how to interact with the community when using AI. I made the pull request to Flathub using an LLM, and while I did read all the Flathub documentation myself and thought I had a good grasp of the process, the PR had a template that you could only see if you opened it through the web. Instead, I asked the AI to open it through the command-line and it wasn’t well received that a chatbot had written the PR. I understand the frustration—it’s hard to draw the line of what AI should and shouldn’t do.</p>
Get Involved</h2>
Reel is still in active development, and I’d love your help:</p>

Try it out</strong>: Install from GitHub</a> and report your experience</li>
Report bugs</strong>: Every issue helps make it better</li>
Contribute code</strong>: Whether it’s features, fixes, or translations</li>
Spread the word</strong>: Let other Linux users know there’s a native option</li>
</ul>
The project is 100% open source, built with Rust and GTK4, and designed to be hackable. Whether you want to add a new backend, improve the UI, or optimize performance, there’s room for your contributions.</p>

Reel is available on GitHub</a>. Currently supporting Plex and Jellyfin, with more backends on the way. Built with Rust, GTK4, and love for the Linux desktop.</em></p>


Monitor Per-Client Network Usage with Custom Metrics
Alex Rosenfeld — Tue, 22 Jul 2025 00:00:00 +0000
Part 3 of the NixOS Router Series</em></p>
Ever wondered which device is hogging all your bandwidth? In this guide, we’ll set up comprehensive monitoring for your NixOS router that tracks exactly how much data each client uses in real-time. By the end, you’ll have beautiful dashboards showing per-device bandwidth usage, connection counts, and network trends.</p>
What Makes This Special?</h2>
Most router monitoring solutions give you aggregate statistics - total bandwidth in and out. That’s useful, but it doesn’t tell you that your smart TV is downloading 50GB of updates at 3 AM, or that your teenager’s gaming PC is saturating your upload bandwidth.</p>
Our custom network-metrics-exporter</a> solves this by:</p>

Tracking bandwidth per individual client IP</li>
Maintaining persistent client names across reboots</li>
Integrating directly with nftables for accurate counts</li>
Exposing everything as Prometheus metrics</li>
Zero performance impact on your routing</li>
</ul>
Prerequisites</h2>

A working NixOS router (from Part 1</a>)</li>
Your router configuration in a flake (as introduced in Part 2</a>)</li>
Basic familiarity with NixOS configuration</li>
About 45 minutes</li>
</ul>
Step 1: Set Up Basic Monitoring Stack</h2>
First, let’s get Prometheus and Grafana running on your router.</p>
Enable Prometheus</h3>
Add to your router configuration:</p>
# configuration.nix</span></span>
{</span></span>
  services</span>.</span>prometheus</span> =</span> {</span></span>
    enable</span> =</span> true</span>;</span></span>
    port</span> =</span> 9090</span>;</span></span>
    </span></span>
    # Scrape metrics every 15 seconds</span></span>
    globalConfig</span> =</span> {</span></span>
      scrape_interval</span> =</span> "15s"</span>;</span></span>
      evaluation_interval</span> =</span> "15s"</span>;</span></span>
    };</span></span>
    </span></span>
    # Start with just local node metrics</span></span>
    scrapeConfigs</span> =</span> [</span></span>
      {</span></span>
        job_name</span> =</span> "node"</span>;</span></span>
        static_configs</span> =</span> [{</span></span>
          targets</span> =</span> [</span> "localhost:9100"</span> ];</span></span>
        }];</span></span>
      }</span></span>
    ];</span></span>
  };</span></span>
  </span></span>
  # Enable node exporter for system metrics</span></span>
  services</span>.</span>prometheus</span>.</span>exporters</span>.</span>node</span> =</span> {</span></span>
    enable</span> =</span> true</span>;</span></span>
    port</span> =</span> 9100</span>;</span></span>
    enabledCollectors</span> =</span> [</span></span>
      "systemd"</span></span>
      "diskstats"</span></span>
      "filesystem"</span></span>
      "loadavg"</span></span>
      "meminfo"</span></span>
      "netdev"</span></span>
      "stat"</span></span>
      "time"</span></span>
      "uname"</span></span>
    ];</span></span>
  };</span></span>
}</span></span></code></pre>Enable Grafana</h3>
Add Grafana for visualization:</p>
{</span></span>
  services</span>.</span>grafana</span> =</span> {</span></span>
    enable</span> =</span> true</span>;</span></span>
    settings</span> =</span> {</span></span>
      server</span> =</span> {</span></span>
        http_addr</span> =</span> "0.0.0.0"</span>;</span></span>
        http_port</span> =</span> 3000</span>;</span></span>
        domain</span> =</span> "192.168.1.1"</span>;</span></span>
      };</span></span>
      </span></span>
      # Disable analytics</span></span>
      analytics</span>.</span>reporting_enabled</span> =</span> false</span>;</span></span>
      </span></span>
      # Anonymous access for read-only dashboards</span></span>
      "auth.anonymous"</span> =</span> {</span></span>
        enabled</span> =</span> true</span>;</span></span>
        org_role</span> =</span> "Viewer"</span>;</span></span>
      };</span></span>
    };</span></span>
    </span></span>
    # Automatically configure Prometheus datasource</span></span>
    provision</span> =</span> {</span></span>
      datasources</span>.</span>settings</span>.</span>datasources</span> =</span> [{</span></span>
        name</span> =</span> "Prometheus"</span>;</span></span>
        type</span> =</span> "prometheus"</span>;</span></span>
        url</span> =</span> "http://localhost:9090"</span>;</span></span>
        isDefault</span> =</span> true</span>;</span></span>
      }];</span></span>
    };</span></span>
  };</span></span>
}</span></span></code></pre>Open Firewall Ports</h3>
Allow access from your LAN:</p>
{</span></span>
  networking</span>.</span>firewall</span>.</span>interfaces</span>.</span>"br-lan"</span> =</span> {</span></span>
    allowedTCPPorts</span> =</span> [</span> 3000 9090</span> ];</span></span>
  };</span></span>
}</span></span></code></pre>
Deploy and verify:</p>
# Update flake inputs to get the module</span></span>
nix</span> flake update</span></span>
</span>
# Build and switch to the new configuration</span></span>
sudo</span> nixos-rebuild switch</span> --flake</span> .</span></span>
</span>
# Verify services</span></span>
curl</span> http://192.168.1.1:3000</span>  # Should see Grafana login</span></span></code></pre>Step 2: Deep Dive - network-metrics-exporter</a></h2>
Now for the star of the show - our custom metrics exporter that makes per-client tracking possible.</p>
What Makes This Exporter Special</h3>
Traditional exporters read from /proc/net/dev</code> or similar, giving you interface-level statistics. The network-metrics-exporter</a> is a purpose-built Go program that provides granular, per-client network statistics with minimal overhead.</p>
Key differences from standard exporters:</strong></p>

Per-client granularity</strong> - Tracks individual devices, not just interfaces</li>
Zero packet loss</strong> - Uses kernel-level counters, not sampling</li>
Connection tracking</strong> - Shows active connections per client</li>
Persistent device names</strong> - Remembers friendly names across reboots</li>
Efficient design</strong> - Written in Go for minimal resource usage</li>
</ol>
Architecture Overview</h3>
The exporter consists of two main components working together:</p>
1. The Go Exporter (network-metrics-exporter</code></a>)</h4>
The main program is written in Go and handles:</p>

Prometheus endpoint</strong> - Serves metrics on port 9101</li>
State management</strong> - Maintains persistent client names in /var/lib/network-metrics</code></li>
Metric collection</strong> - Reads counters and connection tracking data</li>
DHCP integration</strong> - Optionally reads DHCP leases for automatic naming</li>
</ul>
2. The Supporting Service</h4>
client-traffic-tracker.service</code></strong> - A bash script that runs when enableNftablesIntegration = true</code>:</p>

Discovers active clients on your network using ARP and connection tracking</li>
Creates nftables accounting rules for each client IP</li>
Monitors for new devices every 60 seconds</li>
Maintains the CLIENT_TRAFFIC</code> chain in nftables</li>
</ul>
How nftables Integration Works</h3>
When you set enableNftablesIntegration = true</code>, the module sets up sophisticated packet accounting:</p>
1. Accounting Tables</h4>
The system creates dedicated nftables tables for metrics:</p>
table inet filter {</span></span>
    chain CLIENT_TRAFFIC {</span></span>
        # TX rules - count outgoing traffic per source IP</span></span>
        ip saddr 192.168.1.105 counter packets 41234 bytes 3234122 comment "tx_192.168.1.105"</span></span>
        ip saddr 192.168.1.122 counter packets 8934 bytes 987123 comment "tx_192.168.1.122"</span></span>
        ip saddr 192.168.1.150 counter packets 72819 bytes 8234122 comment "tx_192.168.1.150"</span></span>
        </span></span>
        # RX rules - count incoming traffic per destination IP</span></span>
        ip daddr 192.168.1.105 counter packets 58239 bytes 87359823 comment "rx_192.168.1.105"</span></span>
        ip daddr 192.168.1.122 counter packets 7123 bytes 5234122 comment "rx_192.168.1.122"</span></span>
        ip daddr 192.168.1.150 counter packets 91823 bytes 125789012 comment "rx_192.168.1.150"</span></span>
    }</span></span>
    </span></span>
    chain forward {</span></span>
        # ... other forward rules ...</span></span>
        jump CLIENT_TRAFFIC  # All forwarded traffic goes through accounting</span></span>
    }</span></span>
}</span></span></code></pre>2. Connection Tracking</h4>
The exporter also reads from conntrack</code> to count active connections:</p>
# Raw conntrack data</span></span>
tcp</span>      6 431999</span> ESTABLISHED src=</span>192.168.1.105</span> dst=</span>142.250.185.142</span> sport=</span>55234</span> dport=</span>443</span></span>
udp</span>      17 59</span> src=</span>192.168.1.122</span> dst=</span>8.8.8.8</span> sport=</span>51234</span> dport=</span>53</span></span>
</span>
# Processed into metrics</span></span>
network_client_connections</span>{ip=</span>"192.168.1.105"}</span> 47</span></span>
network_client_connections</span>{ip=</span>"192.168.1.122"}</span> 12</span></span></code></pre>3. The Collection Process</h4>
Here’s how the complete flow works:</p>


Discovery Phase</strong> (client-traffic-tracker):</p>
# Discover clients via ARP table</span></span>
ip</span> neigh show</span> |</span> grep</span> '</span>br-lan</span>'</span> |</span> grep</span> -E</span> '</span>192.168.1.[0-9]+</span>'</span> |</span> awk</span> '</span>{print $1}</span>'</span></span>
</span>
# Also check active connections</span></span>
conntrack</span> -L</span> 2></span>/dev/null</span> |</span> grep</span> -oE</span> '</span>192.168.1.[0-9]+</span>'</span> |</span> sort</span> -u</span></span>
</span>
# For each discovered IP, create accounting rules</span></span>
nft</span> add rule inet filter CLIENT_TRAFFIC ip saddr</span> 192.168.1.105</span> counter comment</span> "</span>tx_192.168.1.105</span>"</span></span>
nft</span> add rule inet filter CLIENT_TRAFFIC ip daddr</span> 192.168.1.105</span> counter comment</span> "</span>rx_192.168.1.105</span>"</span></span></code></pre></li>

Collection Phase</strong> (network-metrics-exporter</a>):</p>
// The Go program directly reads nftables counters</span></span>
// Parses rules from CLIENT_TRAFFIC chain</span></span>
// Reads connection tracking data</span></span>
// Enriches with persistent client names</span></span>
// Serves metrics on :9101/metrics</span></span></code></pre></li>
</ol>
Performance Characteristics</h3>
Real-world measurements from an Intel Celeron N5105 router (4 cores @ 2.0-2.9 GHz) with 25+ active clients:</p>


network-metrics-exporter</a> (Go)</strong>:</p>

CPU usage: ~1.5% average</li>
Memory usage: 7.6MB (peak 11.9MB)</li>
Process threads: 9</li>
Runtime: 7+ hours stable</li>
</ul>
</li>

client-traffic-tracker (Bash)</strong>:</p>

CPU usage: < 0.1% (mostly sleeping)</li>
Memory usage: < 1MB</li>
Wake frequency: Every 60 seconds</li>
Runtime: 2+ days stable</li>
</ul>
</li>

System impact</strong>:</p>

Total CPU overhead: < 2%</li>
Total memory: < 10MB combined</li>
Network overhead: Zero (uses kernel counters)</li>
Load average impact: Negligible (0.09 on a 4-core system)</li>
</ul>
</li>
</ul>
Understanding the Metrics</h3>
The exporter provides comprehensive metrics:</p>
# Bandwidth metrics (cumulative counters)</span></span>
network_client_rx_bytes_total{ip="192.168.1.105", hostname="gaming-pc"} 87359823</span></span>
network_client_tx_bytes_total{ip="192.168.1.105", hostname="gaming-pc"} 3234122</span></span>
</span>
# Connection metrics (current gauge)</span></span>
network_client_connections{ip="192.168.1.105", hostname="gaming-pc"} 127</span></span>
</span>
# Status metrics</span></span>
network_client_online{ip="192.168.1.105", hostname="gaming-pc"} 1</span></span>
network_client_last_seen_timestamp{ip="192.168.1.105", hostname="gaming-pc"} 1703123456</span></span>
</span>
# System information</span></span>
network_exporter_up 1</span></span>
network_exporter_scrape_duration_seconds 0.012</span></span></code></pre>Why This Architecture?</h3>
The combination of a Go exporter with a bash helper service provides the best of both worlds:</p>


Go Exporter Benefits</strong>:</p>

Efficient HTTP server for Prometheus scraping</li>
Persistent state management for client names</li>
Clean metric formatting and labeling</li>
Low memory footprint</li>
</ul>
</li>

Bash Helper Benefits</strong>:</p>

Simple client discovery logic</li>
Easy integration with system tools (ip, conntrack)</li>
Transparent nftables rule management</li>
Easy to debug and modify</li>
</ul>
</li>
</ol>
The bash script handles dynamic rule creation as clients appear, while the Go program efficiently serves the metrics to Prometheus.</p>
Step 3: Configure the Exporter</h2>
Let’s enable and configure the network-metrics-exporter</a>.</p>
Basic Configuration</h3>
First, add my nixos repository as a flake input to get access to the network-metrics-exporter</a>:</p>
# flake.nix</span></span>
{</span></span>
  inputs</span> =</span> {</span></span>
    nixpkgs</span>.</span>url</span> =</span> "github:NixOS/nixpkgs/nixos-24.11"</span>;</span></span>
    arsfeld-nixos</span>.</span>url</span> =</span> "github:arsfeld/nixos"</span>;</span></span>
  };</span></span>
  </span></span>
  outputs</span> =</span> {</span> self</span>,</span> nixpkgs</span>,</span> arsfeld-nixos</span> }: {</span></span>
    nixosConfigurations</span>.</span>router</span> =</span> nixpkgs</span>.</span>lib</span>.</span>nixosSystem</span> {</span></span>
      system</span> =</span> "x86_64-linux"</span>;</span></span>
      modules</span> =</span> [ </span></span>
        ./configuration.nix</span></span>
        arsfeld-nixos</span>.</span>nixosModules</span>.</span>network-metrics-exporter</span></span>
      ];</span></span>
    };</span></span>
  };</span></span>
}</span></span></code></pre>
Then configure the exporter in your configuration:</p>
# configuration.nix</span></span>
{</span></span>
  services</span>.</span>network-metrics-exporter</span> =</span> {</span></span>
    enable</span> =</span> true</span>;</span></span>
    </span></span>
    # Network configuration</span></span>
    lanInterface</span> =</span> "enp2s0"</span>;</span>        # Your LAN interface (from Part 1)</span></span>
    wanInterface</span> =</span> "enp1s0"</span>;</span>        # Your WAN interface (from Part 1)</span></span>
    localSubnet</span> =</span> "192.168.1.0/24"</span>;</span> # Your LAN subnet</span></span>
    </span></span>
    # Persistent storage for client names</span></span>
    stateDir</span> =</span> "/var/lib/network-metrics"</span>;</span></span>
    </span></span>
    # Update interval (seconds)</span></span>
    updateInterval</span> =</span> 5</span>;</span></span>
    </span></span>
    # Enable nftables integration</span></span>
    enableNftables</span> =</span> true</span>;</span></span>
    </span></span>
    # Web interface port</span></span>
    port</span> =</span> 9101</span>;</span></span>
  };</span></span>
}</span></span></code></pre>Configure Static Client Names</h3>
Pre-configure friendly names for known devices:</p>
{</span></span>
  services</span>.</span>network-metrics-exporter</span> =</span> {</span></span>
    staticClients</span> =</span> {</span></span>
      "192.168.1.105"</span> =</span> "gaming-pc"</span>;</span></span>
      "192.168.1.122"</span> =</span> "smart-tv"</span>;</span></span>
      "192.168.1.135"</span> =</span> "work-laptop"</span>;</span></span>
      "192.168.1.150"</span> =</span> "nas"</span>;</span></span>
    };</span></span>
  };</span></span>
}</span></span></code></pre>Advanced Options</h3>
{</span></span>
  services</span>.</span>network-metrics-exporter</span> =</span> {</span></span>
    # Automatically detect client names from DHCP leases</span></span>
    dhcpLeaseFile</span> =</span> "/var/lib/dhcp/dhcpd.leases"</span>;</span></span>
    </span></span>
    # How long before considering a client offline (seconds)</span></span>
    offlineThreshold</span> =</span> 300</span>;</span></span>
    </span></span>
    # Exclude certain IPs from monitoring</span></span>
    excludedIPs</span> =</span> [ </span></span>
      "192.168.1.1"</span>     # Router itself</span></span>
      "192.168.1.255"</span>   # Broadcast</span></span>
    ];</span></span>
    </span></span>
    # Extra labels for all metrics</span></span>
    extraLabels</span> =</span> {</span></span>
      location</span> =</span> "home"</span>;</span></span>
      router</span> =</span> "main"</span>;</span></span>
    };</span></span>
  };</span></span>
}</span></span></code></pre>Add to Prometheus Scraping</h3>
Update your Prometheus configuration:</p>
{</span></span>
  services</span>.</span>prometheus</span>.</span>scrapeConfigs</span> =</span> [</span></span>
    # ... existing configs ...</span></span>
    {</span></span>
      job_name</span> =</span> "network-metrics"</span>;</span></span>
      static_configs</span> =</span> [{</span></span>
        targets</span> =</span> [</span> "localhost:9101"</span> ];</span></span>
      }];</span></span>
      # Scrape more frequently for real-time data</span></span>
      scrape_interval</span> =</span> "5s"</span>;</span></span>
    }</span></span>
  ];</span></span>
}</span></span></code></pre>Step 4: Build Powerful Dashboards</h2>
Now the fun part - creating dashboards that give you instant visibility into your network usage.</p>
Import the Pre-Built Dashboard</h3>
The easiest way is to import our pre-built dashboard:</p>
# configuration.nix</span></span>
{</span></span>
  services</span>.</span>grafana</span>.</span>provision</span>.</span>dashboards</span>.</span>settings</span>.</span>providers</span> =</span> [{</span></span>
    name</span> =</span> "default"</span>;</span></span>
    type</span> =</span> "file"</span>;</span></span>
    folder</span> =</span> "Router"</span>;</span></span>
    options</span>.</span>path</span> =</span> ./dashboards</span>;</span>  # Path to your dashboard JSON files</span></span>
  }];</span></span>
}</span></span></code></pre>Key Dashboard Panels</h3>
The repository includes pre-built dashboard panels</a> that provide comprehensive network visibility:</p>
Active Clients Count</h4>
Shows the total number of active clients on your network:</p>
count(count by (ip) (client_active_connections{job="network-metrics"}))</span></span></code></pre>Client Connection Count Table</h4>
Displays each client’s active connections in a sortable table:</p>
client_active_connections{job="network-metrics"}</span></span></code></pre>Real-time Client Bandwidth</h4>
Live graph showing download/upload speeds per client:</p>
# Download speed (bits per second)</span></span>
rate(client_traffic_rx_bytes{job="network-metrics"}[1m]) * 8</span></span>
</span>
# Upload speed (bits per second)  </span></span>
rate(client_traffic_tx_bytes{job="network-metrics"}[1m]) * 8</span></span></code></pre>Client Bandwidth Analysis</h4>
Detailed per-client bandwidth usage over time with legend showing current/avg/max values.</p>
Total Bandwidth Gauges</h4>

Total Download Bandwidth (Mbps)</strong> - Aggregate download across all clients</li>
Total Upload Bandwidth (Mbps)</strong> - Aggregate upload across all clients</li>
</ul>
These panels are defined in clients-panels.json</a> and automatically provisioned when you enable Grafana.</p>
The complete dashboard includes multiple sections:</p>

System Overview</a></strong> - CPU, memory, disk usage</li>
Network Interfaces</a></strong> - WAN/LAN interface statistics</li>
DNS</a></strong> - Query rates, cache hits, blocked domains</li>
QoS</a></strong> - Traffic shaping and prioritization</li>
NAT-PMP</a></strong> - Port mapping statistics</li>
</ul>
All panels are dynamically assembled by default.nix</a> into a cohesive dashboard.</p>

Note on Declarative Dashboards</strong>: The approach shown here makes your entire monitoring stack declarative and reproducible. Your dashboards are defined as code, version-controlled, and automatically provisioned when you deploy. No more manually recreating dashboards or losing them during upgrades! For a deep dive into declarative Grafana dashboards with NixOS, see the upcoming bonus guide in this series.</p>
</blockquote>
Creating Custom Panels</h3>
For a bandwidth usage timeline:</p>

Create new panel → Time series</li>
Add query: rate(network_client_rx_bytes_total[1m]) * 8 / 1000000</code></li>
Legend: {{hostname}} - Download</code></li>
Unit: Mbps</code></li>
Stack series: Off (to see individual clients)</li>
</ol>
For a current usage table:</p>

Create new panel → Table</li>
Add queries:

A: rate(network_client_rx_bytes_total[1m]) * 8 / 1000000</code></li>
B: rate(network_client_tx_bytes_total[1m]) * 8 / 1000000</code></li>
C: network_client_connections</code></li>
</ul>
</li>
Transform → Merge</li>
Override columns:

A: “Download (Mbps)”</li>
B: “Upload (Mbps)”</li>
C: “Connections”</li>
</ul>
</li>
</ol>
Dashboard Variables</h3>
Add variables for filtering:</p>
# In your dashboard JSON</span></span>
"templating"</span>:</span> {</span></span>
  "list"</span>:</span> </span>[</span></span>
    </span>{</span></span>
      "name"</span>:</span> "client"</span>,</span></span>
      "type"</span>:</span> "query"</span>,</span></span>
      "query"</span>:</span> "label_values(network_client_online, hostname)"</span>,</span></span>
      "multi"</span>:</span> true</span>,</span></span>
      "includeAll"</span>:</span> true</span></span>
    }</span></span>
  </span>]</span></span>
}</span></span></code></pre>
Then use in queries:</p>
rate(network_client_rx_bytes_total{hostname=~"$client"}[1m])</span></span></code></pre>Troubleshooting</h2>
No Metrics Appearing</h3>
Check the exporter is running:</p>
systemctl</span> status network-metrics-exporter</span></span>
curl</span> http://localhost:9101/metrics</span> |</span> grep</span> network_client</span></span></code></pre>Missing Clients</h3>
Ensure nftables rules are created:</p>
sudo</span> nft list table netdev metrics</span></span></code></pre>Incorrect Traffic Counts</h3>
Verify interfaces are correct:</p>
ip</span> link show</span>  # Find your LAN/WAN interfaces</span></span></code></pre>Performance Impact</h3>
The exporter is designed for minimal impact:</p>

Atomic counter reads (no packet loss)</li>
Efficient rule management</li>
Configurable update intervals</li>
</ul>
If you have hundreds of clients, increase the update interval:</p>
services</span>.</span>network-metrics-exporter</span>.</span>updateInterval</span> </span>=</span> 30</span>;</span></span></code></pre>Advanced Usage</h2>
Alert on Bandwidth Hogs</h3>
Add Prometheus alerts:</p>
{</span></span>
  services</span>.</span>prometheus</span>.</span>rules</span> =</span> [</span>''</span></span>
    groups:</span></span>
    - name: bandwidth</span></span>
      rules:</span></span>
      - alert: HighBandwidthUsage</span></span>
        expr: rate(network_client_rx_bytes_total[5m]) > 100000000  # 100 MB/s</span></span>
        for: 5m</span></span>
        annotations:</span></span>
          summary: "{{ $labels.hostname }} using high bandwidth"</span></span>
          description: "{{ $labels.hostname }} downloading at {{ $value | humanize }}B/s"</span></span>
  ''</span>];</span></span>
}</span></span></code></pre>Track Monthly Quotas</h3>
# Monthly usage in GB</span></span>
increase(network_client_rx_bytes_total[30d]) / 1073741824</span></span></code></pre>Identify Streaming Devices</h3>
# Sustained bandwidth over 4 Mbps (typical streaming)</span></span>
avg_over_time(</span></span>
  rate(network_client_rx_bytes_total[1m])[1h:]</span></span>
) > 500000</span></span></code></pre>Summary</h2>
You now have powerful per-client network monitoring! Your dashboards show:</p>
✅ Real-time bandwidth usage per device

✅ Historical usage trends

✅ Connection counts and client status

✅ Top bandwidth consumers

✅ Daily/monthly usage totals</p>
With this visibility, you can finally answer questions like:</p>

Why is my internet slow right now?</li>
Which device used all our data this month?</li>
Is someone streaming 4K video during work hours?</li>
Are all my IoT devices phoning home constantly?</li>
</ul>
What’s Next?</h2>
This concludes the currently available posts in the NixOS Router Series. You now have:</p>

Part 1: Getting Started</a></strong> - A working NixOS router with basic connectivity</li>
Part 2: Testing</a></strong> - Comprehensive tests to ensure reliability</li>
Part 3: Monitoring</strong> (this post) - Per-client bandwidth tracking and dashboards</li>
</ul>
For a complete overview of the entire router build including advanced features like QoS, VLANs, and hardware selection, check out my NixOS router journey</a></strong> post.</p>

Found this helpful? Check out the complete code</a> and full router configuration</a> on GitHub.</em></p>


How to Write Tests for Your NixOS Router Configuration
Alex Rosenfeld — Sun, 20 Jul 2025 00:00:00 +0000
Part 2 of the NixOS Router Series</em></p>
In the previous post</a>, we built a minimal NixOS router that provides internet connectivity to your network. Now let’s ensure it stays reliable by writing comprehensive tests for our configuration.</p>
Why test your router?</strong> A misconfigured router can leave you without internet access, making it difficult to fix remotely. By writing tests, you can:</p>

Catch configuration errors before deployment</li>
Verify features work as expected</li>
Prevent regressions when making changes</li>
Document expected behavior</li>
</ul>
Moving to Flakes</h2>
Starting with this post, we’ll use Nix Flakes for a more structured and reproducible configuration. Flakes provide:</p>

Reproducible builds</strong> with locked dependencies</li>
Better composability</strong> for modular configurations</li>
Built-in testing framework</strong> support</li>
Easier deployment</strong> with tools like deploy-rs</li>
</ul>
If you’re new to flakes, check out:</p>

Official Nix Flakes documentation</a></li>
Zero to Nix - Flakes guide</a></li>
My example flake.nix</a></li>
</ul>
To migrate your /etc/nixos</code> configuration to flakes:</p>
# Enable flakes</span></span>
mkdir</span> -p</span> ~/.config/nix</span></span>
echo</span> "</span>experimental-features = nix-command flakes</span>"</span> >></span> ~/.config/nix/nix.conf</span></span>
</span>
# Create a new directory for your flake</span></span>
mkdir</span> ~/nixos-router</span></span>
cd</span> ~/nixos-router</span></span>
</span>
# Copy your existing configuration</span></span>
cp</span> /etc/nixos/configuration.nix .</span></span>
cp</span> /etc/nixos/hardware-configuration.nix .</span></span>
</span>
# Initialize git (flakes require version control)</span></span>
git</span> init</span></span>
git</span> add .</span></span>
</span>
# Create a basic flake.nix</span></span>
cat</span> ></span> flake.nix</span> <<</span> 'EOF'</span></span>
{</span></span>
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";</span></span>
  </span></span>
  outputs = { self, nixpkgs }: {</span></span>
    nixosConfigurations.router = nixpkgs.lib.nixosSystem {</span></span>
      system = "x86_64-linux";</span></span>
      modules = [ ./configuration.nix ];</span></span>
    };</span></span>
  };</span></span>
}</span></span>
EOF</span></span>
</span>
# Test your flake</span></span>
nix</span> flake check</span></span></code></pre>Prerequisites</h2>

A working NixOS router from Part 1</li>
Basic familiarity with Nix expressions</li>
Nix with flakes enabled</li>
About 30 minutes</li>
</ul>
Step 1: Introduction to NixOS Tests</h2>
NixOS has a powerful testing framework that spins up virtual machines to test your configuration. Tests are written as Nix expressions that:</p>

Define virtual machines with your configuration</li>
Run test scripts to verify behavior</li>
Report success or failure</li>
</ol>
Basic Test Structure</h3>
Let’s look at a real router test from my configuration</a>. Create a new file tests/router-test.nix</code>:</p>
{</span> self</span>,</span> inputs</span>,</span> }: {</span> lib</span>,</span> pkgs</span>, ...</span> }: {</span></span>
  name</span> =</span> "router-test"</span>;</span></span>
  </span></span>
  nodes</span> =</span> {</span></span>
    # The router VM using actual configuration</span></span>
    router</span> =</span> {</span> config</span>,</span> pkgs</span>, ...</span> }: {</span></span>
      imports</span> =</span> [</span></span>
        # Import your router configuration</span></span>
        "</span>${</span>self</span>}</span>/configuration.nix"</span></span>
      ];</span></span>
      </span></span>
      # Test-specific overrides</span></span>
      virtualisation</span>.</span>vlans</span> =</span> [</span>1 2 3</span>];</span> # WAN + 2 LAN ports</span></span>
      </span></span>
      # Override hardware-specific settings for VM</span></span>
      boot</span>.</span>loader</span>.</span>grub</span>.</span>enable</span> =</span> false</span>;</span></span>
      fileSystems</span>.</span>"/"</span> =</span> {</span></span>
        device</span> =</span> "tmpfs"</span>;</span></span>
        fsType</span> =</span> "tmpfs"</span>;</span></span>
      };</span></span>
      </span></span>
      # Override interface names for test environment</span></span>
      networking</span>.</span>interfaces</span> =</span> lib</span>.</span>mkForce</span> {</span></span>
        eth1</span>.</span>useDHCP</span> =</span> false</span>;</span>  # WAN</span></span>
        eth2</span>.</span>ipv4</span>.</span>addresses</span> =</span> [{</span></span>
          address</span> =</span> "192.168.1.1"</span>;</span></span>
          prefixLength</span> =</span> 24</span>;</span></span>
        }];</span></span>
      };</span></span>
      </span></span>
      # For test, use static IP on WAN</span></span>
      networking</span>.</span>interfaces</span>.</span>eth1</span>.</span>ipv4</span>.</span>addresses</span> =</span> [{</span></span>
        address</span> =</span> "10.0.2.2"</span>;</span></span>
        prefixLength</span> =</span> 24</span>;</span></span>
      }];</span></span>
      </span></span>
      networking</span>.</span>defaultGateway</span> =</span> "10.0.2.1"</span>;</span></span>
      networking</span>.</span>nat</span>.</span>externalInterface</span> =</span> lib</span>.</span>mkForce</span> "eth1"</span>;</span></span>
      networking</span>.</span>nat</span>.</span>internalInterfaces</span> =</span> lib</span>.</span>mkForce</span> [</span> "eth2"</span> ];</span></span>
    };</span></span>
    </span></span>
    # A client VM to test connectivity</span></span>
    client1</span> =</span> {</span> config</span>,</span> pkgs</span>, ...</span> }: {</span></span>
      virtualisation</span>.</span>vlans</span> =</span> [</span>2</span>];</span></span>
      </span></span>
      networking</span> =</span> {</span></span>
        useDHCP</span> =</span> false</span>;</span></span>
        useNetworkd</span> =</span> true</span>;</span></span>
      };</span></span>
      </span></span>
      systemd</span>.</span>network</span> =</span> {</span></span>
        enable</span> =</span> true</span>;</span></span>
        networks</span>.</span>"30-lan"</span> =</span> {</span></span>
          matchConfig</span>.</span>Name</span> =</span> "eth1"</span>;</span></span>
          networkConfig</span> =</span> {</span></span>
            DHCP</span> =</span> "yes"</span>;</span></span>
            IPv6AcceptRA</span> =</span> false</span>;</span></span>
          };</span></span>
        };</span></span>
      };</span></span>
    };</span></span>
  };</span></span>
  </span></span>
  testScript</span> =</span> ''</span></span>
    start_all()</span></span>
    </span></span>
    # Wait for machines to boot</span></span>
    router.wait_for_unit("multi-user.target")</span></span>
    client1.wait_for_unit("multi-user.target")</span></span>
    </span></span>
    # Your tests here</span></span>
  ''</span>;</span></span>
}</span></span></code></pre>Running Tests Locally</h3>
With flakes, run your test like this:</p>
nix</span> build .#checks.x86_64-linux.router-test</span></span></code></pre>
The test framework provides a Python API for controlling VMs and making assertions.</p>
Step 2: Write Connectivity Tests</h2>
Let’s write tests that verify our router provides internet access and serves DHCP correctly.</p>
Test Internet Access</h3>
Here’s how we test connectivity in the actual router test:</p>
testScript</span> </span>=</span> ''</span></span>
  start_all()</span></span>
  </span></span>
  # Wait for all machines to be ready</span></span>
  external.wait_for_unit("multi-user.target")</span></span>
  router.wait_for_unit("multi-user.target")</span></span>
  client1.wait_for_unit("multi-user.target")</span></span>
  </span></span>
  # Wait for services</span></span>
  router.wait_for_unit("dnsmasq.service")</span></span>
  </span></span>
  # Give DHCP time to assign addresses</span></span>
  client1.wait_until_succeeds("ip addr show eth1 | grep 192.168.1")</span></span>
  </span></span>
  # Test basic connectivity</span></span>
  with subtest("Clients can ping router"):</span></span>
      client1.succeed("ping -c 1 192.168.1.1")</span></span>
  </span></span>
  with subtest("Router can ping external"):</span></span>
      router.succeed("ping -c 1 10.0.2.1")</span></span>
  </span></span>
  with subtest("Clients can reach external through router"):</span></span>
      # Test routing</span></span>
      client1.succeed("ping -c 1 10.0.2.1")</span></span>
      </span></span>
      # Test NAT and web connectivity</span></span>
      client1.succeed("curl -f http://10.0.2.1")</span></span>
''</span>;</span></span></code></pre>Test LAN Connectivity</h3>
Add another client to test LAN-to-LAN communication:</p>
nodes</span> </span>=</span> {</span></span>
  # ... existing nodes ...</span></span>
  </span></span>
  # Client on second LAN port</span></span>
  client2</span> =</span> {</span> config</span>,</span> pkgs</span>, ...</span> }: {</span></span>
    virtualisation</span>.</span>vlans</span> =</span> [</span>3</span>];</span></span>
    </span></span>
    networking</span> =</span> {</span></span>
      useDHCP</span> =</span> false</span>;</span></span>
      useNetworkd</span> =</span> true</span>;</span></span>
    };</span></span>
    </span></span>
    systemd</span>.</span>network</span> =</span> {</span></span>
      enable</span> =</span> true</span>;</span></span>
      networks</span>.</span>"30-lan"</span> =</span> {</span></span>
        matchConfig</span>.</span>Name</span> =</span> "eth1"</span>;</span></span>
        networkConfig</span> =</span> {</span></span>
          DHCP</span> =</span> "yes"</span>;</span></span>
          IPv6AcceptRA</span> =</span> false</span>;</span></span>
        };</span></span>
      };</span></span>
    };</span></span>
  };</span></span>
}</span>;</span></span>
</span>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  with subtest("Clients can communicate with each other"):</span></span>
      # Get IP addresses</span></span>
      client1_ip = client1.succeed("ip -4 addr show eth1 | grep inet | awk '{print $2}' | cut -d'/' -f1").strip()</span></span>
      client2_ip = client2.succeed("ip -4 addr show eth1 | grep inet | awk '{print $2}' | cut -d'/' -f1").strip()</span></span>
      </span></span>
      # Test ping between clients</span></span>
      client1.succeed(f"ping -c 1 {client2_ip}")</span></span>
      client2.succeed(f"ping -c 1 {client1_ip}")</span></span>
      </span></span>
      # Test HTTP between clients</span></span>
      client1.succeed(f"curl -f http://{client2_ip}:8080")</span></span>
      client2.succeed(f"curl -f http://{client1_ip}:9090")</span></span>
''</span>;</span></span></code></pre>Test Service Availability</h3>
Verify essential services are running:</p>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  with subtest("Core services are running"):</span></span>
      # Check that dnsmasq is running (provides DHCP and DNS)</span></span>
      router.succeed("systemctl is-active dnsmasq")</span></span>
      router.wait_for_open_port(53)  # DNS port</span></span>
      </span></span>
      # Check that firewall is active</span></span>
      router.succeed("systemctl is-active nftables")</span></span>
''</span>;</span></span></code></pre>Step 3: Test Your Features</h2>
Now let’s test specific features of your router configuration.</p>
Test NAT and Firewall Rules</h3>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  with subtest("Check NAT table"):</span></span>
      # Generate some traffic</span></span>
      client1.succeed("curl -f http://10.0.2.1")</span></span>
      </span></span>
      # Check NAT translations exist</span></span>
      router.succeed("nft list table ip nat | grep masquerade")</span></span>
''</span>;</span></span></code></pre>Test DHCP Static Reservations</h3>
The router test includes a static DHCP reservation test:</p>
nodes</span> </span>=</span> {</span></span>
  # Storage server with static IP via DHCP reservation</span></span>
  storage</span> =</span> {</span> config</span>,</span> pkgs</span>, ...</span> }: {</span></span>
    virtualisation</span>.</span>vlans</span> =</span> [</span>2</span>];</span></span>
    </span></span>
    systemd</span>.</span>network</span> =</span> {</span></span>
      enable</span> =</span> true</span>;</span></span>
      # Set MAC address for static DHCP reservation</span></span>
      links</span>.</span>"10-eth1"</span> =</span> {</span></span>
        matchConfig</span>.</span>OriginalName</span> =</span> "eth1"</span>;</span></span>
        linkConfig</span>.</span>MACAddress</span> =</span> "00:e0:4c:bb:00:e3"</span>;</span></span>
      };</span></span>
      networks</span>.</span>"30-lan"</span> =</span> {</span></span>
        matchConfig</span>.</span>Name</span> =</span> "eth1"</span>;</span></span>
        networkConfig</span> =</span> {</span></span>
          DHCP</span> =</span> "yes"</span>;</span></span>
          IPv6AcceptRA</span> =</span> false</span>;</span></span>
        };</span></span>
      };</span></span>
    };</span></span>
  };</span></span>
}</span>;</span></span>
</span>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  with subtest("Storage has correct static IP"):</span></span>
      # Verify storage got the static IP 192.168.1.50</span></span>
      storage.wait_until_succeeds("ip addr show eth1 | grep 192.168.1.50")</span></span>
      storage_ip = storage.succeed("ip -4 addr show eth1 | grep inet | awk '{print $2}' | cut -d'/' -f1").strip()</span></span>
      assert storage_ip == "192.168.1.50", f"Storage IP is {storage_ip}, expected 192.168.1.50"</span></span>
''</span>;</span></span></code></pre>Test Port Forwarding (if configured)</h3>
If you’ve added port forwarding rules:</p>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  with subtest("Port forwarding works"):</span></span>
      # Example: Test if port 80 is forwarded to internal server</span></span>
      # Assuming you have a rule like:</span></span>
      # networking.firewall.extraCommands = ''</span></span>
      #   iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 192.168.1.100:80</span></span>
      # '';</span></span>
      </span></span>
      # Start a simple web server on client</span></span>
      client1</span>.</span>execute</span>(</span>"python3 -m http.server 80 &"</span>)</span></span>
      </span></span>
      # Test from external that port is accessible</span></span>
      external</span>.</span>succeed</span>(</span>"curl -f http://10.0.2.2"</span>)</span></span>
'';</span></span></code></pre>Step 4: Integrate with Deployment</h2>
Pre-deployment Testing</h3>
Create a script to run tests before deploying:</p>
#!/usr/bin/env bash</span></span>
# deploy-with-tests.sh</span></span>
</span>
set</span> -e</span></span>
</span>
echo</span> "</span>Running router tests...</span>"</span></span>
nix</span> build .#checks.x86_64-linux.router-test</span></span>
</span>
if</span> [</span> $?</span> -eq</span> 0</span> ];</span> then</span></span>
    echo</span> "</span>Tests passed! Deploying...</span>"</span></span>
    nixos-rebuild</span> switch</span> --flake</span> .#router</span> --target-host 192.168.1.1</span></span>
else</span></span>
    echo</span> "</span>Tests failed! Deployment cancelled.</span>"</span></span>
    exit</span> 1</span></span>
fi</span></span></code></pre>Automated Validation</h3>
Add a post-deployment validation script:</p>
# In your router configuration</span></span>
environment</span>.</span>systemPackages</span> </span>=</span> </span>with</span> pkgs</span>;</span> [</span></span>
  (</span>writeScriptBin</span> "validate-router" ''</span></span>
    #!</span>${</span>stdenv</span>.</span>shell</span>}</span></span>
    set -e</span></span>
    </span></span>
    echo "Validating router configuration..."</span></span>
    </span></span>
    # Check services</span></span>
    systemctl is-active dnsmasq.service >/dev/null || (echo "DHCP/DNS failed" && exit 1)</span></span>
    systemctl is-active nftables.service >/dev/null || (echo "Firewall failed" && exit 1)</span></span>
    </span></span>
    # Check connectivity</span></span>
    ping -c 3 1.1.1.1 >/dev/null || (echo "WAN connectivity failed" && exit 1)</span></span>
    </span></span>
    # Check DNS</span></span>
    nslookup example.com >/dev/null || (echo "DNS resolution failed" && exit 1)</span></span>
    </span></span>
    echo "All validations passed!"</span></span>
  ''</span>)</span></span>
]</span>;</span></span></code></pre>Advanced Testing Patterns</h2>

Note</strong>: The examples in this section are conceptual and untested. They demonstrate possible testing approaches you might want to explore.</p>
</blockquote>
Performance Testing</h3>
Test throughput and latency:</p>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  # Install iperf3 for performance testing</span></span>
  router.succeed("nix-env -iA nixos.iperf3")</span></span>
  client.succeed("nix-env -iA nixos.iperf3")</span></span>
  </span></span>
  # Start iperf3 server on router</span></span>
  router.execute("iperf3 -s -D")</span></span>
  </span></span>
  # Test throughput</span></span>
  result = client.succeed("iperf3 -c 192.168.1.1 -t 10 -J")</span></span>
  </span></span>
  import json</span></span>
  data = json.loads(result)</span></span>
  throughput = data['end']['sum_received']['bits_per_second'] / 1_000_000</span></span>
  print(f"Throughput: {throughput:.2f} Mbps")</span></span>
  </span></span>
  # Ensure minimum performance (adjust based on hardware)</span></span>
  assert throughput > 100, f"Throughput too low: {throughput} Mbps"</span></span>
''</span>;</span></span></code></pre>Failure Testing</h3>
Test recovery from failures:</p>
testScript</span> </span>=</span> ''</span></span>
  # ... existing tests ...</span></span>
  </span></span>
  # Test DHCP server restart</span></span>
  router.systemctl("restart dhcpd4.service")</span></span>
  router.wait_for_unit("dhcpd4.service")</span></span>
  </span></span>
  # Client should still get lease after restart</span></span>
  client.succeed("dhclient -r eth1 && dhclient eth1")</span></span>
  client.succeed("ping -c 3 192.168.1.1")</span></span>
  </span></span>
  # Test firewall reload</span></span>
  router.succeed("nft flush ruleset")</span></span>
  router.systemctl("restart nftables.service")</span></span>
  router.wait_for_unit("nftables.service")</span></span>
  </span></span>
  # NAT should still work</span></span>
  client.succeed("curl -f https://example.com")</span></span>
''</span>;</span></span></code></pre>Troubleshooting Common Issues</h2>
Tests Hang</h3>
If tests hang, add timeouts:</p>
testScript</span> </span>=</span> ''</span></span>
  with subtest("DHCP lease acquisition"):</span></span>
      client.wait_until_succeeds("ip addr show eth1 | grep -q 'inet '", timeout=30)</span></span>
''</span>;</span></span></code></pre>Debugging Failed Tests</h3>
Enable interactive mode to debug:</p>
nix</span> build .#checks.x86_64-linux.router-test</span> --keep-failed</span></span>
# Then run the test interactively:</span></span>
cd</span> result</span> &&</span> ./bin/nixos-test-driver</span> --interactive</span></span></code></pre>Resource Constraints</h3>
Reduce VM resources if tests fail due to memory:</p>
nodes</span> </span>=</span> {</span></span>
  router</span> =</span> {</span> config</span>,</span> pkgs</span>, ...</span> }: {</span></span>
    virtualisation</span>.</span>memorySize</span> =</span> 512</span>;</span>  # MB</span></span>
    virtualisation</span>.</span>cores</span> =</span> 1</span>;</span></span>
  };</span></span>
}</span>;</span></span></code></pre>Summary</h2>
You now have a comprehensive test suite for your NixOS router! Your tests verify:</p>
✅ Basic connectivity and DHCP

✅ Internet access through NAT

✅ Firewall rules and security

✅ Service availability

✅ Configuration-specific features</p>
With these tests in place, you can confidently make changes knowing you’ll catch any issues before they affect your network.</p>
Next Steps</h2>
In the next post, we’ll add monitoring to track per-client network usage with custom metrics. You’ll gain real-time visibility into which devices are using your bandwidth!</p>
Continue to:</strong> Part 3 - Monitor Per-Client Network Usage →</a></p>
For a complete overview of the entire router build including advanced features like QoS, VLANs, and hardware selection, check out my NixOS router journey</a></strong> post.</p>

Found this helpful? Check out the complete test file</a> and full router configuration</a> on GitHub.</em></p>


Build Your Own Router with NixOS: Part 1 - Getting Started
Alex Rosenfeld — Fri, 18 Jul 2025 00:00:00 +0000
</p>
TL;DR</strong>: Turn a $150 mini PC into a powerful, declarative router using NixOS. This guide covers hardware selection, basic installation, and minimal router configuration to get you online.</p>
Why Build Your Own Router?</h2>
Commercial routers often come with limitations: locked-down firmware, poor update cycles, and limited customization. Building your own router with NixOS gives you:</p>

Complete control</strong> over your network configuration</li>
Declarative configuration</strong> that’s version-controlled and reproducible</li>
Regular security updates</strong> through NixOS’s excellent package management</li>
Unlimited customization</strong> for advanced networking features</li>
</ul>
This is the first in a series of guides that will take you from zero to a fully-featured NixOS router. For a deep dive into my complete router setup and the journey that led here, check out my NixOS router journey post</a>. Let’s start with the basics!</p>
Step 1: Choose Your Hardware</h2>
The beauty of building your own router is flexibility in hardware choice. Here’s what you need:</p>
Minimum Requirements</h3>

2+ network interfaces</strong> (NICs) - one for WAN, one for LAN</li>
x86_64 CPU</strong> - NixOS has excellent x86_64 support</li>
4GB+ RAM</strong> - More if you plan to run additional services</li>
16GB+ storage</strong> - SSD preferred for reliability</li>
</ul>
Recommended Budget Option: Intel N5105 Mini PC</h3>
For around $150, Intel N5105-based mini PCs offer excellent value:</p>
Specifications:</span></span>
- CPU: Intel Celeron N5105 (4 cores @ 2.0-2.9 GHz)</span></span>
- RAM: 8GB DDR4 (expandable)</span></span>
- Storage: 128GB SSD</span></span>
- Network: 4x Intel i226-V 2.5GbE</span></span>
- Power: ~10-15W typical consumption</span></span></code></pre>Alternative: ARM-based SBCs</h3>
I’ve also used the NanoPi R2S (ARM-based SBC) as a router, and while my NixOS configuration still supports it</a>, I don’t recommend it for beginners:</p>

Installation is more complex</strong> - requires building custom images</li>
Limited performance</strong> - struggles with QoS, monitoring, and multiple services</li>
Feature trade-offs</strong> - you’ll need to carefully choose which features to enable</li>
Maintenance overhead</strong> - ARM support in NixOS requires more manual work</li>
</ul>
For a first NixOS router, stick with x86_64 hardware for the best experience.</p>
Where to Buy</h3>

AliExpress</strong>: Best prices, 2-4 week shipping

Search for “N5105 mini PC 4 LAN”</li>
Popular vendors: Topton, CWWK, Beelink</li>
</ul>
</li>
Amazon</strong>: Faster shipping, slightly higher prices

Look for “fanless mini PC firewall”</li>
</ul>
</li>
eBay</strong>: Good for used enterprise hardware

Search “Dell Optiplex USFF” + USB NIC</li>
</ul>
</li>
</ul>

Note</strong>: Ensure your chosen hardware has Intel or Realtek NICs for best driver support. Avoid obscure chipsets.</p>
</blockquote>
Step 2: Install NixOS</h2>
Download and Prepare Installation Media</h3>
# Download the latest NixOS ISO (Graphical installer recommended for beginners)</span></span>
wget</span> https://nixos.org/download/nixos-iso-graphical-24.11.tar.xz</span></span>
</span>
# Write to USB drive (replace /dev/sdX with your USB device)</span></span>
sudo</span> dd if=nixos-24.11.iso of=/dev/sdX bs=4M status=progress</span></span></code></pre>Installation Process</h3>

Boot from USB</strong> and select the graphical installer</li>
Partition your disk</strong> - a simple single partition with ext4 works fine</li>
Set up networking</strong> temporarily for the installation</li>
Create your user</strong> and set passwords</li>
Generate initial configuration</strong>:</li>
</ol>
# This creates /etc/nixos/configuration.nix</span></span>
nixos-generate-config</span> --root</span> /mnt</span></span></code></pre>Advanced Installation Method</h3>
For advanced users, I use disko</a> for declarative disk partitioning and nix-anywhere</a> for remote installations:</p>

Disko configuration</strong>: hosts/router/disk-config.nix</a> - Declaratively defines disk layout</li>
Remote deployment</strong>: Can install NixOS on a target machine over SSH without physical access</li>
</ul>
This approach allows for:</p>

Reproducible disk partitioning</li>
Automated remote installations</li>
Zero-touch deployments</li>
</ul>
I’ve automated these tasks in my justfile</a>:</p>
# Install router configuration on new hardware</span></span>
just</span> install router</span> 192.168.1.100</span></span>
</span>
# Deploy updates to existing router</span></span>
just</span> deploy router</span></span>
</span>
# List network interfaces for configuration</span></span>
just</span> router-interfaces router.local</span></span></code></pre>
See my deployment documentation</a> for detailed examples.</p>
Identify Your Network Interfaces</h3>
Before configuring the router, identify your NICs:</p>
# List all network interfaces</span></span>
ip</span> link show</span></span>
</span>
# You should see something like:</span></span>
# enp1s0: WAN interface (connect to modem)</span></span>
# enp2s0: LAN interface (connect to switch/devices)</span></span></code></pre>Step 3: Create Minimal Router Configuration</h2>
Replace your /etc/nixos/configuration.nix</code> with this minimal router setup. We’ll use dnsmasq which provides both DHCP and DNS services in a single, lightweight package:</p>
{</span> config</span>,</span> pkgs</span>, ...</span> }:</span></span>
</span>
{</span></span>
  imports</span> =</span> [</span> ./hardware-configuration.nix</span> ];</span></span>
</span>
  # Basic system configuration</span></span>
  boot</span>.</span>loader</span>.</span>systemd-boot</span>.</span>enable</span> =</span> true</span>;</span></span>
  boot</span>.</span>loader</span>.</span>efi</span>.</span>canTouchEfiVariables</span> =</span> true</span>;</span></span>
</span>
  networking</span>.</span>hostName</span> =</span> "nixos-router"</span>;</span></span>
  </span></span>
  # Enable IP forwarding</span></span>
  boot</span>.</span>kernel</span>.</span>sysctl</span> =</span> {</span></span>
    "net.ipv4.ip_forward"</span> =</span> 1</span>;</span></span>
    "net.ipv6.conf.all.forwarding"</span> =</span> 1</span>;</span></span>
  };</span></span>
</span>
  # Configure network interfaces</span></span>
  networking</span> =</span> {</span></span>
    # Disable NetworkManager for manual configuration</span></span>
    networkmanager</span>.</span>enable</span> =</span> false</span>;</span></span>
    useDHCP</span> =</span> false</span>;</span></span>
</span>
    # WAN interface (adjust interface name as needed)</span></span>
    interfaces</span>.</span>enp1s0</span> =</span> {</span></span>
      useDHCP</span> =</span> true</span>;</span>  # Get IP from ISP</span></span>
    };</span></span>
</span>
    # LAN interface</span></span>
    interfaces</span>.</span>enp2s0</span> =</span> {</span></span>
      ipv4</span>.</span>addresses</span> =</span> [{</span></span>
        address</span> =</span> "192.168.1.1"</span>;</span></span>
        prefixLength</span> =</span> 24</span>;</span></span>
      }];</span></span>
    };</span></span>
</span>
    # NAT for internet sharing</span></span>
    nat</span> =</span> {</span></span>
      enable</span> =</span> true</span>;</span></span>
      externalInterface</span> =</span> "enp1s0"</span>;</span>  # WAN</span></span>
      internalInterfaces</span> =</span> [</span> "enp2s0"</span> ];</span>  # LAN</span></span>
    };</span></span>
</span>
    # Simple firewall rules</span></span>
    firewall</span> =</span> {</span></span>
      enable</span> =</span> true</span>;</span></span>
      </span></span>
      # Allow SSH from LAN only</span></span>
      extraCommands</span> =</span> ''</span></span>
        iptables -A nixos-fw -p tcp --dport 22 -s 192.168.1.0/24 -j ACCEPT</span></span>
      ''</span>;</span></span>
    };</span></span>
  };</span></span>
</span>
  # DHCP and DNS server (dnsmasq provides both)</span></span>
  services</span>.</span>dnsmasq</span> =</span> {</span></span>
    enable</span> =</span> true</span>;</span></span>
    settings</span> =</span> {</span></span>
      # DHCP Configuration</span></span>
      dhcp-range</span> =</span> [</span> "192.168.1.100,192.168.1.200,12h"</span> ];</span></span>
      interface</span> =</span> "enp2s0"</span>;</span></span>
      </span></span>
      # DNS Configuration  </span></span>
      server</span> =</span> [</span> "8.8.8.8" "8.8.4.4"</span> ];</span>  # Upstream DNS servers</span></span>
      </span></span>
      # Don't use /etc/hosts</span></span>
      no-hosts</span> =</span> true</span>;</span></span>
      </span></span>
      # DHCP Options</span></span>
      dhcp-option</span> =</span> [</span></span>
        "option:router,192.168.1.1"</span></span>
        "option:dns-server,192.168.1.1"</span>  # Use router as DNS server</span></span>
      ];</span></span>
    };</span></span>
  };</span></span>
</span>
  # Basic services</span></span>
  services</span>.</span>openssh</span>.</span>enable</span> =</span> true</span>;</span></span>
</span>
  # User configuration</span></span>
  users</span>.</span>users</span>.</span>admin</span> =</span> {</span></span>
    isNormalUser</span> =</span> true</span>;</span></span>
    extraGroups</span> =</span> [</span> "wheel"</span> ];</span>  # Enable 'sudo'</span></span>
    # Don't forget to set a password with 'passwd admin'</span></span>
  };</span></span>
</span>
  system</span>.</span>stateVersion</span> =</span> "24.11"</span>;</span></span>
}</span></span></code></pre>Apply the Configuration</h3>
# Switch to the new configuration</span></span>
sudo</span> nixos-rebuild switch</span></span>
</span>
# Check service status</span></span>
systemctl</span> status dnsmasq</span></span>
systemctl</span> status nftables</span></span></code></pre>Step 4: Test Your Router</h2>
Verify WAN Connectivity</h3>
# Check if router has internet</span></span>
ping</span> -c 3</span> google.com</span></span>
</span>
# Check WAN IP address</span></span>
ip</span> addr show enp1s0</span></span></code></pre>Test LAN Connectivity</h3>

Connect a device</strong> to your LAN port (enp2s0)</li>
Verify DHCP</strong> - the device should get an IP in 192.168.1.100-200 range</li>
Test internet access</strong> from the connected device</li>
</ol>
Basic Troubleshooting</h3>
If things aren’t working:</p>
# Check interface status</span></span>
ip</span> link show</span></span>
ip</span> addr show</span></span>
</span>
# Monitor DHCP leases</span></span>
journalctl</span> -u</span> dnsmasq</span> -f</span></span>
</span>
# View active DHCP leases</span></span>
cat</span> /var/lib/dnsmasq/dnsmasq.leases</span></span>
</span>
# Check firewall rules</span></span>
sudo</span> nft list ruleset</span></span>
</span>
# Watch packet flow</span></span>
sudo</span> tcpdump</span> -i</span> enp2s0</span> -n</span></span></code></pre>Common Issues and Fixes</h3>
No internet on LAN devices?</strong></p>

Verify NAT is working: sudo iptables -t nat -L -v -n</code></li>
Check IP forwarding: sysctl net.ipv4.ip_forward</code></li>
</ul>
DHCP not working?</strong></p>

Ensure dnsmasq is running: systemctl status dnsmasq</code></li>
Check logs: journalctl -u dnsmasq</code></li>
View leases: cat /var/lib/dnsmasq/dnsmasq.leases</code></li>
</ul>
Can’t access router via SSH?</strong></p>

Verify firewall allows SSH from LAN: sudo iptables -L -v -n</code></li>
</ul>
What’s Next?</h2>
Congratulations! You now have a working NixOS router. It’s basic, but it’s yours. Continue with the series to add more features:</p>

Part 2: Testing Your Configuration</a></strong> - Write comprehensive tests to ensure reliability and catch errors before deployment</li>
Part 3: Per-Client Monitoring</a></strong> - Track bandwidth usage per device with Prometheus and Grafana</li>
</ul>
For a complete overview of the entire router build including advanced features like QoS, VLANs, and hardware selection, check out my NixOS router journey</a></strong> post.</p>
The complete configuration for this series is available in my nixos-config repository</a>. Feel free to explore and adapt it to your needs.</p>
Resources</h2>

NixOS Manual - Networking</a></li>
My Router Configuration</a></li>
NixOS Discourse - Networking Topics</a></li>
</ul>
Have questions or run into issues? Feel free to open an issue on the repository</a> or reach out on the NixOS forums!</p>


Building a 2.5Gbps Home Router with NixOS
Alex Rosenfeld — Wed, 16 Jul 2025 00:00:00 +0000
</p>
TL;DR</strong>: Built a NixOS-based router on a $150 Intel N5105 mini PC that handles 2.5Gbps fiber with advanced QoS, monitoring, and declarative configuration. After experiences with pfSense and OPNsense, NixOS with comprehensive testing provides the control and reliability I was seeking. Check out the full router configuration</a>.</p>
Motivation</h2>
Consumer routers work fine for most people. They’re reliable, easy to set up, and just work. But if you’re reading this, you’re probably not “most people.”</p>
For me, the limitation wasn’t about failures or frustration - it was about curiosity. I wanted to:</p>

See real traffic data, not just pretty graphs</li>
Add custom DNS rules for my homelab</li>
Experiment with different QoS algorithms</li>
Actually understand what my network was doing</li>
</ul>
Consumer routers are black boxes. Even the “advanced” settings are usually just basic toggles. Want to try a different packet scheduler? Add custom monitoring? Write your own firewall rules? Good luck with that.</p>
Evolution of My Router Setup</h2>
First Attempt with NixOS</h3>
Three years ago, I discovered NixOS and was attracted to its declarative configuration approach. Version control for system configuration seemed ideal for a router.</p>
The concept was appealing:</p>
networking</span>.</span>firewall</span> </span>=</span> {</span></span>
  enable</span> =</span> true</span>;</span></span>
  # Just declare what I want!</span></span>
}</span>;</span></span></code></pre>
However, I encountered challenges with UPnP implementation. Gaming consoles reported strict NAT types, and port forwarding proved difficult to configure properly. After multiple connectivity issues, I decided to switch to a more established solution.</p>
Experience with pfSense</h3>
pfSense provided a stable solution with its web UI, extensive package ecosystem, and strong community support. It served reliably for several years.</p>
However, a configuration corruption incident after an update highlighted a critical limitation: without declarative configuration or version control, recovering the exact router state required manual reconstruction from memory.</p>
Transition to OPNsense</h3>
Following the pfSense incident, I migrated to OPNsense. It’s well-engineered software with good stability and maintenance.</p>
While functional, the GUI-based configuration lacked the version control and reproducibility benefits of declarative systems. The contrast with Infrastructure as Code principles was apparent.</p>
Return to NixOS with Better Tooling</h3>
In 2025, with improved tooling including AI coding assistants, I revisited NixOS for routing. The key difference was developing a comprehensive test suite.</p>
The test coverage includes:</p>

Basic connectivity validation</li>
DNS resolution verification</li>
Firewall rule testing</li>
UPnP functionality checks</li>
</ul>
See the complete test suite</a> that validates the entire configuration.</p>
This testing infrastructure enables confident deployment. Changes are validated before reaching production, ensuring network stability.</p>
Why NixOS for a Router?</h2>
With proper testing in place, all the NixOS benefits I originally wanted became reality:</p>
Declarative Configuration</strong>: My entire router setup is in git. Every firewall rule, every service, every setting - tracked, reviewable, and reproducible.</p>
# This is my actual DNS configuration</span></span>
services</span>.</span>blocky</span> </span>=</span> {</span></span>
  enable</span> =</span> true</span>;</span></span>
  settings</span> =</span> {</span></span>
    upstream</span>.</span>default</span> =</span> [</span></span>
      "1.1.1.1"</span></span>
      "8.8.8.8"</span></span>
    ];</span></span>
    blocking</span>.</span>blackLists</span> =</span> {</span></span>
      ads</span> =</span> [</span>"https://someonewhocares.org/hosts/zero/hosts"</span>];</span></span>
    };</span></span>
    customDNS</span>.</span>mapping</span> =</span> {</span></span>
      "router.lan"</span> =</span> "192.168.10.1"</span>;</span></span>
      "nas.lan"</span> =</span> "192.168.10.10"</span>;</span></span>
    };</span></span>
  };</span></span>
}</span>;</span></span></code></pre>
See the full DNS configuration</a> for complete setup including conditional forwarding for Tailscale.</p>
Atomic Updates</strong>: Updates either work completely or roll back. No more half-applied configs that break networking.</p>
Reproducible Builds</strong>: I can build the exact same router configuration on a test VM, verify it works, then deploy to production.</p>
Test-Driven Development</strong>: Comprehensive testing enables reliable changes:</p>
# Simplified example from my test suite</span></span>
testScript</span> </span>=</span> ''</span></span>
  router.wait_for_unit("upnp")</span></span>
  client.succeed("upnpc -a 192.168.10.2 8080 8080 TCP")</span></span>
  router.succeed("nft list ruleset | grep 8080")</span></span>
''</span>;</span></span></code></pre>Considerations for Custom Solutions</h2>
Important considerations for custom router solutions:</p>
Full responsibility</strong>: No vendor support available. Troubleshooting relies on system logs and personal expertise.</p>
Time constraints</strong>: Network issues require immediate resolution, especially in households dependent on connectivity.</p>
Maintenance overhead</strong>: Security updates, monitoring, and system health are self-managed.</p>
The benefit is complete understanding and control of the network stack. Issues can be diagnosed and features added as needed.</p>
The Final Setup</h2>
Here’s what I ended up with:</p>
Hardware</strong>: A $150 Intel N5105 mini PC from AliExpress</a></p>

4-core Celeron with AES-NI (plenty for routing)</li>
4x Intel I226-V 2.5GbE NICs</li>
8GB RAM, 16GB NVMe</li>
Fanless, ~15W power draw</li>
Standard x86 architecture for broad compatibility</li>
</ul>
Software Stack</strong>:</p>

NixOS for the base system</li>
nftables for firewall</a></li>
Blocky for DNS with ad blocking</a></li>
miniupnpd for UPnP/NAT-PMP</a></li>
CAKE for QoS and bufferbloat mitigation</a></li>
Prometheus + Grafana for monitoring</a></li>
Tailscale for remote access</li>
</ul>
Performance</strong>:</p>

2.5Gbps symmetric with <1ms added latency</li>
Full IDS/IPS at line rate</li>
50+ days uptime (only reboots for kernel updates)</li>
</ul>
Monitoring Dashboard</h2>
With Prometheus and Grafana, I have complete visibility into my network’s performance:</p>
</p>
The dashboard shows real-time metrics including CPU usage, memory utilization, disk I/O, network traffic per interface, DNS query statistics, client bandwidth analysis, and QoS performance metrics.</p>
What’s Next?</h2>
If you’re interested in building your own NixOS router, I’ve created a tutorial series that walks you through the process:</p>

Part 1: Getting Started</a></strong> - Hardware selection, basic installation, and minimal router configuration</li>
Part 2: Testing Your Configuration</a></strong> - Write comprehensive tests to ensure reliability</li>
Part 3: Per-Client Monitoring</a></strong> - Track bandwidth usage per device with Prometheus and Grafana</li>
</ul>
The full configuration demonstrates many advanced features including comprehensive testing, network architecture with bridging and VLANs, DNS with ad blocking, QoS with CAKE for bufferbloat mitigation, monitoring with Prometheus and Grafana, VPN integration, and dynamic port forwarding.</p>
The full configuration is available on GitHub</a>. The main configuration file</a> ties everything together. For details on how I manage NixOS across multiple hosts in my homelab, see my post on Managing a Homelab with NixOS</a>.</p>
Conclusion</h2>
Building a custom router with NixOS requires significant technical investment. For my use case, the benefits of declarative configuration, comprehensive testing, and complete control justify the effort.</p>
The combination of nixos-rebuild switch</code> with passing tests provides confidence in network changes that GUI-based solutions cannot match.</p>


Simplifying NixOS Configurations with Reusable Modules
Alex Rosenfeld — Wed, 11 Jun 2025 00:00:00 +0000
</p>
Managing multiple NixOS machines quickly becomes unwieldy when you copy-paste configurations between hosts. You end up with duplicated code, inconsistent settings, and the nightmare of keeping everything in sync. After running a fleet of 10+ NixOS machines ranging from ARM routers to x86 servers, I developed what I call the “Constellation Pattern” - a modular system that eliminates configuration duplication while maintaining the flexibility to customize each host.</p>

Note</strong>: All code examples in this post are from my real production NixOS configuration, available at github.com/arsfeld/nixos</a>.</p>
</blockquote>
The Problem with Traditional NixOS Multi-Host Management</h2>
</p>
Most NixOS configurations start simple. You have one machine, one configuration.nix</code>, and life is good. But as you add more hosts, you face several challenges:</p>
Configuration Drift</strong>: Each host accumulates unique tweaks, making it impossible to apply consistent updates across your fleet.</p>
Copy-Paste Hell</strong>: You copy working configurations between machines, creating maintenance nightmares when you need to update common settings.</p>
All-or-Nothing Modules</strong>: Standard NixOS modules are often too rigid - you can’t easily enable just the parts you need on different hosts.</p>
Dependency Management</strong>: Services on one host might depend on services running on another host, but there’s no clean way to express these relationships.</p>
Here’s what a typical problematic setup looks like:</p>
# hosts/server1/configuration.nix</span></span>
{</span> pkgs</span>, ...</span> }: {</span></span>
  # 200 lines of common configuration</span></span>
  services</span>.</span>tailscale</span>.</span>enable</span> =</span> true</span>;</span></span>
  services</span>.</span>openssh</span>.</span>enable</span> =</span> true</span>;</span></span>
  # ... lots of repeated configuration</span></span>
  </span></span>
  # Server-specific stuff mixed in</span></span>
  services</span>.</span>postgresql</span>.</span>enable</span> =</span> true</span>;</span></span>
}</span></span>
</span>
# hosts/server2/configuration.nix  </span></span>
{</span> pkgs</span>, ...</span> }: {</span></span>
  # Same 200 lines copied and pasted</span></span>
  services</span>.</span>tailscale</span>.</span>enable</span> =</span> true</span>;</span></span>
  services</span>.</span>openssh</span>.</span>enable</span> =</span> true</span>;</span></span>
  # ... same repeated configuration</span></span>
  </span></span>
  # Different server-specific stuff</span></span>
  services</span>.</span>nginx</span>.</span>enable</span> =</span> true</span>;</span></span>
}</span></span></code></pre>Enter the Constellation Pattern</h2>
</p>
The Constellation Pattern solves this by creating opt-in feature modules</strong> that can be selectively enabled on any host. Instead of copying configuration, you compose your hosts from a set of reusable, well-tested modules.</p>
The pattern consists of:</p>

Base Module (constellation.common</code>)</strong>: Common configuration that nearly every host needs</li>
Feature Modules</strong>: Specialized modules for specific capabilities (media, backup, services, etc.)</li>
Host Configurations</strong>: Minimal files that just enable the modules they need</li>
</ol>
Here’s how my hosts are now configured:</p>
# hosts/storage/configuration.nix</span></span>
{</span></span>
  constellation</span>.</span>backup</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>services</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>media</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>podman</span>.</span>enable</span> =</span> true</span>;</span></span>
  </span></span>
  # Host-specific configuration</span></span>
  networking</span>.</span>hostName</span> =</span> "storage"</span>;</span></span>
  # ... minimal host-specific settings</span></span>
}</span></span>
</span>
# hosts/cloud/configuration.nix  </span></span>
{</span></span>
  constellation</span>.</span>podman</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>backup</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>services</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>media</span>.</span>enable</span> =</span> true</span>;</span></span>
  constellation</span>.</span>supabase</span>.</span>enable</span> =</span> true</span>;</span></span>
  </span></span>
  # Host-specific configuration</span></span>
  networking</span>.</span>hostName</span> =</span> "cloud"</span>;</span></span>
  nixpkgs</span>.</span>hostPlatform</span> =</span> "aarch64-linux"</span>;</span></span>
}</span></span></code></pre>
Clean, declarative, and immediately obvious what each host provides.</p>
Anatomy of a Constellation Module</h2>
Let’s examine the constellation.common</code> module to understand the pattern:</p>
# modules/constellation/common.nix</span></span>
# Source: https://github.com/arsfeld/nixos/blob/master/modules/constellation/common.nix</span></span>
{</span></span>
  inputs</span>,</span></span>
  config</span>,</span></span>
  pkgs</span>,</span></span>
  lib</span>,</span></span>
  ...</span></span>
}:</span></span>
with</span> lib</span>; {</span></span>
  options</span>.</span>constellation</span>.</span>common</span> =</span> {</span></span>
    enable</span> =</span> mkOption</span> {</span></span>
      type</span> =</span> types</span>.</span>bool</span>;</span></span>
      description</span> =</span> "Enable common configuration"</span>;</span></span>
      default</span> =</span> true</span>;</span>  # This is key - enabled by default</span></span>
    };</span></span>
  };</span></span>
</span>
  config</span> =</span> lib</span>.</span>mkIf config</span>.</span>constellation</span>.</span>common</span>.</span>enable</span> {</span></span>
    # Nix configuration that every host needs</span></span>
    nix</span> =</span> {</span></span>
      settings</span> =</span> {</span></span>
        experimental-features</span> =</span> "nix-command flakes"</span>;</span></span>
        auto-optimise-store</span> =</span> true</span>;</span></span>
        substituters</span> =</span> [</span></span>
          "https://nix-community.cachix.org?priority=41"</span></span>
          "https://fly-attic.fly.dev/system"</span></span>
          # ... more caches</span></span>
        ];</span></span>
        trusted-public-keys</span> =</span> [</span></span>
          "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="</span></span>
          # ... corresponding keys</span></span>
        ];</span></span>
      };</span></span>
    };</span></span>
</span>
    # Essential services every host needs</span></span>
    services</span>.</span>tailscale</span>.</span>enable</span> =</span> true</span>;</span></span>
    services</span>.</span>openssh</span>.</span>enable</span> =</span> true</span>;</span></span>
    services</span>.</span>avahi</span>.</span>enable</span> =</span> true</span>;</span></span>
    </span></span>
    # Common packages</span></span>
    environment</span>.</span>systemPackages</span> = with</span> pkgs</span>; [</span></span>
      git htop tmux wget</span></span>
      # ... essential tools</span></span>
    ];</span></span>
    </span></span>
    # Security and performance defaults</span></span>
    networking</span>.</span>firewall</span>.</span>trustedInterfaces</span> =</span> [</span>"tailscale0"</span>];</span></span>
    zramSwap</span>.</span>enable</span> =</span> true</span>;</span></span>
    nix</span>.</span>gc</span> =</span> {</span></span>
      automatic</span> =</span> true</span>;</span></span>
      dates</span> =</span> "Sat *-*-* 03:15:00"</span>;</span></span>
      options</span> =</span> "--delete-older-than 30d"</span>;</span></span>
    };</span></span>
  };</span></span>
}</span></span></code></pre>
Key principles:</p>

Single Responsibility</strong>: Each module has a clear, focused purpose</li>
Sensible Defaults</strong>: The module works out of the box with minimal configuration</li>
Override Capability</strong>: Hosts can still override specific settings when needed</li>
Dependency Declaration</strong>: Modules can reference other constellation modules</li>
</ul>
Real-World Example: Mixing Containers and Native Services</h2>
The true power of the Constellation Pattern emerges when modules orchestrate both container-based and native NixOS services seamlessly. This hybrid approach lets you choose the best deployment method for each service while maintaining a unified gateway and service discovery system.</p>
Why the Hybrid Approach?</h3>
My constellation.media</code> module runs the *arr stack (Sonarr, Radarr, Prowlarr) as containers because:</p>

NixOS modules for these services weren’t updated frequently enough</li>
Container images provide consistent configuration across updates</li>
The *arr ecosystem expects certain behaviors that containers handle better</li>
</ul>
Meanwhile, services deeply integrated with NixOS (like PostgreSQL databases, Grafana, or Gitea) run as native services for better system integration.</p>
The Media Constellation in Action</h3>
# modules/constellation/media.nix</span></span>
# Container-based services with automatic deployment</span></span>
{</span></span>
  config</span> =</span> lib</span>.</span>mkIf cfg</span>.</span>enable</span> {</span></span>
    media</span>.</span>containers</span> = let</span></span>
      storageServices</span> =</span> {</span></span>
        # The full *arr stack as containers</span></span>
        prowlarr</span> =</span> {</span> listenPort</span> =</span> 9696</span>; };</span></span>
        sonarr</span> =</span> { </span></span>
          listenPort</span> =</span> 8989</span>;</span></span>
          mediaVolumes</span> =</span> true</span>;</span>  # Automatically mounts media directories</span></span>
        };</span></span>
        radarr</span> =</span> { </span></span>
          listenPort</span> =</span> 7878</span>;</span></span>
          mediaVolumes</span> =</span> true</span>;</span></span>
        };</span></span>
        </span></span>
        # Media servers with hardware acceleration</span></span>
        plex</span> =</span> {</span></span>
          mediaVolumes</span> =</span> true</span>;</span></span>
          network</span> =</span> "host"</span>;</span></span>
          devices</span> =</span> [</span>"/dev/dri:/dev/dri"</span>];</span>  # Intel GPU passthrough</span></span>
        };</span></span>
      };</span></span>
    in</span></span>
      lib</span>.</span>mapAttrs</span> (</span>addHost</span> "storage"</span>)</span> storageServices</span>;</span></span>
  };</span></span>
}</span></span>
</span>
# modules/constellation/services.nix</span></span>
# Native NixOS services registered for gateway routing</span></span>
let</span></span>
  services</span> </span>=</span> {</span></span>
    storage</span> =</span> {</span></span>
      # Native services get simple port registration</span></span>
      grafana</span> =</span> 3010</span>;</span></span>
      gitea</span> =</span> 3001</span>;</span></span>
      postgresql</span> =</span> 5432</span>;</span></span>
      # Container services just need their exposed port</span></span>
      jellyfin</span> =</span> 8096</span>;</span></span>
      immich</span> =</span> 15777</span>;</span></span>
      sonarr</span> =</span> 8989</span>;</span></span>
      radarr</span> =</span> 7878</span>;</span></span>
    };</span></span>
  }</span>;</span></span></code></pre>Unified Gateway System</h3>
Both container and native services register with the same gateway system:</p>
# All services - container or native - get automatic:</span></span>
# - Reverse proxy configuration (https://service.domain.com)</span></span>
# - Service discovery across hosts</span></span>
# - Authentication rules</span></span>
# - Health monitoring</span></span>
</span>
media</span>.</span>gateway</span> </span>=</span> {</span></span>
  enable</span> =</span> true</span>;</span></span>
  services</span> =</span> generateServices services</span>;</span>  # Works for both types!</span></span>
}</span>;</span></span></code></pre>
The beauty of this approach:</p>

Use containers when they make sense</strong>: For services with complex dependencies or frequent updates</li>
Use native when better</strong>: For NixOS-integrated services or those needing deep system access</li>
Same gateway for everything</strong>: Users don’t know or care how services are deployed</li>
Flexible migration</strong>: Start with native, move to containers (or vice versa) without changing the gateway configuration</li>
</ul>
This flexibility is where the constellation system truly shines - it doesn’t force you into one deployment model but lets you choose the best tool for each job while maintaining a cohesive system.</p>
Benefits of the Constellation Pattern</h2>
After running this pattern for over a year across 10+ hosts, the benefits are substantial:</p>
Consistency</strong>: Every host gets the same base configuration, eliminating configuration drift.</p>
Maintainability</strong>: Updating all hosts is as simple as updating a single module and redeploying.</p>
Composability</strong>: New hosts are trivial to create - just enable the modules you need.</p>
Testing</strong>: You can test new configurations on a single host before rolling out to the fleet.</p>
Documentation</strong>: The module structure serves as living documentation of your infrastructure capabilities.</p>
Flexibility</strong>: Hosts can still override specific settings when needed, maintaining NixOS’s flexibility.</p>
Comparison with Alternatives</h2>
vs. NixOps</strong>: More lightweight and doesn’t require a separate deployment tool. Works with any deployment method (deploy-rs, nixos-rebuild, etc.).</p>
vs. Terraform/Ansible</strong>: Purely declarative with NixOS’s atomic rollback capabilities. No imperative state management.</p>
vs. Kubernetes</strong>: Simpler for homelab scale. No YAML hell, built-in secret management, and works on bare metal.</p>
vs. Docker Compose</strong>: Better hardware integration, atomic updates, and cross-host service discovery built-in.</p>
How It All Ties Together: Automatic Module Loading with Haumea</h2>
The magic that makes the Constellation Pattern truly effortless is haumea</a>, a library that automatically loads all files as NixOS modules. Instead of manually importing each module file, haumea discovers and loads them for you:</p>
# flake.nix</span></span>
# Source: https://github.com/arsfeld/nixos/blob/master/flake.nix</span></span>
let</span></span>
  modules</span> =</span> inputs</span>.</span>haumea</span>.</span>lib</span>.</span>load</span> {</span></span>
    src</span> =</span> ./modules</span>;</span></span>
    loader</span> =</span> inputs</span>.</span>haumea</span>.</span>lib</span>.</span>loaders</span>.</span>path</span>;</span></span>
  };</span></span>
in</span></span>
  getAllValues modules</span>  # Flattens nested module structure</span></span></code></pre>
This means:</p>

Zero Import Boilerplate</strong>: Drop a new .nix</code> file in modules/</code> and it’s automatically available</li>
Nested Organization</strong>: Create subdirectories like constellation/</code> for logical grouping</li>
Instant Recognition</strong>: New constellation modules are immediately available to all hosts</li>
Clean Flake</strong>: Your flake.nix</code> stays minimal and focused</li>
</ul>
Combined with the constellation pattern, this creates a self-organizing module system where adding new capabilities is as simple as creating a file in the right directory.</p>
Advanced Patterns: A Glimpse into the Future</h2>
The Constellation Pattern enables sophisticated infrastructure patterns that would be complex to implement otherwise. Multi-host service meshes, automatic service discovery, hardware-aware deployments, and declarative secret distribution all become straightforward.</p>
In a future post, we’ll explore these advanced patterns in detail, showing how constellation modules can orchestrate complex multi-host deployments, handle cross-host dependencies, and create self-healing infrastructure - all while maintaining the simplicity of enabling a single option.</p>
Conclusion</h2>
The Constellation Pattern has transformed how I manage my self-hosted infrastructure. What started as a mess of copy-pasted configurations is now a clean, maintainable system that scales from a single Raspberry Pi to a full server fleet. By combining opt-in modules with automatic loading via haumea, the pattern achieves both flexibility and simplicity - the holy grail of infrastructure management.</p>


Managing a Multi-Host Homelab with NixOS
Alex Rosenfeld — Tue, 10 Jun 2025 00:00:00 +0000
</p>
After years of managing services across multiple Ubuntu servers, I finally hit my breaking point. Docker Compose files scattered everywhere, manual package updates breaking production services at 2 AM, and the constant fear of “did I document how I set this up?” It was time for a change. Enter NixOS - a declarative Linux distribution that transformed my homelab from a house of cards into a reproducible, version-controlled infrastructure.</p>
The Ubuntu Problem</h2>
Picture this: You’re running 30+ services across multiple hosts. Your main server has Jellyfin, the *arr stack, databases, monitoring tools. Your cloud VPS runs your public-facing services. Each service has its own quirks:</p>

Docker Compose files that reference specific versions you forgot to pin</li>
System packages installed via apt that conflict with each other</li>
Configuration files edited in-place that you definitely</em> backed up (right?)</li>
That one service that requires a specific kernel module you compiled 6 months ago</li>
</ul>
The breaking point came when a routine apt upgrade</code> on my main server broke PostgreSQL, which cascaded into breaking Gitea, which meant I couldn’t access my infrastructure documentation. While fixing it at 3 AM, I realized I was solving the wrong problem. The issue wasn’t the broken package - it was the entire approach.</p>
</p>
Enter NixOS: Infrastructure as Code, But Actually</h2>
NixOS takes a radically different approach. Instead of imperatively installing packages and editing configs, you declare your entire system configuration in Nix files. Want PostgreSQL 15 with specific settings? Here’s your entire “installation process”:</p>
services</span>.</span>postgresql</span> </span>=</span> {</span></span>
  enable</span> =</span> true</span>;</span></span>
  package</span> =</span> pkgs</span>.</span>postgresql_15</span>;</span></span>
  settings</span> =</span> {</span></span>
    shared_buffers</span> =</span> "256MB"</span>;</span></span>
    max_connections</span> =</span> 100</span>;</span></span>
  };</span></span>
}</span>;</span></span></code></pre>
Deploy it with nixos-rebuild switch</code>. Made a mistake? Roll back instantly with nixos-rebuild switch --rollback</code>. Every change is atomic, reproducible, and version controlled.</p>
My Infrastructure Evolution</h2>
Today, my homelab runs entirely on NixOS, managed through a single Git repository</a>. In fact, the blog you’re reading right now is hosted on this very infrastructure, built and deployed through the same NixOS configuration. Let me introduce the main players:</p>
Storage: The Workhorse</h3>
My primary server is “storage” - an Intel powered box with 32GB DDR5 RAM and a bcachefs array for data integrity. It’s the heart of my homelab, running 30+ services from media streaming to development tools:</p>
Service Categories:</strong></p>

Media Stack</strong>: Plex, Jellyfin, complete *arr suite for automation</li>
Storage</strong>: Nextcloud, Seafile, Samba shares, Time Machine server</li>
Development</strong>: Gitea, code-server, CI/CD runners</li>
Monitoring</strong>: Grafana, Prometheus, Netdata, Loki for logs</li>
</ul>
The Intel integrated GPU handles all video transcoding, keeping the CPU free for other tasks. With bcachefs providing data integrity and compression, it’s both reliable and efficient.</p>
Cloud: The Public Face</h3>
“Cloud” is an ARM64 Oracle Cloud VPS (free tier - 4 cores, 24GB RAM) that serves as my authentication hub and public gateway. It runs LLDAP for user management, Dex for OIDC, and Authelia for 2FA - essentially handling all authentication for my infrastructure. Public services like blogs and chat run here too, all behind Cloudflare and Authelia protection.</p>
The beauty? Both machines share 90% of their configuration through modules. Storage handles the heavy lifting, Cloud provides secure access.</p>
The GitHub Actions Magic</h2>
Here’s where it gets interesting. Every push to my repository triggers automated builds and deployments:</p>
# .github/workflows/deploy.yml</span></span>
name</span>:</span> Deploy NixOS Hosts</span></span>
</span>
on</span>:</span></span>
  push</span>:</span></span>
    branches</span>:</span> [</span> main</span> ]</span></span>
</span>
jobs</span>:</span></span>
  deploy</span>:</span></span>
    runs-on</span>:</span> ubuntu-latest</span></span>
    steps</span>:</span></span>
      -</span> uses</span>:</span> actions/checkout@v3</span></span>
      </span></span>
      -</span> name</span>:</span> Install Nix</span></span>
        uses</span>:</span> cachix/install-nix-action@v22</span></span>
        </span></span>
      -</span> name</span>:</span> Build configurations</span></span>
        run</span>: |</span></span>
          nix build .#nixosConfigurations.storage.config.system.build.toplevel</span></span>
          nix build .#nixosConfigurations.cloud.config.system.build.toplevel</span></span>
          </span></span>
      -</span> name</span>:</span> Deploy to hosts</span></span>
        run</span>: |</span></span>
          nix run .#deploy.storage</span></span>
          nix run .#deploy.cloud</span></span></code></pre>
Push to main, grab coffee, and watch your infrastructure update itself. If something breaks? The old configuration is still running until the new one successfully builds.</p>
</p>
Why Not [Insert Solution Here]?</h2>
The homelab world is full of solutions, each with its own philosophy:</p>
TrueNAS</strong>: Great for storage, but I wanted more flexibility for running arbitrary services. Plus, I like my ZFS configuration in version control.</p>
Proxmox + LXC/VMs</strong>: Powerful, but adds a virtualization layer I didn’t need. I prefer bare metal performance for media transcoding.</p>
CasaOS/Umbrel/etc</strong>: Perfect for beginners! But I wanted more control and the ability to run services these platforms don’t support.</p>
Kubernetes</strong>: I use it at work. My homelab is where I go to escape</em> YAML hell, not create more of it.</p>
Docker Swarm/Nomad</strong>: Still requires managing the underlying OS. NixOS manages everything from kernel to containers.</p>
NixOS sits in the “very technical” category - it’s not for everyone. The learning curve is steep, the documentation can be sparse, and you’ll definitely spend a weekend figuring out why your first configuration won’t build. But once it clicks? You’ll never want to manage infrastructure any other way.</p>
The Reality Check</h2>
Let’s be honest - NixOS isn’t all roses:</p>

Learning Curve</strong>: Nix’s functional language takes time to grok</li>
Ecosystem</strong>: Some software needs packaging or workarounds</li>
Resource Usage</strong>: Keeping multiple system generations eats disk space</li>
Compilation</strong>: Sometimes you’ll need to build packages from source</li>
</ul>
But for a technical user who wants reproducible infrastructure? The tradeoffs are worth it.</p>
What’s Next?</h2>
In my next post, I’ll dive into the Constellation Pattern - how I structure my NixOS configurations to share code between hosts while maintaining flexibility. We’ll look at real examples from my repository and how to build your own modular NixOS infrastructure.</p>
For now, if you’re tired of the “pets vs cattle” debate and want infrastructure that’s more like “robots that configure themselves,” give NixOS a look. Your future self at 3 AM will thank you.</p>
Want to see how it all works? Check out my NixOS configuration on GitHub</a> - everything from this blog’s deployment to my entire homelab is there.</p>


About
Alex Rosenfeld — Sun, 01 Jan 2023 00:00:00 +0000
About Alexandre Rosenfeld</h1>
I’m a Senior Software Architect based in Montreal, Canada, with a passion for building great teams and products. My journey in technology spans over 15 years, from contributing to open source projects as a Computer Engineering student in Brazil to architecting scalable solutions for global companies.</p>
Professional Journey</h2>
Currently serving as Senior Software Architect at ACCESS Newswire, I specialize in re-architecting products using microservices and modern cloud architectures. Previously, I led the Programming & DevOps team at Ubisoft, where I implemented DevOps practices and observability systems that transformed how teams deliver software.</p>
My technical expertise spans multiple languages and frameworks - from C# and Python to Laravel and React - but my true passion lies in solving complex problems and helping teams grow.</p>
A Long History with Open Source</h2>
My open source journey began in 2008 as a Google Summer of Code participant, working on Conduit for the GNOME project. This experience shaped my philosophy about data ownership and interoperability - themes that still resonate in my work today. Back then, I dreamed of applications that could seamlessly share and transform data, making computers truly useful for their users.</p>
From Data Liberation to Self-Hosting</h2>
Over the years, my focus evolved from data interoperability to infrastructure ownership. I’ve been running self-hosted infrastructure for over a decade, progressing through various solutions:</p>

Started with simple scripts and manual configurations</li>
Moved to Docker Compose for containerization</li>
Experimented with Kubernetes for orchestration</li>
Finally settled on NixOS for declarative, reproducible systems</li>
</ul>
Today, I maintain a fleet of NixOS machines ranging from ARM-based routers to powerful x86 servers, all managed through declarative configuration.</p>
What You’ll Find Here</h2>
This blog chronicles my ongoing experiments with:</p>

NixOS patterns and configurations</strong> from real production systems</li>
Self-hosting solutions</strong> as alternatives to cloud services</li>
Infrastructure automation</strong> using declarative approaches</li>
Technical deep-dives</strong> into networking, containerization, and system design</li>
</ul>
All configurations and code shared here are from my actual setup, available on GitHub</a>.</p>
Beyond Code</h2>
I speak five languages (Portuguese, English, French, Spanish, and German) and believe that effective communication is as crucial as technical skills. I’m passionate about mentoring, always learning, and helping others grow in their careers.</p>
Contact</h2>

Email</strong>: alex@rosenfeld.one</li>
GitHub</strong>: @arsfeld</a></li>
LinkedIn</strong>: linkedin.com/in/a-rosenfeld</a></li>
Website</strong>: arsfeld.dev</a></li>
</ul>
Feel free to reach out if you have questions about any of the configurations or patterns discussed here, or if you just want to chat about self-hosting, NixOS, or technology in general!</p>


Laravel and Azure SQL Server
Alex Rosenfeld — Tue, 14 Jul 2015 00:00:00 +0000
From the same project as my last blog post</a>, we had to connect a Laravel 5 web application to a SQL Server instance running on Azure. It took me awhile to get everything working well, so I want to share a few tips for anyone looking for something like that.</p>
A quick Google search gives lots of good resources and once you find out the SQL Server connector in Ubuntu / Linux is actually called FreeTDS or Sybase (btw, Wikipedia has a nice article</a> about why this name), you’re good to go with a few apt-get </strong>commands if you’re on Ubuntu:</p>
sudo apt-get install freetds-common freetds-bin unixodbc php5-sybase
</pre>
Great, but then you get this error:</p>
SQLSTATE[01002] Adaptive Server connection failed (severity 9)
</pre>
Oops! This happens because we’re trying to connect to an Azure server, so you can actually ignore this if you’re not getting this error.</p>
Somewhere in the internet you discover you have to change the TDS</a> protocol version to connect to Azure. Cool! You also discover you can do that in a configuration file. So, open up /etc/freetds/freetds.conf</code> and change a few lines around:</p>
[global]
        # TDS protocol version
        ;tds version = 4.2
        tds version = 8.0
</pre>
Everything is great and life can move on!</p>
Or, so you thought! Once you started handling dates in your models, all hell break loose and you start to get Carbon and Datetime issues everywhere. Don’t worry, the fix is simple again</a>, now go to /etc/freetds/locales.conf</code> and make it look like:</p>
[default]
date format = %Y-%m-%d %I:%M:%S.%z</pre>
Now you can actually start working on something productive again!</p>


Laravel 5 and FileMaker
Alex Rosenfeld — Tue, 30 Jun 2015 00:00:00 +0000
A few weeks ago I was searching Google for exactly the two words in the title, how to connect a Laravel 5 web application to a FileMaker database and I couldn’t find anything at all. Not really surprising, since that is one of the last things you would want to do.</p>
So, why we wanted to do that in the first place? Well, we have a client that has a legacy application running on FileMaker and maintaining it was becoming a huge burden, so they want to migrate to something else. The server itself to host FileMaker is expensive (let alone it has to be a Mac or Windows) and it’s almost impossible to add new features.</p>
While a Laravel connector for FileMaker was not found, I did find a PHP library to connect to FileMaker called SimpleFM</a>. Adding a provider for it in Laravel was pretty easy (I also included the .env configuration introduced in Laravel 5 and the database.php configuration).</p>
Code:</strong> View GitHub Gist</a></p>
There is a bunch of ways you could have implemented this, I just wanted an easy way to get a FileMaker connection.</p>
I also wanted to see information about the available layouts, since I prefer to avoid logging in to FileMaker at all costs. So I wrote a command to display all layout names in a database or to display column information in a specific database:</p>
Code:</strong> View GitHub Gist</a></p>
Please note: I’m using a Laravel 5.1 feature to describe the command as a signature, instead of the obscure and error-prone getOptions and getArguments.</strong></p>
Use it like this:</p>
./artisan fm:show
</pre>
Getting layout names
• Layout1
• Layout2
...
</pre>
And you get a pretty table in response of a specific layout:</p>
./artisan fm:show REPORTS
</pre>
Getting info for REPORTS
+-------+-------+-------+
| index | recid | modid |
+-------+-------+-------+
| 0 | 77 | 0 |
+-------+-------+-------+
</pre>
Take a look at the FileMaker docs</a> for more commands and then you’re ready to do whatever you want with FileMaker inside your Laravel 5 application.</p>
Happy hacking!</p>


GNOME 3.0 and Fedora 15
Alex Rosenfeld — Tue, 12 Apr 2011 00:00:00 +0000
On last sunday it happened the FLISOL, which I was able to partially attend here in La Paz. It was a good event, though I wasn’t able to see all the talks. Unfortunately I didn’t had much time to convince people to use GNOME 3, but I did a short 15 minute demonstration of GNOME 3.0 running on the Fedora livecd. Most questions were about how to use it in Ubuntu, so I had some bad news for them.</p>
As a user of GNOME, I need to say thank you for everyone involved in the GNOME 3.0 release. I started using it only last week and I fell in love immediately. It’s not only beatiful and great to use, it’s also inspiring. It’s great to see the direction GNOME is taking and what we can build on.</p>
I also have to say congratulations to the Fedora guys. I installed Fedora 15 Alpha then updated to the latest packages. Even with the Alpha packages it was rock solid. Sure enough after using it for my day to day work for a week I had some crashes, but it’s amazingly stable. And it has some cool features as well (I love the systemd idea). So at least for me, Fedora has everything to be the best distro around this year.</p>


First impressions with Gnome 3
Alex Rosenfeld — Fri, 25 Mar 2011 00:00:00 +0000
I tried Gnome Shell a few months ago but I had so many issues I didn’t actually experienced anything. Yesterday I downloaded the Gnome 3 livecd but it seems my Radeon doesn’t work at all with it (all I see are some random dots in the screen even with safe mode on). Since I still wanted to test Gnome 3, I updated an Arch Linux installation I had to Gnome 3 (took a long time to download since I had tons of stuff to update). So then I was finally able to actually test Gnome 3 today. And I was quite impressed by two things.</p>
One, it crashed a lot for me. Don’t know if it’s a Gnome 3 issue or an Arch Linux issue. But it crashed every 5 minutes. I couldn’t change the wallpaper without it crashing. And most of the times it wouldn’t login telling me something went wrong and I had to logout. I even added a new user to make sure the old settings were not giving it problems, but it was the same.</p>
I do hope these things are eventually fixed, because of my second point. I loved it! It’s amazingly beautiful, I loved the animations, loved the details like how items glow when you hover them. I loved the menus on the top right and how I could press the Super button to get the overview mode. The new control center is beautiful and it just feels right.</p>
I tried Unity last week and in my personal opinion, the Gnome 3 experience is far better then anything Ubuntu can offer right now.</p>


Back to Ext4 from Btrfs
Alex Rosenfeld — Mon, 27 Dec 2010 00:00:00 +0000
After using Btrfs on both my work and home machines, I’m switching back to ext4. I actually like Btrfs and I wish I could keep using it, but I had two major issues.</p>
The first one and this was enough for me to switch back to ext4, Google Chrome startup time was almost 10 times slower. At first I didn’t realize it was Btrfs causing this, but after some investigation</a>, it’s noticeable how fragmentation affects some applications using Btrfs. I actually switched my work machine to ext4 after I found I could not use the virtual machines I had anymore, because it kept reading the disk for hours at anything I did in the virtual machine (in the end they could not even boot anymore). Btrfs is not always slower, or at least not noticeable, but for a few scenarios that can cause fragmentation, they really do make Btrfs unusable for me.</p>
The second one might just be a misunderstanding of my part, but I read manuals and wikis and could not find an answer. I started with one 150GB partition at work and had another 150GB partition if I wanted to easily switch back to ext4. Then I wanted to test adding multiple devices to Btrfs, which it makes really easy, and added the other partition to the first and did a balance operation, so data was distributed between them. What I did not realize, is that by doing that it created a RAID 1 with my partitions. As far as I know, RAID 1 with two partitions in the same drive are just useless, it just duplicates data between both partitions. After reading more manuals, I learned that on creation time you can control the RAID level, but I found no way to do it afterwards. And the worst of it, I found no way to degrade back to RAID 0, so I found no way to remove the second partition from the filesystem, which means I ended up with 300GB of space being used as 150GB.</p>
And another issue I had, it was not always obvious how much disk space I had free. In some places it indicated 300GB, others 150GB. And in my home machine I even had an out of free space error when it indicated I had 6GB free.</p>
Despite its powerful features, I could not justify the problems I had. Actually, I was not using snapshots and sobvolumes as much as I expected. I believe this may change as more tools are written to take advantage of these features.</p>
I knew well before I started using it that it’s not production ready or even finished yet. Btrfs is definitely a step in the right direction and I hope I can try using it again in some time. It even managed not to lose any of my data despite me poking with stuff I did not understand.</p>


CONSOL 2010
Alex Rosenfeld — Tue, 14 Dec 2010 00:00:00 +0000
I just got back from Santa Cruz de la Sierra, Bolivia, where I was attending CONSOL 2010, the Congreso de Software Libre of Bolivia. And I had an amazing time over there and met some really amazing people. This is a thank you note for everyone there, for welcoming me and trying to understand my lousy spanish talking about Google Summer of Code and Gnome.</p>
It amazes me every day how far Gnome and my Summer of Code experience is taking me. I’m doing an internship in an open-source company in Bolivia simply because I had Gnome in my curriculum and it got the attention from someone. And I am learning so much, both from my work here and from living in such an incredible country as Bolivia, where the diversity and contrast is amazing even for someone coming from Brazil. And the motivation I saw there, not only because in the poorest country of South America, free software makes a lot of sense, but because of their passion to hacking on stuff, to learn about new stuff and make something useful out of all of that.</p>
So, congrats to these guys there and thank you for everything (especially Amos Batto and Hardy Beltran for inviting me).</p>
On a side note, Rhythmbox 0.13.2 released a few weeks ago contains my first real contribution to Gnome, with my Google Summer of Project of this year being released. So if you have an iPhone or Android, enable the DAAP plugin together with the Remote switch and enjoy controlling Rhythmbox anywhere in your home! Thanks to W. Michael Petulio, Jonathan Matthew and Peter, without their help this would never be released.</p>


Analyzing HTTP packets with Wireshark and Python
Alex Rosenfeld — Sun, 21 Nov 2010 00:00:00 +0000
I’m doing some reverse-engineering stuff and it has been quite fun so far (hopefully I’ll blog more about why I’m doing this in the future). I needed to dump some HTTP traffic and analyse the data. Of course, Wireshark comes straight to mind for something like this and it is indeed really useful. It took me some time to understand the Wireshark interface and I still think it’s hiding some great functionality from me. But anyway, I was able to set the filters I wanted and it was showing me exactly the data I wanted. But I still had to right-click the data I wanted and save it to disk, which was not ideal.</p>
Then I thought, if people were smart enough to build such a powerful tool, they probably created a command-line interface as well, probably with scripting. Indeed they did! The command-line interface is called Tshark and the scripting is done in Lua. But I don’t know Lua and it would take too much time to learn it for this task. So I started to look a way to dump everything and then write a small script in Python to extract the data I really want. Took some time but the solution was much simpler then I thought (by the way, there are probably other solutions for this, but my Google skills were not good enough to find anything obvious).</p>
First you run Tshark to dump any HTTP traffic to a XML file (I usually hate XML, but this time it was useful). This is what I used:</p>
sudo tshark -i wlan0 "host 192.168.1.100 and port 45000" -d tcp.port==45000,http -T pdml > dump.xml</pre>
Of course, it all depends on what you want to dump. You should read the “man pcap-filter” to get the capture filter right and it is really useful (crucial sometimes) to only get the traffic you want. And I wanted to treat traffic in port 45000 as HTTP, so I think that is what the -d switch does 😉 The most important thing it “-T pdml”, which tells tshark to dump in this XML format.</p>
Next thing is to analyze in Python, which was much easier than I thought. I was only worried about the data field in the HTTP packets, but if you take a look in the dumped file, you’ll see you have information about all kind of things. My script turned out to be this:</p>
from lxml import etree
import binascii
tree = etree.parse('dump.xml')
data = [binascii.unhexlify(e.get("value")) for e in tree.xpath('/pdml/packet/proto[@name="http"]/field[@name="data"]')]</pre>
I used lxml because I found it has great support for XPath, which is quite useful here. Also, the HTTP data is stored as a hex string, which you can easily convert with unhexlify. So, in the end I was able to automate an annoying process with just a few lines of code. And if I need anything else, it’s quite easy to expand the script. I’m quite happy with the results!</p>
Update: </strong>Someone pointed out in the comments about Scapy (http://www.secdev.org/projects/scapy/), which by reading it’s documentation seems awesome!</p>


glib-mkenums
Alex Rosenfeld — Thu, 12 Aug 2010 00:00:00 +0000
I’m posting this here both to help someone else looking for this and to check if I got everything right.</p>
I needed to use enums in a GObject property. So I needed a enum type</a> for my property param spec</a>. I thought I could hard-code it somehow, but after some long time pondering (actually knocking my head into the wall) I decided to integrate glib-mkenums</a> into autoconf so that it could generate the types for me automatically when running make from my C sources. Unfortunately for me, Google wasn’t being friendly when searching for information on glib-mkenums.</p>
I found somewhere, some program that used glib-mkenums in a simple way (sorry, I forgot where I fount it), close to what I had in mind, so I decided to adapt it to my needs. What I had to do was to add two more files, automatically generated (in this case named dmap-enums.c and dmap-enums.h) adding some commands</a> to Makefile.am (linked to Gitorious because WordPress removes all formatting). Hopefully that is the right way to do it, at least it is working for me.</p>


DACP in Rhythmbox: Week 11
Alex Rosenfeld — Fri, 06 Aug 2010 00:00:00 +0000
I just went from week 2</a> to week 11 in the GSoC progress</a> in my blog 😉 Well, there is not much to tell in a blog if there is not a picture to show (and showing off the iPhone remote working with Rhythmbox should not be any different than iTunes if I’m doing my job correctly).</p>
I realized these last weeks that I had completely mis-planned my project, because I had no idea what I was getting into. I thought DACP would be quite easy to implement and I would focus on other things (making a client library for instance). But I discovered it is a much more complex protocol then I thought, mostly because of DAAP.</p>
What I discovered is that DACP is just an extension for DAAP, and being an Apple protocol, it’s closed and has been reverse-engineered and re-implemented several times in the open source world. The problem is that DACP uses several features in DAAP that were not implemented in libdmapsharing, simply because there is no real standard on DAAP. It took some time for me to learn DAAP enough to find out what was missing in libdmapsharing for DACP to work.</p>
So I spent most of the time fixing, tweaking and implementing stuff on DAAP in libdmapsharing. Which was pretty cool, I improved a lot of my C skills, learned GObject (and quite frankly, liked it a lot) and learned a lot about DAAP and libdmapharing.</p>
By the way, thanks for all the people who have reverse-engineered DACP</a> and the pairing process</a>, you have greatly simplified my life. It’s truly great to work in the open-source world.</p>


Cryptkeeper in your Indicator Applet
Alex Rosenfeld — Thu, 24 Jun 2010 00:00:00 +0000
I like the Indicator Applet and I like Cryptkeeper, so I decided to create an indicator for Cryptkeeper:</p>
</a></p>
For anyone who doesn’t know, Cryptkeeper</a> is a very useful application that allows you to mount/unmount an encrypted folder with just one click. It’s one of the most useful applications running on my startup. But up until now it had a quite ugly icon:</p>
</a></p>
Can you spot the difference?</p>
This is actually a plot to make people to like it and finish it. The patch adds support for showing and letting you mount/unmount folders, but it doesn’t let you delete folders or view information, as it did. Also, when adding a new folder, it doesn’t show up on the list if you don’t restart Cryptkeeper. But the patch does what I wanted it to (I rarely create or delete an encrypted folder), so I probably won’t change it further.</p>
So, the patch is here</a>. Have fun 😉</p>


DACP in Rhythmbox: Week 2
Alex Rosenfeld — Mon, 07 Jun 2010 00:00:00 +0000
Last week there was the inclusion of libdmapsharing</a> in Rhythmbox (by the way, for all of you alpha testing Ubuntu, DAAP isn’t working in Rhythmbox because they haven’t included libdmapsharing in Ubuntu yet). So now I’m just a git pull and git merge away from following Rhythmbox master, which makes my job much easier.</p>
Last week didn’t see much work from me, I was mostly fixing some bugs and some bad decisions. But I noticed I never showed screenshots of my work here. Because I love screenshots, here they are.</p>
First you open your Remote application in iPhone, iPod Touch or Android device (note that on Android there is no passcode):</p>
</figure>Then in Rhythmbox, you type the passcode shown in your Remote. This allows Rhythmbox to pair with your Remote:</p>
</figure>Then Rhythmbox magically appears at your Remote list of libraries:</p>
</figure>“DACP on Rhythmbox” will become your library’s name over time. And of course, this doesn’t fully work yet, because Rhythmbox segfaults when the iPhone tries to connect. Well, what did you expected for about two weeks of work? I was pretty excited already when I saw my iPhone on the list of devices in Rhythmbox (by the way, I think I will create a new group called Remotes, I just didn’t find out how yet).</p>
Stay tuned for more later.</p>


GSoC 2010: DACP Support in Rhythmbox
Alex Rosenfeld — Fri, 21 May 2010 00:00:00 +0000
Community bonding is almost over so I thought I could share some details about my Google Summer of Code project.</p>
As the title says, I will implement DACP support for Rhythmbox. You probably never heard of DACP but you’ve probably seen it in action. It’s the protocol that is used by the Remote application in iPhone and iPod Touch.</p></figure>I’ll be implementing the server side in Rhythmbox, so you’ll be able to control Rhythmbox with your iPhone, iPod Touch or even your Android</a>.</p>
I’ll actually be implementing this inside libdmapsharing</a>, a DMAP (DAAP & DPAP)</a> library that was once extracted from Rhythmbox sources, improved and will be integrated again into Rhythmbox as a library, once my mentor’s patch</a> is accepted. So hopefully, more applications will be able to support DACP, DAAP and DPAP by using libdmapsharing.</p>


Breadcrumb in Gtk
Alex Rosenfeld — Thu, 18 Feb 2010 00:00:00 +0000
Anyone knows how to implement (or anywhere it’s implemented) a breadcrumb / pathbar like the one in Nautilus in PyGtk? I just don’t know how to hide buttons that doent fit the window.</p>
By the way, anyone has seen this:</p>
</a></p>
That pathbar is gorgeous. It doesn’t look as good in action tough.</p>
I’ve been using the smaller Nautilus with the Elementary theme and it is just beautiful (the picture is from Elementary Remake, the original theme with that pathbar).</p>


Conduit GSoC
Alex Rosenfeld — Wed, 26 Aug 2009 00:00:00 +0000
Google Summer of Code is over and I still didnt blogged about the new interface for Conduit I wrote. Well, going back to university and doing multiple things at once can really slow things down.</p>
This shows the new UI with some conduits at the left</figcaption></figure>
Ok, so this is not final but I think it’s an improvement over the old UI</a>. The thing is, I was tired of owner-drawn widgets and I was tired of right-clicking things at the canvas (users didn’t even know that thing in the middle was the canvas). And the new UI gives me a reason to use all the work I did to rebuild the configuration system (see why dialogs was not enough?).</p>
What I still don’t like about it, is that it’s hard to get an overview of the conduit. Sinks are usually hidden so you don’t even know they are there sometimes. I was thinking about adding a button to hide and show the configuration, but I think that is confusing and not HIG-friendly.</p>
Another thing I’m unsure about is tabs. Everyone has tabs nowadays, do why not Conduit?</p>
New UI with tabs</figcaption></figure>
Hm, I don’t like that, it does look better but it’s rather confusing.</p>
I do like design, but I’m not very good at it. Anyone interested in giving me some tips? Maybe someone could draw those Mac-looking mockups, that would be great!</p>
Btw, thanks a lot John Carr and John Stowers for giving me the opportunity to work on this Summer of Code.</p>


Conduit GSoC Progress
Alex Rosenfeld — Thu, 06 Aug 2009 00:00:00 +0000
Thinking about another thing I’m implementing in Conduit I noticed I totally forgot to blog about my Summer of Code progress. So far there has been some hacking and fixing in several places and now I’m starting something very cool, which I really want to blog later.</p>
One of the first things I did this Summer of Code was to improve Conduit startup time. Conduit’s dataproviders come from very different places, such as Flickr, Google, Banshee, iPods, etc. Loading all these modules is very consuming, there are a lot of dependencies and very different requirements for each dataprovider. However, most of the time dataproviders are only used to show their icons in the left-pane, so we dont actually have to load them at all before we really need them. That is just what I did. It was quite easy actually, everything seems to be architectured to do that. All information we really need from each dataprovider was already organized in a central location and in order to work with dataproviders that come and go, the entire UI handles module wrappers instead of modules themselfs, so all we need are module wrappers that load the actual modules when needed. Then on the first Conduit run, all necessary information is pickled into a file in the user cache directory (usually under ~/.cache/conduit). This file is pretty small, so it’s way faster to load then all the modules together. And if anything changes with the modules, the file is modified.</p>
Of course, some problems arise. We really do need factories loaded all the time, those are the ones that create dataproviders for removeable devices and things that come and go (and very soon for online accounts). So I also had to split factories from their respective dataproviders. Some corner cases are still unresolved, such as our custom version of the Google library not loading everytime or the possibility of the iPod dataprovider not showing if you install the GPod library after starting Conduit for the first time (I could say “Who would do that?”, but I do sometimes 😉 I’ll probably disable the cache on these cases.</p>
Another thing I just implemented is the ability to save and restore everything from GConf, while we only used GConf for window settings before and kept all syncset information in a XML format. This means that settings are kept updated when you make any change, such as creating new conduits and, very soon, configure dataproviders. The XML format will still be around for any DBus application to use or some future backup service.</p>
Now I’m implementing an entirelly new UI. My idea was to use DBus to communicate with Conduit, making Conduit a true daemon process, but an idea for the new interface just popped into my head and I had to implement before I changed the DBus API for what I needed. It seems the troubles of using DBus for the GUI are greater then I predicted, but with this new UI it might be possible in the future. I’m insanely hacking at this new UI to have something 100% functional (hopefully very soon) and I’m really excited by it. I just hope the Conduit maintainers agree with me 🙂</p>


Conduit's improvements
Alex Rosenfeld — Mon, 25 May 2009 00:00:00 +0000
As GSoC is officially starting yesterday and I made a promess to finish what I begun almost six months ago (sorry about taking so long), last week I commited the last parts of my branch. So, in the end I rewrote the configuration system of Conduit, based on a previous limited implementation that I met when working at Summer of Code 2008. If anyone wants to know if Summer of Code works, it does. I would never knew so much about Conduit had I never entered Summer of Code last year.</p>
Why is the configuration system so important? Well, every dataprovider needs to be configured. What we do now, is that we open a configuration dialog for the user, with the standard configuration widgets: text entries, drop-boxes, item-lists, etc, and, of course, an OK and Cancel button. The problem was that every dataprovider had its own Gtk and Glade code, meaning a lot of duplicate code and usually confusing interfaces, not HIG-compliant at all. On top of that, every dataprovider showed their own configuration dialog, so we couldnt do anything else then displaying the dialog. Fixing all of this meant fixing each one of them.</p>
I started with the idea that in order to be more useful to outside applications, we had to be more flexible and we had to fix our problems once and for all in all configuration dialogs. I knew I would have to change every dataprovider we ship, so I wanted to do it only once. In the end I created a wrapper to Gtk, letting dataproviders only deal with what matter to them. Because we have a limited set of widgets, we can have a much more useful API then dealing with Gtk directly. We also get some benefits:</p>

Fixing code in one place fixes it for all dataproviders.</li>
Being HIG compliant is much easier.</li>
We could change from Gtk to something else in the future much more quickly.</li>
We can handle configuration dialogs on clients in a much better way (think about embedding an iPod sync configuration into Rhythmbox).</li>
We can do something else then dialogs for configuration. Think about a sidebar, a la Glade.</li>
</ul>
It was explicitely designed for the last two points, because my first work at Conduit was the iPod module and having the same iTunes experience of syncing it was one of the main goals.</p>
So, I wished to show a screenshot of how it looked before, but it seems we fixed so much of it lately (or we screwed up so much before) I can’t run older version. Anyway, here is a screenshot of the new code:</p>
Picasa Screenshot</figcaption></figure>
Of course, we changed a lot of code with the last commits and not without bugs. Our UI is still quite bad, but hopefully we can improve it soon.</p>
I should start thinking about this year’s Summer of Code now. Hopefully we will have something really good at the end of the summer (my winter actually).</p>


Introduction
Alex Rosenfeld — Thu, 07 May 2009 00:00:00 +0000
Let me introduce myself, I am Alexandre Rosenfeld, a Computer Engineering student from Brazil, at the University of São Paulo. I have participated on the Google Summer of Code 2008, working on Conduit. Since then I’ve kept working on Conduit and now I’ve been selected for the Google Summer of Code 2009, to work on making Conduit a background service. Let me just say that since last year Summer of Code I’m getting involved in the Gnome community and I’m enjoying it very much.</p>
I’d like to start talking about why I’m involved in Conduit and how I think it solves one of my favorite problems. I’ve always thought the data in my computer to be mine, just as everybody else, I think. But I always wanted to do stuff with my data, making the computer really useful. But I never could really get what I wanted without coding. So some time ago I had an idea about an application that would allow people to drag and drop components that would process their data in new and interesting ideas. This application would be kind of an script intrepeter, but without writing the script. So, as years went by, I never implemented my idea but I always found something that could be solved by my application or something that resembled it. I was very excited with Yahoo Pipes, as it resembled a lot to what I thought about the interface, but it eventually got me down as it is much different from what I had in mind.</p>
But then I met Conduit. I allows me to pass my data from one point to another, while processing it in different ways. It even knows what kind of data it is passing around and it can make decisions based on that. The first thing I did was to try to sync my iPod, which at the time no application could do something as simple as check what songs was already in the iPod and copy songs not in there. To be honest I was creating scripts for that for a while, but running scripts in the terminal is boring. Eventually that led me to improve the Rhythmbox dataprovider, then the iPod and media classes in Conduit as part of Google Summer of Code 2008 and then I couldn’t stop having ideas for Conduit. Ok, it isn’t doing what I dreamed about, but it is pretty close and it is interesting as hell (for me at least).</p>
Everywhere I look I see data in my computer not getting their full potential. I want a more dynamic world, a place where my data is recognized the way they are, rich, full of metadata and meaningfull to me, and it should be presented and handled like that. The reason social websites are all the hype is because they recognized that people’s data are the most precious things. People post their photos on Facebook and Orkut and it gets tagged and commented. People listen to their music on Last.fm and again, it is tagged, commented and discussed. But when you open your file manager, you get a note icon for your music and your photos appears as simple thumbnails.</p>
Imagine if your applications could interact with your data, no matter where they are, in new and interesting ways, using their full potential? That is where I want Conduit to be, pushing data between applications, web services, devices, etc. It already knows how connect to most of them, all it needs is these things talking together. Applications should be able to use it Conduit as a data service.</p>
My proposal is one step in that direction, bringing Conduit closer to applications. Not a big step, but it’s a start. I know a lot of people (pretty smart people) are thinking about these things, SuperDataDaemonThing</a>, Nepomuk</a>, Tracker</a>, etc, and this is just my way of helping.</p>


Google Summer of Code 2009
Alex Rosenfeld — Tue, 21 Apr 2009 00:00:00 +0000
I have just been approved for Google Summer of Code 2009, which means I can once again work on a great project, the Conduit</a> application.</p>
This year my project is “Making Conduit work as a daemon”, which is by itself a great project and will allow me to implement some ideas I’m having for about a year (or at least find out why I can’t implement them 🙂 )</p>
But what is more important is how I think it helps Gnome into better integrating the Gnome desktop with the online world. Conduit working as a daemon is much more then a synchronization application running in the background, it is a service to access any data, both local and online, indenpendently of API, language or binding, because it is available in a DBus service abstracting all the details. What is more important, is that applications dont have to implement support for every website in the planet, because that is done inside the Conduit API as modules (and plugins, as soon as I finish implementing them).</p>
I would like to details more how all of that is possible and how I think my work can help with that, but I’ll leave that for later. For now I’m just celebrating being accepted!</p>


Something to fix
Alex Rosenfeld — Thu, 09 Apr 2009 00:00:00 +0000
So, this is my first post on this blog. I tried blogging before, but I never wrote much. I didnt have much to write about. But now my life is getting quite busy and I’m quite excited about many things I’m doing, so why not try to blog again.</p>
Let’s start about the title. Well, I just wrote in the About page that I now have a focus in my life and that focus is the computer. More specifically, the human-computer interaction. I’m not only thinking about user interfaces, altough that is one area I am really interested about, but I am talking about everything that involves a computer in our daily activities. Somehow, I think the computer the way we use them now are just getting in the way. We are making people adapt to the computer, instead of the computer adapting to our workflow.</p>
So, no, I dont know how to fix it, I just think it should be fixed. So, my focus? I want to learn as much as I can about our computer usage now. But I am not just standing still, waiting for something better to come along. No, I believe we can fix it from the inside. So I am also learning as much as I can about programming, which is one of my biggest passions, so I can actually try do something useful now.</p>
Later on I’ll explain about how that translates to my current work.</p>

Alex Rosenfeld

Reel Rewrite: How Relm4 Saved My Media Streaming Client

Wrong Abstractions</h3> I initially designed around a single backend to Plex. Simple, right? Except users have multiple Plex servers on one account. And then Jellyfin support meant multiple account types. The entire foundation was wrong, and every feature built on top inherited these flaws.</p>

Going All In</h2> One particularly frustrating evening, after breaking the video player yet again while trying to add a minor feature, something snapped. I decided to burn it all down and rebuild from scratch using Relm4 properly.</p> This meant:</p>

The New Architecture</h2> The rewrite brought clarity. With Relm4, I could finally map concepts to architecture the right way.</p>

Reel: Bringing Native Media Streaming to the GNOME Desktop

Why Rust?</h3> Why not? 🦀</p>

The Subtitle Situation</h3> As mentioned, GStreamer subtitle rendering has some colorspace issues that I’m investigating. The MPV backend provides a workaround for now, but fixing the GStreamer issue properly is a priority—it’s the better integrated solution for GNOME.</p>

Performance Optimization</h3> Loading large libraries can still feel sluggish. I’m working on:</p>

Feature Parity</h3> Compared to official clients, we’re still missing:</p>

The Road Ahead</h2> Looking at my TASKS.md</a>, the focus is on polish and usability:</p>

Medium Term</h3> Local files backend</strong>: For your personal collection</li> Music support</strong>: Because media isn’t just video</li>

Get Involved</h2> Reel is still in active development, and I’d love your help:</p>

Monitor Per-Client Network Usage with Custom Metrics

Step 1: Set Up Basic Monitoring Stack</h2> First, let’s get Prometheus and Grafana running on your router.</p>

Enable Prometheus</h3> Add to your router configuration:</p>

Enable Grafana</h3> Add Grafana for visualization:</p>

Open Firewall Ports</h3> Allow access from your LAN:</p>

Architecture Overview</h3> The exporter consists of two main components working together:</p>

2. The Supporting Service</h4> client-traffic-tracker.service</code></strong> - A bash script that runs when enableNftablesIntegration = true</code>:</p>

How nftables Integration Works</h3> When you set enableNftablesIntegration = true</code>, the module sets up sophisticated packet accounting:</p>

Performance Characteristics</h3> Real-world measurements from an Intel Celeron N5105 router (4 cores @ 2.0-2.9 GHz) with 25+ active clients:</p>

Understanding the Metrics</h3> The exporter provides comprehensive metrics:</p>

Step 3: Configure the Exporter</h2> Let’s enable and configure the network-metrics-exporter</a>.</p>

Configure Static Client Names</h3> Pre-configure friendly names for known devices:</p>

Add to Prometheus Scraping</h3> Update your Prometheus configuration:</p>

Step 4: Build Powerful Dashboards</h2> Now the fun part - creating dashboards that give you instant visibility into your network usage.</p>

Key Dashboard Panels</h3> The repository includes pre-built dashboard panels</a> that provide comprehensive network visibility:</p>

Active Clients Count</h4> Shows the total number of active clients on your network:</p> count(count by (ip) (client_active_connections{job="network-metrics"}))</span></span></code></pre>Client Connection Count Table</h4> Displays each client’s active connections in a sortable table:</p>

Client Connection Count Table</h4> Displays each client’s active connections in a sortable table:</p>

Real-time Client Bandwidth</h4> Live graph showing download/upload speeds per client:</p>

Client Bandwidth Analysis</h4> Detailed per-client bandwidth usage over time with legend showing current/avg/max values.</p>

Total Bandwidth Gauges</h4> Total Download Bandwidth (Mbps)</strong> - Aggregate download across all clients</li>

Creating Custom Panels</h3> For a bandwidth usage timeline:</p> Create new panel → Time series</li> Add query: rate(network_client_rx_bytes_total[1m]) * 8 / 1000000</code></li> Legend: {{hostname}} - Download</code></li> Unit: Mbps</code></li>

Troubleshooting</h2>

Advanced Usage</h2>

How to Write Tests for Your NixOS Router Configuration

Moving to Flakes</h2> Starting with this post, we’ll use Nix Flakes for a more structured and reproducible configuration. Flakes provide:</p>

Prerequisites</h2> A working NixOS router from Part 1</li> Basic familiarity with Nix expressions</li> Nix with flakes enabled</li>

Step 1: Introduction to NixOS Tests</h2> NixOS has a powerful testing framework that spins up virtual machines to test your configuration. Tests are written as Nix expressions that:</p>

Running Tests Locally</h3> With flakes, run your test like this:</p>

Step 2: Write Connectivity Tests</h2> Let’s write tests that verify our router provides internet access and serves DHCP correctly.</p>

Test Internet Access</h3> Here’s how we test connectivity in the actual router test:</p>

Test LAN Connectivity</h3> Add another client to test LAN-to-LAN communication:</p>

Test Service Availability</h3> Verify essential services are running:</p>

Step 3: Test Your Features</h2> Now let’s test specific features of your router configuration.</p>

Step 4: Integrate with Deployment</h2>

Troubleshooting Common Issues</h2>

Build Your Own Router with NixOS: Part 1 - Getting Started

Minimum Requirements</h3> 2+ network interfaces</strong> (NICs) - one for WAN, one for LAN</li> x86_64 CPU</strong> - NixOS has excellent x86_64 support</li> 4GB+ RAM</strong> - More if you plan to run additional services</li>

Recommended Budget Option: Intel N5105 Mini PC</h3> For around $150, Intel N5105-based mini PCs offer excellent value:</p>

Where to Buy</h3> AliExpress</strong>: Best prices, 2-4 week shipping Search for “N5105 mini PC 4 LAN”</li> Popular vendors: Topton, CWWK, Beelink</li> </ul> </li>

Step 3: Create Minimal Router Configuration</h2> Replace your /etc/nixos/configuration.nix</code> with this minimal router setup. We’ll use dnsmasq which provides both DHCP and DNS services in a single, lightweight package:</p>

Step 4: Test Your Router</h2>

Resources</h2> NixOS Manual - Networking</a></li> My Router Configuration</a></li> NixOS Discourse - Networking Topics</a></li> </ul> Have questions or run into issues? Feel free to open an issue on the repository</a> or reach out on the NixOS forums!</p>

Building a 2.5Gbps Home Router with NixOS

Evolution of My Router Setup</h2>

First Attempt with NixOS</h3> Three years ago, I discovered NixOS and was attracted to its declarative configuration approach. Version control for system configuration seemed ideal for a router.</p> The concept was appealing:</p>

Return to NixOS with Better Tooling</h3> In 2025, with improved tooling including AI coding assistants, I revisited NixOS for routing. The key difference was developing a comprehensive test suite.</p> The test coverage includes:</p>

What’s Next?</h2> If you’re interested in building your own NixOS router, I’ve created a tutorial series that walks you through the process:</p>

Simplifying NixOS Configurations with Reusable Modules

Anatomy of a Constellation Module</h2> Let’s examine the constellation.common</code> module to understand the pattern:</p>

Wrong Abstractions</h3>
I initially designed around a single backend to Plex. Simple, right? Except users have multiple Plex servers on one account. And then Jellyfin support meant multiple account types. The entire foundation was wrong, and every feature built on top inherited these flaws.</p>

Why Rust?</h3>
Why not? 🦀</p>

The Subtitle Situation</h3>
As mentioned, GStreamer subtitle rendering has some colorspace issues that I’m investigating. The MPV backend provides a workaround for now, but fixing the GStreamer issue properly is a priority—it’s the better integrated solution for GNOME.</p>

The Road Ahead</h2>
Looking at my TASKS.md</a>, the focus is on polish and usability:</p>

Step 1: Set Up Basic Monitoring Stack</h2>
First, let’s get Prometheus and Grafana running on your router.</p>

Architecture Overview</h3>
The exporter consists of two main components working together:</p>

How nftables Integration Works</h3>
When you set `enableNftablesIntegration = true</code>, the module sets up sophisticated packet accounting:</p>`

Step 3: Configure the Exporter</h2>
Let’s enable and configure the network-metrics-exporter</a>.</p>

Step 4: Build Powerful Dashboards</h2>
Now the fun part - creating dashboards that give you instant visibility into your network usage.</p>

Key Dashboard Panels</h3>
The repository includes pre-built dashboard panels</a> that provide comprehensive network visibility:</p>

Client Bandwidth Analysis</h4>
Detailed per-client bandwidth usage over time with legend showing current/avg/max values.</p>

Step 2: Write Connectivity Tests</h2>
Let’s write tests that verify our router provides internet access and serves DHCP correctly.</p>

Step 3: Test Your Features</h2>
Now let’s test specific features of your router configuration.</p>

Resources</h2>

NixOS Manual - Networking</a></li>
My Router Configuration</a></li>
NixOS Discourse - Networking Topics</a></li> </ul>
Have questions or run into issues? Feel free to open an issue on the repository</a> or reach out on the NixOS forums!</p>