From 5e8ae5156c72593eb24dd125db32e860f59be820 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ra=C3=BAl=20Benencia?= <rul@kalgan.cc>
Date: Tue, 8 Jan 2019 21:00:42 -0800
Subject: Add scdoc manpage

---
 .gitignore           |   3 ++
 Makefile             |  11 ++++-
 docs/shoelaces.8.scd | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 docs/shoelaces.8.scd

diff --git a/.gitignore b/.gitignore
index 74046b8..be201f7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,6 @@ _testmain.go
 shoelaces
 config.yaml
 *.deb
+
+# auto-generated manpage
+docs/shoelaces.8
diff --git a/Makefile b/Makefile
index 7ce9d40..a831cb3 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,6 @@
 GO = go
+SCDOC = scdoc
+
 pkgs = $(shell $(GO) list ./... | grep -v /vendor/)
 
 all:
@@ -8,8 +10,15 @@ fmt:
 	$(GO) fmt
 
 clean:
-	rm -f shoelaces
+	rm -f shoelaces docs/shoelaces.8
+
+shoelaces.8:
+	$(SCDOC) < docs/shoelaces.8.scd > docs/shoelaces.8
+
+docs: shoelaces.8
 
 test: fmt
 		$(GO) test -v $(pkgs) && \
 			./test/integ-test/integ_test.py
+
+.PHONY: all clean docs
diff --git a/docs/shoelaces.8.scd b/docs/shoelaces.8.scd
new file mode 100644
index 0000000..ec38101
--- /dev/null
+++ b/docs/shoelaces.8.scd
@@ -0,0 +1,120 @@
+shoelaces(8)
+
+# NAME
+
+shoelaces - automated server bootstrapping
+
+# SYNOPSIS
+
+*shoelaces* [options...]
+
+# OPTIONS
+
+*-config* <config>
+	Specifies a config file. All the following options can be specified in
+	the config.
+
+*-data-dir* <directory>
+	Specifies a directory with mappings, configs, templates, etc.
+
+*-debug*
+	Enables debug mode.
+
+*-domain* <hostname>
+	Specifies the address where the server is going to listen.
+	Defaults to "localhost".
+
+*-env-dir* <directory>
+	Specifies a directory with environment overrides. Refer to the README of
+	the project for more information about environment overrides.
+
+*-mappings-file* <file>
+	Specifies a mappings YAML file. Defaults to "mappings.yaml". Refer to the
+	README of the project for more information about mappings.
+
+*-port* <port>
+	Specifies the port where the server is going to listen.
+	Defaults to 8080.
+
+*-static-dir* <directory>
+	Specifies a custom web directory with static files. Defaults to "web".
+
+*-template-extension* <extension>
+	Shoelaces template extension. Defaults to ".slc".
+
+# DESCRIPTION
+
+Shoelaces serves over HTTP iPXE boot scripts, cloud-init configuration, and
+any other configuration files to baremetal or virtual machines booting
+using iPXE. It also does a few other things to make easier managing server
+deployments:
+
+- Has a simple but nice UI to show the current configuration, and history
+  of servers that booted.
+- Uses Go templates to handle complex configurations.
+- Allows specifying the boot entry point for a given server based on its IP
+  address or DNS PTR record.
+- Supports the notion of environments for Development and Production
+  environment configurations, while trying to minimize template
+  duplication.
+- Puts unknown servers into iPXE script boot retry loop, while at the same
+  time showing them in the UI allowing the user to select a specific boot
+  configuration.
+
+Shoelaces is better when used along a DHCP server. Refer to the
+*CONFIGURATION* section for examples on how to configure a DHCP server for
+hooking it with Shoelaces.
+
+# CONFIGURATION
+
+Shoelaces searches for a config file whenever the *-config* flag is
+specified.
+
+Here is example config file:
+
+```
+port=8081
+domain=localhost
+data-dir=/etc/shoelaces/data-dir/
+template-extension=.slc
+mappings-file=mappings.yaml
+debug=true
+```
+
+*dhcpd*(8) can be hooked with Shoelaces by adding the following snippet in
+*dhcpd.conf*(5):
+
+```
+# dhcp.conf
+next-server <your-tftp-server>;
+if exists user-class and option user-class = "iPXE" {
+  filename "http://<shoelaces-server>/poll/1/${netX/mac:hexhyp}";
+} else {
+  filename "undionly.kpxe";
+}
+```
+
+Similarly, *dnsmasq*(8) can be configured for working with Shoelaces with
+the following snippet:
+
+```
+dhcp-match=set:ipxe,175 # iPXE sends a 175 option.
+dhcp-boot=tag:!ipxe,undionly.kpxe
+dhcp-boot=http://<shoelaces-server>/poll/1/${netX/mac:hexhyp}
+```
+
+A TFTP server such as *tftpd*(8) must be configured to serve the IPXE ROM,
+*undionly.kpxe*.
+
+# SEE ALSO
+
+*dhcpd*(8) *dhcpd.conf*(5) *dnsmasq*(8) *tftpd*(8)
+
+# AUTHORS
+
+Maintained by ThousandEyes Inc. <opensource@thousandeyes.com>.
+
+Up-to-date sources can be found at https://github.com/thousandeyes/shoelaces.
+
+Bugs reports and patches can be submitted via GitHub's interface or
+contacting the maintainers directly via email.
-- 
cgit v1.2.3