From 05896f595d6536aa2e116a3826235fd3278c5b44 Mon Sep 17 00:00:00 2001 From: Hans Ulrich Niedermann Date: Fri, 29 Mar 2019 01:53:35 +0100 Subject: [PATCH] Rewrite and clean up documentation Rewrite and clean up the documentation especially regarding permission setup. This implies some changes to the rest of the documentation. --- INSTALL.md | 80 +++------------------- PACKAGING.md | 76 ++++++++++++++------- PERMISSIONS.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 47 ++++++++++++- beep.1.in | 4 +- 5 files changed, 279 insertions(+), 103 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index e8a935f..82bcbae 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -5,7 +5,7 @@ This document describes how to install `beep` from sources and how to set up the system afterwards. If you are using `beep` as shipped in a distribution package, the -package should have done most of those steps for you. The one +package should have done most of those steps for you. The notable exception should be adding users to the `beep` group. @@ -18,7 +18,7 @@ The easy way is $ make install By default, it'll put the executable `beep` in `/usr/bin`. If you -don't like this, change the common variables as appropriate: +don't like this, change the common variables as appropriate, e.g. $ make prefix=$HOME/.local $ make prefix=$HOME/.local install @@ -28,7 +28,11 @@ or $ make $ make DESTDIR=$PWD/__installroot install -For the complete list of those variables, see the top of `GNUmakefile`. +For the complete list of those variables, see the top of +[`GNUmakefile`](GNUmakefile). + +Some more compilation related variables mostly useful for distribution +packagers are documented in [`PACKAGING.md`](PACKAGING.md). System configuration @@ -40,71 +44,5 @@ System configuration to a file like e.g. `/etc/modprobe.d/pcspkr-beep.conf`. - After udev rule setup, run `modprobe pcspkr.ko` to load the driver - without a reboot, creating the - `/dev/input/by-path/platform-pcspkr-event-spkr` evdev device with - the desired permissions. - - -Device permission setup to allow non-root users to beep -======================================================= - -If you want to give all users in the `wheel` group write access to the -input event device `/dev/input/by-path/platform-pcspkr-event-spkr`, -add a `udev` rule like this to `/etc/udev/rules.d/90-pcspkr-beep.rules`: - - # Give write access to the PC speaker to "wheel" group so they can run "beep" - ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="PC Speaker", ENV{DEVNAME}!="", RUN+="/usr/bin/setfacl -m g:wheel:w '$env{DEVNAME}'" - -For non-`wheel` users, set up a new system group `beep`: - - [root@host ~]# groupadd -r beep - [root@host ~]# - -Add a `udev` rule to `/etc/udev/rules.d/90-pcspkr-beep.rules` which -allows the `beep` group write access to the input event device -`/dev/input/by-path/platform-pcspkr-event-spkr`: - - # Give write access to the PC speaker to "beep" group so they can run "beep" - ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="PC Speaker", ENV{DEVNAME}!="", RUN+="/usr/bin/setfacl -m g:beep:w '$env{DEVNAME}'" - -You might have to unload and reload the `pcspkr.ko´ module to re-add -the device so that the new rule is invoked: - - [root@host ~]# modprobe -r pcspkr; sleep 2; modprobe pcspkr - [root@host ~]# - -Check that the device has the desired permissions with - - [root@host ~]# ls -lH /dev/input/by-path/platform-pcspkr-event-spkr - crw-rw----+ 1 root input 13, 84 29. Dez 07:35 /dev/input/by-path/platform-pcspkr-event-spkr - [root@host ~]# getfacl /dev/input/by-path/platform-pcspkr-event-spkr - getfacl: Removing leading '/' from absolute path names - # file: dev/input/by-path/platform-pcspkr-event-spkr - # owner: root - # group: input - user::rw- - group::rw- - group:beep:-w- - group:wheel:-w- - mask::rw- - other::--- - - [root@host ~]# - -Now add the users who are allowed to use beep to the `beep` group: - - [root@host ~]# usermod jane -a -G beep - [root@host ~]# - -After having user `jane` log out (and after killing user `jane`'s -running `tmux` instances, killing `system --user` sessions for user -`jane`, or just plain rebooting), user `jane` can log back in and -check whether she now a `beep` group member: - - [jane@host ~]$ id - uid=1000(jane) gid=1000(jane) groups=1000(jane),10(wheel),942(beep) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 - [jane@host ~]$ ./beep -f 220 -n -f 275 -n -f 330 -n -f 440 -n -f 550 -n -f 660 -n -f 880 - [jane@host ~]$ - - + * Set up the udev rules to set the device special file permissions + for non-root users according to [`PERMISSIONS.md`](PERMISSIONS.md). diff --git a/PACKAGING.md b/PACKAGING.md index 3f3db90..a0513e5 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -4,6 +4,9 @@ Packaging beep for Linux distributions This file contains a number of ideas and suggestions which might come in helpful in case you are packaging `beep` for a Linux distribution. +In addition, to a packager of `beep`, [`INSTALL.md`](INSTALL.md) might +also be interesting. + Building and installing ----------------------- @@ -17,7 +20,7 @@ If you want to replace the compiler flags, run `make` like e.g. make CFLAGS_gcc="-O -gstabs,foo" CFLAGS_clang="" -You can also keep `beep`'s default flags and just add your own with +You can also keep `beep`'s default flags and just add your own by setting `CFLAGS`. The same principle applies for `CPPFLAGS`, `LDFLAGS`, and `LIBS`. @@ -33,6 +36,11 @@ variant: make COMPILER_gcc=no +Or you can specifically specify gcc compiler and linker executables +and avoid the clang build: + + make COMPILER_gcc=/path/to/aarch64-linux-gnu-gcc LINKER_gcc='$(COMPILER_gcc)' COMPILER_clang=no + If you need to set any of the `*dir` variables like `mandir` on the `make` command line, please set them both for the build step (`make`) and the install step (`make install`). For example, you might want to @@ -50,17 +58,26 @@ Files to install for beep The `beep` executable. * `/usr/share/man/man1/beep1.gz` + Man page for the `beep` executable. + If your distribution package ships a special `README.Distro` file + (such as `README.Debian` or `README.fedora`), you might want to + add a reference to that file in the man page's __SEE ALSO__ + section instead of the commented out placeholder reference to + `README.Distro`. ### Documentation files * `/usr/share/doc/beep/README.md` + General description of `beep`. * `/usr/share/doc/beep/PERMISSIONS.md` - Change or replace this file as necessary for your distribution to - give package users and system administrators the information - they need to successfully set up device permissions. + Gives package users and system administrators the information they + need to successfully set up device permissions for non-root users. + + Covers installing from source tree, and distro package following + and not following the beep suggested udev rule setup. * `/usr/share/doc/beep/CHANGELOG` @@ -68,51 +85,66 @@ Files to install for beep * `/usr/share/doc/beep/CREDITS` -The files `INSTALL.md`, `DEVELOPMENT.md`, `PACKAGING.md` are not -useful for binary packages. They make most sense for source trees. +The files [`INSTALL.md`](INSTALL.md), +[`DEVELOPMENT.md`](DEVELOPMENT.md), [`PACKAGING.md`](PACKAGING.md) are +not useful for binary packages. They only make sense for source +trees. ### System setup including permissions * `/etc/modprobe.d/pcspkr-beep.conf` When the system administrator uncomments the `alias` line, this - tells the system to load the `pcspkr.ko` kernel module. + tells the system to load the `pcspkr.ko` kernel module: + + alias platform:pcspkr pcspkr - Without `pcspkr.ko`, there will be no sound from the PC speaker - at all. + Without `pcspkr.ko` loaded, there will be no sound from the PC + speaker at all. Use, change, replace as is fitting for your distribution. -If you want to use the default permission setup with a `beep` group -and the system administrator adding users to the `beep` group, install -and do the following: + * `/usr/lib/udev/rules.d/70-pcspkr-beep.rules` or `/lib/udev/rules.d/70-pcspkr-beep.rules` (location depends on distribution) - * `/etc/udev/rules.d/90-pcspkr-beep.rules` - Sets up write access to the PC speaker device for group `beep` or - whatever else the system administrator has set it up to do. + If you want to use the suggested permission setup, ship this + file. For the contents, cf. [`PERMISSIONS.md`](PERMISSIONS.md). - Requires the `pcspkr.ko` kernel module to be loaded. + Use, change, replace as is fitting for your distribution. + + * `/usr/lib/udev/rules.d/90-pcspkr-beep.rules` or `/lib/udev/rules.d/90-pcspkr-beep.rules` (location depends on distribution) + + If you want to use the suggested permission setup, ship this + file. For the contents, cf. [`PERMISSIONS.md`](PERMISSIONS.md). Use, change, replace as is fitting for your distribution. - * Upon installing the package, a `beep` user group needs to be - created with something like + * Add a `beep` system user group + + If you want to use the suggested permission setup + (cf. [`PERMISSIONS.md`](PERMISSIONS.md)), have the package run + something like # getent group beep >/dev/null || groupadd -r beep inside the package installation scripts. * `/usr/share/doc/beep/PERMISSIONS.md` - This describes to system administrators how to add - users to the `beep` group and to users how to check - they actually are members of the `beep` group. - Use, change, replace as is fitting for your distribution. + The [`PERMISSIONS.md`](PERMISSIONS.md) file describes to system + administrators how to give users permissions to actually beep the + PC speaker, both with the suggested udev rules, and generally. + + If your distribution ships a different set of udev rules, you + should describe those in some distribution specific README file + (like e.g. `README.Debian` or `README.fedora`). All files installed into `/etc` are config files which the system administrator may change and expect to not be overwritten with package updates. +The sysadmin may add their own udev rules to `/etc/udev/rules.d/` +which should not be touched by the `beep` package. + Architectures ============= diff --git a/PERMISSIONS.md b/PERMISSIONS.md index 3f5a18c..431101b 100644 --- a/PERMISSIONS.md +++ b/PERMISSIONS.md @@ -1,13 +1,177 @@ Permission setup for beep ========================= -The way to regulate permissions to the speaker device suggested by the -`beep` package is to have the system administrator add all users who -should be able to run beep to the `beep` group. +The `beep` command needs write access to the +`/dev/input/by-path/platform-pcspkr-event-spkr` device special file +which will be a symlink to the actual device special file called +something like `/dev/input/event20`. +This device special file is created when the `pcspkr.ko` PC speaker +driver kernel module is loaded. The permissions given to that device +special file can be changed by adding some `udev(7)` rules. -Add user to `beep` group ------------------------- +The `beep` package suggests the udev rules mentioned in the sections +[Users currently logged into virtual +console](#users-currently-logged-into-virtual-console) and [All other +users](#all-other-users) below are installed by distro package or +manually by the system administrator. + +Then the system administrator can easily give users access to the PC +speaker device as described in the [Add users to `beep` +group](#add-users-to-beep-group) section at the bottom +of this file. + + +udev rules +========== + + +udev rule basics +---------------- + +Whenever a new device is added to or removed from the system, the +`udev(7)` system will apply its rules to the device. + +Every rule consists of a part to match a particular type of device +(with comparison operators such as `==`), and a part which does +something about that device, such as modifying or setting a variable +(e.g. `+=' or `=`), changing its file mode or ownership or file ACL. + +See the sections below for example rules suggested for `beep`. + + +Where to install udev rules +--------------------------- + +There are two locations where `udev(7)` rules can be installed: + + * `/usr/lib/udev/rules.d/*.rules` or `/lib/udev/rules.d/*.rules` + This is the distribution dependent directory where distribution + binary packages will install their static rules which are not to + be modified by the system administrator. + + * `/etc/udev/rules.d/*.rules` + This where the system administrator will install their special + rules independent of any distribution packages. + + This location is suitable when a system administrator is + installing `beep` from source tree, or when the system + administrator wants to install their own rules to override the + distro package provided ones. + + +Users currently logged into virtual console +------------------------------------------- + +Making use of modern GNU/Linux/freedesktop/etc. systems' session and +udev magic, you can give the user logged into the currently active +virtual console session access to the PC speaker by dropping the +following rule into a udev rule file like +`/usr/lib/udev/rules.d/70-pcspkr-beep.rules` or +`/lib/udev/rules.d/70-pcspkr-beep.rules` (the exact location depends +on your distribution): + + # Give write access to the PC speaker to the user logged in on the current virtual console + ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="PC Speaker", ENV{DEVNAME}!="", TAG+="uaccess" + +This allows `beep` to run for the user currently logged in locally +without any user specific setup required. + +However, it will _not_ allow users logged remotely (e.g. via `ssh`) or +processes running in the background to beep the PC speaker, unless the +same user happens to be logged in on the currently active virtual +console session at the time `beep` opens the device special file. + + +All other users +---------------- + +To allow `beep`ing for users logged in remotely (e.g. via ssh) or +processes running as any user other than the one logged into the +currently active virtual console session, the best way is to set up a +system user group `beep` and give that group write access to the +device special file. + + [root@host ~]# groupadd -r beep + [root@host ~]# + +Now to allow writing to the device special file for members of the +`beep` user group, you have the choice between the following two udev +rules for `/usr/lib/udev/rules.d/90-pcspkr-beep.rules` or +`/lib/udev/rules.d/90-pcspkr-beep.rules` (the exact location depends +on your distribution). + + * The following ACL based rule adds access for the `beep` group + without changing the standard group access granted by the default + system setup, by using the `setfacl(1)` command: + + # Add write access to the PC speaker for the "beep" group + ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="PC Speaker", ENV{DEVNAME}!="", RUN+="/usr/bin/setfacl -m g:beep:w '$env{DEVNAME}'" + + * The following non-ACL rule grants access to the `beep` group by + removing access for the default group `input`: + + # Give write access to the PC speaker only to the "beep" group + ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="PC Speaker", ENV{DEVNAME}!="", GROUP="beep", MODE="0620" + + +Verifying the udev rules work +----------------------------- + +You will have to (re-)load the `pcspkr.ko` module to (re-)add the +device so that the new rule is invoked: + + [root@host ~]# modprobe -r pcspkr; sleep 2; modprobe pcspkr + [root@host ~]# + +Check that the device has the desired permissions with + + [root@host ~]# ls -lH /dev/input/by-path/platform-pcspkr-event-spkr + crw-rw----+ 1 root input 13, 84 29. Dez 07:35 /dev/input/by-path/platform-pcspkr-event-spkr + [root@host ~]# getfacl /dev/input/by-path/platform-pcspkr-event-spkr + getfacl: Removing leading '/' from absolute path names + # file: dev/input/by-path/platform-pcspkr-event-spkr + # owner: root + # group: input + user::rw- + group::rw- + group:beep:-w- + group:wheel:-w- + mask::rw- + other::--- + + [root@host ~]# + + +General rules for permissions setup +----------------------------------- + +To keep your system secure, try to keep your permissions as +restrictive as possible, while allowing for what you want. Give access +to a single user. Give access to a special group of users. + +A few __bad ideas__ to __avoid__ you want to change the permissions setup: + + * Add users to the `input` group + This would allows those users access to all input devices, + including keyboards and mice which are none of their business + (think keyloggers or reprogramming programmable keyboards). + + * Running `beep` setuid root or via sudo + There have been a few serious security issues for `beep` in 2018, + mainly when `beep` was run setuid root or via sudo. + + Therefore, `beep` now checks whether it is being run setuid root + or via sudo, and if so, `beep` aborts without doing anything + potentially harmful or useful. + + +Add users to `beep` group +========================= + +The suggested way to regulate permissions to the speaker device is to +have the system administrator add all users who should be able to run +beep to the `beep` group. To add user `jane` to the `beep` group, the system administrator has to run a command like @@ -23,3 +187,4 @@ check whether she now a `beep` group member: uid=1000(jane) gid=1000(jane) groups=1000(jane),10(wheel),942(beep) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 [jane@host ~]$ ./beep -f 220 -n -f 275 -n -f 330 -n -f 440 -n -f 550 -n -f 660 -n -f 880 [jane@host ~]$ + diff --git a/README.md b/README.md index 6aef5f6..0a902fd 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ beep - beep the PC loudspeaker on Linux `beep` allows you to have the PC speaker issue beeps and beep patterns with given frequencies, durations, and spacing. -Beginning in 2019, this version of beep can be found at +Beginning in 2019, this version of `beep` can be found at [github.com/spkr-beep/beep/](https://github.com/spkr-beep/beep/). Please report bugs and other problems at [github.com/spkr-beep/beep/issues](https://github.com/spkr-beep/beep/issues). -This version of`beep` is based on Johnathan Nightingales' original +This version of `beep` is based on Johnathan Nightingales' original `beep` from [github.com/johnath/beep/](https://github.com/johnath/beep/) and [johnath.com/beep/](http://johnath.com/beep/) which was maintained @@ -48,7 +48,10 @@ The evdev API uses `write(2)` to write `EV_SND`/`SND_TONE` input_event data to the `/dev/input/by-path/platform-pcspkr-event-spkr` device file. The system administrator can set up normal file permissions on the device file to allow beeping access for certain users and -groups. See `INSTALL.md` for more detailed elaborations. +groups. + +See [`PERMISSIONS.md`](PERMISSIONS.md) for more details on permission +setup. The console API @@ -59,6 +62,44 @@ classical console API, the Linux kernel insists you must either be root or own the current TTY (e.g. non-root user logged in on `/dev/tty4`). +`beep` only uses this as a fallback. + + +Documentation +============= + +The documentation files shipped with the `beep` source tree, sorted +alphabetically: + + * [`CHANGELOG`](CHANGELOG) + Usually called `NEWS` but not renamed for historical reasons, this + file contains a list of the high level changes between `beep` + releases. + + * [`COPYING`](COPYING) + The licensing text. + + * [`CREDITS`](CREDITS) + Giving credit where credit is due. + + * [`DEVELOPMENT.md`](DEVELOPMENT.md) + Information for developers working on improving beep. + + * [`INSTALL.md`](INSTALL.md) + How to build and install `beep` from source tree. + + * [`PACKAGING.md`](PACKAGING.md) + How to package `beep` for a Linux distribution. + + * [`PERMISSIONS.md`](PERMISSIONS.md) + How to set up the permissions to allow non-root users to run + `beep`. Covers installing from source tree, and distro package + following and not following the beep suggested udev rule setup. + + * [`README.md`](README.md) + This basic overview on `beep` including the history kept over from + the old `README` file. + The history of beep =================== diff --git a/beep.1.in b/beep.1.in index a5afbfb..4a8eba3 100644 --- a/beep.1.in +++ b/beep.1.in @@ -249,8 +249,8 @@ will produce first two 1000Hz beeps, then 5 beeps at the default tone, but only .\" ==================================================================== .\" .SH SEE ALSO -.\" .BR fixme (1), -.\" .BR andme (1), +.\" Distro packages might want to replace the next line with their README +.\" .BR @pkgdocdir@/README.Distro , .BR @pkgdocdir@/README.md , .BR @pkgdocdir@/PERMISSIONS.md , .UR "https://github.com/spkr\-beep/beep"