modular-services: document ghostunnel as a service that was not written for use as a user-level service

Signed-off-by: cinereal <cinereal@riseup.net>

docs/manual/usage/modular-services.md

@@ -62,6 +62,22 @@ For example, `pkgs.php`'s [`php-fpm`]:
 }
 ```
 
+Some packages ship modules written for system services that include
+directives the user-session manager cannot honour (`DynamicUser`,
+`AmbientCapabilities`, ...). The unit is still generated with those
+directives -- user systemd silently ignores what it cannot apply.
+`WantedBy=multi-user.target` is automatically normalized to
+`WantedBy=default.target`. Other directives can be overridden per
+service:
+
+```nix
+home.services."tunnel" = {
+  imports = [ pkgs.ghostunnel.passthru.services.default ];
+  # ...
+  systemd.services."tunnel".serviceConfig.DynamicUser = lib.mkForce false;
+};
+```
+
 ## Configuration data {#sec-usage-modular-services-configdata}
 
 Each service can declare configuration files via `configData.<name>`.

tests/modules/services-modular/ghostunnel.nix

@@ -1,3 +1,9 @@
+# Smoke test that an upstream system-shape portable service module drops in
+# unchanged. The generated unit intentionally contains system-oriented
+# directives (`AmbientCapabilities`, `DynamicUser`) inherited from the upstream
+# ghostunnel module; user systemd silently ignores the ones it cannot honour.
+# `WantedBy=multi-user.target` is normalized to `default.target` by the
+# translator. For a service meant to run as a user see `php-fpm.nix`.
 { pkgs, ... }:
 {
   home.services.tunnel = {
@@ -12,9 +18,6 @@
   };
 
   nmt.script = ''
-    assertFileExists home-files/.config/systemd/user/tunnel.service
-    assertFileContains home-files/.config/systemd/user/tunnel.service '/bin/ghostunnel'
-    assertFileContains home-files/.config/systemd/user/tunnel.service 'allow-all'
-    assertFileContains home-files/.config/systemd/user/tunnel.service 'LoadCredential=cert:/run/secrets/cert.pem'
+    assertFileContent home-files/.config/systemd/user/tunnel.service ${./tunnel.service}
   '';
 }

tests/modules/services-modular/tunnel.service

@@ -0,0 +1,16 @@
+[Install]
+WantedBy=default.target
+
+[Service]
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+DynamicUser=true
+ExecStart="@ghostunnel@/bin/ghostunnel" "server" "--listen" "127.0.0.1:8443" "--target" "127.0.0.1:8080" "--allow-all" --cert=${CREDENTIALS_DIRECTORY}/cert --key=${CREDENTIALS_DIRECTORY}/key
+LoadCredential=cert:/run/secrets/cert.pem
+LoadCredential=key:/run/secrets/key.pem
+Restart=always
+RestartSec=5
+Type=simple
+
+[Unit]
+After=network.target
+Wants=network.target