From 20950bdd60faca6cf63b30d4990e1a8c39a2f3f8 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 23 Oct 2015 14:57:35 +0200 Subject: README.rst: Major overhaul and cleanup after switching to ReStructuredText. --- README.rst | 390 +++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 278 insertions(+), 112 deletions(-) diff --git a/README.rst b/README.rst index e962f6f..249b5ab 100644 --- a/README.rst +++ b/README.rst @@ -1,195 +1,361 @@ -# 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: - +uenv +#### + +| *uenv* - as in `*u*seful *env*ironments` - is a collection of scripts, |systemd| |systemd.service| and |systemd.timer| units and configuration that go along with it. +| It is meant to help organizing your workflow and hiding away user and system services in neat little separate environments. +| Arguably a couple of the |systemd.unit| might only be useful, when using window managers like |awesome|, that stem from a minimalistic approach. +| Some of the functionalities implemented here can be found in desktop environments like |kde| or |gnome|. +| *uenv* and all of its components are licensed under the GPLv3. + +Separate tmux environments +-------------------------- +| |tmux| is a very useful tool to multiplex your terminals. It offers tiling and a high configurability. +| Here it is used for a couple of services to start an environment in which other |cli| programs can run. +| In those services the following |systemd.exec| is set: + + .. code:: systemd + 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 +| This will store the |tmux| server socket in the users' *XDG_RUNTIME_DIR*. Therefore it will be necessary to set your *TMUX_TMPDIR* |environment_variable| for your |bash| or |zsh| (or whatever you run) to the following: - tmux -S /run/user//tmux/ attach + .. code:: bash -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: + export TMUX_TMPDIR="$XDG_RUNTIME_DIR/tmux/" + +| Afterwards a simple + + .. code:: bash tmux -L 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*: +| will attach you to that separate environment. +| *Note*: All of these separate environments are dependant on your login. If there is no login, |systemd| will kill all of your user services! You can get around this by using |loginctl| to set *enable-linger* for your user. + +"REALTIME" kernel parameter +----------------------------------------- +| Some services are dependant or anti-dependant on the |kernel_parameter| *"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, when you're on a |real-time_kernel|. +| Simply add this to your kernel parameters, using |grub|, |syslinux|, or |systemd-boot|: + + .. code:: bash + + systemd.setenv=REALTIME=true + +Services +-------- + +compton --user +______________ +| The |compton| user service needs a properly exported *$DISPLAY* variable to work. You can set this in your |systemd-user.conf|: + + .. code:: systemd - ... 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: +| The compton user service is anti-dependent on the `REALTIME kernel parameter` (i.e. 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: + + .. code:: systemd 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*. +cpupower-rt +___________ +| The cpupower package on |arch_linux| has some [limitations](https://bugs.archlinux.org/task/44270?project=5&cat[0]=33&string=cpupower), which 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. +| jOnce 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/*. -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: +| 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*. + +| The *cpupower-rt.service* is dependant on the `REALTIME kernel parameter`. It will only start, if that condition is met. +| You can start and enable it like any other systemd service: + + .. code:: systemd 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 +irssi --user +____________ +| The systemd user service *irssi.service* starts the |irc| client |irssi| in a separate |tmux| environment for the current user. +| To connect to it after starting the service, just do - tmux -S /run/user//tmux/irssi attach - -or (if you've setup *$TMUX_TMPDIR* properly in your shell) + .. code:: systemd tmux -L irssi attach -### JACK +jack@ --user +____________ 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. +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 and must be found in either `/etc/jack/` or `~/.config/jack/`. 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//tmux/mon attach +monitoring --user +_________________ +| The systemd user service *monitoring.service* is just a useful tool for monitoring. +| Currently it starts |htop|, |glances| and asks loginctl for the current user processes in a `separate |tmux| environment`. +| To connect to it after starting the service, just do -or (if you've setup *$TMUX_TMPDIR* properly in your shell) + .. code:: systemd tmux -L mon attach -### MPD -The specialized systemd user service *mpd@.service* starts MPD with a separate configuration located in *~/.config/mpd/mpd-.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: +mpd@ --user +___________ +| The specialized systemd user service *mpd@.service* starts |mpd| with a separate configuration located in *~/.config/mpd/mpd-.conf*. It will also use |pax11publish| to connect pulseaudio to that server! +| Start and enable it like any other systemd user service: + + .. code:: bash 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. +mpd-new --user +______________ +| 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 |mpd_bug|. +| You can use it instead of *mpd.service*, if you want to use real-time scheduling on newer systemd (>205) based systems. + + .. code:: bash 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: +postpone-screensaver --user +___________________________ +| 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: + + .. code:: bash 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: +rtorrent --user +_______________ +| 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 and set its working directory to *~/Downloads*. +| The systemd user service is started/ enabled like this: + + .. code:: bash 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: +rtorrent +________ +| The systemd system service rtorrent.service is quite similar in functionality, but on top offers the possibility of dependency to a system service - like |openvpn| (the default being a profile called *secure*). +| **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: + + .. code:: bash systemctl start rtorrent@ systemctl enable rtorrent@ -To connect to the user and system service after starting the service, just do - - tmux -S /run/user//tmux/rt attach +| To connect to the user and system service after starting the service, just do -or (if you've setup *$TMUX_TMPDIR* properly in your shell and for the **rtorrent@.service**, too) + .. code:: bash 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: +syndaemon +_________ +The |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: + + .. code:: bash 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: +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: + + .. code:: bash 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: +tmux --user +___________ +| The systemd user service *tmux.service* starts a `separate |tmux| environment`. +| To start/enable it, just do: + + .. code:: bash systemctl --user start tmux systemctl --user enable tmux -To connect to the user service after starting it, just do +| To connect to the user service after starting it, just do - tmux -S /run/user//tmux/default attach - -or (if you've setup *$TMUX_TMPDIR* properly in your shell) + .. code:: bash 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: +update-mirrorlist +_________________ +| |update-mirrorlist| is a script 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: + + .. code:: bash 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 +weechat --user +______________ +| The systemd user service *weechat.service* starts the |irc| client |weechat| in a `separate |tmux| environment` for the current user. +| To start/enable it, just do: - tmux -S /run/user//tmux/weechat attach + .. code:: bash -or (if you've setup *$TMUX_TMPDIR* properly in your shell) + systemctl --user start weechat + systemctl --user enable weechat +| To connect to it after starting the service, just do + + .. code:: bash tmux -L weechat attach -## LICENSE -**uenv** and all of its components are licensed under the GPLv3. +.. |systemd| raw:: html + + systemd + +.. |awesome| raw:: html + + awesome + +.. |gnome| raw:: html + + Gnome + +.. |kde| raw:: html + + KDE + +.. |systemd.unit| raw:: html + + units + +.. |systemd.service| raw:: html + + service + +.. |systemd.timer| raw:: html + + timer + +.. |systemd.exec| raw:: html + + Environment + +.. |tmux| raw:: html + + tmux + +.. |cli| raw:: html + + cli + +.. |environment_variable| raw:: html + + environment variable + +.. |bash| raw:: html + + bash + +.. |zsh| raw:: html + + zsh + +.. |systemd-user.conf| raw:: html + + /etc/systemd/user.conf + +.. |compton| raw:: html + + compton + +.. |real-time_kernel| raw:: html + + real-time kernel + +.. |kernel_parameter| raw:: html + + kernel parameter + +.. |grub| raw:: html + + GRUB + +.. |syslinux| raw:: html + + syslinux + +.. |systemd-boot| raw:: html + + systemd-boot + +.. |arch_linux| raw:: html + + Arch Linux + +.. |htop| raw:: html + + htop + +.. |irc| raw:: html + + IRC + +.. |irssi| raw:: html + + Irssi + +.. |glances| raw:: html + + glances + +.. |openvpn| raw:: html + + OpenVPN + +.. |mpd_bug| raw:: html + + broken version + +.. |mpd| raw:: html + + MPD + +.. |pax11publish| raw:: html + + pax11publish + +.. |xf86-input-synaptics| raw:: html + + xf86-input-synaptics + +.. |loginctl| raw:: html + + loginctl + +.. |update-mirrorlist| raw:: html + + update-mirrorlist + +.. |pacman| raw:: html + + pacman + +.. |weechat| raw:: html + + weechat + + -- cgit v1.2.3