bootstrap has the following properties:
Yes, you can now flash an SDCard at the command line from Windows. 🎉
Bootstrapping a micro computer can be tedious. This repository contains a toolbox to enable the complete automation of the deployment of micro computers while making them low maintenance and as secure as reasonably possible.
There is intentionally no graphical application (GUI) and everything is done at the command line (CLI). There are already excellent GUI based flashing tools. This toolbox is for people wanting a complete self-contained lightweight CLI solution enabling large scale flashing of headless workers.
This toolbox was written to help manage the gohci workers, so they can be reflashed easily in case of tampering. That said, the tools are intentionally generic and reusable.
Prerequisite: you need to have Go installed on your local machine. Then install with:
go get -u -v periph.io/x/bootstrap/cmd/...
bootstrap doesn't use
efe flashes a modified Operating System (e.g. linux) on a SDCard that will
self-configure upon initial boot.
setup.shand other data, like
authorized_keysfor passwordless ssh and settings like the Wifi credentials, country, time zone, etc.
It does so without requiring any third party software or requiring any UI application. It is completely self-contained.
This example downloads the latest Raspbian Stretch Lite image and flashes it to an SDCard connected to the workstation. It setups the wifi and sends an email to you when it is done.
Note that once the device is booted up, the setup takes several minutes, the
hostname will be changed to
raspberrypi-XXXX (or the relevant board name) and
the email sent to you might be landing in your spam folder. The email contains
the device's IP address on the LAN.
efe -manufacturer raspberrypi --wifi-ssid <ssid> --wifi-pass <pwd> -email <[email protected]>
efe takes care of all the steps on the micro computer's initial boot via
-manufacturer is required, everything else is optional. For example if
-wifi-ssid is not provided, Wifi is not configured. Similarly if
efe -help to
see all the options.
If your workstation has more than one removable disk, it will not select one
automatically and will ask you to specify one. You have to specify it with
/dev/diskX. You can identify the disk of your SDCard by running:
diskutil list. It will look like
On a Raspberry Pi 3, the console UART is not enabled by default anymore. Specify
-forceuart to enable it, then use a serial cable (like FT232RL) to connect the serial pins to pins 8 and
10 on the header. Then run
screen /dev/ttyUSB0 115200 on your linux host to
connect (or equivalent on other OSes).
Fetches the library periph.io, then pushes all its tools to
an host named
raspberrypi all at once:
go get -u -v -d periph.io/x/cmd push -host [email protected] periph.io/x/cmd/...
Push two specific executables in the subdirectory of the current one:
push -host [email protected] ./gpio-read ./gpio-write
Use a special GOARCH instead of the default (
arm), for example when targeting
a ARM64 host:
push -host [email protected] -goarch arm64 periph.io/x/cmd/...
push depends on being able to ssh to the remote host, in addition to the Go
toolchain. Try running with
First, make sure that
ssh is enabled on your remote host. On Raspbian, this
requires a specific setup.
Second, you'll need to have one of rsync/scp/pscp in your
PATH. This is the
case by default on OSX and Ubuntu, but not on Windows.
For Windows, visit www.chiark.greenend.org.uk/~sgtatham/putty/latest.html and download the
MSI installer, e.g.
putty-64bit-0.70-installer.msi. Install it. Find
in your start menu and start it. Try to connect to your Raspberry Pi.
If the tool prompts for a password at every execution, you'll want to create a
ssh key with the tool
ssh-keygen, copy your
id_*.pub to your remote host as
~/.ssh/authorized_keys and finally make sure you have a
ssh-agent running on
your host. You can do
ssh-add to save the key password in memory.
On Windows, use
PuTTYgen (instead of
ssh-keygen) to create the ssh key. Save
it on your disk (password is recommended but not required) and copy paste the
string starting with
ssh-rsa to your Raspberry Pi into a new file named
.ssh/authorized_keys, you'll need to create the directory
.ssh first. Start
pageant, right click on the icon in the system tray, and select
setup.sh initializes a linux host by installing default tools (Go, git, ssh,
vim), optionally enables Wifi (set country, timezone, wifi ssid and password),
locks it down (disables ssh password authentication, enable ssh keys) and makes
it self-maintainable (automatic apt upgrade, enables sending emails).
It is a modular tool so it is possible to use all the setup steps (the default) or execute only one configuration step. It intentionally depends on as little tools to be as portable as possible.
setup.sh is automatically used by efe to do the on-device
configuration but it can also be used on a working device, for example on a
Beaglebone or a C.H.I.P. which have integrated non-removable flash.
You can use the copy included in the repository, or for your convenience use the latest copy at raw.githubusercontent.com/periph/bootstrap/master/setup.sh or the short URL https://goo.gl/JcTSsH.
For any non-trivial use, it is recommended to make a copy since the tool can be changed at any moment and is not yet fully stable. The following examples use the short URL but you can replace with your own copy, for example it can be served on the LAN via serve-dir.
To get the full list of steps and options available, download the script
first then run with
curl -sSL https://goo.gl/JcTSsH -o setup.sh bash setup.sh --help
It is also safe to run on your host.
If you already have a running device and want to run the full setup on it, use the following. That is generally what you want.
curl -sSL https://goo.gl/JcTSsH | bash -s -- --wifi-ssid <ssid> --wifi-pass <pwd> --email <[email protected]>
To get the full list of the operations done by default, run
setup.sh in dry
run mode on the device itself. It will not do any modification on the machine.
curl -sSL https://goo.gl/JcTSsH | bash -s -- --dry-run
Installs and/or updates in-place your Go toolchain on any computer. This is super useful to mass upgrade Go on all your workers. It selects the latest version from https://golang.org/dl/.
curl -sSL https://goo.gl/JcTSsH | bash -s -- do_golang
If you want to compile the toolchain instead, which is useful if you want to work on the Go toolchain or use a beta, use instead:
curl -sSL https://goo.gl/JcTSsH | bash -s -- do_golang_compile
Keep in mind that for devices with less than 8Gb of flash, it may not have enough space for this.
ARM64 devices running a 64 bit version of the OS will automatically compile locally since there is no official ARM64 release of Go at the time of this writing.
Renames the host to
<board> is one of
<id> is calculated from either the CPU
serial number or systemd's hostctl 'Machine ID'. It is very useful because the
number is deterministic, so the hostname won't change as you reflash your device
while testing and it has enough entropy that the risk of collision on a LAN is
curl -sSL https://goo.gl/JcTSsH | bash -s -- do_rename_host
Forwards all emails sent to
[email protected] via sendmail to your email address.
This one is very useful for large scale fleet, as it also enables automatic
email upon unattended-upgrade.
This permits to know when something wrong happens on the worker.
curl -sSL https://goo.gl/JcTSsH | bash -s -- --email [email protected] do_sendmail
Here's the list of modications done by
setup.sh. As all documentation, it
could be a bit stale so confirm with the setup.sh source code.
do_beaglebone: For Beaglebone only:
do_chip: For C.H.I.P. only:
do_odroid: For ODROID only:
do_raspberrypi: For Raspbian only:
apt upgradeare run.
apt install curl ssh vimis run.
do_bash_history: Injects commands in
do_timezone: Sets up the timezone.
$HOME/.ssh/authorized_keysis copied from
/booton the device.
PATHsetup automatically upon login.
/etc/postfix/main.cfto send emails to aspmx.l.google.com over TLS.
[email protected]to redirect to the email address specified via
$BOARD-$SERIAL[:4]where the board is the detected board and the serial number is gathered from the CPU, failing that from systemctl.
do_update_motd: Updates MOTD to be short:
Welcome to $HOST.
do_swap: Sets up a swapfile as
/var/swap. Not yet run automatically.
Refer to the code for the exact list, and please send a PR for any bug fixes or improvements you think of.
bootstrap was initiated with ❤️️ and passion by Marc-Antoine