user-session-units
==================

This package contains several systemd unit files related to the systemd
user session, aka `systemd --user`. The goal of this package is to
provide an easy way for people to collect, share and deploy systemd
user session installations and help test the systemd user session
core code.


Content:

In the "units" folder, you will find several unit files for the system
domain and the user session. The most critical ones are:

  user/dbus.socket and user/dbus.service - This creates the dbus
  session bus for the systemd user session. The session bus should
  live under XDG_RUNTIME_DIR, and so the user-session@.service refers
  to this bus address. This is needed to make dbus activation under
  the user session work.

  default.target - not packaged. This symlink is pointing to the target
  unit file that should be started by systemd --user. If invalid, empty
  or missing, nothing will happen when you start the user session.

  other - various example units are packaged for several popular Linux
  desktop sessions. They are examples, which work for the author,
  but may not necessarily function properly on other distributions.

  user-session@.service is obsolete, and you should be automatically
  using the systemd-provided user@.service.


Prerequisites:

  systemd - required. This package uses the pkg-config file from
  systemd to make sure items are installed in the proper locations.
  You should use version 186 or higher.

  PAM needs to be enabled in systemd. Your system should have
  `pam_systemd.so` used in the `login` or `system-auth` files in
  /etc/pam.d.

  xorg-launch-helper - currently required. Xorg by itself does not
  run properly as a systemd service. The xorg-launch-helper project
  performs this task and installs several unit files that are required
  for most of the units in this project to function.

  dbus - current dbus code sends a malformed DBUS_SESSION_BUS_ADDRESS
  to any dbus-activated unit under the systemd user session. A patch
  is pending upstream to resolve the issue. Until this is accepted,
  you need to either apply this patch manually to dbus yourself, or
  live without dbus activation. For reference, the bug is here:
  https://bugs.freedesktop.org/show_bug.cgi?id=50962. A copy of the
  last-good version of the patch can be found in the /patches/
  folder in this source tree. This patch is slated to be part of
  dbus-1.6.9 which is as of this writing not yet released.

  permissions - in order for a normal user to start Xorg and control
  sound and/or video without seat management, the user running the
  session will likely need to be added to the video and audio groups,
  and you may have to make Xorg setuid root (4711). This is a
  potential security risk, so, use caution.


Installation:

  Just run the usual `configure --prefix...; make; make install`.

  Building from git requires running `./autogen.sh` first.


Configuration:

There are two things that need to be done manually by the SA to enable
and configure the user session properly.

1) Choose the default target (cmdline or graphical).

user-session-units ships two targets that can automatically be aliased
to default.target: cmdline.target and graphical.target. cmdline.target
won't start anything automatically, but serves as a target which other
services can add themselves to as dependencies (think multi-user.target).
graphical.target serves exactly the same purpose as the system-provided
graphical.target: as well as starting cmdline.target, it starts a display
server and any graphical services you choose to enable.

The default target should be set by symlinking default.target to the
target file you desire to be default. The links should be placed in
${prefix}/systemd/user/ by distributions, in ${sysconfdir}/systemd/user/
by SAs, and in ~/.config/systemd/user/ by individual users. The targets
can also be automatically linked using `systemctl enable`.

2) Choose your window manager, session manager, and autostarting services.

graphical.target wants two services called window-manager.service and
session-manager.service. These files should be symbolic links to the
service files for your window manager and session manager, respectively.
You may symlink these files manually as described above, or use `systemctl
enable` to do it automatically.

To make a service automatically start, use exactly the same process as
you would for system units: either manually symlink the target to the
appropriate .wants directory in the locations listed above or use
`systemctl enable`.

3) Enable auto-logon/start user session at boot time (optional).

This should simply be done by the SA running: `systemctl enable
user-session-launch@<insert seat>-<insert uid>.service`. However,
this may not work for some people, but you can manually create the
symlink like this:

ln -sf /usr/lib/systemd/system/user-session-launch@.service \
       /etc/systemd/system/graphical.target.wants/user-session-launch@seat0-1000.service

Note that depending on your system, you may have to change the seat
number and user ids.

This version of user-session-units requires systemd-208 or newer. Older
versions are no longer supported.

Once you enable auto-logon for a user on a seat, the
user-session-launch daemon will wait for the seat to appear, and tell
logind to spawn a systemd --user on it. From there on, the default
user units in this package can take over.

The units in this package assume you're going to be running X on
:0. Although you can pass seat name, nothing inside the user session
in this package is properly looking at the seat parameters yet.


Debugging:

You can connect to the user session over dbus and use regular systemctl
commands to start/stop units, look at the state etc.

root> # su - joe
joe> $ export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/dbus/user_bus_socket
joe> $ systemctl --user

One useful thing to try is to run dbus-monitor as joe after setting the session
bus address. It will show you if the session bus is functional.

The system journal should capture all messages output by user session
services. The user is currently not able to see those messages if you
disabled persistent journal logging (IOW, if you don't have /var/log/journal).

---

Download release tarballs here:
    http://foo-projects.org/~sofar/user-session-units/