BITSTIR(8)

NAME
bitstir, bits_avail - Monitor and restore entropy pool

SYNOPSIS
bitstir [switches] --search-dir dir [--search-dir dir ...]

bitstir --version

bits-avail

DESCRIPTION

Programs read /dev/random for high quality entropy. When the pool of entropy is exhausted these programs are blocked and must wait until more entropy is collected. This is inconvenient.

The program bitstir is a daemon which monitors the level of available entropy. When it drops below a threshold, bitstir uses find(1) to generate disk activity which in turn restores the entropy pool. The entropy level is continuously monitored while it is being restored. The disk is run no more than necessary.

The program bits-avail prints the level of available entropy to the standard output.

OPTIONS

--search-dir dir
    Specify directories to "search" to generate disk activity. This switch must be used at least once. The "search" does not cross filesystems so it won't try accessing an NFS link or CD-ROM drive unless explicitly asked. Typically, dir will be the mount point of a filesystem.

--set-find file
    Optionally specify the location of an alternate "find" executable.

--which-find
    Print the default location of the find executable.

--ignore-OS
    By default, bitstir runs only under NetBSD. As of this writing, only NetBSD has a /dev/random device which permits monitoring of the entropy pool. It is possible that under another OS bitstir would just run the disk forever. Use this switch with caution.

By default bitstir logs messages to standard error.

--syslog
    Also log messages to the system log. Priorities of LOG_INFO, LOG_WARN, and LOG_ERR are used depending on severity.

--verbose
    Report more messages than otherwise. In particular, report how long the disk was activated after entropy is restored. Also report disk activity continuously if it runs for an especially long time.

--no-stderr
    Do not print messages to standard error.

--silent
    Make no reports at all.

--report-interval seconds
    It is unusual for the disk to run more than three minutes. If it does so while --verbose is on, a notification is reported every three minutes. This switch sets a new interval for these reports.

--version
    Print the version.

--help
    Print help message.

CAUTION
This program generates disk activity. Presumably enough activity will wear out any disk. Anybody who can cause entropy to be consumed can cause the disk to be active. For example, this could be done by attempting to establish SSH or SSL connections. It's a good idea to try the program by hand first and then keep an eye on the system logs when it runs as a daemon. (See the --verbose switch.)

EXAMPLES
To run bitstir as a background daemon, this works nicely:

    bitstir --verbose --syslog --no-stderr --search-dir / --search-dir /usr &

(If placed in /etc/rc.local, make sure bitstir is in the path or use a complete pathname.)

This is a convenient way to watch the available entropy level:

    while (true) do bits-avail; sleep 1; done

EXIT STATUS
bitstir and bits-avail exit 0 on success, >0 on failure.

FILES
/dev/random

SEE ALSO
rnd(4), rndctl(8), find(1), syslog(3)

AUTHOR
The bitstir program was written by Peter Hendrickson <pdh@wiredyne.com>.