Content
=======

  1. Load the `pkspkr.ko` Kernel Driver Module (required)
  2. Permission setup for non-root users (for non-local logins)
  3. When and how to avoid using `beep`
  4. Example usage of `beep`


1. Load the `pkspkr.ko` Kernel Driver Module (required)
-------------------------------------------------------

To have a working PC speaker beep, the kernel driver module
`pcspkr.ko` must be loaded.

On Fedora >= 32, you need to install the `kernel-modules-extra`
package first which contains the `pcspkr.ko` kernel driver module.

On Fedora >= 12, you need to explicitly make the kernel load the
driver module `pcspkr.ko`. You can do this manually as root as
follows:

    [root@host ~]# modprobe pcspkr

If you want the system to automatically load the pcspkr driver the
next time it boots (very much recommended), uncomment the line

    alias platform:pcspkr pcspkr

in the `/etc/modprobe.d/beep.conf` config file.

You can check whether pcspkr.ko is loaded by running

    [user@host ~]$ lsmod | grep pcspkr

When pcspkr is loaded, you can run

    [root@host ~]# beep

as root and as a non-root user

    [user@host ~]$ beep

and verify that you hear the beep coming from the PC speaker.


2. Permission setup for non-root users (for non-local logins)
-------------------------------------------------------------

For more information on permission setup, please consult
/usr/share/doc/beep/PERMISSIONS.md file.

On Fedora, if a user is currently logged in locally via either a
graphical session or a getty@ttyN.service text session on the virtual
console, that user will automatically be able to access the device
special file `/dev/input/by-path/platform-pcspkr-event-spkr` which
`beep` uses to access the PC speaker.

This means that for many cases, no special permission setup is
required for a user to run beep.

For other cases (such as e.g. users only logged in via ssh sessions),
you can add the respective user to the `beep` group.

To add user `jane` to the `beep` group, have root run

    [root@host ~]# usermod jane -a -G beep

You can check which users are members of the `beep` group by running

    [user@host ~]$ getent group beep
    beep:x:951:jane,bill
    [user@host ~]$

However, any user newly added to the `beep` group must re-login so
their processes can pick up the group membership. A user can check
their group membership as follows:

    [jane@host ~]$ id
    uid=1000(jane) gid=1000(jane) groups=1000(jane),10(wheel),951(beep) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
    [jane@host ~]$

To check the permission of the PC speaker device file, run

    [user@host ~]$ ls -lH /dev/input/by-path/platform-pcspkr-event-spkr
    crw-rw----+ 1 root input 13, 85 Dec 29 13:52 /dev/input/by-path/platform-pcspkr-event-spkr
    [user@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-
    user:user:rw-
    group::rw-
    group:beep:-w-
    mask::rw-
    other::---

    [user@host ~]$ 


3. When and how to avoid using `beep`
-------------------------------------

An alternative way to get sound output for non-root users works if the
system has a sound card set up with a speaker connected to it.

E.g. the standard 440Hz square wave which `beep` emits can be played
through the standard sound infrastructure with the command `play` from
the `sox` package (more pleasant examples are shown in the `sox(1)`
man page):

    [jane@host ~]$ play -q -n synth 0.3 square 440

However, modern desktop systems with the freedesktop.org suite of
middleware (systemd user sessions, pulseaudio audio routing, etc.)
may not be set up to allow use of the sound infrastructure for users
other than the user currently logged into the current virtual console.


4. Example Usage of `beep`
--------------------------

An acoustic notification when a long running compile job finishes
(whether the build was successful or not) could be done with

    [jane@host ~/src/foobar]$ ./configure --prefix=$HOME/.local && make && make check && make install; beep

or

    [bill@host ~/rpms/foobar]$ if fedpkg mockbuild; then /usr/share/doc/beep/contrib/success-beeps; else /usr/share/doc/beep/contrib/failure-beeps; fi