LCAGENT(1)

📦 version 0.1.0, in nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 LCAGENT 💖

okay bestie, gather round, because we're about to talk about lcagent — the Librecast multicast agent. yes, that's her whole name, that's the vibe, she's an icon and she's about to change your whole networking life fr fr 🦋

✨ SYNOPSIS ✨

lcagent [-dflv] [--bpslimit limit] [--expires seconds] [--overhead
packets] [command [argument ...]]

that's the whole summoning ritual, no cap 💅

🌸 DESCRIPTION 🌸

so. lcagent is the Librecast multicast agent. that's the whole sentence, that's the pitch, queen is booked and busy.

When she's out here in server mode, lcagent can be configured to listen on Librecast Channels (you know these, they're multicast groups 💫) and then just... execute programs in response to packet data that shows up on those Channels. main character energy, honestly.

and here's the gatekeeping part — packets MUST be accompanied by an authorized token and signed by the matching key, or they will be silently dropped. like, not even a "sorry bestie", just gone. the void. 🫥

Data gets encoded with RaptorQ using Librecast's liblcrq library, which gives you forward error correction for when packets get lost (and they will get lost, because the internet is a mess 😭).

Any data you receive in addition to the required token? it gets piped straight to stdin of the configured commands after they run. and yes, multiple commands can be executed sequentially — she's multitasking, she's thriving.

you can also use lcagent to send and receive data over multicast, and to pipe data between programs on one computer and as many receivers as the multicast network can possibly handle at the same time. yes really. as many as it can support. simultaneously. obsessed actually 🌈

🎀 OPTIONS 🎀

  • -d, --debug — turns on debug mode so she'll print extra debugging info. she's being vulnerable with you 🙈
  • --bpslimit rate[KMGT] — when sending, this caps the sending speed at rate. rate is a number in bits per second (bps) and you can slap a capital letter after it for SI units. eg. 100M limits sending to 100 megabits per second (Mbps). go off, throttle queen 👑
  • --expires seconds — for the sign command, this sets how long the token stays valid, in seconds. ticking clock energy ⏳
  • -f, --follow — in recv mode, do NOT stop after the first data object. keep blocking and keep receiving until something interrupts you. eg. ^C gets pressed, or the process receives SIGINT. she does not know how to quit 💀
  • -l, --loopback — enables multicast loopback when sending, which means packets can be received by the same host that sent them. by default, multicast packets are NOT received on the sending host. so this is the "talk to yourself" flag, and honestly, same.
  • --overhead packets — when sending, sets how many extra repair packets get sent to help recover lost packets with RaptorQ encoding. Default: 5 ✨
  • -v, --verbose — print more verbose output. she will yap. you will read. 💬

👑 COMMANDS 👑

💫 exec

lcagent exec [options] channel [data] [-]

the exec command executes the commands configured for channel locally, no network data required. like a little dress rehearsal before the real show 🎭

this is genuinely a great way to test the configured commands before you make them accessible on the network. taste test first, bestie 🍓

the nojoin configuration directive can be used to make sure a channel is not network-executable, by stopping lcagent from joining the associated Librecast channel. see lcagentrc(1).

🫶 help

lcagent help

prints some (possibly) helpful instructions for lcagent. "possibly" is doing a lot of heavy lifting in that sentence and I respect the honesty 🎀

🔑 key

lcagent key [options] add|del key

adds or deletes a key from the authorized_keys file.

packets that do not include a token signed by a key in the authorized_keys file are SILENTLY DROPPED. no warning, no note, no text back. just silence. it's giving ghosting 💀

📥 recv

lcagent recv [options] channel

block and wait for data to arrive on channel, where channel is a string that gets hashed to create a Librecast channel. hashing as a glow-up, we love to see it ✨

data received gets written to stdout. if you're expecting binary data, be sure to redirect stdout somewhere appropriate, or you're gonna have a bad time 😭

by default, once EOF is received from the sender, the program exits. you can change that behaviour by specifying the --follow option.

🔄 reload

lcagent reload [options]

reloads the lcagent configuration. sends a SIGHUP to the daemon process.

it has no effect unless lcagent has been started using the start command. service files should just send SIGHUP to the process directly. keep it simple, bestie 💅

📤 send

lcagent send [options] channel [payload] [-]

sends data to channel, where channel is a string that gets hashed to create a Librecast channel.

if payload is specified, that string gets sent as data to the channel. if no payload is specified, a NULL (empty) payload of zero bytes gets sent to the channel. sending absolutely nothing. iconic, honestly 🫥✨

a hyphen (-) at the end of the command means the payload should instead be read from stdin. classic move.

🖥️ server

lcagent [server] [options]

starting lcagent with no command starts her in server mode. the .lcagentrc file gets parsed, lcagent joins the configured channels, and then she waits for data — executing the configured commands when packets arrive on one of the configured channels, and writing any payload data to stdin of the command when executing it.

see lcagentrc(1) for the deets on the runtime control (configuration) file 📖

✍️ sign

lcagent sign [options] [--expires seconds] bearer_key channel

creates and signs a token for the given bearer_key and channel, then writes it to disk. the resulting token gets written to a file in the user's state directory, and the file pathname gets printed. if you copy the token to the state directory of the bearer, it'll be used when sending to channel.

a signed token means that packets sent by the bearer will be accepted by any receivers on channel that have the signer's key added to their authorized_keys file. tokens enable delegation of authority, which is super important for scaling. using pre-signed tokens lets a host, say, issue tokens for virtual machines it creates — without needing to add individual keys for every single machine to all receivers on the network. it's giving delegation, it's giving efficiency, it's giving please stop adding keys manually 😭👑

in the absence of a signed token, packets get sent with a self-signed token, which requires that all receivers have the sender's key installed in their authorized_keys file. no shortcuts, no vibes-based auth.

if the expires option is supplied, that's the validity in seconds of the generated token. a value of zero (0) means the token will never expire. by default, tokens do not expire. forever girlies 🕰️

🚀 start

lcagent start [options]

starts lcagent in server mode and forks it as a daemon.

NOT intended for use with daemon supervising programs. if you're running lcagent as a service, just start lcagent with no command and let the init system or daemon supervisor handle forking and pidfiles. if you are NOT running lcagent as a service and you want it to daemonize, then — and only then — use this command. read the room, bestie 🙈

🛑 stop

lcagent stop [options]

stops the lcagent daemon.

has no effect unless lcagent has been started using the start command. sends SIGINT to the running daemon process. bye bestie 👋

⭐ version

lcagent version

prints the version of lcagent and exits. short, sweet, factual, we love her 💖

🪞 whoami

lcagent whoami [options]

prints the active key to stdout and exits. you can add this key to the authorized_keys file of another host with:

lcagent key add key

identity crisis? no. identity clarity. ✨

💀 EXIT STATUS 💀

lcagent exits with status 0 (EXIT_SUCCESS) if the command was successful, or 1 (EXIT_FAILURE) if an error occurred. two moods, and only two moods. no in-between, no situationship 🎭

🌈 ENVIRONMENT 🌈

  • HOME — set to the path of the user's home directory. that's it, that's the whole environment section, and honestly she's low-maintenance 🏠

📁 FILES 📁

  • ~/.lcagentrc this is the runtime control file for lcagent. this is where global settings, channels and commands are defined that affect the runtime operation of the program. see lcagentrc(5) for more information. the brain, the blueprint, the moment 🧠✨
  • ~/.local/state/lcagent/authorized_keys this file contains the keys which are authorized to issue tokens that will be accepted by the program when receiving data. one key is stored per line. it can be managed with the lcagent key command. one key, one line, no exceptions, we're not animals 🔑📏

🔐 SECURITY 🔐

authenticity of data received is established by checking that each packet received contains a token signed by an authority whose public key is installed in the authorized_keys file. if the token is valid, then the packet must be signed by the bearer key contained in the token. two checks, both mandatory, both non-negotiable. vibe check, passed or dropped 💅

cryptographic signatures use the Ed25519ph algorithm provided by the libsodium library.

data can be encrypted using the seed configuration directive in .lcagentrc. see lcagentrc(5).

the symmetric encryption key is generated from seed using BLAKE2b.

symmetric encryption uses the XSalsa20 stream cipher from libsodium, using a Poly1305 MAC for authentication and a random nonce. cryptography stacking like it's a fit check 🧚

if an encryption seed is used, the permissions for the rcfile must NOT be world readable, or lcagent will refuse to run and print an error. she will simply not. do not test her. 🔥

💜 AUTHOR 💜

lcagent was written by Brett Sheffield <bacs@librecast.net> and released under the terms of the GPL-2 or (at your option) GPL-3.

https://librecast.net/lcagent.html

give her a follow, she's earned it 🫶

🐛 BUGS 🐛

if you find one, email bugs@librecast.net or raise an issue in our online bug tracker at: https://bugs.librecast.net/lcagent

not me asking you to snitch on bugs, but like, do it. it's for the girls 💖

🔗 SEE ALSO 🔗

lcagentrc(1), lcsync(1), librecast(7)

and that's the whole page bestie!! this edition of the Librecast Commands Manual is brought to you by the Librecast crew, dated 2025-05-16, and she ate every single time ✨👑💅 no cap, periodt, go run her 🦋

📦 where this page comes from