--- title: Declare services with smf.services, not hand-imported manifests area: smf impact: HIGH tags: [smf, services, manifest, svccfg, activation, fmri] verified: 2026-11-04 --- # Declare services with smf.services, not hand-imported manifests On Solnix a service is an `smf.services.` declaration, which the build renders into an SMF manifest that activation imports and enables. A manifest you `svccfg import` by hand lives only in the repository of the running boot environment and of BEs later cloned from it. Your configuration does not record it, so a fresh install from that configuration lacks it, and a rollback to a BE made before the import loses it. **Antipattern** ```sh # illumos habit: a hand-written manifest imported into the live repository pfexec svccfg import /var/svc/manifest/site/myapp.xml pfexec svcadm enable svc:/site/myapp:default # NixOS habit: evaluates without error and does nothing (systemd.* is an ignored compat stub) # systemd.services.myapp = { ... }; ``` **The Solnix way** ```nix # configurations/base.nix declares svc:/network/sshd:default the same way smf.services.myapp = { # the attribute name is the service name in the FMRI enable = true; # defaults to false; false: no manifest, activation runs svcadm disable category = "site"; # -> svc:/site/myapp:default (category defaults to "system") instance = "default"; # the : part; "default" is the default description = "My application"; model = "contract"; # startd/duration: contract (default) | transient | wait requires = [ "svc:/milestone/network:default" "svc:/system/filesystem/local:default" ]; start.exec = "${myapp}/bin/myappd &"; # start must return: background a foreground daemon, as nix.nix does start.timeoutSeconds = 60; # the default; 0 = no timeout stop.exec = ":kill"; # the default; use ":true" for a transient service user = "myapp"; # method_credential/user; defaults to root ignoreError = [ "core" "signal" ]; # only if a core dump, or a kill from outside the service, must not fail it properties.config.port = "8080"; # application property group; every value is an astring }; # Then: pfexec solnix-rebuild switch (builds the flake in /etc/nixos for #$(hostname), or pass --flake #; with # neither, switch re-activates the newest registered generation and builds nothing) # Activation: svccfg apply the site profile; svccfg import each generated manifest; svcadm enable or # disable every smf.services entry; svcadm milestone multi-user-server. Every step ends in `|| true`. ``` `contract` is a daemon that stays in its process contract; `transient` is a run-once job whose start method exits 0; `wait` should select svc.startd's wait model (a child restarted whenever it exits; see Unverified). Each generated manifest is checked with `xmllint --dtdvalid` against `service_bundle.dtd.1` during the build, so a malformed one fails the build, not the boot. **The illumos way** (OpenIndiana, OmniOS, SmartOS) ```sh # write the manifest (format: service_bundle(5)), check it, import it, enable it svccfg validate /var/svc/manifest/site/myapp.xml pfexec svccfg import /var/svc/manifest/site/myapp.xml pfexec svcadm enable svc:/site/myapp:default ``` At boot `svc:/system/manifest-import:default` also imports new or changed manifests. Once imported, the repository (changed with `svccfg` and `svcadm`) is the live configuration and the file is only its seed. **The difference.** Underneath it is the same: Solnix's activation runs the same `svccfg import` and `svcadm`. What changes is the source of truth: Solnix re-imports the manifests rendered from your configuration on every switch, while illumos treats the repository as the configuration. To stop a service, set `enable = false`. Deleting the attribute leaves the service in place on a live switch ("Removal-on-switch deferred to P2.1"), and the new BE may inherit it too (see Unverified). **Check.** `svcs -l svc:/site/myapp:default` shows `enabled true` and `state online`. If it shows `(temporary)` after a switch, see smf-temporary-vs-persistent.md (Unverified: what the activation's `svcadm milestone` does to it). **Unverified** - Whether a deleted service ever goes away. install-be leaves its manifest out of the new BE, but `svccfg cleanup` skips a service whose recorded manifest is a store path, and activation imports from the toplevel's store path. install-be.sh records a private-repository test (a manifest dir linked into the store "kept a removed service forever"; real copies dropped it), and xml.nix records a test host deleting a dropped service at import after one more run. Neither is a live switch that drops a service. Set `enable = false` instead of deleting the attribute. - `model = "wait"`: the option accepts it, but svc.startd(8) calls this model `child` (`child also known as "wait"`), design-smf-init.md §7 still lists confirming the value as open, and no module in the OS repo uses it. **Sources** - [Handbook: SMF](https://solnix.io/docs/handbook/smf#how-solnix-manages-services) (site 307b67f), How Solnix manages services; Manifests and method scripts - [modules/system/boot/init/smf.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/modules/system/boot/init/smf.nix) (solnix 5a8e5ce), options category, instance, model, start, stop, user, ignoreError, properties, fmri; the xmllint DTD gate - [modules/system/activation/default.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/modules/system/activation/default.nix) (solnix 5a8e5ce), the `activate` script (steps 1-4, `|| true`), "Removal-on-switch deferred to P2.1" - [modules/system/activation/install-be.sh](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/modules/system/activation/install-be.sh) (solnix 5a8e5ce), step 5: per-BE /var/svc/manifest/site/solnix and `svccfg cleanup` ("Measured with a private repository") - [lib/smf/xml.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/lib/smf/xml.nix) (solnix 5a8e5ce), importDep comment (a dropped service ran once more, then import deleted it) - [modules/nixos-compat.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/modules/nixos-compat.nix) (solnix 5a8e5ce), `systemd.services` "IGNORED compat stub" - [modules/config/nix.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/modules/config/nix.nix) (solnix 5a8e5ce), `smf.services.nix-daemon` (`--daemon &`, `ignoreError`) - [configurations/base.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/configurations/base.nix) (solnix 5a8e5ce), `smf.services.sshd` - [docs/design-generations.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-generations.md) (solnix 5a8e5ce), §4 GATE A (a declared service online after a live switch) - [docs/design-smf-init.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-smf-init.md) (solnix 5a8e5ce), §1.2 field to SMF mapping, §7 open items - [svc.startd(8)](https://solnix.io/docs/man/svc.startd.8) (illumos, CDDL), SERVICE DEFINITION startd/duration; SERVICE FAILURE (start method timeout) - [smf_method(7)](https://solnix.io/docs/man/smf_method.7) (illumos, CDDL), Exiting and Exit Status; :kill and :true; Timeouts - [svccfg(8)](https://solnix.io/docs/man/svccfg.8) (illumos, CDDL), Service Manifest Subcommands import, validate; Example 1 - [smf(7)](https://solnix.io/docs/man/smf.7) (illumos, CDDL), DESCRIPTION (FMRI, "site" category) - [OpenIndiana handbook: System Administration](https://docs.openindiana.org/handbook/systems-administration/#service-management-smf), Service management (SMF)