Moving README to ReStructuredText.

1 files changed, 195 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..e962f6f
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,195 @@
+# uenv
+## About
+**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
+
+* modified/ added systemd system services for
+  * autossh
+  * cpupower
+  * rtorrent
+  * update-mirrorlist
+
+* modified/ added systemd user services for
+  * compton
+  * gpg-agent
+  * irssi
+  * jack
+  * mpd
+  * rtorrent
+  * ssh-agent
+  * syndaemon
+  * systemd-analyze
+  * tmux
+  * weechat
+
+* special systemd user services
+  * 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](https://tmux.github.io/) 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](https://tmux.github.io/) environment, some modifications might be needed.  
+In some services the following Environment will be set:
+    
+    Environment=TMUX_TMPDIR=%t/tmux
+
+This will store the [tmux](https://tmux.github.io/) server socket in the users run directory. If after starting this service one wants to connect to that special [tmux](https://tmux.github.io/) 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 option set.  
+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
+
+### irssi
+The systemd user service *irssi.service* starts the [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) client [irssi](http://irssi.org/) in a separate [tmux](https://tmux.github.io/) environment for the current user.
+To connect to it after starting the service, just do  
+
+    tmux -S /run/user/<your-user-id>/tmux/irssi attach
+
+or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+
+    tmux -L irssi attach
+
+### 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](https://tmux.github.io/) 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](http://linux.die.net/man/1/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
+
+The systemd user service mpd-new.service is a drop-in replacement for mpd.service. It properly starts MPD with a real-time budget and will remain in this repository as long as [upstream decides to ship a version broken for newer systems](http://bugs.musicpd.org/view.php?id=4227).  
+You can use it instead of mpd.service, if you want to use real-time scheduling on newer systemd (>205) based systems.  
+
+    systemctl --user start mpd-new
+    systemctl --user enable mpd-new
+
+### 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 
+
+### rtorrent
+rtorrent doesn't really come with any systemd service. Here it is started within a separate [tmux](https://tmux.github.io/) 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](https://tmux.github.io/) 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
+
+### weechat
+The systemd user service *weechat.service* starts the [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) client [weechat](http://irssi.org/) in a separate [tmux](https://tmux.github.io/) environment for the current user.
+To connect to it after starting the service, just do  
+
+    tmux -S /run/user/<your-user-id>/tmux/weechat attach
+
+or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+
+    tmux -L weechat attach
+
+## LICENSE
+**uenv** and all of its components are licensed under the GPLv3.