Changed Readme. (With the help of some AI)
This commit is contained in:
@@ -1,207 +1,280 @@
|
|||||||
[](https://github.com/DaanSelen/meshbook/actions/workflows/codeql.yaml)
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> *If you experience issues or have suggestions, submit an issue! https://github.com/DaanSelen/meshbook/issues I'll respond ASAP!*
|
|
||||||
|
|
||||||
# Meshbook
|
# Meshbook
|
||||||
|
|
||||||
A way to programmatically manage MeshCentral-managed machines, inspired by applications like [Ansible](https://github.com/ansible/ansible).<br>
|
[](https://github.com/DaanSelen/meshbook/actions/workflows/codeql.yaml)
|
||||||
What problem does it solve? Well, what I wanted to be able to do is to automate system updates through [MeshCentral](https://github.com/ylianst/meshcentral). And some machines are behind unmanaged or 3rd party managed firewalls.<br>
|
|
||||||
And many people will be comfortable with YAML configurations! It's almost like JSON, but different!<br>
|
|
||||||
|
|
||||||
# Quick-start:
|
> \[!NOTE]
|
||||||
|
> 💬 If you experience issues or have suggestions, [submit an issue](https://github.com/DaanSelen/meshbook/issues) — I'll respond ASAP!
|
||||||
|
|
||||||
The quickest way to start is to grab a template from the templates folder in this repository.<br>
|
---
|
||||||
Make sure to correctly pass the MeshCentral websocket API as `wss://<MeshCentral-Host>`.<br>
|
|
||||||
And make sure to fill in the credentails of an account which has `Remote Commands`, `Details` and `Agent Console` permissions on the targeted devices or groups.<br>
|
|
||||||
|
|
||||||
> I did this through a "Service account" with rights on the device group.
|
Meshbook is a tool to **programmatically manage MeshCentral-managed machines**, inspired by tools like [Ansible](https://github.com/ansible/ansible).
|
||||||
|
|
||||||
Then make a yaml with a target and some commands! See below examples as a guideline. And do not forget to look at the bottom's notice.<br>
|
## What problem does it solve?
|
||||||
To install, follow the following commands:<br>
|
|
||||||
|
|
||||||
### Linux setup:
|
Meshbook is designed to:
|
||||||
|
|
||||||
|
* Automate system updates or commands across multiple systems via [MeshCentral](https://github.com/Ylianst/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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏁 Quick Start
|
||||||
|
|
||||||
|
### ✅ Prerequisites
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🔧 Installation
|
||||||
|
|
||||||
|
#### Linux
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/daanselen/meshbook
|
git clone https://github.com/daanselen/meshbook
|
||||||
cd ./meshbook
|
cd ./meshbook
|
||||||
python3 -m venv ./venv
|
python3 -m venv ./venv
|
||||||
source ./venv/bin/activate
|
source ./venv/bin/activate
|
||||||
pip3 install -r ./requirements.txt
|
pip install -r requirements.txt
|
||||||
cp ./templates/meshcentral.conf.template ./meshcentral.conf
|
cp ./templates/meshcentral.conf.template ./meshcentral.conf
|
||||||
```
|
```
|
||||||
|
|
||||||
### Windows setup (PowerShell, not cmd):
|
#### Windows (PowerShell)
|
||||||
|
|
||||||
```shell
|
```powershell
|
||||||
git clone https://github.com/daanselen/meshbook
|
git clone https://github.com/daanselen/meshbook
|
||||||
cd ./meshbook
|
cd .\meshbook
|
||||||
python -m venv ./venv # or python3 when done through the Microsoft Store.
|
python -m venv .\venv
|
||||||
.\venv\Scripts\activate # Make sure to check the terminal prefix.
|
.\venv\Scripts\activate
|
||||||
pip3 install -r ./requirements.txt
|
pip install -r .\requirements.txt
|
||||||
cp .\templates\meshcentral.conf.template .\meshcentral.conf
|
cp .\templates\meshcentral.conf.template .\meshcentral.conf
|
||||||
```
|
```
|
||||||
|
|
||||||
Now copy the configuration template from ./templates and fill it in with the correct details (remove .template from the file) this is shown in the last step of the setup(s).<br>
|
> 📌 Rename `meshcentral.conf.template` to `meshcentral.conf` and fill in your actual connection details.
|
||||||
The url should start with `wss://`.<br>
|
> The URL must start with `wss://<MeshCentral-Host>`.
|
||||||
You can check pre-made examples in the examples directory, make sure the values are set to your situation.<br>
|
|
||||||
After this you can use meshbook, for example:
|
|
||||||
|
|
||||||
### Linux run:
|
---
|
||||||
|
|
||||||
|
## 🚀 Running Meshbook
|
||||||
|
|
||||||
|
Once installed and configured, run a playbook like this:
|
||||||
|
|
||||||
|
### Linux:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 .\meshbook.py -pb .\examples\echo.yaml
|
python3 meshbook.py -pb ./examples/echo_example.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
### Windows run:
|
### Windows:
|
||||||
|
|
||||||
```shell
|
```powershell
|
||||||
.\venv\Scripts\python.exe .\meshbook.py -pb .\examples\echo_example.yaml
|
.\venv\Scripts\python.exe .\meshbook.py -pb .\examples\echo_example.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
### How to check if everything is okay?
|
Use `--help` to explore available command-line options:
|
||||||
|
|
||||||
The python virtual environment can get messed up, therefore...<br>
|
```bash
|
||||||
To check if everything is in working order, make sure that the lists from the following commands are aligned:
|
python3 meshbook.py --help
|
||||||
|
|
||||||
```
|
|
||||||
python3 -m pip list
|
|
||||||
pip3 list
|
|
||||||
```
|
```
|
||||||
|
|
||||||
If not, perhaps you are using the wrong executable, the wrong environment and so on...
|
---
|
||||||
|
|
||||||
# How to create a configuration?
|
## 🛠️ Creating Configurations
|
||||||
|
|
||||||
This paragraph explains how the program interprets certain information.
|
Meshbook configurations are written in YAML. Below is an overview of supported fields.
|
||||||
|
|
||||||
### Targeting:
|
### ▶️ Group Targeting
|
||||||
|
|
||||||
MeshCentral has `meshes` or `groups`, in this program they are called `group(s)`. Because of the way I designed this.<br>
|
|
||||||
So to target for example a mesh/group in MeshCentral called: "Nerthus" do:
|
|
||||||
|
|
||||||
> If your group has multiple words, then you need to use `"` to group the words.
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: example configuration
|
name: My Configuration
|
||||||
group: "Nerthus"
|
group: "Dev Machines"
|
||||||
#target_os: "Linux" # <--- according to os_categories.json.
|
powershell: true
|
||||||
powershell: True # <--- this can be important for Windows clients.
|
|
||||||
variables:
|
variables:
|
||||||
- name: var1
|
- name: message
|
||||||
value: "This is the first variable"
|
value: "Hello from Meshbook"
|
||||||
tasks:
|
tasks:
|
||||||
- name: echo the first variable!
|
- name: Echo a message
|
||||||
command: 'echo "{{ var1 }}"'
|
command: 'echo "{{ message }}"'
|
||||||
```
|
```
|
||||||
|
|
||||||
It is also possible to target a single device, as seen in: [here](./examples/apt_update_example.yaml).<br>
|
* `group`: MeshCentral group (aka "mesh"). Quotation marks required for multi-word names.
|
||||||
|
* `powershell`: Set `true` for PowerShell commands on Windows clients.
|
||||||
|
|
||||||
### Variables:
|
### ▶️ Device Targeting
|
||||||
|
|
||||||
Variables are done by replacing the placeholders just before the runtime (the Python program does this, not you).<br>
|
You can also target a **specific device** rather than a group. See [`apt_update_example.yaml`](./examples/linux/apt_update_example.yaml) for reference.
|
||||||
So if you have var1 declared, then the value of that declaration is placed wherever it finds {{ var1 }}.<br>
|
|
||||||
This is done to imitate popular methods. See below [from the example](./examples/variable_usage_example.yaml).<br>
|
|
||||||
|
|
||||||
### Tasks:
|
### ▶️ Variables
|
||||||
|
|
||||||
The tasks you want to run should be contained under the `tasks:` with two fields, `name` and `command`.<br>
|
Variables are replaced by Meshbook before execution. Syntax:
|
||||||
The name field is for the user of meshbook, to clarify what the following command does in a summary.<br>
|
|
||||||
The command field actually gets executed on the end-point.<br>
|
|
||||||
|
|
||||||
### Windows Client Extra-information:
|
```yaml
|
||||||
|
variables:
|
||||||
|
- name: example_var
|
||||||
|
value: "Example value"
|
||||||
|
|
||||||
If you want to launch commands at Windows machines, make sure you have your `os_categories.conf` up-to-date with the correct reported Windows versions.<br>
|
tasks:
|
||||||
And then make sure to create compatible commands, see: [windows examples](./examples/windows)<br>
|
- name: Use the variable
|
||||||
Related is the yaml option: `powershell: True`.
|
command: 'echo "{{ example_var }}"'
|
||||||
|
```
|
||||||
|
|
||||||
### Granual Operating System filtering:
|
### ▶️ Tasks
|
||||||
|
|
||||||
I have made the program so it can have a filter with the Operating systems. If you have a mixed group, please read:
|
Define multiple tasks:
|
||||||
[This explanation](./docs/operating_system_filtering.md)
|
|
||||||
|
|
||||||
### Tag filtering:
|
```yaml
|
||||||
|
tasks:
|
||||||
|
- name: Show OS info
|
||||||
|
command: "cat /etc/os-release"
|
||||||
|
```
|
||||||
|
|
||||||
Filtering on MeshCentral tags is also possible with `target_tag` inside the meshbook. This string is case-sensitive, lower- and uppercase must match.<br>
|
Each task must include:
|
||||||
This is done because its human made and therefor needs to be keps well administrated.
|
|
||||||
|
|
||||||
# Example:
|
* `name`: Description for human readability.
|
||||||
|
* `command`: The actual shell or PowerShell command.
|
||||||
|
|
||||||
For the example, I used the following yaml file (you can find more in [this directory](./examples/)):
|
---
|
||||||
|
|
||||||
The below group: `Dev` has three devices, of which one is offline, Meshbook checks if the device is reachable.<br>
|
## 🪟 Windows Client Notes
|
||||||
You can expand the command chain as follows:<br>
|
|
||||||
|
* 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`](./examples/windows).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔎 OS & Tag Filtering
|
||||||
|
|
||||||
|
### Filter by OS
|
||||||
|
|
||||||
|
You can limit commands to specific OS types:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
target_os: "Linux" # As defined in os_categories.json
|
||||||
|
```
|
||||||
|
|
||||||
|
See [docs/operating\_system\_filtering.md](./docs/operating_system_filtering.md) for details.
|
||||||
|
|
||||||
|
### Filter by Tag
|
||||||
|
|
||||||
|
You can also filter using MeshCentral tags:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
target_tag: "Production"
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⚠️ Tag values are **case-sensitive**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Example Playbook
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: Echo a string to the terminal through the meshbook example.
|
name: Echo OS Info
|
||||||
group: "Dev"
|
group: "Dev"
|
||||||
#target_os: "Linux" # <--- according to os_categories.json
|
target_os: "Linux"
|
||||||
variables:
|
variables:
|
||||||
- name: file
|
- name: file
|
||||||
value: "/etc/os-release"
|
value: "/etc/os-release"
|
||||||
tasks:
|
tasks:
|
||||||
- name: Echo!
|
- name: Show contents of os-release
|
||||||
command: "echo $(cat {{ file }})"
|
command: "echo $(cat {{ file }})"
|
||||||
```
|
```
|
||||||
|
|
||||||
The following response it received when executing the first yaml of the above files (without the `-s` parameters, which just outputs the below JSON).
|
Sample output:
|
||||||
|
|
||||||
```shell
|
```json
|
||||||
$ python3 meshbook.py -mb books/aggregate_example.yaml -i --nograce -pr
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
meshbook: books/aggregate_example.yaml
|
|
||||||
Operating System Categorisation file: ./os_categories.json
|
|
||||||
Configuration file: ./config.conf
|
|
||||||
Target Operating System category given: Linux
|
|
||||||
Target group: Systemec Development
|
|
||||||
Grace: False
|
|
||||||
Silent: False
|
|
||||||
----------------------------------------
|
|
||||||
Trying to load the MeshCentral account credential file...
|
|
||||||
Trying to load the meshbook yaml file and compile it into something workable...
|
|
||||||
Trying to load the Operating System categorisation JSON file...
|
|
||||||
Connecting to MeshCentral and establish a session using variables from previous credential file.
|
|
||||||
Generating group list with nodes and reference the targets from that.
|
|
||||||
----------------------------------------
|
|
||||||
Executing playbook on the target(s): Development.
|
|
||||||
----------------------------------------
|
|
||||||
1. Running: Ping!
|
|
||||||
----------------------------------------
|
|
||||||
{
|
{
|
||||||
"Task 1": {
|
"Task 1": {
|
||||||
"task_name": "Ping Quad9 DNS",
|
"task_name": "Show contents of os-release",
|
||||||
"data": [
|
"data": [
|
||||||
{
|
{
|
||||||
"complete": true,
|
"command": "echo $(cat /etc/os-release)",
|
||||||
"result": [
|
"result": [
|
||||||
"PING 9.9.9.9 (9.9.9.9) 56(84) bytes of data.",
|
"NAME=\"Ubuntu\"",
|
||||||
"64 bytes from 9.9.9.9: icmp_seq=1 ttl=61 time=26.8 ms",
|
"VERSION=\"22.04.4 LTS (Jammy Jellyfish)\""
|
||||||
"--- 9.9.9.9 ping statistics ---",
|
],
|
||||||
"1 packets transmitted, 1 received, 0% packet loss, time 0ms",
|
"complete": true,
|
||||||
"rtt min/avg/max/mdev = 26.809/26.809/26.809/0.000 ms"
|
"device_name": "dev-host1"
|
||||||
],
|
}
|
||||||
"command": "ping 9.9.9.9 -c 1",
|
|
||||||
"device_id": "yourn nodeip",
|
|
||||||
"device_name": "yournodename"
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
The above without `-s` is quite verbose. use `--help` to read about parameters and getting a minimal response for example.
|
|
||||||
|
|
||||||
# Important Notice:
|
---
|
||||||
|
|
||||||
If you want to use this, make sure to use `NON-BLOCKING` commands. MeshCentral does not work if you send it commands that wait.<br>
|
## ⚠️ Blocking Commands Warning
|
||||||
A couple examples of `BLOCKING COMMANDS` which will never get back to the main MeshCentral server, and Meshbook will quit after the timeout but the agent will not come back:
|
|
||||||
|
|
||||||
```shell
|
Avoid using commands that **block indefinitely** — MeshCentral requires **non-blocking** execution.
|
||||||
apt upgrade # without -y.
|
|
||||||
|
|
||||||
|
🚫 Examples of bad (blocking) commands:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt upgrade # Without -y
|
||||||
sleep infinity
|
sleep infinity
|
||||||
|
ping 1.1.1.1 # Without -c
|
||||||
ping 1.1.1.1 # without a -c flag (because it pings forever).
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
✅ Use instead:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt upgrade -y
|
||||||
|
ping 1.1.1.1 -c 1
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Check Python Environment
|
||||||
|
|
||||||
|
Sometimes the wrong Python interpreter or environment is used. To verify:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 -m pip list
|
||||||
|
pip3 list
|
||||||
|
```
|
||||||
|
|
||||||
|
The lists should match. If not, make sure the correct environment is activated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📂 Project Structure (excerpt)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
This project is licensed under the terms of the MIT License. See [LICENSE](./LICENSE).
|
||||||
|
|||||||
Reference in New Issue
Block a user