Skip to content

Sylve

Build Status Last Commit

Modern, open-source management platform for FreeBSD managing Virtual Machines (Bhyve), Jails, and ZFS storage.

What is Sylve?

Sylve is a modern, open-source management platform for FreeBSD: Bhyve VMs, jails, ZFS, and networking behind one web UI. It manages the host from inside its own jail, so it needs host access a normal container never gets -- kernel modules, devfs entries like /dev/pf and /dev/vmm, ZFS delegation, and allow.vmm. Both deploy methods below wire that up for you.

Version Tags

Both tags ship Sylve's prebuilt native-FreeBSD binary from a GitHub release; they differ only in which release they track.

Tag Description Best For
latest The latest tagged release (AlchemillaHQ/Sylve). Most deployments.
nightly The rolling tip release, tracking upstream master. Early access to unreleased fixes.

Prerequisites

Requirements:

  • FreeBSD 15+ and root
  • A ZFS pool (a sylve dataset gets delegated to the jail)
  • AppJail path: appjail 5.4+, sysutils/py-director -- Podman path: podman, ocijail, podman-compose

Deploy

Experimental

Both the Podman and AppJail deployments of Sylve are experimental on our end.

load-kld hook is required

load-kld hook is required for the kernel-module handling this deployment relies on.

  1. Be sure to set HOOKSDIR in your appjail.conf(5) file. 
    1
2
    $ grep '^HOOKSDIR' /usr/local/etc/appjail/appjail.conf
HOOKSDIR=/usr/local/etc/appjail/hooks
  2. Create the hooks directory if it does not exist. 
    1
    $ mkdir -p /usr/local/etc/appjail/hooks/pre.d/
  3. Install the load-kld hook and set the execute bit. 
    1
2
    $ fetch -o /usr/local/etc/appjail/hooks/pre.d/load-kld.sh https://github.com/DtxdF/AppJail/blob/main/share/examples/appjail/hooks/pre.d/load-kld.sh
$ chmod +x /usr/local/etc/appjail/hooks/pre.d/load-kld.sh

1. Prepare the host (one time). Kernel modules are loaded automatically at jail start via load-kld labels; only the boot-only kern.racct tunable touches loader.conf:

1
2
3
4
pkg install -y appjail sysutils/py-director
[ "$(sysctl -n kern.racct.enable)" = "1" ] || echo 'kern.racct.enable="1"' >> /boot/loader.conf
# reboot if `sysctl -n kern.racct.enable` is still 0 (Sylve requires racct)
sysrc appjail_enable=YES

2. Save as .env:

1
2
3
# Host path for Sylve's data
SYLVE_DATA_LOCATION=/var/appjail-volumes/sylve/data
DIRECTOR_PROJECT=sylve

3. Save as appjail-director.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
options:
  # Equivalent to 'network_host: host'.
  # Use it only if you don't have problems with Sylve managing your pf(4).
  #- alias:
  #- ip4_inherit:
  #
  # The jail will use its own network stack without touching with the host's;
  # in addition, AppJail will configure an IPv4 address that you can use to
  # communicate with Sylve via the jail's IPv4 address or hostname (if you
  # have enabled DNS in AppJail).
  - virtualnet: ':<random> default'
  - nat:
services:
  sylve:
    name: sylve
    options:
      - from: ghcr.io/daemonless/sylve:nightly
      - template: !ENV '${PWD}/sylve-template.conf'
      - container: 'args:--pull'
      - label: 'load-kld:1'
      - label: 'load-kld.load-vmm:vmm'
      - label: 'load-kld.load-if-bridge:if_bridge'
      - label: 'load-kld.load-cryptodev:cryptodev'
      - label: 'load-kld.load-if-epair:if_epair'
      - label: 'load-kld.load-nullfs:nullfs'
      - label: 'load-kld.load-netlink:netlink'
      - label: 'load-kld.load-nlsysevent:nlsysevent'
      - label: 'load-kld.load-nmdm:nmdm'
      - label: 'load-kld.load-pf:pf'
      - label: 'load-kld.load-pflog:pflog'
      - label: 'load-kld.load-if-wg:if_wg'
      - label: 'load-kld.load-linux:linux'
      - label: 'load-kld.load-linux.module:linuxelf'
      - label: 'load-kld.load-linux64:linux64'
      - label: 'load-kld.load-linux64.module:linux64elf'
      - label: 'load-kld.load-pty:pty'
      - label: 'load-kld.load-linprocfs:linprocfs'
      - label: 'load-kld.load-linsysfs:linsysfs'
      - label: 'load-kld.load-ctl:ctl'
      - label: 'load-kld.load-iscsi:iscsi'
      - device: 'include $devfsrules_hide_all'
      - device: 'include $devfsrules_unhide_basic'
      - device: 'include $devfsrules_unhide_login'
      - device: 'include $devfsrules_jail'
      - device: 'include $devfsrules_jail_vnet'
      - device: 'path zfs unhide'
      - device: 'path zvol unhide'
      - device: "path 'zvol/*' unhide"
      - device: "path 'zvol/*/*' unhide"
      - device: "path 'zvol/*/*/*' unhide"
      - device: "path 'zvol/*/*/*/*' unhide"
      - device: "path 'zvol/*/*/*/*/*' unhide"
      - device: 'path shm unhide'
      - device: 'path pf unhide'
      - device: 'path pflog unhide'
      - device: 'path bpf unhide'
      - device: "path 'bpf*' unhide"
      - device: 'path vmm unhide'
      - device: "path 'vmm/*' unhide"
      - device: 'path vmm.io unhide'
      - device: "path 'vmm.io/*' unhide"
      - device: 'path vmmctl unhide'
      - device: "path 'nmdm*' unhide"
      - device: "path 'tap*' unhide"
      - device: 'path mem unhide'
      - device: 'path kmem unhide'
      - device: 'path pci unhide'
      - device: 'path io unhide'
      - device: 'path cam unhide'
      - device: "path 'cam/ctl' unhide"
      - device: "path 'da*' unhide"
      - device: "path 'ada*' unhide"
      - device: "path 'nda*' unhide"
      - device: "path 'pass*' unhide"
      - device: "path 'xpt*' unhide"
      - device: "path 'nvme*' unhide"
      - device: 'path iscsi unhide'
    volumes:
      - sylve-data: /var/db/sylve
volumes:
  sylve-data:
    device: !ENV '${SYLVE_DATA_LOCATION}'

4. Save as sylve-template.conf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# EDIT: the ZFS dataset created during host prep
${dataset}: zroot/sylve
# Number of child jails allowed to be created by this jail.
${children_max}: 100

exec.start: "/bin/sh /etc/rc"
exec.stop: "/bin/sh /etc/rc.shutdown jail"
mount.devfs
persist
allow.vmm
allow.vmm_ppt
stop.timeout: 30
allow.chflags
allow.raw_sockets
allow.routing
allow.nfsd
allow.unprivileged_proc_debug
enforce_statfs: 1
allow.mount
allow.mount.devfs
allow.mount.fdescfs
allow.mount.linprocfs
allow.mount.linsysfs
allow.mount.tmpfs
allow.mount.zfs
zfs.mount_snapshot
children.max: ${children_max}
allow.socket_af
allow.sysvipc
allow.reserved_ports
allow.set_hostname
allow.suser
exec.created+: "zfs create -p -o jailed=on ${dataset}"
exec.created+: "zfs jail ${name} ${dataset}"
exec.created+: "jexec -l ${name} zfs list -t fs -Hro name ${dataset} | xargs -L 1 jexec -l ${name} zfs mount"
exec.prestop+: "jexec -l ${name} zfs list -t fs -Hro name ${dataset} | tail -r | xargs -L 1 jexec -l ${name} zfs umount"
exec.clean

5. Save as Makejail:

1
2
OPTION container=boot
OPTION overwrite=force

6. Create the data directory and deploy:

1
appjail-director up

1. Prepare the host (one time). Generate the setup script, review it, then run it -- it loads the kernel modules, adds a devfs ruleset, creates the ZFS dataset, and installs the OCI createRuntime hook (ocijail can't express devfs rulesets or ZFS delegation through annotations). Each step asks before running; already-configured steps are skipped:

1
2
3
podman run --rm ghcr.io/daemonless/sylve:latest host-setup > sylve-setup.sh
less sylve-setup.sh          # review exactly what it will change
sh sylve-setup.sh            # or: sh sylve-setup.sh -y

If it reports that kern.racct needs a reboot, reboot before continuing (Sylve requires it).

2. Create the deployment files. init writes compose.yaml and .env into the current directory (it refuses to overwrite existing files without --force):

1
2
podman run --rm -v "$PWD:/out" ghcr.io/daemonless/sylve:latest init
vi .env

3. Start:

1
2
mkdir -p "$SYLVE_DATA_LOCATION"   # FreeBSD won't auto-create a bind-mount source
podman compose up -d

Access Sylve at: https://your-host:8181 (first login: admin / admin)

Environment Variables

Variable Default Description
SYLVE_HOSTNAME -- The jail's hostname (node-identity check). Podman: hostname: in compose.yaml.
SYLVE_DATA_LOCATION -- Host path for Sylve's data (/var/db/sylve in the jail).
SYLVE_DATASET zroot/sylve ZFS dataset delegated to Sylve. AppJail: ${dataset} in sylve-template.conf.
TZ System default Timezone.

Ports

Port Service Description
8181 sylve Web UI (HTTPS)

Network Mode

The Podman path shares the host network (network_mode: host) so Sylve manages the host's interfaces, firewall, and VMs directly. The AppJail path defaults to its own vnet + NAT to avoid clobbering the host's pf(4) rules -- uncomment alias/ip4_inherit in appjail-director.yml for host networking instead.

FreeBSD-Specific Notes

selected_node_not_found

If requests fail with selected_node_not_found, Sylve's EnsureCorrectHost check is comparing its configured hostname against the one you're browsing to -- set the jail's hostname to the name you reach it at.

Never bind-mount /dev

A nullfs /dev (-v /dev:/dev) makes Bhyve guest-memory mmap fail with ENXIO (Unable to setup memory (6)) -- VM creation succeeds but the guest never boots. Both deploy methods mount a real devfs via a ruleset; don't override it.

Undo (Podman host-setup)

sh sylve-setup.sh --undo removes Sylve's OCI hook and devfs ruleset. It never touches your ZFS dataset (it prints the zfs destroy command if you want it gone).
Registry ghcr.io/daemonless/sylve
Upstream https://github.com/AlchemillaHQ/Sylve
Website https://sylve.io