From b088c37a65a03c31223e64a5fcd47fb458244979 Mon Sep 17 00:00:00 2001
From: Howard Holm <hdholm@alumni.iastate.edu>
Date: Tue, 14 Dec 2021 05:10:49 -0500
Subject: [PATCH] Man page updates (#80)

* Add a simple man page for tangd-rotate-keys and adjust man page building
to allow for some differentiation between different systems - primarily
for the tang man page.
---
 doc/meson.build              |  1 +
 doc/tang.8.adoc              | 20 +++++++++++++++-
 doc/tangd-rotate-keys.1.adoc | 46 ++++++++++++++++++++++++++++++++++++
 meson.build                  |  2 +-
 4 files changed, 67 insertions(+), 2 deletions(-)
 create mode 100644 doc/tangd-rotate-keys.1.adoc

diff --git a/doc/meson.build b/doc/meson.build
index e60b40d..daa6701 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,4 +1,5 @@
 mans += join_paths(meson.current_source_dir(), 'tang-show-keys.1')
+mans += join_paths(meson.current_source_dir(), 'tangd-rotate-keys.1')
 mans += join_paths(meson.current_source_dir(), 'tang.8')
 
 # vim:set ts=2 sw=2 et:
diff --git a/doc/tang.8.adoc b/doc/tang.8.adoc
index baac223..3031a13 100644
--- a/doc/tang.8.adoc
+++ b/doc/tang.8.adoc
@@ -40,7 +40,13 @@ protocol, see the Tang project's homepage.
 
 Getting a Tang server up and running is simple:
 
+ifdef::freebsd[]
+    $ sudo service tangd enable
+    $ sudo service tangd start
+endif::[]
+ifndef::freebsd[]
     $ sudo systemctl enable tangd.socket --now
+endif::[]
 
 That's it. The server is now running with a fresh set of cryptographic keys
 and will automatically start on the next reboot.
@@ -49,8 +55,13 @@ and will automatically start on the next reboot.
 
 Tang intends to be a minimal network service and therefore does not have any
 configuration. To adjust the network settings, you can override the
+ifdef::freebsd[]
+variables in the */usr/local/etc/rc.d/tangd* file.
+endif::[]
+ifndef::freebsd[]
 *tangd.socket* unit file using the standard systemd mechanisms. See
 link:systemd.unit.5.adoc[*systemd.unit*(5)] and link:systemd.socket.5.adoc[*systemd.socket*(5)] for more information.
+endif::[]
 
 == KEY ROTATION
 
@@ -59,6 +70,10 @@ periodically rotate your keys. The precise interval at which you should rotate
 depends upon your application, key sizes and institutional policy. For some
 common recommendations, see: https://www.keylength.com.
 
+There is a convenience script to deal with this. See
+link:tangd-rotate-keys.1.adoc[*tangd-rotate-keys*(1)] for more information.
+This can also be performed manually as described below.
+
 To rotate keys, first we need to generate new keys in the key database
 directory. This is typically */var/db/tang*. For example, you can create
 new signature and exchange keys with the following commands:
@@ -130,10 +145,13 @@ Nathaniel McCallum <npmccallum@redhat.com>
 
 == SEE ALSO
 
+ifndef::freebsd[]
 link:systemd.unit.5.adoc[*systemd.unit*(5)],
 link:systemd.socket.5.adoc[*systemd.socket*(5)],
+endif::[]
 link:jose-jwk-gen.1.adoc[*jose-jwk-gen*(1)],
-link:tang-show-keys.1.adoc[*tang-show-keys*(1)]
+link:tang-show-keys.1.adoc[*tang-show-keys*(1)],
+link:tangd-rotate-keys.1.adoc[*tangd-rotate-keys*(1)]
 
 == FURTHER READING
 
diff --git a/doc/tangd-rotate-keys.1.adoc b/doc/tangd-rotate-keys.1.adoc
new file mode 100644
index 0000000..f91f933
--- /dev/null
+++ b/doc/tangd-rotate-keys.1.adoc
@@ -0,0 +1,46 @@
+tangd-rotate-keys(1)
+====================
+:doctype: manpage
+
+== NAME
+
+tangd-rotate-keys - Perform rotation of tang keys
+
+== SYNOPSIS
+
+*tangd-rotate-keys* [-h] [-v] -d <KEYDIR>
+
+== DESCRIPTION
+
+in order to preserve the security of the system over the long run, you need to periodically
+rotate your keys. The precise interval at which you should rotate depends upon your application,
+key sizes and institutional policy. For some common recommendations, see: https://www.keylength.com.
+
+*tangd-rotate-keys* generates new keys in the key database directory given by the *-d* option.
+This is typically */var/db/tang*. It also rename the old keys to have a leading . in order to
+hide them from advertisement.
+
+Tang will immediately pick up all changes. No restart is required.
+
+At this point, new client bindings will pick up the new keys and old clients can continue to
+utilize the old keys. Once you are sure that all the old clients have been migrated to use the
+new keys, you can remove the old keys. Be aware that removing the old keys while clients are
+still using them can result in data loss. You have been warned.
+
+== OPTIONS
+*  *-d* <KEYDIR>:
+  The directory with the keys, e.g. /var/db/tang
+
+* *-h*:
+  Display the usage information
+
+* *-v*:
+  Verbose. Display additional info on keys created/rotated
+
+== AUTHOR
+
+Sergio Correia <scorreia@redhat.com>
+
+== SEE ALSO
+
+link:tang.8.adoc[*tang*(8)]
diff --git a/meson.build b/meson.build
index 7664e05..97b7304 100644
--- a/meson.build
+++ b/meson.build
@@ -77,7 +77,7 @@ install_data(licenses, install_dir: licensedir)
 if a2x.found()
   foreach m : mans
     custom_target(m.split('/')[-1], input: m + '.adoc', output: m.split('/')[-1],
-      command: [a2x, '-f', 'manpage', '-D', meson.current_build_dir(), '@INPUT@'],
+      command: [a2x, '--attribute=' + build_machine.system(), '-f', 'manpage', '-D', meson.current_build_dir(), '@INPUT@'],
       install_dir: join_paths(get_option('mandir'), 'man' + m.split('.')[-1]),
       install: true
     )