From f9bf4bd3af7ef114b54d67155bc3a568194d8f5e Mon Sep 17 00:00:00 2001
From: your friendly localhost admin <raingloom@riseup.net>
Date: Thu, 3 Sep 2020 19:43:44 +0200
Subject: [PATCH 11/11] doc: document Yggdrasil service
* doc/guix.texi
(yggdrasil-service-type, yggdrasil-configuration): Newly documented.
---
doc/guix.texi | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
@@ -80,6 +80,7 @@ Copyright @copyright{} 2020 Brice Waegeneire@*
Copyright @copyright{} 2020 R Veera Kumar@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
+Copyright @copyright{} 2020 raingloom@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -15324,6 +15325,59 @@ Use this to add additional options and manage shared secrets out-of-band.
@end table
@end deftp
+@defvr {Scheme Variable} yggdrasil-service-type
+The service type for connecting to the @uref{https://yggdrasil-network.github.io/, Yggdrasil network}, an early-stage implementation of a fully end-to-end encrypted IPv6 network.
+Pass it a value of @code{yggdrasil-configuration} to connect it to public peers and/or local peers.
+
+Here is an example using public peers and private configuration from @file{/etc/yggdrasil-private.conf} (the default value for @code{config-file}).
+See below for which options should go to @code{json-config} and which to @code{config-file}.
+
+@lisp
+(service yggdrasil-service-type
+ (yggdrasil-configuration
+ (autoconf? #f)
+ (json-config
+ ;; choose one from https://github.com/yggdrasil-network/public-peers
+ '((peers . #("tcp://1.2.3.4:1337"))))))
+@end lisp
+@end defvr
+
+@deftp {Data Type} yggdrasil-configuration
+Data type representing the configuration of Yggdrasil. Note that these settings are stored in the Guix store, which is readable to all users.
+
+@table @asis
+@item @code{package} (default: @code{yggdrasil})
+Package object of Yggdrasil.
+
+@item @code{json-config} (default: @code{'()})
+Contents of @file{/etc/yggdrasil.conf}. Will be merged with @file{/etc/yggdrasil-private.conf}.
+Do not store sensitive data (like private keys) in this.
+See the output of @code{yggdrasil -genconf} for a quick overview of valid keys and their default values.
+
+@item @code{autoconf?} (default: @code{#f})
+Whether to automatically configure an address and join through local peers.
+
+@item @code{log-level} (default: @code{'info})
+How much detail to include in logs. Use @code{'debug} for more detail.
+
+@item @code{log-to} (default: @code{'stdout})
+Where to send logs. By default, the service logs standard output to @file{/var/log/yggdrasil.log}.
+The alternative is @code{'syslog}.
+
+@item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"})
+What HJSON file to load sensitive data from. This is where private keys should be stored, which are necessary to specify if you don't want a randomized address after each restart.
+Use @code{"/dev/null"} if you don't need it.
+Options defined in this file take precedence over @code{json-config}.
+Use the output of @code{yggdrasil -genconf} as a starting point. You most likely only need these keys:
+@itemize
+@item @code{EncryptionPublicKey}
+@item @code{EncryptionPrivateKey}
+@item @code{SigningPublicKey}
+@item @code{SigningPrivateKey}
+@end itemize
+@end table
+@end deftp
+
@node Unattended Upgrades
@subsection Unattended Upgrades
--
2.28.0