exec

README

exec

English | 中文

Table of Contents

1. Features
2. Use Cases
3. Installation
4. Quick Start
5. API Reference
6. Security Considerations
7. Best Practices
8. Advanced Usage
9. FAQ
10. Testing

Features

Cross-environment command execution toolkit with:

• Unified Interface: Same API for local, remote SSH and container execution
• Full Output Capture: Synchronously captures stdout, stderr and exit code
• Flexible Timeout: Supports both command-level and connection-level timeouts
• Multiple Auth Methods: SSH supports key, password and agent forwarding
• Process Management: Background process and process group support

Use Cases

Batch Server Operations

// Execute maintenance commands across servers
for _, host := range servers {
    config.Host = host
    exec.RunSSHCommand(config, "apt update && apt upgrade -y", 300)
}

CI/CD Pipelines

// Post-deployment verification
if code, out, _ := exec.RunReturnAll("curl -sSf http://localhost:8080/health", 10); code != 0 {
    log.Fatal("Service health check failed")
}

Container Management

// Run diagnostic commands in containers
exec.RunSSHCommand(config, "singularity exec app.sif df -h", 30)

Installation

go get github.com/kaichao/gopkg/exec

Quick Start

Local Execution

code, stdout, stderr, err := exec.RunReturnAll("ls -l /tmp", 10)
if err != nil {
    log.Printf("Execution failed: %v\nOutput: %s\nError: %s", err, stdout, stderr)
}

SSH Remote Execution

config := exec.SSHConfig{
    User:    "admin",
    Host:    "10.0.0.1", 
    KeyPath: "/home/user/.ssh/id_rsa",
}

// Execute and capture full output
code, out, errOut, err := exec.RunSSHCommand(config, "docker ps -a", 30)

Container Execution

// Run commands in Singularity container
cmd := "singularity exec /images/debian.sif apt-get update"
RunSSHCommand(config, cmd, 60)

API Reference

Core Methods

// Local execution
func RunReturnAll(command string, timeout int) (code int, stdout string, stderr string, err error)

// SSH execution 
func RunSSHCommand(config SSHConfig, command string, timeout int) (code int, stdout string, stderr string, err error)

SSHConfig Struct

type SSHConfig struct {
    User       string // Required
    Host       string // Required
    Port       int    // Default 22
    KeyPath    string // Preferred over password
    Password   string 
    Timeout    int    // Connection timeout (seconds)
    Background bool   // Run command in background
}

Security Considerations

1. Authentication Security

   • Set SSH private key permissions to 600
   • Avoid hardcoding passwords in code

2. Command Injection Protection

   // Unsafe
   cmd := fmt.Sprintf("ls %s", userInput)
   
   // Safe approach
   cmd := fmt.Sprintf("ls %s", filepath.Clean(userInput))
   

3. Logging

   • Record metadata for critical operations (user, command, timestamp)
   • Avoid logging sensitive output

Best Practices

Connection Reuse

var client *ssh.Client

func getClient(config SSHConfig) (*ssh.Client, error) {
    if client == nil {
        // Initialize connection...
    }
    return client, nil
}

Error Handling

// Check specific error types
if errors.Is(err, exec.ErrTimeout) {
    // Handle timeout
}

Resource Cleanup

defer func() {
    if cmd.Process != nil {
        cmd.Process.Kill()
    }
}()

Advanced Usage

Signal Handling

// Terminate entire process group
syscall.Kill(-pid, syscall.SIGTERM)

Background Processes

// Run command in background mode
config := exec.SSHConfig{
    Host: "10.0.0.1",
    User: "admin",
    Background: true, // Enable background execution
    // ... other config
}

// Returns PID immediately while process continues running
_, pid, _, _ := exec.RunSSHCommand(config, "long-running-command", 0)

FAQ

Connection Timeouts

• Check network firewall settings
• Increase connection timeout:

  config.Timeout = 30 // seconds
  

Output Truncation

• Use buffers or temp files for large outputs
• Set reasonable execution timeouts

Testing

1. Prepare test Singularity image:

mkdir -p ~/singularity
docker save debian:12-slim -o debian.tar
singularity build ~/singularity/debian.sif docker-archive://debian.tar

1. Run unit tests:

cd exec && go test -v

Documentation

Index

• func RunReturnAll(command string, timeout int) (int, string, string, error)
• func RunReturnExitCode(command string, timeout int) (int, error)
• func RunReturnStdout(command string, timeout int) (string, error)
• func RunSSHCommand(config SSHConfig, command string, timeout int) (int, string, string, error)
• func RunWithRetries(cmd string, numRetries int, timeout int) int
• type CircularBuffer
  • func NewCircularBuffer(size int) *CircularBuffer
  • func (c *CircularBuffer) Bytes() []byte
  • func (c *CircularBuffer) Write(p []byte) (n int, err error)
• type SSHConfig

Functions

func RunReturnAll

func RunReturnAll(command string, timeout int) (int, string, string, error)

RunReturnAll executes a command and returns its exit code, stdout, stderr, and any error.

Params:

• command: the command string to execute
• timeout: timeout in seconds (0 for no timeout)

Returns: (exitCode, stdout, stderr, err)

• exitCode：命令的退出码（0 表示成功，非零表示命令失败或超时等）
• stdout：标准输出
• stderr：标准错误
• err：执行过程中遇到的错误（如管道创建失败、命令启动失败、超时等）。若命令以非零退出码结束，err 为 nil
• 管道创建或命令启动失败时，返回退出码 125 和具体的 error
• 超时情况下，返回退出码 124 和 err = "command timed out"
• 命令以非零退出码结束时，返回该退出码，err 为 nil
• 其他未预期的错误通过 err 返回，退出码为 125

func RunReturnExitCode

func RunReturnExitCode(command string, timeout int) (int, error)

RunReturnExitCode ...

func RunReturnStdout

func RunReturnStdout(command string, timeout int) (string, error)

RunReturnStdout ...

func RunSSHCommand

func RunSSHCommand(config SSHConfig, command string, timeout int) (int, string, string, error)

RunSSHCommand executes command via SSH with full lifecycle management

func RunWithRetries

func RunWithRetries(cmd string, numRetries int, timeout int) int

RunWithRetries ...

Types

type CircularBuffer

type CircularBuffer struct {
	// contains filtered or unexported fields
}

CircularBuffer 实现固定大小的环形缓冲区

func NewCircularBuffer

func NewCircularBuffer(size int) *CircularBuffer

NewCircularBuffer 创建一个新的环形缓冲区

func (*CircularBuffer) Bytes

func (c *CircularBuffer) Bytes() []byte

Bytes 返回缓冲区中的最新数据

func (*CircularBuffer) Write

func (c *CircularBuffer) Write(p []byte) (n int, err error)

Write 写入数据到环形缓冲区，超出部分覆盖最早数据

type SSHConfig

type SSHConfig struct {
	User       string
	Host       string
	Port       int
	KeyPath    string // Path to private key file, empty for default (~/.ssh/id_rsa)
	Password   string // Optional, if using password auth
	Background bool   // If true, run command in background and return PID
	UseHomeTmp bool   // If true, use ${HOME}/tmp instead of /tmp for temporary files
}

SSHConfig defines SSH connection parameters.