# Per-user user services

In addition to setting up system-level services for each user the configuration import subsystem sets up a whole load of service bundles for each user, to be managed by that user's personal instance of `service-manager`. These service bundles live in the user's service bundles directory in the user's home directory.

## The types of services

The services fall into one of three main groups: logging, non-Desktop Bus, and Desktop Bus.

### Logging services

There are three major logging services.

`simple-servers-log`
  This takes the log outputs of most non-Desktop Bus non-socket servers, and writes it to `/var/log/user/`username`/simple-servers/`.
`socket-servers-log`
  This takes the log outputs of most non-Desktop Bus socket servers, and writes it to `/var/log/user/`username`/socket-servers/`.
`dbus-servers-log`
  This takes the log outputs of most Desktop Bus servers, and writes it to `/var/log/user/`username`/dbus-servers/`.

### Non-Desktop Bus services

Non-Desktop Bus services are either straightforward simple services or services that listen on sockets. They do not require the per-user Desktop Bus broker to be running. Examples are:

`emacs`
  The emacs dæmon (`--fg-daemon` mode only).
`urxvt`
  The `urxvtd` dæmon.
`gpg-agent`
  The GPG Agent, listening on `/run/user/`username`/gnupg/S.gpg-agent`.

These services are not set up with a `DBUS_SESSION_BUS_ADDRESS` environment variable.

### Desktop Bus services

Desktop Bus services require the per-user Desktop Bus broker to be running. This can either be running as the system-level `user-dbus-daemon@`username service or as a user-level `dbus-daemon` service. The latter requires that the full per-user service manager be running; and cannot be used until the per-user service manager is started.

They also need to know how to talk to it. So the configuration import subsystem chain loads them from the `userenv` program with the `--set-dbus` option, setting an environment variable that gives the address (in `path=` form because no-one understands the `runtime=` form yet) of the `/run/user/`name`/bus` socket.

By convention, a Desktop Bus service is named by a common name by which users refer to it directly (such as `gnome-terminal-server`), and has an alias pointing to it from its formal Desktop Bus "server" name (such as `org.gnome.Terminal`). The alias is used by the Desktop Bus broker when demand-starting the service, because the Desktop Bus broker only knows the formal names of services.

## Environment variables

Processes run under per-user service management execute in a dæmon-style context. They don't have controlling terminals, and (initially) they only have the environment variables set up by the `user-services@`username service itself, which just runs `userenv` (which runs `userenv-fromenv`). In particular:

- They do not have the environment variables that are set up in the users' rc/profile/login scripts for shells. Shells, and thus their rc script mechanisms, are not involved in the running of the per-user service manager instance.

- They do not have the environment variables that are set up via the login class records in the users' `~/.login_conf` and the `/etc/login.conf` databases. Per-user service management does not, conceptually, run within a login session.

Every user-level service is afforded an environment directory in its service definition, in the conventional location that is accessble via the likes of `system-control --user print-service-env org.example.Sheila`. Environment variable for services should be configured there.

### Faulty programs that require login session environment variables in their dæmon mode

It is the wrong thing to do to explicitly set up per-user services with `TTY` or `DISPLAY` environment variables, and this is the sign of a faulty service program. Service programs serve a single user that can be logged in multiple times in multiple forms of login session. They should not require terminal access, and should be capable of connecting to multiple X displays simultaneously and not need an X display in order to start up.

Programs that are known to get this wrong include GNOME Terminal, KDE Notify, GNOME Weather, GNOME Maps, and MATE Notification. These fail to work if they are not given a `DISPLAY` environment variable in order to start up in their initial not-a-client-of-any-displays-yet state, where no D-BUS clients have connected to tell them about X displays to make windows on. This is accounted for in the configuration import subsystem, which sets up a `DISPLAY` environment variable for each user's gnome-terminal-server, `knotify`, `org.gnome.Weather.Application`, `org.gnome.Maps` and `mate-notification-daemon` service. It just sets up `DISPLAY` as `:0` for the service. You might need to tweak this for unusual X setups.