README.md: Updating to include information on different programs/services included.

1 files changed, 155 insertions, 1 deletions

diff --git a/README.md b/README.md
index 72fed5f..d98b65b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # uenv
 ## About
-**uenv** - as in *"useful environments"* - is a collection of scripts, systemd service and timer units and configuration that go along with it.
+**uenv** - as in *"useful environments"* - is a collection of scripts, systemd service and timer units and configuration that go along with it.  
+A couple of them might only be useful, when using window managers like [Awesome](http://awesome.naquadah.org/), that stem from a minimalistic approach...
+Some of the functionalities implemented here can be found in desktop environments like [KDE](https://www.kde.org/) or [Gnome](https://www.gnome.org/).
 
 ## Features
 
@@ -25,4 +27,156 @@
   * monitoring
   * postpone-screensaver
 
+## HOWTO & Info
+Here are some short HOWTOs and infos on using some of the special or modified systemd services.  
 
+### Real-time kernel command line option
+Some services are dependant or anti-dependant on the kernel command line option *"systemd.setenv=REALTIME=true"*. The option itself sets nothing but an Environment for systemd.  
+This is pretty useful when wanting to enable or disable certain services using *"ConditionKernelCommandLine"* in their **[Unit]** sections,
+
+### Separate tmux environment
+Tmux is used for a couple of services to start an environment in which other command line interface programs can run. To achieve this and not get in conflict with the standard tmux environment, some modifications might be needed.  
+In some services the following Environment will be set:
+    
+    Environment=TMUX_TMPDIR=/run/user/%U/tmux
+
+This will store the tmux server socket in the users run directory. If after starting this service one wants to connect to that special tmux session, it is necessary to either define the absolute path to the socket   
+
+    tmux -S /run/user/<your-user-id>/tmux/<name-of-socket> attach
+
+or to just set your *"TMUX\_TMPDIR"* variable to the same directoy in your shells configuration files and then just attach to it, like so:  
+
+    tmux -L <name-of-socket> attach
+
+### compton
+The [compton](https://github.com/chjj/compton/) user service will need a properly exported **DISPLAY** variable to work. You can set this in */etc/systemd/user.conf*:  
+
+    ...
+    DefaultEnvironment=DISPLAY=:0
+    ...
+
+The compton user service is anti-dependent on the real-time kernel command line option. It will not start, when booting into a kernel with that 
+You can start and enable it like any other systemd user service:  
+
+     systemctl --user start compton
+     systemctl --user enable compton
+
+### cpupower
+The cpupower package (on Archlinux) has some [limitations](https://bugs.archlinux.org/task/44270?project=5&cat[0]=33&string=cpupower), that make it quite hard to apply CPU settings based on profiles.  
+At least in a real-time environment, the modified version of cpupower - called cpupower-rt - makes it easy to apply differing settings **after** the usual cpupower settings have been applied.  
+Once the above mentioned feature request is resolved, it will be as easy as just copying the *cpupower.service* file and modify it slightly in *"/etc/systemd/sytem/"*
+For now, there needs to be a separate config file **and** a separate script. For setting it up, just modify *"/etc/default/cpupower-rt"* as you would for *"/etc/default/cpupower"*.
+
+This service is dependant on the real-time kernel command line option. It will only start, if that condition is met.  
+You can start and enable it like any other systemd service:  
+
+    systemctl start cpupower-rt
+    systemctl enable cpupower-rt
+
+### dbus
+Some systemd user services will need a dbus message bus, started by the user. Until [kdbus](https://en.wikipedia.org/wiki/Kdbus) is finished (and thus dbus will be automatically started by PAM), activate it like this:  
+
+    systemctl --global enable dbus.socket
+
+### JACK
+JACK2 comes with a dbus interface. Unfortunately systemd's efforts regarding [kdbus](https://en.wikipedia.org/wiki/Kdbus) and integrating kernel CPU [cgroups](https://www.kernel.org/doc/Documentation/cgroups/) (and thereby also real-time scheduling) is still somewhat in limbo.  
+The included jack@.service starts JACK using */usr/bin/jackd"* (so no dbus), according to a profile. The name of that profile follows after the *@* on starting/ activating the unit.  
+
+    systemctl --user start jack@fw1
+    systemctl --user enable jack@fw1
+
+This service is dependant on the real-time kernel command line option. It will only start, if that condition is met.  
+
+### Monitoring
+The systemd user service *monitoring.service* is just a useful tool, that's hopefully going to expand in features in the near future. It starts htop, glances and a *"loginctl user-status"* for the current user in a separate tmux environment.  
+To connect to it after starting the service, just do  
+
+    tmux -S /run/user/<your-user-id>/tmux/mon attach
+
+or (if you've setup *"TMUX_TMPDIR"* properly in your shell)  
+
+    tmux -L mon attach
+
+### MPD
+The specialized systemd user service *mpd@.service* starts MPD with a separate configuration located in *"~/.config/mpd/mpd-<name-of-server>.conf*. It will also use pax11publish to connect pulseaudio to that server!
+Start and enable it like any other systemd user service:
+
+    systemctl --user start mpd@myserver
+    systemctl --user enable mpd@myserver
+
+### postpone-screensaver
+With the systemd user service and timer *postpone-screensaver.{service,timer}* one can - as the name implies - postpone one's screensaver from blanking the screen. The script checks for programs set in *"~/.config/postpone-screensaver"* and can be started and activated like any other timer/service:  
+
+    systemctl --user start postpone-screensaver.timer 
+    systemctl --user enable postpone-screensaver.timer 
+
+### Pulseaudio
+The pulseaudio user service comes with a socket. In some cases or environments it can be quite useful to be able to start and stop pulseaudio as you please. To be able to to that, there's *pulse.service*. It can be started and enabled like any other service:  
+
+    systemctl --user start pulse
+    systemctl --user enable pulse
+
+Make sure to also disable autospawn in your *~/.config/pulse/client.conf*, like so:
+
+    autospawn = no
+
+### rtorrent
+rtorrent doesn't really come with any systemd service. Here it is started within a separate tmux environment. It will automatically create *"~/Downloads/rtorrent/{tmp,session}"*, if non-existent, set its working directory to *"~/Downloads"*.  
+The systemd user service is started/ enabled like this:  
+
+    systemctl --user start rtorrent
+    systemctl --user enable rtorrent
+
+The systemd system service is quite similar in functionality, but on top offers the possibility of dependency to a system service - like [OpenVPN](http://openvpn.net/). The default is a OpenVPN profile called *"ipredator"*.   
+**Note:** In a separate configuration file (*"/etc/conf.d/rtorrent@.conf"*), the *TMUX_TMPDIR* should be set, as it otherwise defaults to using *"/tmp/*!   
+The system service can be started and enabled like this:  
+
+    systemctl start rtorrent@<your-user-name>
+    systemctl enable rtorrent@<your-user-name>
+
+To connect to the user and system service after starting the service, just do  
+
+    tmux -S /run/user/<your-user-id>/tmux/rt attach
+
+or (if you've setup *"TMUX_TMPDIR"* properly in your shell and for the **rtorrent@.service**, too)  
+
+    tmux -L rt attach
+
+### syndaemon
+The [xf86-input-synaptics](https://www.archlinux.org/packages/extra/x86_64/xf86-input-synaptics/) package comes with *"/usr/bin/syndaemon"*. This tool is used to disable the touchpad while typing. While desktop environments like KDE and Gnome use it integrated, it can also be started as a systemd user service:  
+
+    systemctl --user start syndaemon
+    systemctl --user enable syndaemon
+
+### systemd-analyze-plot
+Systemd comes with a functionality to plot the system's boot up process in svg and other file formats. This user service uses *"/usr/bin/systemd-analyze"* to plot a svg to a predefined directory. Configuration takes place in *"~/.config/systemd/plot.conf"*.  
+To start/enable the service afterwards just do:  
+
+    systemctl --user start systemd-analyze-plot
+    systemctl --user enable systemd-analyze-plot
+
+### tmux
+[Tmux](http://tmux.sourceforge.net/) is a very useful tool to multiplex your terminals. It offers tiling and a high configurability.  
+The systemd user service for tmux starts it in a separate environment (set in *"TMUX\_TMPDIR"*). This way it is started as soon as the *user@.service* starts, but will also close, when your last session closes!  
+To start/enable it, just do:  
+
+    systemctl --user start tmux
+    systemctl --user enable tmux
+
+To connect to the user service after starting it, just do  
+
+    tmux -S /run/user/<your-user-id>/tmux/default attach
+
+or (if you've setup *"TMUX_TMPDIR"* properly in your shell)  
+
+    tmux attach
+
+## update-mirrorlist
+[Udpate-mirrorlist](https://github.com/ushis/update-mirrorlist) is a program to update the system's pacman mirrorlist according to some predefined settings. Here it is started on a weekly basis according to a timer unit.
+To start/enable it, just do:  
+
+    systemctl start update-mirrorlist.timer
+    systemctl enable update-mirrorlist.timer
+
+## LICENSE
+**uenv** and all of its components are licensed under the GPLv3.