isochron-orchestrate(1)

💖 isochron-orchestrate — the manual page, bestie edition 💖

okay so you found isochron-orchestrate(1), which lives in the ISOCHRON section of the manual, and honestly? it's giving conductor energy. not the train kind. the "i tell everyone when to go" kind. let's get into it 🎀

---

✨ NAME ✨

isochron-orchestrate — Coordinate isochron daemons

like. that's the whole job description. coordinating the girlies. 💅

---

✨ SYNOPSIS ✨

isochron orchestrate [OPTIONS]

short. sweet. iconic. no notes. 🫶

---

✨ DESCRIPTION ✨

so here's the vibe: this command opens up an orchestration file that's basically a little roster of daemons — how to reach each one, their names, their roles, and the parameters for the test. 📋✨

then it connects to all of them, tells each one what its parameters are, and coordinates them so that nobody starts sending traffic until their synchronization offset drops below the required threshold. like a group chat where nobody sends a message until everyone's ready. we love a synchronized moment. 🦋

once the test is done? the orchestrator goes around collecting the packet logs from every sender and its associated receiver, and saves them onto the local filesystem. it's basically the friend who takes the group photos and actually sends them to everyone afterward. 💖

---

✨ OPTIONS ✨

• -h, --help — prints the short help message and exits. the "hey bestie what do i do" button. 🌸
• -F, --input-file <PATH> — specify the path to the input orchestration file. yes it's capital F. yes that's a choice. we respect it. 💜

---

🌈 ORCHESTRATION FILE FORMAT 🌈

the orchestration file is INI-style, which means:

• it supports multi-line statements ✨
• comments are delineated by the # character 💬

every section in there denotes an orchestration node, and the lines that follow it are in a "key = value" format describing the parameters for that node. cute, structured, organized. main character energy fr fr. 👑

here's the keys you can use:

• host — denotes the IP address through which the isochron daemon can be reached by the orchestrator. 📍
• port — denotes the TCP port through which the isochron daemon can be reached by the orchestrator. 🚪
• exec — denotes the command to be executed by the isochron daemon. and this is where it gets juicy, so buckle up:
  • the syntax is identical to what would be specified as command line arguments to isochron-send.
  • the expected behavior of a daemon in the role of a sender is also identical to that of a dedicated sender, with some exceptions. (the exceptions! they're coming! don't scroll!)
  • the --output-file is interpreted by the orchestrator, not by the daemon — which means files are saved on the orchestrator's filesystem, not the daemon's. plot twist. 😭
  • communication through the management socket does not take place between an orchestrated sender and its receiver. nope. not happening.
  • instead, the orchestrator deduces the address and port of the receiver through the --client and --stats-port arguments of the sender, and connects by itself to the receiver. it's the middleman now. 💅
  • an orchestrated sender does not monitor sync status by itself and does not decide when to start sending test packets. instead, those are controlled by the orchestrator. the sender is just there to look pretty and do what it's told. 💖

---

🌸 EXAMPLES 🌸

so picture this: you wanna orchestrate two senders running on hosts A (10.0.0.1) and B (10.0.0.2), both sending towards two receivers that both live on host C (10.0.0.3), all controlled from a management node D. the whole point? creating packet collisions and measuring the resulting latency. chaos, but make it scientific. 🔥

the commands on nodes A and B are:

ptp4l -i eth0 -2 -P --step_threshold 0.00002 &
phc2sys -a -rr --step_threshold 0.00002 &
isochron daemon

the commands on node C are:

ptp4l -i eth0 -2 -P --step_threshold 0.00002 &
phc2sys -a -rr --step_threshold 0.00002 &
isochron rcv --interface eth0 --stats-port 5000 --etype 0xdead &
isochron rcv --interface eth0 --stats-port 5001 --etype 0xdeaf &

the commands on node D are (and listen — the double backslashes are there to prevent the shell from interpreting them when creating the heredoc, so the resulting file will have simple backslashes. trust the process 🙈):

cat <<- EOF > orchestration.txt
[A]
host = 10.0.0.1
port = 5000
exec = isochron send \\
        --client 10.0.0.3 \\
        --stats-port 5000 \\
        --interface eth0 \\
        --num-frames 10 \\
        --base-time 0.000000000 \\
        --cycle-time 0.01 \\
        --frame-size 1500 \\
        --sync-threshold 100 \\
        --cpu-mask 0x1 \\
        --sched-fifo \\
        --sched-priority 98 \\
        --etype 0xdead \\
        --output-file isochron-host-a.dat

[B]
host = 10.0.0.2
port = 5000
exec = isochron send \\
        --client 10.0.0.3 \\
        --stats-port 5001 \\
        --interface eth0 \\
        --num-frames 10 \\
        --base-time 0.000000100 \\
        --cycle-time 0.01 \\
        --frame-size 1500 \\
        --sync-threshold 100 \\
        --cpu-mask 0x1 \\
        --sched-fifo \\
        --sched-priority 98 \\
        --etype 0xdeaf \\
        --output-file isochron-host-b.dat
EOF

isochron orchestrate --input-file orchestration.txt
isochron report --summary --input-file isochron-host-a.dat
isochron report --summary --input-file isochron-host-b.dat

and that's the whole recipe. slay. 💅✨

---

💜 AUTHOR 💜

isochron was written by Vladimir Oltean vladimir.oltean@nxp.com

we stan. 👑

---

🌟 SEE ALSO 🌟

isochron(8) isochron-send(8) isochron-daemon(8)

the whole friend group. go say hi. 🫶

---

🎀 COMMENTS 🎀

This man page was written using pandoc by the same author. (pandoc girlies, we see you. ✨)

---

okay that's the page, bestie. isochron-orchestrate(1) from the ISOCHRON manual, brought to you with love, packet collisions, and an unreasonable amount of backslashes. byeee 💖🦋🌈