User Guide

Installation, basic usage, and practical examples for Parallax

This guide provides installation steps, basic usage instructions, and practical examples for using Parallax.

Installation

Use a binary from GitLab Releases, or build from a checkout with Go 1.25 or newer:

bash

git clone https://gitlab.com/digitalxero/parallax.git
cd parallax
go install ./cmd/parallax

The executable is installed into $(go env GOPATH)/bin unless GOBIN is set. For release-style platform artifacts, install Task and run task build: build/parallax-<os>-<arch> (with .exe on Windows). Use task build:all for all supported controller targets. The checkout includes the module SDK; versioned go install ...@latest cannot use the repository’s local module replacement.

Go is also required on the controller when running playbooks. The executable includes the matching SDK source; the first module build may download its Go dependencies. Target machines do not need Go or Python for Parallax itself.

Basic Usage

Execute a playbook:

bash

parallax play playbook.yml

Run with a specific inventory and limit to tags:

bash

parallax play -i inventory.ini --tags "setup,configure" playbook.yml

Skip tags during execution:

bash

parallax play --skip-tags "test,cleanup" playbook.yml

Check mode (dry run):

bash

parallax play --check playbook.yml

Examples

Inventory Formats

INI Format

ini

[webservers]
web1.example.com ansible_host=10.0.0.1
web2.example.com ansible_port=2222

[dbservers]
db[1:3].example.com

[webservers:vars]
http_port=80

YAML Format

yaml

all:
  hosts:
    web1.example.com:
      ansible_host: 10.0.0.1
    web2.example.com:
      ansible_port: 2222
  children:
    webservers:
      vars:
        http_port: 80

Command Line

bash

parallax play -i "web1.example.com,web2.example.com" playbook.yml

Sample Playbook

yaml

- hosts: webservers
  tasks:
    - name: Ensure nginx is installed
      package:
        name: nginx
        state: present

Run the sample playbook:

bash

parallax play -i inventory.ini sample.yml

Persistent Facts Cache

parallax play --facts-cache-dir ~/.parallax/facts-cache playbook.yml reuses facts across controller processes. The directory holds a cache separate from recorded facts history. Entries include the host address, transport, execution user and gather options; an alias pointing at a different host cannot reuse the old host’s facts. --facts-cache-ttl applies to the original observation time. Use --facts-force-full to refresh or --facts-cache-clear to clear that cache.

For standalone collection, use parallax facts gather --cache-dir PATH --cache-ttl 10m. facts watch always gathers fresh facts so caching cannot hide changes from monitoring.

External Callbacks and Prompts

Built-in callback names work as before. An unrecognized --callback NAME loads an external callback from the typed callback directory under --plugin-dir; a missing or incompatible plugin is an error.

Play-level vars_prompt prompts once per play. Input is private by default; confirm requests confirmation. Extra variables supplied with -e bypass the prompt. Noninteractive runs use a supplied default or report missing input. Prompt encryption supports bcrypt; other schemes are rejected explicitly.