This is a simple guide on how to use this program. The program consists in a server-client application, where the client sends "command names" to the server, the server runs the associated actual commands, and then it sends back the commands results. The protocol used is MQTT.
A complete simple example can be found in testMosquitto/ folder.
The server requires a configuration file.
Its definition can be found in src/jsonTypes/JsonServerConfig.ts, and a simple
example can be found in testMosquitto/serverConfig.json:
{
"version": 1,
"topic": "open-kappa/mqtt-runner/test",
"broker": {
"password": "",
"port": 1883,
"protocol": "mqtt",
"server": "test.mosquitto.org",
"username": ""
// "clientId"?: string;
},
"commands": [
{
"command": "echo 'hi!'",
"name": "hello",
"passwords": ["secret"]
}
],
"qos": 0
}
Run the server by passing as first argment the configuration file:
node mqttRunnerServer testMosquitto/serverConfig.json
This mode of running the server is fine for a quick test. A production
deployment hsould run the server as a systemd process. Please refer to the
dedicated section for documentation.
Also the client needs a configuration file.
Its definition can be found in src/jsonTypes/JsonClientConfig.ts, and a simple
example can be found in testMosquitto/clientConfig.json:
{
"version": 1,
"replyTo": "open-kappa/mqtt-runner/test-replyTo",
"broker": {
"password": "",
"port": 1883,
"protocol": "mqtt",
"server": "test.mosquitto.org",
"username": ""
// "clientId"?: string;
},
"topic": "open-kappa/mqtt-runner/test",
"qos": 0,
"password": "secret",
"timeoutMs": 5000
}
Run the client by passing as first argument its configuration and as second argument the name of the command to execute:
node mqttRunnerClient testMosquitto/clientConfig.json hello
The client will send the command and it will print the command response on the console.
This section briefly describes how to setup a systemd daemon for the server.
First of all, a node.js installation is required. there are various
possibilities, so please use the one you prefer. We usually prefer installation
via nvm.
In the folder systemd/ you can find the mqtt-runner.service file, which is a
basic example of service file:
[Unit]
Description=Autostart of Mqtt Runner
[Service]
User=root
Type=forking
ExecStart=/root/mqtt-runner.sh
#ExecStop=
TimeoutSec=30
Restart=on-failure
RestartSec=30
StartLimitInterval=350
StartLimitBurst=10
[Install]
WantedBy=multi-user.target
Copy it in /etc/systemd/system, and then change it to point to the
mqtt-runner.sh script.
This script is also located in systemd/ folder.
Copy it wherever you like, and adapt it: as minimum, set correctly the
MQTT_RUNNER variable.
The script accepts as first optional parameter load_nvm_node, to load the
nvm variables, which is required if node.js has been installed via nvm.
All the other parameters will be passed to the server.
@open-kappa/mqtt-runner - A simple command runner
Copyright 2022 Francesco Stefanni
https://bitbucket.org/open-kappa/mqtt-runner
@open-kappa/mqtt-runner is distributed under the MIT license. Please see the license section to get a copy of the full license.
Copyright (c) 2022 Francesco Stefanni
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The following individuals and institutions are among the contributors:
This library has been sponsored by the following patreons:
Generated using TypeDoc
MOTIVATIONS
This is a simple client-server application, which allows to run pre-defined commands on the server.
It has been developed to run remote commands, as simple deployment pipelines for CI/CD:
mqtt-runnercan only run predefined (and hence hopefully safe) commands.