lcagent - the Librecast multicast agent
lcagent [-dflv] [--bpslimit limit] [--expires seconds] [--overhead packets] [command [argument ...]]
lcagent is the Librecast multicast agent.
In server mode lcagent can be configured to listen on Librecast Channels (multicast groups) and execute programs in response to packet data received on those Channels.
Packets must be accompanied by an authorized token and signed by the matching key or they will be silently dropped.
Data is encoded with RaptorQ using Librecast's liblcrq library to provide forward error correction in the event of packet loss.
Any data received in addition to the required token will be piped to stdin of the configured commands after they are executed. Multiple commands can be executed sequentially.
lcagent can be used 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 support simultaneously.
Enable debug mode to print additional debugging information.
When sending, this option limits the sending speed to rate. Rate is a number in bits per second (bps) and can be followed by a capital letter representing SI units. eg. 100M limits the sending rate to 100 megabits per second (Mbps).
For the sign command, this sets the validity of the token in seconds.
In recv mode, do not stop after first data object received. Keep blocking and receiving data until interrupted. eg. ^C is pressed or SIGINT is received by the process.
Enable multicast loopback when sending. This will allow packets to be received by the same host that sent them. By default multicast packets are not received on the sending host.
When sending, this option sets the number of additional repair packets sent to aid with recovery of lost packets with RaptorQ encoding. Default: 5
Print more verbose output.
lcagent exec [options] channel [data] [-]
The exec command executes the commands configured for channel locally, without requiring data to be received over the network.
This is a good way to test the configured commands that will be executed before making them accessible on the network.
The nojoin configuration directive can be used to ensure that a channel is not network-executable, by preventing lcagent from joining the associated Librecast channel. See lcagentrc(1).
lcagent help
Print some (possibly) helpful instructions for lcagent.
lcagent key [options] add|del key
Add or delete 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.
lcagent recv [options] channel
Block and wait for data to be received on channel, where channel is a string that will be hashed to create a Librecast channel.
Data received will be written to stdout. If expecting binary data, be sure to redirect stdout somewhere appropriate.
By default, once EOF is received from the sender, the program will exit. This behaviour can be changed by specifying the --follow option.
lcagent reload [options]
Reload the lcagent configuration. Sends a SIGHUP to the daemon process. Has no effect unless lcagent has been started using the start command. Service files should simply send SIGHUP to the process.
lcagent send [options] channel [payload] [-]
Send data to channel, where channel is a string that will be hashed to create a Librecast channel.
If payload is specified, this string will be sent as data to the channel. If no payload is specified, an NULL (empty) payload of zero bytes will be sent to the channel.
A hyphen (-) at the end of the command indicates that the payload should instead be read from stdin.
lcagent [server] [options]
Starting lcagent with no command starts it in server mode. The .lcagentrc file will be parsed and lcagent will join the configured channels and wait for data, executing the configured commands when packets are received on one of the configured channels and writing any payload data to stdin of the command when executing it.
See lcagentrc(1) for details of the runtime control (configuration) file.
lcagent sign [options] [--expires seconds] bearer_key channel
Create and sign a token for the given bearer_key and channel and write to disk. The resulting token will be written to a file in the user's state directory, and the file pathname will be printed. If the token is copied to the state directory of the bearer it will be used when sending to channel.
A signed token means that packets sent by the bearer will be accepted by any receivers on channel which have the signer's key added to their authorized_keys file. Tokens enable delegation of authority, which is important for scaling. Using pre-signed tokens allows, say, a host to issue tokens for virtual machines it creates without the need to add individual keys for every machine to all receivers on the network.
In the absence of a signed token, packets will be sent with a self-signed token, requiring that all receivers have the sender's key installed in their authorized_keys file.
If the expires option is supplied, this will be the validity in seconds of the generated token. A value of zero (0) means that the token will never expire. By default tokens do not expire.
lcagent start [options]
Start lcagent in server mode and fork it as a daemon.
Not intended for use with daemon supervising programs. If you are 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 want it to daemonize, use this command.
lcagent stop [options]
Stop the lcagent daemon. Has no effect unless lcagent has been started using the start command. Sends SIGINT to the running daemon process.
lcagent version
Print the version of lcagent and exit.
lcagent whoami [options]
Print the active key to stdout and exit. This key can be added to the authorized_keys file of another host with:
lcagent key add key
lcagent exits with status 0 (EXIT_SUCCESS) if the command was successful, or 1 (EXIT_FAILURE) if an error occured.
Set to the path of the user’s home directory.
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.
This file contains the keys which are authorized to issue tokens which will be accepted by the program when receiving data. One key is stored per line. It can be managed with the lcagent key command.
Authenticity of data received is established by checking that each packet received contains a token signed by an authority with their public key installed in the authorized_keys file. If the token is valid, the packet must be signed by the bearer key contained in the token.
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 random nonce.
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.
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
If you find one, email bugs@librecast.net or raise an issue in our online bug tracker at: https://bugs.librecast.net/lcagent
lcagentrc(1), lcsync(1), librecast(7)