aboutsummaryrefslogtreecommitdiffstats
path: root/README.rst
blob: 003e359dc076e8d2fd1201c8c421a6a13b3c0fb4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
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:: ini

    Environment=TMUX_TMPDIR=%t/tmux

| 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/"

| Afterwards a simple

  .. code:: bash

    tmux -L <name-of-socket> 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 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:: ini

    DefaultEnvironment=DISPLAY=:0

| 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:: bash

     systemctl --user start compton
     systemctl --user enable compton

cpupower-rt
___________
| The cpupower package on |arch_linux| has some |cpupower_feature_request|, 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/*.

| 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:: bash

    systemctl start cpupower-rt
    systemctl enable cpupower-rt

gpg-agent --user
________________
| The systemd user service *gpg-agent.service* starts the gpg-agent and thus makes it independent of a certain session the user runs. The `homedir` for GnuPG is set to be in `~/.gnupg` (default).
| Therefore make sure to set your *GPG_TTY* and *GPG_AGENT_INFO* |environment_variable| for your |bash| or |zsh| (or whatever you run) to the following

  .. code:: bash

    export GPG_TTY=$(tty)
    export GPG_AGENT_INFO=""

| *Note*: These settings specifically apply to gnupg > 2.1!
| Otherwise you can start and enable it like any other systemd user service:  

  .. code:: bash

     systemctl --user start gpg-agent
     systemctl --user enable gpg-agent


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

  .. code:: bash

    tmux -L irssi attach

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/`.  

  .. code:: bash

    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 --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  

  .. code:: bash

    tmux -L mon attach

mpd@ --user
___________
| 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:

  .. code:: bash

    systemctl --user start mpd@myserver
    systemctl --user enable mpd@myserver

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

offlineimap --user
__________________
| The systemd user service *offlineimap.service* starts offlineimap as a user service and can comfortably (depending on your settings) sync your IMAP accounts in the background.

  .. code:: bash

    systemctl --user start offlineimap
    systemctl --user enable offlineimap


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 --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

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@<your-user-name>
    systemctl enable rtorrent@<your-user-name>

| To connect to the user and system service after starting the service, just do

  .. code:: bash

    tmux -L rt attach

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:

  .. code:: bash

    export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"

| Otherwise you can start and stop the service like any other:

  .. code:: bash

    systemctl --user start ssh-agent
    systemctl --user enable ssh-agent


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:  

  .. code:: bash

    systemctl --user start systemd-analyze-plot
    systemctl --user enable systemd-analyze-plot

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

  .. code:: bash

    tmux attach

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 --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

    systemctl --user start weechat
    systemctl --user enable weechat

| To connect to it after starting the service, just do

  .. code:: bash

    tmux -L weechat attach


.. |systemd| raw:: html

  <a href="https://en.wikipedia.org/wiki/Systemd" target="_blank">systemd</a>

.. |awesome| raw:: html

  <a href="http://awesome.naquadah.org/" target="_blank">awesome</a>

.. |gnome| raw:: html

  <a href="https://gnome.org" target="_blank">Gnome</a>

.. |kde| raw:: html

  <a href="https://kde.org" target="_blank">KDE</a>

.. |systemd.unit| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/systemd.unit.html" target="_blank">units</a>

.. |systemd.service| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/systemd.service.html" target="_blank">service</a>

.. |systemd.timer| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/systemd.timer.html" target="_blank">timer</a>

.. |systemd.exec| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/systemd.exec.html" target="_blank">Environment</a>

.. |tmux| raw:: html

  <a href="https://tmux.github.io/" target="_blank">tmux</a>

.. |cli| raw:: html

  <a href="https://en.wikipedia.org/wiki/Command-line_interface" target="_blank">cli</a>

.. |environment_variable| raw:: html

  <a href="https://en.wikipedia.org/wiki/Environment_variable" target="_blank">environment variable</a>

.. |bash| raw:: html

  <a href="https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29" target="_blank">bash</a>

.. |zsh| raw:: html

  <a href="https://en.wikipedia.org/wiki/Z_shell" target="_blank">zsh</a>

.. |systemd-user.conf| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/systemd-user.conf.html" target="_blank">/etc/systemd/user.conf</a>

.. |compton| raw:: html

  <a href="https://github.com/chjj/compton/" target="_blank">compton</a>

.. |real-time_kernel| raw:: html

  <a href="https://www.kernel.org/pub/linux/kernel/projects/rt/" target="_blank">real-time kernel</a>

.. |kernel_parameter| raw:: html

  <a href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt" target="_blank">kernel parameter</a>

.. |grub| raw:: html

  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#GRUB" target="_blank">GRUB</a>

.. |syslinux| raw:: html

  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#Syslinux" target="_blank">syslinux</a>

.. |systemd-boot| raw:: html

  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#systemd-boot" target="_blank">systemd-boot</a>

.. |arch_linux| raw:: html

  <a href="https://www.archlinux.org/" target="_blank">Arch Linux</a>

.. |htop| raw:: html

  <a href="https://en.wikipedia.org/wiki/Htop" target="_blank">htop</a>

.. |irc| raw:: html

  <a href="https://en.wikipedia.org/wiki/Internet_Relay_Chat" target="_blank">IRC</a>

.. |irssi| raw:: html

  <a href="http://irssi.org/" target="_blank">Irssi</a>

.. |glances| raw:: html

  <a href="https://github.com/nicolargo/glances" target="_blank">glances</a>

.. |openvpn| raw:: html

  <a href="https://github.com/nicolargo/glances" target="_blank">OpenVPN</a>

.. |mpd_bug| raw:: html

  <a href="http://bugs.musicpd.org/view.php?id=4413" target="_blank">broken version</a>

.. |mpd| raw:: html

  <a href="http://www.musicpd.org/" target="_blank">MPD</a>

.. |pax11publish| raw:: html

  <a href="http://linux.die.net/man/1/pax11publish" target="_blank">pax11publish</a>

.. |xf86-input-synaptics| raw:: html

  <a href="https://www.archlinux.org/packages/extra/x86_64/xf86-input-synaptics/" target="_blank">xf86-input-synaptics</a>

.. |loginctl| raw:: html

  <a href="http://www.freedesktop.org/software/systemd/man/loginctl.html" target="_blank">loginctl</a>

.. |update-mirrorlist| raw:: html

  <a href="https://github.com/ushis/update-mirrorlist" target="_blank">update-mirrorlist</a>

.. |pacman| raw:: html

  <a href="https://en.wikipedia.org/wiki/Arch_Linux#Pacman" target="_blank">pacman</a>

.. |weechat| raw:: html

  <a href="http://weechat.org/" target="_blank">weechat</a>

.. |cpupower_feature_request| raw:: html

  <a href="https://bugs.archlinux.org/task/44270" target="_blank">limitations</a>