.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "shoelaces" "8" "2024-01-07"
.P
.SH NAME
.P
shoelaces - automated server bootstrapping
.P
.SH SYNOPSIS
.P
\fBshoelaces\fR [options.\&.\&.\&]
.P
.SH OPTIONS
.P
\fB-base-url\fR <string>
.RS 4
Optional parameter.\& Specifies the base address that will be used when
generating URLs.\&
If it'\&s not specified, the value of "-bind-addr" will be used.\&
.P
.RE
\fB-bind-addr\fR <host:port>
.RS 4
The address where Shoelaces will listen for requests.\& Defaults to
"localhost:8081".\&
.P
.RE
\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-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-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
bind-addr=localhost:8081
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>/start";
} 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>/start
.fi
.RE
.P
A TFTP server such as \fBtftpd\fR(8) must be configured to serve the iPXE executable,
\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.\&