RCM: The Ruby Configuration Management DSL

2026-03-02T00:00:00+02:00

RCM: The Ruby Configuration Management DSL

Distributed Systems Simulator - Part 3: Advanced Examples and Protocol API

-Published at 2026-03-02T00:00:00+02:00
+Published at 2026-04-02T00:00:00+03:00

-RCM is a tiny configuration management system written in Ruby. It gives me a small DSL for describing how I want my machines to look, then it applies the changes: create files and directories, manage packages, and make sure certain lines exist in configuration files. It's deliberately KISS and optimised for a single person's machines instead of a whole fleet.
+This is the third and final blog post of the Distributed Systems Simulator series. This part covers advanced simulation examples, the Raft consensus protocol, and the extensible Protocol API.

-
+ds-sim on Codeberg (modernized, English-translated version)
+
+These are all the posts of this series:
+
+2026-03-31 Distributed Systems Simulator - Part 1: Introduction and GUI
+2026-04-01 Distributed Systems Simulator - Part 2: Built-in Protocols
+2026-04-02 Distributed Systems Simulator - Part 3: Advanced Examples and Protocol API (You are currently reading this)
+
+

RCM: The Ruby Configuration Management DSL
⇢ Why I built RCM
⇢ How the DSL feels
⇢ ⇢ Keywords and resources
⇢ ⇢ Files, directories, and templates
⇢ How Ruby's metaprogramming helps
⇢ ⇢ A bit more about method_missing
⇢ Ruby metaprogramming: further reading
⇢ Safety, dry runs, and debugging
⇢ RCM vs Puppet and other big tools
⇢ Cutting RCM 0.1.0
⇢ What's next
⇢ Feature overview (for now)
⇢ ⇢ Template rendering into a file
⇢ ⇢ Ensuring a line is absent from a file
⇢ ⇢ Guarding a configuration run on the current hostname
⇢ ⇢ Creating and deleting directories, and purging a directory tree
⇢ ⇢ Managing file and directory modes and ownership
⇢ ⇢ Using a chained, more natural language style for notifications
⇢ ⇢ Touching files and updating their timestamps
⇢ ⇢ Expressing dependencies between notifications
⇢ ⇢ Creating and updating symbolic links
⇢ ⇢ Detecting duplicate resource definitions at configure time
Distributed Systems Simulator - Part 3: Advanced Examples and Protocol API
⇢ Additional Examples
⇢ ⇢ Lamport and Vector Timestamps
⇢ ⇢ Simulating Slow Connections
⇢ ⇢ Raft Consensus Failover
⇢ Protocol API
⇢ ⇢ Class Hierarchy
⇢ ⇢ Implementing a Custom Protocol
⇢ ⇢ Available API Methods
⇢ ⇢ Example: Reliable Multicast Implementation
⇢ Project Statistics

Why I built RCM

Additional Examples

-I've used (and still use) the usual suspects in configuration management: Puppet, Ansible, etc. They are powerful, but also come with orchestration layers, agents, inventories, and a lot of moving parts. For my personal machines I wanted something smaller: one Ruby process, one configuration file, a few resource types, and good enough safety features.
-
-I've always been a fan of Ruby's metaprogramming features, and this project let me explore them in a focused, practical way.
+

Lamport and Vector Timestamps

-Because of that metaprogramming support, Ruby is a great fit for DSLs. You can get very close to natural language without inventing a brand-new syntax. RCM leans into that: the goal is to read a configuration and understand what happens without jumping between multiple files or templating languages.
+

-RCM repo on Codeberg
+"For many purposes, it is sufficient that all machines agree on the same time. It is not necessary that this time also agrees with real time, like every hour announced on the radio... For a certain class of algorithms, only the internal consistency of clocks is important." - Andrew Tanenbaum

-

How the DSL feels

+Clocks that provide such a time are also known as logical clocks. Two implementations are realized in the simulator: Lamport timestamps and vector timestamps.

-An RCM configuration starts with a configure block. Inside it you declare resources (file, package, given, notify, …). RCM figures out dependencies between resources and runs them in the right order.
+After activating the Lamport time switch in expert mode, the current Lamport timestamp appears at every event of a process. Each process has its own Lamport timestamp that is incremented when a message is sent or received. Each message carries the current Lamport time t_l(i) of the sending process i. When another process j receives this message, its Lamport timestamp t_l(j) is recalculated as:

- -

configure do
-  given { hostname is :earth }
-
-  file '/tmp/test/wg0.conf' do
-    requires file '/etc/hosts.test'
-    manage directory
-    from template
-    'content with <%= 1 + 2 %>'
-  end
-
-  file '/etc/hosts.test' do
-    line '192.168.1.101 earth'
-  end
-end
++t_l(j) := 1 + max(t_l(j), t_l(i))
 
 

-Which would look like this when run:

+The larger Lamport time of the sender and receiver process is used and then incremented by 1. After the Berkeley simulation shown here, P1 has Lamport timestamp 16, P2 has 14, and P3 has 15.

 

-
-% sudo ruby example.rb
-INFO 20260301-213817 dsl(0) => Configuring...
-INFO 20260301-213817 file('/tmp/test/wg0.conf') => Registered dependency on file('/etc/hosts.test')
-INFO 20260301-213817 file('/tmp/test/wg0.conf') => Evaluating...
-INFO 20260301-213817 file('/etc/hosts.test') => Evaluating...
-INFO 20260301-213817 file('/etc/hosts.test') => Writing file /etc/hosts.test
-INFO 20260301-213817 file('/tmp/test/wg0.conf') => Creating parent directory /tmp/test
-INFO 20260301-213817 file('/tmp/test/wg0.conf') => Writing file /tmp/test/wg0.conf
+

+

+With the active vector time switch, all vector timestamps are displayed. Like the Lamport timestamp, each message includes the current vector timestamp of the sending process. With n participating processes, the vector timestamp v has size n. Each participating process i has its own index, accessible via v(i). When v is the vector timestamp of the receiving process j and w is the vector timestamp of the sending process, the new local vector timestamp of process j is calculated as follows:

+

++for (i := 0; i < n; i++) {
+    if (i = j) {
+        v(i)++;
+    } else if (v(i) < w(i)) {
+        v(i) := w(i);
+    }
+}
 
 

-The idea is that you describe the desired state and RCM worries about the steps. The given block can short‑circuit the whole run (for example, only run on a specific hostname). Each file resource can either manage a complete file (from a template) or just make sure individual lines are present.

+By default, the vector timestamp is only incremented when a message is sent or received. In both cases, the sender and receiver each increment their own index in the vector timestamp by 1. Upon receiving a message, the local vector timestamp is then compared with the sender's, and the larger value is taken for all indices.

 

-Keywords and resources


+After the simulation, P1 has vector timestamp (8,10,6), P2 has (6,10,6), and P3 has (6,10,8).

 

-Under the hood, each DSL word is either a keyword or a resource:

+The simulation settings include boolean variables "Lamport times affect all events" and "Vector times affect all events" (both default to false). When set to true, all events (not just message send/receive) will update the timestamps.

 

-
-Keyword is the base class for all top‑level DSL constructs.
-Resource is the base class for things RCM can manage (files, packages, and so on).
-


-Resources can declare dependencies with requires. Before a resource runs, RCM makes sure all its requirements are satisfied and only evaluates each resource once per run. This keeps the mental model simple even when you compose more complex configurations.

+Simulating Slow Connections


 

-Files, directories, and templates


+

 

-The file resource handles three common cases:

+The simulator can also simulate slow connections to a specific process. This example revisits the comparison of Internal Synchronization (P1) and Christian's Method (P3), with P2 serving both. In this scenario, P3 has a poor network connection, so messages to and from P3 always require a longer transmission time.

 

-
-Managing parent directories (manage directory) so you don't have to create them manually.
-Rendering ERB templates (from template) so you can mix Ruby expressions into config files.
-Ensuring individual lines exist (line) for the many "append this line if missing" situations.
-


-Every write operation creates a backup copy in .rcmbackup/, so you can always inspect what changed and roll back manually if needed.

+P3's minimum transmission time is set to 2000ms and maximum to 8000ms, while P1 and P2 keep the defaults (500ms/2000ms). The simulation duration is 20000ms. With the "Average transmission times" setting enabled, the effective transmission time for messages involving P3 is:

 

-How Ruby's metaprogramming helps


++1/2 * (rand(500,2000) + rand(2000,8000)) = 1/2 * rand(2500,10000) = rand(1250,5000)ms
+
 

-The nice thing about RCM is that the Ruby code you write in your configuration is not that different from the Ruby code inside RCM itself. The DSL is just a thin layer on top.

+Because P3 starts a new request before receiving the answer to its previous one, and because it always associates server responses with its most recently sent request, its RTT calculations become incorrect on each round, and its local time is poorly synchronized. P1 synchronizes to 21446ms (error: -1446ms) while P3 only reaches 16557ms (error: -3443ms).

 

-For example, when you write:

+Raft Consensus Failover


 

-
-file '/etc/hosts.test' do
-  line '192.168.1.101 earth'
-end
-
+

 

-Ruby turns file into a method call and '/etc/hosts.test' into a normal argument. Inside RCM, that method builds a File resource object and stores it for later. The block you pass is just a Ruby block; RCM calls it with the file resource as self, so method calls like line configure that resource. There is no special parser here, just plain Ruby method and block dispatch.

+While modernizing ds-sim, I also added a simplified Raft Consensus example. The simulation is intentionally small: three processes, one initial leader, one crash, a clean reelection, a recovery of the old leader, and then another crash later in the run. This makes it possible to see the most important Raft transitions without being overwhelmed by cluster size.

 

-The same goes for constructs like:

+The event log tells a very readable story. At 0ms, P1 starts as the initial leader in term 0. It immediately sends a heartbeat and an appendEntry message carrying the log entry cmd1. P2 joins at 100ms, P3 at 1700ms, and both acknowledge the leader's traffic. At that point the cluster is healthy: one leader, two followers, successful heartbeats, and successful log replication.

 

-
-given { hostname is :earth }
+At 3500ms, P1 crashes. The followers still process the last in-flight messages, but once the election timeout expires, P2 becomes a candidate and sends a voteRequest for term 1. P3 grants that vote, and at 9395ms the log records the decisive line:

+

++009395ms: PID: 2; ... Leader elected by majority vote: process 2 (term 1)
 
 

-RCM uses Ruby's dynamic method lookup to interpret hostname and is in that block and to decide whether the rest of the configuration should run at all. Features like method_missing, blocks, and the ability to change what self means in a block make this kind of DSL possible with very little code. You still get all the power of Ruby (conditionals, loops, helper methods), but the surface reads like a small language of its own.

+That transition is followed immediately by new heartbeats and a new appendEntry, which is exactly what you want to see in a Raft simulation: leadership is not just declared, it is exercised.

 

-A bit more about method_missing


+At 12002ms, the old leader P1 recovers. Importantly, it does not try to reclaim control. Instead, it receives heartbeats from P2 and answers with heartbeatAck messages, rejoining the cluster as a follower. That is one of the most useful teaching moments in the log, because it makes the term-based leadership model concrete: the recovered node does not become leader again just because it used to be one.

 

-method_missing is one of the key tools that make the RCM DSL feel natural. In plain Ruby, if you call a method that does not exist, you get a NoMethodError. But before Ruby raises that error, it checks whether the object implements method_missing. If it does, Ruby calls that instead and lets the object decide what to do.

+At 20000ms, P3 crashes. The cluster continues running with P2 as leader and P1 as follower for the rest of the 60-second simulation. The log remains dominated by periodic heartbeats from P2 and acknowledgments from P1, showing that the system stays stable even after a second failure.

 

-In RCM, you can write things like:

+This single scenario demonstrates several core Raft properties in one replay:

 

-
-given { hostname is :earth }
+
+Stable startup leadership
+Heartbeats and follower acknowledgments
+Log replication
+Leader failure detection
+Majority-based reelection
+Safe reintegration of a recovered former leader
+Continued service after a later follower crash
+


+It is also a good example of why a simulator is useful for distributed systems. In a real production system, reconstructing this sort of sequence would require stitching together logs from multiple nodes. Here, the message flow, the crashes, the recoveries, and the Lamport/vector timestamps are all visible in one place.

+

+Protocol API


+

+The simulator was designed from the ground up to be extensible. Users can implement their own protocols in Java by extending the VSAbstractProtocol base class. Each protocol has its own class in the protocols.implementations package.

+

+Class Hierarchy


+

++VSAbstractEvent
+  +-- VSAbstractProtocol (base class for all protocols)
+        +-- VSDummyProtocol
+        +-- VSPingPongProtocol
+        +-- VSBroadcastProtocol
+        +-- VSInternalTimeSyncProtocol
+        +-- VSExternalTimeSyncProtocol
+        +-- VSBerkeleyTimeProtocol
+        +-- VSOnePhaseCommitProtocol
+        +-- VSTwoPhaseCommitProtocol
+        +-- VSBasicMulticastProtocol
+        +-- VSReliableMulticastProtocol
 
 

-Inside that block, calls such as hostname and is don't map to normal Ruby methods. Instead, RCM's DSL objects see those calls in method_missing, and interpret them as "check the current hostname" and "compare it to this symbol". This lets the DSL stay small and flexible: adding a new keyword can be as simple as handling another case in method_missing, without changing the Ruby syntax at all.

+Implementing a Custom Protocol


 

-Put differently: you can write what looks like a tiny English sentence (hostname is :earth) and Ruby breaks it into method calls (hostname, then is) that RCM can interpret dynamically. Those "barewords" are not special syntax; they are just regular Ruby method names that the DSL catches and turns into configuration logic at runtime.

+Each protocol class must implement the following methods:

 

-Here's a simplified sketch of how such a condition object could look in Ruby:

+
+A public constructor: Must specify whether the client or the server initiates requests, using VSAbstractProtocol.HAS_ON_CLIENT_START or VSAbstractProtocol.HAS_ON_SERVER_START.
+onClientInit() / onServerInit(): Called once before the protocol is first used. Used to initialize protocol variables and attributes via the VSPrefs methods (e.g. initVector, initLong). Variables initialized this way appear in the process editor and can be configured by the user.
+onClientReset() / onServerReset(): Called each time the simulation is reset.
+onClientStart() / onServerStart(): Called when the client/server initiates a request. Typically creates and sends a VSMessage object.
+onClientRecv(VSMessage) / onServerRecv(VSMessage): Called when a message arrives.
+onClientSchedule() / onServerSchedule(): Called when a scheduled alarm fires.
+toString(): Optional. Customizes log output for this protocol.
+


+Available API Methods


+

+Methods inherited from VSAbstractProtocol:

+

+
+sendMessage(VSMessage message): Sends a protocol message (automatically updates Lamport and Vector timestamps)
+hasOnServerStart(): Whether the server or client initiates requests
+isServer() / isClient(): Whether the current process has the protocol activated as server/client
+scheduleAt(long time): Creates an alarm that fires at the given local process time, triggering onClientSchedule() or onServerSchedule()
+removeSchedules(): Cancels all pending alarms in the current context
+getNumProcesses(): Returns the total number of processes in the simulation
+


+Process methods available via the inherited process attribute:

+

+
+getTime() / setTime(long): Get/set the local process time
+getGlobalTime(): Get the current global simulation time
+getClockVariance() / setClockVariance(float): Get/set the clock drift
+getLamportTime() / setLamportTime(long): Get/set the Lamport timestamp
+getVectorTime() / updateVectorTime(VSVectorTime): Get/update the vector timestamp
+getProcessID(): Get the process PID
+isCrashed() / isCrashed(boolean): Check or set crash state
+getRandomPercentage(): Get a random value between 0 and 100
+


+Message methods (VSMessage):

+

+
+new VSMessage(): Create a new message
+getMessageID(): Get the message NID
+setBoolean(key, value) / getBoolean(key): Set/get boolean data
+setInteger(key, value) / getInteger(key): Set/get integer data
+setLong(key, value) / getLong(key): Set/get long data
+setString(key, value) / getString(key): Set/get string data
+getSendingProcess(): Get a reference to the sending process
+isServerMessage(): Whether it's a server or client message
+


+Example: Reliable Multicast Implementation


+

+Here is a condensed example showing key parts of the Reliable Multicast Protocol implementation:

 

 
-class HostCondition
-  def initialize
-    @current_hostname = Socket.gethostname.to_sym
-  end
+public class VSReliableMulticastProtocol extends VSAbstractProtocol {
+    public VSReliableMulticastProtocol() {
+        // The client initiates requests
+        super(VSAbstractProtocol.HAS_ON_CLIENT_START);
+        super.setClassname(super.getClass().toString());
+    }
 
-  def method_missing(name, *args, &)
-    case name
-    when :hostname
-      @left = @current_hostname
-      self               # allow chaining: hostname is :earth
-    when :is
-      @left == args.first
-    else
-      super
-    end
-  end
-end
+    private ArrayList pids;
 
-HostCondition.new.hostname.is(:earth)
+    // Initialize protocol variables (editable in the process editor)
+    public void onClientInit() {
+        Vector vec = new Vector();
+        vec.add(1); vec.add(3);
+        super.initVector("pids", vec, "PIDs of participating processes");
+        super.initLong("timeout", 2500, "Time until resend", "ms");
+    }
+
+    // Send multicast to all servers that haven't ACKed yet
+    public void onClientStart() {
+        if (pids.size() != 0) {
+            long timeout = super.getLong("timeout") + process.getTime();
+            super.scheduleAt(timeout);
+            VSMessage message = new VSMessage();
+            message.setBoolean("isMulticast", true);
+            super.sendMessage(message);
+        }
+    }
+
+    // Handle ACK from a server
+    public void onClientRecv(VSMessage recvMessage) {
+        if (pids.size() != 0 && recvMessage.getBoolean("isAck")) {
+            Integer pid = recvMessage.getIntegerObj("pid");
+            if (pids.contains(pid))
+                pids.remove(pid);
+            super.log("ACK from Process " + pid + " received!");
+            if (pids.size() == 0) {
+                super.log("ACKs from all processes received!");
+                super.removeSchedules();
+            }
+        }
+    }
+
+    // Retry on timeout
+    public void onClientSchedule() { onClientStart(); }
+}
 
 

-RCM's real code is more sophisticated, but the idea is the same: Ruby happily calls method_missing for unknown methods like hostname and is, and the DSL turns those calls into a value (true/false) that decides whether the rest of the configuration should run.

-

-Ruby metaprogramming: further reading


+Project Statistics


 

-If you want to dive deeper into the ideas behind RCM's DSL, these books are great starting points:

+The original VS-Sim project (August 2008) was written in Java 6 and consisted of:

 

 
-"Metaprogramming Ruby 2" by Paolo Perrotta
-"The Well-Grounded Rubyist" by David A. Black (and others)
-"Eloquent Ruby" by Russ Olsen
+61 source files across 12 Java packages
+Approximately 15,710 lines of code
+2.2 MB of generated Javadoc documentation
+142 KB compiled JAR file
+10 built-in protocols
+163 configurable settings
 


-They all cover Ruby's object model, blocks, method_missing, and other metaprogramming techniques in much more detail than I can in a single blog post.

+The modernized successor ds-sim (version 1.1.0) has been updated to Java 21 and translated to English:

 

-Safety, dry runs, and debugging


+
+146 source files (117 main + 29 test) across 19 Java packages
+Approximately 27,900 lines of code (22,400 main + 5,500 test)
+12 built-in protocols
+208 unit tests
+269 configurable settings
+


+ds-sim source code on Codeberg

+vs-sim source code on Codeberg (original German version, 2008)

 

-RCM has a --dry mode: it logs what it would do without actually touching the file system. I use this when iterating on new configurations or refactoring existing ones. Combined with the built‑in logging and debug output, it's straightforward to see which resources were scheduled and in which order.

+Other related posts are:

 

-Because RCM is just Ruby, there's no separate agent protocol or daemon. The same process parses the DSL, resolves dependencies, and performs the actions. If something goes wrong, you can drop into the code, add a quick debug statement, and re‑run your configuration.

+2026-03-01 Loadbars 0.13.0 released

+2022-12-24 (Re)learning Java - My takeaways

+2022-03-06 The release of DTail 4.0.0

+2016-11-20 Object oriented programming with ANSI C

 

-RCM vs Puppet and other big tools


+E-Mail your comments to paul@nospam.buetow.org

 

-RCM does not try to compete with Puppet, Chef, or Ansible on scale. Those tools shine when you manage hundreds or thousands of machines, have multiple teams contributing modules, and need centralised orchestration, reporting, and role‑based access control. They also come with their own DSLs, servers/agents, certificate handling, and a long list of resource types and modules. Ansible may be more similar to RCM than the other tools, but it's still much more complex than RCM.

+Back to the main site

+

foo.zone feed

RCM: The Ruby Configuration Management DSL

RCM: The Ruby Configuration Management DSL

Distributed Systems Simulator - Part 3: Advanced Examples and Protocol API

Table of Contents

Why I built RCM

Additional Examples

Lamport and Vector Timestamps

How the DSL feels

Keywords and resources

Simulating Slow Connections

Files, directories, and templates

How Ruby's metaprogramming helps

Raft Consensus Failover

A bit more about method_missing

Protocol API

Class Hierarchy

Implementing a Custom Protocol

Available API Methods

Example: Reliable Multicast Implementation

Ruby metaprogramming: further reading

Project Statistics

Safety, dry runs, and debugging

RCM vs Puppet and other big tools