man/mdt.1

.TH MDT "1" "December 2018" "MDT" "User Commands"
.SH NAME
mdt \- manipulate Mendel Linux devices
.SH SYNOPSIS
.B mdt
[\fI\,SUBCOMMAND\/\fR] [\fI\,ARGS\/\fR]...
.SH DESCRIPTION
.PP
MDT is a simple tool to aid in working with single board computers that the
Mendel Linux distribution runs on. It consists of a whole bunch of pre-existing
open source tooling, coupled with some simple wrappers written in python to ease
their use.
.PP
It also provides an easy way to interact with these boards without having to
fight with serial consoles, IP addresses, and other fiddly bits, reducing
barrier to entry when working with these boards.
.PP
With minimal effort, MDT should also be portable to existing systems such as
Debian and Ubuntu, if needed. This, however, is out of the scope of this
project.
.PP
MDT primarily uses the SSH protocol for most of its operations, and heavily
relies on key-based authentication to the device.
.SH TYPICAL WORKFLOW
.PP
Running the \fBmdt\fR command will automatically print out a summary of useful
subcommands to run. The typical workflow with mdt is the following:
.PP
Run \fBmdt devices\fR to see what devices are available on your local network
segment.
.PP
Run \fBmdt set preferred-device \fR\fIDEVICE-NAME-OR-IP-ADDRESS\fR to set the
name or IP address of the device you would like to connect to.
.PP
Run \fBmdt shell\fR to open an interactive terminal to the device. This will
automatically generate a key (if you didn't have one already), push the key to
the board, and then open an interactive shell via SSH.
.PP
Run \fBmdt pull\fR or \fBmdt push\fR to push and pull files to and from the
device.
.PP
Run \fBmdt install\fR to install a locally-built Debian package to the board,
without having to manually push and run dpkg.
.SH NETWORKING
.PP
MDT uses SSH to handle most commands in the backend, and requires SSH keys for
authentication to the device. Keys are stored in the \fB~/.config/mdt/keys\fR
directory, and are readily usable by standard SSH tooling, if required. The
remote device is expected to advertise the _googlemdt._tcp service over mDNS
and run both SSH and \fBmdt-keymaster\fR.
.SH INITIAL SETUP
.PP
MDT expects the remote device to be free of any initial SSH keys and running the
\fBmdt-keymaster\fR service on port 41337. This service is a simple HTTP server
that expects a single PUT command to be sent containing a line that can be added
to the default user's authorized_keys file.
.PP
During first contact the MDT client will generate an SSH key if none are on
disk. Once it has one, it will attempt to connect via SSH to the remote device
using this key only. If this fails, it will then attempt to push the key's
public part via the \fBmdt-keymaster\fR service as described above.
.PP
Once this file has been written to, \fBmdt-keymaster\fR will stop running from
that point forward, and key authentication should perform normally. It is
expected that the remote SSH service will be running in key authentication mode
only.
.PP
To reset the board's authentication keys, run \fBmdt resetkeys\fR. This will
remove all MDT keys from the device's authorized_keys file and restart
\fBmdt-keymaster\fB, making it ready to receive new keys again.
.SH SUBCOMMANDS
.PP
MDT recognizes the following subcommands:
.PP
.TP
\fBhelp\fR
gets detailed help on any other subcommand
.TP
\fBclear\fR
clears (unsets) an MDT variable on disk
.TP
\fBdevices\fR
prints a list of discovered devices on the local network segment
.TP
\fBexec\fR
runs a shell command on a connected device
.TP
\fBgenkey\fR
generates an SSH key to use for authenticating to a device
.TP
\fBget\fR
prints the value of an MDT variable on disk
.TP
\fBinstall\fR
installs a Debian package (.deb) to a connected device
.TP
\fBpull\fR
pulls (copies, downloads) a single or set of files from a connected device
.TP
\fBpush\fR
pushes (copies, uploads) a single or set of files to a connected device
.TP
\fBreboot\fR
reboots a connected device
.TP
\fBreboot-bootloader\fR
reboots a connected device into the fastboot bootloader
.TP
\fBresetkeys\fR
removes all MDT keys from a device and restarts \fBmdt-keymaster\fR so that keys
may be pushed again
.TP
\fBset\fR
sets an MDT variable on disk
.TP
\fBsetkey\fR
imports an OpenSSH \fBprivate\fR key in PEM format into MDT's keys directory
.TP
\fBshell\fR
opens an SSH shell connection to a connected device
.TP
\fBwait-for-device\fR
waits for a device to be discovered on the local network segment
.TP
\fBversion\fR
prints which version of MDT this is
.SH FILES
.PP
MDT stores files in the user's home directory under the standard
\fB.config/mdt\fR heirarchy. Two subdirectories are used in here, called
\fBattribs\fR and \fBkeys\fR.
.PP
\fBattribs\fR contains any single-line files used to store MDT variables.
.PP
\fBkeys\fR contains the SSH keys generated by MDT and are used for SSH
authentication.
.SH KNOWN ISSUES
.PP
None.
.SH AUTHOR
Written by June Tate-Gans.
.SH "REPORTING BUGS"
Contact Coral support at <coral-support@google.com>
.SH COPYRIGHT
Copyright \(co 2018 Google, Inc.
License Apache 2.0.