Content
=======

  1. Load the pkspkr.ko Kernel Driver Module (required)
  2. Set Up `beep` For Use As non-root Users Via `sudo` (optional)
  3. Example Usage


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

To have a working PC speaker beep on Fedora >= 12, you must load the
kernel driver module `pcspkr.ko` first.

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, uncomment the

    alias platform:pcspkr pcspkr

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

You can check whether pcspkr.ko is loaded by running

    [root@host ~]# lsmod | grep pcspkr

as root.

When pcspkr is loaded, you can run

    [root@host ~]# beep

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

CAUTION: There (used to?) appear to be some issues with access to the
`/dev/console` device which beep uses, possibly related to
`ConsoleKit`. This means that sometimes, just having `pcspkr.ko`
loaded is not enough for beep to actually beep. This issue is being
investigated.


2. Set Up `beep` For Use As non-root Users Via `sudo` (optional)
----------------------------------------------------------------

If you want non-root users can run the `beep` command, you can set up
`sudo` such that non-root users can run beep. This might have security
implications if the `beep` executable and/or the `pcspkr.ko` kernel
driver contain exploitable flaws.

An alternative way to get sound output for non-root users without
becoming root works if the system has a sound card set up with a
speaker connected to it. 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 in
the `sox(1)` man page):

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

So, if you still insist on making non-root users run `beep` as root,
do read on.

First, make sure the `sudo` package is installed.

As root, edit the `/etc/sudoers.d/beep` file to allow certain users or
groups to run beep. The example file shipped by the beep package
contains those two simple examples which you can uncomment and adapt:

    # Allow user 'jane' to run beep as root (if uncommented)
    # jane NOPASSWD: /usr/bin/beep
    
    # Allow all members of the group 'mock' to run beep as root (if uncommented)
    # %mock NOPASSWD: /usr/bin/beep

For more information on setting up sudo, read the `sudoers(5)` man page.

When you have finished setting up the `sudoers` file, you can check
whether `sudo beep` works with commands run as non-root users like

    [jane@host ~]$ id
    uid=1000(jane) gid=1000(jane) groups=1000(jane) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
    [jane@host ~]$ sudo -n beep
    [jane@host ~]$ 
    
    [bill@host ~]$ id
    uid=1066(bill) gid=1066(bill) groups=1066(bill),135(mock) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
    [bill@host ~]$ sudo -n beep
    [bill@host ~]$ 

Now you can source the alias definitions for `beep` in your shell (if
you are running a `csh` variant, replace `.sh` with `.csh`):

    [jane@host ~]$ source /etc/profile.d/beep.sh
    [jane@host ~]$ beep
    [jane@host ~]$ 

The sourcing of the `/etc/profile.d/beep.(csh|sh)` file will be done
automatically when you start a new (login?) shell.

In case you have *not* configured `sudo` for a non-password execution
of `beep`, `beep` will still work normally for the `root` user, and all
other users see a `sudo` error message

    [jane@host ~]$ alias beep
    alias beep='sudo -n /usr/bin/beep'
    [jane@host ~]$ beep
    sudo: a password is required
    [jane@host ~]$ 

instead of the `beep` error message they see without the sudo based
alias for `beep`:

    [jane@host ~]$ alias beep
    -bash: alias: beep: not found
    [jane@host ~]$ beep
    Could not open /dev/tty0 or /dev/vc/0 for writing
    open: No such file or directory
    [jane@host ~]$ 


3. Example Usage
----------------

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]$ fedpkg mockbuild; beep