dropshell/runner/README.md

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

{
  "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:

sudo ./install_deps.sh

This will install all required dependencies (cmake, g++, libssh-dev, jq).

Manual Installation

Ubuntu/Debian

sudo apt-get install cmake g++ libssh-dev jq

CentOS/RHEL

sudo yum install cmake gcc-c++ libssh-devel jq

macOS

brew install cmake libssh jq

Windows

Using vcpkg:

vcpkg install libssh nlohmann-json

Building

To build the project, you can use the provided build script:

./build.sh

Or manually:

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:

./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:

ENABLE_SSH_TEST=1 ./test.sh

Troubleshooting

If CMake cannot find libssh, you can:

1. Run the libssh finder script to locate your installation:

   ./examples/find_libssh.sh
   

2. Specify its location manually:

   cmake -DCMAKE_PREFIX_PATH=/path/to/libssh/installation ..
   

3. Or set the libssh_DIR environment variable:

   export libssh_DIR=/path/to/libssh/installation
   cmake ..
   

4. If the problem persists, specify the library and include paths directly:

   cmake -DLIBSSH_LIBRARY=/path/to/libssh.so -DLIBSSH_INCLUDE_DIR=/path/to/include ..
   

Usage Examples

Running a local command

# 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

# 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

# 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

# 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:

# Run with a JSON file
./run.sh examples/local_command.json

# Run with a JSON string
./run.sh '{"command":"echo","args":["Hello World"]}'