From 957b81357458a33499f5adeb3b074095772fa6d8 Mon Sep 17 00:00:00 2001 From: David Runge Date: Mon, 26 Jun 2017 15:49:18 +0200 Subject: README.rst: Adding line breaks for readability. Updating information about TMUX_TMPDIR (now in XDG_RUNTIME_DIR). --- README.rst | 147 +++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 103 insertions(+), 44 deletions(-) diff --git a/README.rst b/README.rst index 954731c..9980c6f 100644 --- a/README.rst +++ b/README.rst @@ -1,36 +1,48 @@ 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* - 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. +| |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:: ini - Environment=TMUX_TMPDIR=%t/tmux + Environment=TMUX_TMPDIR=%t -| 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: +| 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: .. code:: bash - export TMUX_TMPDIR="$XDG_RUNTIME_DIR/tmux/" + export TMUX_TMPDIR="$XDG_RUNTIME_DIR/" -| Afterwards a simple +Afterwards a simple .. code:: bash tmux -L attach | 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 enable lingering for your user. +| **Note**: All of these separate user service 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 enable lingering for + your user. .. code:: bash @@ -42,14 +54,16 @@ Services compton --user ______________ -| The |compton| user service needs a properly exported *$DISPLAY* variable to work. You can set this in your |systemd-user.conf|: +| The |compton| user service needs a properly exported *$DISPLAY* variable to + work. You can set this in your |systemd-user.conf|: .. code:: ini DefaultEnvironment=DISPLAY=:0 -| The compton user service is anti-dependent on the realtime kernel (i.e. it will not start, if **/sys/kernel/realtime** is present and not empty). -| You can start and enable it like any other systemd user service: +| The compton user service is anti-dependent on the realtime kernel (i.e. it will + not start, if **/sys/kernel/realtime** is present and not empty). +| You can start and enable it like any other systemd user service: .. code:: bash @@ -58,14 +72,18 @@ ______________ conky@ --user ______________ -| The |conky| user service needs a properly exported *$DISPLAY* variable to work. You can set this in your |systemd-user.conf|: +| The |conky| user service needs a properly exported *$DISPLAY* variable to work. +| You can set this in your |systemd-user.conf|: .. code:: ini DefaultEnvironment=DISPLAY=:0 -| The |conky| user service starts conky scripts by name. This means, the word after the *@* directly relates to configuration files in your conky configuration directory (*~/.config/conky/*) -| You can start and enable it like any other systemd user service, by supplying it with a configuration file name: +| The |conky| user service starts conky scripts by name. This means, the word + after the *@* directly relates to configuration files in your conky + configuration directory (*~/.config/conky/*). +| You can start and enable it like any other systemd user service, by supplying + it with a configuration file name: .. code:: bash @@ -74,10 +92,13 @@ ______________ cpupower-rt ___________ -| The cpupower package on |arch_linux| has been |cpupower_feature_request|, to allow easier appliance of CPU settings based on other profiles, than the system's default. -| This is very useful, when using a real-time kernel: cpupower-rt settings will be applied **after** the general cpupower settings have been applied. - -| The *cpupower-rt.service* is dependant on a realtime kernel. It will only start, if **/sys/kernel/realtime** is present and not empty. +| The cpupower package on |arch_linux| has been |cpupower_feature_request|, to + allow easier appliance of CPU settings based on other profiles, than the + system's default. +| This is very useful, when using a real-time kernel: cpupower-rt settings will + be applied **after** the general cpupower settings have been applied. +| The *cpupower-rt.service* is dependant on a realtime kernel. It will only + start, if **/sys/kernel/realtime** is present and not empty. | You can start and enable it like any other systemd service: .. code:: bash @@ -87,7 +108,8 @@ ___________ irssi --user ____________ -| The systemd user service *irssi.service* starts the |irc| client |irssi| in a separate |tmux| environment for the current 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 .. code:: bash @@ -96,8 +118,14 @@ ____________ 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 and must be found in either */etc/jack/* or *~/.config/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 and must be found in either */etc/jack/* or + *~/.config/jack/*. .. code:: bash @@ -107,9 +135,11 @@ ____________ 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 +| 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 .. code:: bash @@ -117,7 +147,10 @@ _________________ 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, if the configuration is not called localhost* or like your hostname*! +| 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, if the + configuration is not called localhost* or like your hostname*! | Start and enable it like any other systemd user service: .. code:: bash @@ -127,7 +160,10 @@ ___________ 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: +| 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 @@ -136,7 +172,10 @@ ___________________________ 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*. +| 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 @@ -146,8 +185,12 @@ _______________ rtorrent@ _________ -| The systemd system service rtorrent@.service is quite similar to the user service rtorrent.service 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 systemd system service rtorrent@.service is quite similar to the user + service rtorrent.service 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 @@ -163,9 +206,12 @@ _________ ssh-agent --user ________________ -| The systemd user service *ssh-agent.service* starts a ssh-agent for the current user, which makes it independent from the current login session. -| In its |systemd.exec| *SSH_AUTH_SOCK* will be set to the user's *XDG_RUNTIME_DIR*. -| Therefore make sure to set your *SSH_AUTH_SOCK* |environment_variable| for your |bash| or |zsh| (or whatever you run) to the following: +| The systemd user service *ssh-agent.service* starts a ssh-agent for the + current user, which makes it independent from the current login session. +| In its |systemd.exec| *SSH_AUTH_SOCK* will be set to the user's + *XDG_RUNTIME_DIR*. +| Therefore make sure to set your *SSH_AUTH_SOCK* |environment_variable| for + your |bash| or |zsh| (or whatever you run) to the following: .. code:: bash @@ -181,7 +227,10 @@ ________________ syndaemon --user ________________ -| 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: +| 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 @@ -190,7 +239,10 @@ ________________ 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*. +| 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 @@ -216,11 +268,16 @@ ___________ update-motd ___________ -| The system service *update-motd.service* updates your MOTD (message of the day) with your hostname, your currently running kernel version, available package updates and needed security updates. -| To be able to check pacman and security updates, the accompanying *update-motd.timer* will start the service hourly. -| If a /etc/motd.name is available, then that file will be used instead of /etc/hostname to generate a banner. -| For the security updates |aur-arch-audit| is needed and if you want to have colorful output of it all, install |aur-python-lolcat|. -| To start/enable the timer just do: +| The system service *update-motd.service* updates your MOTD (message of the day) + with your hostname, your currently running kernel version, available + package updates and needed security updates. +| To be able to check pacman and security updates, the accompanying + *update-motd.timer* will start the service hourly. +| If a /etc/motd.name is available, then that file will be used instead of + /etc/hostname to generate a banner. +| For the security updates |aur-arch-audit| is needed and if you want to have + colorful output of it all, install |aur-python-lolcat|. +| To start/enable the timer just do: .. code:: bash @@ -231,7 +288,8 @@ ___________ weechat --user ______________ -| The systemd user service *weechat.service* starts the |irc| client |weechat| in a separate |tmux| environment for the current 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: .. code:: bash @@ -264,7 +322,8 @@ ______________ .. |systemd.unit| raw:: html - units + units .. |systemd.service| raw:: html -- cgit v1.2.3