diff --git a/README.md b/README.md index 9709afc..d48fa79 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,3 @@ -> [!NOTE] -> *If you experience issues or have suggestions, submit an issue! https://github.com/DaanSelen/meshbook/issues I'll respond ASAP!* - # Meshbook A way to programmatically manage MeshCentral-managed machines, a bit like Ansible does.
@@ -11,10 +8,15 @@ And many people will be comfortable with YAML configurations! It's almost like J The quickest way to start is to grab a template from the templates folder in this repository.
Make sure to correctly pass the MeshCentral websocket API as `wss:///control.ashx`.
-And make sure to fill in the credentails of an account which has remote commands permissions.
+And make sure to fill in the credentails of an account which has `Remote Commands` permissions and `Device Details` permissions on the targeted devices or groups.
+ +> I did this through a "Global Service" group which I added the meshbook account to! + 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.
To install, follow the following commands:
+### Linux setup: + ```shell git clone https://github.com/daanselen/meshbook cd ./meshbook @@ -22,15 +24,84 @@ python3 -m venv ./venv source ./venv/bin/activate pip3 install -r ./meshbook/requirements.txt ``` + +### Windows setup: + +```shell +git clone https://github.com/daanselen/meshbook +cd ./meshbook +python3 -m venv ./venv +.\venv\Scripts\activate # Make sure to check the terminal prefix. +pip3 install -r ./meshbook/requirements.txt +``` + Now copy the configuration template from ./templates and fill it in with the correct details. The url should start with `wss://` and end in `control.ashx`.
After this you can use meshbook, for example: + +### Linux run: + ```shell -python3 ./meshbook/meshbook.py -pb examples/echo.yaml +python3 .\meshbook\meshbook.py -pb .\examples\echo.yaml ``` +### Windows run: + +```shell +.\venv\Scripts\python.exe .\meshbook\meshbook.py -pb .\examples\echo.yaml +``` + +### How to check if everything is okay? + +The python virtual environment can get messed up, therefor...
+To check if everything is in working order, make sure that the lists from the following commands are aligned: + +``` +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? + +This paragraph explains how the program interprets certain information. + +### Targeting: + +MeshCentral has `meshes` or `groups`, in this program they are called `companies`. Because of the way I designed this.
+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 +--- +name: example configuration +company: "Nerthus" +variables: + - name: var1 + value: "This is the first variable" +tasks: + - name: echo the first variable! + command: 'echo "{{ var1 }}"' +``` + +It is also possible to target a single device, as seen in: [here](./examples/echo.yaml).
+ +### Variables: + +Variables are done by replacing the placeholders just before the runtime.
+So if you have var1 declared, then the value of that declaration is placed wherever it finds {{ var1 }}.
+This is done to imitate popular methods. See below [from the example](./examples/variable_example.yaml).
+ +### Tasks: + +The tasks you want to run should be contained under the `tasks:` with two fields, `name` and `command`.
+The name field is for the user of meshbook, to clarify what the following command does in a summary.
+The command field actually gets executed on the end-point.
+ # Example: -For the example, I used the following yaml file: +For the example, I used the following yaml file (you can find more in [this directory](./examples/)): The below group: `Temp-Agents` has four devices, of which one is offline.
You can expand the command chain as follows:
@@ -56,7 +127,7 @@ tasks: command: "{{ command1 }} {{ host2 }} {{ cmd_arguments }}" ``` -The following response it received when executing the first yaml of the above files. +The following response it received when executing the first yaml of the above files (with the `-s` and the `-i` parameters). ```shell python3 meshbook/meshbook.py -pb examples/variable_example.yaml -si