214 lines
4.7 KiB
Markdown
214 lines
4.7 KiB
Markdown
# Runner
|
|
|
|
Simple c++ demonstration program of the dropshell runner library.
|
|
|
|
use:
|
|
runner BASE64COMMAND
|
|
|
|
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
|
|
{
|
|
"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)
|
|
}
|
|
}
|
|
```
|
|
|
|
If SSH information is provided, the command will be executed on the remote server.
|
|
|
|
## 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
|
|
```
|
|
|
|
This will install all required dependencies (cmake, g++, libssh-dev, jq).
|
|
|
|
##### Manual Installation
|
|
|
|
###### Ubuntu/Debian
|
|
|
|
```bash
|
|
sudo apt-get install cmake g++ libssh-dev jq
|
|
```
|
|
|
|
###### 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"]}'
|
|
```
|