cmdproxy

cmdproxy

Server and client for running commands through a proxy.

• About
  • Concepts
• Install
• Quick start
• Usage
• Configuration
  • Server
    • Container
  • Client
• Command reference

About

The purpose of cmdproxy (server and client) is to provide a means to run a selection of command-line applications as if local but ran through the server on another host/container. The communication between server and client is over Unix domain sockets by default.

As an added benefit eventual credentials and secrets live with the server, and not where the tool is run, providing a layer of control in scenarios where other tools make use of command-line tools.

The application comes with it's built-in container image build and method to run itself in a container that handles mount and setup of the configuration directory and shared files for the server and client.

Concepts

The application comes in two modes, the server through cmdproxy serve and the client through cmdproxy run.

For most use cases the server and client share configuration, with subsections that are specific to each. By default the configuration is located in the file ~/.cmdproxy/config.json.

Commands to proxy are configured in an "allow list", the field commands in the configuration file. These commands/programs needs to be available/installed where the server runs.

The server listens for connections and command requests, and runs them. The client sends command requests.

Install

Prerequisites:

• (Optional) Docker Engine (Built-in container handling)

Install script

[!NOTE] Script for Linux and macOS.

curl -fsSL https://codeberg.org/KarlGW/cmdproxy/raw/branch/main/scripts/install.sh | sh

Linux

Go to Releases and download the latest release for Linux:

# This example uses architecture amd64 as an example, if you are using arm64, change it.
curl -sLO https://codeberg.org/KarlGW/cmdproxy/releases/download/v<version>/cmdproxy-<version>-linux-amd64.tar.gz
mkdir -p ~/.local/bin
tar -C ~/.local/bin -xvf cmdproxy-<version>-linux-amd64.tar.gz && rm cmdproxy-<version>-linux-amd64.tar.gz

[!NOTE] Make sure ~/.local/bin is set to $PATH.

macOS

Go to Releases and download the latest release for macOS:

# This example uses architecture arm64 as an example, if you are using amd64, change it.
curl -sLO https://codeberg.org/KarlGW/cmdproxy/releases/download/v<version>/cmdproxy-<version>-darwin-arm64.tar.gz
mkdir -p ~/.local/bin
tar -C ~/.local/bin -xvf cmdproxy-<version>-darwin-arm64.tar.gz && rm cmdproxy-<version>-darwin-arm64.tar.gz

[!NOTE] Make sure ~/.local/bin is set to $PATH.

go install

go install codeberg.org/KarlGW/cmdproxy/cmd/cmdproxy@latest

Quick start

The following quick start guide shows how to run cmdproxy in a container and run curl.

Setting up and running the server

1. Create an image template file:

   mkdir -p ~/.cmdproxy
   touch ~/.cmdproxy/image.tmpl
   

2. Edit ~/.cmdproxy/image.tmpl Add RUN statement to install curl:

   RUN apk update && apk add --no-cache curl
   

   [!NOTE] This is a Dockerfile "template", no need add a FROM statement, as this is done during the parsing stage.

3. Build the image:

   cmdproxy build
   

4. Add curl to commands in ~/.cmdproxy/config.json:

   {
     "commands": [ "curl" ]
   }
   

5. Start the server:

   cmdproxy serve
   

Setting up and running the client

These steps are preferably done inside a container that will run the commands.

1. Set ~/cmdproxy/bin to PATH:

   export PATH=${HOME}/.cmdproxy/bin:$PATH
   

2. Initialise client (create command shims in ~/.cmdproxy/bin)

   cmdproxy init
   

3. Run proxied command:

   curl https://example.com
   

Usage

Configuration

Server

Container

Client

Command reference