ork

README

Ork

Ork is a Go package for SSH-based server automation. Think of it like Ansible, but in Go - you define Nodes (remote servers) and run commands or playbooks against them.

Installation

go get github.com/dracory/ork

Quick Start

The core concept is the Node - a representation of a remote server:

package main

import (
    "log"
    "github.com/dracory/ork"
)

func main() {
    // Create a node (remote server) - multiple ways:
    
    // Option 1: From host (most common)
    node := ork.NewNodeForHost("server.example.com")
    
    // Option 2: Empty node, configure later
    node := ork.NewNode().SetHost("server.example.com")
    
    // Option 3: From existing config
    node := ork.NewNodeFromConfig(cfg)
    
    // Run a command
    output, err := node.RunCommand("uptime")
    if err != nil {
        log.Fatal(err)
    }
    log.Println(output)
}

Configuration

Use the fluent API to configure connection settings:

// From host
node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

output, err := node.RunCommand("uptime")

Persistent Connections

For multiple operations, establish a persistent connection:

node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

// These commands reuse the same SSH connection
output1, _ := node.RunCommand("uptime")
output2, _ := node.RunCommand("df -h")

Playbooks

Run pre-built automation tasks (playbooks) against a node:

node := ork.NewNodeForHost("server.example.com").
    SetArg("username", "alice").
    SetArg("shell", "/bin/bash")

err := node.RunPlaybook(ork.PlaybookUserCreate)

Available Playbooks

ork Package	playbook Package	String	Args	Description
PlaybookPing	NamePing	ping	-	Check SSH connectivity
PlaybookAptUpdate	NameAptUpdate	apt-update	-	Refresh package database
PlaybookAptUpgrade	NameAptUpgrade	apt-upgrade	-	Install available updates
PlaybookAptStatus	NameAptStatus	apt-status	-	Show available updates
PlaybookReboot	NameReboot	reboot	-	Reboot server
PlaybookSwapCreate	NameSwapCreate	swap-create	size (GB)	Create swap file
PlaybookSwapDelete	NameSwapDelete	swap-delete	-	Remove swap file
PlaybookSwapStatus	NameSwapStatus	swap-status	-	Show swap status
PlaybookUserCreate	NameUserCreate	user-create	username	Create user with sudo
PlaybookUserDelete	NameUserDelete	user-delete	username	Delete user
PlaybookUserStatus	NameUserStatus	user-status	username (opt)	Show user info

Advanced Usage

Inspecting Configuration

node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

fmt.Printf("Host: %s\n", node.GetHost())
fmt.Printf("Port: %s\n", node.GetPort())
fmt.Printf("User: %s\n", node.GetUser())

// Get full config for integration with internal packages
cfg := node.GetConfig()

Custom Playbooks

Extend Ork with custom automation tasks:

import (
    "github.com/dracory/ork/playbook"
    "github.com/dracory/ork/config"
)

// Create a custom playbook
customPlaybook := playbook.NewSimplePlaybook(
    "custom-task",
    "Performs a custom automation task",
    func(cfg config.Config) error {
        // Your custom logic here
        return nil
    },
)

// Register it in the playbook registry
// (access via the playbook package)

Internal Packages

For advanced use cases or when you need fine-grained control, you can use the internal packages directly:

• ssh - SSH connection utilities and command execution
• config - Configuration types for remote operations
• playbook - Base interfaces and registry for organizing playbooks
• playbooks - Reusable playbook implementations (ping, apt, reboot, swap, user)

For advanced use cases, use the internal packages directly:

package main

import (
    "log"

    "github.com/dracory/ork/config"
    "github.com/dracory/ork/playbooks"
)

func main() {
    cfg := config.Config{
        SSHHost:  "db3.sinevia.com",
        SSHPort:  "40022",
        SSHKey:   "2024_sinevia.prv",
        RootUser: "root",
    }

    // Ping server to check connectivity
    ping := playbooks.NewPing()
    if err := ping.Run(cfg); err != nil {
        log.Fatal(err)
    }

    // Update packages
    aptUpdate := playbooks.NewAptUpdate()
    if err := aptUpdate.Run(cfg); err != nil {
        log.Fatal(err)
    }

    // Create a 2GB swap file
    cfg.Args = map[string]string{"size": "2"}
    swapCreate := playbooks.NewSwapCreate()
    if err := swapCreate.Run(cfg); err != nil {
        log.Fatal(err)
    }
}

Package Overview

• ork - Main API: NodeInterface, NewNode(), NewNodeForHost(), NewNodeFromConfig()
• config - Configuration types
• ssh - SSH client with connection management
• playbook - Playbook interface and registry
• playbooks - Built-in playbook implementations

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). You can find a copy of the license at https://www.gnu.org/licenses/agpl-3.0.en.html

For commercial use, please use my contact page to obtain a commercial license.

Documentation

Overview

Package ork provides a simple, intuitive API for SSH-based server automation.

The core concept is the Node - a representation of a remote server that you can connect to and run commands or playbooks against.

Basic usage:

node := ork.NewNode("server.example.com")
output, err := node.Run("uptime")

With configuration:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy")
output, err := node.Run("uptime")

Persistent connections for multiple operations:

node := ork.NewNode("server.example.com")
if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

output1, _ := node.Run("uptime")
output2, _ := node.Run("df -h")

Running playbooks:

node := ork.NewNode("server.example.com").
    SetArg("username", "alice")
err := node.Playbook("user-create")

For advanced use cases, the internal packages remain accessible:

• config - Configuration types
• ssh - SSH client
• playbook - Playbook interface and registry
• playbooks - Built-in playbook implementations

Index

• Constants
• type NodeInterface
  • func NewNode() NodeInterface
  • func NewNodeForHost(host string) NodeInterface
  • func NewNodeFromConfig(cfg config.Config) NodeInterface

Constants

const (
	// PlaybookPing checks SSH connectivity
	PlaybookPing = playbook.NamePing

	// PlaybookAptUpdate refreshes the package database
	PlaybookAptUpdate = playbook.NameAptUpdate

	// PlaybookAptUpgrade installs available updates
	PlaybookAptUpgrade = playbook.NameAptUpgrade

	// PlaybookAptStatus shows available updates
	PlaybookAptStatus = playbook.NameAptStatus

	// PlaybookReboot reboots the server
	PlaybookReboot = playbook.NameReboot

	// PlaybookSwapCreate creates a swap file (requires "size" arg in GB)
	PlaybookSwapCreate = playbook.NameSwapCreate

	// PlaybookSwapDelete removes the swap file
	PlaybookSwapDelete = playbook.NameSwapDelete

	// PlaybookSwapStatus shows swap status
	PlaybookSwapStatus = playbook.NameSwapStatus

	// PlaybookUserCreate creates a user with sudo (requires "username" arg)
	PlaybookUserCreate = playbook.NameUserCreate

	// PlaybookUserDelete deletes a user (requires "username" arg)
	PlaybookUserDelete = playbook.NameUserDelete

	// PlaybookUserStatus shows user info (accepts optional "username" arg)
	PlaybookUserStatus = playbook.NameUserStatus
)

Playbook name constants for use with RunPlaybook. These constants provide compile-time safety and IDE autocomplete for playbook names. They are aliases to the constants in the playbook package.

Example:

node := ork.NewNodeForHost("server.example.com")
err := node.RunPlaybook(ork.PlaybookPing)

Types

type NodeInterface

type NodeInterface interface {

	// GetArg retrieves a single argument value by key.
	// Returns empty string if the argument is not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetArg("username", "alice")
	//	fmt.Println(node.GetArg("username"))  // Output: alice
	GetArg(key string) string

	// GetArgs returns a copy of the entire arguments map.
	// Modifying the returned map will not affect the node's internal state.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetArg("username", "alice")
	//	args := node.GetArgs()
	//	fmt.Println(args["username"])  // Output: alice
	GetArgs() map[string]string

	// GetConfig returns a copy of the underlying config.Config.
	// This allows integration with code that uses the config package directly.
	// The returned configuration includes all accumulated settings (host, port, user, key, args).
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").
	//	    SetPort("2222").
	//	    SetUser("deploy")
	//	cfg := node.GetConfig()
	//	fmt.Printf("Connecting to %s\n", cfg.SSHAddr())
	GetConfig() config.Config

	// GetHost returns the configured SSH host (hostname or IP address).
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	fmt.Println(node.GetHost())  // Output: server.example.com
	GetHost() string

	// GetUser returns the configured SSH user.
	// Returns "root" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetUser("deploy")
	//	fmt.Println(node.GetUser())  // Output: deploy
	GetUser() string

	// GetKey returns the configured SSH private key filename.
	// Returns "id_rsa" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetKey("production.prv")
	//	fmt.Println(node.GetKey())  // Output: production.prv
	GetKey() string

	// GetPort returns the configured SSH port.
	// Returns "22" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetPort("2222")
	//	fmt.Println(node.GetPort())  // Output: 2222
	GetPort() string

	// SetPort sets the SSH port for the connection.
	// Returns the NodeInterface to enable method chaining.
	// Default is "22" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetPort("2222")
	SetPort(port string) NodeInterface

	// SetUser sets the SSH user for the connection.
	// Returns the NodeInterface to enable method chaining.
	// Default is "root" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetUser("deploy")
	SetUser(user string) NodeInterface

	// SetKey sets the SSH private key filename for authentication.
	// The key is resolved to ~/.ssh/<keyname>.
	// Returns the NodeInterface to enable method chaining.
	// Default is "id_rsa" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetKey("production.prv")
	SetKey(key string) NodeInterface

	// SetArg adds a single argument to the arguments map.
	// This adds to existing arguments without replacing them.
	// Arguments are passed to playbooks for configuration.
	// Returns the NodeInterface to enable method chaining.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").
	//	    SetArg("username", "alice").
	//	    SetArg("shell", "/bin/bash")
	SetArg(key, value string) NodeInterface

	// SetArgs replaces the entire arguments map with the provided map.
	// Any existing arguments are discarded.
	// Arguments are passed to playbooks for configuration.
	// Returns the NodeInterface to enable method chaining.
	//
	// Example:
	//
	//	args := map[string]string{
	//	    "username": "alice",
	//	    "shell": "/bin/bash",
	//	}
	//	node := ork.NewNode("server.example.com").SetArgs(args)
	SetArgs(args map[string]string) NodeInterface

	// Connect establishes a persistent SSH connection to the remote server.
	// The connection is maintained until Close() is called.
	// Subsequent RunCommand() and RunPlaybook() calls will reuse this connection.
	//
	// Returns an error if the connection fails, with a descriptive message
	// including the host and port.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	if err := node.Connect(); err != nil {
	//	    log.Fatalf("Failed to connect: %v", err)
	//	}
	//	defer node.Close()
	Connect() error

	// Close terminates the persistent SSH connection and releases resources.
	// After calling Close(), IsConnected() will return false.
	// It is safe to call Close() multiple times or on a non-connected node.
	//
	// Returns an error if closing the connection fails.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	node.Connect()
	//	defer node.Close()
	Close() error

	// IsConnected returns true if a persistent SSH connection is currently active.
	// Returns false if Connect() has not been called or if Close() was called.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	fmt.Println(node.IsConnected())  // Output: false
	//	node.Connect()
	//	fmt.Println(node.IsConnected())  // Output: true
	//	node.Close()
	//	fmt.Println(node.IsConnected())  // Output: false
	IsConnected() bool

	// RunCommand executes a shell command on the remote server.
	// If a persistent connection is active (via Connect()), it is reused.
	// Otherwise, a one-time connection is created for this command.
	//
	// Returns the command output as a string and any error that occurred.
	// If the command execution fails, the error message includes the command
	// and failure reason.
	//
	// Example with persistent connection:
	//
	//	node := ork.NewNode("server.example.com")
	//	node.Connect()
	//	defer node.Close()
	//
	//	output1, _ := node.RunCommand("uptime")
	//	output2, _ := node.RunCommand("df -h")  // Reuses same connection
	//
	// Example without persistent connection:
	//
	//	node := ork.NewNode("server.example.com")
	//	output, err := node.RunCommand("uptime")  // Creates one-time connection
	RunCommand(cmd string) (string, error)

	// RunPlaybook executes a named playbook on the remote server.
	// The playbook is retrieved from the global registry.
	// The current node configuration (including arguments set via SetArg/SetArgs)
	// is passed to the playbook.
	//
	// Returns an error if the playbook is not found in the registry or if
	// execution fails. The error message includes the playbook name and failure reason.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").
	//	    SetArg("username", "alice").
	//	    SetArg("shell", "/bin/bash")
	//
	//	if err := node.RunPlaybook("user-create"); err != nil {
	//	    log.Fatalf("Playbook failed: %v", err)
	//	}
	RunPlaybook(name string) error
}

NodeInterface defines the contract for managing a remote server via SSH. Implementations must support configuration via setter methods, connection management, command execution, and playbook execution.

The interface provides two patterns for configuration:

• Fluent builder pattern: Chain setter methods for readable configuration
• Getter methods: Inspect current configuration state

Connection management is explicit, allowing users to control the SSH connection lifecycle. Operations (RunCommand, RunPlaybook) can work with or without a persistent connection.

Example usage with fluent builder pattern:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

output, err := node.RunCommand("uptime")
if err != nil {
    log.Fatal(err)
}
fmt.Println(output)

Example usage without persistent connection:

node := ork.NewNode("server.example.com")
output, err := node.RunCommand("uptime")  // Creates one-time connection

Example usage with playbooks:

node := ork.NewNode("server.example.com").
    SetArg("username", "alice").
    SetArg("shell", "/bin/bash")

if err := node.RunPlaybook("user-create"); err != nil {
    log.Fatal(err)
}

func NewNode

func NewNode() NodeInterface

NewNode creates a new Node with default configuration values. Unlike NewNodeForHost, this function takes no arguments and creates a node with an empty host. Use SetArg or SetArgs to configure the node.

Default values:

• Host: "" (empty - must be set before connecting)
• Port: "22"
• User: "root"
• Key: "id_rsa"
• Args: empty map

Example:

node := ork.NewNode().
    SetHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}

func NewNodeForHost

func NewNodeForHost(host string) NodeInterface

NewNode creates a new Node with default configuration values. The host parameter specifies the remote server (hostname or IP address).

Default values:

• Port: "22"
• User: "root"
• Key: "id_rsa"
• Args: empty map

The returned NodeInterface can be configured using setter methods (SetPort, SetUser, SetKey, SetArg, SetArgs) before connecting.

Example:

node := ork.NewNode("server.example.com")
// Equivalent to:
// Node{
//     cfg: config.Config{
//         SSHHost: "server.example.com",
//         SSHPort: "22",
//         RootUser: "root",
//         SSHKey: "id_rsa",
//         Args: map[string]string{},
//     },
//     connected: false,
// }

Example with configuration:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

func NewNodeFromConfig

func NewNodeFromConfig(cfg config.Config) NodeInterface

NewNodeFromConfig creates a new Node from an existing config.Config. This is useful when you have a pre-built configuration and want to create a Node from it directly.

The config is copied internally, so modifications to the original config after calling this function will not affect the Node.

Example:

cfg := config.Config{
    SSHHost:  "server.example.com",
    SSHPort:  "2222",
    RootUser: "deploy",
    SSHKey:   "production.prv",
    Args: map[string]string{"env": "production"},
}
node := ork.NewNodeFromConfig(cfg)

if err := node.Connect(); err != nil {
    log.Fatal(err)
}