Skip to content

Commit

Permalink
Rewrite and clean up documentation
Browse files Browse the repository at this point in the history 
Rewrite and clean up the documentation especially regarding permission setup.
This implies some changes to the rest of the documentation.
  • Loading branch information
@ndim
ndim committed Mar 29, 2019
1 parent e6e803e commit 05896f5
Show file tree
Hide file tree
Showing 5 changed files with 279 additions and 103 deletions.
80 changes: 9 additions & 71 deletions INSTALL.md
View file
Expand Up @@ -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.


Expand All @@ -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
Expand All @@ -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
Expand All @@ -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).
76 changes: 54 additions & 22 deletions PACKAGING.md
View file
Expand Up @@ -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
-----------------------
Expand All @@ -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`.

Expand All @@ -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
Expand All @@ -50,69 +58,93 @@ 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`

* `/usr/share/doc/beep/COPYING`

* `/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
=============
Expand Down

0 comments on commit 05896f5

Please sign in to comment.