.\" Generated by scdoc 1.9.4
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "shoelaces" "8" "2019-07-27"
.P
.SH NAME
.P
shoelaces - automated server bootstrapping
.P
.SH SYNOPSIS
.P
\fBshoelaces\fR [options...]
.P
.SH OPTIONS
.P
\fB-config\fR <config>
.RS 4
Specifies a config file. All the following options can be specified in
the config.
.P
.RE
\fB-data-dir\fR <directory>
.RS 4
Specifies a directory with mappings, configs, templates, etc.
.P
.RE
\fB-debug\fR
.RS 4
Enables debug mode.
.P
.RE
\fB-domain\fR <hostname>
.RS 4
Specifies the address where the server is going to listen.
Defaults to "localhost".
.P
.RE
\fB-env-dir\fR <directory>
.RS 4
Specifies a directory with environment overrides. Refer to the README of
the project for more information about environment overrides.
.P
.RE
\fB-mappings-file\fR <file>
.RS 4
Specifies a mappings YAML file. Defaults to "mappings.yaml". Refer to the
README of the project for more information about mappings.
.P
.RE
\fB-port\fR <port>
.RS 4
Specifies the port where the server is going to listen.
Defaults to 8080.
.P
.RE
\fB-static-dir\fR <directory>
.RS 4
Specifies a custom web directory with static files. Defaults to "web".
.P
.RE
\fB-template-extension\fR <extension>
.RS 4
Shoelaces template extension. Defaults to ".slc".
.P
.RE
.SH DESCRIPTION
.P
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:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
Has a simple but nice UI to show the current configuration, and history
of servers that booted.
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
Uses Go templates to handle complex configurations.
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
Allows specifying the boot entry point for a given server based on its IP
address or DNS PTR record.
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
Supports the notion of environments for Development and Production
environment configurations, while trying to minimize template
duplication.
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
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.

.RE
.P
Shoelaces is better when used along a DHCP server. Refer to the
\fBCONFIGURATION\fR section for examples on how to configure a DHCP server for
hooking it with Shoelaces.
.P
.SH CONFIGURATION
.P
Shoelaces searches for a config file whenever the \fB-config\fR flag is
specified.
.P
Here is example config file:
.P
.nf
.RS 4
port=8081
domain=localhost
data-dir=/etc/shoelaces/data-dir/
template-extension=\&.slc
mappings-file=mappings\&.yaml
debug=true
.fi
.RE
.P
\fBdhcpd\fR(8) can be hooked with Shoelaces by adding the following snippet in
\fBdhcpd.conf\fR(5):
.P
.nf
.RS 4
# 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";
}
.fi
.RE
.P
Similarly, \fBdnsmasq\fR(8) can be configured for working with Shoelaces with
the following snippet:
.P
.nf
.RS 4
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}
.fi
.RE
.P
A TFTP server such as \fBtftpd\fR(8) must be configured to serve the IPXE ROM,
\fBundionly.kpxe\fR.
.P
.SH SEE ALSO
.P
\fBdhcpd\fR(8) \fBdhcpd.conf\fR(5) \fBdnsmasq\fR(8) \fBtftpd\fR(8)
.P
.SH AUTHORS
.P
Maintained by ThousandEyes Inc. <opensource@thousandeyes.com>.
.P
Up-to-date sources can be found at https://github.com/thousandeyes/shoelaces.
.P
Bugs reports and patches can be submitted via GitHub's interface or
contacting the maintainers directly via email.