Meshbook is a tool to programmatically manage MeshCentral-managed machines, inspired by tools like Ansible.

Meshbook is designed to:

• Automate system updates or commands across multiple systems via MeshCentral, even behind third-party-managed firewalls.
• Allow configuration using simple and readable YAML files (like Ansible playbooks).
• Simplify the use of group-based or tag-based device targeting.

• Python 3.7+

• Git

• Access to a MeshCentral instance and credentials with:

  • Remote Commands
  • Details
  • Agent Console permissions

A service account with access to the relevant device groups is recommended.

git clone https://github.com/daanselen/meshbook
cd ./meshbook
python3 -m venv ./venv
source ./venv/bin/activate
pip install -r requirements.txt
cp ./templates/meshcentral.conf.template ./meshcentral.conf

git clone https://github.com/daanselen/meshbook
cd .\meshbook
python -m venv .\venv
.\venv\Scripts\activate
pip install -r .\requirements.txt
cp .\templates\meshcentral.conf.template .\meshcentral.conf

📌 Rename meshcentral.conf.template to meshcentral.conf and fill in your actual connection details. The URL must start with wss://<MeshCentral-Host>.

Once installed and configured, run a playbook like this:

python3 meshbook.py -pb ./examples/echo_example.yaml

.\venv\Scripts\python.exe .\meshbook.py -pb .\examples\echo_example.yaml

Use --help to explore available command-line options:

python3 meshbook.py --help

Meshbook configurations are written in YAML. Below is an overview of supported fields.

---
name: My Configuration
group: "Dev Machines"
powershell: true
variables:
  - name: message
    value: "Hello from Meshbook"
tasks:
  - name: Echo a message
    command: 'echo "{{ message }}"'

• group: MeshCentral group (aka "mesh"). Quotation marks required for multi-word names.
• powershell: Set true for PowerShell commands on Windows clients.

You can also target a specific device rather than a group. See apt_update_example.yaml for reference.

Variables are replaced by Meshbook before execution. Syntax:

variables:
  - name: example_var
    value: "Example value"

tasks:
  - name: Use the variable
    command: 'echo "{{ example_var }}"'

• Primary and Secondary mark the order in which will take prescendence

Define multiple tasks:

tasks:
  - name: Show OS info
    command: "cat /etc/os-release"

Each task must include:

• name: Description for human readability.
• command: The actual shell or PowerShell command.

• Keep your os_categories.json up to date for proper OS filtering.
• Ensure Windows commands are compatible (use powershell: true if needed).
• Examples are available in examples/windows.

You can limit commands to specific OS types:

target_os: "Linux"  # As defined in os_categories.json

See docs/operating_system_filtering.md for details.

You can also filter using MeshCentral tags:

target_tag: "Production"

⚠️ Tag values are case-sensitive.

---
name: Echo OS Info
group: "Dev"
target_os: "Linux"
variables:
  - name: file
    value: "/etc/os-release"
tasks:
  - name: Show contents of os-release
    command: "echo $(cat {{ file }})"

Sample output:

{
  "Task 1": {
    "task_name": "Show contents of os-release",
    "data": [
      {
        "command": "echo $(cat /etc/os-release)",
        "result": [
          "NAME=\"Ubuntu\"",
          "VERSION=\"22.04.4 LTS (Jammy Jellyfish)\""
        ],
        "complete": true,
        "device_name": "dev-host1"
      }
    ]
  }
}

Avoid using commands that block indefinitely — MeshCentral requires non-blocking execution.

🚫 Examples of bad (blocking) commands:

apt upgrade       # Without -y
sleep infinity
ping 1.1.1.1      # Without -c

✅ Use instead:

apt upgrade -y
ping 1.1.1.1 -c 1

Sometimes the wrong Python interpreter or environment is used. To verify:

python3 -m pip list
pip3 list

The lists should match. If not, make sure the correct environment is activated.

meshbook/
├── books/
│   ├── apt-update.yaml
│   └── rdp.yaml
├── examples/
│   ├── linux/
│   │   ├── apt_update_example.yaml
│   │   └── ...
│   └── windows/
│       ├── get_sys_info.yaml
│       └── ...
├── modules/
│   ├── executor.py
│   └── utilities.py
├── meshbook.py
├── os_categories.json
├── requirements.txt
├── templates/
│   └── config.conf.template

This project is licensed under the terms of the GPL3 License. See LICENSE.