yggdrasil for Debian
--------------------

BASIC INFORMATION
=================

All binaries for this package are installed into /usr/sbin:

  yggdrasil - daemon started by systemd

  yggdrasilctl - control utility

  yggdrasil-genkeys - key generation utility (usually not needed)

INITIAL CONFIGURATION
=====================

You need to create a configuration file in order to use Yggdrasil.  To
do that, run:

mkdir /etc/yggdrasil
yggdrasil -genconf > /etc/yggdrasil/yggdrasil.conf
chown -R root:yggdrasil /etc/yggdrasil
chmod 0750 /etc/yggdrasil

By default, Yggdrasil is not set up to run.  To enable it, run:

systemctl enable yggdrasil
systemctl start yggdrasil

OPERATIONAL NOTES
=================

The systemd configuration for Yggdrasil drops as many privileges as possible.
It runs as an unprivileged user (yggdrasil).  It simply needs group-read access
to the config file.

UPGRADES
========

Because you may be using something like ssh over Yggdrasil to update
your system, the Yggdrasil package will not automatically restart the
service after an upgrade.

To do so, you can run:

systemctl daemon-reload
systemctl restart yggdrasil

Please also note that newer versions of Yggdrasil may require updating the
configuration.  For instance:

cp /etc/yggdrasil/yggdrasil.conf /etc/yggdrasil/yggdrasil.conf.old

/usr/sbin/yggdrasil -useconf -normaliseconf \
  < /etc/yggdrasil/yggdrasil.conf.old > /etc/yggdrasil/yggdrasil.conf

MIGRATION FROM NON-DEBIAN PACKAGE
=================================

If you are migrating from a .deb generated by the Yggdrasil project itself, or
another third party, here's what you should do:

1) Save your yggdrasil.conf somewhere safe

2) Purge the other package

3) Install the Debian one

4) Move your saved yggdrasil.conf to /etc/yggdrasil/yggdrasil.conf

5) chown yggdrasil:yggdrasil /etc/yggdrasil/yggdrasil.conf

6) Edit yggdrasil.conf and set AdminListen to
unix:///var/run/yggdrasil/yggdrasil.sock

Then proceed with enabling the systemd service as above.

BLOCKING OTHER SERVICES ON YGGDRASIL
====================================

If, for instance, you want to bind to the Yggdrasil port for another daemon
that is listening, you will need Yggdrasil to be running first.  systemd may
not necessarily start things in that order.  If you want to make sure, for
instance, Yggdrasil is running before ssh, run:

systemctl edit ssh.service

And in the [Unit] section, add:

Wants=yggdrasil.service
After=yggdrasil.service

For more details, see the discussion at
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1024053 .

-- John Goerzen <jgoerzen@complete.org>