95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
# vesperprofiled-config-schema
|
|
|
|
Schema definitions package for VesperOS configuration profiles.
|
|
|
|
Installed at `/usr/share/vesperprofiled/schema/profile.schema.yml`.
|
|
|
|
---
|
|
|
|
## What this package does
|
|
|
|
`vesperprofiled` reads this schema at startup to determine which payload types and fields are valid for the current installation. Any `.vconfig` profile containing a payload type not listed in `allowed-payload-types` will be **rejected at install time** with a clear error.
|
|
|
|
Shipping the schema separately from the daemon means:
|
|
|
|
- **Independent updates** — schema additions (new payload types, new optional fields) don't require rebuilding or reflashing the daemon binary.
|
|
- **OEM restriction** — OEMs building VesperOS-based products can ship a trimmed schema that only exposes the configuration surface their platform supports. A digital signage OEM might allow only `wifi`, `cert`, `kiosk`, and `mdm`. An enterprise desktop OEM might allow everything except `kiosk` and `asam`.
|
|
- **Schema versioning** — the `schema-version` field is checked by the daemon at startup. A newer daemon with an older schema is always fine. An older daemon with a newer schema logs a warning and falls back to its compiled-in defaults.
|
|
|
|
---
|
|
|
|
## OEM customisation
|
|
|
|
To restrict available payload types, create a replacement Debian package:
|
|
|
|
**1. Copy and trim the schema**
|
|
|
|
```bash
|
|
cp /usr/share/vesperprofiled/schema/profile.schema.yml \
|
|
my-schema/profile.schema.yml
|
|
|
|
# Edit my-schema/profile.schema.yml:
|
|
# - Remove payload type entries from allowed-payload-types
|
|
# - Remove their blocks from the payloads: section
|
|
# - Bump schema-version if you consider this a new schema variant
|
|
```
|
|
|
|
**2. Create your package**
|
|
|
|
`debian/control`:
|
|
```
|
|
Package: my-vesperos-config-schema
|
|
Architecture: all
|
|
Depends: ${misc:Depends}
|
|
Provides: vesperprofiled-config-schema
|
|
Conflicts: vesperprofiled-config-schema
|
|
Replaces: vesperprofiled-config-schema
|
|
Description: Trimmed VesperOS profile schema for My Product
|
|
Only allows: wifi, cert, mdm, kiosk, passcode, restrictions.
|
|
```
|
|
|
|
`debian/rules`:
|
|
```makefile
|
|
#!/usr/bin/make -f
|
|
%:
|
|
dh $@
|
|
override_dh_auto_install:
|
|
install -Dm 0644 profile.schema.yml \
|
|
debian/my-vesperos-config-schema/usr/share/vesperprofiled/schema/profile.schema.yml
|
|
```
|
|
|
|
**3. Add to your product package list**
|
|
|
|
```makefile
|
|
# In your VesperOS device makefile or product.mk:
|
|
PRODUCT_PACKAGES += my-vesperos-config-schema
|
|
```
|
|
|
|
Because your package `Provides: vesperprofiled-config-schema` and `Conflicts: vesperprofiled-config-schema`, `apt` will automatically use yours in place of the default when both are available.
|
|
|
|
---
|
|
|
|
## Schema versioning
|
|
|
|
The `schema-version` field in the YAML file follows `MAJOR.MINOR.PATCH`:
|
|
|
|
- **PATCH** — non-breaking: new optional fields added to existing payload types.
|
|
- **MINOR** — new payload types added to `allowed-payload-types`. Older daemons that don't know the new type will accept profiles containing it but log a warning and skip the unknown payload.
|
|
- **MAJOR** — breaking: required fields renamed, payload types removed, or semantics changed. Daemons older than this MAJOR version must not run with a schema of a higher MAJOR version.
|
|
|
|
---
|
|
|
|
## Building the package
|
|
|
|
```bash
|
|
dpkg-buildpackage -us -uc -b -A # Architecture: all, no signing
|
|
```
|
|
|
|
---
|
|
|
|
## Files installed
|
|
|
|
```
|
|
/usr/share/vesperprofiled/schema/profile.schema.yml
|
|
```
|