=head1 NAME

hippotat-setup-permissions - set up permissions for (non-root) use of hippotat

=head1 SYNOPSYS

 hippotat-setup-permissions client
 hippotat-setup-permissions server
 hippotat-setup-permissions revoke

=head1 DESCRIPTION

Sets up (or revokes)
the permissions to allow hippotat and/or hippotatd to run.

With C<server>
permissions needed for the server are granted to the C<_hippotat> user
(or other user set using C<USER> in C</etc/default/hippotat>.)

With C<client>
permissions needed for the client are granted to the C<_hippotat> I<group>
(or other group set using C<GROUP> in C</etc/default/hippotat>.)

Required permissions are determined based on the hippotat configuration in
C</etc/hippotat>.  (The C<hippotat> or C<hippotatd> program is run in a
special mode to query the configuration.)

In every run, revokes permissions granted to the 
configured user and/or group
by previous invocations of this script,
but which are not any longer needed according to the configuration
and command line.
So C<revoke> revokes all permissions,
and C<client> and C<server> each revoke the other.
(Only permissions granted in the specific files used by this script
will be amended or revoked.)

=head1 FILES

=over

=item C</etc/userv/ipif-access/hippotat>.

Grants to the appropriate user or group the ability to make
the virtual network interfaces, and route traffic to them.
Created on both clients and servers.

=item C</etc/authbind/byuid/>I<uid>

Grants the server the ability
to bind to the configured ports and addresses.
The uid is that for the C<_hippotat> user, or C<USER>.
Created on servers.

=item C</etc/userv/services.d/ipif>

Enables the C<ipif> userv service,
which is itself controlled by C</etc/userv/ipif-access/> etc.

Will be made a symlink to C</etc/userv/services-available/ipif>.
Created on both clients and servers.
Not removed during revocation,
since other programs on the system may need it,

Makes the symlink in .
(This is not undone by C<revoke>, since that might disturb other
services which are relying on it.)

=item C</etc/default/hippotat>

Shell script fragment sourced by 
the init script and by hippotat-setup-permissions,
and the hippotatd init script.
Can set C<USER> and C<GROUP>
(and other variables that control the init script).

=back