
=pod

=head1 NAME

prngd - Pseudo Random Number Generator Daemon

=head1 SYNOPSIS

B<prngd>
[ I<command_opts> ]
I</path/to/socket>
[ I</path/to/other_socket> ]

B<prngd>
I<-k/--killmode>
I</path/to/socket>
[ I</path/to/other_socket> ]

=head1 DESCRIPTION

PRNGD is the Pseudo Random Number Generator Daemon.
It offers an EGD compatible interface to obtain random data and is
intended to be used as an entropy source to feed other software,
especially software based on OpenSSL.

Like EGD (http://sourceforge.net/projects/egd/) it calls system programs
to collect entropy.  Unlike EGD it does not generate a pool of random
bits that can be called from other software.

Rather it feeds the bits gathered into its internal PRNG from which
the "random bits" are obtained when requested. This way, PRNGD is
never drained and can never block (unlike EGD), so it is also suitable
to seed inetd-started programs.

It also features a seed-save file, so that it is immediately usable
after system start.

=head1 USAGE

Startup - (reads the seed file)
 /usr/local/bin/prngd [other options] /var/run/egd-pool

Clean shutdown - (saves current data to the seed file)
 /usr/local/bin/prngd --kill /var/run/egd-pool

The above line should be added to the system startup files so that
prngd starts up before any program that would query the random data
socket, such as OpenSSH.

PRNGD supports both UNIX sockets (as shown in the examples) as well as
TCP sockets (localhost only!). There is no port number registered (yet),
so pick a free port on your system, e.g. 708 when running with root perms
and you want to offer it as a system service, or 4840 without root perms.

Both ports are not assigned to any service as of
 http://www.isi.edu/in-notes/iana/assignments/port-numbers

To have PRNGD listen on both the Unix socket and TCP do
 prngd [other options] /var/run/egd-pool tcp/localhost:708 tcp/localhost:4840

You should add these lines to /etc/services: (substitute your chosen ports)
 prngd         708/tcp     # prngd/EGD system service
 prngd-user    4840/tcp    # prngd/EGD user service

PRNGD itself by now only handles numerical port numbers.

=head1 OPTIONS

PRNGD has the following options:

=over 4

=item -c / --cmdfile file

Read the entropy gathering commands from "file" instead of reading from
the compiled in default location.

=item -d / --debug

Do not go into daemon (background) mode and print diagnostic messages to
stderr.

=item -f / --fg

Stay in foreground, do not fork. Do not print diagnostic messages. This
is e.g. usefull when using AIX System Resource Controller, so that
the resource controler could detect a crash of prngd.

=item -k / --kill

Kill the daemon(s) at the locations given. It is possible to kill more than
one prngd at a time with this command. If several locations are given at
one time, prngd will try to contact them one after the other, query the
process id according to the EGD protocol and send a SIGTERM to the
process. As one daemon may server more than one socket, one may wish
to kill the daemon with the same argument that was used to start prngd.
The kill operation will however only succeed for the first socket, as
the daemon will be killed in the first attempt. prngd -k ... will therefore
silently ignore the failure at the other location(s).

=item -m / --mode mode

Set the file access mode of the UNIX socket to be "mode". The mode is
set after creation of the socket. This option can be used to restrict
access to prngd. If more than one UNIX socket is served by prngd, the
same mode setting applies to all UNIX sockets. The mode must be given
in numeric notation, e.g. 777 for read and write and execute permission
for owner/group/other.

=item -n / --no-seedfile

Do not read from any seedfile and do not create a seedfile or write to
any seedfile.

=item -p / --pidfile file

Write the pid of the prngd process into the specified file. If this option
is not explicitly used, no pid-file will be written, as prngd -k can be
used to kill a running prngd.

=item -s / --seedfile file

Location of the seedfile. The file is read at startup to initially
seed the PRNG. On clean shutdown entropy is retrieved from the pool
and written back to the file. If no location is given, the compiled in
location of the seedfile is used. If the seedfile does not exist on startup,
it is created automatically.

=item -v / --version

Print the version of prngd and exit.

=back

=head1 DIAGNOSTICS

=head1 AUTHOR/LICENSE

Author: Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>

This software is free. You can do with it whatever you want.
I would however kindly ask you to acknowledge the use of this
package, if you are going use it in your software, which you might
be going to distribute. I would also like to receive a note if you
are a satisfied user :-)

=head1 SEE ALSO

PRNGD Home Page:
  http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html

Related Sites:
  http://sourceforge.net/projects/egd/
  http://www.openssh.org/
  http://www.openssl.org/

=cut
