Base: Document SystemServer

Base/usr/share/man/man5/SystemServer.md

@@ -0,0 +1,59 @@
+## Name
+
+SystemServer - services configuration
+
+## Synopsis
+
+`/etc/SystemServer.ini`
+
+## Description
+
+SystemServer configuration consists of a list of *services* for it to spawn.
+
+Each service is configured as a section in the configuration file, where the
+section name is the service name and the keys inside the section are the options
+describing how to launch and manage this service.
+
+## Options
+
+* `Executable` - an executable to spawn. If no explicit executable is specified, SystemServer assumes `/bin/{service name}` (for example, `/bin/WindowServer` for a service named `WindowServer`).
+* `Arguments` - a space-separated list of arguments to pass to the service as `argv` (excluding `argv[0]`). By default, SystemServer does not pass any arguments other than `argv[0]`.
+* `StdIO` - a path to a file to be passed as standard I/O streams to the service. By default, services inherit SystemServer's own standard I/O streams, which are normally set to `/dev/tty0`.
+* `Priority` - the scheduling priority to set for the service, either "idle", "low", "normal", or "high". The default is "normal".
+* `KeepAlive` - whether the service should be restarted if it exits or crashes. For lazy services, this means the service will get respawned once a new connection is attempted on their socket after they exit or crash.
+* `Lazy` - whether the service should only get spawned once a client attempts to connect to their socket.
+* `Socket` - a path to a socket to create on behalf of the service. For lazy services, SystemServer will actually watch the socket for new connection attempts. An open file descriptor to this socket will be passed as fd 3 to the service.
+* `User` - a name of the user to run the service as. This impacts what UID and GID the service processes have. By default, services are run as root.
+
+## Environment
+
+* `SOCKET_TAKEOVER` - set by the SystemServer for a service if the service is being passed a socket.
+
+## Examples
+
+```ini
+# Spawn the terminal as user anon once on startup.
+[Terminal]
+User=anon
+
+# Set up a socket at /tmp/portal/lookup; once a connection attempt
+# is made spawn the LookupServer as user anon with a low priority.
+# If it exits or crashes, repeat.
+[LookupServer]
+Socket=/tmp/portal/lookup
+Lazy=1
+Priority=low
+KeepAlive=1
+User=anon
+
+# Spawn the TTYServer on /dev/tty1 once on startup with a high priority,
+# additionally passing it "tty1" as an argument.
+[TTYServer]
+Arguments=tty1
+StdIO=/dev/tty1
+Priority=high
+```
+
+## See also
+
+* [`SystemServer`(7)](../man7/SystemServer.md)

Base/usr/share/man/man7/SystemServer.md

@@ -0,0 +1,47 @@
+## Name
+
+SystemServer - one server to rule them all
+
+## Description
+
+SystemServer is the first userspace process to be started by the kernel on boot.
+Its main responsibility is spawning all the other servers and other programs
+that need to be autostarted (referred to as **services**).
+
+A service can be configured to be *kept alive*, in which case SystemServer will
+respawn it if it exits or crashes. A service may also be configured as *lazy*,
+in which case SystemServer won't spawn it immediately, but only once a client
+connects to its socket (see **Socket takeover** below).
+
+## Socket takeover
+
+SystemServer can be configured to set up a socket on behalf of a service
+(typically, an *IPC portal* socket inside `/tmp/portal/`). SystemServer sets up
+the configured sockets before spawning any services, preventing any races
+between socket creation and the client trying to connect to those sockets.
+
+When a service is spawned, SystemServer passes it an open file descriptor to the
+configured socket as fd 3, and sets `SOCKET_TAKEOVER=1` in the environment to
+inform the service that socket takeover is happening. SystemServer calls
+[`listen`(2)](../man2/listen.md) on the file descriptor, so the service doesn't
+need to do it again. The file descriptor does not have the `FD_CLOEXEC` flag set
+on it.
+
+The service is advised to set this flag using [`fcntl`(2)](../man2/fcntl.md) and
+unset `SOCKET_TAKEOVER` from the environment in order not to confuse its
+children.
+
+LibCore provides `CLocalServer::take_over_from_system_server()` method that
+performs the service side of the socket takeover automatically.
+
+If a service is configured as *lazy*, SystemServer will actually listen on the
+socket it sets up for the service, and only spawn the service once a client
+tries to connect to the socket. The service should then start up and accept the
+connection. This all happens transparently to the client. If a lazy service is
+configured to be *kept alive*, it can even exit after some period of inactivity;
+in this case SystemServer will respawn it again once there is a new connection
+to its socket.
+
+## See also
+
+* [`SystemServer`(5)](../man5/SystemServer.md)