documentation: Add in a fully qualified man page.
Change-Id: Ief34784a7e873b08111b1f18b7e7c21ac2e24477
diff --git a/man/mdt.1 b/man/mdt.1
index 423d5ad..7044f56 100644
--- a/man/mdt.1
+++ b/man/mdt.1
@@ -3,7 +3,7 @@
mdt \- manipulate Mendel Linux devices
.SH SYNOPSIS
.B mdt
-[\fI\,OPTIONS\/\fR]... [[\fI\,SUBCOMMAND\/\fR] [\fI\,ARGS\/\fR]...]
+[\fI\,SUBCOMMAND\/\fR] [\fI\,ARGS\/\fR]...
.SH DESCRIPTION
.PP
MDT is a simple tool to aid in working with single board computers that the
@@ -18,6 +18,86 @@
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.
+.SH NETWORKING
+.PP
+MDT uses SSH to handle most commands in the backend, and requires SSH keys for
+authentication to the device. The remote device is expected to advertise the
+_google_mdt._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.
+.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
+\fBset\fR
+sets an MDT variable on disk
+.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
+.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"
