This commit is contained in:
Your Name
254
runner/README.md
254
runner/README.md
@ -7,207 +7,77 @@ use:
|
||||
|
||||
BASE64COMMAND is Base64 encoded json. The json format is as described below. The exit code is that of the command run, or -1 if the command couldn't be run.
|
||||
|
||||
The c++ library used, which is contained in this codebase, has two simple functions:
|
||||
bool runner(nlohmann::json run_json); // no output capture
|
||||
bool runner(nlohmann::json run_json, std::string & output); // with output capture.
|
||||
|
||||
## JSON Specification
|
||||
|
||||
```json
|
||||
The c++ library used, which is contained in this codebase, has one simple function:
|
||||
|
||||
typedef struct sSSHInfo {
|
||||
std::string host;
|
||||
std::string user;
|
||||
std::string port;
|
||||
} sSSHInfo;
|
||||
|
||||
|
||||
static int execute_cmd(
|
||||
const std::string& command,
|
||||
const std::vector<std::string>& args,
|
||||
const std::string& working_dir,
|
||||
const std::map<std::string, std::string>& env,
|
||||
bool silent,
|
||||
bool interactive,
|
||||
sSSHInfo * sshinfo = nullptr,
|
||||
std::string* output = nullptr,
|
||||
);
|
||||
|
||||
|
||||
If SSH information is provided, the command will be executed on the remote server. Otherwise on the local machine.
|
||||
|
||||
If output is provided, the output of the command is captured.
|
||||
|
||||
If interactive is true, then an interactive session is created - e.g. for running nano to remotely edit a file, or sshing into a docker container from the remote host.
|
||||
|
||||
If silent is true, then all output is suppressed.
|
||||
|
||||
Before the command is run, the current directory is changed to working_dir on the remote host (or local host if no ssh info provided).
|
||||
|
||||
|
||||
## BASE64COMMAND JSON Format
|
||||
|
||||
The BASE64COMMAND argument should be a Base64-encoded JSON object with the following fields:
|
||||
|
||||
- `command` (string, required): The command to execute (e.g., "ls").
|
||||
- `args` (array of strings, optional): Arguments to pass to the command (e.g., ["-l", "/tmp"]).
|
||||
- `working_dir` (string, optional): Directory to change to before running the command.
|
||||
- `env` (object, optional): Environment variables to set (e.g., {"FOO": "bar"}).
|
||||
- `silent` (boolean, optional): If true, suppress all output. Default: false.
|
||||
- `interactive` (boolean, optional): If true, run the command interactively. Default: false.
|
||||
- `sshinfo` (object, optional): If present, run the command on a remote host (not implemented in demo):
|
||||
- `host` (string): Hostname or IP.
|
||||
- `user` (string): Username.
|
||||
- `port` (string): SSH port.
|
||||
|
||||
### Example JSON
|
||||
|
||||
```
|
||||
{
|
||||
"ssh": { // Optional: SSH connection information
|
||||
"host": "hostname", // Remote host to connect to
|
||||
"port": 22, // Port number (default: 22)
|
||||
"user": "username", // Username for SSH connection
|
||||
"key": "path/to/key" // Path to SSH key file or "auto" to use current user's key
|
||||
},
|
||||
"working_directory": "/path", // Optional: Directory to change to before executing the command
|
||||
"env": { // Optional: Environment variables
|
||||
"VAR1": "value1",
|
||||
"VAR2": "value2"
|
||||
},
|
||||
"command": "command_name", // Required: Command to execute
|
||||
"args": ["arg1", "arg2"], // Optional: Command arguments
|
||||
"options": { // Optional: Execution options
|
||||
"silent": false, // Suppress all terminal output (default: false)
|
||||
"interactive": false // Hook up TTY for interactive sessions (default: false)
|
||||
}
|
||||
"command": "ls",
|
||||
"args": ["-l", "/tmp"],
|
||||
"working_dir": "/",
|
||||
"env": {"FOO": "bar"},
|
||||
"silent": false,
|
||||
"interactive": false
|
||||
}
|
||||
```
|
||||
|
||||
If SSH information is provided, the command will be executed on the remote server.
|
||||
To use, encode the JSON as a single line, then base64 encode it:
|
||||
|
||||
## Build Instructions
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- CMake 3.10 or newer
|
||||
- C++17 compatible compiler
|
||||
- libssh development libraries
|
||||
- jq (for the helper scripts)
|
||||
|
||||
#### Installing Dependencies
|
||||
|
||||
##### Quick Installation (Ubuntu/Debian)
|
||||
|
||||
For Ubuntu/Debian systems, you can use the provided installation script:
|
||||
|
||||
```bash
|
||||
sudo ./install_deps.sh
|
||||
```
|
||||
echo -n '{"command":"ls","args":["-l","/tmp"],"working_dir":"/","env":{"FOO":"bar"},"silent":false,"interactive":false}' | base64
|
||||
```
|
||||
|
||||
This will install all required dependencies (cmake, g++, libssh-dev, jq).
|
||||
Then run:
|
||||
|
||||
##### Manual Installation
|
||||
|
||||
###### Ubuntu/Debian
|
||||
|
||||
```bash
|
||||
sudo apt-get install cmake g++ libssh-dev jq
|
||||
```
|
||||
./build/runner <BASE64COMMAND>
|
||||
```
|
||||
|
||||
###### CentOS/RHEL
|
||||
|
||||
```bash
|
||||
sudo yum install cmake gcc-c++ libssh-devel jq
|
||||
```
|
||||
|
||||
###### macOS
|
||||
|
||||
```bash
|
||||
brew install cmake libssh jq
|
||||
```
|
||||
|
||||
###### Windows
|
||||
|
||||
Using vcpkg:
|
||||
|
||||
```bash
|
||||
vcpkg install libssh nlohmann-json
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
To build the project, you can use the provided build script:
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
mkdir -p build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
```
|
||||
|
||||
The executable will be created at `build/runner`.
|
||||
|
||||
### Testing
|
||||
|
||||
A simple test script is included to verify the functionality:
|
||||
|
||||
```bash
|
||||
./test.sh
|
||||
```
|
||||
|
||||
This will run basic tests for command execution, environment variables, silent mode, and return codes.
|
||||
|
||||
If you have SSH configured on your local machine and want to test the SSH functionality:
|
||||
|
||||
```bash
|
||||
ENABLE_SSH_TEST=1 ./test.sh
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If CMake cannot find libssh, you can:
|
||||
|
||||
1. Run the libssh finder script to locate your installation:
|
||||
```bash
|
||||
./examples/find_libssh.sh
|
||||
```
|
||||
|
||||
2. Specify its location manually:
|
||||
```bash
|
||||
cmake -DCMAKE_PREFIX_PATH=/path/to/libssh/installation ..
|
||||
```
|
||||
|
||||
3. Or set the libssh_DIR environment variable:
|
||||
```bash
|
||||
export libssh_DIR=/path/to/libssh/installation
|
||||
cmake ..
|
||||
```
|
||||
|
||||
4. If the problem persists, specify the library and include paths directly:
|
||||
```bash
|
||||
cmake -DLIBSSH_LIBRARY=/path/to/libssh.so -DLIBSSH_INCLUDE_DIR=/path/to/include ..
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Running a local command
|
||||
|
||||
```bash
|
||||
# Create a JSON configuration for the 'ls -l' command
|
||||
JSON='{"command":"ls","args":["-l"]}'
|
||||
|
||||
# Base64 encode the JSON
|
||||
BASE64=$(echo -n "$JSON" | base64)
|
||||
|
||||
# Run the command
|
||||
./build/runner $BASE64
|
||||
```
|
||||
|
||||
### Running a command with environment variables
|
||||
|
||||
```bash
|
||||
# Create a JSON configuration with environment variables
|
||||
JSON='{"command":"echo","args":["$GREETING"],"env":{"GREETING":"Hello, World!"}}'
|
||||
|
||||
# Base64 encode the JSON
|
||||
BASE64=$(echo -n "$JSON" | base64)
|
||||
|
||||
# Run the command
|
||||
./build/runner $BASE64
|
||||
```
|
||||
|
||||
### Running a command on a remote server via SSH
|
||||
|
||||
```bash
|
||||
# Create a JSON configuration for a remote command
|
||||
JSON='{"ssh":{"host":"example.com","user":"username","key":"auto"},"command":"hostname"}'
|
||||
|
||||
# Base64 encode the JSON
|
||||
BASE64=$(echo -n "$JSON" | base64)
|
||||
|
||||
# Run the command
|
||||
./build/runner $BASE64
|
||||
```
|
||||
|
||||
### Running an interactive command
|
||||
|
||||
```bash
|
||||
# Create a JSON configuration for an interactive command
|
||||
JSON='{"command":"vim","options":{"interactive":true}}'
|
||||
|
||||
# Base64 encode the JSON
|
||||
BASE64=$(echo -n "$JSON" | base64)
|
||||
|
||||
# Run the command
|
||||
./build/runner $BASE64
|
||||
```
|
||||
|
||||
### Using the helper script
|
||||
|
||||
The `run.sh` script simplifies testing by handling the JSON validation and Base64 encoding:
|
||||
|
||||
```bash
|
||||
# Run with a JSON file
|
||||
./run.sh examples/local_command.json
|
||||
|
||||
# Run with a JSON string
|
||||
./run.sh '{"command":"echo","args":["Hello World"]}'
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user