52 lines
2.9 KiB
Plaintext
52 lines
2.9 KiB
Plaintext
[#entities]
|
|
= Entities
|
|
|
|
An entity is something that exists - a "thing", like a VM, or a Container is an entity. OliveTin allows you to then dynamically generate actions based around these entities.
|
|
|
|
This is really useful if you want to generate wake on lan or poweroff actions for `server` entities, for example.
|
|
|
|
A very popular use case that entities were designed for was for `container` entities - in a similar way you could generate `start`, `stop`, and `restart` container actions.
|
|
|
|
Entities are just loaded from files on disk, OliveTin will also watch these files for updates while OliveTin is running, and update entities.
|
|
|
|
Entity data files can contain any fields you need. Those values are available in action templates as `{{ .CurrentEntity.field }}` — for example, `{{ .CurrentEntity.status }}` or `{{ .CurrentEntity.hostname }}`.
|
|
|
|
Entity field values are **not** sanitized for shell safety. If you substitute them into `shell` or `shellAfterCompleted`, OliveTin assumes the entity files are server-controlled and that you accept responsibility for that data. See xref:action_execution/shellvsexec.adoc#shell-entity-env-trust[Entity and .Env values are not shell-sanitized].
|
|
|
|
To control which fields appear in the Entities page table and entity details view, configure `properties` on the entity definition in `config.yaml`. See xref:entities/properties.adoc[Entity properties] for details.
|
|
|
|
To restrict which users may see an entity type (list, details, search, and related UI), list `acls` on the entity definition. See xref:security/acl.adoc#acls[Access Control Lists] (Entities section). Entity types with no `acls` stay unrestricted.
|
|
|
|
[source,yaml]
|
|
----
|
|
entities:
|
|
- file: /etc/OliveTin/containers.json
|
|
name: container
|
|
|
|
- file: /etc/OliveTin/servers.yaml
|
|
name: server
|
|
icon: ssh
|
|
acls:
|
|
- ops
|
|
properties:
|
|
- name: hostname
|
|
title: Hostname
|
|
- name: ip
|
|
title: IP
|
|
----
|
|
|
|
Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards].
|
|
|
|
== What's Next?
|
|
|
|
Now that you understand entities, here's how to use them effectively:
|
|
|
|
* xref:entities/properties.adoc[Configure entity properties] - Choose which fields appear in the UI and API
|
|
* xref:entities/icons.adoc[Configure entity icons] - Set an icon for each entity type
|
|
* xref:entities/yaml.adoc[Create YAML entity files] - Learn the YAML format for entity files
|
|
* xref:entities/json.adoc[Create JSON entity files] - Learn the JSON format for entity files
|
|
* xref:entities/examples.adoc[View entity examples] - See complete examples of entity configurations
|
|
* xref:dashboards/intro.adoc[Use entities in dashboards] - Combine entities with dashboards for dynamic action generation
|
|
* xref:solutions/container-control-panel/index.adoc[Container control panel solution] - See a complete example using container entities
|
|
* xref:solutions/systemd-control-panel/index.adoc[Systemd control panel solution] - See a complete example using systemd entities
|