Runner.

runner/README.md

@@ -0,0 +1,212 @@
+# 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
+  },
+  "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"]}'
+```