mirror of
https://gitlab.com/fabinfra/fabaccess/docs.git
synced 2024-08-23 22:30:44 +02:00
232 lines
5.8 KiB
Markdown
232 lines
5.8 KiB
Markdown
# bffh.dhall
|
|
|
|
BFFH uses [DHALL](https://dhall-lang.org/) for Config-File structure
|
|
BFFH uses [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) for access control
|
|
|
|
BFFH Config is in `bffh.dhall` file.
|
|
## General BFFH Config
|
|
### `listens`
|
|
Contains the Addresses BFFH is listen for Connection for the API
|
|
Default Port for BFFH is `59661`
|
|
|
|
**Example:**
|
|
```
|
|
listens =
|
|
[
|
|
{ address = "127.0.0.1", port = Some 59661 }
|
|
]
|
|
```
|
|
|
|
### `mqtt_url`
|
|
Contains the Address for the MQTT Server BFFH connects to
|
|
**Example:**
|
|
```
|
|
mqtt_url = "tcp://localhost:1883"
|
|
```
|
|
|
|
### `db_path`
|
|
Contains the Path for the internal Database BFFH uses.
|
|
BFFH will create two files: `<db_path>` and `<db_path>-lock`.
|
|
Make sure that BFFH has write access in the relevant directory
|
|
**Example:**
|
|
```
|
|
db_path = "/tmp/bffh"
|
|
```
|
|
|
|
## Permissions
|
|
---
|
|
BFFH uses a Path-style string as permission format, separated by ".".
|
|
So for example `this.is.a.permission` consists of the parts `this`, `is`, `a` and `permission`.
|
|
When requireing permissions, such as in machines you always need to give an exact permission, so for example `test.write`.
|
|
When granting permissions, such as in roles you can either give an exact permission or you can use the two wildcards `*` and `+`.
|
|
These wildcards behave similar to regex or bash wildcards:
|
|
- `*` grants all permissions in that subtree.
|
|
So, `perms.read.*` will match for any of:
|
|
- `perms.read`
|
|
- `perms.read.machineA`
|
|
- `perms.read.machineB`
|
|
- `perms.read.machineC.manage`
|
|
- `+` grants all permissions below that one.
|
|
So, `perms.read.+` will match for any of:
|
|
- `perms.read.machineA`
|
|
- `perms.read.machineB`
|
|
- `perms.read.machineC.manage`
|
|
- **but not** `perms.read`
|
|
|
|
Wildcards are probably most useful if you group you machines around them, e.g. your 3D-printers and your one bandsaw require:
|
|
|
|
1. Write permissions
|
|
- `machines.printers.write.prusa.sl1`
|
|
- `machines.printers.write.prusa.i3`
|
|
- `machines.printers.write.anycubic`
|
|
- `machines.bandsaws.write.bandsaw1`
|
|
1. Manage permissions
|
|
- `machines.printers.manage.prusa.sl1`
|
|
- `machines.printers.manage.prusa.i3`
|
|
- `machines.printers.manage.anycubic`
|
|
- `machines.bandsaws.manage.bandsaw1`
|
|
1. Admin permissions
|
|
- `machines.printers`
|
|
* For all printers
|
|
- `machines.bandsaws`
|
|
* For all bandsaws
|
|
|
|
And you then give roles permissions like so:
|
|
|
|
* Use any 3D printer:
|
|
* `machines.printers.write.+`
|
|
* Only allow use of the "cheap" printers
|
|
* `machines.printers.write.anycubic.*`
|
|
* `machines.printers.write.prusa.i3`
|
|
* Allow managing of printers:
|
|
* `machines.printers.+`
|
|
* Allow administrating printers:
|
|
* `machines.printers.*`
|
|
|
|
This way if you buy a different anycubic and split the permissions to e.g.
|
|
|
|
- `machines.printers.write.anycubic.i3`
|
|
- `machines.printers.write.anycubic.megax`
|
|
|
|
It still works out.
|
|
|
|
|
|
## Machine Config
|
|
|
|
### `machines`
|
|
Contains list of machines
|
|
|
|
Machines have different perission levels to interact with:
|
|
* disclose: User can see the machine in machine list
|
|
* read: User can read information about the machine and there state
|
|
* write: User can use the machine
|
|
* manage: User can interact with the machine as Manager (Check, ForceFree, ForceTransfer)
|
|
|
|
Each machine must have an ID to reference the machine in other part of this config or over the API.
|
|
And each machine must have a name.
|
|
|
|
#### Optional Information
|
|
To provide more information about the machine you can add it to the description or provid an external wiki link.
|
|
Both attributes are only optional and do not need to be set.
|
|
|
|
**Example:**
|
|
```
|
|
machines =
|
|
{
|
|
machine123 =
|
|
{
|
|
name = "Testmachine",
|
|
description = Some "A test machine",
|
|
wiki = "https://someurl"
|
|
|
|
disclose = "lab.test.read",
|
|
read = "lab.test.read",
|
|
write = "lab.test.write",
|
|
manage = "lab.test.admin"
|
|
}
|
|
}
|
|
```
|
|
"machine123" is in this case the "Machine-ID"
|
|
|
|
## Roles Config
|
|
|
|
The roles are configured in the bffh.dhall. If the file "roles.toml" is existing in the directory, it can be deleted and can't be used to manage roles.
|
|
|
|
### `roles`
|
|
Contains list of roles
|
|
|
|
Roles have a list of permission and can be inherited.
|
|
Permission can be wildcard in permission list.
|
|
|
|
**Example:**
|
|
```
|
|
roles =
|
|
{
|
|
testrole =
|
|
{
|
|
permissions = [ "lab.test.*" ]
|
|
},
|
|
somerole =
|
|
{
|
|
parents = ["testparent"],
|
|
permissions = [ "lab.some.admin" ]
|
|
},
|
|
testparent =
|
|
{
|
|
permissions =
|
|
[
|
|
"lab.some.write",
|
|
"lab.some.read",
|
|
"lab.some.disclose"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Actors Config
|
|
|
|
### `actors`
|
|
Contains list of actors
|
|
Actors are defined by a module and one or more paramters
|
|
|
|
Currenty supported actors:
|
|
#### `Shelly Actor`
|
|
This actor connects BFFH over an MQTT-Server to an shelly device.
|
|
|
|
You need to set the `topic` parameter of the Shelly to the Shelly specific MQTT-Topic.
|
|
|
|
[Find shelly topic here](https://shelly-api-docs.shelly.cloud/gen1/#shelly-plug-plugs-overview)
|
|
|
|
**Example:**
|
|
```
|
|
actors =
|
|
{
|
|
Shelly_123 =
|
|
{
|
|
module = "Shelly",
|
|
params =
|
|
{
|
|
topic = "shellyplug-s-123456"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
"Shelly_123" is in this case the "Actor-ID".
|
|
|
|
#### `Process Actor`
|
|
This actor makes it possible for you to connect your own Devices to BFFH.
|
|
|
|
`cmd` = Path of executable
|
|
|
|
`args` = Arguments for executable
|
|
|
|
**Example:**
|
|
```
|
|
actors =
|
|
{
|
|
Bash =
|
|
{
|
|
module = "Process", params =
|
|
{
|
|
cmd = "./examples/actor.sh",
|
|
args = "your ad could be here"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `actor_connections`
|
|
Connects the actor with a machine
|
|
A machine can have multiple actors
|
|
|
|
Use the "Machine-ID" and "Actor-ID".
|
|
**Example:**
|
|
```
|
|
actor_connections =
|
|
[
|
|
{ machine = "Testmachine", actor = "Shelly_1234" },
|
|
{ machine = "Another", actor = "Bash" },
|
|
{ machine = "Yetmore", actor = "Bash2" }
|
|
]
|
|
```
|