Quick start: your first replicated table in 15 minutes
You will copy a small table from one server (the high side) to another (the low side) through the one-way link, change it, and watch the change arrive. It needs no database server: it uses SQLite files, so you can try the whole product before involving a DBA. Real databases (SQL Server, PostgreSQL, Oracle, MySQL, ...) use the same two programs with different settings: see "Next steps" at the end.
You need: two 64-bit (x86-64) Linux servers that can reach each other over UDP, administrator access on both, the package datadiode_<version>_amd64.deb and your license file diode-license.dglic. Both files are on the Software page of your DiodeGuard account. The commands below are for Ubuntu or Debian (22.04 or newer) with sudo; if your servers are different (you are already root, another Linux, another firewall, no internet, no systemd), read "If your setup is different" before you start: it has the matching commands. In the commands below, HIGH_IP is the high-side server's address and LOW_IP the low-side server's.
This is a software one-way link: the sender never reads and the receiver never answers. For physical one-wayness in production, put the link behind a hardware diode or a transmit-only fibre (docs/THREAT_MODEL.md). For this tutorial an ordinary network is fine.
1. Install on both servers
sudo apt install ./datadiode_*_amd64.deb # on BOTH servers
sudo apt install sqlite3 # for this tutorial only (to create and look at the sample data)
Then install your license file, also on both servers (one license covers all the servers of your organization):
sudo diode-license install diode-license.dglic # on BOTH servers
diode-license status # prints "license OK ... valid until ..."
The programs that move data (sender, receiver, applier, protocol gateways) refuse to start without a valid license and stop when it ends; the monitoring tools (diode-status, the console) always work. In the last two weeks they keep running and print a warning in the log. To renew, download the new file from your account and run the same diode-license install command: running programs pick it up within ten minutes, no restart is needed.
2. Make the shared key (high side) and copy it to the low side
The key makes the link refuse anything that was not sent by your sender.
# on the HIGH side
sudo install -d -o diode -g diode -m 0750 /var/lib/diode/quick
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' | sudo tee /etc/diode/diode.key >/dev/null
sudo chown root:diode /etc/diode/diode.key && sudo chmod 640 /etc/diode/diode.key
sudo cat /etc/diode/diode.key # copy this ONE line to the low side over a channel you trust (ssh, a password manager, ...)
# on the LOW side: paste the same line
sudo install -d -o diode -g diode -m 0750 /var/lib/diode/quick
echo 'PASTE-THE-KEY-LINE-HERE' | sudo tee /etc/diode/diode.key >/dev/null
sudo chown root:diode /etc/diode/diode.key && sudo chmod 640 /etc/diode/diode.key
3. Low side: receive and apply
Two small files in /etc/diode/conf.d/. Naming matters: a service called diode-recv@quick reads quick.conf, and diode-sql-apply@quick reads quick-apply.conf (the -apply / -source suffix is added for you).
sudo tee /etc/diode/conf.d/quick.conf >/dev/null <<EOF
bind = "LOW_IP:9000"
out = "/var/lib/diode/quick/rx"
idle-secs = 30
rcvbuf-mb = 256
key-file = "/etc/diode/diode.key"
EOF
sudo tee /etc/diode/conf.d/quick-apply.conf >/dev/null <<EOF
in = "/var/lib/diode/quick/rx/delivered"
state-dir = "/var/lib/diode/quick/apply"
stream = "quick"
sink = "sqlite"
out = "/var/lib/diode/quick/replica.db"
EOF
sudo chown root:diode /etc/diode/conf.d/quick*.conf && sudo chmod 640 /etc/diode/conf.d/quick*.conf
# let ONLY the high side's address reach the UDP port (if you use ufw; otherwise use your firewall)
sudo ufw allow from HIGH_IP to any port 9000 proto udp
sudo systemctl enable --now diode-recv@quick diode-sql-apply@quick
4. High side: some data, and the sender
sudo -u diode sqlite3 /var/lib/diode/quick/plant.db "
pragma journal_mode=wal; -- recommended for a source database: the source reads it while your application writes
create table readings(id integer primary key, point text not null, value real, at text);
insert into readings values (1,'pump-1',41.5,'2026-11-16T09:00:00Z'),(2,'pump-2',39.8,'2026-11-16T09:00:00Z'),(3,'tank-1',72.0,'2026-11-16T09:00:00Z');"
sudo tee /etc/diode/conf.d/quick-source.conf >/dev/null <<EOF
driver = "sqlite"
sqlite-file = "/var/lib/diode/quick/plant.db"
tables = ["readings"]
dest = "LOW_IP:9000"
state-dir = "/var/lib/diode/quick/source"
stream = "quick"
key-file = "/etc/diode/diode.key"
rate = 100
repeat = 2
poll-ms = 1000
heartbeat-secs = 30 # a small "I am alive" message when nothing changes, so a quiet table is not mistaken for a fault
auto-snapshot-on-gap = true
EOF
sudo chown root:diode /etc/diode/conf.d/quick-source.conf && sudo chmod 640 /etc/diode/conf.d/quick-source.conf
sudo diode-sql-source --config /etc/diode/conf.d/quick-source.conf --check # prints "config ok" (changes nothing)
sudo systemctl enable --now diode-sql-source@quick
(Every table needs a primary key: that is how a changed row is recognised.)
5. Watch it work
On the low side the first copy arrives within a few seconds:
sqlite3 /var/lib/diode/quick/replica.db "select * from readings"
Now change the data on the high side and look again on the low side:
sudo -u diode sqlite3 /var/lib/diode/quick/plant.db "
insert into readings values (4,'valve-7',12.25,'2026-11-16T09:05:00Z');
update readings set value=43.1 where id=1;
delete from readings where id=2;"
About a second later the low side shows the new row, the new value and no row 2. Check the health of every part (OK / WARNING / CRITICAL):
diode-status --source /var/lib/diode/quick/source # high side
diode-status --rx /var/lib/diode/quick/rx --apply /var/lib/diode/quick/apply # low side
If your setup is different
We tested these steps on Ubuntu 24.04 with sudo, ufw and systemd. The programs are static binaries with no dependencies, so the same steps work elsewhere; below is what to change. Anything marked not tested by us follows the standard tools of that system and has not been run by us on it. Tell us if it did not work: [email protected].
You are logged in as root, or you have no sudo. Leave sudo out of every command. Where a command says sudo -u diode ..., use runuser -u diode -- ... instead (for example runuser -u diode -- sqlite3 /var/lib/diode/quick/plant.db "select 1"), or su -s /bin/sh diode -c '...'. If your company uses doas instead of sudo, replace sudo with doas. Where a line pipes into sudo tee FILE, run tee FILE as root.
Debian or Ubuntu without apt access, or you prefer dpkg. sudo dpkg -i datadiode_*_amd64.deb installs the same package. The package has no dependencies, so it also installs on servers with no internet: copy the .deb and the license file over (scp, a USB stick, your software distribution tool).
**Red Hat, Rocky, Alma, Fedora, SUSE, Amazon Linux or another Linux (not tested by us).** There is no .rpm, but the .deb is only an archive. Unpack it, then do by hand what the package does:
ar x datadiode_*_amd64.deb data.tar.xz # needs binutils (ar) and xz
tar -C / -xf data.tar.xz # puts the programs in /usr/bin and the service files in /lib/systemd/system
useradd --system --home-dir /var/lib/diode --shell /sbin/nologin diode
install -d -m 0750 -o root -g diode /etc/diode /etc/diode/conf.d
install -d -m 0750 -o diode -g diode /var/lib/diode
systemctl daemon-reload
sysctl -p /etc/sysctl.d/90-diode.conf # larger network buffers, recommended
Use your own package tool for sqlite3 (dnf install sqlite, zypper install sqlite3). With SELinux enforcing, if a service will not start with permission denied, run restorecon -Rv /usr/bin/diode-* and look at ausearch -m avc -ts recent.
No sqlite3 command, and you cannot install it. Python 3 can do the same. Create the sample table on the high side (use runuser -u diode -- python3 - if you are root, or sudo -u diode python3 -):
sudo -u diode python3 - <<'PY'
import sqlite3
c = sqlite3.connect("/var/lib/diode/quick/plant.db")
c.executescript("""
pragma journal_mode=wal;
create table readings(id integer primary key, point text not null, value real, at text);
insert into readings values (1,'pump-1',41.5,'2026-11-16T09:00:00Z'),(2,'pump-2',39.8,'2026-11-16T09:00:00Z'),(3,'tank-1',72.0,'2026-11-16T09:00:00Z');
""")
c.commit()
PY
To look at the result on the low side, or to change the data in step 5, use the same pattern: python3 -c 'import sqlite3; print(sqlite3.connect("/var/lib/diode/quick/replica.db").execute("select * from readings").fetchall())' and, on the high side, c.executescript("insert into readings values (4,'valve-7',12.25,'2026-11-16T09:05:00Z'); update readings set value=43.1 where id=1; delete from readings where id=2;") followed by c.commit().
A firewall other than ufw. The goal is the same: let only the high side's address send UDP to port 9000 on the low side. Use the line that matches your system instead of the ufw line in step 3:
# firewalld (Red Hat family, SUSE):
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="HIGH_IP" port port="9000" protocol="udp" accept' && firewall-cmd --reload
# nftables (add it to the table and chain you already use; names differ):
nft add rule inet filter input ip saddr HIGH_IP udp dport 9000 accept
# iptables:
iptables -A INPUT -p udp -s HIGH_IP --dport 9000 -j ACCEPT
In the cloud (AWS, Azure, Google, Contabo, ...) also open the same rule in the security group or cloud firewall: inbound UDP 9000 from the high side's address, and allow outbound UDP from the high side. If nothing arrives and the firewall on the server looks right, this is the usual cause.
No systemd (containers, Alpine, WSL1, runit, supervisord). The service files are only a convenience. Run the same programs in the foreground with the same files, under your own supervisor, as the diode user:
runuser -u diode -- diode-recv --config /etc/diode/conf.d/quick.conf # low side
runuser -u diode -- diode-sql-apply --config /etc/diode/conf.d/quick-apply.conf # low side
runuser -u diode -- diode-sql-source --config /etc/diode/conf.d/quick-source.conf # high side
Set the supervisor to restart them if they stop, except after exit code 78 (no valid license: restarting cannot fix it). In Docker, mount /etc/diode and /var/lib/diode as volumes and use network_mode: host or publish the UDP port (-p LOW_IP:9000:9000/udp).
Different addresses, ports or folders. bind (low side) is an address of the low-side server (0.0.0.0:9000 means every address); dest (high side) is that address as seen from the high side, so behind NAT use the translated address. To use another UDP port, change it in bind, in dest and in the firewall rule. All paths are only defaults: change them in the .conf files and, if you use the service files, in ReadWritePaths= (systemctl edit diode-recv@quick). We have tested IPv4 only.
Other hardware. The package is for 64-bit x86 (amd64). ARM servers (Raspberry Pi, AWS Graviton) and Windows are not supported yet: ask us if you need them.
If something does not work
| You see | Likely cause |
|---|---|
A program exits at once with code 78, or systemctl status shows exited, status=78 | No valid license: run diode-license status; install or renew the file with sudo diode-license install diode-license.dglic. |
systemctl status says cannot read config ... | The service name does not match the file name (see the naming note in step 3). |
| Nothing arrives on the low side | The firewall on the low side, or dest / bind do not use the same address and port. diode-status on the low side shows no packet received. |
diode-status says metrics are N s old - diode-recv is not running | The receiver is stopped: journalctl -u diode-recv@quick -n 20. |
Files appear in /var/lib/diode/quick/rx/quarantine | The key differs between the two sides, or the network lost more packets than the error correction can repair (docs/PRODUCT.md section 3, lossy networks). Nothing wrong is ever delivered. |
| snapshot needed / the applier reports a gap | Expected after an outage: the source sends a fresh copy by itself (auto-snapshot-on-gap). |
Next steps
- Your real database: SQL Server with Change Data Capture (docs/RUNBOOK.md 3b), PostgreSQL as the destination (3c), or any other database through ODBC (3h).
- Be told when something breaks:
diode-notifysends syslog / webhook / email alerts (docs/RUNBOOK.md 3j). - See it in a browser: the management console with live status, configuration editing, audit trail and single sign-on (docs/RUNBOOK.md 3g).
- Lock it down for production: run the self-check (
diode-console selfcheck), restrict the UDP port to the sender, and read docs/THREAT_MODEL.md.
Verified on two cloud servers (Ubuntu 24.04) on 2026-11-15, following these steps in this order with the packaged build: the table, then an insert, an update and a delete, arrived in about one second, and again after a package upgrade. Walking through it found and fixed one real bug (the source service insisted on a password file that SQLite does not use). The sample table is tiny: for throughput on your hardware see docs/PRODUCT.md section 3.